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

#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

#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

#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

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



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

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