# Polyphonic instrument

> Eight owned, velocity-sensitive oscillator voices with ADSR, sustain and MPE, played from a MIDI cable in the Toy's tuning.

Source: https://docs.tune.toys/nodes/std.poly/

A ready-made eight-voice instrument. It has no audio input: it makes sound when it receives notes from a Frame piano, the computer keyboard or MIDI, and sends a stereo signal out.

## What it does

Each note takes one of eight voices. A voice is an oscillator with its own attack, decay, sustain and release, so overlapping notes keep their own envelopes. The instrument responds to note velocity and to the sustain pedal. Level is shared across the voices: each voice receives one eighth of it, so playing eight notes together has fixed headroom.

It does not take an audio input or modulation cables. Effects go after it on the output cable.

### Pitch and tuning

The keys play the Toy's `tuning`: a preset such as 31-EDO or just intonation, or a custom table of cents. Without one the Toy plays 12-TET with A4 at 440 Hz, and note 69 is A4.

- **Equal divisions of the octave** (12-TET, 19-, 22-, 24-, 31- and 53-EDO): middle C (MIDI 60) is degree 0, each key up is one step, and A4 stays at the reference on the degree three of the division's own fifths above C. In 31-EDO, C4 to C5 spans 31 keys.
- **Just, Pythagorean, Bohlen–Pierce and custom tables**: MIDI 60 plus Root plays the root at its 12-TET pitch from the reference, and each key up is the next degree, repeating at the period (an octave, or a tritave for Bohlen–Pierce).

The engine maps all 128 notes once when the Toy is prepared, so a note-on only reads a table. Pitch bend is ±2 semitones, except on MPE member channels (below). The tuning is set in the Toy's source, for example `"tuning": { "preset": "31-edo", "root": 0, "reference": 440 }`; the Thirty-One Keys example Toy plays that one. A [Tuner](https://docs.tune.toys/nodes/std.tuner/) left on Toy tuning measures against the same degrees.

### Voices and stealing

A note takes the voice already playing that key from the same source and channel, else a silent voice, else the oldest released voice, else the oldest held one. A stolen voice crossfades to its new note over 32 samples. Each MIDI source (a Frame piano, the computer keyboard, each MIDI device) owns its own notes and sustain pedal per channel, so one source releasing a key never silences another's.

### MPE

With MPE set to Lower zone (master channel 1, members 2–16) or Upper zone (master channel 16, members 1–15), each note arrives on its own member channel. That channel's pitch bend then moves only the voice holding its note, by up to MPE bend semitones; master-channel bend still moves every voice by ±2 semitones, and the two add. Pressure and CC74 have no target in this instrument; build a [polyphonic group](https://docs.tune.toys/concepts/voices/) to route them per voice. MPE configuration messages (MCM) and MIDI-CI are not handled: set the zone here to match the controller.

## When to use it

Use it when you want something playable with a few controls and no wiring: a starting point for keyboards, pads and plucks. Reach for [Oscillator](https://docs.tune.toys/nodes/std.oscillator/) with an [Envelope](https://docs.tune.toys/nodes/std.envelope/) when you need a single voice you can wire and modulate yourself, and give its group [voices](https://docs.tune.toys/concepts/voices/) to play chords with it.

## Ports

<!-- ports:start -->

| Port    | Direction | Signal | Lanes                   |
| ------- | --------- | ------ | ----------------------- |
| `midi`  | Input     | MIDI   | 16 MIDI channels        |
| `audio` | Output    | Audio  | Inferred from the cable |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter     | Label       | Range        | Default | Unit  | Scale  | Notes                                                                                                                                                                         |
| ------------- | ----------- | ------------ | ------- | ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amplitude`   | Level       | 0 to 0.5     | 0.3     |       | linear | Master level. Each of the eight voices receives one eighth of this level for fixed headroom.                                                                                  |
| `shape`       | Shape       | 0 to 3       | 0       |       | linear | Continuous sine, triangle, saw and pulse morph using the shared wave oscillator.                                                                                              |
| `attack_ms`   | Attack      | 0 to 10000   | 5       | ms    | linear | Voice attack time.                                                                                                                                                            |
| `decay_ms`    | Decay       | 0 to 10000   | 120     | ms    | linear | Voice decay time.                                                                                                                                                             |
| `sustain`     | Sustain     | 0 to 1       | 0.7     | %     | linear | Held voice envelope level. Stored as a fraction; shown ×100 as a percentage.                                                                                                  |
| `release_ms`  | Release     | 0 to 10000   | 200     | ms    | linear | Voice release after note-off or sustain release.                                                                                                                              |
| `detune`      | Fine tune   | -100 to 100  | 0       | cents | linear | Moves every note by this many cents from the Toy's tuning, for this instrument only. 0 plays the tuning as written.                                                           |
| `pulse_width` | Pulse width | 0.05 to 0.95 | 0.5     |       | linear | Pulse duty cycle.                                                                                                                                                             |
| `mpe`         | MPE         | 0 to 2       | 0       |       | linear | In a zone, a member channel's pitch bend moves only the voice holding that channel's note; master-channel bend moves every voice. Choices: 0 Off, 1 Lower zone, 2 Upper zone. |
| `mpe_bend`    | MPE bend    | 0 to 96      | 48      | st    | linear | Semitones a full member-channel pitch bend moves its note in an MPE zone.                                                                                                     |

<!-- parameters:end -->

### Level (`amplitude`)

Master level of the instrument. Because each voice gets one eighth, raising it never makes a full chord clip on its own.

### Shape (`shape`)

A continuous morph: 0 is sine, 1 is triangle, 2 is saw and 3 is pulse. Values between blend neighboring waves.

### Attack (`attack_ms`), Decay (`decay_ms`), Sustain (`sustain`), Release (`release_ms`)

The per-voice envelope. Attack, Decay and Release are times in milliseconds. Sustain is the level, shown from 0 to 100 %, that a held key stays at after the decay. Release starts at note-off, or when the sustain pedal is let go.

### Fine tune (`detune`)

Moves every note of this instrument by up to 100 cents either way from the Toy's tuning; 0 plays the tuning as written. Two instruments a few cents apart thicken a sound. The tuning itself, including the A4 reference, belongs to the Toy (see [Pitch and tuning](#pitch-and-tuning)).

### Pulse width (`pulse_width`)

The duty cycle of the pulse wave, from 0.05 to 0.95. It affects the sound near the pulse end of Shape.

### MPE (`mpe`)

Off treats every channel alike. Lower zone and Upper zone make channel 1 or channel 16 the master and the other fifteen member channels, one per sounding note (see [MPE](#mpe)).

### MPE bend (`mpe_bend`)

How far a full pitch bend on a member channel moves its note, 0 to 96 semitones each way; 48 is the MPE default most controllers send. It applies only while MPE is on.

## Tips

- Short Attack and Release sound plucked; long ones sound like a pad.
- Sustain of 0 makes a note die away after the decay even while the key is held.
- Add [Reverb](https://docs.tune.toys/nodes/std.reverb/) after the instrument for space.
- Frame pianos and MIDI both reach the instrument. See [MIDI](https://docs.tune.toys/concepts/midi/).
- To hear a microtonal scale, give the Toy a `tuning` and play neighbouring keys: each is one degree.

## See also

[Oscillator](https://docs.tune.toys/nodes/std.oscillator/), [Envelope](https://docs.tune.toys/nodes/std.envelope/), [Reverb](https://docs.tune.toys/nodes/std.reverb/), [Tuner](https://docs.tune.toys/nodes/std.tuner/), [Frames](https://docs.tune.toys/concepts/frames/), [Voices](https://docs.tune.toys/concepts/voices/).