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

401 lines
25 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Versioned profiles and articulation compiler
**The operational MCP service defaults to three evidence-backed target subsets.**
Three explicit Standard MIDI fallback profiles also remain packaged and available.
Actual built-wheel generation/discovery is verified outside the checkout;
this is not application compatibility.
Installed AME 4.0.1 / AMR 4.1.0 identities and native Riffer XML 2.1 are now
locally verified, with default native subset profiles.
SD3 3.4.4 has a default SL-DFH core three-voice subset.
All application acceptance remains unrun.
Synthetic fixtures stay test-only.
Step 6 supplies composition; Step 9 connects the compiler to real MCP generation
and lists all six profiles with runtime native readiness and subset limitations.
Installed resource and stdio/software evidence is recorded in
[final native report_10.md](../prompts/report_10.md), separately from the unrun receiver,
plugin and Cubase checks. No bank/program setup is sent: configure receiver
patches and channel routing externally before importing/playing the MIDI.
## SD3 core subset policy v1
`toontrack.sd3.3.4.4.core.v1` / `toontrack-sd3-3.4.4-core-v1.json` is a
default `verified_subset`, not a GM profile promoted to vendor support.
Read-only SD3 3.4.4 SL-DFH native declarations establish kickR/36, snareR/38,
hatsTP/42 and ordinary packed MIDI velocities 1–127. These are the only
declared voices: kick, snare, closed_hat (with documented convenience aliases).
No extra GM pitches, hat-controller states, choke behavior, named velocity
layers or other libraries are claimed. Actual template pad aliases and the
library/input-channel are checked at codec preflight.
Zero-based channel 9, linear intensity-to-velocity interpolation, no controls
or reset events, common score-relative zero and six-place finite-decimal timing
are **generator policies**, separate from local vendor facts. The profile has
one action-free normal/sustain articulation. Templates are operator-local;
their kit/mixer/non-song state is preserved. Native output needs the actual
template, not just a metadata flag. See [SD3 codec](formats/sdp.md).
The template is configured only through operator CLI `--sd3-template` or typed
service/server keyword. Without it the target MIDI map still works, but runtime
native readiness is false. Invalid supplied templates error; no hidden fallback.
Real service wiring is verified; application acceptance remains unrun.
## Standard fallback policy v1
These are standard MIDI facts plus explicit generator policy, **NOT verified
Eclips/Ray/SD3 maps**. They are neither synthetic fixtures nor vendor defaults.
| Production ID / resource | Part | Zero-based channel | Range / voices |
| --- | --- | --- | --- |
| `standard.lead.v1` / `standard-midi-lead-v1.json` | lead | 0 | inclusive MIDI numbers 0–127 |
| `standard.bass.v1` / `standard-midi-bass-v1.json` | bass | 1 | inclusive MIDI numbers 0–127 |
| `standard.gm-drums.v1` / `general-midi-percussion-v1.json` | drums | 9 | all 47 GM Level 1 percussion sounds, 35–81 |
Each is explicitly selectable by ID, not a default. Summary `mapping_kind` and
provenance `status` are both `standard_midi`; product/mapping versions identify
the MIDI standard and `standard-fallback-1`, not an installed plugin version.
The existing summary `instrument` field (`eclips` / `ray` / `sd3`) identifies
intended routing only, **never compatibility**. `native_format` identifies the actual target suffix (`griff` / `briff` / `sd3p`),
not a request alias or available writer; `native_available=false` for fallbacks.
Public product names and limitations explicitly disclose the fallback.
Lead/bass channels 0/1 and accepting the full legal note-number range are output
policy, not guitar/bass playable-range claims. Drum channel 9 is the deliberate
selection of GM's human-numbered channel 10; it is not the SD3 default map.
Canonical drum names normalize the source sound names. Convenience aliases
(`kick`=36, `snare`=38, `closed_hat`/`hihat`=42, `pedal_hat`=44,
`open_hat`=46, `crash`=49, `ride`=51, `clap`=39) are generator vocabulary.
No other drum voice, instrument-specific variation, or choke behavior is inferred.
Only canonical `normal` with alias `sustain` is supported, using no actions.
`sustain` means normal note duration, **not sustain-pedal CC64**. Palm mute,
slide, accent, and every undeclared technique fail explicitly. There are no
keyswitches, CCs, program/bank changes, GM-on messages, reset/state changes, or
control lead/gate/release tails. Notes use the score's exact rational start and
duration, converted without rounding at the selected PPQ; normal compilation
does not add pre-roll. Generic switch/CC mechanics remain available for separate
instrument/test profiles, not these fallbacks.
All three profiles use a single interpolation interval `[0,1]` and positive
velocity range 1–127: `round(1 + 126 * intensity)`, nearest integer, ties to even.
Examples: 0→1, .25→32, .5→64, .75→96, 1→127. This is generator dynamics policy,
**not vendor velocity layers** or a claim that every receiver sounds every note.
Receiver patch selection, GM mode, routing, tuning, and sound behavior must be
configured externally. Service results carry per-part `STANDARD_MIDI_MAPPING`
warnings, including MIDI-only successes, and never claim vendor compatibility.
### Public facts checked 2026-10-19
- **MIDI1-MESSAGES**: [MIDI Association message summary](https://midi.org/summary-of-midi-1-0-messages)
gives seven-bit note/velocity fields and zero-based channels 0–15. Hence
note numbers 0–127 are legal; sounding-note velocities here are 1–127.
- **GM1-OVERVIEW**: [MIDI Association GM Level 1 overview](https://midi.org/general-midi-level-1)
establishes the standard and distinguishes named sounds from acoustic timbre.
The overview alone does **not** supply the numerical percussion map.
- **GM1-PERCUSSION-TABLE**: [Computer Music Resource's Vanderbilt University
Blair School of Music teaching table](https://computermusicresource.com/GM.Percussion.KeyMap.html)
explicitly gives channel 10 and every percussion number 35–81. Checked core
entries include bass drum 1=36, acoustic snare=38, closed hi-hat=42, pedal
hi-hat=44, open hi-hat=46, crash cymbal 1=49, ride cymbal 1=51; endpoints
acoustic bass drum=35 and open triangle=81. All 47 numeric/name pairs have
independent regression assertions. Octave labels are deliberately unused.
The profile sources use `standard_public` for external facts and
`generator_policy` for this policy section. Neither kind can satisfy `verified`
vendor provenance. Public reference URLs and facts only are stored, not manuals
or factory songs. No plugin or Cubase import test is implied.
## Riffer subset policy v1
The production registry packages these **default** target maps:
| ID / resource | Target | MIDI channel (policy) | Explicit tuning by descending string ID | Conservative frets/range |
| --- | --- | --- | --- | --- |
| `ample.ame.4.0.1.riffer.v1` / `ample-metal-eclipse-4.0.1-riffer-v1.json` | Ample Metal Eclipse 4.0.1, `.griff` | 0 | 36,43,48,53,57,62 | 0–22, MIDI 36–84 |
| `ample.amr.4.1.0.riffer.v1` / `ample-metal-ray5-4.1.0-riffer-v1.json` | Ample Metal Ray5 4.1.0, `.briff` | 1 | 35,40,45,50,55 | 0–19, MIDI 35–74 |
These profiles declare `mapping_kind=instrument`, `status=verified_subset`,
`native_available=true` for the independently callable codec. This does **not**
mean application acceptance is complete. Native service wiring is implemented.
Target MIDI-only requests use mapped MIDI without needing a native template;
default/native requests generate actual native files whenever preflight succeeds.
Runtime listing supplements stored codec metadata with actual template readiness.
### Description technique applicability
`palm mute`, `palm-mute`, `palm muted`, `palm-muted` and `palm muting` apply to every selected
pitched part. In mixed lead/bass/drum requests the drums deliberately retain
normal articulation and this applicability is recorded in resolved assumptions.
Drum-only palm mute raises `UNSUPPORTED_ARTICULATION / pitched_parts_required`;
it is not silently ignored or interpreted as a drum choke.
Selected standard pitched profiles cannot implement palm mute and still error.
Integration tests assert actual guitar MIDI D0/26 and native PM, bass C0/24,
musical velocity 32–63 and native PMP, with ordinary mapped drum notes.
### Instrument facts
Read-only ProductVersion and native XML evidence IDs are
`LOCAL-AME-401-RIFF21-20261019` and `LOCAL-AMR-410-RIFF21-20261019`.
They establish XML 2.1 / PPQ 480, string layouts, MIDI pitch minus fret, `Sus` /
`PM` / bass `PMP`, off velocity, and discrete raw-unit CC1 points. Default-tuning subsets were
distinguished from actual drop variants. Fret limits above deliberately bound
generation to target-observed maxima; they are not claims about every possible
instrument configuration.
Public main-panel manuals were checked in memory, without saving manual assets:
[Eclipse](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf), sections
2.2.1–2.2.4, and [Ray5](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf),
sections 2.2.1–2.2.4. Vendor C0 is numeric **24**, consistent with Eclipse's
documented C1 low range and native MIDI 36. D0 is **26**. Do not apply another
DAW's octave-label convention to these maps.
- **Eclipse normal:** C0/24. Actual current manual sustain bands are 1–15 full
mute, 16–31 three-quarter mute, 32–63 half mute, **64–126 sustain**, and
127 Pop/PH depending on Settings. Therefore normal generation uses **64–126**,
not a falsely normal 1–127 sweep.
- **Eclipse palm mute:** D0/26, native `PM`; lower velocity means greater mute
depth. Uses legal positive velocities **1–127** without inventing sublayers.
- **Ray5 normal:** C0/24, **64–126** sustain; 127 accent is excluded.
- **Ray5 palm mute:** also C0/24, **32–63** documented palm-mute band; below 32
dead notes are excluded. D0's separate high/low dead-note behavior is not used.
The native C0-band representation is `PMP`, not D0's `PM`. Target-local
numeric observations distinguish them: 313 `PMP` notes use 40–60, whereas
56 `PM` notes use 70–100 and 89 `DN` notes use 30–60. This distinction matters:
writing D0 `PM` with a C0-band velocity would conflate different modes.
Only the supported C0-band technique is generated; no additional named mode
or guessed D0 threshold is introduced.
### Eclipse pinch harmonic extension
AME mapping revision `riffer-subset-2` retains the existing production ID,
product 4.0.1 and XML 2.1 codec. A read-only check on 2026-10-20 verified the
installed VST3 ProductVersion 4.0.1 and aggregated 35 local AME `.griff` files:
17 `Articulation="PH"` notes, observed velocities 80–100 and NoteID pitches
49–73. No note sequences or factory assets were retained or copied.
The official [Main Panel manual](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf)
was fetched and parsed in memory: page 6, section 2.2.1 lists PH at G0 with
range C1–C5; page 9, section 2.2.9 confirms G0. Established vendor C0=24 gives
G0=31 and C1–C5=36–84. The local observation range is not a technique limit.
Only AME receives `pinch_harmonic` (alias `ph`), dedicated keyswitch31 and native
`PH`; AMR, SD3 and standard fallbacks remain unchanged. Strict native maps reject
wrong PH switch/label, arbitrary labels and bass PH. Legal positive velocities
1–127 with linear intensity interpolation, latched switching, zero lead and
1/32-quarter positive gates are generator policy, not inferred PH velocity
layers or vendor timing guarantees. No normal-C0 velocity127 shortcut or CC
effect is substituted. PH may remain one continuous cross-bar note.
No named vibrato technique is enabled. Eclipse's manual describes default auto
vibrato while Ray5 describes manual mod-wheel behavior and configurable auto
modulation. The codec preserves already compiled CC1 stair points in raw MIDI
units; it does not guess a named mode, normalize values or invent resets.
### Generator policy (not vendor facts)
- Channels 0/1 route the two parts independently; configure receivers externally.
- Supported target techniques are explicitly latched. MIDI switch velocity 100,
zero lead, 1/32-quarter-note positive pulse, same-tick switch-before-note
ordering and no release offset are deliberate scheduling policy. They avoid
automatic pre-roll, not a claim that every host guarantees audible switching.
- One linear interval interpolates intensity using ties-to-even rounding:
`round(low + (high-low) * intensity)`. Vendor facts bound the legal technique
band; interpolation within it is **not** an asserted vendor layer definition.
- Native note mapping consumes only verified MIDI switches, uses explicit
physical strings/frets, and rejects impossible allocation, unsupported CCs,
off-grid timing, nonzero pre-roll or tails. It never clips or shifts content.
Strict `riffer` settings include version, PPQ, instrument, actual extension,
per-string ID/open MIDI note/max fret, native articulation map and allowed CC1.
Unknown fields, wrong target/version, booleans masquerading as integer literals,
arbitrary tunings/fret policies and fabricated mappings are rejected. There is
no template scripting or filename-derived tuning. See the
[codec and independent reader](formats/agp.md) for API and saved-file limits.
## Internal APIs
- `profiles.parse_profile(str | bytes) -> InstrumentProfile`: strict JSON and
model validation, including duplicate JSON object-key rejection.
- `profiles.load_profile_registry() -> ProfileRegistry`: use
`importlib.resources.files`, not repository paths or the working directory.
`data.profiles.PROFILE_RESOURCES` explicitly lists three target defaults and
three explicit standard fallback resources.
Both resource package initializers are bundled in wheels; an inaccessible
package, missing or undeclared JSON, duplicate manifest entry, invalid JSON,
invalid profile, duplicate ID/default, or synthetic map is an error, not an
empty-registry success. Optional `package`/`declared` arguments support
resource testing; they do not bypass production validation.
- `ProfileRegistry.summaries() -> list[ProfileSummary]`: returns independent
copies of the reviewed public summary contract, sorted by ID.
- `ProfileRegistry.select(parts, ProfileSelection) -> dict[Part, InstrumentProfile]`:
explicit IDs must exist and match the part. Only an explicitly marked unique
production default is automatic; even a single nondefault requires an explicit
choice. Missing mappings use `ProfileRequiredError`/`ProfileNotFoundError`;
ambiguity uses `AmbiguousProfileError`; wrong parts use
`ProfilePartMismatchError`. Errors give fixed safe reasons and actionable
messages; ambiguity lists only the registry's validated IDs.
- `articulations.compile_score(score, selected_profiles, *, ppq=960) -> EventPlan`:
requires complete explicit selections, defensively revalidates score/profile
graphs, compiles events, enforces the 100,000-event budget incrementally, and
calls the reviewed `midi.validate_event_plan` before returning.
Explicit synthetic selections are supported for tests; discovery and registry
selection never admit them.
Registry/profile failures are named `SerializationError` subclasses; selection
failures retain `PROFILE_REQUIRED`. Compilation failures use
`ArticulationCompileError` or the existing named timing/writer failures.
Unsupported techniques use `UnsupportedArticulationError`. Public details never
copy raw JSON, validation messages, unsupported input strings, or file paths.
Programming errors are not turned into successful fallback results.
## Schema version 1
All objects inherit the strict shared `ContractModel`: unknown fields, numeric
strings/booleans, nonfinite numbers, and invalid MIDI ranges are rejected.
Version is the exact string `"1"`, not a coerced number. Required fields have no
guessed musical defaults (summary `mapping_kind` alone defaults to `instrument`
for existing contracts/fixtures). See the three clearly labeled
`tests\fixtures\profiles\synthetic-*.json` files for complete **test-only**
examples; they are not packaged production resources.
A profile declares:
- `id`, reviewed `summary`, `provenance`, explicit `default`, zero-based
`channel`, `playable_range` **or** `drum_voices`, canonical
`normal_articulation`, and `articulations`.
- Summary ID, product/mapping version, supported canonical techniques, MIDI
capability, and limitations must agree with the map/provenance.
Stored `native_available` agrees with strict `riffer` or `sdp` settings;
a flag or mapping evidence alone cannot authorize a serializer.
- Public summary `mapping_kind` is `instrument` (backward-compatible default) or
`standard_midi`; standard summaries expose only `normal`, with native unavailable.
- Provenance status is `test_only`, `verified`, `verified_subset`, or `standard_midi`.
`verified_subset` separates official/local identity, range, actions and velocity
facts from generator channel/state/timing policy, with explicit limitations.
`standard_midi` must
agree exactly with summary `mapping_kind`, use an explicit Standard/General
MIDI product label, declare only action-free normal/sustain, and separately
cover standard identity/range facts and generator channel/action/state/timing/
velocity policy. It is not vendor verification. Test profiles require `test.`
IDs, a `SYNTHETIC ` product-name prefix, no vendor sources, and no default flag.
Production profiles cannot use that test identity.
- Provenance requires target build, mapping/preset identifier, product/mapping
versions, and limitations. Full `verified` attestations require explicit official
HTTPS or lawfully held local references covering identity, range/voices,
channels, actions, state/reset, timing, and velocity. This is a metadata
completeness rule, **not** automated verification that assertions are true.
Human evidence review remains mandatory. In-memory registry-policy tests use
unmistakable TEST-HARNESS references, not vendor evidence.
- Pitched profiles require an inclusive numeric range; drums require unique
logical voices with unambiguous physical MIDI numbers. No GM/channel-9
convention is inferred. Musical pitches must be disjoint from all switches.
- Articulations/voices declare canonical names and aliases. Normalization
case-folds and collapses ASCII spaces, hyphens, and underscores to `_`;
resulting names must be ASCII alphanumeric segments. Every canonical/alias
collision, including within one item, is rejected.
### Actions, layers, and units
An articulation declares `mode: latched | momentary`, actions, and velocity
layers. Explicit typed actions can occur separately or together:
| Action | Required data |
| --- | --- |
| `keyswitch` | MIDI note, positive velocity, `pulse` or `hold`, lead, positive gate, release offset |
| `cc` | controller, value, explicit reset value or null, lead, release offset |
All action timing is rational **quarter-note beats**, using existing
`RationalBeat`/`PositiveBeat`; every declared value, even on unused techniques,
must convert exactly at the chosen PPQ. No rounding or milliseconds are implied.
Pulse switches release at selection tick plus gate, with zero release offset.
Holds release after the last compatible active note plus offset; gate is their
minimum positive duration, and an undersized hold is rejected, not extended.
Latched switches must be pulses. Momentary CCs require explicit reset values;
latched CCs cannot declare resets/tails. Duplicate physical actions in a
technique are invalid. Latched techniques must explicitly cover the same CC
controller set to prevent omitted-controller state leakage.
Intensity intervals exactly cover 0 through 1, with no gaps/overlap:
`[low, high)`, except the last interval includes 1. Velocity bounds are
inclusive integers 1–127, monotonic, and disjoint across layers. Linear
interpolation within the selected interval rounds to nearest integer, ties
to even; there is no clamp. At an internal intensity boundary the upper layer
wins by definition, not arbitrary overlapping-layer precedence.
## State and causal ordering
Each selected part owns exactly one declared channel. Selected channels must
be distinct, including selected empty tracks. Notes and state never migrate
between parts/channels. Different physical musical pitches permit polyphony;
same-pitch overlap is rejected by the reviewed writer, not merged away.
For a stateful profile, normal must be latched and **every** technique needs
explicit actions. Normal is not MIDI pitch zero or an assumed universal CC.
Velocity-only profiles can have no actions; differing velocity-only techniques
then overlap safely without global control state.
- Latched selections are emitted initially and on transitions only; compatible
overlapping notes and repeated same-technique notes across gaps deduplicate.
- Overlapping controlled notes must request the same canonical technique.
Different techniques are conservatively incompatible even if some actions
happen to match; no unsupported independent-voice state is inferred.
- Compatible momentary overlaps form one active interval. Held switches remain
held until the final note releases; CC selections and pulse triggers remain
per-note, while resets wait for the final note plus declared offsets.
- A momentary overlay starts from declared normal. If necessary, normal's actual
actions are established before the overlay's first controls, allowing positive
switch gates to finish. Its normal actions are emitted again after the final
reset/release. A preceding nonnormal latched state needs enough room for this
explicit setup; it is never silently inherited as the overlay baseline.
- Lead/setup/restoration controls cannot change state while previous incompatible
musical notes remain active. Restoration and physical switch tails must fit
before subsequent incompatible demands; unsafe schedules fail explicitly.
Simultaneous conflicting switch triggers are not guessed into a valid map.
- Per-note pulses that overlap the same physical switch are unrepresentable and
rejected, not deduplicated. Exact release/retrigger boundaries are legal.
Notes are deterministically sorted before scheduling. Raw integer schedules
can start before zero; one common pre-roll is exactly `max(0, -earliest_event)`.
Every part is shifted by that amount. `Score.start` remains a logical origin;
relative offsets, not that origin's absolute size, become ticks.
The shared end is the musical end or the latest switch/reset/restoration tail,
whichever is later, including when other tracks are empty. Restoration's declared
lead-time readiness is included even if the last physical event occurs earlier.
Within a tick, priority 0 releases notes/switches, 10 resets CCs, 20 performs
selection/restoration controls (in causal emission sequence), and 30 starts
musical notes. Sequence values are unique and deterministic per track.
Every switch/musical note has a positive-duration paired release. Boundary
same-pitch retriggers release before re-onset. The existing writer performs
the final role, overlap, grid, channel, SMF-bound, and pairing checks.
## Verification and remaining vendor/native gates
Tests cover strict JSON/provenance/resource/selection policy, aliases, ranges,
layers/endpoints, separate and combined actions, state transitions, compatible
and incompatible overlap, per-note retriggers, exact timing/pre-roll/tails,
mutated graphs, deterministic output, and exactly 100,000 events versus overflow.
The three-part integration fixture has palm-muted lead, bass holds, articulated
drums, compatible overlapping notes, and boundary retriggers. Independently
hand-derived event lists are checked against both the compiler and a real
saved MIDI parsed by Mido, including channels, pairing, tempo, and common EOT.
Built-wheel tests install offline into an isolated import target and also load
resources directly from the wheel ZIP; both probes run outside the checkout
with isolated Python imports and confirm six production profiles, target defaults,
explicit standard selections/channels, core GM numbers and absence of synthetic
maps. Standard compilation is separately checked against independent events
and real MIDI read-back, including note range/velocity endpoints, no controls,
and honest unsupported-technique/voice failures.
The old simplified Ample-page extraction was incomplete: raw official HTML
exposes public Eclipse/Ray5 main-panel, Riffer, Strummer, and settings PDFs.
See [compatibility](compatibility.md) for exact links and limitations.
To add verified **vendor** profiles, obtain installed product/edition/build and
mapping/preset/library versions,
lawful authoritative numeric ranges/channels/voices/keyswitches, latch/hold/
reset/CC semantics, control lead/gate/release timing, velocity-layer/intensity
rules, and target-behavior verification with provenance/permission recorded.
Native layout/content evidence, controlled files, and plugin/Cubase load/save
round trips are a **separate** gate. No application acceptance test ran.
The [Step 5 fix report](../prompts/report_5_fix.md) records validation.
The current target subset maps, real native writers and native/MIDI service wiring
are verified in report_9_fix; standard fallbacks remain explicitly selectable.
Broader mappings and actual application acceptance remain separate, unrun gates.