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

Docs file normalization.

Browse source
This commit is contained in:
Johannes Findeisen 2026-11-06 15:20:20 +01:00
commit 619c2d0808
46 changed files with 3587 additions and 2579 deletions
Download patch file Download diff file Expand all files Collapse all files

63
docs/ROUTING.md
View file

@ -1,15 +1,15 @@
# Modular routing workflow
# Modular Routing Workflow
Open Modular Graph (Ctrl+3). Select a node or wire to inspect it in the feedback
line. Nodes have stable IDs, role labels and distinct colors: teal sources,
purple gain/bus nodes, blue processors/meters and red output sums. LADSPA nodes
also show the saved plugin label. Track names remain in Sequencer/Mixer; the
Audio mix and MIDI mix graph sources represent their shared mix buffers, not
individual tracks. MIDI mix is the internal sine-instrument mix; its graph
ports carry audio, not MIDI events. Native nodes are trusted extensions.
individual tracks. MIDI mix is the internal sine-instrument mix; its graph ports
carry audio, not MIDI events. Native nodes are trusted extensions.
Wires show arrows from right-hand audio outputs to left-hand inputs. Selecting
a node highlights all its incoming/outgoing wires; selecting a wire shows its
Wires show arrows from right-hand audio outputs to left-hand inputs. Selecting a
node highlights all its incoming/outgoing wires; selecting a wire shows its
endpoint IDs. Inputs sum all connected signals without normalization; fan-out
sends the same signal to each destination. Multiple output nodes sum into the
engine output. Gain/bus nodes are ordinary summing gain processors, not a new
@ -31,6 +31,8 @@ path is not a substitute for stopping playback or muting a track. The graph
models one audio lane per port; stereo compilation processes paired independent
lanes. It does not expose separate left/right, MIDI or control wires.
---
## Commands
| Action | Operation |
@ -58,11 +60,13 @@ allocates a fresh stable node ID and is **one** semantic edit/undo step. It
preserves all other edges. Failure (including capacity, a missing/stale wire or
backend refusal) keeps the previous graph and plan. It introduces no new node
type or project record: v8 persistence already represents the resulting graph.
One-level stereo mix buses are added before shared graph sources (see
MIXER.md). Track templates, folders and independent per-track/bus graph inserts
remain deferred because graph sources still expose shared mixes.
One-level stereo mix buses are added before shared graph sources (see MIXER.md).
Track templates, folders and independent per-track/bus graph inserts remain
deferred because graph sources still expose shared mixes.
## Transactions, cycles and realtime ownership
---
## Transactions, Cycles and Realtime Ownership
The public C `xtc_graph_apply_edit` command constructs a private candidate.
`XTC_EDIT_INSERT_GAIN` uses `data.connection` and returns the fresh ID through
@ -77,34 +81,37 @@ The GUI clones its project and compiles/publishes the exact candidate through
the existing backend before replacing the displayed model/history. When running,
a complete immutable plan is adopted at a block boundary; the control thread
collects acknowledged retired plans. The feedback line distinguishes prepared,
queued and active revisions. A queued graph can appear before it becomes audible.
The single pending slot can reject a busy edit with CAPACITY: wait for adoption
and retry. There is no hidden unbounded edit queue or callback mutation. Normal
graph edits can run during playback; undo/redo uses the existing stopped-plan
installation contract. Recording still blocks semantic graph edits. Plan swaps
may reset oscillator/plugin state and are not crossfaded.
queued and active revisions. A queued graph can appear before it becomes
audible. The single pending slot can reject a busy edit with CAPACITY: wait for
adoption and retry. There is no hidden unbounded edit queue or callback
mutation. Normal graph edits can run during playback; undo/redo uses the
existing stopped-plan installation contract. Recording still blocks semantic
graph edits. Plan swaps may reset oscillator/plugin state and are not
crossfaded.
`xtc_graph_analyze` computes input/output edge counts, longest-path level,
rendered-output reachability and external-input fallback in dense-node order.
It is a bounded, allocation-free **control-thread** API, not a callback service.
It never loads plugins. It honors explicit outputs; legacy terminal fallback
rendered-output reachability and external-input fallback in dense-node order. It
is a bounded, allocation-free **control-thread** API, not a callback service. It
never loads plugins. It honors explicit outputs; legacy terminal fallback
applies only when there are no explicit output nodes and the caller has not
required them. Errors leave result storage/count unchanged. The GUI caches this
analysis when binding a graph; drawing reads cached metadata only. It uses
public C snapshots/commands and never engine internals or callback storage.
## Verification and limits
---
## Verification and Limits
`make test-routing` checks branch reachability, external input, levels, capacity
rollback, exact unity-insertion rendering and complete plan handoff. `make test`
also retains concurrent publication/lifecycle tests.
`make test-reliability` retains the callback-allocation guards.
`make test-gui-plugins` checks selection diagnostics, unique placement/layout,
failed backend publication, atomic insertion undo/redo and keyboard focus.
`make test-gui-jack` inserts/disconnects/restores real routes during live software
playback and checks engine revision acknowledgements and cycle rejection.
also retains concurrent publication/lifecycle tests. `make test-reliability`
retains the callback-allocation guards. `make test-gui-plugins` checks selection
diagnostics, unique placement/layout, failed backend publication, atomic
insertion undo/redo and keyboard focus. `make test-gui-jack`
inserts/disconnects/restores real routes during live software playback and
checks engine revision acknowledgements and cycle rejection.
Physical routing/listening and hardware endurance remain unqualified. This is
an audio-lane DAG editor with a default 64-node project capacity (standalone
C graphs up to 256), no zoom/lasso or persisted layout, no latency compensation
Physical routing/listening and hardware endurance remain unqualified. This is an
audio-lane DAG editor with a default 64-node project capacity (standalone C
graphs up to 256), no zoom/lasso or persisted layout, no latency compensation
and no plugin crash isolation. Unconnected branches are diagnosed, not pruned.