Cubase-MCP-GAJ3T.MusicGen.R.../docs/articulation-mappings.md

569 lines
37 KiB
Markdown

# Instrument profile and event-intention contract
## Status and evidence boundary
Correction iteration 4 now admits **five Documented default capabilities**:
AGLP/AGM/AGT/AME Lead Sustain/PalmMute, and ABJ Bass **Sustain only**.
AMR and SD3 remain `mapping_unavailable`; ABJ PalmMute explicitly fails
`unsupported_articulation`, not a guessed PM/Dead Note velocity transform.
Published manuals plus vendor demo MIDI provide genuine numeric anchors;
switch timing/routing are disclosed writer policies, not vendor-certified limits.
`Documented` means source-backed defaults, **not installed-plugin acceptance**.
`Verified` remains the application-verified stage; zero shipped profiles have
that status. `Unverified` and `Synthetic` are rejected in production.
Full requested-product/application readiness remains **false / BLOCKED**.
See [the compatibility inventory](format-compatibility.md).
## Declared instrument catalog (correction iteration 2)
The owner requested six Ample targets, plus the existing SD3 target. Immutable
Core `InstrumentDefinition` contains only `id`, string `vendor`, `productCode`,
`displayName`, the existing `role`, and `documentationUrl`. It deliberately has
no fabricated version, playable range, controls or native capabilities.
| ID | Vendor | Code | Display name | Role | Official documentation |
| --- | --- | --- | --- | --- | --- |
| `ample-abj` | Ample Sound | ABJ | Ample Bass J | Bass | [ABJ manual](https://www.amplesound.net/en/Main_Panel_Manual-ABJ.pdf) |
| `ample-aglp` | Ample Sound | AGLP | Ample Guitar LP | Lead | [AGLP manual](https://www.amplesound.net/en/Main_Panel_Manual-AGLP.pdf) |
| `ample-agm` | Ample Sound | AGM | Ample Guitar M | Lead | [AGM manual](https://www.amplesound.net/en/Main_Panel_Manual-AGM.pdf) |
| `ample-agt` | Ample Sound | AGT | Ample Guitar T | Lead | [AGT manual](https://www.amplesound.net/en/Main_Panel_Manual-AGT.pdf) |
| `ample-ame` | Ample Sound | AME | Ample Metal Eclipse | Lead | [AME manual](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf) |
| `ample-amr` | Ample Sound | AMR | Ample Metal Ray5 | Bass | [AMR manual](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf) |
| `toontrack-sd3` | Toontrack | SD3 | Superior Drummer 3 | Drums | [SD3 manual](https://www.toontrack.com/manual/superior-drummer-3/) |
Names/manual URLs were confirmed through the official rendered website in the
approved correction. Identities are not proof of installation or mapping.
The owner's folder screenshot establishes neither versions, directory paths nor
maps. Acoustic guitars occupy the existing Lead/guitar slot; no new track roles,
extra slots, strumming patterns or per-product articulation assumptions.
Generation `InstrumentCatalog.LoadEmbedded()` reads `Instruments\instruments.json`
independently of cwd, ordered by ordinal ID. `Find(id)` uses exact IDs and returns
null when unknown; `ForRole(role)` returns an immutable filtered list, rejecting
undefined roles. IDs/codes must contain only nonempty ASCII letters/digits,
dash/underscore/dot. Vendor/display name must be nonempty, trimmed and free of
control characters. Documentation URLs must be absolute HTTP(S), without
credentials or whitespace. Duplicate IDs and duplicate vendor/code or vendor/name
identities are invalid; versions belong in profiles, not duplicate definitions.
The profile catalog's immutable joined `Instruments` entries expose `Instrument`,
matching versioned `Profiles`, and derived `Availability`:
- `mapping_unavailable`: no admitted Documented/Verified mapping exists.
- `profile_available`: at least one admitted Documented/Verified mapping exists.
Neither status asserts native writer support, installed plugins, supported
extensions, or application/Cubase acceptance. All four guitars and Sustain-only
ABJ are available under the scope below; AMR and SD3 remain unavailable. Step 8 exposes
`list_instrument_profiles` and `generate_project` with this same bounded evidence
scope and explicit selection; native writers and application verification remain absent.
### Adding another instrument as data
1. Add a JSON definition with a unique ID and identity to
`Generation\Instruments\instruments.json`, with a real documentation URL and
one existing role. Vendor is data, not a product/vendor enum.
2. After authorized documentation review or actual application verification,
add profiles to `Generation\Profiles\instrument-profiles.json`. Each needs a
unique profile ID, required `instrumentId` referencing the definition, matching
role and exact `productName == displayName`, honest product-version scope,
independent mapping revision, evidence and all mapping fields below.
Documented profiles also require explicit compatibility notes.
Multiple versions share an instrument
ID, not a profile ID. Do not fill mapping gaps with test fixture numbers.
3. Run catalog/profile/planner tests, rebuild and publish: resources are embedded.
There are no runtime directories, hot reload, VST scanning/loading, reflection
plugins or external services. Existing mechanisms need no subclass, product
switch or engine change. New mechanisms still require separately reviewed work.
Test-only JSON fixtures add extra vendor-neutral targets and two versions for
one target; selection and the unchanged planner consume both. Their invented
`Verified` evidence exercises admission validation only, not application truth.
They live solely in the test assembly. Production still rejects `Synthetic` and
`Unverified` profiles, even when every other field/binding is valid.
Future native writers remain format-based, not per-instrument hierarchies; no
writer implementation or unverified shared Ample native format is implied.
## Additional evidenced capabilities (correction iteration 4, 2026-10-20)
All five IDs end in `-documented-defaults-2026-10-20`, with instrument prefixes
`ample-aglp`, `ample-agm`, `ample-agt`, `ample-ame` and `ample-abj`.
No role default is authorized; each selected role requires an explicit ID.
| New profile prefix | Articulations | Absolute switch/range | Musical velocities | Route |
| --- | --- | --- | --- | --- |
| `ample-agm` | Sustain, PalmMute | 24/26; 40-84 | Sustain 1-126, PM 1-127 | Lead channel 0 |
| `ample-agt` | Sustain, PalmMute | 24/26; 40-84 | Sustain 1-126, PM 1-127 | Lead channel 0 |
| `ample-abj` | **Sustain only** | 24; 35-76 | Sustain 1-125; 126-127 are excluded accents | Bass channel 1 |
These extend, not alter, the AGLP/AME numeric rules and source records below.
They share unknown-initial-articulation initialization and the explicit
velocity-100/120-tick advance/30-tick pulse writer policy. Source/demo timing
is **not** a certified pulse minimum or latency measurement. Bass channel 1
(display channel 2) is a project routing policy, not the demo's channel 0.
Default tuning/mapping/velocity thresholds, instrument mode, MIDI Guitar mode
off and an isolated idle receiver remain required. Full installed/application
acceptance is still unverified.
### AGM: direct numeric switches
The rendered [official download page](https://www.amplesound.net/en/download.asp)
publicly lists both AGM projects:
- [AGM-Rylynn.zip](https://www.amplesound.net/dl0822/ds/AGM-Rylynn.zip),
HTTP Last-Modified 2019-06-11 17:57:25 GMT,
SHA256 `e88c40ce4e67fde7b692b7f1cd5c4d057d7cd2a50e21d71114379b55d1fabd6f`.
Entry `AGM-Rylynn/AGM3-Rylynn.mid`, 480 PPQ, zero-based track 1 "G1",
channel 0: note 24/velocity 80 on 32215/off 32335.
- [AGM-Dear_Ben.zip](https://www.amplesound.net/dl0822/ds/AGM-Dear_Ben.zip),
HTTP Last-Modified 2019-11-24 16:38:43 GMT,
SHA256 `bb6dd773b5f998a1d0efa80ebc77d6661922e49f137f74a685000792ed618fe5`.
Entry `AGM-Dear Ben/AGM-Dear Ben Tempo 74.mid`, 480 PPQ, track 1
"AGM ARP", channel 0: note 26/velocity 80 on 28798/off 28858;
note 24/velocity 80 on 30238/off 30298.
Together with AGM manual pp.6-7 §§2.2.1-2.2.4 (revision/hash below), these
anchor C0=24, D0=26, E1-C5=40-84; Sustain 1-126 excludes Pop at 127.
PM musical velocity 1-127 controls mute depth without a guessed transformation.
### ABJ: vendor-listed shared source, deliberately Sustain only
The official download row explicitly lists products **ABJ ABP** for
[AB-Articulations.zip](https://www.amplesound.net/dl0822/ds/AB-Articulations.zip).
HTTP Last-Modified 2019-06-11 17:32:45 GMT,
SHA256 `c3efc1dc787c59a00be7405687488317efaf952822aededf54b9e19f4e145cb7`.
Entry `AB-Articulations/4.2 Articulations & Poly Legato.mid`, 480 PPQ,
track 1 is named **ABP**, channel 0: note 24/velocity 90 on 3720/off 4080;
musical note 40/velocity 90 on 3840. This is vendor-listed shared applicability,
**not** an independently ABJ-named performance or an inferred AMR mapping.
ABJ manual pp.6-7 §§2.2.1-2.2.4 documents C0, B0-E4 and Sustain 1-125;
the numeric anchor yields switch 24/range 35-76.
The dedicated D0 PalmMute/Dead Note split still lacks its numeric threshold.
That blocks **PM**, not an otherwise supported Sustain-only capability.
Discovery advertises only Sustain; requested ABJ PM fails explicitly with no
file/partial arrangement. No fixed velocity, Sustain fallback or PM rule is
invented. AMR does not inherit this ABJ/ABP source.
### AGT: confirmed named tab-play anchor, not a direct articulation performance
The concrete lead was confirmed in the rendered official
[Tab Player documentation](https://www.amplesound.net/en/tutorial-b.asp),
§6.3 **Tab Play Toggle**: MIDI note **A6** controls tab play (high velocity on,
low velocity off). Retrieved 2026-10-20; no HTTP Last-Modified header;
HTML SHA256 `542ae25caec1dfea772fbe9f5cc80be0c12ad3104f057e654410226aa1e69e92`.
This is the vendor's historical applicable Tab Player documentation, not
a note name supplied by our MIDI library or an assumed octave convention.
The official download row identifies "Tab Project - Wish You Were Here",
products **AGT AGM**, linking
[AGT-Wish_You_Were_Here.zip](https://www.amplesound.net/dl0822/ds/AGT-Wish_You_Were_Here.zip).
HTTP Last-Modified 2019-06-11 18:04:59 GMT,
SHA256 `82a9b42109519d20d9340c6c6cdb972a66663482df483fd0bf5034b84b5d9262`.
The exact entry is `AGT-Wish_You_Were_Here/AGT3-Wish You Were Here Tempo 62.mid`
(underscores in the directory), 480 PPQ. Tracks 1 "Solo" and 2 "Strum" each
contain only note 105/velocity 80, channel 0, on 3840/off 4320.
Matching that tab-play control to the documented named A6 establishes
`C0 = 105 - (6*12 + 9) = 24`, hence D0=26 and E1-C5=40-84 from the reviewed
AGT main-panel table. This is **not** a direct Sustain/PM performance.
Historical source and non-versioned current main-panel revisions are recorded
separately from an unknown installed release. The generated profile does not
trigger Tab Player or emit note 105.
All four ZIP MIDI streams were re-read with pinned DryWetMIDI 8.0.3; archives,
MIDI, manuals and other vendor entries were not retained. No helper package,
product installation, native-file inspection or access-control bypass was needed.
AMR has no public demo among the nine inspected official rows; no invented URL,
cross-bass substitution or open-ended search was attempted. SD3 stays unavailable.
Built and refreshed published RPC tests exercise every Lead with ABJ, shared
lead-in, separate channels/tracks, exact notes/controls and one fallback artifact.
## Documentation-backed defaults (correction iteration 3, 2026-10-20)
This initial AGLP/AME source record is retained. The newly resolved AGM/AGT/ABJ
anchors above supersede the original inventory's missing-anchor conclusions.
### Published numeric facts and admitted subset
| Profile ID | Source mapping | Absolute pitches | Musical velocity constraints |
| --- | --- | --- | --- |
| `ample-aglp-documented-defaults-2026-10-20` | AGLP manual PDF pp.6-7, §§2.2.1, 2.2.3, 2.2.5 | Sustain C0 = 24, PM D0 = 26; E1-D5 = 40-86 | Sustain 1-126 (127 is Pop/Pinch Harmonic depending on settings); PM 1-127, lower velocity increases mute depth |
| `ample-ame-documented-defaults-2026-10-20` | AME manual PDF pp.6-7, §§2.2.1-2.2.4 | Sustain C0 = 24, PM D0 = 26; C1-C5 = 36-84 | Sustain 64-126 only (1-15 full mute, 16-31 three-quarter, 32-63 half; 127 Pop/Pinch Harmonic); PM 1-127, lower velocity increases mute depth |
Neither conversion starts with an assumed octave convention. The official
[download page](https://www.amplesound.net/en/download.asp), inspected rendered,
links these vendor-authored demo archives (read in memory, not redistributed):
- [AGLP-Prison_Break.zip](https://www.amplesound.net/dl0822/ds/AGLP-Prison_Break.zip):
HTTP Last-Modified 2019-11-24 16:33:18 GMT;
SHA256 `738956bced4e78a00ab755646d34108f9e25c5346ef79b96a5c1664c876f5e5f`.
`AGLP-Prison Break/AGLP-Prison Break-Tempo100.mid`, 480 PPQ, zero-based
track 1: switch 24, velocity 100, on tick 3837/off 3957; track 3:
switch 26, velocity 100, on 34438/off 34558. These are the actual numeric
C0/D0 anchors for the manual's switch labels.
- [AME-Eclipse.zip](https://www.amplesound.net/dl0822/ds/AME-Eclipse.zip):
HTTP Last-Modified 2019-11-24 17:03:34 GMT;
SHA256 `e448d85f9ff80692f625f23ef6ea4dd0b14367b9f92412adbb76aa6e4a987f66`.
`AME-Eclipse/AME-Eclipse-Tempo130.mid`, 480 PPQ, zero-based track 4:
switch 24, velocity 100, on 3720/off 3840, musical C1 pitch 36 at 3840.
C0=24 anchors the manual's D0 two semitones above (26) and C1-C5 (36-84).
Its `1 Channel` variant also contains switch 24.
Existing pinned DryWetMIDI 8.0.3 read the demo streams; no parallel MIDI parser,
copied demo, sample library or native content was retained. The public
[third-party Eclipse map](https://github.com/zaibuyidao/ReaScripts/blob/98e88777ff4cf2e478d6bc85d35349f62acc7e41/Various/Articulation%20Map/banks/70-96%20Ample%20Metal%20Eclipse%20%28%E9%87%91%E5%B1%9E%E5%90%89%E4%BB%96%29.reabank)
(blob `ea878807ac429bd7294b9f8a8612a9261feacb4f`) corroborates 24/26 only.
Its implementation and velocity interpretations are not copied or substituted
for vendor evidence. The public Reaticulate Rickenbacker bank also uses 24/26,
but a different product does not establish the missing targets' numeric anchors.
### Source revisions and remaining gaps
Retrieved 2026-10-20 from each catalog URL. Manuals are **non-versioned**; HTTP
timestamps/hashes identify source revisions, not installed product versions.
`productVersion` explicitly says documented defaults/installed version unknown;
`mappingVersion` is our `published-defaults-2026-10-20.1` data revision.
| Manual | HTTP Last-Modified (GMT) | SHA256 |
| --- | --- | --- |
| [ABJ](https://www.amplesound.net/en/Main_Panel_Manual-ABJ.pdf) | 2025-04-16 05:04:25 | `9291c4e3027ac1469bd845bb04614f5a2754bd35a4f017bcfd7cdb75db335e7e` |
| [AGLP](https://www.amplesound.net/en/Main_Panel_Manual-AGLP.pdf) | 2025-09-08 09:00:15 | `7b28b62f3c25ecb774227b15beab06f5e0f0c944f35db9e82121028017f9cedb` |
| [AGM](https://www.amplesound.net/en/Main_Panel_Manual-AGM.pdf) | 2025-09-08 09:00:15 | `449bd7b8bca7771dbf8e08e0029d2bbe999f991efe441d7900ee93da29dd86a4` |
| [AGT](https://www.amplesound.net/en/Main_Panel_Manual-AGT.pdf) | 2025-09-08 09:00:02 | `2e5696d750841a47061d37737ec7d8435cb4e30756cda15596d1f89ff87810dd` |
| [AME](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf) | 2025-09-08 09:00:39 | `ab482f08b0546eca0a4233b8be3776c411b77f3dca96979f529debc2dfc0c4ca` |
| [AMR](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf) | 2025-04-16 05:04:22 | `833115ed9d650d9d7dc0a60695a5405f2dca8cf7f0e3e4b7c7bbf6e0baa65428` |
| [Settings/CPC](https://www.amplesound.net/en/Settings_and_CPCv2.pdf) | 2026-06-16 17:25:14 | `d36c4bed2d24da060588230ea7526b7a08fb9346a8b00d8adb622eaecc36bce3` |
- ABJ pp.6-7 §§2.2.1-2.2.4: Sustain C0, B0-E4, velocities 1-125;
126-127 Accent; PM D0, E1-D4, high-velocity PM/low-velocity dead notes,
but **no numeric dividing threshold**. No product-specific absolute anchor
was established in iteration 3. Iteration 4 above resolves the Sustain anchor
using the explicitly shared ABJ/ABP demo; dedicated PM remains unsupported.
- AGM pp.6-7 §§2.2.1-2.2.4 and AGT pp.6-7 §§2.2.1-2.2.4:
Sustain C0/PM D0, both E1-C5; sustain 1-126, 127 Pop; PM depth follows
velocity. No product-specific numeric anchor obtained in this bounded pass.
Iteration 4 above resolves AGM via direct switches and AGT via named A6=105;
shared vendor note labels alone were not used as numeric evidence.
- AMR pp.6-7 §§2.2.1-2.2.4: Sustain C0 A0-E4, 64-126 Sustain/127 Accent,
32-63 PM/1-31 dead; dedicated PM D0 B0-E4 has an unspecified high/low split.
No product-specific numeric anchor established. The PDF calls itself
"Ample Metal R"; the catalog retains the vendor site's Ray5 identity.
Unavailable; a future supported velocity-only subset still needs that anchor.
- Settings/CPC pp.7-9 §§1.2.2-1.2.9 documents single/per-string channels,
MIDI Guitar mode, configurable velocity thresholds and accent settings;
pp.14-15 §1.5 documents user CC assignments. No standard numeric C0
anchor or keyswitch pulse minimum was found. These settings constrain scope,
not justify invented CCs or plugin-certified timing.
- [SD3 manual](https://www.toontrack.com/manual/superior-drummer-3/):
simplified fetch **and rendered page** require login; stopped without bypass.
The accessible vendor-hosted
[Example-Layout.pdf](https://www.toontrack.com/app/uploads/topic/how-can-i-use-midi-or-notaion-created-in-notion-6-to-drive-superior-drummer/pdf/Example-Layout.pdf),
page 1, is a rendered SD3 **Hansa - Marble Room** layout, not a documented
universal/core default map. It explicitly shows Kick Open 36, Snare Center
38, Hi-Hat Closed Tip 42 (and C0=24 in that diagram). HTTP Last-Modified
2026-03-04 08:25:19 GMT. It is a forum attachment; default-state authorship,
core-library applicability, velocity and controller assumptions are not
established. Public forum search corroborates 36/38/42; visible topic
bodies/replies are login-limited. Do **not** promote this Hansa-specific
example or General MIDI convention into an SD3 core/installed map. SD3 stays
unavailable. Needed: authorized default layout for the chosen library/map,
velocity/hi-hat control scope, and installed configuration/application checks.
All six official main-panel PDFs and Settings/CPC were consulted, not just
search summaries. Rendered vendor links supplied what simplified fetch omitted.
No products were installed, private directories scanned, credentials requested,
access controls bypassed, or manual/native assets retained.
### Compatibility policies, not published requirements
The admitted guitar profiles require default tuning/mapping/velocity thresholds,
instrument (not Strummer) mode, MIDI Guitar mode off, and an isolated idle receiver
with no external held keyswitches or custom remapping. They use no guessed CCs,
program changes or per-string routing. Lead routes on zero-based channel 0
(display channel 1); the host must route/accept it explicitly.
At 960 PPQ, use switch velocity 100 (present in vendor examples), **120 ticks
advance/30 ticks pulse**. Advance/pulse are conservative deterministic writer
policies, not measured/certified vendor minimums. They are tempo-relative,
not a promise of real-plugin latency compensation; the 480-PPQ demo timings
are evidence of pulses, not the selected writer timing. Switches release before
musical onset. Unknown initial articulation (`null`) selects **only the first
requested state**, never an unconditional Sustain-plus-PM combination.
Repeated latches suppress duplicates; incompatible overlapping state windows
fail rather than change timing. No final articulation reset is guessed; every
emitted switch is released and the last selection stays latched.
`DocumentedProfileMidiTests` exercises all five admitted capabilities, first Sustain/PM
where supported (ABJ Sustain only),
numeric pitch/velocity boundaries, repeated latching and transitions through
actual file writing/read-back, checking channels/order/timing/pairing and
source immutability. These are source/format tests, not audible plugin checks.
## Earlier vendor documentation and screenshot review (2026-10-20)
The following records the earlier limited review; the anchored subset and
current admission decisions above supersede its former empty-catalog gate.
The official manual links were discovered through Ample's rendered website and
the PDFs were read locally. The earlier simplified HTML retrieval did not expose
these links; that was a retrieval limitation, not evidence that documentation
was unavailable. Documentation research is the assistant's responsibility;
the owner need not reconstruct published mappings through tooltip screenshots.
Primary sources:
- [Ample Metal Eclipse main-panel manual](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf),
sections 2.2.1-2.2.4 (PDF pages 6-7).
- [Ample Metal Ray5 main-panel manual](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf),
sections 2.2.1-2.2.4 (PDF pages 6-7). This is the vendor's documented Ray5
target; the owner's installed bass identity/version is not yet confirmed.
- [Ample Riffer 4 manual](https://www.amplesound.net/en/Guitar_Riffer.pdf),
section 4.4.3 (PDF page 28).
Both instrument manuals label Sustain with keyswitch C0 and Palm Mute with D0.
The owner's Eclipse screenshots corroborate those labels and identify the open
instrument as Ample Metal Eclipse. They also show Natural Harmonic C#0,
Slide In/Out D#0, Legato Slide E0, Hammer-On/Pull-Off F0, Tap F#0 and
Pinch Harmonic G0. Recording these labels does not implement extra articulations.
Eclipse's documented Sustain selection uses note velocities 1-15 for full mute,
16-31 for three-quarter mute, 32-63 for half mute and 64-126 for sustain;
velocity 127 has a settings-dependent accent effect. Palm Mute depth increases
as velocity decreases. The owner's tooltip calls the high-velocity effect
Accent; the manual describes Pop/Pinch Harmonic depending on settings. Do not
assume those version/settings-dependent effects are identical.
Ray5's documented Sustain selection uses 1-31 for dead notes, 32-63 for palm
mute and 64-126 for sustain, with accent at 127. Its dedicated D0 selection
also distinguishes high-velocity palm mute from low-velocity dead notes, but
the cited paragraph does not give a numeric threshold for that split.
These are vendor note labels and documented velocity facts, not a verified
conversion of C0 to an absolute MIDI number. The reviewed sections do not
establish all switch velocities, lead times, pulse/hold durations, initial
state or release behavior required by the current profile contract. Do not
fill such fields with invented constants or confuse documented defaults
with verification of the owner's installed configuration.
Riffer documents SMF type 0/1 import with only one track. A combined multi-role
Cubase MIDI arrangement must therefore not be assumed directly importable into
Riffer. This is a MIDI import capability, not an AGP serialization specification.
The [SD3 online manual](https://www.toontrack.com/manual/superior-drummer-3/)
still requires login in the available browser session. No account credentials
are needed or requested; selected SD3 library/map and any custom overrides
remain unresolved. Native AGP/SDP schemas and application acceptance remain
separate gates. No production catalog data changed during that earlier review.
The generic mechanism fixtures are invented **Synthetic** test/pipeline/catalog
identities, not vendor mappings or acceptance evidence. No synthetic profiles
are embedded in production. New documented-profile tests separately exercise
the admitted vendor facts above. Step 8's two MCP tools expose only admitted
production profiles and actual MIDI/fallback output, never synthetic fixtures.
## In-process boundaries
- Core `InstrumentProfileValidator.Validate(profile)` rejects unverified and
synthetic profiles by default. `allowSynthetic: true` is an explicit testing
opt-in; it does not bless unverified profiles or bypass other validation.
- Core `ArticulationPlanner.Plan(composition, profiles)` revalidates its input
composition and explicit profiles, returning either a complete immutable
`MidiEventPlan` or diagnostics and a null plan. It never mutates the composition.
- Generation `InstrumentProfileCatalog.LoadEmbedded()` loads only the assembly
resources, cross-validating every profile against the declared identity, role
and exact product name. Dangling references or mismatches fail the whole load.
The stream parsers are internal
and exposed to unit tests only. There is no filesystem/network profile discovery,
vendor scanning, runtime editor or plugin system.
- `catalog.Select(role, id)` requires an exact matching role/ID. A missing ID
reports `no_default_profile`; an unknown ID reports `unknown_profile`, and an
existing wrong-role ID reports `profile_role_mismatch`. No
defaults are currently authorized and there is no synthetic/sustain fallback.
- `catalog.SelectInstrument(role, instrumentId, profileId?)` distinguishes
`unknown_instrument`, `instrument_role_mismatch`, `mapping_unavailable`,
`unknown_profile`, `profile_role_mismatch`, `profile_instrument_mismatch` and
`ambiguous_profile`. A known instrument with one admitted candidate can select
it; multiple candidates require an explicit exact profile ID, never the first
item or another guitar/bass. An explicitly empty profile ID fails as
`no_default_profile`; no instrument/profile defaults are silently substituted.
- A missing, malformed or invalid embedded resource throws `InvalidDataException`,
not a successful empty catalog. JSON uses camel-case property names and string
enums, requires every non-optional constructor field (including explicit nullable fields),
rejects null required values, unknown/duplicate properties and integer enums,
and validates every profile/definition. Composite/numeric roles are invalid.
Legacy profiles can omit optional `compatibilityNotes`; Documented profiles
cannot. Present notes require all four fields; missing/blank/invalid fields
fail instead of acquiring defaults. Documented primary sources must be
absolute public HTTP(S) URLs without credentials. An intentional empty JSON
list is valid; profile enumeration is ordinal by ID.
Core has no DryWetMIDI dependency. These are typed **event intentions**, not SMF
bytes or MIDI-library objects: `PlannedNoteOn`, `PlannedNoteOff` and
`PlannedControlChange`, with absolute ticks, channel, pitch/velocity or CC
number/value. `IsKeyswitch` distinguishes control notes from musical notes;
`IsReset` distinguishes initialization/release/reset controls.
Step 5 now translates these intentions through DryWetMIDI 8.0.3 in Generation's
`MidiEventBuilder`, `MidiFileBuilder` and `MidiFileWriter`, with actual file
write/read-back tests using the extracted test-only synthetic pipeline profiles.
Core still has no library dependency. No native serialization or public
generation tools exist alongside five documented default capabilities.
## Profile fields
| Field | Meaning and constraints |
| --- | --- |
| `id` | Stable nonempty ASCII letters/digits/dash/underscore/dot; catalog IDs unique |
| `instrumentId` | Required stable ASCII ID with the same shape; must reference a declared instrument at catalog admission; no inferred/default binding |
| `role` | Existing `Lead`, `Bass` or `Drums` typed role; exactly one matching profile per selected track |
| `productName`, `productVersion`, `mappingVersion` | Nonempty exact identity, honest version/default scope and independent mapping revision; product name matches the definition display name |
| `evidence` | `status` (`Unverified`, `Verified`, `Synthetic`, `Documented`), nonempty `source`, `authorization`, `verificationRecord`; Documented is cited defaults, Verified is application-verified |
| `compatibilityNotes` | Immutable string record: `versionScope`, `configurationRequirements`, `routingPolicy`, `timingPolicy`; required for Documented, optional for legacy Verified/Synthetic; fields must be nonempty, trimmed, without control characters |
| `minimumPitch`, `maximumPitch` | Inclusive ascending absolute MIDI playable range, 0..127 |
| `channel` | Explicit zero-based MIDI channel, 0..15; independently controlled tracks cannot share a channel |
| `initialArticulation` | Null means unknown receiver articulation, forcing the first requested latched selection; a non-null pitched value declares known resting state and must be supported, never momentary; drums require null |
| `initialControllers` | Complete explicit initial state for all CC numbers used by rules; emitted at tick zero |
| `finalResetArticulation` | Optional explicit latched rule to restore after all musical/control releases; null means no articulation reset |
| `finalControllers` | Optional explicit final CC resets; no undeclared controller or contradiction with a final articulation rule |
| `rules` | Nonempty unique articulation/voice rules, as below |
Synthetic IDs must begin `synthetic-` and product names `Synthetic `. Constructors
snapshot input lists; profiles, rules, results and event collections are read-only.
Verification status is provenance metadata, not a cryptographic attestation:
editing a status to `Verified` cannot establish real-world correctness. Production
resource changes require evidence review; the five bounded documented
capabilities above do not assert full application compatibility.
All pitches are absolute numbers. Octave labels never determine switch values.
Every keyswitch must be outside the **entire** playable range, not just absent
from the particular composition. Drum rules map existing logical voices to
distinct absolute playable pitches; no GM/SD3 assumption is made.
## Rules, velocity and state
A rule contains typed `articulation`, nullable `voice`/`drumPitch`, `behavior`,
nullable `keyswitch`, a required `velocity` layer and explicit `controllers`.
Pitched rules have null voice/drum pitch. Drum rules have a defined voice and
mapped pitch, using the existing sustain intention (logical hits carry no
separate pitched articulation). Unknown articulations/voices fail explicitly.
The smallest supported velocity contract is an **inclusive requested-velocity
interval** `minimum..maximum`, inside 1..127. A request outside that interval
fails with `velocity_layer_conflict`; it is never clamped. Null `outputVelocity`
preserves musical dynamics. A non-null output explicitly transforms every valid
requested velocity to that one value, which must itself lie within the interval.
This transformation is visible in the profile and event plan, not a mutation of
the source note/hit. No interpolation, inferred sample layers or randomization.
Different articulations with identical control state need disjoint velocity
intervals. State-free disjoint layers can coexist on different musical pitches.
For example, **test-only** disjoint layers 1..63 (sustain) and 64..127 (palm mute)
accept their exact boundaries. Sustain at 64 fails. An explicit palm-mute output
of 100 preserves the source requested velocity while emitting 100.
The supported channel-wide state schemes are deliberately bounded:
- `None`: no keyswitch/CC actions; velocity-only rules need no global state.
- `Latched`: keyswitch actions are fixed-duration note pulses. State is the
switch **pitch and velocity**, plus the complete CC number/value vector.
Emit changes only when this state differs. A repeated identical articulation
does not repeat the switch or CC. Every rule in a latched scheme must specify
its complete state; if switches are used, sustain also needs an explicit
switch. A declared initial switch state is assumed known, not needlessly
re-triggered (backward-compatible known-state behavior). Null means unknown:
the first requested switch is emitted, without a preliminary sustain switch.
Initial CC state is always emitted explicitly.
- `Momentary`: each musical note re-triggers its switch/CC actions, even for a
repeated articulation. Hold the switch until both the musical note ends and
its configured minimum switch duration has elapsed. Then emit its note-off
and restore the explicitly declared initial CC values. A state-free resting
rule expresses sustain after release; no guessed sustain keyswitch is sent.
`keyswitch` holds absolute pitch, sounding velocity 1..127, nonnegative
`advanceTicks` and positive `durationTicks`. Timing is exact integer ticks at
960 PPQ. For latched actions duration is the pulse length; for momentary actions
it is the minimum hold measured from switch-on, **including advance**. CC actions
occur at the same activation time as the associated keyswitch, or at the musical
start for CC-only rules. CC numbers/values are 0..127, unique within a state.
Mixed latched/momentary control schemes on one channel are unsupported. Drum
profiles support voice pitches plus latched/momentary complete CC state; pitched
keyswitch state is not a drum mechanism here. Overlapping momentary requests
are rejected, even for identical state, because retrigger/release ownership
would be ambiguous. There is no channel-per-note workaround.
## Shared timing, transitions and extent
The planner computes the largest configured switch advance among **requested
rules on selected tracks**, using one `LeadInTicks` for the whole arrangement.
All musical starts and ends receive that same offset. Controls are scheduled at
`shifted musical start - advance`, never clamped to zero. Unselected profiles/
unused rules do not increase lead-in. CC initialization alone remains at zero.
The planner checks overlapping control windows (activation through musical end,
or later minimum hold/pulse end). Conflicting channel-wide states fail with
`conflicting_articulation_state`. Thus a nonzero-advance transition cannot
silently change state during a previous incompatible sustained note: provide
enough gap or a separately verified representable mapping. Identical latched
states can support chords; overlapping identical musical pitches cannot be
paired unambiguously and are rejected. Overlapping switch pulses also cannot
create stuck/re-triggered same-pitch controls.
Ordering is stable by absolute tick, then priority, retaining deterministic
insertion order for ties:
1. Musical and switch note-offs (priority 0).
2. Initial/release/reset CCs (priority 1).
3. New CC state and switch note-ons (priority 2, CC vector before switch).
4. Musical note-ons (priority 3).
At a shared note boundary, releases/resets therefore precede the next state and
musical onset. Final resets are only those explicitly requested by the profile.
They occur after the declared shifted musical extent and any later releases;
a final latched reset pulse includes a matching note-off and can extend the plan.
No unrequested “all notes off” or controller resets are injected.
`MusicalExtentTicks` is the exact unshifted declared bar extent, including
trailing rests. `MusicalEndTick` adds the shared lead-in. `EndTick` is the maximum
of that end and all required control/release/reset events. Checked Int64 timing
includes advance, note ends and final pulses. Range/timing/profile/state errors
yield no usable partial plan. Pairing validation rejects overlapping pitch
ownership and unpaired note-offs before success.
## MIDI translation boundary (Step 5)
The writer accepts a validated composition and its matching event plan, not
instrument names or guessed mappings. It preserves the planner's event order,
absolute pitches, transformed output velocities, channels (including the
synthetic drum channel 9), switches, explicit note-offs and CC state. It does
not reconstruct articulations through a high-level note helper or inject
all-notes-off. SMF cannot retain the internal `IsKeyswitch`/`IsReset` flags;
read-back tests distinguish controls from musical notes using the known plan.
Type-1 output has a tick-zero conductor, selected role tracks at 960 PPQ and
one End-of-Track per track at the global `EndTick`. Exact metadata, limits,
borrowed streams, safe no-overwrite same-directory staging and cancellation
boundaries are documented in [the MIDI API guide](../README.md#in-process-standard-midi-generation).
DryWetMIDI 8.0.3 supports actual meter denominators through 128; Core-valid /256
fails explicitly at the writer. Four-byte VLQ gaps are checked before output;
the conductor's end gap bounds global `EndTick` to 268435455 ticks.
Synthetic format tests are not mapping admission or plugin acceptance. The
combined conductor-plus-role arrangement is not the single-track Riffer import
documented above, and no AGP/SDP or Riffer-specific export is implemented.
## Remaining production gate
The five admitted capabilities meet a **documented-default source/format** milestone,
not full requested-target or application compatibility. Obtain the missing
AMR numeric anchor/thresholds and authoritative SD3 library/map scope; ABJ's dedicated
PM threshold is still absent and PM is not advertised.
For application-verified readiness, obtain exact installed product/version/settings for each selected Ample target and SD3;
the actual SD3 library/map/overrides; authorized versioned mapping provenance;
verified playable pitches, switch pitches/velocities, layers, CC combinations,
timing/durations, channel behavior, initial/latch/momentary/reset semantics; and
repeatable real-application verification. Native schemas, lawful fixtures/
template rights, extension/entity semantics and Cubase/plugin import acceptance
remain separate missing gates. Passing synthetic tests does not satisfy any of
those production evidence requirements. The approved generic Step 5 sequencing
does not authorize guessed production profiles, native writers or public tools.