xtc/docs/USER_MANUAL.md

# xtc User Manual (0.1.0 Development Build)

xtc is a bounded Linux music-making prototype. Start with a copy of an important
project and keep backups of its WAV media. Supported limits and unfinished areas
are listed in KNOWN_LIMITATIONS.md; no production/device qualification is
implied.

---

## Build or Install

Configure first with `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug`; see
BUILD.md and LINUX.md. Core: `cmake --build build --parallel && cmake --build build --target check`; GUI: `cmake --build build --target gui`, then
`./build/xtc`. Use an existing JACK-compatible server and reconnect with F6.
Connect `midi_in` to a controller, `input` to mono capture and `output` /
`output_right` to left/right playback using your JACK routing application. No
server, physical routing or system configuration is changed automatically.
`xtc --version`, `xtc --help` and `xtc --diagnose` need no display/server.

For a source installation, configure `-DCMAKE_INSTALL_PREFIX=/usr`, build, then
stage with `DESTDIR="$PWD/build/stage" cmake --install build`. Inspect the stage
and use your normal deployment process. A user prefix such as an absolute path
to `.local` is also supported. Use `cmake --build build --target uninstall`
with the same DESTDIR and configured prefix for exact removal. See LINUX.md for
package extraction, dependencies and removal. Rebuild and test for the intended
system ABI before deployment.

---

## Make A Short Project

1. New/Open starts in Sequencer. Add track; use F2 to name it.
2. Add MIDI clip, select it and open Piano roll (Ctrl+4). Left-click to draw
   notes, drag to move, drag a right edge to resize, Delete/right-click to
   remove.
3. Alternatively Import WAV (Ctrl+I). It creates/routes an Audio clips source;
   supported WAV formats and preload limits are in AUDIO_FILES.md.
4. Drag clips to arrange them and edges to trim. View/Snap sets the timeline
   grid; +/- zoom buttons and scrollbars navigate. Ctrl+D duplicates a clip
   after its end, retaining its complete source. F2 names clips; right-click
   offers duplicate/rename/delete. Alt+Up/Down with timeline focus reorders
   tracks.
5. Play/F5 starts; Pause/F7 or Stop/F8 leaves the position for resuming. Home
   returns to start while stopped (or stops first); click the ruler to seek.
   Recording uses Stop, not Pause. F9 Panic releases the instrument.
6. Mixer (Ctrl+2) offers track gain/pan/mute/solo and Gain/Pan automation lanes.
   Click to add points, right-click to remove. CONTROL.md explains timing and
   live CC7 volume, CC10 pan and CC64 sustain.
7. Save (Ctrl+S), close, reopen and continue editing. Ctrl+Z undoes and
   Ctrl+Shift+Z/Ctrl+Y redoes. New/Open resets history after unsaved-change
   handling.

Modular Graph (Ctrl+3) exposes routing. Drag output to input to connect, select
a wire/node and Delete to remove; cycles and invalid ports are rejected. Keep an
Output route for playback. GUI changes show queued/active graph status. Graph
positions are session-only; music/routing/automation are saved. Edits that
prepare new plans stop playback; disk/compilation may pause the GUI, never run
in audio.

---

## Record and Retain Media

Choose a project folder and save the project there first. Record/Shift+F5 asks
for an unused WAV path. Stop finalizes the take and inserts it. Existing
destinations are protected, including a file created while recording.
Undo/removing a take removes its reference, never the recorded file. Imported
external files are also never deleted. WAVs inside the save folder become
relative references; move the folder and media together. Save As preserves the
same source media, not a copy.

On write failure the GUI reports a retained path. Keep it and recover complete
frames to a different, unused destination:

```sh
xtc-check --recover-recording take.wav.tmp.XXXXXX recovered.wav
```

Only xtc's canonical float32 mono temporary format is salvaged. Incomplete
trailing frames are omitted. The source is retained. Import/relink the recovered
WAV. Missing/unreadable media is silent and reported; select the clip and use
File/ Relink selected audio. See RECOVERY.md for interruption, disk-full and
power-loss limits. Close/project operations are refused while recording; finish
the take first.

---

## Trusted Effects and Sources

File/Load LADSPA plugin lists compatible descriptor indices from the chosen
`.so`. Loading executes native code. Select a documented compatible mono plugin,
connect its graph ports, then use Edit/Selected plugin control. Edit/Selected
plugin automation adds/removes tick-based linear or step points. Control
names/ranges appear in the dialogs. Module identity/control values/lanes save
with the project; module binaries and DSP history do not. The initial
amp/inverter/sine set and unsupported layouts are listed in PLUGIN_HOSTING.md.
Missing plugins reject GUI Open with identity/path information and preserve the
saved/current documents. Restore the compatible module at that path and retry.
Plugins are not sandboxed.

---

## Diagnose A Problem

Run `xtc-check --diagnose` and capture the version, architecture, compiled
features, GUI error text and steps to reproduce. `xtc-check --validate song.xtc`
checks metadata without opening plugins/media; it does not certify playback
resources. Check JACK routing, sample rate/format and xrun/process status in the
GUI. After server loss/rate change stop/reconnect and retry. Keep the original
project, media and retained temporary files before recovery attempts.

A native plugin can crash/hang the process. There is no crash-isolation
guarantee. Use the operating system's core-dump/debugger tools if available; xtc
does not install signal handlers, change core limits or upload crash reports.
Debugger/ core files may contain media paths and audio memory; share only what
you intend. Report bugs following MAINTENANCE.md, including whether the issue
reproduces without plugins. Physical listening and independent human
install/usability acceptance remain pending.

---

## MIDI Composition

In Piano roll, use the Notes menu for grid (including triplets), channel/pitch
filters, velocity/channel, quantization, transposition and pattern repetition.
Click selects a single note; Ctrl+A selects all filtered notes. Ctrl+D repeats
that selection at a chosen spacing within the existing clip source. Up/Down
transposes by a semitone. Commands are undoable through the main Edit menu. See
[MIDI.md](MIDI.md#composition-commands) for shortcuts, timing and limits.

---

## Audio Clip Tools

Select an audio clip, click the ruler at the desired cut while stopped, then
choose Edit / Split clip at cursor (S with timeline focus). Ctrl+D duplicates;
Delete removes the clip reference. Drag the body to move and edges to trim. Edit
/ Audio clip gain and fades (A) sets linear gain and fade durations in ticks.
All are undoable and preserve the WAV file. Waveforms show cached raw source
peaks, before gain/fades; large media can take time to load on Open/import. See
[AUDIO_FILES.md](AUDIO_FILES.md#non-destructive-clip-editing) for boundary
behavior, preview limits and the deferred stretch/pitch tools.

---

## Inspecting and Organizing Routing

In Modular Graph, select a node or wire to inspect its routing in the feedback
line. Arrows show direction; yellow no-output badges identify disconnected
branches. L arranges nodes by signal flow. Select a wire and press I to insert a
unity gain/bus node as one undoable edit. These commands are also in View/Edit
and the graph context menu. Unwired effect inputs use external audio, as shown
by “ext in”; they do not imply silence. See [ROUTING.md](ROUTING.md).

The Mixer also offers Add bus and a Route choice for ordinary tracks. Select
Track/Bus strips to edit their controls and automation. Master and selected
strip meters show dBFS with 20 dB/s release; Reset peaks clears latched
clipping. See MIXER.md for solo rules, gain staging and meter taps.

File → Load LADSPA plugin offers a descriptor browser. Select a graph plugin and
Edit → Selected plugin control for identity, values, ranges and Reset defaults;
Apply commits, Cancel discards. Edit also offers replacement, reset and
insertion of an effect on a selected wire. Graph wires determine processing
order; Delete removes a selected plugin and its wires. Changes are undoable.
Replacement keeps compatible audio wiring but resets plugin controls and
automation. See PLUGIN_HOSTING.md for supported formats and failure behavior.

Mixer Interpolation selects Linear or Hold for each point added or replaced.
Audio → MIDI controller mapping lists all channel bindings; enter
`channel volume_CC pan_CC sustain_CC` (channels 0..15, 128 disables, enabled CCs
must be distinct, 120/123 reserved). Maps are undoable and saved. Controllers
modify live sine voices; arranged track/bus/plugin automation takes precedence
over its static controls and is unaffected by those MIDI bindings. See
CONTROL.md.

Unavailable main-menu undo/redo actions are disabled, including while recording.
Piano roll has Edit/Undo/Redo shortcuts and a right-click note menu; right-click
no longer immediately deletes notes. Graph right-click targets the node/wire
under the pointer. Undo preserves surviving selections. Completed takes add one
undo step; undo removes references and keeps WAV files. See EDITING.md for
grouped commands, failure handling and keyboard/focus behavior.

Project troubleshooting: `xtc-check --validate PROJECT.xtc` reports metadata
errors with the expected record and syntax line.
`xtc-check --inspect PROJECT.xtc` lists resolved media/module paths and plugin
identities without executing plugins or starting JACK. Exit codes: 0 = valid
metadata and available files, 2 = missing or unreadable references, 1 =
metadata/I/O error. File availability does not certify WAV contents or plugin
compatibility. See [PROJECT_FORMAT.md](PROJECT_FORMAT.md) for the compatibility
and relocation policy.

**File → Load plugin** supports LADSPA plus an initial Linux CLAP/VST2/VST3
effect subset. Select the actual module binary (`.clap` or `.so`, including a
VST3 bundle's inner binary). Modern effects require one mono input and output,
float32 and zero latency; they use default configuration. Instruments, modern
parameter editing/automation, opaque state and custom editors are not
implemented. Projects now save v12 and read v1–v12. See PLUGIN_HOSTING.md for
the full contract and test/qualification limits.

---

## Instrument Support

MIDI tracks can bind CLAP, VST2 and VST3 instruments. In the Track menu, select
**Load instrument plugin** for the selected sequencer track; **Use built-in
instrument** removes the binding. Assignment also selects the track for live
MIDI. **Live MIDI to selected instrument** changes that target; **Live MIDI to
built-in sine** restores the legacy live source. MIDI clip notes always go to
their own track's instrument. Independent instances feed track gain/pan,
mute/solo, bus routing and automation. Bindings/live target save in v12.

Supply the actual trusted Linux binary (including the inner .so of a VST3
bundle). Supported instruments have zero audio inputs, one mono output, float32
processing, zero latency and one note/event input. Default configuration only:
no custom editor, opaque state/preset restoration, modern parameter
editing/automation, stereo/multichannel instruments or MIDI output. No arbitrary
third-party instrument is qualified by the original ABI fixture tests.

CLAP accepts MIDI or native notes; VST2 uses MIDI events; VST3 uses IEventList
note events. Live CC reaches CLAP MIDI/VST2; native CLAP/VST3 have no controller
mapping (including sustain). Live MIDI goes to exactly one selected target.
Seeks/loops retrigger notes crossing the destination with fresh envelopes;
plugin oscillator/opaque DSP state cannot be reconstructed. Panic delivers
all-off (VST3 held-key note-offs); plugin release tails may remain. Processing
uses preallocated 256-frame chunks and 256 incoming events per instance/chunk;
overflow or processing failure silences the block and schedules reset events.
The existing 32 simultaneous scheduled-note and 4096 stored-note bounds remain.
Do not unload/replace modules during playback; candidate plans are prepared off
the callback and old instances are reclaimed on the control thread. Missing
references remain inspectable without loading; failed GUI preparation retains
the current project. Save a backup for applications limited to v11 or earlier.

---

## Workspace

The flat workspace puts New MIDI/audio track, WAV import and instrument loading
in a persistent sidebar, with a musical transport display and selected-track
overview. See [WORKSPACE.md](WORKSPACE.md) for shortcuts and workflow. Open
`modern-session.xtc` in the installed examples for an original four-track
arrangement.

Use the sequencer Snap dropdown for straight/triplet/bar grids or Off.
Double-click MIDI clips to edit notes, then use the Velocity lane or
selected-note slider for dynamics. Each non-bus track header has an instrument
dropdown offering built-in sine, project instruments and explicit plugin
loading. See WORKSPACE.md.

Additive clip selection, atomic group commands, phrase clipboard and repeat,
alignment/slip tools, MIDI swing/gate/legato/scale/velocity transforms, batch
audio fades and static mixer A/B recall are also available. See
[MODERN_EDITING.md](MODERN_EDITING.md) for commands, scope and limitations.

See [arrangement and composition workflows](COMPOSITION_WORKFLOWS.md) for
markers, MIDI composition, normalization and portable media collection.

Select an audio clip and open View / Sample editor (or double-click it) to
inspect source samples, choose native frame ranges, trim the clip or export a
new WAV. Processing and one-level local undo remain in the editor until Save
full copy and relink. See [AUDIO_EDITOR.md](AUDIO_EDITOR.md) for all sample
tools, transient slicing, musical-tick rounding and source preservation limits.