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.



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

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_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

Instance Method Details

#duration ⇒ Float

Calculates the total duration of the track.

Returns:

  • (Float) —

    duration in seconds.



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

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



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

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



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

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

#peak_amp ⇒ Float

Finds the maximum absolute amplitude across all channels.

Returns:

  • (Float) —

    the peak amplitude.



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

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.



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

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.



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

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.



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

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.



115
116
 
# File 'stubs/ruby_dsp/audio_track.rb', line 115

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.



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

def to_mono!
end

#to_s ⇒ String

Returns a formatted summary of the track.

Returns:

  • (String) —

    a formatted summary of the track.



128
129
 
# File 'stubs/ruby_dsp/audio_track.rb', line 128

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.



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

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.



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

def zcr
end