xtc/docs/WORKFLOW.md

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	Fade out, then deactivate playback and hold the final block-end sample position. Play resumes from there. Disabled during recording.
Stop / F8	Fade out and hold the final block-end sample position. 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.

Pause/Stop completion is asynchronous: the GUI briefly shows “stopping”. Recording Stop and Home retain immediate deactivation. See 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.

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:

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.