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

225
docs/MIXER.md
View file

@ -1,42 +1,46 @@
# Studio mixer
# Studio Mixer
Open **View / Mixer** (Ctrl+2) to see a channel strip for every track and bus.
The horizontal scrollbar reveals additional channels; the master output monitor
stays pinned on the right. The bank supports the full 64-track/bus project limit.
Channel order follows the sequencer, and colors match the track headers.
stays pinned on the right. The bank supports the full 64-track/bus project
limit. Channel order follows the sequencer, and colors match the track headers.
Each strip offers:
- A name button that selects its track for automation below the bank.
- **Mute** and **Solo** switches using the existing inclusive track/bus solo rules.
- **Mute** and **Solo** switches using the existing inclusive track/bus solo
rules.
- A flat **Pan** knob: left -1, center 0, right +1. Drag to turn it;
double-click to center. The text shows direction and percentage.
- An output dropdown for **Master** or a project bus. Bus outputs stay at Master;
nested bus routing remains unsupported. **Add bus** creates a new bus strip.
- A vertical level fader, displayed in dB. Zero dB is unity gain. The upper limit
is approximately +12.04 dB (linear gain 4); the -60 dB bottom position is silence.
- An output dropdown for **Master** or a project bus. Bus outputs stay at
Master; nested bus routing remains unsupported. **Add bus** creates a new bus
strip.
- A vertical level fader, displayed in dB. Zero dB is unity gain. The upper
limit is approximately +12.04 dB (linear gain 4); the -60 dB bottom position
is silence.
- Independent stereo sample-peak meters, numeric dBFS readouts and sticky clip
indications. **Reset peaks** clears all strip and master clip latches.
Changing a fader or knob commits on release, so a completed gesture is one undo
step. The existing preparation guard stops playback before model edits and
rejects changes while recording. Failed edits restore the displayed model values.
Selections are UI state and create no undo step. Track IDs keep controls attached
to the correct channel after reordering, undo, deletion or project replacement.
rejects changes while recording. Failed edits restore the displayed model
values. Selections are UI state and create no undo step. Track IDs keep controls
attached to the correct channel after reordering, undo, deletion or project
replacement.
The top Track selector provides another way to select automation targets; the
bank scrolls to reveal the selection. M/S toggle the selected track's mute/solo,
Left/Right adjust its linear gain, Shift+Left/Right adjust pan, and Up/Down select
adjacent tracks. The existing automation controls below the bank retain Gain/Pan,
First tick and Linear/Hold interpolation. Click to add a point and right-click
near a point to remove it.
Left/Right adjust its linear gain, Shift+Left/Right adjust pan, and Up/Down
select adjacent tracks. The existing automation controls below the bank retain
Gain/Pan, First tick and Linear/Hold interpolation. Click to add a point and
right-click near a point to remove it.
Faders and knobs display **static** mix values. Automation replaces those values
during playback; the controls are not motorized automation displays. Automation
values retain their existing linear gain and pan units. Existing project files
store mix values and automation without a format change. Very small nonzero
gains display at the fader floor; pan/mute/solo edits preserve their actual value.
Moving the fader to its bottom explicitly sets silence.
gains display at the fader floor; pan/mute/solo edits preserve their actual
value. Moving the fader to its bottom explicitly sets silence.
Meters use the backend's consumed peak snapshot for every track and bus,
including offscreen channels. Track taps are after track controls and before the
@ -44,41 +48,49 @@ bus, bus taps follow bus controls, and the master follows the modular graph and
transport envelope. Missing taps decay to silence. Displays use instant attack,
20 dB/s release and sticky clipping at a linear sample peak of 1 or more.
Numeric displays have a -90 dBFS floor, channel bars a -60 dBFS floor; master
bars cover -90 to +6 dBFS. These are sample-peak meters, not loudness or true-peak
meters. The master strip is an output monitor, not a new gain control.
bars cover -90 to +6 dBFS. These are sample-peak meters, not loudness or
true-peak meters. The master strip is an output monitor, not a new gain control.
## Engine mixing behavior
---
Gain is a linear multiplier from 0 to 4. Pan ranges from -1 (left) to +1 (right):
center has unity on both sides and moving away attenuates the opposite side
linearly. This preserves existing centered mono levels; it is not an equal-power
pan law. Mute wins over Solo. Solo behavior across tracks and buses is defined below. WAV clips and scheduled MIDI use their containing track's settings before
summing into the audio/instrument graph sources. Live MIDI input and independent
graph oscillators/external input are unassigned sources and bypass track mixing.
Stereo WAV files are still downmixed at import; stereo output comes from panning
those mono sources. Separate per-track graph inserts/sends are deferred.
## Engine Mixing Behavior
## Automation lanes
Gain is a linear multiplier from 0 to 4. Pan ranges from -1 (left) to +1
(right): center has unity on both sides and moving away attenuates the opposite
side linearly. This preserves existing centered mono levels; it is not an
equal-power pan law. Mute wins over Solo. Solo behavior across tracks and buses
is defined below. WAV clips and scheduled MIDI use their containing track's
settings before summing into the audio/instrument graph sources. Live MIDI input
and independent graph oscillators/external input are unassigned sources and
bypass track mixing. Stereo WAV files are still downmixed at import; stereo
output comes from panning those mono sources. Separate per-track graph
inserts/sends are deferred.
---
## Automation Lanes
Choose Gain or Pan under Automation. The lane shows four bars (15360 ticks);
First tick moves its viewport across the project. Grid labels are absolute ticks.
Click to add a point or replace the point at that snapped time (1/16 note, 240
ticks). Vertical position maps to gain 0..4 or pan -1..1, top to bottom descending.
Right-click near a point's time to remove it. Removing every point restores the
static control. There are at most 1024 points globally, with one per
track/parameter/tick. Track deletion cascades to its automation.
First tick moves its viewport across the project. Grid labels are absolute
ticks. Click to add a point or replace the point at that snapped time (1/16
note, 240 ticks). Vertical position maps to gain 0..4 or pan -1..1, top to
bottom descending. Right-click near a point's time to remove it. Removing every
point restores the static control. There are at most 1024 points globally, with
one per track/parameter/tick. Track deletion cascades to its automation.
A nonempty lane replaces that parameter's static value. Between points the C
engine interpolates linearly or holds each segment (Interpolation chooser),
holding the first/last value outside
their range. Preparation converts ticks to integer sample endpoints, sorts and
indexes lanes. When several ticks quantize to one sample at very low sample
rates, the last point wins at that sample. Rendering searches prepared bounded
arrays; it never sorts, allocates, accesses project data, or calls the GUI.
Seeking and block partitioning give the same timeline values. Mute/solo are
static; automation capture, modes, curves and tempo automation are deferred.
holding the first/last value outside their range. Preparation converts ticks to
integer sample endpoints, sorts and indexes lanes. When several ticks quantize
to one sample at very low sample rates, the last point wins at that sample.
Rendering searches prepared bounded arrays; it never sorts, allocates, accesses
project data, or calls the GUI. Seeking and block partitioning give the same
timeline values. Mute/solo are static; automation capture, modes, curves and
tempo automation are deferred.
## Stereo output and meters
---
## Stereo Output and Meters
The GUI opens the JACK backend with two audio output ports: `output` (left) and
`output_right`. Input and raw WAV recording remain mono. Connect both outputs
@ -89,30 +101,34 @@ port. Old mono audio/MIDI render functions apply gain/mute/solo and gain
automation while ignoring pan; the stereo variants apply both lanes.
The graph executes the same topology separately on left and right buses;
oscillators advance once per frame and are centered on both sides. Existing
port metadata and validation describe the mono graph topology. Stereo processing
uses explicit paired buffers, not new port IDs. Output buffers must be distinct;
oscillators advance once per frame and are centered on both sides. Existing port
metadata and validation describe the mono graph topology. Stereo processing uses
explicit paired buffers, not new port IDs. Output buffers must be distinct;
stereo callers must not alias them with source buffers. Graph-node meter reads
report the maximum of both sides on the processing owner only.
Track and bus meters measure coherent audio plus scheduled MIDI sums, after their
own gain/pan/mute/solo controls, before the shared modular graph. A track tap is
before its parent bus: a muted bus can have active member-track meters. Bus taps
are after bus controls. Master L/R measure the final graph output after transport
fades; downstream effects and graph routing can change its level independently.
Track and bus meters measure coherent audio plus scheduled MIDI sums, after
their own gain/pan/mute/solo controls, before the shared modular graph. A track
tap is before its parent bus: a muted bus can have active member-track meters.
Bus taps are after bus controls. Master L/R measure the final graph output after
transport fades; downstream effects and graph routing can change its level
independently.
The backend retains interval sample-peak maxima until one serialized control
reader consumes them with `xtc_backend_read_meters`. The GUI polls about every
100 ms. Atomic channels are independent (not a simultaneous waveform snapshot);
peaks are quantized to 0.000001 linear and capped at 1000. Legacy backend status
peaks remain last-block linear values. GUI readouts display 20*log10(peak) dBFS, floor -90, with instantaneous
attack and 20 dB/second release. Channel bars cover -60 to +6 dBFS; master
bars cover -90 to +6 dBFS.
Each channel latches red CLIP at linear peak >=1 (0 dBFS) until Reset peaks.
Reset is session state, not an audio edit. Selection changes preserve every strip's meter history. These are sample-peak meters, not RMS, LUFS or true-peak measurements.
There is no limiter; summed levels can exceed unity.
peaks remain last-block linear values. GUI readouts display 20*log10(peak) dBFS,
floor -90, with instantaneous attack and 20 dB/second release. Channel bars
cover -60 to +6 dBFS; master bars cover -90 to +6 dBFS. Each channel latches red
CLIP at linear peak >=1 (0 dBFS) until Reset peaks. Reset is session state, not
an audio edit. Selection changes preserve every strip's meter history. These are
sample-peak meters, not RMS, LUFS or true-peak measurements. There is no
limiter; summed levels can exceed unity.
## Mix buses and gain staging
---
## Mix Buses and Gain Staging
Use Add bus in Mixer, select an ordinary track, then choose its Route: Master or
an existing bus. Buses share the 64-track capacity and gain/pan automation APIs.
@ -123,42 +139,45 @@ routing. Editing uses the existing stopped-transport preparation workflow.
Track controls apply first, then parent bus controls, then the shared graph.
Gain multiplies (track 2 times bus 2 gives 4); pan uses the same center-unity
balance law at both stages. There is no normalization or automatic attenuation.
Solo is one inclusive domain: a soloed track passes through its bus, a soloed bus
admits all its members, and unrelated tracks are silent. Track mute silences
Solo is one inclusive domain: a soloed track passes through its bus, a soloed
bus admits all its members, and unrelated tracks are silent. Track mute silences
that member; bus mute silences its entire output even when a member is soloed.
Live MIDI, external audio inputs and independent graph oscillators remain
unassigned and outside this solo domain.
Master here means the source mix feeding the shared graph, not independent
per-bus effect chains. Graph fan-out and gain branches permit parallel processing
of shared sources. Independent per-track aux sends, sidechains, bus plugin
inserts and nested buses are not represented and remain deferred.
per-bus effect chains. Graph fan-out and gain branches permit parallel
processing of shared sources. Independent per-track aux sends, sidechains, bus
plugin inserts and nested buses are not represented and remain deferred.
Preparation allocates shared stereo monitor scratch on the control thread:
2 * track_count * max_frames * sizeof(float), at most 32 MiB at current limits.
The callback clears, accumulates and scans bounded buffers, with no allocation,
I/O, locks or GUI calls. Immutable audio/MIDI snapshots borrow this scratch until
Preparation allocates shared stereo monitor scratch on the control thread: 2 *
track_count * max_frames * sizeof(float), at most 32 MiB at current limits. The
callback clears, accumulates and scans bounded buffers, with no allocation, I/O,
locks or GUI calls. Immutable audio/MIDI snapshots borrow this scratch until
stopped replacement or backend destruction.
## Undo and keyboard workflow
---
Ctrl+Z undoes; Ctrl+Shift+Z or Ctrl+Y redoes. The C history keeps 32 project edits
plus a baseline, cloning metadata and graph, never audio samples. Common graph,
track, clip, note, mixer, import/relink and automation edits are included. One
accepted gesture is one step; selection, scrolling and graph-node placement are
GUI state and are not undoable. New/Open resets history; Save retains it.
Undo/redo stops and resets transport; surviving selections are preserved by
stable ID (layout remains session state). The
candidate is installed before moving the history cursor: validation, asset-plan
or backend failure retains the current document and history position. Missing
assets retain the existing silent/reporting behavior. A new edit after Undo
removes the redo branch; the oldest state is evicted at capacity. Allocation
ID high-water marks survive Undo/branching so abandoned IDs are not reused. History is
session-only and Undo marks the document dirty even if it matches a saved state.
External WAV files are never deleted or restored by Undo; recording itself cannot
be undone while active. Snapshot storage is reserved before GUI commands mutate/publish, so an
allocation failure rejects the command before adoption; reserved capture itself
does not allocate. C clients using unreserved history record must handle errors.
## Undo and Keyboard Workflow
Ctrl+Z undoes; Ctrl+Shift+Z or Ctrl+Y redoes. The C history keeps 32 project
edits plus a baseline, cloning metadata and graph, never audio samples. Common
graph, track, clip, note, mixer, import/relink and automation edits are
included. One accepted gesture is one step; selection, scrolling and graph-node
placement are GUI state and are not undoable. New/Open resets history; Save
retains it. Undo/redo stops and resets transport; surviving selections are
preserved by stable ID (layout remains session state). The candidate is
installed before moving the history cursor: validation, asset-plan or backend
failure retains the current document and history position. Missing assets retain
the existing silent/reporting behavior. A new edit after Undo removes the redo
branch; the oldest state is evicted at capacity. Allocation ID high-water marks
survive Undo/branching so abandoned IDs are not reused. History is session-only
and Undo marks the document dirty even if it matches a saved state. External WAV
files are never deleted or restored by Undo; recording itself cannot be undone
while active. Snapshot storage is reserved before GUI commands mutate/publish,
so an allocation failure rejects the command before adoption; reserved capture
itself does not allocate. C clients using unreserved history record must handle
errors.
With mixer focus, M/S toggles mute/solo, Left/Right changes gain by 0.05,
Shift+Left/Right changes pan, and Up/Down selects a track. Native sliders also
@ -168,30 +187,34 @@ singly selected; automation-point dragging is not implemented. Track rename and
arrangement clipboard editing are available. See MODERN_EDITING.md for static
mixer A/B comparison and its automation limits.
## Verification and limits
---
## Verification and Limits
`test_mixer` verifies exact stereo gain/pan, mute/solo precedence, automation
samples and block equivalence, stereo graph phase/routing, WAV mixing, v4 exact
roundtrip/truncations/malformed records, lane capacities and history eviction and
branching. Backend fault injection verifies stereo registration failure, output
names, output separation and atomic meters. GUI tests edit lanes with mouse
events, use mixer keys and exercise undo/redo, failed installation rollback,
branching, save/reopen and history reset. Live JACK MIDI acceptance verifies
saved/reopened hard-right playback and stereo peaks using only software clients.
A native Xvfb mouse smoke check covers sliders and automation drawing.
Checks cover independent strip callbacks/meters, fader gestures, pan
centering, failed-edit restoration, routing, undo/reload, duplicate names and
stable IDs across reorder/removal. A 64-channel GUI session verifies scrolling
and minimum/large layouts. Screenshots include live JACK meters and a bus strip.
roundtrip/truncations/malformed records, lane capacities and history eviction
and branching. Backend fault injection verifies stereo registration failure,
output names, output separation and atomic meters. GUI tests edit lanes with
mouse events, use mixer keys and exercise undo/redo, failed installation
rollback, branching, save/reopen and history reset. Live JACK MIDI acceptance
verifies saved/reopened hard-right playback and stereo peaks using only software
clients. A native Xvfb mouse smoke check covers sliders and automation drawing.
Checks cover independent strip callbacks/meters, fader gestures, pan centering,
failed-edit restoration, routing, undo/reload, duplicate names and stable IDs
across reorder/removal. A 64-channel GUI session verifies scrolling and
minimum/large layouts. Screenshots include live JACK meters and a bus strip.
Physical stereo devices, listening quality, realtime endurance and high-density
project performance remain unverified; no new dependency was introduced.
`test_buses` covers bus routing, exact taps, audio/MIDI cancellation, controls,
automation, persistence, invalid routes, deletion/undo and dBFS ballistics. Backend
tests cover consuming interval peaks; GUI tests cover routing undo and clipping.
automation, persistence, invalid routes, deletion/undo and dBFS ballistics.
Backend tests cover consuming interval peaks; GUI tests cover routing undo and
clipping.
Linear/Hold interpolation is available for each point added or replaced. The
point's mode applies to its following segment. Static controls remain fallbacks
while a lane exists; moving/splitting clips does not move absolute track/bus lanes.
See CONTROL.md for common parameter IDs and controller/automation precedence.
while a lane exists; moving/splitting clips does not move absolute track/bus
lanes. See CONTROL.md for common parameter IDs and controller/automation
precedence.