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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file_name = '', target_channels = 0, target_sample_rate = 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.

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).

Raises:

  • (RuntimeError) —

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



33
34
 
# File 'stubs/ruby_dsp/audio_track.rb', line 33

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

Instance Attribute Details

#channels ⇒ Integer (readonly)

Returns the number of audio channels.

Returns:

  • (Integer) —

    the number of audio channels



10
11
12
 
# File 'stubs/ruby_dsp/audio_track.rb', line 10

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



7
8
9
 
# File 'stubs/ruby_dsp/audio_track.rb', line 7

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



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

def is_mono?
  @is_mono?
end

#sample_count ⇒ Integer (readonly)

Returns number of samples in samples.

Returns:

  • (Integer) —

    number of samples in samples



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

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



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

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



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

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.

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:



179
180
 
# File 'stubs/ruby_dsp/audio_track.rb', line 179

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.

Parameters:

  • cutoff_freq (Integer, Float) —

    The center frequency in Hz.

Returns:



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

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:



187
188
 
# File 'stubs/ruby_dsp/audio_track.rb', line 187

def clip!
end

#duration ⇒ Float

Calculates the total duration of the track.

Returns:

  • (Float) —

    duration in seconds.



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

def duration
end

#fade_in!(duration_sec) ⇒ AudioTrack

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

Parameters:

  • duration_sec (Float) —

    The length of the fade-in in seconds.

Returns:



145
146
 
# File 'stubs/ruby_dsp/audio_track.rb', line 145

def fade_in!(duration_sec)
end

#fade_out!(duration_sec) ⇒ AudioTrack

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

Parameters:

  • duration_sec (Float) —

    The length of the fade-out in seconds.

Returns:



151
152
 
# File 'stubs/ruby_dsp/audio_track.rb', line 151

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].



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

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].



112
113
 
# File 'stubs/ruby_dsp/audio_track.rb', line 112

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.

Parameters:

  • cutoff_freq (Integer, Float) —

    The threshold frequency in Hz.

Returns:



205
206
 
# File 'stubs/ruby_dsp/audio_track.rb', line 205

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.

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:



253
254
 
# File 'stubs/ruby_dsp/audio_track.rb', line 253

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.

Parameters:

  • cutoff_freq (Integer, Float) —

    The threshold frequency in Hz.

Returns:



196
197
 
# File 'stubs/ruby_dsp/audio_track.rb', line 196

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.

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:



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

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.

Parameters:

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

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

Returns:



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

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.

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:



222
223
 
# File 'stubs/ruby_dsp/audio_track.rb', line 222

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.

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:



158
159
 
# File 'stubs/ruby_dsp/audio_track.rb', line 158

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.

Parameters:

  • target_duration_sec (Float) —

    The desired total length of the track in seconds.

Returns:



165
166
 
# File 'stubs/ruby_dsp/audio_track.rb', line 165

def pad_to_duration!(target_duration_sec)
end

#peak_amp ⇒ Float

Finds the maximum absolute amplitude across all channels.

Returns:

  • (Float) —

    the peak amplitude.



69
70
 
# File 'stubs/ruby_dsp/audio_track.rb', line 69

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.

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:



231
232
 
# File 'stubs/ruby_dsp/audio_track.rb', line 231

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.

Parameters:

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

    The new sample rate in Hz.

Returns:

Raises:

  • (RuntimeError) —

    if the resampler fails to initialize or process.



84
85
 
# File 'stubs/ruby_dsp/audio_track.rb', line 84

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.



90
91
 
# File 'stubs/ruby_dsp/audio_track.rb', line 90

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.



57
58
 
# File 'stubs/ruby_dsp/audio_track.rb', line 57

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.



124
125
 
# File 'stubs/ruby_dsp/audio_track.rb', line 124

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.

Returns:

Raises:

  • (RuntimeError) —

    if channel count is invalid.



76
77
 
# File 'stubs/ruby_dsp/audio_track.rb', line 76

def to_mono!
end

#to_s ⇒ String

Returns a formatted summary of the track.

Returns:

  • (String) —

    a formatted summary of the track.



257
258
 
# File 'stubs/ruby_dsp/audio_track.rb', line 257

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.

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:



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

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.



104
105
 
# File 'stubs/ruby_dsp/audio_track.rb', line 104

def zcr
end