95 lines
5 KiB
Markdown
95 lines
5 KiB
Markdown
# Project format v3 (reads v1/v2)
|
||
|
||
Phases 5–7 use 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.
|
||
|
||
## Schema
|
||
|
||
Records occur in this exact order, separated by LF, including the final record.
|
||
Fields use ASCII spaces. Integers are unsigned decimal, without signs.
|
||
Counts determine the number of subsequent records:
|
||
|
||
```text
|
||
XTC_PROJECT 3
|
||
APP 0 1 0
|
||
TEMPO 120000
|
||
IDS 1 1
|
||
GRAPH 1 2 2 1
|
||
NODE 0 1 3e800000
|
||
NODE 1 4 00000000
|
||
EDGE 0 1
|
||
TRACKS 1
|
||
TRACK 0 547261636b
|
||
CLIPS 1
|
||
CLIP 0 0 3840 2880 960 3840 526567696f6e
|
||
ASSET -
|
||
MIDI 0
|
||
NOTES 0 0
|
||
END
|
||
```
|
||
|
||
- `APP`: producer major/minor/patch; informational, never executed.
|
||
- `TEMPO`: constant milli-BPM (20000..300000, default 120000), fixed 4/4.
|
||
- `IDS`: next track ID and next clip ID. IDs are uint64, monotonic and never
|
||
reused; UINT64_MAX is reserved. Track and clip ID namespaces are separate.
|
||
- `GRAPH`: output-node policy (0/1), next node ID, node count, edge count.
|
||
Nodes retain stable IDs (limited to the host's size_t range). No pointers or
|
||
compiled state are serialized.
|
||
- `NODE`: ID, type (1 gain, 2 oscillator, 3 meter, 4 output, 5 audio source, 6 instrument), and exactly eight
|
||
hexadecimal digits encoding the IEEE binary32 parameter bits, independent
|
||
of locale and host byte order. Nonfinite values are rejected.
|
||
- `EDGE`: source and destination node IDs. Mono port directions are implied
|
||
by node type; endpoints, duplicates and cycles are validated by the graph API.
|
||
- `TRACK`: ID and hex-encoded name bytes.
|
||
- `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
|
||
length. Overlaps are allowed and audio clips mix through the audio source node.
|
||
- `ASSET`: required after each CLIP in v2/v3; "-" means no audio asset, otherwise
|
||
hex-encoded absolute path bytes, <=511 bytes after decoding, no embedded NUL
|
||
or ASCII control characters. Each clip directly references a WAV; no sample
|
||
data, pointers or DSP state are embedded. Paths can contain spaces.
|
||
- `MIDI`: required after each ASSET in v3; 0 for silent/audio regions, 1 for
|
||
MIDI clips. MIDI clips must have no asset.
|
||
- `NOTES`: next stable note ID and global note count, followed by that many
|
||
`NOTE id clip_id start_tick length_tick pitch velocity channel` records.
|
||
Notes reference MIDI clips; start/length are source-relative, positive length
|
||
within source bounds. Pitch is 0..127, velocity 1..127, channel 0..15.
|
||
Note IDs are unique, monotonic uint64 IDs with UINT64_MAX reserved.
|
||
- Names decode to nonempty valid UTF-8 of at most 63 bytes; ASCII control
|
||
characters and embedded NULs are forbidden. Hex avoids quoting ambiguity.
|
||
|
||
Ticks use 960 per quarter note, 3840 per bar. All region endpoints are bounded
|
||
by 38400000 ticks (10000 bars). Limits: 64 tracks, 1024 clips, 64 graph nodes,
|
||
4096 edges, 4096 notes, 4 MiB input, 1535 bytes per record, 12 tokens per record. The reader
|
||
rejects invalid references, duplicate IDs, inconsistent next IDs, ranges,
|
||
truncated records, raw control/non-ASCII bytes, and trailing data.
|
||
|
||
Unsupported format versions return UNSUPPORTED. Other malformed data returns
|
||
FORMAT. The reader explicitly accepts v1 records without ASSET lines, with
|
||
node types 1..4, migrating their clips to empty asset paths. Version 2 accepts
|
||
node types 1..5 and ASSET records. Both migrate to MIDI=0 and no notes.
|
||
Saving always writes v3. Unknown versions are rejected without replacing the destination; older
|
||
applications cannot read v3. Migration and maximum-path roundtrips are tested.
|
||
|
||
## Ownership and failures
|
||
|
||
Load builds and validates a separate candidate, closes the input, then replaces
|
||
the destination. Any failure retains the complete previous project. Saving
|
||
validates the project, creates a mode-0600 temporary in the destination
|
||
directory, writes, flushes, fsyncs, closes and renames over the destination.
|
||
Failures before rename retain the previous destination and remove the temporary.
|
||
The parent directory is not fsynced: survival of the rename through sudden power
|
||
loss is not guaranteed. Save replaces symlinks themselves and does not preserve
|
||
existing file permissions. POSIX I/O is private to the Linux-first persistence
|
||
module; public headers contain no POSIX types.
|
||
|
||
Saved data reproduces the arrangement and graph, including ID allocation state.
|
||
Graph node positions, timeline zoom/scroll/selection, transport position and DSP
|
||
oscillator phase are GUI/session state and are not saved. Asset references are
|
||
external absolute paths, not copied on Save As. Metadata loading preserves
|
||
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.
|