The WaveFile gem lets you read and write wave files.

Reading is done using the Reader class, and writing is done using the Writer class.

The Buffer class represents a collection of samples in a given sample format (e.g. stereo 16-bit PCM samples at a 44,100Hz sample rate). When samples are read using Reader they are returned in Buffer instances. Samples to be written are given to Writer wrapped in Buffer instances as well.

A Buffer consists of two parts: an array of samples, and a Format instance that describes the sample format (since it might not be possible to determine just by looking at the raw samples). For example, the sample array in a Buffer read out of a mono 8-bit PCM file (in which each sample is an integer between 0 and 255) might look like this:

    [45, 192, 13, 231, 201, 101, 15, ...etc...]

When there is more than one channel, each sample frame will be represent by a sub array. For example, a set of stereo floating point samples (in which each sample is between -1.0 and 1.0) might look like this:

    [[-0.2, 0.4], [0.3, 0.9], [-0.4, -0.8], [0.9, -0.2], [-0.3, 0.4], ...etc...]

When writing a program that creates sound, you would generate an array like this with the sample data, then wrap it in a Buffer, and then use Writer to write the samples in the Buffer to disk.

Buffers have the ability to convert their samples to any other format this gem supports. This means you can read samples from a file in whatever format you like, regardless of the actual sample format in the file (e.g. read a file with 8-bit samples and get 16-bit samples back). You can also do the same with Writer - for example, rather than remember the sample range of a PCM format (was it 32,767? or 32,768?) you can just generate floating point samples between -1.0 and 1.0, and transparently write them out as PCM samples.
