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

---

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

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

---

## 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
piano-roll right-click now opens a menu instead of immediately deleting a note.
Load/import/plugin work paints busy feedback while remaining synchronous.