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

37 KiB

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.

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
ample-aglp Ample Sound AGLP Ample Guitar LP Lead AGLP manual
ample-agm Ample Sound AGM Ample Guitar M Lead AGM manual
ample-agt Ample Sound AGT Ample Guitar T Lead AGT manual
ample-ame Ample Sound AME Ample Metal Eclipse Lead AME manual
ample-amr Ample Sound AMR Ample Metal Ray5 Bass AMR manual
toontrack-sd3 Toontrack SD3 Superior Drummer 3 Drums SD3 manual

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 publicly lists both AGM projects:

  • 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, 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. 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, §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. 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, inspected rendered, links these vendor-authored demo archives (read in memory, not redistributed):

  • 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: 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 (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 2025-04-16 05:04:25 9291c4e3027ac1469bd845bb04614f5a2754bd35a4f017bcfd7cdb75db335e7e
AGLP 2025-09-08 09:00:15 7b28b62f3c25ecb774227b15beab06f5e0f0c944f35db9e82121028017f9cedb
AGM 2025-09-08 09:00:15 449bd7b8bca7771dbf8e08e0029d2bbe999f991efe441d7900ee93da29dd86a4
AGT 2025-09-08 09:00:02 2e5696d750841a47061d37737ec7d8435cb4e30756cda15596d1f89ff87810dd
AME 2025-09-08 09:00:39 ab482f08b0546eca0a4233b8be3776c411b77f3dca96979f529debc2dfc0c4ca
AMR 2025-04-16 05:04:22 833115ed9d650d9d7dc0a60695a5405f2dca8cf7f0e3e4b7c7bbf6e0baa65428
Settings/CPC 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: simplified fetch and rendered page require login; stopped without bypass. The accessible vendor-hosted 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:

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 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. 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.