WaveFile Tutorial

NOTE: This document covers the non-yet-released 0.4.0 version of the WaveFile gem. Also, I haven't actually run this code yet, so there may be mistakes.

Reading a Wave File (Auto File Close Edition)

The example below shows the preferred way of reading an entire wave file. First construct a Reader object, then call each_buffer() on it. Successive sample buffers will be read from the file and passed to the given block, until all sample data in the file has been read. Finally, the Reader will automatically be closed. (Note that this is essentially the same as how IO.open works if you pass it a block).

Note that when calling each_buffer() (and read()), the number you pass indicates the number of samples to read, not the number of bytes. So, if you call each_buffer(1024) on a stereo/16-bit file, then 1024 samples for the left channel will be read, and 1024 samples for the right channel will be read.

require 'wavefile'
include WaveFile 

Reader.new("my_file.wav").each_buffer(4096) do |buffer|
  puts "Read #{buffer.samples.length} samples."
end

Reading a Wave File (Manual Edition)

Alternately, you can manually call read() to control exactly how much of the file to read. When doing this, make sure to close the Reader when you're done.

require 'wavefile'
include WaveFile

reader = Reader.new("my_file.wav")
begin
  while true do
    buffer = reader.read(4096)
    puts "Read #{buffer.samples.length} samples."
  end
rescue EOFError
  reader.close()
end

Reading a Wave File Into a Different Format

It's easy to read sample data out of a file in whatever format you need, regardless of what format is used inside the file. For example, suppose that my_file.wav is stereo/16-bit, but you need mono/8-bit. No problem, as shown below.

require 'wavefile'
include WaveFile

# Assume my_file.wav is stereo and 16-bit
reader = Reader.new("my_file.wav", Format.new(:mono, 8, 44100)).each_buffer do |buffer|
  puts "Read #{buffer.samples.length} samples."
end

Getting Metadata About a Wave File

require 'wavefile'
include WaveFile

info = Reader.info("my_file.wav")
puts "Channels:         #{info.channels}"
puts "Bits per sample:  #{info.bits_per_sample}"
# Etc...

Writing a Wave File

require 'wavefile'
include WaveFile

format = Format.new(:mono, 16, 44100)
writer = Writer.new("my_file.wav", format)

# Write a 1 second long 440Hz square wave
cycle = ([10000] * 50) + ([-10000] * 50)
220.times do
  buffer = Buffer.new(cycle, format)
  writer.write(buffer)
end

writer.close()

Copying a Wave File to Different Format

In this example, the sample data in the file original.wav will be written to copy.wav as stereo/16-bit with a 44,100Hz sample rate, regardless of what format the sample data in original.wav is stored in.

require 'wavefile'
include WaveFile

Writer.new("copy.wav", Format.new(:stereo, 16, 44100) do |writer|
  Reader.new("original.wav").each_buffer(4096) do |buffer|
    writer.write(buffer)
  end
end

Appending Wave Files

require 'wavefile'
include WaveFile

files_to_append = ["file1.wav", "file2.wav", "file3.wav"]

Writer.new("append.wav", Format.new(:stereo, 16, 44100) do |writer|
  files_to_append.each do |file_name|
    Reader.new(file_name).each_buffer(4096) do |buffer|
      writer.write(buffer)
    end
  end
end