deftones 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80388e6ab20e1b3a9affc4cca0a73812c482003d1ac124b80ccfb1714c94a4a5
-  data.tar.gz: 30a59df05c0faec27f12794bb167d80b5ab0ce61c6273a3c2d77df72106a11fc
+  metadata.gz: 6215833a8d30fe3a76382b1928335e8a22b94df1e1649f7fb0b028f5836d9b3e
+  data.tar.gz: 943cdc21e72614d018ca04709763cf8e38d1c646c071a53311c3a0e5aaef97ef
 SHA512:
-  metadata.gz: 4fed0062263092487ce098080789d29f754151f6991fbd6479fe6cfa35f8c3f248a2e5c2f8d4c06206cfbdc3447ea0569d46052f72f4763aa6a9617a0a3549b1
-  data.tar.gz: 611b45acf4df1b5621a137892ff04ecb286634c96185a29d34b41e21e8bfec57181f0e296b24e6fab634815a036d95e9716786d40093e2fb49d12176cf0bbac3
+  metadata.gz: 07dd0a8c79f2ed19114d2af15ed16a7a622a9dcbe816cf2573940af20e028d0fac81c37c6f162a9ea8529d0b635aa61a0da0d066cd424e069f56b9f8015c63e6
+  data.tar.gz: 494465a98c4407ac72999dbc9070351a2b39cdc013af4f957129f50cdcae524a47efd9f16b6a31723da62a0d5178fbdcda53175e3a88e831a057afb95d000cc2

data/CHANGELOG.md

@@ -2,11 +2,16 @@
 
 ## Unreleased
 
-- Added realtime PortAudio stream integration with lazy context startup.
-- Added `UserMedia` live capture support through pluggable capture backends.
-- Added `Buffers`, compressed audio import, MIDI I/O helpers, and lower-level routing primitives.
-- Added MP3 export support for offline rendering when `ffmpeg` or `afconvert` is available.
+## 1.0.0 - 2026-05-25
 
-## 0.1.0
+- Expanded the public API surface across sources, instruments, effects, analysis, transport/event helpers, music-unit wrappers, and top-level compatibility helpers.
+- Improved transport and event scheduling with context-scoped schedulers, scheduler-window offline rendering, tempo/state automation, richer pattern scheduling, and duplicate-safe realtime lookahead.
+- Expanded sample, buffer, and render workflows with explicit resampling, interpolation modes, LUFS normalization, slice metadata, codec capability reporting, streamed compressed renders, codec path/format validation, and WAV bit depth/dither options.
+- Added more synthesis and effects controls, including grain jitter/window options, selectable panner pan laws, reverb damping controls, compressor detector controls, nonlinear effect oversampling, sampler playback policies, instrument loaded state, and packed audio block access.
+- Improved audio correctness and failure modes with stricter graph routing, voice state, source type, automation, param, event, codec, and music-value validation; clearer music value errors; feedback delay clamping; triangle oscillator fixes; filter state resets; and denormal DSP handling.
+- Improved realtime and MIDI workflows with selectable realtime output devices, explicit realtime stream error policy, sample rate mismatch detection, metering diagnostics, MIDI device session handling, and MIDI-to-transport/target routing.
+- Optional realtime, MIDI, and codec backends now load lazily and expose capability queries, so offline rendering can run without native realtime, MIDI, or codec dependencies.
 
-- Initial public MVP release.
+## 0.1.0 - 2026-03-27
+
+- Initial release.

data/README.md

@@ -1,5 +1,10 @@
 # Deftones
 
+[![CI](https://github.com/ydah/deftones/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/deftones/actions/workflows/main.yml)
+[![Gem Version](https://img.shields.io/gem/v/deftones.svg)](https://rubygems.org/gems/deftones)
+[![Required Ruby](https://img.shields.io/gem/ruby-version/deftones.svg)](https://rubygems.org/gems/deftones)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
 Deftones is a Ruby audio synthesis library with a flexible node graph, oscillator and synth variants, effects, transport/event scheduling, sample playback, analysis utilities, offline rendering, and an optional PortAudio-backed realtime context.
 
 ## Features

data/Rakefile

@@ -1,8 +1,57 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+require "rbconfig"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+namespace :quality do
+  desc "Verify gem package file boundaries"
+  task :gem_files do
+    spec = Gem::Specification.load("deftones.gemspec")
+    forbidden_prefixes = %w[.github/ spec/ build/ pkg/]
+    forbidden_files = spec.files.select { |file| forbidden_prefixes.any? { |prefix| file.start_with?(prefix) } }
+    raise "Unexpected files in gem: #{forbidden_files.join(', ')}" unless forbidden_files.empty?
+
+    large_files = spec.files.select { |file| File.file?(file) && File.size(file) > 1_000_000 }
+    raise "Large files in gem: #{large_files.join(', ')}" unless large_files.empty?
+  end
+
+  desc "Verify optional compressed audio backend detection without PATH tools"
+  task :optional_backends do
+    require_relative "lib/deftones"
+
+    previous_path = ENV["PATH"]
+    previous_backend = Deftones::IO::Buffer.codec_backend
+    ENV["PATH"] = ""
+    Deftones::IO::Buffer.codec_backend = nil
+    raise "Compressed audio backend should be unavailable without PATH tools" if Deftones.compressed_audio_available?
+  ensure
+    Deftones::IO::Buffer.codec_backend = previous_backend if defined?(Deftones::IO::Buffer)
+    ENV["PATH"] = previous_path
+  end
+
+  desc "Verify the library loads cleanly with Ruby warnings enabled"
+  task :require_warnings do
+    ruby = RbConfig.ruby
+    sh ruby, "-w", "-Ilib", "-e", "require 'deftones'; puts Deftones.version"
+  end
+end
+
+namespace :release do
+  desc "Verify release tag and changelog metadata"
+  task :verify do
+    require_relative "lib/deftones/version"
+
+    tag = ENV["GITHUB_REF_NAME"] || `git tag --points-at HEAD`.lines.first&.strip
+    expected_tag = "v#{Deftones::VERSION}"
+    raise "Release tag #{tag.inspect} does not match #{expected_tag}" if tag && !tag.empty? && tag != expected_tag
+
+    changelog = File.read("CHANGELOG.md")
+    raise "CHANGELOG.md is missing #{Deftones::VERSION}" unless changelog.include?("## #{Deftones::VERSION}")
+  end
+end
+
+task quality: ["quality:gem_files", "quality:optional_backends", "quality:require_warnings"]
+task default: %i[spec quality]

data/lib/deftones/analysis/meter.rb

@@ -3,14 +3,16 @@
 module Deftones
   module Analysis
     class Meter < Core::AudioNode
-      attr_accessor :normal_range
+      attr_accessor :normal_range, :clip_threshold
 
-      def initialize(smoothing: 0.8, normal_range: false, channels: 1, context: Deftones.context)
+      def initialize(smoothing: 0.8, normal_range: false, channels: 1, clip_threshold: 1.0, context: Deftones.context)
         super(context: context)
         @channels = [channels.to_i, 1].max
         @peak_values = Array.new(@channels, 0.0)
         @rms_values = Array.new(@channels, 0.0)
+        @clip_counts = Array.new(@channels, 0)
         @normal_range = !!normal_range
+        @clip_threshold = clip_threshold.to_f
         self.smoothing = smoothing
       end
 
@@ -26,6 +28,17 @@ module Deftones
         @rms_values.length == 1 ? @rms_values.first : @rms_values.dup
       end
 
+      def clip_count
+        @clip_counts.length == 1 ? @clip_counts.first : @clip_counts.dup
+      end
+
+      def reset
+        @peak_values.fill(0.0)
+        @rms_values.fill(0.0)
+        @clip_counts.fill(0)
+        self
+      end
+
       def smoothing
         @smoothing
       end
@@ -57,6 +70,7 @@ module Deftones
           segment = analysis_block.channel_data[channel_index].first(num_frames)
           instantaneous_peak = segment.map(&:abs).max || 0.0
           instantaneous_rms = Math.sqrt(segment.sum { |sample| sample * sample } / [segment.length, 1].max)
+          @clip_counts[channel_index] += segment.count { |sample| sample.abs >= @clip_threshold }
           @peak_values[channel_index] = smooth(@peak_values[channel_index], instantaneous_peak)
           @rms_values[channel_index] = smooth(@rms_values[channel_index], instantaneous_rms)
         end
@@ -66,11 +80,17 @@ module Deftones
 
       alias getValue get_value
       alias normalRange normal_range
+      alias clipCount clip_count
+      alias clipThreshold clip_threshold
 
       def normalRange=(value)
         self.normal_range = value
       end
 
+      def clipThreshold=(value)
+        self.clip_threshold = value
+      end
+
       private
 
       def smooth(previous, current)

data/lib/deftones/component/channel.rb

@@ -9,7 +9,7 @@ module Deftones
         attr_reader :buses
       end
 
-      attr_reader :input, :output, :pan_vol, :solo
+      attr_reader :input, :output, :pan_vol
 
       def initialize(pan: 0.0, volume: 0.0, solo: false, muted: false, mute: nil, context: Deftones.context)
         super(context: context)

data/lib/deftones/component/compressor.rb

@@ -3,15 +3,69 @@
 module Deftones
   module Component
     class Compressor < Core::AudioNode
-      attr_accessor :threshold, :ratio, :attack, :release
+      DETECTORS = %i[peak rms].freeze
 
-      def initialize(threshold: -18.0, ratio: 4.0, attack: 0.01, release: 0.1, context: Deftones.context)
+      attr_reader :threshold, :ratio, :attack, :release, :detector, :knee, :lookahead, :lookahead_samples,
+                  :rms_window, :true_peak
+
+      def initialize(threshold: -18.0, ratio: 4.0, attack: 0.01, release: 0.1, detector: :peak,
+                     knee: 0.0, lookahead: 0.0, rms_window: 0.01, true_peak: false,
+                     context: Deftones.context)
         super(context: context)
-        @threshold = threshold.to_f
-        @ratio = ratio.to_f
-        @attack = attack.to_f
-        @release = release.to_f
         @gain_db = []
+        @rms_energy = []
+        @lookahead_buffers = []
+        @previous_detector_samples = []
+        self.threshold = threshold
+        self.ratio = ratio
+        self.attack = attack
+        self.release = release
+        self.detector = detector
+        self.knee = knee
+        self.lookahead = lookahead
+        self.rms_window = rms_window
+        self.true_peak = true_peak
+      end
+
+      def threshold=(value)
+        @threshold = value.to_f
+      end
+
+      def ratio=(value)
+        @ratio = value.to_f
+      end
+
+      def attack=(value)
+        @attack = value.to_f
+        @attack_smoothing = smoothing_for(@attack)
+      end
+
+      def release=(value)
+        @release = value.to_f
+        @release_smoothing = smoothing_for(@release)
+      end
+
+      def detector=(value)
+        @detector = normalize_detector(value)
+      end
+
+      def knee=(value)
+        @knee = [value.to_f, 0.0].max
+      end
+
+      def lookahead=(value)
+        @lookahead = [value.to_f, 0.0].max
+        @lookahead_samples = (@lookahead * context.sample_rate).round
+        @lookahead_buffers = []
+      end
+
+      def rms_window=(value)
+        @rms_window = [value.to_f, 0.0].max
+        @rms_smoothing = smoothing_for(@rms_window)
+      end
+
+      def true_peak=(value)
+        @true_peak = !!value
       end
 
       def multichannel_process?
@@ -19,7 +73,7 @@ module Deftones
       end
 
       def process(input_block, num_frames, _start_frame, _cache)
-        ensure_gain_state(input_block.channels)
+        ensure_channel_state(input_block.channels)
         Core::AudioBlock.from_channel_data(
           input_block.channel_data.each_with_index.map do |channel, channel_index|
             Array.new(num_frames) { |index| compress(channel[index], channel_index) }
@@ -30,34 +84,85 @@ module Deftones
       private
 
       def compress(sample, channel_index)
-        level = [sample.abs, 1.0e-9].max
+        level = [detector_level(sample, channel_index), 1.0e-9].max
         level_db = 20.0 * Math.log10(level)
-        target_gain_db =
-          if level_db > @threshold
-            compressed_db = @threshold + ((level_db - @threshold) / [@ratio, 1.0].max)
-            compressed_db - level_db
-          else
-            0.0
-          end
+        target_gain_db = gain_reduction_db(level_db)
 
         current_gain_db = @gain_db[channel_index]
-        smoothing = target_gain_db < current_gain_db ? attack_smoothing : release_smoothing
+        smoothing = target_gain_db < current_gain_db ? @attack_smoothing : @release_smoothing
         current_gain_db += (target_gain_db - current_gain_db) * smoothing
         @gain_db[channel_index] = current_gain_db
-        sample * (10.0**(current_gain_db / 20.0))
+        lookahead_sample(sample, channel_index) * (10.0**(current_gain_db / 20.0))
+      end
+
+      def detector_level(sample, channel_index)
+        level =
+          case @detector
+          when :rms then rms_level(sample, channel_index)
+          else sample.abs
+          end
+        return level unless @true_peak
+
+        previous_sample = @previous_detector_samples[channel_index] || sample
+        @previous_detector_samples[channel_index] = sample
+        [level, sample.abs, previous_sample.abs, ((previous_sample + sample) * 0.5).abs].max
       end
 
-      def attack_smoothing
-        1.0 / [(@attack * context.sample_rate), 1.0].max
+      def rms_level(sample, channel_index)
+        energy = @rms_energy[channel_index]
+        @rms_energy[channel_index] = ((1.0 - @rms_smoothing) * energy) + (@rms_smoothing * sample * sample)
+        Math.sqrt(@rms_energy[channel_index])
       end
 
-      def release_smoothing
-        1.0 / [(@release * context.sample_rate), 1.0].max
+      def gain_reduction_db(level_db)
+        ratio = [@ratio, 1.0].max
+        return 0.0 if ratio <= 1.0
+        return hard_knee_gain_reduction_db(level_db, ratio) if @knee.zero?
+
+        over_threshold = level_db - @threshold
+        half_knee = @knee * 0.5
+        return 0.0 if over_threshold <= -half_knee
+        return hard_knee_gain_reduction_db(level_db, ratio) if over_threshold >= half_knee
+
+        ((1.0 / ratio) - 1.0) * ((over_threshold + half_knee)**2.0) / (2.0 * @knee)
+      end
+
+      def hard_knee_gain_reduction_db(level_db, ratio)
+        return 0.0 unless level_db > @threshold
+
+        compressed_db = @threshold + ((level_db - @threshold) / ratio)
+        compressed_db - level_db
       end
 
-      def ensure_gain_state(channels)
+      def lookahead_sample(sample, channel_index)
+        return sample if @lookahead_samples.zero?
+
+        buffer = @lookahead_buffers[channel_index]
+        buffer << sample
+        buffer.shift || 0.0
+      end
+
+      def smoothing_for(seconds)
+        1.0 / [(seconds.to_f * context.sample_rate), 1.0].max
+      end
+
+      def ensure_channel_state(channels)
         required = [channels.to_i, 1].max
         @gain_db.fill(0.0, @gain_db.length...required)
+        @rms_energy.fill(0.0, @rms_energy.length...required)
+        @previous_detector_samples.fill(0.0, @previous_detector_samples.length...required)
+        required.times do |channel_index|
+          next if @lookahead_buffers[channel_index]&.length == @lookahead_samples
+
+          @lookahead_buffers[channel_index] = Array.new(@lookahead_samples, 0.0)
+        end
+      end
+
+      def normalize_detector(value)
+        normalized = value.to_sym
+        return normalized if DETECTORS.include?(normalized)
+
+        raise ArgumentError, "Unsupported compressor detector: #{value}"
       end
     end
   end

data/lib/deftones/component/filter.rb

@@ -5,33 +5,48 @@ module Deftones
     class Filter < Core::AudioNode
       TYPES = DSP::Biquad::TYPES
 
-      attr_reader :detune, :frequency, :q, :gain
-      attr_accessor :type
+      attr_reader :detune, :frequency, :gain, :q, :type
 
       def initialize(type: :lowpass, frequency: 350.0, q: 1.0, gain: 0.0, detune: 0.0, context: Deftones.context)
         super(context: context)
-        @type = normalize_type(type)
+        @biquads = []
+        self.type = type
         @frequency = Core::Signal.new(value: frequency, units: :frequency, context: context)
         @q = Core::Signal.new(value: q, units: :number, context: context)
         @gain = Core::Signal.new(value: gain, units: :number, context: context)
         @detune = Core::Signal.new(value: detune, units: :number, context: context)
-        @biquads = []
       end
 
       def detune=(value)
         @detune.value = value
       end
 
+      def type=(value)
+        normalized = normalize_type(value)
+        return @type = normalized if @type == normalized
+
+        @type = normalized
+        reset!
+      end
+
       def multichannel_process?
         true
       end
 
       def process(input_block, num_frames, start_frame, _cache)
-        update_filters(input_block.channels, start_frame)
+        ensure_biquads(input_block.channels)
+        frequencies = @frequency.process(num_frames, start_frame)
+        detunes = @detune.process(num_frames, start_frame)
+        q_values = @q.process(num_frames, start_frame)
+        gain_values = @gain.process(num_frames, start_frame)
+
         Core::AudioBlock.from_channel_data(
           input_block.channel_data.each_with_index.map do |channel, channel_index|
             biquad = @biquads[channel_index]
-            Array.new(num_frames) { |index| biquad.process_sample(channel[index]) }
+            Array.new(num_frames) do |index|
+              update_filter(biquad, frequencies[index], detunes[index], q_values[index], gain_values[index])
+              biquad.process_sample(channel[index])
+            end
           end
         )
       end
@@ -43,19 +58,14 @@ module Deftones
 
       private
 
-      def update_filters(channels, start_frame)
-        ensure_biquads(channels)
-        frequency = @frequency.process(1, start_frame).first
-        detune = @detune.process(1, start_frame).first
-        @biquads.each do |biquad|
-          biquad.update(
-            type: normalize_type(@type),
-            frequency: frequency * (2.0**(detune / 1200.0)),
-            q: @q.process(1, start_frame).first,
-            gain_db: @gain.process(1, start_frame).first * 24.0,
-            sample_rate: context.sample_rate
-          )
-        end
+      def update_filter(biquad, frequency, detune, q, gain)
+        biquad.update(
+          type: normalize_type(@type),
+          frequency: frequency * (2.0**(detune / 1200.0)),
+          q: q,
+          gain_db: gain * 24.0,
+          sample_rate: context.sample_rate
+        )
       end
 
       def ensure_biquads(channels)

data/lib/deftones/component/merge.rb

@@ -13,6 +13,20 @@ module Deftones
         @output = self
       end
 
+      def number_of_inputs
+        2
+      end
+
+      alias numberOfInputs number_of_inputs
+
+      def input_for_index(index)
+        case index
+        when 0 then @left
+        when 1 then @right
+        else raise_connection_index_error!(:input_index, index, number_of_inputs)
+        end
+      end
+
       def render(num_frames, start_frame = 0, cache = {})
         cache_key = [object_id, start_frame, num_frames]
         return cache.fetch(cache_key).dup if cache.key?(cache_key)

data/lib/deftones/component/multiband_compressor.rb

@@ -3,7 +3,7 @@
 module Deftones
   module Component
     class MultibandCompressor < Core::AudioNode
-      attr_reader :high, :high_frequency, :input, :low, :low_frequency, :mid, :output, :q, :split
+      attr_reader :high, :input, :low, :mid, :output, :split
 
       def initialize(low_frequency: 400.0, high_frequency: 2_500.0, q: 1.0, low: {}, mid: {}, high: {},
                      context: Deftones.context)

data/lib/deftones/component/one_pole_filter.rb

@@ -5,20 +5,27 @@ module Deftones
     class OnePoleFilter < Core::AudioNode
       TYPES = %i[lowpass highpass].freeze
 
-      attr_reader :frequency
-      attr_accessor :type
+      attr_reader :frequency, :type
 
       def initialize(frequency: 880.0, type: :lowpass, context: Deftones.context)
         super(context: context)
         @frequency = Core::Signal.new(value: frequency, units: :frequency, context: context)
-        @type = normalize_type(type)
         @lowpass_state = []
+        self.type = type
       end
 
       def frequency=(value)
         @frequency.value = value
       end
 
+      def type=(value)
+        normalized = normalize_type(value)
+        return @type = normalized if @type == normalized
+
+        @type = normalized
+        reset!
+      end
+
       def multichannel_process?
         true
       end

data/lib/deftones/component/panner.rb

@@ -3,17 +3,24 @@
 module Deftones
   module Component
     class Panner < Core::AudioNode
-      attr_reader :pan
+      PAN_LAWS = %i[equal_power linear].freeze
 
-      def initialize(pan: 0.0, context: Deftones.context)
+      attr_reader :pan, :pan_law
+
+      def initialize(pan: 0.0, pan_law: :equal_power, context: Deftones.context)
         super(context: context)
         @pan = Core::Signal.new(value: pan, units: :number, context: context)
+        @pan_law = normalize_pan_law(pan_law)
       end
 
       def pan=(value)
         @pan.value = value
       end
 
+      def pan_law=(value)
+        @pan_law = normalize_pan_law(value)
+      end
+
       def multichannel_process?
         true
       end
@@ -47,6 +54,7 @@ module Deftones
 
       def stereo_left_gain(pan)
         normalized = pan.to_f.clamp(-1.0, 1.0)
+        return [1.0 - normalized, 0.0].max if @pan_law == :linear && normalized.positive?
         return 1.0 if normalized <= 0.0
 
         Math.cos(normalized * Math::PI * 0.5)
@@ -54,22 +62,37 @@ module Deftones
 
       def stereo_right_gain(pan)
         normalized = pan.to_f.clamp(-1.0, 1.0)
+        return [1.0 + normalized, 0.0].max if @pan_law == :linear && normalized.negative?
         return 1.0 if normalized >= 0.0
 
         Math.cos(normalized.abs * Math::PI * 0.5)
       end
 
       def left_gain(pan)
+        return (1.0 - pan.to_f.clamp(-1.0, 1.0)) * 0.5 if @pan_law == :linear
+
         Math.cos(angle_for(pan))
       end
 
       def right_gain(pan)
+        return (1.0 + pan.to_f.clamp(-1.0, 1.0)) * 0.5 if @pan_law == :linear
+
         Math.sin(angle_for(pan))
       end
 
       def angle_for(pan)
         ((pan.to_f.clamp(-1.0, 1.0) + 1.0) * Math::PI) * 0.25
       end
+
+      def normalize_pan_law(value)
+        normalized = value.to_sym
+        return normalized if PAN_LAWS.include?(normalized)
+
+        raise ArgumentError, "Unsupported pan law: #{value}"
+      end
+
+      alias panLaw pan_law
+      alias panLaw= pan_law=
     end
   end
 end

data/lib/deftones/component/panner3d.rb

@@ -178,16 +178,6 @@ module Deftones
           @listener.position_y.value,
           @listener.position_z.value
         ]
-        listener_forward = normalize_vector([
-          @listener.forward_x.value,
-          @listener.forward_y.value,
-          @listener.forward_z.value
-        ])
-        listener_up = normalize_vector([
-          @listener.up_x.value,
-          @listener.up_y.value,
-          @listener.up_z.value
-        ])
         mono_input = send(:mix_source_blocks, num_frames, start_frame, cache).mono
 
         Array.new(num_frames) do |index|

data/lib/deftones/component/split.rb

@@ -11,6 +11,20 @@ module Deftones
         @right = OutputTap.new(parent: self, channel: 1, context: context)
       end
 
+      def number_of_outputs
+        2
+      end
+
+      alias numberOfOutputs number_of_outputs
+
+      def output_for_index(index)
+        case index
+        when 0 then @left
+        when 1 then @right
+        else raise_connection_index_error!(:output_index, index, number_of_outputs)
+        end
+      end
+
       def render_channel(_channel, num_frames, start_frame = 0, cache = {})
         render_channel_block(_channel, num_frames, start_frame, cache).mono
       end