569 lines
37 KiB
Markdown
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.
|