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