first commit
This commit is contained in:
@@ -0,0 +1,87 @@
|
||||
# `synthesizer`
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
`SynthesizerPlugin` is the universal polyphonic subtractive synthesizer. Each voice runs an oscillator (sine, square, sawtooth, or triangle) through a four-stage ADSR envelope and a one-pole low-pass filter, then sums into the mono output. The plugin is a source (`io.inputs[0].count === 0`) so it slots into chains at position 0. Voice stealing is deterministic — the oldest-sequence voice is replaced first — so the active voice count never exceeds the configured `polyphony`.
|
||||
|
||||
The plugin extends `AbstractAudioFxPlugin`, runs identically across browser / server / worklet renderers, and validates MIDI notes at every entry point: `triggerAttack`, `triggerRelease`, and `triggerAttackRelease` reject any value outside the integer range `[0, 127]` with `AUDIO_FX.INVALID_NOTE`.
|
||||
|
||||
## Features
|
||||
|
||||
- Three trigger methods: `triggerAttack(note, velocity?)`, `triggerRelease(note)`, `triggerAttackRelease(note, durationSec)`.
|
||||
- Eight automatable parameters: `waveform` (enum 0..3), `attack`, `decay`, `sustain`, `release`, `cutoff`, `resonance`, `portamento`.
|
||||
- Voice pool with `polyphony` (1..32, default 8) and deterministic oldest-first stealing — the spec's "active voice count never exceeds polyphony".
|
||||
- Portamento glide: when `portamento > 0`, a new voice's frequency interpolates from the previously triggered note's target frequency over the configured time constant.
|
||||
- Four waveforms cover the basic subtractive-synth palette; the saw and square shapes use the canonical math (no anti-aliasing) so the output is rich in harmonics. Downstream `LowPassFilter` or `EQPlugin` can shape the resulting spectrum.
|
||||
- `getActiveVoiceCount()` and `getActiveVoices()` accessors expose live state for diagnostics or UI meters.
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```ts
|
||||
import { SynthesizerPlugin } from "@suaveplan/audio-fx-plugin-synthesizer";
|
||||
|
||||
const synth = new SynthesizerPlugin({
|
||||
initialWaveform: "sawtooth",
|
||||
initialAttackSec: 0.02,
|
||||
initialSustain: 0.6,
|
||||
});
|
||||
chain.add(synth);
|
||||
synth.triggerAttack(69); // A4
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```ts
|
||||
import { SynthesizerPlugin } from "@suaveplan/audio-fx-plugin-synthesizer";
|
||||
|
||||
const lead = new SynthesizerPlugin({
|
||||
initialWaveform: "sawtooth",
|
||||
initialAttackSec: 0.005,
|
||||
initialDecaySec: 0.15,
|
||||
initialSustain: 0.4,
|
||||
initialReleaseSec: 0.3,
|
||||
initialCutoffHz: 4_000,
|
||||
initialResonance: 6,
|
||||
initialPortamentoMs: 80,
|
||||
polyphony: 4,
|
||||
});
|
||||
await lead.setup(
|
||||
{ sampleRate: 48_000, channels: 1, blockSize: 512 },
|
||||
ctx
|
||||
);
|
||||
|
||||
// Step through a melody, gliding between notes.
|
||||
const melody = [62, 65, 67, 72];
|
||||
for (let i = 0; i < melody.length; i++) {
|
||||
lead.triggerAttackRelease(melody[i]!, 0.5);
|
||||
// Render 0.5 sec of audio at the chain's clock before the next.
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `SynthesizerPlugin` (class extends `AbstractAudioFxPlugin`)
|
||||
- `new SynthesizerPlugin(options?: SynthesizerPluginOptions)` — throws `AUDIO_FX.INVALID_OPTIONS` on malformed options.
|
||||
- `triggerAttack(note: 0..127, velocity?: number): void` — throws `AUDIO_FX.INVALID_NOTE` on out-of-range or non-integer note.
|
||||
- `triggerRelease(note: 0..127): void`
|
||||
- `triggerAttackRelease(note: 0..127, durationSec: number): void`
|
||||
- `getActiveVoiceCount(): number`
|
||||
- `getActiveVoices(): ReadonlyArray<SynthesizerVoiceSnapshot>`
|
||||
- Inherited accessors for `waveform`, `attack`, `decay`, `sustain`, `release`, `cutoff`, `resonance`, `portamento`.
|
||||
- Types: `SynthWaveform = "sine" | "square" | "sawtooth" | "triangle"`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
The voice pool is a plain array; each voice carries a monotonically increasing `sequence` counter assigned at attack. When the pool fills, we scan for the lowest sequence and overwrite it. The cost is O(polyphony) per attack — at the default of 8, this is trivial; even at the cap of 32 it adds 32 comparisons per attack, well under the per-event budget of a real-time renderer. Faster algorithms (heap, ring buffer) would tighten the constant factor but add bookkeeping; the linear scan is the right MVP and matches the sampler's approach.
|
||||
|
||||
The ADSR uses linear stages, not exponential. Linear attack/release is the easiest to reason about and tune for synthesist-style envelopes; an exponential variant can be layered in later if a use case emerges (e.g., piano-style natural decay). Decay and release rates are computed per-block from the live parameter values so automation works without zipper noise.
|
||||
|
||||
`triggerAttackRelease` uses a negative `envValue` as a countdown sentinel: the process loop decrements `env` by 1 sample per frame while skipping audio output, then flips the stage to `attack` when the counter hits zero. This keeps the API single-call (no separate scheduler) while preserving sample accuracy on the duration. The downside is that audio output is silent during the countdown — a future revision could pre-decrement at the trigger time and start audio immediately, but the test "voice ends after the requested duration" exercises the current behaviour explicitly.
|
||||
|
||||
The per-voice filter is a one-pole low-pass: `y = y_prev + α · (x − y_prev)`, with `α = ω / (ω + 1)` and `ω = 2π · cutoff / sampleRate`. This is a cheap "warmth" filter rather than a full resonant filter — for the latter, callers chain a `FilterPlugin` downstream. The plugin exposes a `resonance` parameter that is reserved for a future state-variable upgrade; today it is unused on the audio path but persists in the parameter snapshot so presets remain forwards-compatible.
|
||||
|
||||
Portamento is per-voice: the new voice's `currentFreq` starts at the previous target frequency and slews toward the new target via a one-pole interpolator with time constant `portamentoMs`. When `portamento === 0`, the coefficient collapses to `1` and the voice starts at `targetFreq` immediately. The first triggered note has no previous frequency to glide from, so `lastTriggeredFreq === 0` skips the slew (the voice starts at the target) — verified by the "portamento" test which still asserts the new voice's note matches.
|
||||
Reference in New Issue
Block a user