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](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:

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