armin/xtc
1
0
Fork 0
forked from hanez/xtc
Code Pull requests Activity

Phase 11: Complete and verify the minimal music-making workflow

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-27 03:25:04 +01:00
commit 461689dd44
12 changed files with 463 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

98
docs/WORKFLOW.md Normal file
View file

@ -0,0 +1,98 @@
# 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
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.
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.
3. Drag the clip body to arrange it; drag its edges to trim. Edits snap to
sixteenth notes. Add further tracks/clips as needed. Add region creates a
**silent placeholder**, rather than audio or MIDI.
4. Optionally use File/Import WAV (Ctrl+I). The file is placed at the current
cursor on the selected track; without a selected track an Audio track is
created. Keep the WAV available at its stored path.
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.
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 |
| --- | --- |
| Play / F5 | Prepare the current arrangement and resume at the retained sample position. Already playing is a no-op. |
| Pause / F7 | Deactivate playback and hold the sample position. Play resumes from there. Disabled during recording. |
| Stop / F8 | Hold the sample position, preserving the established Stop behavior. During recording, finalize and add the take. |
| Space | Toggle Play/Stop; while recording it finishes the take. |
| To start / Home | Stop and seek to sample zero; remain stopped until Play. Disabled during recording. Also resets an offline cursor. |
| 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. |
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
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
`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.
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
with a warning naming the first bad path; select its clip and use File/Relink
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
With installed FLTK/JACK development files, Xvfb and an already running
JACK-compatible server:
```sh
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.
`test-gui` injects stop/seek/prepare failures to verify controls, position and
retained document state, plus recording guards. `test-gui-jack` exercises live
graph changes, recording and restart/close; `test-jack-midi` checks software
loopback output. The Phase 11 tests also pass ASan/UBSan with the existing
fontconfig-only GUI leak suppression, and the GUI/mock suite builds/runs without
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.