85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# Project format v2 (reads v1)
|
|
|
|
Phases 5/6 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 content is a subsequent phase.
|
|
|
|
## 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 2
|
|
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 -
|
|
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), 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; "-" means silent, 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.
|
|
- 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, 2 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. Saving always writes
|
|
v2. Unknown versions are rejected without replacing the destination; older
|
|
applications cannot read v2. 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.
|