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

10 KiB
Raw Blame History

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:

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

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.

Phase 26: 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.

Phase 27: 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 for the compatibility and relocation policy.

Phase 31: 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 v11 and read v1–v11. See PLUGIN_HOSTING.md for the full contract and test/qualification limits.