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

139
docs/WORKFLOW.md
View file

@ -1,14 +1,17 @@
# Make and reopen a small project
# Make and Reopen A Small Project
The default workspace is Sequencer. New and Open return to this workspace;
Mixer and Modular Graph remain available with Ctrl+2 and Ctrl+3. Start with an
empty project at 120 BPM, 4/4. Clips default to one bar and piano-roll notes use
The default workspace is Sequencer. New and Open return to this workspace; Mixer
and Modular Graph remain available with Ctrl+2 and Ctrl+3. Start with an empty
project at 120 BPM, 4/4. Clips default to one bar and piano-roll notes use
velocity 100; no notes or test oscillators are inserted automatically.
## Create music
---
1. Start your existing JACK-compatible server, launch `xtc`, and check that audio
says ready/stopped. If disconnected, start the server and use Reconnect/F6.
## Create Music
1. Start your existing JACK-compatible server, launch `xtc`, and check that
audio says ready/stopped. If disconnected, start the server and use
Reconnect/F6.
2. Click Add track, then Add MIDI clip. Click Piano roll (Ctrl+4) and click the
grid to draw notes. Drag notes to move them or their right edges to resize.
Close the piano-roll window to return to the arrangement.
@ -21,14 +24,16 @@ velocity 100; no notes or test oscillators are inserted automatically.
5. MIDI creation supplies an instrument-to-output route, and audio import
supplies an audio-to-output route for a new project. No graph editing or
project-file editing is required. Ctrl+3 shows these routes if you want to
inspect or change them. Existing custom routes are respected; see MIDI.md
and AUDIO_FILES.md for routing limits.
inspect or change them. Existing custom routes are respected; see MIDI.md and
AUDIO_FILES.md for routing limits.
6. In your existing JACK routing tool, connect xtc's `output` and `output_right`
ports to left/right playback inputs. Press Play/F5. Mixer/Ctrl+2 shows output
meters and track gain/pan/mute/solo. If meters move but nothing is audible,
check external playback routing and device levels. xtc does not connect
physical ports automatically or start/configure the server.
---
## Transport
| Command | Behavior |
@ -41,27 +46,30 @@ velocity 100; no notes or test oscillators are inserted automatically.
| Click timeline ruler | Seek on the sixteenth-note grid while stopped; during playback the seek is refused. |
| New / Open / Reconnect | Stop and reset the position. New/Open show Sequencer; Reconnect leaves the document intact. |
Pause/Stop completion is asynchronous: the GUI briefly shows “stopping”. Recording
Stop and Home retain immediate deactivation. See [AUDIO_QUALITY.md](AUDIO_QUALITY.md)
for the 5 ms fade policy and timing bounds.
Pause/Stop completion is asynchronous: the GUI briefly shows “stopping”.
Recording Stop and Home retain immediate deactivation. See
[AUDIO_QUALITY.md](AUDIO_QUALITY.md) for the 5 ms fade policy and timing bounds.
The backend sample count drives the playhead; its display refreshes every 100 ms.
Pause/Stop retain the exact sample position even though the ruler displays ticks.
Arrangement, note and mixer edits stop playback; graph edits can be adopted live.
A failed stop leaves playback running and the controls reflect that. A failed
return-to-start seek does not set the cursor to zero. If candidate project
preparation fails after stopping/seeking, the old document stays loaded and the
GUI refreshes to its actual stopped position (which may be zero). A parse failure
occurs before installation and leaves playback alone.
The backend sample count drives the playhead; its display refreshes every 100
ms. Pause/Stop retain the exact sample position even though the ruler displays
ticks. Arrangement, note and mixer edits stop playback; graph edits can be
adopted live. A failed stop leaves playback running and the controls reflect
that. A failed return-to-start seek does not set the cursor to zero. If
candidate project preparation fails after stopping/seeking, the old document
stays loaded and the GUI refreshes to its actual stopped position (which may be
zero). A parse failure occurs before installation and leaves playback alone.
## Save, close and continue
---
## Save, Close and Continue
Use File/Save (Ctrl+S), choose a `.xtc` path and retain external WAV files. The
unsaved title marker clears on success. File/Save As confirms overwrites.
Close the window, launch xtc again and use File/Open (Ctrl+O), or run
unsaved title marker clears on success. File/Save As confirms overwrites. Close
the window, launch xtc again and use File/Open (Ctrl+O), or run
`xtc /path/to/song.xtc`. The arrangement, stable IDs, routing, notes, mixing and
automation are restored; the transport starts stopped at zero. Continue drawing,
importing or moving clips, use Ctrl+Z/Ctrl+Shift+Z for undo/redo, and save again.
importing or moving clips, use Ctrl+Z/Ctrl+Shift+Z for undo/redo, and save
again.
New/Open/Quit ask before discarding unsaved edits. They are refused while
recording: use Stop to finalize the take, then save. Missing media stays silent
@ -70,7 +78,9 @@ selected audio. Failed file operations retain the document and show an error;
check the path, format and permissions. Server loss or rate changes require
Reconnect; this resets position, so seek again before resuming.
## Repeatable acceptance test
---
## Repeatable Acceptance Test
With installed FLTK/JACK development files, Xvfb and an already running
JACK-compatible server:
@ -80,14 +90,15 @@ make all test gui test-gui test-workflow test-gui-jack test-jack-midi
```
`test-workflow` drives real GUI commands and timeline gestures under Xvfb. It
creates a track, draws two notes, arranges the MIDI clip two beats later, imports
a generated WAV and verifies both automatic source routes. It saves and closes,
destroys the first window, reopens in a fresh window and compares the complete
stereo offline render exactly (including silence, imported audio and notes).
It checks stable clip IDs/positions and graph counts, seeks through the ruler,
plays on the real backend, observes nonzero stereo output meters and advancing
playhead, pauses/resumes, stops, returns to start, edits/undoes/redoes, saves and
reopens again. It uses temporary files only and cleans them on success.
creates a track, draws two notes, arranges the MIDI clip two beats later,
imports a generated WAV and verifies both automatic source routes. It saves and
closes, destroys the first window, reopens in a fresh window and compares the
complete stereo offline render exactly (including silence, imported audio and
notes). It checks stable clip IDs/positions and graph counts, seeks through the
ruler, plays on the real backend, observes nonzero stereo output meters and
advancing playhead, pauses/resumes, stops, returns to start,
edits/undoes/redoes, saves and reopens again. It uses temporary files only and
cleans them on success.
`test-gui` injects stop/seek/prepare failures to verify controls, position and
retained document state, plus recording guards. `test-gui-jack` exercises live
@ -98,34 +109,40 @@ JACK support. Core tests use no GUI leak suppression.
These checks cover a minimal composition workflow, not physical listening or
endurance qualification. No new dependency, project-format change, plugin host,
MIDI capture, tempo editor, loop playback, device-routing GUI, or persisted editor
layout was introduced. See GUI.md, MIDI.md, MIXER.md and LINUX.md for details.
MIDI capture, tempo editor, loop playback, device-routing GUI, or persisted
editor layout was introduced. See GUI.md, MIDI.md, MIXER.md and LINUX.md for
details.
## Editing workflow
---
Select a clip and press Ctrl+D (or Edit/Duplicate clip) to duplicate it immediately
after its end. Complete source notes, trim offsets and media references are
retained with fresh stable IDs. No audio file is copied or overwritten. F2 or
Edit/Rename clip or track names the selection. Clip labels show both kind and
user name. Alt+Up/Down with timeline focus reorders its selected track without
changing IDs, clip membership or routing. Right-click a timeline clip/track for
Duplicate, Rename and Delete. Invalid/capacity edits retain the existing model.
## Editing Workflow
View/Snap selects 1, 120, 240 (default), 480 or 960 ticks. It affects ruler seeks,
clip moves and trims; 1 tick is the finest grid. Existing +/- zoom and scrollbars
retain their behavior. Piano roll has its own configurable grid (see MIDI.md); mixer lanes retain their 240-tick
grid. Grid and zoom are application preferences saved on Apply/clean exit;
selection is session state. These controls are not undoable music edits.
Escape cancels a drag; Delete affects the focused editor; text fields keep their
own editing keys. Commands are named in menus/tooltips and timeline focus accepts
keyboard editing; screen-reader and broad accessibility qualification are pending.
Select a clip and press Ctrl+D (or Edit/Duplicate clip) to duplicate it
immediately after its end. Complete source notes, trim offsets and media
references are retained with fresh stable IDs. No audio file is copied or
overwritten. F2 or Edit/Rename clip or track names the selection. Clip labels
show both kind and user name. Alt+Up/Down with timeline focus reorders its
selected track without changing IDs, clip membership or routing. Right-click a
timeline clip/track for Duplicate, Rename and Delete. Invalid/capacity edits
retain the existing model.
View/Snap selects 1, 120, 240 (default), 480 or 960 ticks. It affects ruler
seeks, clip moves and trims; 1 tick is the finest grid. Existing +/- zoom and
scrollbars retain their behavior. Piano roll has its own configurable grid (see
MIDI.md); mixer lanes retain their 240-tick grid. Grid and zoom are application
preferences saved on Apply/clean exit; selection is session state. These
controls are not undoable music edits. Escape cancels a drag; Delete affects the
focused editor; text fields keep their own editing keys. Commands are named in
menus/tooltips and timeline focus accepts keyboard editing; screen-reader and
broad accessibility qualification are pending.
Create/delete/move/trim/duplicate, names/order, graph connects/deletes, notes,
mixer/automation and plugin edits use the 32-edit snapshot history. Ctrl+Z undoes;
Ctrl+Shift+Z or Ctrl+Y redoes. Backend preparation precedes accepting an undo/redo
snapshot; failure retains its cursor/document. Model edits stop playback before
mutation; compilation/file work occurs on the control thread and may pause the
GUI, never block the audio callback. This is not a background-loading editor.
mixer/automation and plugin edits use the 32-edit snapshot history. Ctrl+Z
undoes; Ctrl+Shift+Z or Ctrl+Y redoes. Backend preparation precedes accepting an
undo/redo snapshot; failure retains its cursor/document. Model edits stop
playback before mutation; compilation/file work occurs on the control thread and
may pause the GUI, never block the audio callback. This is not a
background-loading editor.
A successful recorded take adds a reference as one undoable edit. Undo/removing
its region never deletes the WAV; recording failures retain their recovery path.
@ -133,14 +150,16 @@ There is no destructive media-delete operation. New/Open reset history after
unsaved-change handling. The capacity limit and allocation-error reporting in
MIXER.md still apply. Tests: `make test-editing test-gui-plugins test-workflow`.
## Editing audit
---
## Editing Audit
See [EDITING.md](EDITING.md) for the operation-by-operation undo matrix, command
ownership, allocation-failure boundary, external-media behavior and manual
context-menu/focus procedure. History now reserves storage before edits and
publication, preserving redo when commands fail. Recording start has no empty
undo entry; a completed take is one step and undo never deletes its WAV.
Undo preserves surviving selections and an open piano roll; the piano window
also offers Edit/Undo/Redo. Graph context menus select under the pointer and
undo entry; a completed take is one step and undo never deletes its WAV. Undo
preserves surviving selections and an open piano roll; the piano window also
offers Edit/Undo/Redo. Graph context menus select under the pointer and
piano-roll right-click now opens a menu instead of immediately deleting a note.
Load/import/plugin work paints busy feedback while remaining synchronous.