class WaveFile::Buffer

Creates a new Buffer.

samples

An array of samples. If the Format has 1 channel (i.e. is mono), this should be a flat array of samples such as [0.5, 0.4, -0.3, ...]. If the Format has 2 or more channels the array should include a sub-array for each sample frame. For example, [[0.5, 0.2], [0.1, 0.6], [-0.2, 0.4], ...] for a stereo file.

The individual samples should match the given format:

:pcm_8

Integer between 0 and 255

:pcm_16

Integer between -32_768 and 32_767

:pcm_24

Integer between -8_388_608 and 8_388_607

:pcm_32

Integer between 2_147_483_648 and 2_147_483_647

:float

Float between -1.0 and 1.0

:float_32

Float between -1.0 and 1.0

:float_64

Float between -1.0 and 1.0

format

A Format instance which describes the sample format of the sample array.

Note that the sample array is not compared with the format to make sure they match - you are on the honor system to make sure they do. If they don’t match, unexpected things will happen.

Examples¶ ↑

# One cycle of a floating point 441Hz mono square wave
samples = ([0.5] * 50) + ([-0.5] * 50)
buffer = Buffer.new(samples, Format.new(:mono, :float, 44100))

# One cycle of a floating point 441Hz stereo square wave
samples = ([0.5, 0.5] * 50) + ([-0.5, -0.5] * 50)
buffer = Buffer.new(samples, Format.new(2, :float, 44100))

# One cycle of a 16-bit PCM 441Hz mono square wave
samples = ([16000] * 50) + ([-16000] * 50)
buffer = Buffer.new(samples, Format.new(1, :pcm_16, 44100))

Returns¶ ↑

Returns a constructed Buffer.

# File lib/wavefile/buffer.rb, line 53
def initialize(samples, format)
  @samples = samples
  @format = format
end

Returns¶ ↑

Returns the bits per sample of the buffer’s sample data

# File lib/wavefile/buffer.rb, line 117
def bits_per_sample
  @format.bits_per_sample
end

Returns¶ ↑

Returns the number of channels the buffer’s sample data has

# File lib/wavefile/buffer.rb, line 111
def channels
  @format.channels
end

Creates a new Buffer containing the sample data of this Buffer, but converted to a different format.

new_format

The format that the sample data should be converted to. If the new format has a different number of channels than the original buffer format, the sample data will be converted in the following way:

1 -> n: Each mono sample will be duplicated into the new number of channels.

n -> 1: Each sample in each sample frame will be averaged into a single sample.

(n > 2) -> 2: The first two channels will be kept, all other channels discarded.

other: Unsupported, will cause BufferConversionError to be raised.

Examples¶ ↑

new_format = Format.new(:mono, :pcm_16, 44100)
new_buffer = old_buffer.convert(new_format)

Returns¶ ↑

Returns a new Buffer; the existing Buffer is unmodified.

Raises BufferConversionError if the Buffer can’t be converted to the given format

# File lib/wavefile/buffer.rb, line 82
def convert(new_format)
  new_samples = convert_buffer(@samples.dup, @format, new_format)
  Buffer.new(new_samples, new_format)
end

Converts the sample data contained in the Buffer to a new format. The sample data is converted in place, so the existing Buffer is modified.

new_format

The format that the sample data should be converted to. See Buffer#convert for how samples will be mapped if the new number of channels differs from the original number of channels.

Examples¶ ↑

new_format = Format.new(:mono, :pcm_16, 44100)
old_buffer.convert!(new_format)

Returns¶ ↑

Returns self.

Raises BufferConversionError if the Buffer can’t be converted to the given format

# File lib/wavefile/buffer.rb, line 103
def convert!(new_format)
  @samples = convert_buffer(@samples, @format, new_format)
  @format = new_format
  self
end

Returns¶ ↑

Returns the sample rate of the buffer’s sample data

# File lib/wavefile/buffer.rb, line 123
def sample_rate
  @format.sample_rate
end