audio_waveform-ruby

The audio_waveform-ruby gem provides a Ruby API for access to audio waveform data files generated by the audiowaveform program.

Refer to the audiowaveform documentation for more information and this page for file format details.

Installation

To install:

$ gem install audio_waveform-ruby

or, if using bundler, add this line to your application's Gemfile:

gem 'audio_waveform-ruby', :require => 'audio_waveform'

or, to use the latest code from the GitHub repository:

gem 'audio_waveform-ruby', :require => 'audio_waveform',
    :git => 'https://codeberg.org/chrisn/audio_waveform-ruby.git'

and run

$ bundle install

Usage

To use this Gem in your program, add:

require 'audio_waveform'

Then, to load and use data from an existing waveform data file:

waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")

puts waveform.sample_rate       # Returns audio sample rate, in Hz
puts waveform.bits              # Returns resolution of waveform data points
puts waveform.samples_per_pixel # Returns waveform zoom level, in samples per pixel
puts waveform.size              # Returns number of waveform data points

(0...waveform.size).each do |i|
  puts waveform.min_sample(i)   # Returns waveform minimum at index i
  puts waveform.max_sample(i)   # Returns waveform maximum at index i
end

To generate a binary representation of a waveform data file:

waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
data = waveform.to_binary

To save waveform data as a file in binary format:

waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
waveform.save_as_binary("output.dat")

To generate a JSON representation of a waveform data file:

waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
waveform.to_json

To save waveform data as a file in JSON format:

waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
waveform.save_as_json("output.json")

To create a new waveform data file:

waveform = AudioWaveform::WaveformDataFile.new(
    sample_rate: 44100,
    samples_per_pixel: 512,
    bits: 8
)

waveform.append(-10, 10)
        .append(-11, 11)
        .append(-3, 3)
# etc

License

See COPYING for details.

Contributing

If you'd like to contribute to audio_waveform-ruby, please take a look at the contributor guidelines.

If you have a feature request or want to report a bug, we'd be happy to hear from you. Please either raise an issue, or fork the project and send us a pull request.

Authors

This software was written by Chris Needham.

Copyright

Copyright 2025 Chris Needham