xtc/docs/WORKSPACE.md

15 KiB
Raw Blame History

Flat DAW workspace

Phase 33 presents the existing xtc editors in a consistent flat workspace. 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.

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 delete commands remain available. F2 renames the selection. Drag clips to move them and their edges to trim them; click the ruler to seek while stopped.

Creating a track uses candidate preparation, so module, capacity or allocation failures retain the current project. As with other project replacements, the engine stops and the transport returns to the beginning. Track creation is unavailable while recording. No track type restriction is added to the model: ordinary tracks still accept the existing audio and MIDI workflows.

Track headers show a stable color, name, order and mute/solo state. Clip colors follow track identity through reordering. MIDI previews show real note starts, durations and relative pitches; waveforms continue to show loaded audio data. The selected clip has a light outline. A teal playhead and bar grid make musical 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.

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 listening. Work on a copy if the installed examples are read-only.

GUI tests exercise sidebar creation, selected clip/editor access, undo/redo, failed preparation, save/reopen and layout at 1220 × 720 and 1600 × 1000. The running example was also inspected at 1280 × 800. Existing GUI plugin, live JACK and workflow tests cover the retained commands. A modern presentation does not add commercial-DAW features: detachable/resizable docks, mixer channel strips, automatic plugin scanning, custom plugin editors and new audio/MIDI features remain outside this phase. Existing plugin and engine limits still apply.

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

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 slider at a value from 1 to 127. Only that note changes; pitch, timing, length, channel and other notes stay intact. One completed drag/slider edit is one undo step; Escape cancels a lane drag. For chord notes sharing a start time, select 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.

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.

Phase 36 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 horizontally for larger projects; the master output monitor stays visible. 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 for fader units, metering, automation and limits.

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

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.

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.

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

Detachable transport and mixer (Phase 39)

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.

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 numeric/text editing protection. Closing the main window closes all panels only after the existing unsaved/recording/backend shutdown checks succeed.

The initial Phase 39 layout used session-only positions and a transport minimum width of 1220 pixels. Phase 45 below adds saved layouts and transport wrapping down to 400 pixels. The floating mixer resizes down to 600 × 420 and retains horizontal track scrolling.

Verified with make BUILD_DIR=build/phase39 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.

Phase 45 saved panel layouts

Preferences / Apply now saves transport/mixer dock state and window rectangles. Preferences / Apply captures their current positions; Phase 100 also saves on clean application exit. Startup restores the saved layout; off-screen rectangles are clamped to an available display's work area. Invalid dimensions are rejected transactionally by the settings reader.

The floating transport supports widths down to 400 pixels. Controls wrap into rows below 1220 pixels, retaining playback, BPM, loop and navigation actions; its height grows as necessary to keep every control available. Docking restores the wide toolbar and arrangement geometry. Mixer minimum remains 600 × 420. 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.

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

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

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.

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.

Phases 47–57 add additive clip selection, atomic group commands, phrase clipboard and repeat, alignment/slip tools, MIDI swing/gate/legato/scale/velocity transforms, batch audio fades and static mixer A/B recall. See MODERN_EDITING.md for commands, scope and limitations.

Phases 58–68 add arrangement markers and sections, ripple edits, complete track duplication, MIDI splitting/consolidation and composition tools, peak normalization and portable media collection. See COMPOSITION_WORKFLOWS.md.

Phases 69–79 add a modal audio source editor with frame selection, reversible processing, selection export, copy adoption and transient slicing. See AUDIO_EDITOR.md for commands, undo behavior and mono/size limits.