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

25 KiB
Raw Permalink Blame History

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, 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. 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 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 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 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, sections 2.2.1–2.2.4, and Ray5, 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 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 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 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 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.