ruby_dsp 0.0.8 → 0.0.9

data/lib/ruby_dsp/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module RubyDSP
-  VERSION = '0.0.8'
+  VERSION = '0.0.9'
 end

data/stubs/ruby_dsp/audio_track.rb

@@ -2,6 +2,11 @@
 
 module RubyDSP
   # 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.
   class AudioTrack
     # @return [String] the path to the loaded audio file
     attr_reader :file_name
@@ -26,12 +31,37 @@ module RubyDSP
     # Decodes the given file using miniaudio. If `file_name` is an empty string `""`,
     # it initializes an empty, blank audio canvas for synthesis and sequencing.
     #
+    # @example Load an entire audio file
+    #   track = RubyDSP::AudioTrack.new("vocals.wav")
+    #
+    # @example Load a 10-second snippet starting at the 1-minute mark
+    #   snippet = RubyDSP::AudioTrack.new("podcast.mp3", 0, 0, 60.0, 10.0)
+    #
+    # @example Initialize a blank mono canvas at 48kHz
+    #   canvas = RubyDSP::AudioTrack.new("", 1, 48000)
+    #
     # @param file_name [String] Path to the audio file, or `""` for a blank track.
     # @param target_channels [Integer] Optional. Force a specific number of channels (Defaults to 1 for blank tracks).
     # @param target_sample_rate [Integer] Optional. Force a specific sample rate (Defaults to 44100 for blank tracks).
+    # @param start_sec [Float] Optional. The timestamp in seconds to start reading from. Defaults to 0.0.
+    # @param duration_sec [Float] Optional. The length of audio to read in seconds. Defaults to 0.0 (reads to the end).
     # @raise [RuntimeError] if a file is provided but cannot be processed or read.
-    def initialize(file_name = '', target_channels = 0, target_sample_rate = 0)
+    def initialize(file_name = '', target_channels = 0, target_sample_rate = 0, start_sec = 0.0, duration_sec = 0.0)
+    end
+
+    # 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.
+    #
+    # @example Non-destructive chaining
+    #   clean_vocals = track.dup.high_pass!(100).normalize!
+    #
+    # @return [AudioTrack] A new, independent instance of the track.
+    def dup
     end
+    alias clone dup
 
     # Saves the audio track to disk.
     #
@@ -71,6 +101,9 @@ module RubyDSP
 
     # Destructively converts the track to mono by averaging the channels.
     #
+    # @example
+    #   track.to_mono!
+    #
     # @return [AudioTrack] self for method chaining.
     # @raise [RuntimeError] if channel count is invalid.
     def to_mono!
@@ -78,6 +111,9 @@ module RubyDSP
 
     # Destructively resamples the track to the target rate using linear resampling.
     #
+    # @example Resample to standard CD quality
+    #   track.resample!(44100)
+    #
     # @param target_rate [Integer] The new sample rate in Hz.
     # @return [AudioTrack] self for method chaining.
     # @raise [RuntimeError] if the resampler fails to initialize or process.
@@ -126,6 +162,9 @@ module RubyDSP
 
     # Destructively trims leading and trailing silence from the track's internal sample array.
     #
+    # @example Trim anything quieter than -50dB from the start and end
+    #   track.trim_silence!(-50.0)
+    #
     # @param threshold_db [Float] The threshold in decibels below the peak RMS to consider as silence. Default is -60.0.
     # @param frame_length [Integer] The number of samples per frame. Default is 2048.
     # @param hop_length [Integer] The number of samples to advance each frame. Default is 512.
@@ -134,24 +173,40 @@ module RubyDSP
     end
 
     # Normalizes the audio track to a specific peak decibel level.
+    #
+    # @example Normalize peak to -1.0 dBFS
+    #   track.normalize!(-1.0)
+    #
     # @param target_db [Float] The target peak amplitude in dBFS. Defaults to -10.0.
     # @return [AudioTrack] self for method chaining.
     def normalize!(target_db = -10.0)
     end
 
     # Applies a linear fade-in to the beginning of the audio track.
+    #
+    # @example Fade in over 1.5 seconds
+    #   track.fade_in!(1.5)
+    #
     # @param duration_sec [Float] The length of the fade-in in seconds.
     # @return [AudioTrack] self for method chaining.
     def fade_in!(duration_sec)
     end
 
     # Applies a linear fade-out to the end of the audio track.
+    #
+    # @example Fade out over the last 2 seconds
+    #   track.fade_out!(2.0)
+    #
     # @param duration_sec [Float] The length of the fade-out in seconds.
     # @return [AudioTrack] self for method chaining.
     def fade_out!(duration_sec)
     end
 
     # Pads the audio track with digital silence (0.0) at the beginning and/or end.
+    #
+    # @example Add 1 second of silence to the start, and 0.5 to the end
+    #   track.pad!(1.0, 0.5)
+    #
     # @param head_sec [Float] Seconds of silence to add to the beginning. Defaults to 0.0.
     # @param tail_sec [Float] Seconds of silence to add to the end. Defaults to 0.0.
     # @return [AudioTrack] self for method chaining.
@@ -160,6 +215,10 @@ module RubyDSP
 
     # 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.
+    #
+    # @example Center a 3-second sound effect into exactly a 5-second window
+    #   track.pad_to_duration!(5.0)
+    #
     # @param target_duration_sec [Float] The desired total length of the track in seconds.
     # @return [AudioTrack] self for method chaining.
     def pad_to_duration!(target_duration_sec)
@@ -170,6 +229,11 @@ module RubyDSP
     # 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.
     #
+    # @example 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)
+    #
     # @param wave_type [String] The shape of the waveform (`"sine"`, `"square"`, `"sawtooth"`, `"noise"`).
     # @param frequency [Float] The frequency of the wave in Hz (e.g., 440.0).
     # @param duration_sec [Float] The length of the generated wave in seconds.
@@ -191,6 +255,9 @@ module RubyDSP
     #
     # Attenuates frequencies above the cutoff, letting lower frequencies pass through.
     #
+    # @example Cut out harsh high frequencies above 5kHz
+    #   track.low_pass!(5000)
+    #
     # @param cutoff_freq [Integer, Float] The threshold frequency in Hz.
     # @return [AudioTrack] self for method chaining.
     def low_pass!(cutoff_freq)
@@ -200,6 +267,9 @@ module RubyDSP
     #
     # Attenuates frequencies below the cutoff, letting higher frequencies pass through.
     #
+    # @example Cut out low-end rumble/wind noise below 80Hz
+    #   track.high_pass!(80)
+    #
     # @param cutoff_freq [Integer, Float] The threshold frequency in Hz.
     # @return [AudioTrack] self for method chaining.
     def high_pass!(cutoff_freq)
@@ -209,6 +279,9 @@ module RubyDSP
     #
     # Preserves frequencies around the cutoff, heavily attenuating both higher and lower frequencies.
     #
+    # @example Create a "telephone" effect by isolating 1000Hz
+    #   track.band_pass!(1000)
+    #
     # @param cutoff_freq [Integer, Float] The center frequency in Hz.
     # @return [AudioTrack] self for method chaining.
     def band_pass!(cutoff_freq)
@@ -216,6 +289,9 @@ module RubyDSP
 
     # Applies a 2nd-order notch filter to surgically remove a specific frequency.
     #
+    # @example Eliminate 60Hz electrical hum
+    #   track.notch!(60)
+    #
     # @param center_freq [Integer, Float] The exact frequency to eliminate in Hz.
     # @param q [Float] The resonance/width of the notch. Defaults to 0.707 (Butterworth).
     # @return [AudioTrack] self for method chaining.
@@ -224,6 +300,9 @@ module RubyDSP
 
     # Applies a 2nd-order peaking EQ filter to boost or cut a specific frequency band.
     #
+    # @example Boost 3kHz by 2.5dB for vocal clarity
+    #   track.peak_eq!(3000, 2.5)
+    #
     # @param center_freq [Integer, Float] The target frequency in Hz.
     # @param gain_db [Float] The amount to boost (positive) or cut (negative) in decibels.
     # @param q [Float] The resonance/width of the bell curve. Defaults to 0.707.
@@ -235,6 +314,9 @@ module RubyDSP
     #
     # Boosts or cuts frequencies below the cutoff without affecting higher frequencies.
     #
+    # @example Add a 3dB bass boost below 150Hz
+    #   track.low_shelf!(150, 3.0)
+    #
     # @param cutoff_freq [Integer, Float] The threshold frequency in Hz.
     # @param gain_db [Float] The amount to boost (positive) or cut (negative) in decibels.
     # @param q [Float] The resonance/slope of the shelf. Defaults to 0.707.
@@ -246,6 +328,9 @@ module RubyDSP
     #
     # Boosts or cuts frequencies above the cutoff without affecting lower frequencies.
     #
+    # @example Reduce harsh treble above 8kHz by 4dB
+    #   track.high_shelf!(8000, -4.0)
+    #
     # @param cutoff_freq [Integer, Float] The threshold frequency in Hz.
     # @param gain_db [Float] The amount to boost (positive) or cut (negative) in decibels.
     # @param q [Float] The resonance/slope of the shelf. Defaults to 0.707.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_dsp
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - Radek C.
@@ -204,6 +204,7 @@ files:
 - ext/ruby_dsp/extconf.rb
 - ext/ruby_dsp/ruby_dsp.cpp
 - ext/ruby_dsp/vendor/miniaudio.h
+- ext/ruby_dsp/vendor/pocketfft_hdronly.h
 - lib/ruby_dsp.rb
 - lib/ruby_dsp/version.rb
 - ruby_dsp.gemspec