165 lines
9 KiB
Markdown
165 lines
9 KiB
Markdown
# 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
|
|
cmake -S . -B build -DXTC_ENABLE_LIVE_TESTS=ON && cmake --build build --parallel && cmake --build build --target check 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: `cmake -S . -B build -DXTC_ENABLE_LIVE_TESTS=ON && cmake --build build --target 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.
|