hanez/xtc
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs file normalization.

Browse source
This commit is contained in:
Johannes Findeisen 2026-11-06 15:20:20 +01:00
commit 619c2d0808
46 changed files with 3587 additions and 2579 deletions
Download patch file Download diff file Expand all files Collapse all files

228
docs/WORKSPACE.md
View file

@ -1,21 +1,24 @@
# Flat DAW workspace
# Flat DAW Workspace
The workspace presents the existing xtc editors in a consistent flat layout. It uses
FLTK vector drawing and system fonts: no images, shadows, bevels, 3D rendering,
external theme packages or new runtime dependencies.
The workspace presents the existing xtc editors in a consistent flat layout. It
uses FLTK vector drawing and system fonts: no images, shadows, bevels, 3D
rendering, external theme packages or new runtime dependencies.
The default window is 1280 × 800; the supported minimum is 1220 × 720. The main
editor grows with the window. Use the scrollbars for longer arrangements and
larger track counts. The sidebar stays available across Sequencer, Mixer and
Modular Graph views. Ctrl+1/2/3 switches those views; Ctrl+4 opens the piano roll.
Modular Graph views. Ctrl+1/2/3 switches those views; Ctrl+4 opens the piano
roll.
## Create and arrange
---
- **New MIDI track** (Ctrl+Shift+M) creates a named track and a one-bar MIDI clip
at the cursor. The new clip and mixer track are selected together. **Edit MIDI
notes** opens its piano roll. Creation is one undo step.
- **New audio track** (Ctrl+Shift+A) creates an empty named track. **Import WAV**
imports into the selected track, or creates one when none is selected.
## Create and Arrange
- **New MIDI track** (Ctrl+Shift+M) creates a named track and a one-bar MIDI
clip at the cursor. The new clip and mixer track are selected together. **Edit
MIDI notes** opens its piano roll. Creation is one undo step.
- **New audio track** (Ctrl+Shift+A) creates an empty named track. **Import
WAV** imports into the selected track, or creates one when none is selected.
- **Load instrument plugin** opens the instrument browser for the selected
sequencer track. Unassigned MIDI tracks retain the built-in sine instrument.
- Existing Add track/region/MIDI clip, duplication, trimming, split, rename and
@ -36,16 +39,18 @@ time visible. The transport display reads **bar : beat : tick** (4/4, 960 ticks
per beat); BPM follows the project tempo. These displays are read-only.
The sidebar inspector follows the sequencer selection, showing track name,
gain/pan, mute/solo and assigned instrument. Use the Mixer for controls, routing,
meters and automation; the sidebar is an overview, not another mixer. Status and
errors remain visible below the editor. Existing engine connection, transport,
recording and keyboard safety behavior is retained.
gain/pan, mute/solo and assigned instrument. Use the Mixer for controls,
routing, meters and automation; the sidebar is an overview, not another mixer.
Status and errors remain visible below the editor. Existing engine connection,
transport, recording and keyboard safety behavior is retained.
## Example and verification
---
## Example and Verification
Open `examples/projects/modern-session.xtc` for an original four-track, four-bar
MIDI arrangement with 16 clips and 128 notes. It needs no media or plugins. It is
also installed with the project examples. Connect JACK playback ports before
MIDI arrangement with 16 clips and 128 notes. It needs no media or plugins. It
is also installed with the project examples. Connect JACK playback ports before
listening. Work on a copy if the installed examples are read-only.
GUI tests exercise sidebar creation, selected clip/editor access, undo/redo,
@ -56,22 +61,24 @@ add commercial-DAW features: detachable/resizable docks, mixer channel strips,
automatic plugin scanning, custom plugin editors and new audio/MIDI features
remain outside this workspace. Existing plugin and engine limits still apply.
## Editing controls
---
The **Snap** dropdown above the sequencer selects Off, 1/32, 1/16 triplet,
1/16, 1/8 triplet, 1/8, 1/4, 1/2 or one bar. Existing View/Snap commands update
the same preference. Bar lines are strongest, beats medium, subdivisions subtle.
At low zoom closely spaced lines are coarsened to at least six pixels; snapping
## Editing Controls
The **Snap** dropdown above the sequencer selects Off, 1/32, 1/16 triplet, 1/16,
1/8 triplet, 1/8, 1/4, 1/2 or one bar. Existing View/Snap commands update the
same preference. Bar lines are strongest, beats medium, subdivisions subtle. At
low zoom closely spaced lines are coarsened to at least six pixels; snapping
still uses the selected division. Clip moves and trim boundaries snap to the
nearest absolute grid position (halfway rounds forward), including clips that
start off the grid. Off removes musical quantization; pointer resolution and
integer model ticks still apply. Invalid trims retain the original clip.
Snap is a UI preference, not a project edit or a saved project setting.
integer model ticks still apply. Invalid trims retain the original clip. Snap is
a UI preference, not a project edit or a saved project setting.
Double-click a MIDI clip with the left mouse button to open its piano roll.
The clip is selected and the click does not move/trim it. Audio/silent clips
retain their existing selection/drag behavior. The piano roll also has a Snap
dropdown for its existing note grid; sequencer and piano snap remain independent.
Double-click a MIDI clip with the left mouse button to open its piano roll. The
clip is selected and the click does not move/trim it. Audio/silent clips retain
their existing selection/drag behavior. The piano roll also has a Snap dropdown
for its existing note grid; sequencer and piano snap remain independent.
The piano roll has a fixed **Velocity** lane beneath the keys and a **Note
velocity** slider. Select a note, then drag its bar vertically or release the
@ -82,25 +89,29 @@ the desired note in the keys first; its highlighted velocity bar and slider
remain individually editable. Horizontal scrolling aligns the lane with note
starts; vertical scrolling moves the keys while the lane stays available.
Filters apply to lane visibility and selection. Values save with existing note
metadata and affect built-in synthesis; plugin patches determine velocity response.
This is MIDI velocity, not a per-note audio gain or loudness meter.
metadata and affect built-in synthesis; plugin patches determine velocity
response. This is MIDI velocity, not a per-note audio gain or loudness meter.
Every ordinary track header has an instrument dropdown. Choose **Built-in sine**,
an instrument already assigned elsewhere in the project, or **Load plugin...**
for a trusted CLAP/VST2/VST3 binary. Entries show the format and plugin label.
Each assignment creates an independent track instance, selects that track for
live MIDI and remains undoable; clear/reorder/reopen use stable track IDs. Bus
tracks show their bus label instead. Cancel or failed preparation restores the
model's selection in the dropdown. The list is project-local, not a scanner or
installed-plugin database. Existing mono/default-configuration host limits apply.
Instrument changes stop/reprepare playback and are refused while recording.
Every ordinary track header has an instrument dropdown. Choose **Built-in
sine**, an instrument already assigned elsewhere in the project, or **Load
plugin...** for a trusted CLAP/VST2/VST3 binary. Entries show the format and
plugin label. Each assignment creates an independent track instance, selects
that track for live MIDI and remains undoable; clear/reorder/reopen use stable
track IDs. Bus tracks show their bus label instead. Cancel or failed preparation
restores the model's selection in the dropdown. The list is project-local, not a
scanner or installed-plugin database. Existing mono/default-configuration host
limits apply. Instrument changes stop/reprepare playback and are refused while
recording.
Verification includes off-grid move/trim, snap Off, dropdown labels, double-click,
coincident notes, per-note slider/lane edits, invalid velocities, undo/reload and
instrument reuse/clear/reorder for all three fixture formats. Manual checks use
the original modern-session example and the flat sequencer/piano windows.
Verification includes off-grid move/trim, snap Off, dropdown labels,
double-click, coincident notes, per-note slider/lane edits, invalid velocities,
undo/reload and instrument reuse/clear/reorder for all three fixture formats.
Manual checks use the original modern-session example and the flat
sequencer/piano windows.
## Studio mixer
---
## Studio Mixer
The Mixer tab now presents all tracks and buses as channel strips with vertical
dB faders, flat pan knobs, mute/solo, output routing and stereo meters. Scroll
@ -109,63 +120,68 @@ Select a channel name to edit its gain/pan automation below the bank. Existing
undo, keyboard controls and project persistence remain available. See
[MIXER.md](MIXER.md) for fader units, metering, automation and limits.
---
## Direct editing and navigation
## Direct Editing and Navigation
**Commands** (Ctrl+P) searches active menu actions by case-insensitive substring.
Type part of an action path such as `mixer`, `import` or `preferences`, use
Up/Down to select, then Enter or **Run command**. Double-click also runs an
entry. Escape or Cancel leaves the project unchanged. The palette closes before
executing the existing menu callback; context and recording guards still apply.
**Commands** (Ctrl+P) searches active menu actions by case-insensitive
substring. Type part of an action path such as `mixer`, `import` or
`preferences`, use Up/Down to select, then Enter or **Run command**.
Double-click also runs an entry. Escape or Cancel leaves the project unchanged.
The palette closes before executing the existing menu callback; context and
recording guards still apply.
The transport **BPM** field edits project tempo from 20 to 300 BPM, stored in
milli-BPM. Enter or release commits one undoable change. It stops and rewinds
transport and prepares the project, including converting loop ticks to samples
at the new tempo. Failed validation/preparation retains the previous project;
the field returns to its actual value. Existing track/clip and piano-roll
selection survives. This is project tempo, separate from Preferences' new-project
default. Tempo automation is not added.
selection survives. This is project tempo, separate from Preferences'
new-project default. Tempo automation is not added.
The **Track inspector** now edits the selected track's linear Gain (0..4), Pan
(-1..1), Mute and Solo. In Mixer it follows the selected channel; in Sequencer
and Graph it follows arrangement selection. Controls synchronize with model
changes and undo, while typing is protected from the display refresh timer.
Only the edited field is committed. Unchanged values create no history entry.
These are static values; automation still overrides gain and pan. Recording
prevents edits. Track instruments and routing retain their existing selectors.
changes and undo, while typing is protected from the display refresh timer. Only
the edited field is committed. Unchanged values create no history entry. These
are static values; automation still overrides gain and pan. Recording prevents
edits. Track instruments and routing retain their existing selectors.
The session row shows track/bus count, clip count and the arrangement's bar span.
**Fit song** (Ctrl+0) returns to the start and selects the largest supported zoom
that fits the arrangement plus a beat of padding. Supported zoom remains
24, 48, 96, 192 or 384 pixels per beat; a sufficiently long arrangement requires
scrolling even at the minimum. Empty projects fit one bar.
The session row shows track/bus count, clip count and the arrangement's bar
span. **Fit song** (Ctrl+0) returns to the start and selects the largest
supported zoom that fits the arrangement plus a beat of padding. Supported zoom
remains 24, 48, 96, 192 or 384 pixels per beat; a sufficiently long arrangement
requires scrolling even at the minimum. Empty projects fit one bar.
**Follow playhead** pages the arrangement horizontally during playback, retaining
vertical scroll. It operates only in Sequencer and waits while a mouse drag is
active. It is off by default; Preferences / Apply persists it in
**Follow playhead** pages the arrangement horizontally during playback,
retaining vertical scroll. It operates only in Sequencer and waits while a mouse
drag is active. It is off by default; Preferences / Apply persists it in
`[transport] follow_playhead=0` or `1`. Manual scrolling remains available and
Fit song resets the viewport without editing the project.
Verification covers real FLTK palette filtering, empty searches and cancellation,
tempo callbacks/undo/failed adoption, inspector edits and in-progress numeric
input, fit and follow navigation, and existing core/GUI/live JACK workflows.
Verification covers real FLTK palette filtering, empty searches and
cancellation, tempo callbacks/undo/failed adoption, inspector edits and
in-progress numeric input, fit and follow navigation, and existing core/GUI/live
JACK workflows.
---
## Detachable transport and mixer
## Detachable Transport and Mixer
Use **View → Detach transport** or **View → Detach mixer** to move either panel
into a separate window. Toggle the same menu action, use the floating panel's
**Dock** button, or close its window to return it to the main workspace.
**View → Dock all panels** restores both. **View → Mixer** (Ctrl+2) also raises
the floating mixer. The main arrangement expands when the transport is detached.
The mixer remains the same live view, with its channel selection, faders, routing
and meters; the main Mixer tab offers Show and Dock actions while it is floating.
**Dock** button, or close its window to return it to the main workspace. **View
→ Dock all panels** restores both. **View → Mixer** (Ctrl+2) also raises the
floating mixer. The main arrangement expands when the transport is detached. The
mixer remains the same live view, with its channel selection, faders, routing
and meters; the main Mixer tab offers Show and Dock actions while it is
floating.
The transport owns the playback buttons, position, **BPM**, **Loop** toggle and
**Loop range...** settings in both layouts. Shift-drag on the sequencer ruler
still updates the same loop region. BPM remains an undoable project edit;
loop preferences persist through Preferences / Apply or clean application exit.
Space and menu playback shortcuts work from either floating panel, with normal
still updates the same loop region. BPM remains an undoable project edit; loop
preferences persist through Preferences / Apply or clean application exit. Space
and menu playback shortcuts work from either floating panel, with normal
numeric/text editing protection. Closing the main window closes all panels only
after the existing unsaved/recording/backend shutdown checks succeed.
@ -174,12 +190,15 @@ The initial layout used session-only positions and a transport minimum width of
described below. The floating mixer resizes down to 600 × 420 and retains
horizontal track scrolling.
Verified with `make BUILD_DIR=build/workspace-detach gui test-gui test-gui-instruments
test-gui-jack` (one line), plus the GUI suite under AddressSanitizer/UBSan.
Tests cover repeated reparenting, close-to-dock, resize, shared BPM/loop state,
playback shortcuts, failed shutdown and cleanup.
Verified with
`make BUILD_DIR=build/workspace-detach gui test-gui test-gui-instruments test-gui-jack`
(one line), plus the GUI suite under AddressSanitizer/UBSan. Tests cover
repeated reparenting, close-to-dock, resize, shared BPM/loop state, playback
shortcuts, failed shutdown and cleanup.
## Saved panel layouts
---
## Saved Panel Layouts
Preferences / Apply now saves transport/mixer dock state and window rectangles.
Clean application exit also saves their current positions. Startup restores the
@ -194,41 +213,46 @@ Existing close-to-dock, Dock all and shortcuts retain their shared widget state.
Tests cover narrow control bounds, save/restart, off-screen restoration, invalid
geometry, repeated docking/resizing and shared transport state.
## Editor panels and pinned track headers
---
## Editor Panels and Pinned Track Headers
**View → Detach sequencer** and **Detach modular graph** float each complete
editor, including its toolbar and scroll area. Its main tab offers Show and Dock
buttons. Closing the floating window docks it; View shortcuts also raise floating
editors. Supported dock locations are their original main-window tabs; arbitrary
split regions, tab reordering and drag-to-dock are not implemented. Sequencer
minimum floating size is 1100 × 420; Graph is 1000 × 420.
buttons. Closing the floating window docks it; View shortcuts also raise
floating editors. Supported dock locations are their original main-window tabs;
arbitrary split regions, tab reordering and drag-to-dock are not implemented.
Sequencer minimum floating size is 1100 × 420; Graph is 1000 × 420.
The Piano roll now also has a main-window tab. Select a MIDI clip and open it as
before. **View → Float piano roll** switches its existing widgets between the tab
and a floating window; closing the floating window docks it. The tab's Open
before. **View → Float piano roll** switches its existing widgets between the
tab and a floating window; closing the floating window docks it. The tab's Open
selected MIDI clip button opens the current selection. Default floating behavior
is retained for older preferences. A missing/invalid MIDI selection is reported.
All panels share project/history, preserve editor selections and scroll offsets,
and retain playback shortcuts and text-input protection.
**View → Dock all panels** includes all editors. **Reset workspace layout** docks
all panels, restores default floating rectangles and resets header width. Use
Preferences / Apply to persist either result. Editor dock state, floating window
rectangles and header width use the same validated settings/restore path as the
transport/mixer. Piano content opens lazily for the selected MIDI clip; startup
does not invent a clip or save a project-specific selection in application settings.
**View → Dock all panels** includes all editors. **Reset workspace layout**
docks all panels, restores default floating rectangles and resets header width.
Use Preferences / Apply to persist either result. Editor dock state, floating
window rectangles and header width use the same validated settings/restore path
as the transport/mixer. Piano content opens lazily for the selected MIDI clip;
startup does not invent a clip or save a project-specific selection in
application settings.
Arrangement track headers and instrument selectors now stay pinned during
horizontal scrolling. Drag the divider within the header's final five pixels to
resize from 180 to 360 pixels; Escape cancels the drag. Clip timing coordinates,
snap and horizontal scrolling use the resized origin. Header layout is a UI
preference, not an undoable project edit. Vertical scrolling remains shared with
the track rows. Clips covered by the pinned header cannot be selected through it.
the track rows. Clips covered by the pinned header cannot be selected through
it.
GUI regressions cover repeated detach/dock and close-to-dock, toolbar ownership,
minimum/large resize, shared model/note/clip selection, scrolling, header dragging,
short-clip hit tests, Apply/restart, reset layout and failed/successful shutdown.
ASan/UBSan checks retain only the existing system Fontconfig leak suppression.
minimum/large resize, shared model/note/clip selection, scrolling, header
dragging, short-clip hit tests, Apply/restart, reset layout and
failed/successful shutdown. ASan/UBSan checks retain only the existing system
Fontconfig leak suppression.
Additive clip selection, atomic group commands, phrase clipboard and repeat,
alignment/slip tools, MIDI swing/gate/legato/scale/velocity transforms, batch
@ -237,8 +261,10 @@ audio fades and static mixer A/B recall are also available. See
Arrangement markers and sections, ripple edits, complete track duplication, MIDI
splitting/consolidation and composition tools, peak normalization and portable
media collection are also available. See [COMPOSITION_WORKFLOWS.md](COMPOSITION_WORKFLOWS.md).
media collection are also available. See
[COMPOSITION_WORKFLOWS.md](COMPOSITION_WORKFLOWS.md).
A modal audio source editor provides frame selection, reversible processing,
selection export, copy adoption and transient slicing. See
[AUDIO_EDITOR.md](AUDIO_EDITOR.md) for commands, undo behavior and mono/size limits.
[AUDIO_EDITOR.md](AUDIO_EDITOR.md) for commands, undo behavior and mono/size
limits.