ruby_dsp 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 413c7e687de2f9253fc92e7d57b1a9a9facc40a1597ffd0c6ce9135f1d4eaeb4
-  data.tar.gz: 816c5a826c06f77e9a306762185f26323ff0a06894b0d06e6669d39289295cdd
+  metadata.gz: d0352100ed3bc4d5984dd4b59ca7540eea006a7234eb2ed9a87ca88c61af3c91
+  data.tar.gz: 94b1b8182701c588618dbbe6e44f9135a73c62c9b8f174d745f5e807df379145
 SHA512:
-  metadata.gz: a750759a4c53edf49001f021898c39d0c1ca473f64aa1a68983267b04117fb2e339867778c72d778891bac23d2ef44a42ace5cd8ae56c82feda4616dcb155fd9
-  data.tar.gz: c1744710c8b0f5a99f0a46dcf40fb91159d13a976c8f4fe0cef1751e85e457a07743924c90dba30916cced84760c74fd56ce6b2c82692aba01906b033fb9bc14
+  metadata.gz: 17e977dd018f850f37210a0d4cc9abd209ad276f51f62792fb240ccb94a8d096f8f8ff7d59a201b21cab38e048b901ed93e4ff9c89809c281d2b923816bb2641
+  data.tar.gz: d807466791df6a0f6cac661dc77e763cd03c5aeb2dd251d969054ff2bda5d0321735f4615819233f9ed9fdb9bb51f3b8b0eaf2e886d7269f29c1595aa616bc0d

data/README.md

@@ -1,4 +1,4 @@
-# [RubyDSP](https://github.com/cichrrad/rubyDSP) | [Documentation](https://www.rubydoc.info/gems/ruby_dsp/0.0.7)
+# [RubyDSP](https://github.com/cichrrad/rubyDSP) | [Documentation](https://www.rubydoc.info/gems/ruby_dsp/0.0.8)
 
 [![Ruby CI](https://github.com/cichrrad/rubyDSP/actions/workflows/test.yml/badge.svg)](https://github.com/cichrrad/rubyDSP/actions/workflows/test.yml)
 
@@ -19,6 +19,8 @@ I made this gem to try hands-on binding these two languages together, as I would
 
 * **Audio Synthesis & Sequencing:** Build multitrack, polyphonic audio from scratch using a (very limited) set of built-in mathematically generated waveforms (sine, square, sawtooth, and white noise).
 
+* **DSP Filters & EQ:** A suite of filters (Low-pass, High-pass, Band-pass, Notch, and Shelving EQs) via `miniaudio`.
+
 * **Format Agnostic Loading:** Automatically decodes standard audio formats (WAV, MP3, FLAC) via `miniaudio`.
 > **Note:** While the loading of these formats is supported, `miniaudio` saves only in `.wav`. While other encodings might be considered in the future, they would require more dependencies and thus are not available right now.
 
@@ -26,6 +28,16 @@ I made this gem to try hands-on binding these two languages together, as I would
 
 * **YARD Support:** Includes pure-Ruby stubs (in `stubs`, duh) for IDE autocomplete and inline documentation.
 
+## Overview of Capabilities
+
+* **File Operations:** `save_track`
+* **Mutations:** `to_mono!`, `resample!`, `trim_silence!`, `normalize!`, `fade_in!`, `fade_out!`, `pad!`, `pad_to_duration!`, `clip!`
+* **DSP Filters:** `low_pass!`, `high_pass!`, `band_pass!`, `notch!`, `peak_eq!`, `low_shelf!`, `high_shelf!`
+* **Synthesis:** `add_wave!`
+* **Analysis:** `duration`, `peak_amp`, `rms`, `framed_rms`, `zcr`, `framed_zcr`, `silence_bounds`
+
+*(For full parameters and usage, please check the [API Documentation](https://www.rubydoc.info/gems/ruby_dsp/0.0.8))*
+
 ## Benchmarks & Performance
 
 My primary motivation (love for Ruby aside) was to try and bring C++ speed to Ruby, avoiding the massive memory and garbage collection overhead of native Ruby math for audio/DSP tasks. 
@@ -41,10 +53,10 @@ Benchmark script files are in `benchmark` directory. If you clone the repo for d
 -----------------------------------------------------------------------------------------------
 | Benchmark                 | C++ Speedup  | Ruby Allocation        | C++ Allocation         |
 -----------------------------------------------------------------------------------------------
-| Read-Only (RMS)           | 49.07x       | 40 B (1 obj)           | 64 B (1 obj)           |
-| Mutation (Normalize)      | 462.51x      | 3,528,040 B (1 obj)    | 0 B (0 obj)            |
-| Complex (Framed RMS)      | 49.25x       | 41,264 B (860 obj)     | 64 B (1 obj)           |
-| Dynamic (Add Wave)        | 11.73x       | N/A                    | N/A                    |
+| Read-Only (RMS)           | 48.71x       | 40 B (1 obj)           | 64 B (1 obj)           |
+| Mutation (Normalize)      | 69.47x       | 3,528,040 B (1 obj)    | 0 B (0 obj)            |
+| Complex (Framed RMS)      | 48.68x       | 41,264 B (860 obj)     | 64 B (1 obj)           |
+| Dynamic (Add Wave)        | 11.67x       | N/A                    | N/A                    |
 -----------------------------------------------------------------------------------------------
 ```
 ### Why is it faster?
@@ -75,7 +87,7 @@ $ gem install ruby_dsp
 
 *(Note: Installing this gem requires a modern C++ compiler, as it builds the native extensions directly on your machine upon installation. It requires Ruby 3.0+).*
 
-## Quick Start: Audio Processing
+## Audio Processing
 
 Here is a quick look at what you can do with a loaded `AudioTrack`. Thanks to the fluent API, you can process audio in a single readable chain:
 
@@ -91,6 +103,8 @@ puts track
 # Process, edit, and save in one chain
 track.to_mono!                       # Averages channels into mono
      .resample!(44100)               # Linearly resamples to target rate
+     .high_pass!(100)                # Cuts out low-end rumble below 100Hz
+     .peak_eq!(1000, 3.0)            # Boosts 1000Hz by 3dB for vocal clarity
      .trim_silence!(-60.0)           # Strips leading/trailing silence below -60dB
      .normalize!(-1.0)               # Scales audio to target peak dBFS
      .pad_to_duration!(15.0)         # Centers audio evenly into a 15s window
@@ -98,7 +112,7 @@ track.to_mono!                       # Averages channels into mono
      .fade_out!(0.5)                 # Adds a 0.5s linear fade-out
      .save_track("processed.wav")    # Export the final result
 
-# Analysis & Math (Still works!)
+# Analysis & Math
 puts "Peak Amp: #{track.peak_amp}"
 puts "Overall RMS: #{track.rms}"
 puts "Overall ZCR: #{track.zcr}"
@@ -107,7 +121,7 @@ puts "Overall ZCR: #{track.zcr}"
 framed_rms_data = track.framed_rms(frame_length: 2048, hop_length: 512)
 ```
 
-## Quick Start: Synthesis & Sequencing
+## Synthesis & Sequencing
 
 Initialize an empty track and generate your own jam using `add_wave!`:
 
@@ -133,28 +147,17 @@ track.normalize!(-30.0)  # This goes a long way for your hearing
 
 #### **TWINKLE**
 
-
-
 https://github.com/user-attachments/assets/af6dbaee-630f-49e3-9704-8ff3440334cb
 
-
-
 #### **TETRIS**
 
-
-
 https://github.com/user-attachments/assets/b3ad6886-3552-4200-b725-f14083f96792
 
-
-
 #### **SUPER MARIO BROS**
 
-
-
 https://github.com/user-attachments/assets/5193d72d-4c32-4c83-8253-206402ac2889
 
 
-
 ## Development
 
 If you want to clone the repo and work on C++ guts, start with:

data/ext/ruby_dsp/ruby_dsp.cpp

@@ -170,7 +170,7 @@ struct AudioTrack
         float max_val = 0.0f;
         for (const auto &sample : samples)
         {
-            max_val = std::max(max_val, std::fabs(sample));
+            max_val = std::fmax(max_val, std::fabs(sample));
         }
         return max_val;
     }
@@ -592,7 +592,7 @@ struct AudioTrack
         float scale_factor = target_linear / current_peak;
 
         // already at the target peak -- do nothing
-        if (std::abs(scale_factor - 1.0f) < 1e-5f)
+        if (std::fabs(scale_factor - 1.0f) < 1e-5f)
             return *this;
 
         for (auto &sample : samples)
@@ -662,18 +662,13 @@ struct AudioTrack
         unsigned long long head_samples = head_frames * channels;
         unsigned long long tail_samples = tail_frames * channels;
 
-        // pad the beginning
-        if (head_samples > 0)
-        {
-            samples.insert(samples.begin(), head_samples, 0.0f);
-        }
-
-        // pad the end
-        if (tail_samples > 0)
-        {
-            samples.insert(samples.end(), tail_samples, 0.0f);
-        }
+        // calculate total new size
+        unsigned long long new_size = head_samples + sample_count + tail_samples;
+        std::vector<float> new_samples(new_size, 0.0f);
 
+        // move old samples in
+        std::move(samples.begin(), samples.end(), new_samples.begin() + head_samples);
+        samples = std::move(new_samples);
         sample_count = samples.size();
 
         return *this;
@@ -700,18 +695,12 @@ struct AudioTrack
         unsigned long long head_samples = head_frames * channels;
         unsigned long long tail_samples = tail_frames * channels;
 
-        // pad the beginning
-        if (head_samples > 0)
-        {
-            samples.insert(samples.begin(), head_samples, 0.0f);
-        }
-
-        // pad the end
-        if (tail_samples > 0)
-        {
-            samples.insert(samples.end(), tail_samples, 0.0f);
-        }
+        unsigned long long new_size = head_samples + sample_count + tail_samples;
+        std::vector<float> new_samples(new_size, 0.0f);
 
+        // move old samples in
+        std::move(samples.begin(), samples.end(), new_samples.begin() + head_samples);
+        samples = std::move(new_samples);
         sample_count = samples.size();
 
         return *this;
@@ -775,6 +764,137 @@ struct AudioTrack
         return *this;
     }
 
+    AudioTrack &clip_bang()
+    {
+        for (auto &s : samples)
+        {
+            s = std::clamp(s, -1.0f, 1.0f);
+        }
+        return *this;
+    }
+
+    AudioTrack &low_pass_bang(int cutoffFreq)
+    {
+        // High order low-pass filter (Butterworth)
+        // [https://miniaud.io/docs/manual/index.html#Filtering]
+        ma_lpf lpf;
+        ma_lpf_config config;
+
+        // last argument is MA_MAX_FILTER_ORDER, goes up to 4?
+        config = ma_lpf_config_init(ma_format_f32, channels, sample_rate, (double)cutoffFreq, 2);
+
+        if (ma_lpf_init(&config, NULL, &lpf) != MA_SUCCESS)
+        {
+            throw std::runtime_error("RubyDSP: Failed to initialize low-pass filter.");
+        }
+
+        // in-place filtering
+        unsigned long long frame_count = sample_count / channels;
+        ma_lpf_process_pcm_frames(&lpf, samples.data(), samples.data(), frame_count);
+        ma_lpf_uninit(&lpf, NULL);
+
+        return *this;
+    }
+
+    AudioTrack &high_pass_bang(int cutoff_freq)
+    {
+        ma_hpf hpf;
+        // 2nd order high-pass
+        ma_hpf_config config = ma_hpf_config_init(ma_format_f32, channels, sample_rate, (double)cutoff_freq, 2);
+
+        if (ma_hpf_init(&config, NULL, &hpf) != MA_SUCCESS)
+        {
+            throw std::runtime_error("RubyDSP: Failed to initialize high-pass filter.");
+        }
+
+        unsigned long long frame_count = sample_count / channels;
+        ma_hpf_process_pcm_frames(&hpf, samples.data(), samples.data(), frame_count);
+
+        return *this;
+    }
+
+    AudioTrack &band_pass_bang(int cutoff_freq)
+    {
+        ma_bpf bpf;
+        // order MUST be even for band-pass
+        // [https://miniaud.io/docs/manual/index.html#Filtering]
+        ma_bpf_config config = ma_bpf_config_init(ma_format_f32, channels, sample_rate, (double)cutoff_freq, 2);
+
+        if (ma_bpf_init(&config, NULL, &bpf) != MA_SUCCESS)
+        {
+            throw std::runtime_error("RubyDSP: Failed to initialize band-pass filter.");
+        }
+
+        unsigned long long frame_count = sample_count / channels;
+        ma_bpf_process_pcm_frames(&bpf, samples.data(), samples.data(), frame_count);
+
+        return *this;
+    }
+
+    AudioTrack &notch_bang(int center_freq, double q = 0.707)
+    {
+        ma_notch2 notch;
+        ma_notch2_config config = ma_notch2_config_init(ma_format_f32, channels, sample_rate, q, (double)center_freq);
+
+        if (ma_notch2_init(&config, NULL, &notch) != MA_SUCCESS)
+        {
+            throw std::runtime_error("RubyDSP: Failed to initialize notch filter.");
+        }
+
+        unsigned long long frame_count = sample_count / channels;
+        ma_notch2_process_pcm_frames(&notch, samples.data(), samples.data(), frame_count);
+
+        return *this;
+    }
+
+    AudioTrack &peak_eq_bang(int center_freq, double gain_db, double q = 0.707)
+    {
+        ma_peak2 peak;
+        ma_peak2_config config = ma_peak2_config_init(ma_format_f32, channels, sample_rate, gain_db, q, (double)center_freq);
+
+        if (ma_peak2_init(&config, NULL, &peak) != MA_SUCCESS)
+        {
+            throw std::runtime_error("RubyDSP: Failed to initialize peaking EQ filter.");
+        }
+
+        unsigned long long frame_count = sample_count / channels;
+        ma_peak2_process_pcm_frames(&peak, samples.data(), samples.data(), frame_count);
+
+        return *this;
+    }
+
+    AudioTrack &low_shelf_bang(int cutoff_freq, double gain_db, double q = 0.707)
+    {
+        ma_loshelf2 shelf;
+        ma_loshelf2_config config = ma_loshelf2_config_init(ma_format_f32, channels, sample_rate, gain_db, q, (double)cutoff_freq);
+
+        if (ma_loshelf2_init(&config, NULL, &shelf) != MA_SUCCESS)
+        {
+            throw std::runtime_error("RubyDSP: Failed to initialize low-shelf filter.");
+        }
+
+        unsigned long long frame_count = sample_count / channels;
+        ma_loshelf2_process_pcm_frames(&shelf, samples.data(), samples.data(), frame_count);
+
+        return *this;
+    }
+
+    AudioTrack &high_shelf_bang(int cutoff_freq, double gain_db, double q = 0.707)
+    {
+        ma_hishelf2 shelf;
+        ma_hishelf2_config config = ma_hishelf2_config_init(ma_format_f32, channels, sample_rate, gain_db, q, (double)cutoff_freq);
+
+        if (ma_hishelf2_init(&config, NULL, &shelf) != MA_SUCCESS)
+        {
+            throw std::runtime_error("RubyDSP: Failed to initialize high-shelf filter.");
+        }
+
+        unsigned long long frame_count = sample_count / channels;
+        ma_hishelf2_process_pcm_frames(&shelf, samples.data(), samples.data(), frame_count);
+
+        return *this;
+    }
+
     std::string to_s()
     {
         std::ostringstream stream;
@@ -849,5 +969,27 @@ extern "C"
                                                               Arg("duration_sec"),
                                                               Arg("start_sec") = -1.0f,
                                                               Arg("amplitude") = 1.0f)
+                                               .define_method("clip!", &AudioTrack::clip_bang)
+                                               .define_method("low_pass!", &AudioTrack::low_pass_bang,
+                                                              Arg("cutoff_freq"))
+                                               .define_method("high_pass!", &AudioTrack::high_pass_bang,
+                                                              Arg("cutoff_freq"))
+                                               .define_method("band_pass!", &AudioTrack::band_pass_bang,
+                                                              Arg("cutoff_freq"))
+                                               .define_method("notch!", &AudioTrack::notch_bang,
+                                                              Arg("center_freq"),
+                                                              Arg("q") = 0.707)
+                                               .define_method("peak_eq!", &AudioTrack::peak_eq_bang,
+                                                              Arg("center_freq"),
+                                                              Arg("gain_db"),
+                                                              Arg("q") = 0.707)
+                                               .define_method("low_shelf!", &AudioTrack::low_shelf_bang,
+                                                              Arg("cutoff_freq"),
+                                                              Arg("gain_db"),
+                                                              Arg("q") = 0.707)
+                                               .define_method("high_shelf!", &AudioTrack::high_shelf_bang,
+                                                              Arg("cutoff_freq"),
+                                                              Arg("gain_db"),
+                                                              Arg("q") = 0.707)
                                                .define_method("to_s", &AudioTrack::to_s);
 }

data/lib/ruby_dsp/version.rb

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

data/stubs/ruby_dsp/audio_track.rb

@@ -179,6 +179,80 @@ module RubyDSP
     def add_wave!(wave_type, frequency, duration_sec, start_sec = -1.0, amplitude = 1.0)
     end
 
+    # Destructively clamps all audio samples to the standard [-1.0, 1.0] range.
+    #
+    # This prevents harsh digital clipping when exporting polyphonic or boosted audio.
+    #
+    # @return [AudioTrack] self for method chaining.
+    def clip!
+    end
+
+    # Applies a high-order low-pass filter (Butterworth) to the track.
+    #
+    # Attenuates frequencies above the cutoff, letting lower frequencies pass through.
+    #
+    # @param cutoff_freq [Integer, Float] The threshold frequency in Hz.
+    # @return [AudioTrack] self for method chaining.
+    def low_pass!(cutoff_freq)
+    end
+
+    # Applies a 2nd-order high-pass filter to the track.
+    #
+    # Attenuates frequencies below the cutoff, letting higher frequencies pass through.
+    #
+    # @param cutoff_freq [Integer, Float] The threshold frequency in Hz.
+    # @return [AudioTrack] self for method chaining.
+    def high_pass!(cutoff_freq)
+    end
+
+    # Applies a 2nd-order band-pass filter to the track.
+    #
+    # Preserves frequencies around the cutoff, heavily attenuating both higher and lower frequencies.
+    #
+    # @param cutoff_freq [Integer, Float] The center frequency in Hz.
+    # @return [AudioTrack] self for method chaining.
+    def band_pass!(cutoff_freq)
+    end
+
+    # Applies a 2nd-order notch filter to surgically remove a specific frequency.
+    #
+    # @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.
+    def notch!(center_freq, q = 0.707)
+    end
+
+    # Applies a 2nd-order peaking EQ filter to boost or cut a specific frequency band.
+    #
+    # @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.
+    # @return [AudioTrack] self for method chaining.
+    def peak_eq!(center_freq, gain_db, q = 0.707)
+    end
+
+    # Applies a 2nd-order low-shelf filter.
+    #
+    # Boosts or cuts frequencies below the cutoff without affecting higher frequencies.
+    #
+    # @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.
+    # @return [AudioTrack] self for method chaining.
+    def low_shelf!(cutoff_freq, gain_db, q = 0.707)
+    end
+
+    # Applies a 2nd-order high-shelf filter.
+    #
+    # Boosts or cuts frequencies above the cutoff without affecting lower frequencies.
+    #
+    # @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.
+    # @return [AudioTrack] self for method chaining.
+    def high_shelf!(cutoff_freq, gain_db, q = 0.707)
+    end
+
     # @return [String] a formatted summary of the track.
     def to_s
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_dsp
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Radek C.