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