armin/xtc
1
0
Fork 0
forked from hanez/xtc
Code Pull requests Activity

Phase 2.

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-26 23:32:04 +01:00
commit 577d80f018
16 changed files with 1100 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

58
docs/AUDIO_ENGINE.md
View file

@ -77,5 +77,59 @@ Tests in `tests/unit/test_offline.c` cover known oscillator samples, gain and
meter output, reset and partition equivalence, fan-out/fan-in, reverse insertion
order, disconnected nodes, in-place processing, nonfinite input, invalid ports,
cycles, capacity limits, plan lifetime and repeated compilation/cleanup.
Hardware playback, concurrent graph publication and backend stress tests remain
Phase 2 work; this offline API does not claim hardware real-time qualification.
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
Use `xtc_backend.h` on one serialized control thread:
1. Open a config with `XTC_BACKEND_JACK`, a client name, channel_count 1, and
max_frames 1..65536. It must accommodate the server's current buffer size.
The actual rate and buffer size are returned through get_status. Open does
not start the server or acquire devices directly. Invalid config returns
invalid argument, missing build support returns unsupported, and JACK setup
failures return I/O error. If cleanup itself fails, a non-NULL output handle
is preserved for close retry; no other operation is allowed on that handle.
2. Submit a graph (copied/compiled at the server rate), then start. Starting
an already running client is an invalid-state error; stopping a stopped
client succeeds. With no submitted graph, callbacks produce silence.
3. Enumerate available audio ports with visit_ports. Names are borrowed only
during the visitor; do not reenter backend operations from the visitor.
Connect the client's input to a remote output or its output to a remote
input explicitly. JACK maps device selection to server/device port routes;
ALSA device identifiers are not accepted here. The server controls rate,
period and hardware configuration outside this API. Names/ports can disappear
between enumeration and connection; route failures are returned as I/O errors.
4. During playback, submit edited graphs and periodically collect retired
resources. Capacity means one pending graph is still awaiting adoption;
keep the current graph and retry later. get_status is a nonblocking snapshot
of rate, frames, running/server-loss/rate-change flags, xruns, processed
blocks and last process result. No active DSP memory is exposed.
5. Stop pauses the retained DSP state after deactivation. Restart resumes it.
Close removes the JACK client, synchronizes all callbacks, then destroys
plans. Stop/close failures preserve the handle for recovery/retry. No plan
is freed on the audio thread. Sample-rate change or server loss requires
close/reopen and a fresh submission; there is no automatic reconnect.
Buffers can change size. In-limit changes process normally; oversized blocks
are silent and report capacity errors until the size is supported again.
Rate changes latch silence and invalid-state processing results. A missing input
buffer is treated as unavailable input (silence). A missing output buffer is
reported as an I/O process error. Shutdown callbacks only set the loss flag;
the control thread closes the client. No JACK or GUI types cross the C API.
The standalone `xtc_realtime.h` API allows hardware-independent consumers and
stress tests. Submit compiles on the producer; process adopts at a block
boundary without allocation/free, I/O, locks or waits. All process calls must
come from one consumer thread, and destruction requires that consumer stopped
and joined. Release/acquire publication, retirement backpressure and atomic
requirements are specified in decision 0004. Ordinary project processing and
JACK notification callbacks were audited for prohibited operations; JACK's own
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/output, no parameter ramping or
crossfaded graph changes, no realtime meter bridge, no automatic reconnect,
no physical-device or long-duration endurance qualification. GUI controls and
status display are Phase 3; the GUI remains a placeholder shell.