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.

## Phase 17 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.

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/zoom/selection are session UI preferences, 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.

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