# voice-pool

> Note players: what a MIDI track plays through, all taking notes the same way, and the voice pool that plays an instrument of the library with a voice for each note it holds, the oldest given up first.

```bash
npx shadcn@latest add @audio-ui/voice-pool
```

```ts
import { noteParameters, createVoicePool } from "@/lib/voice-pool";
```

- Files: `lib/voice-pool.ts`
- Depends on: `device-library`, `polyphony`; npm: `@audio-ui/engine`
- Used by: `arrangement-engine`, `drum-rack`, `instrument-rack`

| Export | Kind | What it is |
| --- | --- | --- |
| `PlayedNote` | interface | A note to play: its pitch and velocity, 0 to 1, and the instrument's own note parameters it sets over them, such as a pad's frequency and cutoff. |
| `NotePlayer` | interface | What plays a MIDI track's notes, at times of the audio clock in seconds, each note by an id its note off names. |
| `noteParameters` | function | The note parameters an instrument is given for `note`: its defaults, the pitch's frequency, the velocity, then the note's own. |
| `VoicePool` | interface | An instrument played by a pool of voices: what `update` changes in all of them. |
| `createVoicePool` | function | An instrument of the library played with `count` voices into `output`, one note each: a new note takes a free voice, or the one held longest. |

## Usage

What a MIDI track plays through: an instrument of the [device library](/docs/lib/device-library) with a voice for each note it holds ([`createPolyphony`](/docs/lib/polyphony)), or the one engine of a mono instrument, which glides from note to note. Every player takes notes the same way, by pitch and velocity, at times of the audio clock, each by an id its note off gives again.

```ts
import { libraryDevice } from "@/lib/device-library";
import { createVoicePool } from "@/lib/voice-pool";

const entry = libraryDevice("audioui.poly-synth");
if (entry) {
  const player = createVoicePool(ctx, entry, entry.device.defaults(), { tempo }, 8, output);
  await player.ready();
  player.noteOn({ pitch: 60, velocity: 0.8 }, time, "c4");
  player.noteOff(time + 0.5, "c4");
}
```

`noteParameters` turns a played note into what the instrument's `noteOn` takes: its note defaults, the pitch's frequency, the velocity, then the note's own parameters (a pad's tune or cutoff).