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

260
docs/USER_MANUAL.md
View file

@ -1,36 +1,44 @@
# xtc user manual (0.1.0 development build)
# 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.
are listed in KNOWN_LIMITATIONS.md; no production/device qualification is
implied.
## Build or install
---
## 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.
`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.
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
---
## 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.
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.
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.
@ -38,22 +46,27 @@ a release built for a different system ABI without rebuilding/testing it.
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.
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
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.
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.
## 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:
@ -62,62 +75,74 @@ 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.
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.
## Trusted Effects and Sources
## Diagnose a problem
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.
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.
## Diagnose A Problem
## MIDI composition
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.
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
---
## 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.
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.
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
---
## 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
@ -126,48 +151,54 @@ 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.
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.
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
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.
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.
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.
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.
**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
---
## 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
@ -178,9 +209,9 @@ 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
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.
@ -198,27 +229,32 @@ 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.
`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.
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.
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.
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.