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 = 'default.wav', target_channels = 0, target_sample_rate = 0) ⇒ AudioTrack

Initializes a new AudioTrack and decodes the given file.

Parameters:

  • file_name (String) (defaults to: 'default.wav') —

    Path to the audio file.

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

    Optional. Force a specific number of channels (0 = original).

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

    Optional. Force a specific sample rate (0 = original).

Raises:

  • (RuntimeError) —

    if the file cannot be processed or read.



30
31
 
# File 'stubs/ruby_dsp/audio_track.rb', line 30

def initialize(file_name = 'default.wav', 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

#duration ⇒ Float

Calculates the total duration of the track.

Returns:

  • (Float) —

    duration in seconds.



60
61
 
# File 'stubs/ruby_dsp/audio_track.rb', line 60

def duration
end

#fade_in!(duration_sec) ⇒ Boolean

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:

  • (Boolean) —

    true if the fade was applied, false if the track is empty or duration is <= 0.



142
143
 
# File 'stubs/ruby_dsp/audio_track.rb', line 142

def fade_in!(duration_sec)
end

#fade_out!(duration_sec) ⇒ Boolean

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:

  • (Boolean) —

    true if the fade was applied, false if the track is empty or duration is <= 0.



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

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



95
96
 
# File 'stubs/ruby_dsp/audio_track.rb', line 95

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



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

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

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

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:

  • (Boolean) —

    true if the track was altered, false if it was already at the target or silent.



136
137
 
# File 'stubs/ruby_dsp/audio_track.rb', line 136

def normalize!(target_db = -10.0)
end

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

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:

  • (Boolean) —

    true if padding was added, false otherwise.



155
156
 
# File 'stubs/ruby_dsp/audio_track.rb', line 155

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

#pad_to_duration!(target_duration_sec) ⇒ Boolean

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:

  • (Boolean) —

    true if padding was added, false if the track is already longer than the target.



162
163
 
# File 'stubs/ruby_dsp/audio_track.rb', line 162

def pad_to_duration!(target_duration_sec)
end

#peak_amp ⇒ Float

Finds the maximum absolute amplitude across all channels.

Returns:

  • (Float) —

    the peak amplitude.



66
67
 
# File 'stubs/ruby_dsp/audio_track.rb', line 66

def peak_amp
end

#resample!(target_rate = 0) ⇒ Boolean

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:

  • (Boolean) —

    true if resampling happened, false if the rate was unchanged.

Raises:

  • (RuntimeError) —

    if the resampler fails to initialize or process.



81
82
 
# File 'stubs/ruby_dsp/audio_track.rb', line 81

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.



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

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.



54
55
 
# File 'stubs/ruby_dsp/audio_track.rb', line 54

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.



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

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

#to_mono! ⇒ Boolean

Destructively converts the track to mono by averaging the channels.

Returns:

  • (Boolean) —

    true if conversion happened, false if already mono.

Raises:

  • (RuntimeError) —

    if channel count is invalid.



73
74
 
# File 'stubs/ruby_dsp/audio_track.rb', line 73

def to_mono!
end

#to_s ⇒ String

Returns a formatted summary of the track.

Returns:

  • (String) —

    a formatted summary of the track.



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

def to_s
end

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

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:

  • (Boolean) —

    true if the track was trimmed, false if no trimming occurred.



130
131
 
# File 'stubs/ruby_dsp/audio_track.rb', line 130

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.



101
102
 
# File 'stubs/ruby_dsp/audio_track.rb', line 101

def zcr
end