Class: RubyDSP::AudioTrack

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_dsp.rb,
stubs/ruby_dsp/audio_track.rb

Overview

A high-performance audio track processor backed by miniaudio.

This class heavily utilizes a fluent API pattern. Most processing methods end in ! to indicate that they destructively mutate the audio data in C++ memory for maximum performance with zero Garbage Collection overhead. These methods return self to allow for clean method chaining.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file_name = '', target_channels = 0, target_sample_rate = 0, start_sec = 0.0, duration_sec = 0.0) ⇒ AudioTrack

Initializes a new AudioTrack.

Decodes the given file using miniaudio. If file_name is an empty string "", it initializes an empty, blank audio canvas for synthesis and sequencing.

Examples:

Load an entire audio file

track = RubyDSP::AudioTrack.new("vocals.wav")

Load a 10-second snippet starting at the 1-minute mark

snippet = RubyDSP::AudioTrack.new("podcast.mp3", 0, 0, 60.0, 10.0)

Initialize a blank mono canvas at 48kHz

canvas = RubyDSP::AudioTrack.new("", 1, 48000)

Parameters:

  • file_name (String) (defaults to: '') —

    Path to the audio file, or "" for a blank track.

  • target_channels (Integer) (defaults to: 0) —

    Optional. Force a specific number of channels (Defaults to 1 for blank tracks).

  • target_sample_rate (Integer) (defaults to: 0) —

    Optional. Force a specific sample rate (Defaults to 44100 for blank tracks).

  • start_sec (Float) (defaults to: 0.0) —

    Optional. The timestamp in seconds to start reading from. Defaults to 0.0.

  • duration_sec (Float) (defaults to: 0.0) —

    Optional. The length of audio to read in seconds. Defaults to 0.0 (reads to the end).

Raises:

  • (RuntimeError) —

    if a file is provided but cannot be processed or read.



49
50
 
# File 'stubs/ruby_dsp/audio_track.rb', line 49

def initialize(file_name = '', target_channels = 0, target_sample_rate = 0, start_sec = 0.0, duration_sec = 0.0)
end

Instance Attribute Details

#channels ⇒ Integer (readonly)

Returns the number of audio channels.

Returns:

  • (Integer) —

    the number of audio channels



15
16
17
 
# File 'stubs/ruby_dsp/audio_track.rb', line 15

def channels
  @channels
end

#file_name ⇒ String (readonly)

Returns the path to the loaded audio file.

Returns:

  • (String) —

    the path to the loaded audio file



12
13
14
 
# File 'stubs/ruby_dsp/audio_track.rb', line 12

def file_name
  @file_name
end

#is_mono? ⇒ Boolean (readonly)

Returns true if the track has exactly 1 channel.

Returns:

  • (Boolean) —

    true if the track has exactly 1 channel



21
22
23
 
# File 'stubs/ruby_dsp/audio_track.rb', line 21

def is_mono?
  @is_mono?
end

#sample_count ⇒ Integer (readonly)

Returns number of samples in samples.

Returns:

  • (Integer) —

    number of samples in samples



27
28
29
 
# File 'stubs/ruby_dsp/audio_track.rb', line 27

def sample_count
  @sample_count
end

#sample_rate ⇒ Integer (readonly)

Returns the sample rate of the track in Hz.

Returns:

  • (Integer) —

    the sample rate of the track in Hz



18
19
20
 
# File 'stubs/ruby_dsp/audio_track.rb', line 18

def sample_rate
  @sample_rate
end

#samples ⇒ Array<Float> (readonly)

Returns vector of samples from the audio file.

Returns:

  • (Array<Float>) —

    vector of samples from the audio file



24
25
26
 
# File 'stubs/ruby_dsp/audio_track.rb', line 24

def samples
  @samples
end

Instance Method Details

#add_wave!(wave_type, frequency, duration_sec, start_sec = -1.0,, amplitude = 1.0) ⇒ AudioTrack

Generates and mixes a mathematical waveform into the track.

Dynamically resizes the track if the wave extends past the current duration. If a wave overlaps with existing audio data, it is mixed (added) together, allowing for polyphony.

Examples:

Create a polyphonic C Major chord

track.add_wave!("sine", 261.63, 2.0)           # C4
     .add_wave!("sine", 329.63, 2.0, 0.0)      # E4 (starts at 0.0)
     .add_wave!("sine", 392.00, 2.0, 0.0)      # G4 (starts at 0.0)

Parameters:

  • wave_type (String) —

    The shape of the waveform ("sine", "square", "sawtooth", "noise").

  • frequency (Float) —

    The frequency of the wave in Hz (e.g., 440.0).

  • duration_sec (Float) —

    The length of the generated wave in seconds.

  • start_sec (Float) (defaults to: -1.0,) —

    The timestamp in seconds to start the wave. Defaults to -1.0 (appends to the end).

  • amplitude (Float) (defaults to: 1.0) —

    The peak amplitude of the wave. Defaults to 1.0.

Returns:



243
244
 
# File 'stubs/ruby_dsp/audio_track.rb', line 243

def add_wave!(wave_type, frequency, duration_sec, start_sec = -1.0, amplitude = 1.0)
end

#band_pass!(cutoff_freq) ⇒ AudioTrack

Applies a 2nd-order band-pass filter to the track.

Preserves frequencies around the cutoff, heavily attenuating both higher and lower frequencies.

Examples:

Create a "telephone" effect by isolating 1000Hz

track.band_pass!(1000)

Parameters:

  • cutoff_freq (Integer, Float) —

    The center frequency in Hz.

Returns:



287
288
 
# File 'stubs/ruby_dsp/audio_track.rb', line 287

def band_pass!(cutoff_freq)
end

#clip! ⇒ AudioTrack

Destructively clamps all audio samples to the standard [-1.0, 1.0] range.

This prevents harsh digital clipping when exporting polyphonic or boosted audio.

Returns:



251
252
 
# File 'stubs/ruby_dsp/audio_track.rb', line 251

def clip!
end

#dup ⇒ AudioTrack Also known as: clone

Creates a deep copy of the audio track in memory.

Since most processing methods mutate the track in-place for performance, use dup when you want to branch off a new version of the audio while preserving the original state.

Examples:

Non-destructive chaining

clean_vocals = track.dup.high_pass!(100).normalize!

Returns:

  • (AudioTrack) —

    A new, independent instance of the track.



62
63
 
# File 'stubs/ruby_dsp/audio_track.rb', line 62

def dup
end

#duration ⇒ Float

Calculates the total duration of the track.

Returns:

  • (Float) —

    duration in seconds.



93
94
 
# File 'stubs/ruby_dsp/audio_track.rb', line 93

def duration
end

#fade_in!(duration_sec) ⇒ AudioTrack

Applies a linear fade-in to the beginning of the audio track.

Examples:

Fade in over 1.5 seconds

track.fade_in!(1.5)

Parameters:

  • duration_sec (Float) —

    The length of the fade-in in seconds.

Returns:



192
193
 
# File 'stubs/ruby_dsp/audio_track.rb', line 192

def fade_in!(duration_sec)
end

#fade_out!(duration_sec) ⇒ AudioTrack

Applies a linear fade-out to the end of the audio track.

Examples:

Fade out over the last 2 seconds

track.fade_out!(2.0)

Parameters:

  • duration_sec (Float) —

    The length of the fade-out in seconds.

Returns:



202
203
 
# File 'stubs/ruby_dsp/audio_track.rb', line 202

def fade_out!(duration_sec)
end

#framed_rms(frame_length = 2048, hop_length = 512) ⇒ Array<Array<Float>>

Calculates the framed Root Mean Square (RMS) over time.

Parameters:

  • frame_length (Integer) (defaults to: 2048) —

    The number of samples per frame.

  • hop_length (Integer) (defaults to: 512) —

    The number of samples to advance each frame.

Returns:

  • (Array<Array<Float>>) —

    A 2D array of RMS values [channel][frame].



134
135
 
# File 'stubs/ruby_dsp/audio_track.rb', line 134

def framed_rms(frame_length = 2048, hop_length = 512)
end

#framed_zcr(frame_length = 2048, hop_length = 512) ⇒ Array<Array<Float>>

Calculates the framed Zero Crossing Rate (ZCR) over time.

Parameters:

  • frame_length (Integer) (defaults to: 2048) —

    The number of samples per frame.

  • hop_length (Integer) (defaults to: 512) —

    The number of samples to advance each frame.

Returns:

  • (Array<Array<Float>>) —

    A 2D array of ZCR values [channel][frame].



148
149
 
# File 'stubs/ruby_dsp/audio_track.rb', line 148

def framed_zcr(frame_length = 2048, hop_length = 512)
end

#high_pass!(cutoff_freq) ⇒ AudioTrack

Applies a 2nd-order high-pass filter to the track.

Attenuates frequencies below the cutoff, letting higher frequencies pass through.

Examples:

Cut out low-end rumble/wind noise below 80Hz

track.high_pass!(80)

Parameters:

  • cutoff_freq (Integer, Float) —

    The threshold frequency in Hz.

Returns:



275
276
 
# File 'stubs/ruby_dsp/audio_track.rb', line 275

def high_pass!(cutoff_freq)
end

#high_shelf!(cutoff_freq, gain_db, q = 0.707) ⇒ AudioTrack

Applies a 2nd-order high-shelf filter.

Boosts or cuts frequencies above the cutoff without affecting lower frequencies.

Examples:

Reduce harsh treble above 8kHz by 4dB

track.high_shelf!(8000, -4.0)

Parameters:

  • cutoff_freq (Integer, Float) —

    The threshold frequency in Hz.

  • gain_db (Float) —

    The amount to boost (positive) or cut (negative) in decibels.

  • q (Float) (defaults to: 0.707) —

    The resonance/slope of the shelf. Defaults to 0.707.

Returns:



338
339
 
# File 'stubs/ruby_dsp/audio_track.rb', line 338

def high_shelf!(cutoff_freq, gain_db, q = 0.707)
end

#low_pass!(cutoff_freq) ⇒ AudioTrack

Applies a high-order low-pass filter (Butterworth) to the track.

Attenuates frequencies above the cutoff, letting lower frequencies pass through.

Examples:

Cut out harsh high frequencies above 5kHz

track.low_pass!(5000)

Parameters:

  • cutoff_freq (Integer, Float) —

    The threshold frequency in Hz.

Returns:



263
264
 
# File 'stubs/ruby_dsp/audio_track.rb', line 263

def low_pass!(cutoff_freq)
end

#low_shelf!(cutoff_freq, gain_db, q = 0.707) ⇒ AudioTrack

Applies a 2nd-order low-shelf filter.

Boosts or cuts frequencies below the cutoff without affecting higher frequencies.

Examples:

Add a 3dB bass boost below 150Hz

track.low_shelf!(150, 3.0)

Parameters:

  • cutoff_freq (Integer, Float) —

    The threshold frequency in Hz.

  • gain_db (Float) —

    The amount to boost (positive) or cut (negative) in decibels.

  • q (Float) (defaults to: 0.707) —

    The resonance/slope of the shelf. Defaults to 0.707.

Returns:



324
325
 
# File 'stubs/ruby_dsp/audio_track.rb', line 324

def low_shelf!(cutoff_freq, gain_db, q = 0.707)
end

#normalize!(target_db = -10.0)) ⇒ AudioTrack

Normalizes the audio track to a specific peak decibel level.

Examples:

Normalize peak to -1.0 dBFS

track.normalize!(-1.0)

Parameters:

  • target_db (Float) (defaults to: -10.0)) —

    The target peak amplitude in dBFS. Defaults to -10.0.

Returns:



182
183
 
# File 'stubs/ruby_dsp/audio_track.rb', line 182

def normalize!(target_db = -10.0)
end

#notch!(center_freq, q = 0.707) ⇒ AudioTrack

Applies a 2nd-order notch filter to surgically remove a specific frequency.

Examples:

Eliminate 60Hz electrical hum

track.notch!(60)

Parameters:

  • center_freq (Integer, Float) —

    The exact frequency to eliminate in Hz.

  • q (Float) (defaults to: 0.707) —

    The resonance/width of the notch. Defaults to 0.707 (Butterworth).

Returns:



298
299
 
# File 'stubs/ruby_dsp/audio_track.rb', line 298

def notch!(center_freq, q = 0.707)
end

#pad!(head_sec = 0.0, tail_sec = 0.0) ⇒ AudioTrack

Pads the audio track with digital silence (0.0) at the beginning and/or end.

Examples:

Add 1 second of silence to the start, and 0.5 to the end

track.pad!(1.0, 0.5)

Parameters:

  • head_sec (Float) (defaults to: 0.0) —

    Seconds of silence to add to the beginning. Defaults to 0.0.

  • tail_sec (Float) (defaults to: 0.0) —

    Seconds of silence to add to the end. Defaults to 0.0.

Returns:



213
214
 
# File 'stubs/ruby_dsp/audio_track.rb', line 213

def pad!(head_sec = 0.0, tail_sec = 0.0)
end

#pad_to_duration!(target_duration_sec) ⇒ AudioTrack

Pads the audio track with digital silence so that it reaches an exact target duration. The padding is distributed evenly to both the head and the tail, effectively centering the audio.

Examples:

Center a 3-second sound effect into exactly a 5-second window

track.pad_to_duration!(5.0)

Parameters:

  • target_duration_sec (Float) —

    The desired total length of the track in seconds.

Returns:



224
225
 
# File 'stubs/ruby_dsp/audio_track.rb', line 224

def pad_to_duration!(target_duration_sec)
end

#peak_amp ⇒ Float

Finds the maximum absolute amplitude across all channels.

Returns:

  • (Float) —

    the peak amplitude.



99
100
 
# File 'stubs/ruby_dsp/audio_track.rb', line 99

def peak_amp
end

#peak_eq!(center_freq, gain_db, q = 0.707) ⇒ AudioTrack

Applies a 2nd-order peaking EQ filter to boost or cut a specific frequency band.

Examples:

Boost 3kHz by 2.5dB for vocal clarity

track.peak_eq!(3000, 2.5)

Parameters:

  • center_freq (Integer, Float) —

    The target frequency in Hz.

  • gain_db (Float) —

    The amount to boost (positive) or cut (negative) in decibels.

  • q (Float) (defaults to: 0.707) —

    The resonance/width of the bell curve. Defaults to 0.707.

Returns:



310
311
 
# File 'stubs/ruby_dsp/audio_track.rb', line 310

def peak_eq!(center_freq, gain_db, q = 0.707)
end

#resample!(target_rate = 0) ⇒ AudioTrack

Destructively resamples the track to the target rate using linear resampling.

Examples:

Resample to standard CD quality

track.resample!(44100)

Parameters:

  • target_rate (Integer) (defaults to: 0) —

    The new sample rate in Hz.

Returns:

Raises:

  • (RuntimeError) —

    if the resampler fails to initialize or process.



120
121
 
# File 'stubs/ruby_dsp/audio_track.rb', line 120

def resample!(target_rate = 0)
end

#rms ⇒ Array<Float>

Calculates the Root Mean Square (RMS) for the entire track, per channel.

Returns:

  • (Array<Float>) —

    An array containing the RMS value for each channel.



126
127
 
# File 'stubs/ruby_dsp/audio_track.rb', line 126

def rms
end

#save_track(out_file, format = :auto) ⇒ Boolean

Saves the audio track to disk.

The format can be inferred from the out_file extension, or explicitly forced via the format argument. If no extension or format is provided, it defaults to saving as a WAV file and will append the .wav extension automatically.

Note: Currently, only the WAV format (:wav) is supported for encoding.

Examples:

Save with inferred extension

track.save_track("output.wav")

Save without extension (auto-appends .wav)

track.save_track("my_beat")

Force format on an unknown extension

track.save_track("audio.data", :wav)

Parameters:

  • out_file (String) —

    The destination path and filename.

  • format (Symbol) (defaults to: :auto) —

    Optional. Forces a specific format (e.g., :wav). Defaults to :auto.

Returns:

  • (Boolean) —

    true if the file was successfully written.

Raises:

  • (RuntimeError) —

    if the track is empty, encoder fails, or an unsupported format is requested.



87
88
 
# File 'stubs/ruby_dsp/audio_track.rb', line 87

def save_track(out_file, format = :auto)
end

#silence_bounds(threshold_db = -60.0,, frame_length = 2048, hop_length = 512) ⇒ Array<Integer>

Finds the start and end sample indices of non-silent audio.

This scans the track's framed RMS energy and compares it against the global peak. Any frame that falls below the top_db threshold relative to the peak is considered silent.

Parameters:

  • threshold_db (Float) (defaults to: -60.0,) —

    The threshold in decibels below the peak RMS to consider as silence. Default is -60.0.

  • frame_length (Integer) (defaults to: 2048) —

    The number of samples per frame. Default is 2048.

  • hop_length (Integer) (defaults to: 512) —

    The number of samples to advance each frame. Default is 512.

Returns:

  • (Array<Integer>) —

    A 2-element array containing the [start_sample, end_sample] indices.



160
161
 
# File 'stubs/ruby_dsp/audio_track.rb', line 160

def silence_bounds(threshold_db = -60.0, frame_length = 2048, hop_length = 512)
end

#to_mono! ⇒ AudioTrack

Destructively converts the track to mono by averaging the channels.

Examples:

track.to_mono!

Returns:

Raises:

  • (RuntimeError) —

    if channel count is invalid.



109
110
 
# File 'stubs/ruby_dsp/audio_track.rb', line 109

def to_mono!
end

#to_s ⇒ String

Returns a formatted summary of the track.

Returns:

  • (String) —

    a formatted summary of the track.



342
343
 
# File 'stubs/ruby_dsp/audio_track.rb', line 342

def to_s
end

#trim_silence!(threshold_db = -60.0,, frame_length = 2048, hop_length = 512) ⇒ AudioTrack

Destructively trims leading and trailing silence from the track's internal sample array.

Examples:

Trim anything quieter than -50dB from the start and end

track.trim_silence!(-50.0)

Parameters:

  • threshold_db (Float) (defaults to: -60.0,) —

    The threshold in decibels below the peak RMS to consider as silence. Default is -60.0.

  • frame_length (Integer) (defaults to: 2048) —

    The number of samples per frame. Default is 2048.

  • hop_length (Integer) (defaults to: 512) —

    The number of samples to advance each frame. Default is 512.

Returns:



172
173
 
# File 'stubs/ruby_dsp/audio_track.rb', line 172

def trim_silence!(threshold_db = -60.0, frame_length = 2048, hop_length = 512)
end

#zcr ⇒ Array<Float>

Calculates the Zero Crossing Rate (ZCR) for the entire track, per channel.

Returns:

  • (Array<Float>) —

    An array containing the ZCR value for each channel.



140
141
 
# File 'stubs/ruby_dsp/audio_track.rb', line 140

def zcr
end