@maruaudio/dsp/voices/polyphonic-pool decides which voice slot a note owns, deterministically: same-note retrigger first, then the lowest free slot, then the oldest active slot. It marks releases, retires slots and counts active and held voices. DSP state belongs to the composing instrument. The identified variants match on a note identity instead of pitch, so two simultaneous notes at the same pitch take separate slots and release independently.
Parameters
| Call | Coded range and behavior |
|---|---|
initPolyphonicVoicePool(capacity) | Capacity bounded to 1..16 (boundedPolyphonicCapacity: non-positive or NaN gives 1, then floor); default 8 (POLYPHONIC_MAX_VOICES) |
allocatePolyphonicVoice(pool, note) | Note clamped to 0..127 and rounded; returns the slot |
allocateIdentifiedPolyphonicVoice(pool, note, noteId) | noteId < 0 means none (POLYPHONIC_NO_NOTE_ID −1), else rounded |
releasePolyphonicVoice(pool, note) | Note rounded, not clamped; marks the first active slot with that note; returns it or −1 |
releaseIdentifiedPolyphonicVoice, findPolyphonicVoiceByNoteId | Match by identity, ignoring pitch; −1 when not found |
retirePolyphonicVoice(pool, slot) | Ignores slots outside 0..capacity−1 |
Lifecycle
Init allocates five arrays at the compile-time ceiling of 16 and resets them → allocate on note-on, release on note-off, retire when the owner's tail reaches idle → resetPolyphonicVoicePool clears every slot and restarts ages at 1. Nothing is allocated after init.
When to use it
A polyphonic synth or struck instrument where pressing a sounding key again should restart that voice rather than add one, and where a full pool steals the oldest note. Use the identified calls for MPE input. For a pool that steals by start serial without same-note retrigger, see @maru/voices-serial-voice-pool.
Limits
- At most 16 voices; every loop counts to that ceiling and breaks at
capacity. - Ages are stored in a
Float32Array. - A legacy (pitch-only) note-on never retriggers an identified voice, but it can still steal one as the oldest slot when the pool is full.
- No audio output.