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

129 lines
8.0 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.

# 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](../../prompts/report_9_fix.md)
and [final exact-wheel native acceptance](../../prompts/report_10.md).
## 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](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf)
and [Ray5](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf) main-panel
manuals establish the limited technique semantics; the
[Riffer manual](https://www.amplesound.net/en/Guitar_Riffer.pdf) documents
Riffer save/load separately from MIDI import/export.
See [profile facts versus generator policy](../articulation-profiles.md#riffer-subset-policy-v1).
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.