Cubase-MCP-GAJ3T.MusicGen.R.../docs/formats/agp.md

8.0 KiB
Raw Blame History

Ample Riffer XML 2.1: .griff / .briff

Implemented: native musical-content writers and independent saved-file validators for Ample Metal Eclipse 4.0.1 and Ample Metal Ray5 4.1.0. agp is a logical request/legacy Python API alias, not a file extension. No MIDI is renamed. Plugin/Cubase load/save/reload acceptance remains UNRUN. The native profiles are now defaults, wired to MCP generation alongside the SD3 template-song codec. See service verification and final exact-wheel native acceptance.

Evidence and reproducibility

Read-only local evidence checked 2026-10-19:

Safe evidence ID Technical observations
LOCAL-AME-401-RIFF21-20261019 Installed VST3 ProductVersion 4.0.1; 35 target AME preset files, XML Riff, Ver="2.1", PPQBase="480", six strings, Inst="AME"
LOCAL-AMR-410-RIFF21-20261019 Installed VST3 ProductVersion 4.1.0; 30 target AMR preset files with the same XML version/PPQ and five strings; factory files omit Inst, a user-authored example includes Inst="AMR"

Only schema/numeric facts were extracted. Factory sequences, plugin binaries, manuals and private templates were neither copied into the repository nor uploaded. Public Eclipse and Ray5 main-panel manuals establish the limited technique semantics; the Riffer manual documents Riffer save/load separately from MIDI import/export. See profile facts versus generator policy.

Original generated, independently validated XML fixtures:

  • tests\fixtures\riffer\original-lead.griff
  • tests\fixtures\riffer\original-bass.briff

Integration tests retain real generated read-back evidence under .test-artifacts\native-riffer-evidence-v1\. These are newly composed minimal verification notes and CC points, not vendor music or application re-saves. Tests require no vendor files, network, plugin installation or manual parser.

APIs

The module remains riff_groove_builder.formats.agp for compatibility:

  • check_riffer_capability(part, profile) / require_riffer_capability(...). Legacy check_agp_capability / require_agp_capability retain their signatures. Checks perform no filesystem IO, revalidate the whole mutable profile, and return frozen NativeCapability(part, format="agp", available, reason). Supported target/version/settings return available=True, reason="riffer_xml_2_1"; standard and synthetic profiles return available=False, reason="riffer_profile_not_supported".
  • write_riffer(path: Path, plan: EventPlan, part: Part, profile: InstrumentProfile) -> Path, also named write_agp. It exclusively creates the supplied staged path, requires the actual case-sensitive suffix, flushes/fsyncs, then reads the saved file back. It creates no parent, sibling, template or fallback file. The caller owns staging, cleanup and publication. An invalid saved file is left in its stage for inspection and is never reported as success.
  • validate_riffer_file(path, plan, part, profile) -> RifferReadback, also named validate_agp_file. Reads bounded actual saved XML without calling the serializer; returns parsed notes, discrete CC1 points and native end tick. Independently checks root metadata, tuning/frets, string overlap, velocities, technique, exact timeline and every requested note/CC against the score/plan.
  • preflight_riffer(plan, part, profile) runs exact content/grid/physical-string checks without output IO. Service fallback recognizes only specific known representation failures from preflight, never write/read-back corruption. Writers accept optional on_created(fstat) for service-owned partial-file identity tracking, invoked immediately after exclusive open and before writes.

Only AME 4.0.1 / AMR 4.1.0 with the strict native subset can authorize this codec. A native flag, mapping attestation, synthetic profile or product string alone cannot do so. Profile schema "1" and mapping version are not container versions. Malformed/mutated models raise SERIALIZATION_ERROR; wrong-part selection raises PROFILE_REQUIRED; invalid requested parts raise INVALID_REQUEST. Unavailable profiles raise NATIVE_FORMAT_UNAVAILABLE; wrong suffix, unsupported content, unrepresentable timing and saved-content mismatches are serialization failures in the codec. The service may explicitly fall back only for known preflight capability/representation limits. Existing output raises OUTPUT_EXISTS; IO errors use OUTPUT_IO_ERROR. Unexpected programming failures propagate.

Encoded subset

  • UTF-8 XML Riff root, Ver="2.1", PPQBase="480", Inst="AME" / "AMR", numStr=6 / 5. Author is the generator name, Category Metal, Type Riff, Rating 0, Quantize 1/32; these are output metadata, not quantization. Measures, Time-Signature, Tempo and Key come from the score. Native keys use pitch class plus m for minor. Loop spans the exact whole score from zero.
  • Strings are emitted in descending physical ID order, including empty strings. Explicit guitar tuning by ID 6..1: 36,43,48,53,57,62; bass 5..1: 35,40,45,50,55. Conservative maximum frets are respectively 22 / 19. Observed drop variants are not inferred or silently substituted.
  • Every note has NoteID (MIDI pitch), Fret, Begin, End, Velocity, Off-Velocity, Articulation (Sus; guitar PM, bass C0-band PMP), Legato (No Legato), Muted (False). Bass PM is the separate D0 high-velocity mode, not the C0 32–63 band selected by this profile. Physical routing uses bounded deterministic backtracking, preferring lower frets. If no assignment exists, or 200,000 search iterations are exhausted, it explicitly fails; it never steals a string, shortens or drops notes. Legal chords occupy distinct strings. Same-string boundary-touching notes are allowed; overlapping notes on a string are not.
  • Native normal/palm-mute fields replace the compiler's verified MIDI keyswitches, not musical notes. A separate recompile of the selected score part verifies every musical and switch on/off before serialization. Off velocities come from the actual event plan, not a fabricated constant.
  • Compiled CC1 is preserved in cc-1.Mod with root ccName-1="1.Mod", ccVisibility-1="1" and p(tick,value,curveType="stair"). Values remain raw MIDI 0..127, not normalized 0..1. No reset or named vibrato mode is invented. Other CCs, duplicate-tick CC1 actions, curved interpolation, legato/effects/strums or arbitrary extra XML content are explicitly rejected.

Timing and limitations

Score beats are exact fractions. Conversion to PPQ 480 never rounds. The score origin is translated to zero exactly as the MIDI compiler does; notes retain their exact relative starts/durations. Multiple score parts may be supplied, but one explicit selected part is written to each native file.

Nonzero compiled pre-roll or any control tail is rejected. There is not yet an evidence-backed fractional pickup/extra-measure origin contract shared by native and MIDI outputs. Shifting notes back, clipping tails, inserting guessed bars or changing loop bounds would falsely claim alignment. The new profiles use same-tick ordered switches, zero lead, and a 1/32-quarter-note pulse as generator MIDI policy; no vendor timing guarantee is claimed. Native controls at valid ticks inside the shared musical span are retained exactly.

The independent reader deliberately validates this generated subset, not all vendor-authored Riffer files. It rejects DTD/entities, non-UTF-8 input, over 16 MiB, links/reparse points, unknown fields/content, illegal numeric values, wrong target/version and note/CC corruption. It does not launch a plugin, prove audible articulation or certify native load/save/reload. Those are separate application acceptance tasks, not pytest skips.