hanez/xtc
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

phase information removal.

Browse source
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
Download patch file Download diff file Expand all files Collapse all files

30
docs/AUDIO_ENGINE.md
View file

@ -26,7 +26,7 @@ rational timeline representations to avoid cumulative floating-point drift.
Define tempo-map conversion and behavior at tempo changes before implementing
tempo automation.
## Phase 1 offline API
## Offline API
`xtc_graph_create` accepts 1..256 nodes; IDs are monotonic stable identifiers, never reused
within a graph's lifetime. Enumeration indexes are dense and distinct from IDs. Supported nodes are gain (any finite multiplier), sine
@ -82,7 +82,7 @@ cycles, capacity limits, plan lifetime and repeated compilation/cleanup.
The offline API remains single-owner. The realtime/backend APIs below add
publication and JACK processing; offline tests alone do not qualify hardware.
## Phase 2 backend and realtime bridge
## Backend and realtime bridge
Use `xtc_backend.h` on one serialized control thread:
@ -135,11 +135,11 @@ internal realtime guarantees depend on the installed implementation/server.
Validation commands and results are recorded in BUILD.md and the integration
test README. Current limitations: mono input, no crossfaded graph changes, no automatic reconnect,
no physical-device or long-duration endurance qualification. Phase 3 connects
the FLTK shell to backend controls and status; see GUI.md. Its editors remain
placeholders except the Phase 4 modular editor described below.
no physical-device or long-duration endurance qualification. The FLTK shell is
connected to backend controls and status; see GUI.md. Its editors remain
placeholders except the modular editor described below.
## Phase 4 graph snapshots and edits
## Graph snapshots and edits
The control-thread API exposes copies through get_counts, get_node(index) and
get_connection(index), including node IDs/types/values and port endpoints. No
@ -182,7 +182,7 @@ offline/standalone callers. Input on unconnected nodes retains the existing
external-input contract; the GUI does not connect external JACK ports.
## Phase 5 transport
## Transport
Backend status includes a uint64 sample_position. Each successful processing
callback advances it by its exact frame count (including silence); errors do
@ -200,11 +200,11 @@ The GUI observes the counter every 100 ms, so visual updates are block-quantized
and delayed by polling. No external JACK transport synchronization is provided.
Silent clip metadata is control-thread data, never traversed by the callback.
Audio/MIDI scheduling will be added in later phases through compiled event/clip
plans rather than direct callback access to the editable project.
Audio/MIDI scheduling uses compiled event/clip plans rather than direct callback
access to the editable project.
## Phase 6 audio source and recording
## Audio source and recording
xtc_audio.h provides control-thread import and immutable preloaded clip plans.
The backend prepares a project only while stopped: build audio candidate,
@ -238,7 +238,7 @@ borrowed recorder; the caller must not free it before successful quiescence.
Live software source/capture acceptance and concurrent ring tests pass; physical
recording, latency compensation and disk endurance remain unverified.
## Phase 7 MIDI source
## MIDI source
The C MIDI plan prepares bounded source-relative notes into sample spans and
renders a separate instrument buffer. `xtc_plan_process_sources` and
@ -250,7 +250,7 @@ requests and no callback allocation/I/O. Stop/seek clear live voices; scheduled
notes chase their absolute phase. See MIDI.md for event ordering, panic semantics,
capacities and test coverage. No new dependency is required.
## Phase 8 stereo mixing and automation
## Stereo mixing and automation
Track settings and automation are copied into immutable source-plan snapshots.
`xtc_audio_plan_render_stereo` and `xtc_midi_plan_render_stereo` pan track audio
@ -264,7 +264,7 @@ bounded and allocation/I/O/lock free. Meter UI reads no active plan memory.
See MIXER.md for exact pan law, automation interpolation, event/source exceptions,
memory/history bounds and verification. Input/recording remain mono.
## Phase 9 native processing
## Native processing
Graph-native effects/sources use copied versioned descriptors, two independently
prepared mono instances and the existing plan ownership/retirement protocol.
@ -274,14 +274,14 @@ without rolling back already advanced DSP. Native event instruments can render
explicitly into graph instrument buffers. See NATIVE_API.md for exact lifecycle
and serialization limits and PERFORMANCE.md for measured workload and budgets.
## Phase 10 ownership audit
## Ownership audit
[RELIABILITY.md](RELIABILITY.md) records resource owners, publication and
reclamation ordering, callback work bounds and repeatable diagnostic tests.
Graph stereo rendering completes both channels before writing caller outputs;
either output may equal a source, but the output buffers must not overlap.
## Phase 12 quality policy
## Quality policy
[AUDIO_QUALITY.md](AUDIO_QUALITY.md) defines absolute musical timing, tempo snapshot
changes, scheduled source envelopes and configurable master transitions. The GUI