Metadata-Version: 2.5
Name: pymidiinstrumentdefs
Version: 0.3.0
Summary: What a particular model of MIDI instrument answers to: definitions transcribed from manufacturers' manuals, with a loader and a validator.
Project-URL: Homepage, https://github.com/simonholliday/PyMidiInstrumentDefs
Project-URL: Repository, https://github.com/simonholliday/PyMidiInstrumentDefs
Project-URL: Issues, https://github.com/simonholliday/PyMidiInstrumentDefs/issues
Author: Simon Holliday
License-Expression: MIT
License-File: LICENSE
Keywords: definitions,instrument,midi,midnam,music,synthesizer
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pymididefs>=0.4
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: fonttools; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pypdf[crypto]; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# PyMidiInstrumentDefs

What a particular model of MIDI instrument answers to - its controls, its
voicing, its note range - read from definitions transcribed from the
manufacturers' own manuals.

It is the companion to [PyMidiDefs](https://github.com/simonholliday/PyMidiDefs),
which carries the MIDI specification's own constants. PyMidiDefs says CC 7 is
Volume; this package says a Matriarch's CC 94 switches it between one, two and
four voices.

## Two kinds of fact

PyMidiDefs holds **specification** facts. CC 7 is Volume; note 60 is C4. They
are true for everybody, permanently, they are transcribed from published
standards, and they cannot be wrong about the world.

This package holds **model** facts. A Minitaur ignores notes above 72; a
Matriarch's CC 94 switches it between one, two and four voices. They are true
for everybody who owns that model, and they change when the manufacturer ships
firmware.

The difference matters when you are deciding how much to trust a number. **A
model fact is a report, and reports are wrong in the wild.** For one parameter
on one common synth - the Minitaur's key priority - the manual, the firmware
addendum, and the `.midnam` file everybody shares give three different answers.
So every instrument definition carries a `source` saying which manual and which
page it came from, and one imported automatically stays marked `unverified`
until a person has checked it. [Sources](#sources), below, says where each of
the bundled ones came from and gives that Minitaur disagreement in full.

**Rig facts are not here and never will be.** Which MIDI channel *your*
Minitaur is on, which port it is plugged into, which notes you have chosen to
play - those belong to your own project, not to a definition shared by
everyone who owns the same box.

**And specification facts stay in PyMidiDefs.** The MIDI channel mode messages,
CC 120 to 127 - All Sound Off, Local Control and the rest - mean the same on
every instrument that has them, so a definition does not list them as controls
even where a manufacturer's chart prints them. The validator refuses one, and
names the PyMidiDefs constant it would have duplicated.

## Installation

```bash
pip install pymidiinstrumentdefs
```

Requires Python 3.10 or later. It depends on PyMidiDefs and on PyYAML, since
every definition is a YAML file.

To install the latest unreleased code straight from the repository:

```bash
pip install git+https://github.com/simonholliday/PyMidiInstrumentDefs.git
```

## Usage

```python
import pymidiinstrumentdefs

matriarch = pymidiinstrumentdefs.load("moog/matriarch")

matriarch.voice.voicing_modes            # (1, 2, 4)  switchable voicing
matriarch.voice.plays_note(60)           # True
matriarch.controls["glide_type"].kind    # 'choice'

# What to send to put a banded control into a named state. Definitions record
# the band boundaries as manuals print them; working out the number is this
# library's job.
matriarch.controls["glide_type"].value_for("exp")   # 106

pymidiinstrumentdefs.available()         # what is on the search path
```

A control says what values it takes, or says that its maker's documents do not
settle it. A DeepMind 12's table prints one range for its modulation sources and
its own list of them runs past it:

```python
deepmind = pymidiinstrumentdefs.load("behringer/deepmind_12")

deepmind.controls["mod_1_depth"].range          # (0, 255)   as the table prints it
deepmind.controls["mod_1_source"].range_known   # False      two figures, and they disagree
deepmind.controls["mod_1_source"].range         # (0, 16383) all an NRPN can carry, and no claim
```

Some instruments are several instruments at once, each answering on its own
MIDI channel. A definition says so with `parts`, and a control names the part
it belongs to - so the same controller number can mean two different things
and still be unambiguous:

```python
streichfett = pymidiinstrumentdefs.load("waldorf/streichfett")

streichfett.parts["solo"].channel_for(1)   # 2 - one channel above the strings
streichfett.parts["solo"].takes("notes")   # True
streichfett.parts["solo"].polyphony        # 8 - its own voices, not the strings'
streichfett.controls_by_part()[""]         # the controls on the base channel
streichfett.controls_reaching("strings")   # all 19 - the strings sit on the base channel
```

`takes()` answers `True` for a kind of message the part is recorded as taking
and `False` for any other, with one exception. It answers `None` where the file
says a kind of message reaches the instrument there and no document ties it to
the part: neither yes nor no, so a page that leaves out what a part does not
take should not leave that out.

Some instruments change shape with a setting, and a definition says so with
`modes`: a part may exist in one mode only, a mode may silence the controls
that name no part, and a mode may give the base channel a range of its own,
which `channels_in()` answers with. A page asks what answers in each:

```python
ju = pymidiinstrumentdefs.load("roland/ju_06a")

list(ju.modes)                             # ['sound_module', 'control_surface']
len(ju.controls_in("sound_module"))        # 39 - the first page of its chart
len(ju.controls_in("control_surface"))     # 24 - the second, sent and never recognised
ju.factory_mode                            # None - no page says which it ships in
```

A definition also says what its maker calls each group of controls, which is
what a page can head a table with. The groups are what the maker's own document
groups them into, in the order to show them:

```python
take_5 = pymidiinstrumentdefs.load("sequential/take_5")

take_5.groups["mod_1"]                   # 'Mod 1' - the mod matrix slot, as the panel numbers it
take_5.groups["envelope_1"]              # 'Env 1 (Filter)' - the guide's own words for which is which
list(take_5.grouped_controls())[:3]      # ['performance', 'oscillators', 'glide']
```

A group with no label is shown by its own name, which is honest: a label is
only ever there because a document says it.

### Names, and where the files go

A definition is named for its maker and its model, and the name is also where
its file sits: `moog/matriarch` is `moog/matriarch.yaml`, in a folder named for
the maker. Each half is lower case, digits and underscores.

Definitions are looked for in three places, nearest first:

1. an `instruments/` folder beside your project,
2. your own library, one per person, so a definition you write once is found
   by every tool you run:
   - Linux: `~/.local/share/pymidiinstrumentdefs/` (or under `$XDG_DATA_HOME`)
   - macOS: `~/Library/Application Support/pymidiinstrumentdefs/`
   - Windows: `%APPDATA%\pymidiinstrumentdefs\`
3. the set bundled with this package.

So **a file you drop always beats one we shipped**. That is the whole answer to
adding your own synth: no index to edit, no registration, no pull request. To
describe your own synth, or to correct one of ours, write
`instruments/<maker>/<model>.yaml` beside your project. A definition is one
self-contained YAML file, and you share it by sending it.

### The bundled definitions

| Name | Instrument |
|------|------------|
| `ableton/move` | Ableton Move: no controls, because its maker states the absence - "MIDI CC, and MIDI mapping are not supported" - and the one controller it sends is All Sound Off on stop; built against its own manual, which is three years of releases out of date and says nothing about being so |
| `access/virus_ti` | Access Virus TI: four controls, each written a second time for a Multi part, because the maker's two manuals publish no control map at all - the 2006 one says the list is on its website and the 2013 one deletes even that sentence |
| `akai/mpc_key_37` | Akai MPC Key 37: one controller number, which is the mod wheel's factory default - the third definition out of one 530-sheet guide about fourteen machines, and the first to find anything in it |
| `akai/mpc_live` | Akai Professional MPC Live: two controls, 1 and 11, both received, because one user guide covers ten machines and every other controller number in it is one the owner assigns |
| `akai/mpc_live_iii` | Akai Professional MPC Live III: two controls, 1 and 11, both received, the first MPC Live's answer read again from its own guide - two machines in one book, every other controller number the owner's both ways, and a guide that says a fixed map exists three times without printing it |
| `akai/mpc_sample` | Akai Professional MPC Sample: no controls at all, because its maker publishes no controller number and the absence is proved rather than assumed |
| `akai/mpc_xl` | Akai Professional MPC XL: two controls, 1 and 11, both received, read from the MPC Live III's own book - the same answers in every field, and a panel of its own with four MIDI outputs, eight CV/Gate outputs and the one setting only it has, its footswitches |
| `alesis/sr_16` | Alesis SR-16: no controls, because a 72-page reference manual never names a controller - twelve pads on twelve notes it gives as defaults, a hundred drum sets by program change, and clock and start both ways with stop sent |
| `arturia/astrolab` | Arturia AstroLab: 37 controls off a table that gives a direction for every row in both directions - and a Section column that cannot be read as a grouping, because the rows are in controller-number order |
| `arturia/astrolab_37` | Arturia AstroLab 37: the AstroLab 61's table less its two looper rows, 35 controls unchanged from its 1.0.0 manual to its 2.0.0 one - and three pedal rows on an instrument with one pedal input |
| `arturia/drumbrute` | Arturia DrumBrute: publishes no controller number - its seventeen drum notes are one screenshot that both editions of its manual print, and its program change is in the firmware release notes and in no manual |
| `arturia/drumbrute_impact` | Arturia DrumBrute Impact: publishes no controller number at all - its drum map is the one set of numbers it states, and it states them inside a screenshot |
| `arturia/matrixbrute` | Arturia MatrixBrute: 80 controls on 78 numbers - two of them shared by an expression pedal and a macro knob, as its manual says - and 32 that can send 14-bit values on fine halves no page numbers |
| `arturia/microbrute` | Arturia MicroBrute: thirteen controls, every one of them a setting of an editor whose manual ships inside a software archive rather than on the downloads page |
| `arturia/microfreak` | Arturia MicroFreak: four paraphonic voices, and 21 controls out of a manual with no MIDI chart in it |
| `arturia/minifreak` | Arturia MiniFreak: six voices, twelve when paraphonic, and one control its manual never mentions that its firmware release notes do |
| `arturia/polybrute` | Arturia PolyBrute: 74 controls off a chart set as eighteen small tables three across, whose column positions shift from one block of rows to the next |
| `arturia/polybrute_12` | Arturia PolyBrute 12: the same 74-number chart as the PolyBrute, asserted against it number for number - plus controller 74, the MPE Slide dimension, which that chart does not list |
| `asm/hydrasynth_explorer` | ASM Hydrasynth Explorer: 112 controls off a chart its maker prints twice, once by module and once by number - and four more the maker puts on numbers the MIDI specification reserves for channel mode, which this format cannot hold |
| `asm/leviasynth` | ASM Leviasynth: 109 controls off a complete 128-row chart the maker prints three times across two manuals, all three agreeing row for row - and one definition covers the Desktop and the Keyboard because of it |
| `behringer/b2600` | Behringer 2600: a channel from 1 to 16 on four switches and one voice or two on another, and nothing else - a quick start guide with no table of MIDI messages is all its maker publishes, while its product page claims a comprehensive MIDI implementation, so no controller is recorded and none is declared absent |
| `behringer/deepmind_12` | Behringer DeepMind 12: 269 controls from a retailer's copy of Behringer's own manual, which Behringer does not serve - 105 controllers and 177 NRPNs, on one control only where both tables print one name, thirteen times |
| `behringer/edge` | Behringer EDGE: no controls and deliberately not `none` - everything its maker publishes for it is a quick start guide, and the 16-voice poly chain its page sells is documented nowhere but a diagram |
| `behringer/lm_drum` | Behringer LM DRUM: 17 controllers, all received, and sixteen drum notes from the manual for firmware 1.1.5 - the quick start guide in the box numbers six of them for other drums, from before every drum could be tuned - and each drum playable at pitch on a channel of its own |
| `behringer/model_d` | Behringer MODEL D: no control changes at all; its remote surface is SysEx |
| `behringer/neutron` | Behringer NEUTRON: two controllers, and the maker counts them for you - everything else this semi-modular answers to is system exclusive, and a note outside its stated range is clamped rather than silenced |
| `behringer/pro_800` | Behringer PRO-800: 70 controls out of a table whose six columns say what each number is - 34 of them 14-bit, paired to a fine half by name alone, at three different offsets and none of them the MIDI specification's |
| `behringer/rd_6` | Behringer RD-6: eight drums on eight fixed notes and eight voices at once, out of a quick start guide's MIDI message table that names no controller - `none` by enumeration, as for the TD-3 |
| `behringer/rd_9` | Behringer RD-9: eleven drum notes, ten voices at once, a start message and a SysEx dump, and no controls - a search of its whole 38-page manual finds no controller, the route the Model D's `none` takes |
| `behringer/td_3` | Behringer TD-3: no control changes either, established from the channel messages in the maker's own MIDI message table - its "Modded Out" sibling adds exactly one and needs a definition of its own |
| `behringer/td_3_mo` | Behringer TD-3-MO: the TD-3's MIDI message table with one row more - Filter Cutoff on controller 74, printed only in hexadecimal, the one control it answers to |
| `behringer/ub_xa` | Behringer UB-Xa: no controls, because the maker advertises a comprehensive MIDI implementation and publishes no part of one - two quick start guides covering two products name a controller number nowhere, and the keyboard's leaves its last two pages blank |
| `dirtywave/m8` | Dirtywave M8: no controls, because every continuous controller it answers to is one its player assigned - the maker prints "10 user defined CCs per instrument" on its own specification list, and the 128 CCs a third party publishes for it is the count of mapping slots a song can hold |
| `dreadbox/artemis` | Dreadbox Artemis: 85 controls out of a chapter of the manual rather than out of the standalone CC list, which is a firmware behind it - and one of them, number 31, decides what the 52 listed under it mean |
| `dreadbox/nymphes` | Dreadbox Nymphes: 82 controls read off two pages that are pictures, on an instrument whose maker ships with control change switched off |
| `dreadbox/typhon` | Dreadbox Typhon: 98 controllers out of a three-column list on two pages of the manual, which is the only place its maker publishes them - the standalone CC chart on the same download page belongs to a different instrument |
| `elektron/analog_four` | Elektron Analog Four: 229 controls off an appendix whose maker publishes it three times over, in which 157 parameters can be reached by NRPN and by nothing else |
| `elektron/analog_rytm_mkii` | Elektron Analog Rytm MKII: 99 controls of the 319 its appendix prints, because the other 220 are 32 machines' names for the same eight numbers |
| `elektron/digitakt` | Elektron Digitakt: eight audio tracks and eight that only send, with thirty controller numbers meaning more than one thing |
| `elektron/digitakt_ii` | Elektron Digitakt II: 144 controls off an appendix that numbers two of its own sections twice, and gives four pairs of parameters the same NRPN |
| `elektron/digitone` | Elektron Digitone: nine parts on nine MIDI channels, where one CC means three things |
| `elektron/digitone_ii` | Elektron Digitone II: 164 controls over sixteen tracks that each sound or send, sharing sixteen voices - and eleven NRPNs that mean one thing on an audio track and another on a MIDI track |
| `elektron/machinedrum` | Elektron Machinedrum: 71 controls, which is what its maker prints - sixteen tracks over four MIDI channels, of which it enumerates one track and abbreviates the other fifteen with an ellipsis |
| `elektron/model_cycles` | Elektron Model:Cycles: the Model:Samples' manual with a synth in it, where four of its 30 controls mean something different on each of six machines |
| `elektron/model_samples` | Elektron Model:Samples: 29 controls off a one-page appendix headed CC MSB that gives an LSB for exactly one of them |
| `elektron/octatrack` | Elektron Octatrack: two controller maps where 51 numbers mean different things, one file for the MKI and the MKII because their appendices agree row for row - and sixteen rows the maker puts on numbers the MIDI specification reserves for channel mode, which this format cannot hold |
| `elektron/syntakt` | Elektron Syntakt: twelve tracks and an FX track, where 28 controller numbers mean one thing on a track and another on the FX track |
| `elektron/tonverk` | Elektron Tonverk: 242 controls over sixteen tracks in four kinds - six controller numbers name one parameter on an audio track and another on the mix track, and 49 controls sit on a part of eight subtracks inside each audio track, whose NRPN MSB carries the 343 numbers the appendix generates by a rule rather than printing |
| `ensoniq/esq_1` | Ensoniq ESQ-1: two third-party scans of Ensoniq's own manual, read by eye - four controllers for the keyboard and the same four for each of eight sequencer tracks, which in MULTI mode each answer on a channel of their own |
| `erica_synths/hexdrums` | Erica Synths HexDrums: ten voices on ten consecutive notes and no controllers at all - the one instrument here whose maker says it chose not to have any, and says why |
| `erica_synths/perkons_hd_01` | Erica Synths PĒRKONS HD-01: 44 controls for its single-channel mode and eleven for the four voices of its multi-channel mode, off a manual reached through a news item - whose table and pictured settings file disagree on six of the eleven numbers of each voice the picture shows in full, and whose numbers a player can rewrite on the SD card |
| `erica_synths/steampipe` | Erica Synths Steampipe: eight voices, MPE, a clock for its LFOs, and no controls - its manual says every parameter answers to a controller on a mapping from the factory that its owner can change, and prints no table of it, so no controller is recorded and none is declared absent |
| `expressive_e/osmose` | Expressive E Osmose: an MPE instrument whose 24 voices each take a MIDI channel of their own, and which ignores velocity entirely |
| `groove_synthesis/third_wave` | Groove Synthesis 3rd Wave: 515 controls in two maps a setting chooses between - 102 controllers that name the keyboard's own knobs and buttons and its bank select, and 413 NRPNs that name the settings a program holds - from a specification that covers three models and gives each its own controller table |
| `groove_synthesis/third_wave_24m` | Groove Synthesis 3rd Wave 24M, the 24-voice desktop module: 518 controls in the same two maps - 100 controllers from a table that grew from the panel's knobs to numbers for each oscillator and envelope, and 418 NRPNs, five of them the desktop module's own |
| `groove_synthesis/third_wave_8m` | Groove Synthesis 3rd Wave 8M, the 8-voice desktop: 477 controls - 62 controllers and 415 NRPNs - two parts, and the only one of the three whose manual says it takes program change |
| `intellijel/cascadia` | Intellijel Cascadia: four controllers, and four is all there are - a semi-modular whose MIDI becomes a voltage at eight jacks, two of them driven by whichever controller its owner last taught it |
| `korg/drumlogue` | Korg drumlogue: 245 controls from its manual's **two** complete implementation charts, one for each mode - the alternate's twelve parts each take a channel, and 50 of its numbers mean more than one thing across them |
| `korg/electribe` | Korg electribe: 20 controls out of a plain text file that prints every number twice, with sixteen parts on one MIDI channel and no way given of choosing one |
| `korg/kronos` | Korg KRONOS: 87 controls, every one travelling both ways, out of a MIDI document that is prose rather than a chart - and 27 of them switched off on a new instrument until somebody loads them |
| `korg/m1` | Korg M1: four controls, each written a second time for a Multi timbre, because everything else about this 1988 workstation is reached by system exclusive - read by eye out of a 138-page scan with no text in it at all |
| `korg/microkorg` | Korg microKORG: 41 controller numbers that are the factory assignment and not fixed, each meaning one thing in a synth program and another in a vocoder one |
| `korg/microkorg2` | Korg microKORG2: 189 controls out of a maker who prints the same map three times, where the NRPN table gives six parameters one address and numbers two more twice over, and the manual's own pages are what put all eight right |
| `korg/minilogue` | Korg minilogue: 41 controls, thirteen of them switches whose named bands the maker gives twice over - as the values it sends and as the bands it reads them in - from an implementation its maker publishes as a plain text file and again, five years later, as a chart in the manual |
| `korg/minilogue_xd` | Korg minilogue xd: 60 controls and 61 NRPNs, out of a document that inverts two of them between sending and receiving |
| `korg/modwave_mk_ii` | Korg modwave mk II: one manual covers three models, and the only difference is the voice count - with a chart whose two direction columns had to be proved rather than read in order |
| `korg/monologue` | Korg monologue: 24 controls out of an implementation printed twice, one direction each, where two numbers are received only and one control's bands are the footnote the maker forgot |
| `korg/ms_20_mini` | Korg MS-20 mini: no controls, because the only MIDI this 1978 reissue accepts is notes on MIDI channel 1 with velocity disabled - and the maker says exactly that in one sentence |
| `korg/multi_poly` | Korg multi/poly: nine fixed controllers and twelve that are factory defaults, off a chart page three of whose spans are enciphered |
| `korg/nts_1` | Korg NTS-1 digital kit: 29 controllers both ways, off a text implementation and a chart that agree on every number, eight of them types whose every value sent falls in the band received |
| `korg/opsix` | Korg opsix: 30 controls off one chart page whose text is enciphered, five of them recognised and never sent |
| `korg/radias` | Korg RADIAS: 176 controls from two documents that each hold half the map - 57 panel controls at factory numbers only the owner's manual prints, joined by name to the value bands only the implementation prints, and 108 NRPNs from a 2005 implementation never revised for system 2.0 - over four timbres, a vocoder and a drum mode |
| `korg/triton` | Korg TRITON: 65 controls, the 41 controller numbers among them all travelling both ways, out of a text implementation shaped like the KRONOS's - one definition for the 61-, 76- and 88-key models, sixteen tracks, and an arpeggiator reached by NRPN |
| `korg/volca_bass` | Korg volca bass: 12 controls that only arrive, from an instrument with no MIDI Out jack - and three of them reach parameters its panel cannot, two of which its owner's manual never names |
| `korg/volca_beats` | Korg volca beats: 20 controls and ten parts off a plain text file, where the chart beside it draws its yes and no marks and names only seven of the ten |
| `korg/volca_drum` | Korg volca drum: both of its maker's charts, one for each mode - six parts on six MIDI channels out of the box, or six on one channel, each with nine numbers of its own |
| `korg/volca_fm` | Korg volca fm: eleven controls that only travel inwards, out of the first implementation in this corpus that is a plain text file - and a value table that disagrees with itself |
| `korg/volca_keys` | Korg volca keys: sixteen controls, all received, and a chart whose ticks and crosses are drawings - its own legend prints `: Yes` and `: No` with the symbols missing |
| `korg/volca_sample` | Korg volca sample: eleven controls off a chart whose ticks and crosses are drawings rather than text, so the only column that matters is invisible to a reader that extracts the page |
| `korg/wavestate` | Korg wavestate: 41 of its 50 controller numbers are defaults a player can reassign, and its maker publishes no control-change chart |
| `korg/wavestation` | Korg Wavestation: eight controls read by eye from three scans, from a chart and two appendices that disagree only about controller 7, which a 1991 addendum settles; sixteen channels in its multi mode, and five of the eight written again for them |
| `make_noise/zero_coast` | Make Noise 0-COAST: 19 controllers off a list whose maker says most of them are ignored unless the instrument is in a particular mode - and one row of which is not text at all but a drawing |
| `modal/carbon8m` | Modal CARBON8M: 106 controls, and a voice count set per patch |
| `moog/dfam` | Moog DFAM: no MIDI at all, and the file says so |
| `moog/grandmother` | Moog Grandmother: one voice, five controls in 14-bit pairs, and a value table of 24 clock divisions |
| `moog/labyrinth` | Moog Labyrinth: answers to notes, clock and transport, and nothing else |
| `moog/little_phatty` | Moog Little Phatty, the Stage II edition at 2.2: 52 controls sent and received, off the one table the Slim Phatty's is a copy of but for the value of a 16' octave - from the only manual Moog serves for it, part of whose text layer is shifted and was read by eye as well |
| `moog/matriarch` | Moog Matriarch: 37 controls, one of which only its firmware notes mention, and a voice count you can switch over MIDI |
| `moog/messenger` | Moog Messenger: 56 controls, 31 of them 14-bit pairs the specification's own way round, with every band named |
| `moog/minimoog_model_d` | Moog Minimoog Model D: one control, the fourteen-bit mod wheel on CC 1 and CC 33 - the only controller number in 84 pages, from a maker whose manual points at a SysEx document it no longer offers |
| `moog/minitaur` | Moog Minitaur: plays notes 0-72, with the firmware v2.1 corrections |
| `moog/mother_32` | Moog Mother-32: seven controllers, four of which reach no sound at all but a voltage at a jack the player patches |
| `moog/muse` | Moog Muse: 102 controls off one appendix that four documents print identically, two of whose rows are misprinted - and two timbres on two MIDI channels out of the box |
| `moog/slim_phatty` | Moog Slim Phatty: 52 controls off one table that gives every stepped setting's exact values - and the manual is older than the firmware Moog ships, whose notes add a controller this file leaves out |
| `moog/sub_37` | Moog Sub 37: 116 controls, every one of them the same as the Subsequent 37's, established by reading both charts rather than assumed |
| `moog/subharmonicon` | Moog Subharmonicon: reads a note as an offset from C4, not as a pitch, and answers to one controller its manual does not list |
| `moog/subsequent_37` | Moog Subsequent 37: 116 controls in CC and NRPN pairs, out of a chart whose empty cells were proved empty rather than unread |
| `moog/theremini` | Moog Theremini: 28 controllers received, off one table that its English and its German manual print alike, fifteen of them with a fine half - and two more that its antennas send, on numbers the owner chooses; neither manual names a channel it listens on or a note message |
| `native_instruments/maschine_plus` | Native Instruments MASCHINE+: two controller numbers in 243 pages, both of them ones the MIDI specification had already spoken for - every other one belongs to the owner, and the document that would hold them ships inside an application |
| `nord/lead_a1` | Nord Lead A1 and A1R: 61 controls off the manual's one list, sent and received on a Global channel where a parameter goes to whichever of its four Slots has the panel's focus - and seven standard controllers written again for a Slot on a channel of its own, which only receives |
| `novation/bass_station_ii` | Novation Bass Station II: 94 controls across three products that share one guide, and one controller number the guide prints that the MIDI specification says is something else |
| `novation/circuit` | Novation Circuit: 299 controls over two synths, four drums and a session, from a guide that prints seventy-four of its rows twice and leaves thirty-nine out - two of the eight macro knobs among them |
| `novation/circuit_rhythm` | Novation Circuit Rhythm: 74 controls over eight sample tracks and a project, out of the third Circuit here - where 64 of its numbers are also the Circuit's, only eleven of those mean the same thing, and the master filter moved |
| `novation/circuit_tracks` | Novation Circuit Tracks: 358 controls, the most here, over two synth tracks, four drum tracks, two MIDI tracks and a project - including eight the maker's contents page files as a table of values rather than of controls |
| `novation/mininova` | Novation MiniNova: 557 controls off a nine-sheet chart, where 105 answer to a controller number and the other 452 only to an NRPN, and no parameter to both |
| `novation/peak` | Novation Peak: 246 controls off two documents three firmware releases apart, 33 of which carry no default, because the maker's default column does not agree with itself |
| `novation/summit` | Novation Summit: 250 controls over two parts, sixty of them the fifteen Modulation Matrix slots its guide names with no controller number - blank in three editions of the guide, and numbered here from the manual of the Peak, whose engine the guide says it shares - and one more a noise filter its guide describes and its list leaves out, on the Peak's number too |
| `oberheim/ob_x8` | Oberheim OB-X8: 147 controls out of a user's guide that contains its own MIDI implementation, and contradicts itself about more things than any document here - including printing one page number twice |
| `oberheim/teo_5` | Oberheim TEO-5: 198 controls off an implementation document that says in its own words the map belongs to a Sequential synth |
| `polyend/tracker` | Polyend Tracker: 80 controls in two maps - the performance effects and mixer, and the selected instrument's own parameters, which answer only in its synthesiser mode - one of them a controller the manual's table drops and the instrument's own screen shows |
| `pwm/malevolent` | PWM Malevolent: from its quick-start guide alone, and says so |
| `roland/alpha_juno_2` | Roland αJUNO-2: five controllers off a 1986 implementation read by eye from Roland's own scan, carried as the implementation numbers them because its chart prints six controller numbers beside five lines |
| `roland/d_50` | Roland D-50: the manual twice sends you to a MIDI implementation chart that is not in it, so this carries no controls - only the two ranges its pedals may be set to send |
| `roland/fantom_6_7_8` | Roland FANTOM-6/7/8: 33 controls, every one of them the MIDI specification's own assignment under its own name, out of a 67-page implementation whose transmit section names five fewer than its receive section and says why |
| `roland/jd_08` | Roland JD-08: 85 controls over two parts, from the implementation chart at the back of its Reference Manual - which the HTML edition prints again row for row - and a system channel that selects patterns and passes notes to the selected part |
| `roland/jd_800` | Roland JD-800: seven controllers read by eye from two scanned 1991 manuals and written once for each of its three implementation charts that marks them, nineteen controls in all - only the five synth parts obey pan, and the special part's chart prints its controller numbers against the wrong names |
| `roland/jd_xa` | Roland JD-XA: 178 controls on three kinds of part - four analogue, four digital and the program - each on a channel of its own, where the same controller number means one thing on an analogue part and another on a digital one |
| `roland/jd_xi` | Roland JD-Xi: 98 controls over four parts on four fixed MIDI channels, 21 of them addressed by NRPN rather than by a controller number - the first Roland here whose NRPN is more than a crossed box |
| `roland/jp_8000` | Roland JP-8000: 50 controls on two parts and a performance channel, read by eye from a scanned manual - forty knobs at the numbers its second edit mode gives them from the factory, twelve of which its first mode sends as system exclusive instead |
| `roland/ju_06a` | Roland JU-06A: 63 controls in two modes, one for each page of an implementation chart whose pages are two whole maps - fifteen numbers in both and eleven of them meaning something else |
| `roland/juno_106` | Roland JUNO-106: two controller numbers in the whole instrument, and everything else it can be told is system exclusive |
| `roland/juno_x` | Roland JUNO-X: 33 controller numbers, 59 controls over two kinds of part, four of them with no heading in the implementation's transmission half and sent all the same by its chart and its address map - and 188 more rows of tone parameters in five other documents, with two lists of sixty for a tone's partials, counted and not carried, because what a number means there turns on the model a part holds |
| `roland/jupiter_x` | Roland JUPITER-X: 24 controllers, 41 controls over two kinds of part, from a 90-sheet implementation that holds none of its tone parameters - those are in the Parameter Guide, in six tables, where 28 numbers are given more than one name |
| `roland/jx_08` | Roland JX-08: 49 controls over two parts and a system channel that selects patterns, from the implementation chart at the back of its Reference Manual - which prints two names twice each, and has no row for one of the panel's two TUNE knobs |
| `roland/jx_8p` | Roland JX-8P: five controls read by eye from a scanned 1985 manual, behind four MIDI function switches that no page pairs with a message - and the switch table's footnote says a switch only stops sending, while the implementation says it stops receiving too |
| `roland/mc_101` | Roland MC-101: 28 controls over four tracks and a fifth MIDI channel that makes no sound, from a chart its maker publishes in numbered editions - of which the middle one is missing, so one firmware step was never printed |
| `roland/mc_707` | Roland MC-707: three editions of one chart served from one path, a control channel that makes no sound, and an effect send two documents put on two different numbers |
| `roland/p_6` | Roland P-6: 40 controls out of a list its implementation chart only points at - the chart names no controller number at all - and every one of them moved MIDI channel in the firmware this describes, from the auto channel alone to the granular sampler's as well |
| `roland/s_1` | Roland S-1: 54 controls out of two tables that each hold half the answer - a chart with ranges and no names, a list with names and no directions - and two of them told apart only by a drawn waveform |
| `roland/sh_4d` | Roland SH-4d: 32 controls off the first of three whole implementation charts its manual prints, where the other two cross control change entirely - so these are the four tone parts' controls and the rhythm part answers to none of them |
| `roland/sp_404mkii` | Roland SP-404MKII: 41 controls, seven of which the implementation chart publishes only inside a footnote - and one controller number that selects a different effect on each of three buses, so the same value means three things |
| `roland/tb_3` | Roland TB-3: fifteen controls off a one-sheet chart, seven of them confirmed by a second document that was written about system exclusive - the only controller numbers in this corpus published twice |
| `roland/tr8s` | Roland TR-8S: eleven voices of four controls, and two it only sends |
| `roland/tr_08` | Roland TR-08: 38 controls off a one-sheet chart, every number one the TR-8 uses and eleven of them under another name - 86 to 88 reach this machine's cowbell where the TR-8 has `RC` - and sixteen instruments over twenty-three notes that no single range describes |
| `roland/tr_1000` | Roland TR-1000: 66 controls off a real chart, which is nine firmware releases behind the instrument it describes |
| `roland/tr_6s` | Roland TR-6S: 34 controls, 33 of which are the TR-8S's - and one the TR-8S has not, named BEAT and explained nowhere |
| `roland/tr_707` | Roland TR-707: no controls, because its chart crosses the row - fifteen voices on factory note numbers the owner can change by playing a note at it, two settings for the numbers it sends in place of sounding, and clock, start, continue, stop, song position and song select both ways, read by eye from a scan in Roland's manual archive |
| `roland/tr_8` | Roland TR-8: 50 controls off a chart five firmware releases old, eleven instruments over seventeen contiguous notes, and three controls it obeys and never reports |
| `roland/tr_909` | Roland TR-909: no controls, because its maker's whole published MIDI is one page of a scanned manual that names seven kinds of message and not one number |
| `sequential/fourm` | Sequential Fourm: 100 controls out of two tables for one set of parameters, a controller and an NRPN apiece, which disagree about six of them and about which neither is reliably right |
| `sequential/pro_3` | Sequential Pro 3: 106 controllers by name, which is all its guide's table gives them, with fifteen global settings and the sequencer's play and stop by NRPN - and 308 program parameters by NRPN, which have a name and no range and say their range is unknown |
| `sequential/prophet_10` | Sequential Prophet-10: the Prophet-5's 85 controls, because its maker offers the Prophet-5's implementation for it, read again from the same file; ten voices, and since OS 2.0 two layers that nothing published says how to reach over MIDI |
| `sequential/prophet_5` | Sequential Prophet-5: 85 controls off a real MIDI implementation, which is also the Prophet-10's and is older than two of the instrument's own operating systems - 50 by controller number and NRPN both, 21 by NRPN alone |
| `sequential/prophet_6` | Sequential Prophet-6 keyboard and desktop module: 115 controls, most reachable by CC and by finer NRPN, from an appendix its maker prints three times over - twice in the English manual and once again in the German - with no two printings agreeing |
| `sequential/prophet_x` | Sequential Prophet X: 598 controls, because its NRPN table gives every one of 241 program parameters a number for each of its two layers - and its 90 controllers are not paired with them, since no page says which layer a controller reaches |
| `sequential/take_5` | Sequential Take 5: 170 controls, most reachable by CC and by finer NRPN |
| `soma/pulsar_23` | Soma Pulsar-23: every note and controller assigned by MIDI learn |
| `synthstrom_audible/deluge` | Synthstrom Audible Deluge: no fixed controller or note map at all, read from both of the guidebooks its maker publishes - one per display edition - whose last chapter turns out to be a reprint of a user-written guide |
| `teenage_engineering/ep_133_ko_ii` | teenage engineering EP–133 K.O. II: six controllers, bank select's two among them, and 48 pads, out of a web guide whose implementation chart says yes with a picture and no with a letter |
| `teenage_engineering/op_1` | teenage engineering OP-1: publishes no controller number at all - four incoming control changes are routed by the player, per sound |
| `teenage_engineering/op_1_field` | teenage engineering OP-1 field: 52 controls out of two forms of one guide, where the web page carries the whole MIDI reference and the downloadable PDF carries none of it - and the four controllers the page omits are in the PDF |
| `teenage_engineering/op_xy` | teenage engineering OP-XY: its maker publishes one guide twice, and the two editions give different numbers for the same row |
| `teenage_engineering/op_z` | teenage engineering OP-Z: 53 controls, every one of them from the guide's incoming MIDI table - what it sends is a number the player sets, parameter by parameter, and no page prints one before they do |
| `ten_ten_music/blackbox` | 1010music Blackbox: sixteen pads on a note map, each pad on a channel of its own if set, three named controllers and the rest learned - and a 16-note pool that two of its five pad modes stand outside |
| `udo_audio/super_6` | UDO Audio Super 6: 86 controls off the most complete implementation a new maker has brought here - every number from 0 to 127 given a row, and 41 of them carrying an NRPN that is the controller number plus 1024 |
| `vermona/drm1_mkiv` | Vermona DRM1 MkIV: a drum machine that ignores controller data |
| `vermona/perfourmer_mkii` | Vermona PERfourMER MKII: Vermona's own manual, from a retailer's copy - four synthesiser channels, each one voice and each assigned a MIDI channel, and CC 1 to the pulse width |
| `voce/electric_piano` | Voce ELECTRIC PIANO: 16 or 32 voices, depending on the chorus |
| `waldorf/blofeld` | Waldorf Blofeld: a chart with a row for all 128 controller numbers, sixteen of which are not controls - and one manual covering a Desktop with no MIDI out and a Keyboard with one |
| `waldorf/iridium` | Waldorf Iridium: no control map at all - almost every parameter is reached by MIDI learn, so what is here is the fifteen controller numbers the maker fixes, out of a manual two product pages serve as the same bytes |
| `waldorf/iridium_core` | Waldorf Iridium Core: the Iridium's fifteen fixed controllers, most other parameters by MIDI learn, two layers on one pool of twelve voices, and program change sent from a Macro button and received through the `Favorites` list on one FAQ entry the three Iridiums share |
| `waldorf/iridium_mk2` | Waldorf Iridium MK2: the Iridium's fifteen fixed controllers and Master Volume on 7, most other parameters by MIDI learn, four layers on one pool of sixteen voices, program change through the `Favorites` list on one FAQ entry the three Iridiums share, and MIDI 2.0 over USB, which the format has no field for |
| `waldorf/microwave` | Waldorf MicroWave, the rack of 1989 at software 2.0: five received controllers its chart and its manuals agree on, 1, 7, 10, 64 and 65, and four more whose numbers the owner sets - breath left out because the chart says 3 and the Programming Manual 2; Single mode, and a Multi mode of up to eight Instruments sharing eight voices, read by eye from Waldorf's own scans |
| `waldorf/protein` | Waldorf Protein: fifteen fixed modulation sources, a bank select LSB and MIDI learn for everything else, out of a manual whose MIDI chapter is a glossary of what MIDI is |
| `waldorf/streichfett` | Waldorf Streichfett: controls whose values are exact numbers, not bands |
| `yamaha/dx7` | Yamaha DX7: sends one set of controllers and answers to another, out of a 1983 manual that only exists as a scan |
| `yamaha/montage_6_7_8` | Yamaha MONTAGE6/7/8: 31 controller numbers over 16 parts, eleven of them written a second time for a part on its own channel, out of a Data List whose maker lists ten editions of it and serves two of those rows from one file - the map is unchanged across the three editions read, and fourteen of the numbers are the factory assignment rather than a fixture |
| `yamaha/reface_cp` | Yamaha reface CP: 18 controls out of the same data list as the reface DX, and the only one of its four instruments with a sostenuto and a soft pedal - it does no program change at all, where its sibling does |
| `yamaha/reface_cs` | Yamaha reface CS: 21 controls out of a Data List that covers four instruments in four self-contained sections - 17 of them answer only while a setting is on, and its pedal socket sends one of two controllers and never both |
| `yamaha/reface_dx` | Yamaha reface DX: 29 controls out of a data list covering four instruments, told apart by the system exclusive model identifier - and 25 of them answer only while MIDI Control is on |
| `yamaha/seqtrak` | Yamaha SEQTRAK: 42 controller numbers over eleven tracks, each on a fixed MIDI channel it cannot be moved from, written as 105 controls, most numbers once for each kind of track they reach - every number and direction is in the Data List, under its own names, and the User Guide adds which tracks most of them reach |

The set is a starting point rather than a catalogue. `moog/dfam` is five lines,
because the DFAM has no MIDI at all and saying so is worth more than saying
nothing. Three others - the Labyrinth, the MODEL D and the DRM1 - are nearly
as short for the same reason: somebody read the whole manual and found no
control changes, and the file records that it looked.

### Starting from a MIDNAM file

If your instrument has a `.midnam` file - Ardour bundles several hundred -
`pymidiinstrumentdefs.midnam` will start a definition from it:

```python
import pymidiinstrumentdefs.midnam

draft = pymidiinstrumentdefs.midnam.read_file("Moog_Minitaur.midnam")

pymidiinstrumentdefs.midnam.suggested_name(draft)   # 'moog_music/minitaur'
print(pymidiinstrumentdefs.midnam.to_yaml(draft))
```

What that lands is a **draft**, and it says so in its own first line. MIDNAM
carries a control map and nothing else - no polyphony, no note range, no
velocity response - and the numbers it does carry are worth checking against
the manual. It stays marked `unverified` until you replace the `source` line
with what you checked it against.

**This is not how the bundled definitions were made.** Those came from manuals,
and none of them is an import. [Sources](#sources) measures how far a `.midnam`
can be trusted, on the one instrument where both can be compared.

## Sources

**A definition is only as good as its `source` line, and that line is the
authority - not this README.**

```python
matriarch = pymidiinstrumentdefs.load("moog/matriarch")

matriarch.source        # the manual and the pages, in the file's own words
matriarch.sources       # the same, in fields: edition, address, SHA-256, page offset
matriarch.is_unverified # True if nobody has checked it yet
matriarch.warnings      # what the validator thought worth saying
```

The definitions bundled here were read out of **manufacturers' own
documents**, page by page, and each names the document and the pages it came
from. Usually that is the user manual. For the TR-8S and the Take 5 it is the
maker's MIDI implementation document, and for the Malevolent a quick-start
guide, because that is all there is, and its file keeps to what the guide says. Two were checked against a second source as well: the
Minitaur against Moog's firmware v2.1 addendum, and the DRM1's note map against
a working implementation of the same machine. The MiniFreak's second source is the
maker's own firmware release notes, which carry one control - CC 7, volume - that
its manual never mentions, and the file says so where it records it.

**None of them was imported from a `.midnam` file, and none ever will be.** The
importer is a tool for starting a definition of *your* instrument; it is not
where ours come from.

Three tests hold that line, so it is a property of the package rather than a
promise in a README: one refuses to ship a definition that does not name a
document and cite pages, one refuses anything still marked `unverified`, and one
refuses anything the importer wrote.

The Minitaur is the worked example of why that second source matters. Its
manual prints the key-priority bands as `0-42`, `43-84`, `87-127` - leaving 85
and 86 assigned to nothing - and the firmware addendum corrects the third band
to **86**. This package carries 86, and the file says why it differs from the
printed table. That is the level of care every bundled definition is held to,
and it is why a `source` line records pages rather than saying "the manual".

**Anything imported is a draft, and is not held to that at all.**
`pymidiinstrumentdefs.midnam` starts a definition from a `.midnam` file, and
what it lands says `imported from <file>, unverified` in its own source line,
keeps saying it, and is reported by the validator until a person replaces it.

That is not a reason to avoid importing - it is a good way to start and a poor
place to stop, and it is worth being precise about which. Comparing the widely
shared `Moog_Minitaur.midnam` against the same instrument's manual and firmware
addendum, on the one instrument where this package holds both:

- **all 37 control-change numbers agree**, and
- **all 17 14-bit pairings agree**, which is the tedious half of a definition and
  the half most easily mistyped by hand;
- **4 of the 11 comparable band boundaries differ**, including the key-priority
  band it gives as `85` where the manual says `87` and the addendum says `86`.

None of those four changes what gets *sent*, because a band is transmitted as its
midpoint rather than its edge. They do change what gets *read back*: ask that
imported definition what a value of 85 means on key priority and it says `last`,
where the corrected file says `high`. So an import is reliable about which
controller does what, and not yet reliable about what its values mean.

**And a definition you supply yourself is yours.** Files you drop beside your
project or into your own library beat the ones bundled here, by design, and
this package makes no claim about where their numbers came from.

**Writing one, and want the numbers to be right?**
[docs/adding-an-instrument.md](docs/adding-an-instrument.md) is the long answer:
where makers actually publish, which kinds of source can be the only source for a
fact and which can do no more than disagree with you, how to tell which firmware a
document describes when its own date will not tell you, and how to cite it so that a
stranger can check every number in the file.

## History

These definitions, the loader and the importer were first published inside
PyMidiDefs 0.4.0, as `pymididefs.instruments`, and moved here so that
specification constants and instrument reports can be released separately.
PyMidiDefs' own history up to that point is in its repository, ending at
commit `4abf367`.

## License

MIT - you are free to use, copy, modify, merge, publish, distribute,
sublicense, and sell copies of this software in any project, including
commercial and closed-source applications. The only requirement is that you
include the LICENSE file when redistributing the software. See
[LICENSE](https://github.com/simonholliday/PyMidiInstrumentDefs/blob/main/LICENSE)
for the full text.
