# Tonic AP — Sound Authoring Kit
*Generated from the running parameter list of Tonic AP 1.2.0 on 29 Oct 2026. Do not edit by hand:
`python3 ios/tools/gerar-kit-timbres.py` rebuilds it.*
> **Kit revision `98661d7d49b3`** — 191 parameters. Two kits can carry the same app version and still
> differ; this line, not the version, is what tells you whether to fetch again. The same string is in
> `patch-kit.json`, in `revision`.
>
> **Machine-readable twin:** [`patch-kit.json`](patch-kit.json) carries the whole table as data — identifier,
> address, range, default, unit and every option — so a sound can be checked before it ever reaches the app.
This is everything an assistant — any assistant — needs to read, edit and write Tonic AP sounds that open in the
app and actually sound like something. It is plain text on purpose: no tooling, no account, no API.
Tonic AP is an acoustic piano built **entirely by physical modelling**: there are no recordings inside, not even
for the noises of the action. A sound is a set of numbers that says how the piano is built (a grand or an
upright, how big, which soundboard wood), how its hammers are voiced, what state it is in, where you listen from
(microphones or your own two ears), the room around it and the effects after it. Change the numbers and you
change the instrument.
---
## 1 · The six rules
**1. Start from a sound the app gave you.** In the library, touch and hold a sound (right-click on the Mac):
*Export Sound…* gives you a `.tap` file, and *Copy Sound* puts the same sound on the clipboard as
text, with every control spelled out. Edit that. A sound carries more than knobs — six scenes, the pitch-bend
range, what the mod wheel moves, its MIDI filter, and the per-key regulation of the Note Edit — and a file
written from an empty page silently loses whatever it forgot. *Copy Sound* leaves the Note Edit out: for a sound
whose keys you regulated one by one, use *Export Sound…*.
**2. Keep the extension.** A sound is **`.tap`**; a bank is **`.tapbk`**; a backup of the
whole library is **`.tapall`** (`.tapmap` is a MIDI map, not a sound). The app reads by
CONTENT, not by name, so a renamed file still opens — but the extension is the only thing a person sees before
opening, and what is inside decides what the app does with it: a sound is saved as a **new** sound in your own
bank (a number is added to the name if it is already taken); a bank arrives as a **new** bank; a backup updates
the sounds that have the same name in the bank of the same name, adds the rest, and never deletes anything.
Inside, `format` is `"tonic-ap"`: the app refuses any other format, so a sound from the electric
piano or the synth of the same family does not open here, by design.
**3. Never invent an identifier.** Only the identifiers in §4 exist. An unknown key is ignored in silence: the
sound opens, looks fine, and does not sound the way you wrote it.
**4. Keep `format`, `version` and `level` exactly as they came.** A `version` above 1 is
refused as *made by a newer version*. `level` is the generation of the engine's output level that the Volume
was set in — **1** today, the only one so far. Sounds you write say `"level": 1`.
**5. A scene is a photo of the whole sound.** Each of the six scenes (A–F) is `null` (empty) or
`{"params": {…}}`. When the sound opens, anything a scene leaves out is filled with the sound's own value — so
a partial scene means *the sound, plus these differences*. That makes scenes easy to write: for a scene B with
more room and the lid at half-stick, write only those keys in it. It also works the other way: a key left out of
a scene goes back to the sound's own value when that scene is called.
**6. Values are not percentages.** Read §3 before writing numbers. It is the difference between a sound that
feels designed and one that sounds random.
---
## 2 · The file
A `.tap` is UTF-8 JSON. The envelope and one sound, as the app exports it — a factory sound with a
scene B stored on top, shortened here: a few of its parameters, and the scene cut down to what it changes from
the sound (rule 5). A sound you saved yourself carries every value, in the sound and in every scene; a factory
sound only the ones that differ from the defaults.
```json
{
"app": "Tonic AP",
"format": "tonic-ap",
"kind": "preset",
"preset": {
"author": "",
"bendDown": 2,
"bendUp": 2,
"edited": false,
"factory": false,
"factoryKey": "",
"favorite": false,
"id": "00000000-0000-4000-8000-000000000001",
"level": 1,
"mechanism": "grand",
"modAmount": 0.5,
"name": "Jazz Club Grand",
"params": {
"dynamics": 0.85,
"hardness": 0.92,
"listenMode": 1,
"mic1Azimuth": 0,
"mic1Elevation": -90,
"mic1Level": 1,
"mic1Pan": -0.7,
"mic1Pattern": 0.5
},
"scenes": [
null,
{
"params": {
"lid": 0.5,
"reverb": 0.34
}
},
null,
null,
null,
null
],
"tags": [
"jazz",
"warm"
]
},
"version": 1
}
```
| field | what it is |
|---|---|
| `name` | the sound's name. If the bank already has one with that name, the app adds a number |
| `mechanism` | `"grand"` or `"upright"` — the badge the library shows and filters by. It must agree with the `caseShape` parameter (0 = Grand, 1 = Upright), which is what actually plays. The app rewrites it from `caseShape` every time the sound is saved |
| `tags` | words the library filters by. The Tonica (the Tonic AP community) offers: Concert, Studio, Intimate, Bright, Warm, Dark, Soft, Felt, Vintage, Honky, Binaural, Mics, Classical, Jazz, Pop, Ballad, Ambient, Early Music |
| `author` | free text |
| `params` | identifier → value (§4). A parameter left out opens at its default, so a sound only needs the values that differ |
| `scenes` | six entries, `null` or `{"params": {…}}` (rule 5) |
| `lastScene` | the scene the sound opens in, 0 = A … 5 = F. Ignored when it points at an empty scene |
| `bendUp`, `bendDown` | pitch-bend range in semitones, 0–24 each (default 2) |
| `modWheel` | the identifier the mod wheel moves in this sound. Absent = the wheel moves nothing: an acoustic piano has no wheel |
| `modAmount` | how much of that control's range the wheel sweeps, 0–1 (the app offers 0.25, 0.5, 0.75, 1; default 0.5) |
| `midiFilter` | MIDI filter rules saved with the sound — best left as exported |
| `noteEdits` | the Note Edit: the regulation of single keys (see below). Absent = every key as the factory voiced it |
| `level` | rule 4 — `1` |
| `id` | any UUID. The app gives every sound a new one when it arrives |
| `factory`, `factoryKey`, `favorite`, `edited` | bookkeeping: `false`, `""`, `false`, `false`. The app clears the factory stamp on anything that arrives, so a file cannot pass itself off as a factory sound |
A bank (`"kind": "bank"`) carries `"bank": {"name": …, "presets": […]}` instead of `preset`.
### The Note Edit (`noteEdits`)
A piano technician regulates one key at a time; so can a sound. `noteEdits` maps a **MIDI note number, written
as a string** (`"21"` = A0 … `"60"` = C4 … `"108"` = C8), to the fields that differ
from the factory:
```json
"noteEdits": { "60": { "tune": 3, "volume": -1.5 }, "88": { "hardness": 0.8 } }
```
| field | range | default | what it does |
|---|---|---|---|
| `tune` | -50 → 50 ct | 0 ct | The tuning of this key alone, in cents. Nudge a note that sounds a little out against its neighbours — or detune it on purpose. |
| `volume` | -24 → 12 dB | 0 dB | The level of this key alone. Even out a note that jumps out or hides, the way a technician voices one hammer. |
| `hardness` | ×0.5 → ×2 | ×1 | The hammer of this key alone: softer for a rounder note, harder for a brighter one. It acts on the next time you play it. |
| `decay` | ×0.25 → ×4 | ×1 | How long this key keeps ringing, compared with the others. |
| `width` | ×0 → ×4 | ×1 | How far apart the strings of this key are tuned. Up, the note shimmers more; down, the unison is purer. |
| `balance` | -1 → 1 | 0 | Which string the hammer favours: centred, or leaning to the left or right string of the unison — a different colour in the beating. |
A key outside 21–108, or a field not in this table, is dropped; a value out of range is moved
to the nearest edge; a value equal to the default is simply not stored. The Note Edit is not a scene: it is the
same in all six.
---
## 3 · What the numbers mean
- **Volume** (`volume`) is a linear gain after the effects: 1 = 0 dB, 2 = +6.0 dB (the
top), 0 = silence. Balance a new sound against a factory sound you like — here, not with the effects.
- **Ratios**, shown as ×: 1 = the piano as the factory built it; below 1 is less, above 1 is more. Hardness ×2
is a harder hammer; Decay ×0.5 is a note that dies sooner.
- **Hz, dB, ms, m, mm, degrees**: real frequencies, decibels, milliseconds, metres, millimetres and angles.
Controls marked *(log)* travel logarithmically on screen: halfway between 300 Hz and 4 kHz is about 1.1 kHz,
not 2.15 kHz.
- **Options**: a whole number — the index into the list printed in §4, starting at 0. An option marked
*(hidden)* is no longer offered in the menus; it still opens, and §4 says how it plays. Do not write it.
- **Plain numbers**: an amount on the control's own scale. The range column says where it starts and ends,
and the small text under it is what the screen shows: Soundboard 0.5 shows as 50 %; Lid 0.5 as Half-stick.
- **On switches** (`eqOn`, `compOn`, `exciterOn`, `chorusOn`, `delayOn`, `reverbOn`, `limiterOn`): 0 = off,
1 = on. An effect whose switch is off does nothing, whatever its knobs say — so to hear an effect, write its
switch. The reverb is the only one that starts **on**: it is the room the piano stands in.
- **⟳ rebuilds the piano.** These controls change how the instrument is BUILT — its model, size, soundboard,
or where the mics and the listener stand. The app recalculates the piano in the background (from a moment
to a few seconds); a note that is already sounding finishes on the piano it started on. They are fine in a
sound and in a scene, but they are not for sweeping with a wheel while you play.
Every row in §4 shows, under the range, the text the musician sees at the minimum, the default and the maximum —
so a reading of a number can be checked against the screen.
---
## 4 · The controls
Grouped as the app shows them, in the order a DAW lists them. *What it does* is the app's own guided-tour note,
followed, where the tour does not give the number, by what the number does. The address is what a DAW's
automation and a MIDI map store; inside a sound, everything goes by identifier.
### The piano
#### Hammer
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `hardness` | 4 | Hammer Hardness | 0.25 → 4 *(log)*
×0.25 → ×4.00 | 1
×1.00 | How hard the hammer felt is. Soft gives a round, dark attack; hard a bright, cutting one. It acts on the next note you play — a real hammer can't change while the string rings.
×1 = the factory hammer; ×0.25 velvet, ×4 steel. |
| `dynamics` | 5 | Hammer Dynamics | 0.5 → 2
×0.50 → ×2.00 | 1
×1.00 | The distance between your softest and your loudest note. Fortissimo stays where it is: turn it down and the soft notes come up, so the piano sounds bigger and easier to hear; turn it up for a wide, classical range. The colour of each note still follows your touch. |
| `hammerNoise` | 11 | Hammer Noise | 0 → 1
0% → 100% | 0.5
50% | The knock of the hammer and the key against the keybed. In the middle it is the real amount, measured on a grand; turn it down for a polished studio piano. |
| `hardnessPiano` | 22 | Hammer Hardness pp | 0.5 → 2
×0.50 → ×2.00 | 1
×1.00 | How hard the felt is when you play softly. Down gives a velvet pianissimo; up a clearer one. |
| `hardnessForte` | 23 | Hammer Hardness ff | 0.5 → 2
×0.50 → ×2.00 | 1
×1.00 | How hard the felt is when you play loudly. Up for a fortissimo that rings like steel; down for one that stays round. |
| `strikePoint` | 24 | Hammer Strike Point | 0.8 → 1.25
×0.80 → ×1.25 | 1
×1.00 | Where the hammer hits the string. Nearer the end, the sound is brighter and thinner; further in, rounder and fuller.
Below ×1 is nearer the end of the string; above ×1, further in. |
| `voicingTilt` | 25 | Hammer Voicing Tilt | -1 → 1
-1.00 → 1.00 | 0
0.00 | Voices the whole keyboard at once: down makes the bass brighter than the treble, up the opposite.
−1 = bass harder, treble softer; +1 = treble harder, bass softer; 0 = factory. |
| `spectrum1` | 117 | Hammer Spectrum 55 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | Tone profile: raises or lowers the string harmonics that fall in this octave band, on every key, before the soundboard — the A4 band moves the 2nd harmonic of A3 and the note A4 alike. 0 = factory.
Shown in the app as the **Tone profile**; a DAW calls it *Hammer Spectrum*. One octave band per control, centred at 55 · 110 · 220 · 440 · 880 · 1760 · 3520 · 7040 Hz, −12 to +12 dB, 0 = factory. |
| `spectrum2` | 118 | Hammer Spectrum 110 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | *As above.* |
| `spectrum3` | 119 | Hammer Spectrum 220 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | *As above.* |
| `spectrum4` | 120 | Hammer Spectrum 440 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | *As above.* |
| `spectrum5` | 121 | Hammer Spectrum 880 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | *As above.* |
| `spectrum6` | 122 | Hammer Spectrum 1760 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | *As above.* |
| `spectrum7` | 123 | Hammer Spectrum 3520 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | *As above.* |
| `spectrum8` | 124 | Hammer Spectrum 7040 Hz | -12 → 12
-12.0 dB → +12.0 dB | 0
+0.0 dB | *As above.* |
| `hammerFelt` | 176 | Hammer Felt | 0 = Soft · 1 = Med · 2 = Hard · 3 = Lacq · 4 = Felt | 2 | The felt on the hammers. Soft is warm and round; Med (medium) is softer and smoother than the factory felt; Hard is the factory voicing, with more bite; Lacq (lacquered) is the hardened felt of a stage piano, the brightest.
0 = Soft — needled felt: warm and round.
1 = Med — medium: softer and smoother than the factory felt.
2 = Hard — the factory voicing: brighter, more bite.
3 = Lacq — lacquered, hardened felt: the brightest, for the stage.
4 = Felt — a strip of thick felt between the hammers and the strings: the intimate, muffled felt-piano sound, with the action right up front. |
| `strikeUneven` | 188 | Hammer Uneven Strike | 0 → 2
0.00 → 2.00 | 1
1.00 | How unevenly the hammer meets the strings of each key. At 100% (the factory) it brings the small tick you hear on soft notes and a little more of the long ringing tail; turn it down for a cleaner, rounder attack, as if the technician had seated the hammer evenly; up for a livelier, rougher strike. |
| `velocityCurve` | 465 | Hammer Curve | 0 = Settings · 1 = Curve 1 · 2 = Curve 2 · 3 = Curve 3 · 4 = Curve 4 · 5 = Curve 5 · 6 = Curve 6 · 7 = Curve 7 · 8 = Curve 8 · 9 = Curve 9 | 0 | The keyboard curve for THIS sound only. Settings uses the curve chosen in Settings; a numbered curve overrides it here and travels with the sound.
0 = the curve in Settings; 1–9 = that curve, for this sound only. |
#### Strings
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `unison` | 6 | Strings Unison | 0 → 3
×0.00 → ×3.00 | 1
×1.00 | How the two or three strings of each key are tuned against each other. Low is a clean, pure unison; up, they drift apart and the note shimmers and blooms — the sound of a piano a few weeks after tuning.
0 = strings in perfect unison, 1 = factory, 3 = wide, chorus-like. |
| `decay` | 7 | Strings Decay | 0.25 → 4
×0.25 → ×4.00 | 1
×1.00 | How long a held note keeps ringing. Down for a dry, close piano; up for long, singing notes. |
| `damper` | 8 | Strings Damper | 0.25 → 4
×0.25 → ×4.00 | 1
×1.00 | How firmly the felt damper stops the string when you lift the key. Low lets notes ring on a little after you let go; high stops them at once. |
| `keyoffNoise` | 12 | Strings Key-off Noise | 0 → 1
0% → 100% | 0.3
30% | The small sound of the damper landing back on the string when you lift the key. |
| `damperPosition` | 113 | Strings Damper Position | 0 → 0.25
Wide → 1/4.0 | 0
Wide | How wide the dampers press on the string. Wider stops it faster and cleaner.
0 = the wide factory felt; otherwise the fraction of the string where the felt sits. |
| `lastDamper` | 114 | Strings Last Damper | 60 → 108
C4 → C8 | 89
F6 | The highest key that has a damper. Above it the strings ring free, as on a real piano.
A MIDI note number: 60 = C4, 89 = F6 (factory), 108 = C8. |
#### Body
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `lid` | 1 | Body Lid | 0 → 1
Closed → Open | 1
Open | The grand's lid: closed, on the short stick or wide open. Open throws the brilliance toward the audience; closed is softer and rounder. Touch and hold (right-click on a Mac) to take the lid off completely.
*On the upright:* The upright's top lid: closed or open. Open lets out the hammers and the top of the strings — clearer; closed is softer and rounder. Touch and hold (right-click on a Mac) to put the front panel on or take it off.
0 = closed, 0.5 = half-stick, 1 = fully open (factory). |
| `soundboard` | 10 | Body Soundboard | 0 → 1
0% → 100% | 0.5
50% | How alive the soundboard is. Up, the wood keeps singing after the strike and the body of the note grows; down, it is drier and closer to the strings alone. |
| `cutoff` | 18 | Body Bridge | 1500 → 8000 *(log)*
1.5 kHz → 8.0 kHz | 3500
3.5 kHz | How heavy the bridge is. A light bridge lets more of the high partials into the soundboard — brighter; a heavy one keeps the top softer.
Hz: above it the soundboard radiates less and less. Lower is darker, higher is brighter. |
| `boardWood` | 19 | Body Wood | 0 = Alpine · 1 = Sitka · 2 = Engelmann · 3 = Laminated | 0 | The wood of the soundboard: three kinds of spruce, or a laminated board. Each has its own stiffness and weight: one is brighter, another warmer and slower.
⟳ *rebuilds the piano* |
| `boardThickness` | 20 | Body Thickness | 7 → 10
7.0 mm → 10.0 mm | 9
9.0 mm | How thick the soundboard is. Thinner is livelier and louder in the treble; thicker is darker and holds the bass.
⟳ *rebuilds the piano* |
| `pianoSize` | 21 | Body Size | 1.5 → 2.9
1.50 m → 2.90 m | 2.74
2.74 m | The length of the grand, from a small parlour grand to a full concert grand. Longer bass strings sing deeper and cleaner. Rebuilds the piano when you let go.
Grand only (the upright uses Upright Height). 2.74 m is the concert grand of the factory.
⟳ *rebuilds the piano* |
| `caseShape` | 107 | Body Shape | 0 = Grand · 1 = Upright | 0 | The model: Grand, lying flat with its soundboard under the strings, or Upright, standing against the wall. Changing it rebuilds the piano — the note that is sounding finishes on the old one.
0 = Grand — lying flat, the soundboard under the strings, the lid opening to the room.
1 = Upright — standing against the wall: the soundboard faces the wall and the sound comes back from it.
⟳ *rebuilds the piano* |
| `uprightHeight` | 108 | Body Upright Height | 1.1 → 1.35
1.10 m → 1.35 m | 1.21
1.21 m | How tall the upright is. A taller case means longer bass strings and a bigger soundboard.
Upright only.
⟳ *rebuilds the piano* |
| `uprightWall` | 109 | Body Wall Distance | 0.05 → 1
0.05 m → 1.00 m | 0.15
0.15 m | How far the upright stands from the back wall of the room — turning it moves the piano on the map. Close to the wall the bass gets stronger and the sound boxier.
Upright only.
⟳ *rebuilds the piano* |
| `lidOff` | 177 | Body Lid Off | 0 = Off · 1 = On | 0 | Takes the grand's lid off completely: no lid reflection, the sound opens up. Touch and hold the Lid knob (right-click on a Mac) to switch it too.
*On the upright:* Puts the upright's front panel on, for a closed, darker sound; tap again to take it off, as it comes from the factory. Touching and holding the Lid knob (right-click on a Mac) does the same.
1 on the grand removes the lid; 1 on the upright puts the front panel ON (a closed, darker sound). |
| `decayKnee` | 186 | Body Harmonic Decay Knee | 300 → 4000 *(log)*
300 Hz → 4.0 kHz | 1000
1.0 kHz | Harmonic decay: how long the upper harmonics ring, from C3 to E5 on the grand. Drag the dot sideways to choose where they start to fade (the knee), and down to make them fade sooner.
The knee: above this frequency the harmonics start to lose energy faster. 1 kHz is the factory setting; lower it and the fading reaches down into the body of the note. |
| `decayHigh` | 187 | Body Harmonic Decay | 0 → 3
0.00 → 3.00 | 1
1.00 | Harmonic decay: how long the upper harmonics ring, from C3 to E5 on the grand. Drag the dot sideways to choose where they start to fade (the knee), and down to make them fade sooner. At 0 every harmonic rings as long as the string allows.
How much faster the harmonics above the knee fade. **1 = factory.** 0 adds no extra loss (the longest, brightest tail); 2–3 make the top die away quickly — a rounder, darker tail while the attack keeps its bite. |
#### Resonance
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `sympathetic` | 9 | Resonance Sympathetic | 0 → 1
0% → 100% | 0.5
50% | The other strings ringing along. With the sustain pedal down every string is free and the whole piano sings; with it up only the top notes, which have no damper, still ring. |
| `duplex` | 105 | Resonance Duplex | 0 → 1
0% → 100% | 0
0% | The short lengths of string beyond the bridge, tuned to ring along with the treble. Up adds a silvery halo on top of the notes. |
| `plate` | 106 | Resonance Plate | 0 → 1
0% → 100% | 0
0% | The cast-iron frame ringing faintly under the strings. |
#### Pedals
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `pedalNoise` | 13 | Pedals Noise | 0 → 1
0% → 100% | 0.3
30% | The sound of the sustain pedal: the damper rail lifting and falling. |
| `leftPedalType` | 115 | Pedals Left Pedal | 0 = Auto · 1 = Una Corda · 2 = Half-blow · 3 = Celeste · 4 = Mozart Rail · 5 = Buff Stop | 0 | What the left pedal does: shift the hammers to fewer strings (una corda), move them closer (half-blow), or the old pedals of historical pianos. Auto picks the right one for the model.
Auto = una corda on the grand, half-blow on the upright. |
| `middlePedalType` | 116 | Pedals Middle Pedal | 0 = Auto · 1 = Sostenuto · 2 = Muffler · 3 = Harmonic · 4 = Super Sostenuto · 5 = Rattle · 6 = Buff Stop · 7 = Pinch Harmonic | 0 | What the middle pedal does: sostenuto (holds only the notes already down), a felt muffler for quiet practice, or the special pedals. Auto picks the right one for the model.
Auto = sostenuto on the grand, muffler (a felt strip for quiet practice) on the upright. |
#### Tuning
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `tuningA4` | 16 | Tuning A4 | 430 → 450
430.0 Hz → 450.0 Hz | 440
440.0 Hz | The pitch of the A above middle C. 440 Hz is the standard; orchestras often use 442. |
| `stretch` | 17 | Tuning Stretch | 0 → 1.5
×0.00 → ×1.50 | 1
×1.00 | How much the octaves are stretched, as a tuner does: the treble a little sharp and the bass a little flat, so the octaves sound in tune with the piano's own overtones.
0 = no stretch (pure equal temperament), 1 = the stretch the piano's own overtones ask for (factory), 1.5 = more. |
| `temperament` | 111 | Tuning Temperament | 0 = Equal · 1 = Werckmeister III · 2 = Kirnberger III · 3 = Vallotti · 4 = Meantone 1/4 · 5 = Just · 6 = Pythagorean | 0 | How the twelve notes are tuned against each other. Equal is the modern piano; the historical temperaments make some keys sweeter and others sharper, as in Bach's and Mozart's time. |
| `temperamentRoot` | 112 | Tuning Temperament Root | 0 = C · 1 = C# · 2 = D · 3 = D# · 4 = E · 5 = F · 6 = F# · 7 = G · 8 = G# · 9 = A · 10 = A# · 11 = B | 0 | The key the temperament is built on — the sweetest key of the historical temperaments. |
#### Condition
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `condition` | 110 | Condition | 0 = New · 1 = Concert *(hidden)* · 2 = Concert · 3 = Old · 4 = Saloon | 2 | The state of the piano. New: fresh from the workshop, the hammers still soft. Concert: the factory sound, a piano kept in shape. Old: hardened hammers, unisons drifting apart, a shorter ring. Saloon: the neglected bar piano — harsh, out of tune, with false strings beating here and there.
0 **New**: fresh, softer felt (about 5.5 dB less treble than Concert at the same volume), a slightly shorter sustain and a clean, just-tuned unison. 1: hidden from the menus — it plays exactly as Concert (sounds saved with the old option open as Concert). 2 **Concert**: the factory piano. 3 **Old**: grooved, harder hammers, strings that die sooner with partials up to 3 cents out, a tired soundboard, wider unisons and softer dampers. 4 **Saloon**: the neglected bar piano — hard hammers, short sustain, partials up to 8 cents out, unisons far apart, dampers that barely stop. |
#### Output
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `volume` | 0 | Output Volume | 0 → 2
−∞ dB → 6.0 dB | 1
0.0 dB | The piano's output level, after the effects. Use it to match this sound to the rest of your set — it doesn't change the tone.
Linear: 1 = 0 dB (factory), 2 = +6 dB, 0 = silence. |
### Listening and the room
#### Listening
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `perspective` | 2 | Listening Perspective | 0 → 1
Bench → Far | 0
Bench | Host automation only — not on the app screen. It belonged to the old fixed listening positions; with Microphones or Binaural it changes nothing. To move the listener, move the head or the mics on the Listen screen.
In this version it acts only on a reference listening position the app no longer offers: with Microphones or Binaural it changes nothing. To move the listener, move the head or the mics. |
| `width` | 3 | Listening Width | 0 → 1
0% → 100% | 0.7
70% | How wide the piano sounds. 70% is the piano as you hear it (the factory); less brings it toward mono; up to 100% spreads it wider. |
| `listenMode` | 26 | Listening Mode | 0 = Binaural *(hidden)* · 1 = Microphones · 2 = Binaural | 2 | How the piano reaches your ears: Microphones — up to eight mics you place around the piano — or Binaural, for headphones, as if your head were where you put it on the map. Move the mics or the head closer or farther to change the distance.
Write 1 (Microphones) or 2 (Binaural). 0 is no longer offered and plays as Binaural.
1 = Microphones — up to eight microphones you place around the piano.
2 = Binaural — for headphones: as if your own head were at the piano.
⟳ *rebuilds the piano* |
#### Mic
Eight microphones, `mic1…` to `mic8…`, each with the same nine controls. One row per control; the defaults column gives mic 1 → mic 8. The positions are in metres: **X** across the piano (bass side → treble side), **Y** along it (keyboard → tail), **Height** above the floor.
| identifiers | addresses | name | range | defaults, mic 1 → 8 | what it does |
|---|---|---|---|---|---|
| `mic1X` … `mic8X` | 27, 35, 43, 51, 59, 67, 75, 83 | Mic N X | -1 → 3
-1.00 m → 3.00 m | 0.62 · 0.88 · 0.55 · 0.95 · 0.45 · 1.05 · 2.9 · 2.9 | Where the microphone stands across the piano, from the bass side to the treble side.
⟳ *rebuilds the piano* |
| `mic1Y` … `mic8Y` | 28, 36, 44, 52, 60, 68, 76, 84 | Mic N Y | -2 → 4
-2.00 m → 4.00 m | 1 · 1 · 0.25 · 0.25 · 2.2 · 2.2 · 0.6 · 1.6 | Where the microphone stands along the piano, from the keyboard to the tail.
*On the upright:* How high the microphone is on the upright, from the bottom of the soundboard to the top of the case.
⟳ *rebuilds the piano* |
| `mic1Z` … `mic8Z` | 29, 37, 45, 53, 61, 69, 77, 85 | Mic N Height | -20 → 4
-20.00 m → 4.00 m | 1.2 · 1.2 · 0.35 · 0.35 · 1.5 · 1.5 · 1.5 · 1.5 | How high the microphone is above the soundboard (the strings). Close, inside the lid, it hears the hammers and strings; higher up, the whole piano and more room.
*On the upright:* How far the microphone is from the soundboard: in front of the upright, or — below zero — behind it, in the gap to the wall.
Metres above the floor. On the upright, a negative value puts the mic behind the soundboard.
⟳ *rebuilds the piano* |
| `mic1Azimuth` … `mic8Azimuth` | 30, 38, 46, 54, 62, 70, 78, 86 | Mic N Azimuth | -180 → 180
-180° → 180° | 0 · 0 · 0 · 0 · 180 · 180 · -90 · -90 | Where the microphone points, around the piano.
⟳ *rebuilds the piano* |
| `mic1Elevation` … `mic8Elevation` | 31, 39, 47, 55, 63, 71, 79, 87 | Mic N Elevation | -90 → 90
-90° → 90° | -90 · -90 · -60 · -60 · -30 · -30 · 0 · 0 | How far the microphone tilts up or down.
⟳ *rebuilds the piano* |
| `mic1Pattern` … `mic8Pattern` | 32, 40, 48, 56, 64, 72, 80, 88 | Mic N Pattern | 0 → 1
Omni → Figure 8 | 0.5 · 0.5 · 0.5 · 0.5 · 0.5 · 0.5 · 0 · 0 | How the microphone picks up: omni hears all around; card (cardioid) hears the front; fig8 (figure-8) hears front and back and ignores the sides.
0 = omni, 0.5 = cardioid, 1 = figure-8; values in between are the patterns in between.
⟳ *rebuilds the piano* |
| `mic1Level` … `mic8Level` | 33, 41, 49, 57, 65, 73, 81, 89 | Mic N Level | 0 → 2
×0.00 → ×2.00 | 1 · 1 · 0 · 0 · 0 · 0 · 0 · 0 | The level of this microphone in the mix. At zero it is off.
0 switches the mic off. Mics 3–8 start at 0. |
| `mic1Pan` … `mic8Pan` | 34, 42, 50, 58, 66, 74, 82, 90 | Mic N Pan | -1 → 1
-1.00 → 1.00 | -1 · 1 · -0.5 · 0.5 · -1 · 1 · -1 · 1 | Where this microphone sits between left and right.
−1 = left, +1 = right. |
| `mic1Phase` … `mic8Phase` | 178, 179, 180, 181, 182, 183, 184, 185 | Mic N Phase | 0 = Normal · 1 = Invert | 0 · 0 · 0 · 0 · 0 · 0 · 0 · 0 | Flips this microphone's polarity. A mic behind an upright hears the soundboard push the other way: flip it, and the front and back pairs add up instead of thinning the bass. |
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `micLevelComp` | 96 | Mic Level Compensation | 0 = Off · 1 = On | 1 | Evens out the level of microphones placed far from the piano. |
| `micDelayComp` | 97 | Mic Delay Compensation | 0 = Off · 1 = On | 1 | Lines up microphones placed at different distances, so the attacks arrive together. |
#### Head
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `headX` | 91 | Head X | -1 → 3
-1.00 m → 3.00 m | 0.875
0.88 m | Where your head is across the piano.
⟳ *rebuilds the piano* |
| `headY` | 92 | Head Y | -2 → 4
-2.00 m → 4.00 m | -0.4
-0.40 m | Where your head is along the piano.
⟳ *rebuilds the piano* |
| `headZ` | 93 | Head Height | 0 → 3
0.00 m → 3.00 m | 0.6
0.60 m | How high your ears are.
*On the upright:* How far your head is in front of the upright.
⟳ *rebuilds the piano* |
| `headDiameter` | 94 | Head Diameter | 0.12 → 0.25
12 cm → 25 cm | 0.18
18 cm | The size of your head — it sets how far apart your ears are.
⟳ *rebuilds the piano* |
| `headAngle` | 95 | Head Angle | -180 → 180
-180° → 180° | 0
0° | Where your head is turned.
⟳ *rebuilds the piano* |
| `headHeight` | 189 | Head Ear Height | 0.8 → 2
0.80 m → 2.00 m | 1.2
1.20 m | How high your ears are at the upright, from the floor: 1.2 m is sitting at the keys, about 1.65 m is standing. Higher up you hear more of the open top and less of the front of the case.
⟳ *rebuilds the piano* |
#### Room
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `roomCustom` | 98 | Room Custom | 0 = Off · 1 = On | 0 | On, the first reflections come from the room you set here: its size, its walls and where the piano stands.
On, the room also chooses the reverb's Type, Decay, Space and Damping from its size and walls. |
| `roomWidth` | 99 | Room Width | 3 → 40
3.00 m → 40.00 m | 12.3
12.30 m | How wide the room is. |
| `roomDepth` | 100 | Room Depth | 3 → 40
3.00 m → 40.00 m | 9.7
9.70 m | How deep the room is. |
| `roomHeight` | 101 | Room Height | 2.2 → 20
2.20 m → 20.00 m | 6
6.00 m | How high the ceiling is. |
| `roomMaterial` | 102 | Room Material | 0 = Wood · 1 = Plaster · 2 = Stone · 3 = Curtains · 4 = Studio | 0 | What the walls are made of: Wood is warm, Plaster brighter, Stone bright and long, Curtains dry, Studio the driest — a treated room. |
| `roomWallDistance` | 103 | Room Wall Distance | 0.5 → 20
0.50 m → 20.00 m | 4.9
4.90 m | How far the piano stands from the side wall. |
| `roomFrontDistance` | 104 | Room Front Distance | 1.2 → 20
1.20 m → 20.00 m | 4.4
4.40 m | How far the piano stands from the front wall. |
### The effects rack
#### EQ
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `eqOn` | 125 | EQ On | 0 = Off · 1 = On | 0 | EQ — five bands to shape the piano for the mix: cut the mud, lift the presence, add air. |
| `eqLowGain` | 126 | EQ Low Gain | -15 → 15
-15.0 dB → +15.0 dB | 0
+0.0 dB | Low band: weight and body. Touch and hold (right-click on a Mac) to move its frequency. |
| `eqLowFreq` | 127 | EQ Low Freq | 30 → 400 *(log)*
30 Hz → 400 Hz | 100
100 Hz | Frequency of this band. Sweep it with the band boosted to find the spot, then set the gain. |
| `eqLoMidGain` | 128 | EQ Low-Mid Gain | -15 → 15
-15.0 dB → +15.0 dB | 0
+0.0 dB | Low-mid band: where mud and boxiness live — often better cut than boosted. Touch and hold (right-click on a Mac) to move its frequency. |
| `eqLoMidFreq` | 129 | EQ Low-Mid Freq | 100 → 1000 *(log)*
100 Hz → 1.0 kHz | 300
300 Hz | Frequency of this band. Sweep it with the band boosted to find the spot, then set the gain. |
| `eqMidGain` | 130 | EQ Mid Gain | -15 → 15
-15.0 dB → +15.0 dB | 0
+0.0 dB | Middle band: the body and the honk of the piano. Touch and hold (right-click on a Mac) to move its frequency. |
| `eqMidFreq` | 131 | EQ Mid Freq | 300 → 4000 *(log)*
300 Hz → 4.0 kHz | 1000
1.0 kHz | Frequency of this band. Sweep it with the band boosted to find the spot, then set the gain. |
| `eqHiMidGain` | 132 | EQ High-Mid Gain | -15 → 15
-15.0 dB → +15.0 dB | 0
+0.0 dB | High-mid band: attack and presence. Touch and hold (right-click on a Mac) to move its frequency. |
| `eqHiMidFreq` | 133 | EQ High-Mid Freq | 1000 → 8000 *(log)*
1.0 kHz → 8.0 kHz | 3000
3.0 kHz | Frequency of this band. Sweep it with the band boosted to find the spot, then set the gain. |
| `eqHighGain` | 134 | EQ High Gain | -15 → 15
-15.0 dB → +15.0 dB | 0
+0.0 dB | High band: air and sparkle. Touch and hold (right-click on a Mac) to move its frequency. |
| `eqHighFreq` | 135 | EQ High Freq | 2000 → 16000 *(log)*
2.0 kHz → 16.0 kHz | 8000
8.0 kHz | Frequency of this band. Sweep it with the band boosted to find the spot, then set the gain. |
#### Compressor
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `compOn` | 140 | Compressor On | 0 = Off · 1 = On | 0 | Compressor — evens out the dynamics, so soft notes come forward and loud chords don't jump out of the mix. |
| `compThreshold` | 141 | Compressor Threshold | -40 → 0
-40.0 dB → +0.0 dB | -18
-18.0 dB | Above this level the compressor starts to act. Lower means it acts on more of the playing. |
| `compRatio` | 142 | Compressor Ratio | 1 → 10
×1.00 → ×10.00 | 3
×3.00 | How strongly it holds the loud notes. 2:1 is gentle glue; 10:1 is a limiter. |
| `compAttack` | 143 | Compressor Attack | 1 → 100
1 ms → 100 ms | 10
10 ms | How fast it grabs a loud note. Slower lets the hammer's attack through before it acts. |
| `compRelease` | 144 | Compressor Release | 20 → 1000
20 ms → 1.00 s | 120
120 ms | How fast it lets go. Longer is smoother; shorter can pump. |
| `compMakeup` | 145 | Compressor Makeup | 0 → 24
+0.0 dB → +24.0 dB | 0
+0.0 dB | Gain after the compressor, to get back the level it took. |
#### Exciter
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `exciterOn` | 154 | Exciter On | 0 = Off · 1 = On | 0 | Exciter — adds new harmonics only to the top of the sound: presence and air without making the body louder. The classic trick to make a piano cut through a band. |
| `exciterFreq` | 155 | Exciter Freq | 1000 → 8000 *(log)*
1.0 kHz → 8.0 kHz | 3000
3.0 kHz | Above which frequency the exciter works. Lower adds bite to the attack; higher adds only air. |
| `exciterAmount` | 156 | Exciter Amount | 0 → 1
0% → 100% | 0.3
30% | How much of the new top is added. A little goes a long way. |
#### Chorus
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `chorusOn` | 149 | Chorus On | 0 = Off · 1 = On | 0 | Chorus — copies of the piano, slightly detuned and moving, around the original: the shimmering ballad piano of the eighties, or just a wider stage sound. |
| `chorusMode` | 150 | Chorus Mode | 0 = I · 1 = II · 2 = I+II · 3 = Ensemble · 4 = Vintage · 5 = Dark · 6 = Wide · 7 = Strings | 0 | The voicing of the chorus, from one subtle voice to a wide ensemble.
0 = I — one voice, subtle: the piano a little wider.
1 = II — one voice, deeper and faster.
2 = I+II — two voices together: the classic ballad shimmer.
3 = Ensemble — three voices: thick and lush.
4 = Vintage — a deep old pedal, a little darker.
5 = Dark — slow and deep, darker still.
6 = Wide — two voices in opposite phase: width without wobble.
7 = Strings — the string-machine ensemble: a pad-like piano. |
| `chorusRate` | 151 | Chorus Rate | 0.05 → 5 *(log)*
0.05 Hz → 5 Hz | 0.5
0.5 Hz | How fast the chorus moves (only in Vintage, Dark, Wide and Strings; the others keep their own speed). |
| `chorusDepth` | 152 | Chorus Depth | 0 → 1
0% → 100% | 1
100% | How far the copies drift from the piano. Low is a gentle widening; high is the seasick wobble. |
| `chorusMix` | 153 | Chorus Mix | 0 → 1
0% → 100% | 0.5
50% | How much of the chorus you hear against the dry piano. |
#### Delay
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `delayMix` | 136 | Delay Mix | 0 → 1
0% → 100% | 0.3
30% | How much of the echoes you hear. |
| `delayTime` | 137 | Delay Time | 20 → 2000
20 ms → 2.00 s | 350
350 ms | Time between echoes. |
| `delayFeedback` | 138 | Delay Feedback | 0 → 0.9
0% → 90% | 0.3
30% | How many repeats. Low is one or two echoes; high keeps repeating. |
| `delayTone` | 139 | Delay Tone | 1000 → 12000 *(log)*
1.0 kHz → 12.0 kHz | 6000
6.0 kHz | Brightness of the repeats. Down makes each echo darker. |
| `delayOn` | 146 | Delay On | 0 = Off · 1 = On | 0 | Delay — echoes of what you play, from a short slapback to long ambient repeats. |
#### Reverb
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `reverb` | 14 | Reverb Mix | 0 → 1
0% → 100% | 0.18
18% | How much of the room you hear. The first reflections are calculated from the room; the tail is the reverb. Touch and hold (right-click on a Mac) for what's behind it: Room Size on the Play screen, Dry and Duck in the effects rack.
0 = no room at all, 1 = all room. |
| `reverbSize` | 15 | Reverb Size | 0 → 1
0% → 100% | 0.45
45% | How big the room sounds and how long its tail lasts. In the effects rack (Decay), touch and hold it (right-click on a Mac) for Depth and Rate.
Shown as **Decay** on the reverb card. |
| `reverbOn` | 147 | Reverb On | 0 = Off · 1 = On | 1 | The room and its reverb tail. Off, the piano plays dry, with no room at all. |
| `reverbType` | 161 | Reverb Type | 0 = Room · 1 = Hall · 2 = Cathedral · 3 = Plate · 4 = Spring · 5 = Shimmer · 6 = Cloud · 7 = Gate · 8 = Swell | 1 | The kind of space. Picking one sets the reverb to a starting point for that space.
0 = Room — a small, natural room.
1 = Hall — a concert hall: wide and smooth.
2 = Cathedral — huge and long.
3 = Plate — dense and bright, the studio classic for keys.
4 = Spring — the bouncy spring tank of an amp.
5 = Shimmer — a tail that rises an octave: ethereal pads.
6 = Cloud — a soft, diffuse wash.
7 = Gate — a big reverb that stops abruptly.
8 = Swell — the tail fades in after the note. |
| `reverbDim` | 162 | Reverb Space | 0 → 1
0% → 100% | 0.5
50% | Space: how big the space is. Bigger spreads the reflections out; smaller is tighter. |
| `reverbDamp` | 163 | Reverb Damping | 0 → 1
0% → 100% | 0.5
50% | How quickly the highs die in the tail — like soft walls. Up is darker and warmer. |
| `reverbPreDelay` | 164 | Reverb Pre-Delay | 0 → 1
0% → 100% | 0.5
50% | A short gap before the reverb starts, so the attack of the note stays clear. The middle is the natural setting of each type. |
| `reverbTone` | 165 | Reverb Tone | 0 → 1
0% → 100% | 1
100% | Brightness of the reverb tail. |
| `reverbLowEnd` | 166 | Reverb Low End | 0 → 1
0% → 100% | 1
100% | Bass in the tail. Turn it down to keep the reverb from muddying your chords. |
| `reverbModDepth` | 167 | Reverb Mod Depth | 0 → 1
0% → 100% | 0.5
50% | Depth — behind Decay (touch and hold it; right-click on a Mac): how much the tail moves — a slow chorus inside the room. The middle is the type's own amount; up swirls, down stays still and clean. |
| `reverbModRate` | 168 | Reverb Mod Rate | 0 → 1
0% → 100% | 0.5
50% | Rate — behind Decay (touch and hold it; right-click on a Mac): how fast the tail moves. The middle is the type's own speed. |
| `reverbShimPitch` | 169 | Reverb Shimmer Pitch | 0 → 1
-24 st → +24 st | 0.75
+12 st | Interval — on Shimmer, touch and hold Type (right-click on a Mac) and choose Shimmer controls…: the interval the tail climbs to. +12 st is the classic octave up; 0 keeps it in unison; below zero it falls.
0.75 = one octave up (factory); lower values climb less, then fall. |
| `reverbFreeze` | 170 | Reverb Freeze | 0 = Off · 1 = On | 0 | Freeze holds the tail forever: the chord you were playing becomes a pad, and what you play on top stays dry. Tap again to let it go. Touch and hold it (right-click on a Mac) for Feed. |
| `reverbFreezeIn` | 171 | Reverb Freeze Feed | 0 → 1
0% → 100% | 0
0% | Feed — behind Freeze (touch and hold it; right-click on a Mac): how much of what you play still gets into the frozen tail. At zero the door stays shut — only the frozen chord sounds. |
| `reverbP1` | 172 | Reverb Param 1 | 0 → 1
0% → 100% | 0.5
50% | Changes with the type — touch and hold Type (right-click on a Mac) and choose the type's controls: Shimmer — how much octave enters the tail; Diffuse, on Cloud — how dense the cloud is; Time, on Gate — how long it holds before the cut; Attack, on Swell — how slowly it swells in. |
| `reverbP2` | 173 | Reverb Param 2 | 0 → 1
0% → 100% | 0.5
50% | Shape — on Gate, behind Type (touch and hold it; right-click on a Mac): how the gated tail falls — down drops like a door, up lets it breathe out. |
| `reverbDuck` | 174 | Reverb Duck | 0 → 1
0% → 100% | 0
0% | Duck — behind Mix (touch and hold it; right-click on a Mac): the tail steps back while you play and blooms in the gaps between phrases. Off keeps it as it always was. |
| `reverbDry` | 175 | Reverb Dry | 0 → 1
0% → 100% | 1
100% | Dry — behind Mix (touch and hold it; right-click on a Mac): how much of the piano itself passes. 100% keeps the piano full with the reverb on top; 0% leaves only the reverb. |
#### Limiter
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `limiterOn` | 157 | Limiter On | 0 = Off · 1 = On | 0 | Limiter — the last thing in the chain: nothing goes above the ceiling, so you can push the level without clipping. |
| `limiterGain` | 158 | Limiter Gain | 0 → 12
+0.0 dB → +12.0 dB | 0
+0.0 dB | Pushes the piano into the limiter: louder and denser as it goes up. |
| `limiterCeiling` | 159 | Limiter Ceiling | -12 → 0
-12.0 dB → +0.0 dB | -1
-1.0 dB | The highest level that can come out. |
| `limiterRelease` | 160 | Limiter Release | 10 → 1000
10 ms → 1000 ms | 120
120 ms | How fast it lets go after a peak. Short is loud but can pump; long is smoother. |
#### Rack
| identifier | address | name | range | default | what it does |
|---|---|---|---|---|---|
| `fxRackBypass` | 148 | Effects Bypass | 0 = In · 1 = Bypass | 0 | Bypasses the whole rack at once, to hear the piano alone. |
---
## 5 · The effects rack
7 effects, in a **fixed** order — the order a studio uses for an acoustic piano. There is nothing
to reorder and no position to write. The Volume comes after all of them. `fxRackBypass` = 1 takes the whole
rack out, room included: the dry piano alone.
| order | effect | switch | default |
|---|---|---|---|
| 1 | EQ | `eqOn` | off |
| 2 | Compressor | `compOn` | off |
| 3 | Exciter | `exciterOn` | off |
| 4 | Chorus | `chorusOn` | off |
| 5 | Delay | `delayOn` | off |
| 6 | Reverb | `reverbOn` | on |
| 7 | Limiter | `limiterOn` | off |
The Reverb card is the room the piano stands in: the first reflections are calculated from the room, the tail
is the reverb. With `roomCustom` on, the room's size and walls also choose the reverb's Type, Decay, Space and
Damping — so with a custom room, shape the space with the Room controls, not with those four.
---
## 6 · Editing, end to end
**The quick way — copy and paste:**
1. In the library, touch and hold a sound close to what you want (right-click on the Mac) → *Copy Sound*.
2. Paste it into the conversation with your assistant, together with this kit, and ask in musical terms:
*"warmer, a softer hammer, and a scene B with more room"*.
3. The answer must be the whole sound: **`TONICAP-PRESET-v1:`** immediately followed by the JSON, with nothing before
it (a blank line or spaces around it are fine). That label is how the app recognises a sound on the
clipboard — without it, nothing is pasted.
4. Copy the answer, open the library and tap **Paste**. It is saved as a new sound in the bank that is open;
nothing you already have is replaced. (*Paste* from the menu of the sound's name on the main screen only
opens it, to try — save it from there if you keep it.)
**With a file:** *Export Sound…* → edit → save it with the `.tap` extension → open it on the device
(Files, AirDrop, Mail). It lands in your own bank as a new sound, and the library opens.
**Things that will bite:**
- **No brand names** in `name`, `tags` or anywhere that gets published — no piano makers, no software, no
artists, no song titles. Describe the sound instead (*"Warm Late-Night Grand"*).
- **`mechanism` and `caseShape` must agree.** The sound plays the model the parameter says; the library shows
the badge the field says.
- **The grand and the upright have their own controls.** `pianoSize` shapes only the grand; `uprightHeight`
and `uprightWall` only the upright. On the upright, `lidOff` = 1 *adds* the front panel.
- **An effect needs its switch.** The knobs of an effect that is off change nothing you can hear.
- **Mic levels at 0 are switched off.** In Microphones mode only the mics with a level above 0 are heard —
the default setup uses mics 1 and 2.
- **Balance the Volume last,** by ear, against a sound you know.
---
## 7 · Recipes
What to move for the requests that come up most. Start from the closest factory sound, change a few controls
by a modest amount, and listen — the physical model answers to small moves.
| the request | move | notes |
|---|---|---|
| **Warmer, rounder** | `hammerFelt` 1 (Med) or 0 (Soft) · `hardness` ×0.6–0.8 · `decayHigh` 1.5–2 · `cutoff` 2000–2500 Hz · `lid` 0.5 | A softer felt is the first move; the harmonic decay makes the tail mellow without dulling the attack. For a gentler top only, `spectrum7`/`spectrum8` −3 to −6 dB. |
| **Brighter, more presence** | `hammerFelt` 3 (Lacq) or `hardness` ×1.5–2 · `dynamics` ×1.3 · `cutoff` 5000–6000 Hz · `decayHigh` 0.3–0.6 · `lid` 1 | For a band mix: `eqOn` 1 with `eqHiMidGain` +2–4 dB, or `exciterOn` 1 with a small `exciterAmount`. |
| **Felt piano, intimate** | `hammerFelt` 4 (Felt) · `hammerNoise` 0.6–0.8 · `keyoffNoise` and `pedalNoise` 0.5 · `reverb` 0.08–0.15 · close mics or binaural near the keys | The Felt option is the strip of felt between hammers and strings: muffled, with the action up front. On the upright, `lidOff` 1 closes it further. |
| **Binaural, for headphones** | `listenMode` 2 · keep `headX`/`headY`/`headZ` where the factory puts them (the player's seat) · `width` 0.7–1 | Move the head back along `headY` to hear the piano from further away; `headAngle` turns it. `perspective` does nothing here. |
| **Recording, close mics** | `listenMode` 1 · mics 1–2 `micNLevel` 1, the rest 0 · `micNPattern` 0.5 (cardioid) or 0 (omni) · `micLevelComp` and `micDelayComp` 1 | Closer mics = more attack and less room. Behind an upright, flip the back pair with `micNPhase` 1. On the grand, `lidOff` 1 removes the lid for an open, airy pickup. Then `compOn`/`eqOn` as in a studio. |
| **Upright** | `caseShape` 1 with `"mechanism": "upright"` · `uprightHeight` 1.10–1.35 m · `uprightWall` 0.05–0.3 m | Taller is deeper in the bass; closer to the wall is boomier and boxier. The pedals on Auto become half-blow and muffler. |
| **Honky-tonk, saloon** | `condition` 4 (Saloon) or 3 (Old) · `unison` ×2–3 · Note Edit: every key `tune` ±8 cents and `width` ×3.5 | That Note Edit is the app's own *Honky-tonk* profile. An upright and a small, dry room complete it. |
| **Ambient, pad-like** | `reverbType` 5 (Shimmer), 6 (Cloud) or 2 (Cathedral) · `reverb` 0.4–0.6 · `reverbSize` 0.7–0.9 · `decay` ×1.5–2 · `sympathetic` 0.7 | `chorusOn` 1 with `chorusMode` 7 (Strings) or 3 (Ensemble) makes it a pad; `reverbFreeze` 1 holds the chord; `reverbDuck` keeps the playing clear. `hammerFelt` 4 suits it. |
---
## 8 · Sounds written by other versions
You will open sounds older — or newer — than the app reading them. Nothing breaks, and knowing the rules saves
you from chasing a bug that is not there:
- **A key the app does not know is ignored.** When you paste a sound made by a newer Tonic AP, the app says how
many controls it did not know, and plays without them.
- **A value outside its range is moved to the nearest edge** when the sound opens. An invented number never
crashes anything — it just lands at the limit. The pitch-bend range is held to 0–24 and `modAmount` to 0–1.
- **A key left out opens at its default** — which is why a sound only needs the values that differ.
- **A missing field is not an error:** no `scenes` means six empty scenes, no `name` opens as *Untitled*.
- **Options retired from the menus still open:** `listenMode` 0 plays as Binaural, `condition` 1 as Concert.
---
## 9 · Checking a sound before it reaches the app
- `format` is `"tonic-ap"`, `version` is 1, `kind` is `"preset"` (or `"bank"`).
- Every key in `params` — and in every scene — is in §4; every value is within its range; options are whole
numbers, and none of them a hidden one.
- `mechanism` agrees with `caseShape`.
- `scenes` has six entries; `lastScene`, if present, points at a filled one.
- `noteEdits` keys are note numbers 21–108 as strings, with only the fields of §2.
- `level` is `1`.
`patch-kit.json` carries everything needed to run these checks by machine.
---
## 10 · What this kit does not give you
The factory sounds are not in this document: they are the instrument's own voice, and they ship inside the app.
Nor are MIDI maps (`.tapmap`): a map belongs to the keyboard on your desk, not to a sound — make it
in the app with MIDI Learn. This kit is the format, the ranges and what the numbers mean — enough to build your
own sounds, and enough for an assistant to do it with you without guessing.