phase information removal.

This commit is contained in:
Johannes Findeisen 2026-11-06 14:12:22 +01:00
commit dd32143bf8
45 changed files with 325 additions and 330 deletions

View file

@ -1,6 +1,6 @@
# Project format v17 (reads v1–v17)
Phases 5–31 use a bounded text format implemented in C99 without a parser library.
The project uses a bounded text format implemented in C99 without a parser library.
The extension is `.xtc`. File operations run exclusively on the control thread.
The project owns its graph, tracks and silent/audio arrangement regions. Audio samples remain in external WAV
files; MIDI notes are stored inline.
@ -67,7 +67,7 @@ END
by `MIX gain_bits pan_bits mute solo`: finite binary32 gain 0..4, pan -1..1
encoded as eight hex digits, mute and solo unsigned 0/1.
- `ROUTE`: since v9, required after MIX: bus flag and destination bus ID;
UINT64_MAX denotes master. See Phase 24 constraints below.
UINT64_MAX denotes master. See the mix routing constraints below.
- `CLIP`: ID, track ID, start tick, length tick, source offset tick, source
length tick, hex-encoded name bytes. Trimming
preserves source bounds, so a region can re-extend only within its original
@ -130,18 +130,18 @@ missing references; audio-plan preparation reports unreadable/invalid assets
and renders them silently. Relinking replaces a selected clip's path without
changing its IDs or arrangement. See AUDIO_FILES.md for recovery and limitations.
## Phase 9 extension and recovery policy
## Extension and recovery policy
Phase 9 kept format v4. Native processor descriptors are process-local and have no
Format v4 was retained. Native processor descriptors are process-local and have no
serialized representation; saving a native graph returns UNSUPPORTED and retains
the existing destination. Unknown file versions/types remain rejected. See
NATIVE_API.md for the extension boundary and RECOVERY.md for write-failure, killed
writer and unfinished-recording behavior. Metadata validation is available via
`xtc-check --validate PROJECT` without a GUI or server; it does not load assets.
## Phase 15: version 5 plugin metadata
## Version 5: plugin metadata
Phase 15 introduced `XTC_PROJECT 5`; its reader also supported versions 1–4. All v4 records and
`XTC_PROJECT 5` was introduced; its reader also supported versions 1–4. All v4 records and
order remain the same. Node type 8 is a LADSPA plugin; native pointer-bearing type
7 is still unsupported in files. Immediately after each type-8 `NODE id 8
00000000` record come:
@ -163,9 +163,9 @@ Missing modules remain preserved by metadata load/save; GUI installation rejects
them with a repair message. No transient DSP state, pointer or plugin binary is
stored. See PLUGIN_HOSTING.md and decision 0009 for supported processors/limits.
## Phase 16: version 6
## Version 6
Phase 16 introduced v6 and its reader accepted v1–v6. After each plugin's CONTROL records,
Version 6 was introduced and its reader accepted v1–v6. After each plugin's CONTROL records,
`PLUGIN_AUTOMATION count` is followed by exactly count (<=32) records:
`PARAM tick port mode float32_hex_bits`. Mode is 0 linear or 1 step. Duplicate
port/tick pairs, nonfinite values, unknown control ports and ticks beyond the
@ -173,9 +173,9 @@ project limit are rejected. Loaded plugin tempo comes from TEMPO. Range and
discrete-mode compatibility are checked on control-thread compilation. Versions
1–5 migrate with empty plugin lanes. See CONTROL.md for timing/ordering.
## Phase 18: version 7 and project folders
## Version 7 and project folders
Phase 18 introduced v7; its readers migrated v1–v6. Record ordering and field bounds
Version 7 was introduced; its readers migrated v1–v6. Record ordering and field bounds
are otherwise unchanged from v6. v7 ASSET may contain a relative path, interpreted
against the actual containing directory of the named project file (resolved on
the control thread), never the launch working directory. Opening a symlink to a project uses the
@ -214,10 +214,10 @@ writers and write-limit failures. ASan/UBSan/static analysis additionally audit
bounded parser. This is regression/fault-injection coverage, not exhaustive fuzzing
or a claim of power-cut qualification.
## Phase 22: version 8 audio clip settings
## Version 8: audio clip settings
Phase 22 introduced v8 and reads v1–v7 with unity clip gain and no explicit
clip fades. After **every** clip's `MIDI` record (including silent and MIDI
Version 8 adds audio clip gain/fade settings and reads v1–v7 with unity clip
gain and no explicit clip fades. After **every** clip's `MIDI` record (including silent and MIDI
clips), v8 requires:
```text
@ -240,10 +240,9 @@ No waveform cache or source audio is serialized. Checked-in v1–v7 migrations,
v8 exact roundtrips, malformed new metadata and byte-mutation tests cover the
format change (`make test test-portability test-audio-editing`).
## Phase 24: version 9 mix routing
## Version 9: mix routing
Phase 24 introduced v9. Immediately after each TRACK's MIX record it writes
`ROUTE is_bus bus_id`. `is_bus` is 0 or 1; `bus_id` is an existing bus track ID,
Version 9 adds `ROUTE is_bus bus_id` immediately after each TRACK's MIX record. `is_bus` is 0 or 1; `bus_id` is an existing bus track ID,
or decimal UINT64_MAX (18446744073709551615) for master. Buses must route to
master and cannot contain clips. Invalid destinations, flags and nested routing
are rejected. v1–v8 migrate all tracks to ordinary direct-to-master tracks.
@ -252,9 +251,9 @@ reject v9 rather than discard routing. The public `xtc_track_info` grew fields;
API consumers must rebuild. Fixtures cover v1–v8 migration and tests exercise
v9 exact roundtrips and malformed routing.
## Phase 26: version 10 interpolation and controller bindings
## Version 10: interpolation and controller bindings
Phase 26 introduced v10 with migration from v1–v9. Track/bus automation points are
Version 10 adds interpolation modes and migration from v1–v9. Track/bus automation points are
`POINT track_id parameter tick value_bits step`, where step is 0 linear or 1
hold for the segment starting there. v1–v9 points migrate to step=0. LADSPA
`PARAM` encoding remains unchanged (already has interpolation mode).
@ -272,10 +271,10 @@ Fixtures cover v1–v10 loading and migration. Exact roundtrips, malformed metad
renders and remapped live events cover the new writer/reader. Public clients
must rebuild and initialize the appended `xtc_automation_point.step` field.
## Phase 28 compatibility and diagnostic contract
## Compatibility and diagnostic contract
The current reader accepts versions 1–15 and the writer always emits version 15.
Phase 28 made no format change; Phase 31 adds plugin format identity in v11. Saving an older document upgrades it;
Compatibility diagnostics made no format change; plugin format identity is added in v11. Saving an older document upgrades it;
retain an original backup if an older application must still open it. APP is
informational; compatibility depends on the format version, not the producer's
application version. A future incompatible schema requires a new format number.
@ -338,7 +337,7 @@ reports I/O while leaving a complete new document; inspect it before retrying.
Fault wrappers are linked into tests only. These tests complement killed-writer
coverage in `make test-recovery`; they do not qualify power-cut behavior.
## Phase 31: version 11 plugin format identity
## Version 11: plugin format identity
Immediately after every plugin MODULE record, v11 requires:
@ -368,7 +367,7 @@ the existing document on failure. No automatic path search or plugin substitutio
occurs. Current and historical migration fixtures, malformed fields, identity
mismatch, missing-module and exact-render roundtrips cover this extension.
## Phase 32: version 12 track instruments
## Version 12: track instruments
After CONTROL_MAPS/MAP records and before END: