140 lines
8.1 KiB
Markdown
140 lines
8.1 KiB
Markdown
# 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
|
|
|
|
Follow BUILD.md and LINUX.md. Core: `make all test`; GUI: `make 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 install stage with `make install-gui DESTDIR="$PWD/build/stage"
|
|
PREFIX=/usr`, inspect the stage, and use your normal deployment process. A user
|
|
prefix is supported (for example an absolute path to your `.local` folder).
|
|
`make uninstall` with the same DESTDIR/PREFIX removes only that version's known
|
|
files. See LINUX.md for package extraction, dependencies and removal. Never use
|
|
a release built for a different system ABI without rebuilding/testing it.
|
|
|
|
## 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#phase-21-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 audio 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#phase-22-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).
|
|
|
|
Phase 24: 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.
|
|
|
|
Phase 25: 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.
|