xtc/docs/ROUTING.md

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.

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 bus/mixer-strip type. Add gain retains its existing 0.10 preset.

A yellow ! no output path badge and dim wires identify branches that cannot reach a rendered output. This is a structural warning, not an invalid graph: isolated nodes are allowed, and may still consume processing time. Conversely, “path to engine output” does not guarantee audible music: clips, MIDI, gain, mute, plugin behavior and external hardware routing still matter. Graph output is not an automatic JACK hardware connection.

An ext in port means it has no incoming graph wire: the existing renderer uses external audio input there (subject to its input gain), rather than silence. Connecting a wire replaces this fallback with the wired sum; deleting the last input wire restores fallback. This applies to unwired effects, meters and outputs. Generator/audio/MIDI sources have no input port. Removing an output 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
Connect	Drag an output circle to an input circle
Disconnect	Select a wire and press Delete/Backspace
Remove node	Select node, Delete; its incident wires are removed too
Inspect nodes	Click, or Left / Right within the focused graph
Arrange by signal flow	View menu, L with graph focus, or context menu
Insert unity gain	Select wire, Edit menu, I with graph focus, or context menu
Move / pan	Drag node body; scroll the canvas
Cancel drag	Escape

Right-click opens commands for the current selection. Auto-layout places each node in a column matching its longest source-to-node path and in a distinct row within that column. Disconnected roots remain in the first column. It enlarges the scrollable canvas when necessary. Moving, selecting and arranging are session UI changes; they do not publish audio plans, alter routing, or add undo steps. Open/undo may rebuild layout. Node positions are not persisted. Whole- project binding gives distinct initial grid positions to all new nodes.

Inserting unity gain replaces an existing wire A -> B by A -> gain -> B, with gain exactly 1. This simple reusable routing operation preserves level, 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.

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 out_added_id only on complete success. It disconnects, inserts and reconnects inside that private copy. Any failure destroys it; the source and output ID remain unchanged, and the graph output pointer is NULL. Ordinary connect/delete commands retain their existing transactional behavior. Self-edges, direct and indirect feedback cycles, wrong port directions, duplicate wires and missing ports are explicitly rejected. No feedback/delay-loop processing is supported.

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.

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 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

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.

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.