deftones 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80388e6ab20e1b3a9affc4cca0a73812c482003d1ac124b80ccfb1714c94a4a5
+  data.tar.gz: 30a59df05c0faec27f12794bb167d80b5ab0ce61c6273a3c2d77df72106a11fc
+SHA512:
+  metadata.gz: 4fed0062263092487ce098080789d29f754151f6991fbd6479fe6cfa35f8c3f248a2e5c2f8d4c06206cfbdc3447ea0569d46052f72f4763aa6a9617a0a3549b1
+  data.tar.gz: 611b45acf4df1b5621a137892ff04ecb286634c96185a29d34b41e21e8bfec57181f0e296b24e6fab634815a036d95e9716786d40093e2fb49d12176cf0bbac3

data/.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+--protected
+--private
+README.md
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 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.
+
+## 0.1.0
+
+- Initial public MVP release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,197 @@
+# Deftones
+
+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
+
+- Pull-based `AudioNode` graph with `connect`, `>>`, `chain`, `fan`, and `to_output`
+- `Context`, `OfflineContext`, `Destination`, `Draw`, `Listener`, `Emitter`, `Clock`, and `Delay`
+- `Signal` automation, note/frequency/time wrappers, MIDI device I/O wrappers, and compatibility top-level helpers
+- `Param`, `ToneAudioNode`, `UserMedia`, `CrossFade`, `Merge`, and `Split` for lower-level graph construction
+- Oscillators: basic, pulse, PWM, FM, AM, fat, omni, noise
+- Instruments: `Synth`, `MonoSynth`, `FMSynth`, `AMSynth`, `DuoSynth`, `NoiseSynth`, `PluckSynth`, `MembraneSynth`, `MetalSynth`, `PolySynth`, `Sampler`
+- Effects: distortion, crusher, chebyshev, delays, reverbs, chorus, phaser, tremolo, vibrato, auto-filter, auto-panner, auto-wah, shifter, pitch shift, widener
+- Filters, EQ, compressor, limiter, gate, convolution, comb, mid/side, multiband, and channel utilities
+- Transport, loops, parts, sequences, and patterns
+- Player, players, grain player, `ToneBufferSource`, `ToneOscillatorNode`, recorder, `ToneAudioBuffer`, `ToneAudioBuffers`, analyser, meter, FFT, waveform, DC meter
+- Standalone sources and modulation effects can be scheduled against the transport with `sync` / `start` / `stop`
+- Instruments expose `volume`, `mute`, camelCase trigger helpers, `PolySynth#releaseAll`, and `Sampler#add` / `get` / `has?`
+
+## Installation
+
+```bash
+bundle add deftones
+```
+
+For realtime output on macOS:
+
+```bash
+brew install portaudio
+```
+
+For development in this repository:
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec yard doc
+```
+
+## Quick Start
+
+### Offline synth render
+
+```ruby
+require "deftones"
+
+Deftones.render_to_file("output.wav", duration: 1.0) do |context|
+  synth = Deftones::Synth.new(context: context, type: :sawtooth).to_output
+  synth.play("C4", duration: "8n", at: 0.0)
+  synth.play("E4", duration: "8n", at: "4n")
+  synth.play("G4", duration: "8n", at: "2n")
+end
+
+Deftones.render_to_file("output.mp3", duration: 1.0) do |context|
+  Deftones::Synth.new(context: context).to_output.play("A4", duration: "4n")
+end
+```
+
+### Transport + sequence
+
+```ruby
+require "deftones"
+
+context = Deftones::OfflineContext.new(duration: 1.0)
+synth = Deftones::MonoSynth.new(context: context).to_output
+
+Deftones.transport.bpm = 120
+Deftones::Sequence.new(notes: ["C4", "E4", "G4", "B4"], subdivision: "8n", loop: false) do |time, note|
+  synth.play(note, duration: "16n", at: time)
+end.start(0)
+
+context.render.save("sequence.wav")
+```
+
+### Sample playback
+
+```ruby
+require "deftones"
+
+context = Deftones::OfflineContext.new(duration: 0.5)
+player = Deftones::Player.new(buffer: "kick.wav", context: context)
+player >> context.output
+player.start(0.0)
+context.render.save("player.wav")
+```
+
+### Buffer collections and MIDI output
+
+```ruby
+require "deftones"
+
+buffers = Deftones::Buffers.new(kick: "kick.wav", snare: "snare.ogg")
+Deftones::Midi.note_on("C4", velocity: 100, device: "IAC Driver Bus 1")
+```
+
+### Realtime context and live input
+
+```ruby
+require "deftones"
+
+mic = Deftones::UserMedia.new(live: true).to_output.start
+sleep 2
+mic.stop
+```
+
+### Compatibility helpers
+
+```ruby
+require "deftones"
+
+Deftones.start(use_realtime: false)
+Deftones.destination.volume.value = -6
+
+clock = Deftones::Clock.new(frequency: 2)
+time = Deftones.time("4n")
+freq = Deftones.frequency("A4")
+
+puts [clock.nextTickTime(0.25), time.to_seconds, freq.to_hz].inspect
+```
+
+### Synced sources and modulation effects
+
+```ruby
+require "deftones"
+
+context = Deftones::OfflineContext.new(duration: 0.6, sample_rate: 100)
+source = Deftones::Oscillator.new(frequency: 5, context: context).sync
+effect = Deftones::Tremolo.new(frequency: 5, depth: 1.0, context: context).sync
+
+Deftones.transport.bpm = 120
+source >> effect >> context.output
+source.start("8n")
+effect.start("8n")
+source.stop("4n")
+effect.stop("4n")
+
+context.render.save("synced.wav")
+```
+
+## Main API Surface
+
+### Core and globals
+
+`Context`, `OfflineContext`, `BaseContext`, `AudioNode`, `ToneAudioNode`, `Gain`, `Param`, `Signal`, `SyncedSignal`, `Emitter`, `Clock`, `Delay`, `Destination`, `Draw`, `Listener`
+
+Top-level helpers include `start`, `loaded`, `supported`, `getContext`, `setContext`, `getDestination`, `getDraw`, `getListener`, `getTransport`, `connect`, `disconnect`, `connectSeries`, `connectSignal`, `fanIn`, `dbToGain`, `gainToDb`, `intervalToFrequencyRatio`, `frequency`, `midi`, `time`, `ticks`, and `transportTime`.
+
+Every `AudioNode` also exposes shared helpers such as `toDestination`, `toMaster`, `toSeconds`, `toTicks`, `toFrequency`, `toMidi`, `set`, `get`, and `toString`.
+
+`Signal` and `Param` expose automation helpers including `setValueCurveAtTime`, `setTargetAtTime`, `linearRampToValueAtTime`, `exponentialRampToValueAtTime`, `cancelAndHoldAtTime`, `targetRampTo`, and `getValueAtTime`.
+
+### Sources
+
+`Oscillator`, `Noise`, `UserMedia`, `PulseOscillator`, `FMOscillator`, `AMOscillator`, `FatOscillator`, `PWMOscillator`, `OmniOscillator`, `Player`, `Players`, `GrainPlayer`, `ToneBufferSource`, `ToneOscillatorNode`
+
+### Instruments
+
+`Synth`, `MonoSynth`, `FMSynth`, `AMSynth`, `DuoSynth`, `NoiseSynth`, `PluckSynth`, `MembraneSynth`, `MetalSynth`, `PolySynth`, `Sampler`
+
+Common helpers include `volume`, `mute`, `set`, `get`, `triggerAttack`, `triggerRelease`, and `triggerAttackRelease`.
+
+### Effects and Dynamics
+
+`Distortion`, `BitCrusher`, `Chebyshev`, `FeedbackDelay`, `PingPongDelay`, `Reverb`, `Freeverb`, `JCReverb`, `Chorus`, `Phaser`, `Tremolo`, `Vibrato`, `AutoFilter`, `AutoPanner`, `AutoWah`, `FrequencyShifter`, `PitchShift`, `StereoWidener`, `Filter`, `EQ3`, `Compressor`, `Limiter`, `Gate`
+
+LFO-based effects also support `start`, `stop`, `restart`, `state`, `sync`, and `unsync`.
+
+### Scheduling
+
+`Transport`, `ToneEvent`, `Loop`, `Part`, `Sequence`, `Pattern`
+
+### Analysis and Utilities
+
+`Analyser`, `Meter`, `FFT`, `Waveform`, `DCMeter`, `Volume`, `Panner`, `Panner3D`, `PanVol`, `Solo`, `Channel`, `CrossFade`, `Merge`, `Split`, `Param`, `Buffer`, `Buffers`, `ToneAudioBuffer`, `ToneAudioBuffers`, `Recorder`, `Note`, `Frequency`, `Time`, `Ticks`, `TransportTime`, `Midi`
+
+Alias constants matching the docs are also available: `FrequencyClass`, `MidiClass`, `TimeClass`, `TicksClass`, and `TransportTimeClass`.
+
+## Examples
+
+Runnable examples live in [`examples/`](examples).
+
+Release history lives in [`CHANGELOG.md`](CHANGELOG.md).
+
+## Notes
+
+- Offline rendering is the most stable path and is fully covered by specs.
+- The default realtime context starts lazily when you connect to output.
+- Realtime output and `UserMedia.new(live: true)` use the `portaudio` gem when available.
+- WAV I/O uses the `wavify` gem, and MP3/OGG loading falls back to `ffmpeg` when installed.
+- `render_to_file` and `Buffer#save` can export WAV, MP3, and OGG when an encoder backend is installed.
+- MIDI device discovery and I/O wrappers use `unimidi` when available.
+- Unit-style classes map to Ruby wrappers where possible; `Frequency`, `Time`, `Ticks`, and `TransportTime` are available directly, while `Midi` also keeps device I/O class methods.
+- Unit wrappers expose conversion helpers such as `toNotation`, `toMilliseconds`, `toSamples`, `transpose`, `harmonize`, `quantize`, `dispose`, and `toString`.
+
+## License
+
+Released under the MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/poly_chord.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "deftones"
+
+Deftones.render_to_file("poly_chord.wav", duration: 0.75) do |context|
+  synth = Deftones::PolySynth.new(
+    Deftones::Synth,
+    voices: 4,
+    context: context
+  ).to_output
+
+  synth.play(%w[C4 E4 G4 B4], duration: 0.2, at: 0.0)
+  synth.play(%w[A3 C4 E4 G4], duration: 0.2, at: 0.25)
+end

data/examples/render_sampler.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "deftones"
+
+sample_rate = 44_100
+transient = Array.new((sample_rate * 0.25).to_i) do |index|
+  time = index.to_f / sample_rate
+  envelope = Math.exp(-12 * time)
+  Math.sin(2.0 * Math::PI * 110 * time) * envelope
+end
+sample = Deftones::Buffer.from_mono(transient, sample_rate: sample_rate)
+
+Deftones.render_to_file("render_sampler.wav", duration: 1.0) do |context|
+  sampler = Deftones::Sampler.new(samples: { "C4" => sample }, context: context).to_output
+  sampler.play(%w[C4 E4 G4], duration: 0.2, at: 0.0)
+end

data/examples/render_sequence.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "deftones"
+
+context = Deftones::OfflineContext.new(duration: 1.0)
+synth = Deftones::MonoSynth.new(context: context, type: :sawtooth).to_output
+
+Deftones.transport.bpm = 120
+Deftones::Sequence.new(notes: ["C4", "E4", "G4", "B4"], subdivision: "8n", loop: false) do |time, note|
+  synth.play(note, duration: "16n", at: time)
+end.start(0)
+
+context.render.save("render_sequence.wav")

data/examples/render_synth.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "deftones"
+
+Deftones.render_to_file("render_synth.wav", duration: 1.0) do |context|
+  synth = Deftones::Synth.new(
+    context: context,
+    type: :sawtooth,
+    attack: 0.01,
+    decay: 0.08,
+    sustain: 0.35,
+    release: 0.2
+  ).to_output
+
+  synth.play("C4", duration: "8n", at: 0.0)
+  synth.play("E4", duration: "8n", at: "4n")
+  synth.play("G4", duration: "8n", at: "2n")
+end

data/lib/deftones/analysis/analyser.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Deftones
+  module Analysis
+    class Analyser < Core::AudioNode
+      TYPES = %i[fft waveform].freeze
+      RETURN_TYPES = %i[float byte].freeze
+
+      attr_reader :size, :type, :return_type, :min_decibels, :max_decibels
+      attr_accessor :normal_range
+
+      def initialize(size: 1024, type: :fft, return_type: :float, smoothing: 0.8,
+                     normal_range: false, min_decibels: -100.0, max_decibels: 0.0,
+                     context: Deftones.context)
+        super(context: context)
+        @type = normalize_type(type)
+        @return_type = normalize_return_type(return_type)
+        @normal_range = !!normal_range
+        @min_decibels = min_decibels.to_f
+        @max_decibels = max_decibels.to_f
+        self.smoothing = smoothing
+        self.size = size
+      end
+
+      def waveform
+        Waveform::Snapshot.new(@recent_samples.dup)
+      end
+
+      def fft
+        FFT.magnitudes(@recent_samples)
+      end
+
+      def size=(value)
+        @size = [value.to_i, 1].max
+        recent = @recent_samples || []
+        padding = [@size - recent.length, 0].max
+        @recent_samples = Array.new(padding, 0.0) + recent.last(@size)
+        @smoothed_waveform = @recent_samples.dup
+        @smoothed_fft = FFT.decibels(@recent_samples, floor: @min_decibels)
+      end
+
+      def type=(value)
+        @type = normalize_type(value)
+      end
+
+      def return_type=(value)
+        @return_type = normalize_return_type(value)
+      end
+
+      def smoothing
+        @smoothing
+      end
+
+      def smoothing=(value)
+        @smoothing = Deftones::DSP::Helpers.clamp(value.to_f, 0.0, 1.0)
+      end
+
+      def min_decibels=(value)
+        @min_decibels = value.to_f
+        @smoothed_fft = FFT.decibels(@recent_samples, floor: @min_decibels)
+      end
+
+      def max_decibels=(value)
+        @max_decibels = value.to_f
+      end
+
+      def get_value
+        if @type == :waveform
+          format_waveform_values(@smoothed_waveform)
+        else
+          format_fft_values(@smoothed_fft)
+        end
+      end
+
+      def multichannel_process?
+        true
+      end
+
+      def process(input_block, num_frames, _start_frame, _cache)
+        analysed = input_block.mono.first(num_frames)
+        @recent_samples.concat(analysed)
+        @recent_samples = @recent_samples.last(@size)
+        @smoothed_waveform = smooth_values(@smoothed_waveform, @recent_samples)
+        @smoothed_fft = smooth_values(@smoothed_fft, FFT.decibels(@recent_samples, floor: @min_decibels))
+        input_block
+      end
+
+      alias getValue get_value
+      alias returnType return_type
+      alias normalRange normal_range
+      alias minDecibels min_decibels
+      alias maxDecibels max_decibels
+
+      def returnType=(value)
+        self.return_type = value
+      end
+
+      def normalRange=(value)
+        self.normal_range = value
+      end
+
+      def minDecibels=(value)
+        self.min_decibels = value
+      end
+
+      def maxDecibels=(value)
+        self.max_decibels = value
+      end
+
+      private
+
+      def normalize_type(value)
+        normalized = value.to_s.downcase.to_sym
+        raise ArgumentError, "Unsupported analyser type: #{value}" unless TYPES.include?(normalized)
+
+        normalized
+      end
+
+      def normalize_return_type(value)
+        normalized = value.to_s.downcase.to_sym
+        raise ArgumentError, "Unsupported analyser return type: #{value}" unless RETURN_TYPES.include?(normalized)
+
+        normalized
+      end
+
+      def smooth_values(previous, current)
+        return current.dup if @smoothing.zero?
+
+        previous.zip(current).map do |prior, sample|
+          (prior.to_f * @smoothing) + (sample.to_f * (1.0 - @smoothing))
+        end
+      end
+
+      def format_waveform_values(values)
+        if @return_type == :byte
+          values.map { |sample| (((Deftones::DSP::Helpers.clamp(sample, -1.0, 1.0) + 1.0) * 0.5) * 255.0).round }
+        elsif @normal_range
+          values.map { |sample| Deftones::DSP::Helpers.clamp((sample + 1.0) * 0.5, 0.0, 1.0) }
+        else
+          values.map { |sample| Deftones::DSP::Helpers.clamp(sample, -1.0, 1.0) }
+        end
+      end
+
+      def format_fft_values(values)
+        return values.map { |value| scale_to_byte_range(value) } if @return_type == :byte
+        return values.map { |value| scale_to_normal_range(value) } if @normal_range
+
+        values.map { |value| Deftones::DSP::Helpers.clamp(value, @min_decibels, @max_decibels) }
+      end
+
+      def scale_to_normal_range(value)
+        return 0.0 if @max_decibels <= @min_decibels
+
+        Deftones::DSP::Helpers.clamp((value - @min_decibels) / (@max_decibels - @min_decibels), 0.0, 1.0)
+      end
+
+      def scale_to_byte_range(value)
+        (scale_to_normal_range(value) * 255.0).round
+      end
+    end
+  end
+end

data/lib/deftones/analysis/dc_meter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Deftones
+  module Analysis
+    class DCMeter < Core::AudioNode
+      def initialize(smoothing: 0.8, channels: 1, context: Deftones.context)
+        super(context: context)
+        @channels = [channels.to_i, 1].max
+        @offsets = Array.new(@channels, 0.0)
+        self.smoothing = smoothing
+      end
+
+      def offset
+        @offsets.length == 1 ? @offsets.first : @offsets.dup
+      end
+
+      def smoothing
+        @smoothing
+      end
+
+      def smoothing=(value)
+        @smoothing = Deftones::DSP::Helpers.clamp(value.to_f, 0.0, 1.0)
+      end
+
+      def get_value
+        @offsets.length == 1 ? @offsets.first : @offsets.dup
+      end
+
+      def multichannel_process?
+        true
+      end
+
+      def process(input_block, num_frames, _start_frame, _cache)
+        analysis_block = input_block.fit_channels(@channels)
+
+        @channels.times do |channel_index|
+          segment = analysis_block.channel_data[channel_index].first(num_frames)
+          instantaneous_offset = segment.sum / [segment.length, 1].max
+          @offsets[channel_index] = smooth(@offsets[channel_index], instantaneous_offset)
+        end
+
+        input_block
+      end
+
+      alias getValue get_value
+
+      private
+
+      def smooth(previous, current)
+        return current if @smoothing.zero?
+
+        (previous.to_f * @smoothing) + (current.to_f * (1.0 - @smoothing))
+      end
+    end
+  end
+end

data/lib/deftones/analysis/fft.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Deftones
+  module Analysis
+    class FFT < Core::AudioNode
+      def self.magnitudes(samples)
+        size = samples.length
+        half = size / 2
+
+        Array.new(half) do |bin|
+          real = 0.0
+          imaginary = 0.0
+
+          samples.each_with_index do |sample, index|
+            angle = (2.0 * Math::PI * bin * index) / size
+            real += sample * Math.cos(angle)
+            imaginary -= sample * Math.sin(angle)
+          end
+
+          Math.sqrt((real * real) + (imaginary * imaginary)) / [size, 1].max
+        end
+      end
+
+      def self.decibels(samples, floor: -100.0)
+        magnitudes(samples).map do |magnitude|
+          [Deftones.gain_to_db([magnitude, 1.0e-12].max), floor.to_f].max
+        end
+      end
+
+      def initialize(size: 1024, smoothing: 0.8, return_type: :float, normal_range: false,
+                     min_decibels: -100.0, max_decibels: 0.0, context: Deftones.context)
+        super(context: context)
+        @delegate = Analysis::Analyser.new(
+          size: size,
+          type: :fft,
+          smoothing: smoothing,
+          return_type: return_type,
+          normal_range: normal_range,
+          min_decibels: min_decibels,
+          max_decibels: max_decibels,
+          context: context
+        )
+      end
+
+      def size
+        @delegate.size
+      end
+
+      def size=(value)
+        @delegate.size = value
+      end
+
+      def smoothing
+        @delegate.smoothing
+      end
+
+      def smoothing=(value)
+        @delegate.smoothing = value
+      end
+
+      def return_type
+        @delegate.return_type
+      end
+
+      def return_type=(value)
+        @delegate.return_type = value
+      end
+
+      def normal_range
+        @delegate.normal_range
+      end
+
+      def normal_range=(value)
+        @delegate.normal_range = value
+      end
+
+      def min_decibels
+        @delegate.min_decibels
+      end
+
+      def min_decibels=(value)
+        @delegate.min_decibels = value
+      end
+
+      def max_decibels
+        @delegate.max_decibels
+      end
+
+      def max_decibels=(value)
+        @delegate.max_decibels = value
+      end
+
+      def get_value
+        @delegate.get_value
+      end
+
+      alias getValue get_value
+      alias returnType return_type
+      alias normalRange normal_range
+      alias minDecibels min_decibels
+      alias maxDecibels max_decibels
+
+      def returnType=(value)
+        self.return_type = value
+      end
+
+      def normalRange=(value)
+        self.normal_range = value
+      end
+
+      def minDecibels=(value)
+        self.min_decibels = value
+      end
+
+      def maxDecibels=(value)
+        self.max_decibels = value
+      end
+
+      def process(input_buffer, num_frames, start_frame, cache)
+        @delegate.process(input_buffer, num_frames, start_frame, cache)
+      end
+
+      def multichannel_process?
+        true
+      end
+    end
+  end
+end