class

Wav

a simple WAV file reader, writer and basic audio processor.

usage

require "wav"

# Reading and writing
wav = Wav.read("input.wav")
wav.write("output.wav")

# Building from scratch
sine = Wav.build { |w| w.sine 440, 2.0 }
square = Wav.build { |w| w.square 220, 1.0, 0.8 }

# Mixing tracks
mix = sine.mix square

# Applying effects
mix.delay(0.3, feedback: 0.5)
   .chorus(depth: 0.003, lfo_rate: 2.0, mix: 0.3)
   .low_pass(2_000)
   .normalize(0.95)
   .fade_in(0.1)
   .fade_out(0.5)

# Generating noise and silence
Wav.build { |w| w.noise(2.0, 0.2).silence(0.5).saw 440, 1.0 }

# Trimming and resampling
wav.trim(1.0, 3.5).resample(22_050.0).to_mono

# Multi‑channel composition with cursor and channel targeting
track = Wav.build do |w|
  w.left.sine 440, 1.0              # left channel, first second
  w.at(1.0).right.square 880, 1.0   # right channel, second second
  w.all.forward                     # move to end
  w.triangle 220, 2.0, 0.5          # both channels
end
track.write "track.wav"

# Custom waveform generation
wav = Wav.build do |w|
  w.generate(2.0, 0.8) { |t| Math.cos 2 * Math::PI * 330 * t }
end

# Information
puts wav   # => #<Wav r=44100 ch=2 b=16 t=2.0s>

Constants

DATA = "data"

FMT = "fmt "

RIFF = "RIFF"

WAVE = "WAVE"

Constructors

build(rate = 44100.0, channels = 1, bits = 16, &) : Wav

creates a new Wav instance and yields it to the block for building.

accepts rate or samples per second (default: 44_100.0), channels number of channels (default: 1), bits bit depth, 8 or 16 (default: 16)

Source

new(rate : Float64 = 44100.0, channels : Int32 = 1, bits : Int32 = 16, samples : Array(Float64) = [] of Float64, cursor : Int32 = 0, target : Int32 | Nil = nil.as(Int32 | ::Nil))

create a new Wav instance

accepts rate or samples per second (default: 44_100.0), channels number of channels (default: 1), bits bit depth, 8 or 16 (default: 16), other exceptional options are: samples initial sample array (default: empty array of Float64), cursor internal cursor position (default: 0) and target optional channel target for generation (default: nil, meaning all channels)

raises exception if parameters are invalid.

Source

read(path : String) : Wav

reads a WAV file from the given path, raises exception on invalid WAV or non-existent file

Source

read(io : IO) : Wav

reads a WAV file from any io, IO must be at start and it must be valid WAV, raises otherwise

Source

Instance methods

all

resets the channel target to all channels

Source

at(time : Float64) : self

moves the internal cursor to the sample corresponding to time in seconds

Source

bits

Source

channel(target : Int32 | Nil = nil) : self

sets channel target to a specific index (0 based)

Source

channels

Source

chorus(depth = 0.002, lfo_rate = 1.5, mix = 0.5) : self

applies a chorus effect, depth is modulation depth in seconds (default 0.002), lfo_rate is modulation rate in Hz (default 1.5), mix is the wet/dry balance (0 = dry only, 1 = wet only, default 0.5).

Source

delay(time : Float64, feedback = 0.4) : self

adds an echo / delay effect. time is delay in seconds, feedback controls the decay of repeats (default 0.4)

Source

fade(duration : Float64, head = false, tail = false) : self

applies a linear fade of duration in seconds. if head is true, fades in at the start, if tail is true fades out at the end. defaults to fade in

Source

fade_in(duration : Float64) : self

shorthand for #fade with head fade

Source

fade_out(duration : Float64) : self

shorthand for #fade with tail fade

Source

forward(time : Float64 = 0.0) : self

moves the internal cursor forward by time in seconds, if time not set moves to the end

Source

generate(duration : Float64, amplitude = 1.0, &) : self

appends custom samples generated by block, given duration in seconds, scaled by amplitude, block receives time in seconds and should return a sample value between -1.0 and 1.0

Source

left

targets the left channel for generation when stereo, otherwise targets the only channel

Source

low_pass(cutoff : Float64) : self

applies a simple first-order low-pass filter with cutoff frequency in Hz

Source

mix(other : Wav) : self

mixes the samples of another Wav, other into the current one (additive), the two must have identical sample rates and channel counts otherwise raises exception

Source

noise(duration, amplitude = 1.0) : self

appends white noise for duration in seconds, scaled by amplitude

Source

normalize(target = 0.95) : self

scales the audio to the peak absolute amplitude of target, target should be between 0 and 1 (default: 0.95)

Source

rate

Source

resample(new_rate : Float64) : Wav

resamples the audio using linear interpolation with new_rate, returns a new Wav instance

Source