hanez/xtc

hanez d676d74a11 feat: normalize selected audio clips to a bounded sample peak

2026-11-06 00:46:14 +01:00

91 KiB

Raw Blame History

Roadmap

Phase 0 — Baseline

Inspect repository/toolchain, verify Makefile and minimal executable, document dependencies. No system changes without permission.

Baseline implementation: headless startup/shutdown executable, core tests, separate debug build, optional FLTK shell build, and header dependencies. See BUILD.md for toolchain, commands, licensing and limitations.

Phase 1 — C core and offline processing

Graph data structures, validation, cycle detection, topological ordering, preallocated buffers, test oscillator, gain and offline render tests.

Implemented: mono ports, transactional cycle rejection, independent compiled plans, precomputed input routing, oscillator/gain/meter/output, deterministic variable-block tests and lifecycle/error coverage. See AUDIO_ENGINE.md for API limits and compatibility behavior.

Phase 2 — Real-time backend

Choose and implement a Linux backend. Document callback semantics, start/stop, device errors, shutdown, and safe graph publication.

Implemented: optional JACK-compatible mono backend, explicit audio port routing, format/xrun/loss status, start/stop/reopen, and bounded pending/retired plan handoff using lock-free atomics. Hardware-independent failure/concurrency tests and a 30-second software-loopback run pass. See decision 0004 and AUDIO_ENGINE.md. Physical hardware playback/endurance and live server-loss recovery remain unverified; GUI engine controls are implemented in Phase 3.

Phase 3 — FLTK shell

Main window, transport controls, view switching, backend status, clean startup and shutdown through the C API.

Implemented: dark FLTK shell, Play/Stop/Reconnect, view/menu shortcuts, backend state/format/xrun/process status, persistent command errors, timer-based refresh and retirement collection, and callback-safe close/retry. Mock-backend GUI tests and live GUI/JACK start/stop/reconnect/close tests pass under Xvfb. Sequencer, mixer and project-file actions remain placeholders; initial graph is silent. See GUI.md.

Phase 4 — Modular editor

Draw nodes/ports/edges; create, move and connect nodes; reject invalid edges; safely submit edits to the C core.

Implemented: scrollable node/port/wire canvas; add/select/move/delete nodes; drag connections, select/delete wires, and show invalid-edit feedback. C owns stable IDs, read-only snapshots and transactional edits. Exact accepted graph snapshots are submitted to the backend; prepared/queued/active state is exposed through revision acknowledgements. Core/render, GUI rollback, mouse smoke and live adoption tests pass. See GUI.md and AUDIO_ENGINE.md. Preset parameters, mono-only processing, fixed canvas and no persistence/undo/zoom remain limits.

Phase 5 — Project and sequencer

Versioned persistence, stable IDs, tracks, clips, timeline, selection, zoom, scrolling, and transport synchronization.

Implemented: bounded version-1 project persistence with transactional loads and temporary-file/fsync/rename saves; stable track/clip/node IDs; silent regions; track and region creation/deletion, selection, move/trim, timeline zoom/scroll; sample-counted playhead, pause/resume and stopped seek. Project/graph arrangement roundtrips, malformed-input, GUI rollback/gesture and live transport tests pass. See PROJECT_FORMAT.md and GUI.md. Constant tempo/4/4, silent metadata regions, no undo, asset playback, MIDI or persisted GUI layout are explicit limits.

Phase 6 — Audio clips and recording

Audio import/playback, recording through bounded buffers, missing-asset handling, no file I/O in callbacks.

Implemented: bounded PCM16/24/32 and float32 WAV import (mono/stereo downmix), preloaded overlap-summed clip plans with linear rate conversion, and an audio source node using ordinary graph routing. A lock-free SPSC ring transfers JACK input to a control-thread WAV writer; Stop finalizes and adds successful takes. Version 2 metadata stores external asset references and reads v1. Missing assets remain silent with reporting and manual relinking. Core, callback, GUI and live software record/save/reopen/play acceptance tests pass. See AUDIO_FILES.md for memory/format limits, overflow recovery and deferred physical-device validation. No new dependency or callback I/O was introduced.

Phase 7 — MIDI and instrument

MIDI input/events/clips, simple internal instrument, note-off/panic handling, then a basic piano roll.

Implemented: bounded source-relative note events with stable IDs; sample-offset JACK MIDI input; a velocity-scaled sine instrument and separate graph source; panic, note-off, stop and seek handling; and a piano roll for drawing, moving, resizing and deleting notes. Version 3 saves notes and reads v1/v2 projects. Core, fault-injection, GUI and live software MIDI/save/reopen/play tests pass. Acceptance uses drawn notes; MIDI recording and SMF import are deferred. See MIDI.md for capacities, immediate note-off, routing and hardware limits.

Phase 8 — Mixer and editing

Gain/pan, meters, mute/solo, automation, undo/redo, keyboard workflow.

Implemented: selectable per-track channel strips with gain/pan and mute/solo; stereo graph/JACK output and output peak meters; editable gain/pan automation lanes with sample interpolation; bounded 32-edit C snapshot undo/redo and mixer keyboard controls. Format v4 persists mixing/automation and reads v1–v3. Core, GUI rollback/gesture/history and live stereo software playback tests pass. See MIXER.md for routing, mono compatibility, pan law, history behavior and limits. Track inserts/sends, live fader adoption, MIDI capture, per-track meters and advanced automation remain deferred. No project-file editing is needed for the implemented composition/mixing workflow.

Phase 9 — Extensibility and release

Native node API, evaluate plugin hosting, licensing review, packaging, installation tests, performance and recovery tests.

Implemented: versioned native C processor lifecycle and graph source/effect API, explicit instrument-buffer integration, example and error/retirement tests; external-hosting evaluation (deferred); dependency/license review; deterministic source/release targets; core/GUI staged install/uninstall and installed C/C++ consumer tests; headless version/help/metadata validation; offline performance and process-crash/write-failure recovery tests. Source format stays v4, reading v1–v3. See NATIVE_API.md, RELEASING.md, LINUX.md, LICENSES.md, PERFORMANCE.md and RECOVERY.md. Native graphs remain session-only, with unsupported saves preserving files. No stable binary plugin ABI, external host, system package, autosave or physical-device/endurance qualification is claimed.

Phase 10 — Engine Correctness and Reliability

Goal: Verify that the existing implementation behaves correctly under realistic workloads before adding more features.

Tasks

Audit graph compilation, topological ordering, port compatibility, and cycle detection.
Test graph replacement while audio is running, including safe reclamation of old processing graphs.
Verify that audio-thread operations are bounded and non-blocking.
Test repeated initialization, start/stop cycles, device failures, shutdown, and partial initialization.
Run AddressSanitizer, UndefinedBehaviorSanitizer, leak checks, and static analysis where available.
Add regression tests for every bug discovered.
Document known limitations and thread ownership for shared resources.

Acceptance criteria

Reproducible tests cover engine lifecycle, graph changes, error handling, and DSP output.
No known critical real-time safety defects remain.
Resource ownership and cleanup behavior are documented.

Implemented: graph/DSP and ownership audit; stereo source-alias correction with exact-output regression tests; maximum-size reverse-order graph/cycle rollback; allocation-failure sweeps and callback allocation/free guards; 2000 concurrent native-plan replacements with control-thread destruction and balanced lifetimes; repeatable ASan/UBSan/leak and Clang static-analysis targets. Core, no-JACK, GUI/mock/live JACK, recovery and TSan publication/recorder tests pass. See RELIABILITY.md for ownership, synchronization, bounded-work analysis, commands and evidence. Physical-device/endurance validation and trusted native callback behavior remain explicit limits; no critical realtime safety defect is known within the documented contracts.

Phase 11 — Complete Minimal Music-Making Workflow

Goal: Ensure a user can create, save, reopen, and play a small musical project without manually editing project files.

Tasks

Verify project creation, track creation, clip arrangement, routing, and transport as one integrated workflow.
Ensure play, pause, stop, seek, and return-to-start behavior are consistent.
Save, close, reopen, and continue editing projects.
Provide useful defaults and actionable error messages.
Keep the sequencer as the default workspace, with the modular graph available when needed.
Test that GUI state and engine state remain synchronized.

Acceptance criteria

A user can create and reopen a small project and reproduce the same arrangement and routing.
Common operations do not require manual project-file edits.
Transport and GUI state remain consistent during normal playback and error conditions.

Implemented: explicit Pause/F7 and To start/Home controls, position-preserving Stop compatibility, recording guards, sequencer selection on New/Open, first-use composition/routing guidance, and GUI status refresh after failed installation. A real GUI/backend workflow test creates MIDI and audio, arranges/routes, saves, closes/destroys the window, reopens in a fresh window, compares exact stereo rendering and stable clip/routing metadata, then plays/seeks/pauses/resumes, continues editing with undo/redo and saves/reopens again. Mock failure tests and live JACK/GUI/software MIDI tests pass. See WORKFLOW.md for instructions, transport semantics, test commands and limits. External playback routing remains explicit; physical-device listening and endurance remain unqualified.

Phase 12 — Audio Quality and Transport Correctness

Goal: Make timing and audio output predictable and musically reliable.

Tasks

Define precise behavior for tempo and meter changes.
Verify conversion between musical positions and sample positions without accumulated timing drift.
Test clips and events that cross processing-block boundaries.
Prevent clicks at clip boundaries and during playback start/stop where appropriate.
Implement gain ramps and parameter smoothing where abrupt changes could create artifacts.
Test silence, clipping, denormal values, channel layouts, and unusual supported buffer sizes.
Document latency reporting and identify whether latency compensation is required by the current architecture.
Add deterministic tests for sample-accurate event scheduling where supported.

Acceptance criteria

Automated tests verify timing conversions and expected sample output.
Tests cover events and clips at block boundaries and tempo changes.
Listening tests cover transitions, start/stop behavior, and representative projects.
Known limitations involving latency and synchronization are documented.

Implemented: documented constant-tempo/fixed-4/4 snapshot policy; absolute timing and sample-offset regression matrix; configurable audio/scheduled-note boundary fades; single-owner gain ramps; GUI 5 ms start and asynchronous Pause/Stop fades with control-thread acknowledgement/deactivation; finite/subnormal output policy; exact endpoint, block-size, stereo, overload and failure/retry tests. Latency and synchronization limits are documented in AUDIO_QUALITY.md. Normal/no-JACK, sanitizer/static-analysis, TSan, GUI/workflow/live JACK and install checks pass. make quality-preview generates matched listening WAVs. Human listening and physical-device acceptance remain pending; immediate safety/recording/seek paths and live graph swaps may still click. No tempo/meter map, latency compensation, limiter or project-format change is claimed.

Phase 13 — Recording and Recovery

Goal: Protect recorded material and handle recording failures predictably.

Tasks

Test long recordings and recording-buffer saturation.
Handle disk-full conditions, write errors, interrupted recording, and unavailable destinations.
Keep file I/O outside the real-time audio callback.
Define and implement recovery or clear reporting for incomplete recordings.
Make recording destinations and supported file formats explicit.
Protect existing files from accidental overwrites.
Test reopening projects when media files are missing, incomplete, or inaccessible.
Ensure shutdown and project closure do not silently discard pending recorded data.

Acceptance criteria

Recording failures are reported clearly and do not cause unsafe audio-thread behavior.
Valid recorded material is preserved whenever possible.
Incomplete recordings and missing media are detected and explained.
Recording and recovery behavior is covered by automated or repeatable integration tests.

Implemented: no-clobber recording destinations and race-safe publication; explicit opt-in replacement API; retained failed temporaries and recovery-path reporting; streaming xtc-check --recover-recording TEMP NEW.wav salvage; quiescent destructor draining and exceptional-shutdown reporting. Virtual 30-minute recording, saturation/concurrency, destination races, disk-write failure/prefix recovery, killed writers and missing/incomplete media tests pass. See AUDIO_FILES.md and RECOVERY.md. Physical endurance, power-loss guarantees and playback of assets above the existing preload limit remain unqualified.

Phase 14 — Native Plugin, Instrument, and Effect Architecture

Goal: Provide a stable internal extension interface before hosting external plugins.

Tasks

Finalize the native C node API, including initialization, processing, reset, and destruction.
Define parameter metadata, defaults, valid ranges, and automation behavior.
Specify audio channel layouts and MIDI/event handling.
Define node state serialization and restoration requirements.
Establish rules for node creation, failure, reconfiguration, and destruction.
Ensure the GUI uses documented public APIs rather than internal engine structures.
Provide a small example instrument and effect implemented against the public interface.
Document ABI/API compatibility expectations for native extensions.

Acceptance criteria

A developer can implement a small native instrument or effect using documented interfaces.
Invalid parameters, unsupported layouts, and failed initialization are handled safely.
Node state can be saved and restored where required.
No C++ or FLTK types leak into the public C API.

Implemented: ABI 2 parameter-only C processor lifecycle with copied descriptors, metadata/default/range validation, sample-offset parameter/MIDI ordering, transactional portable configuration restoration, and public gain/instrument examples. Lifecycle, invalid input, event ordering, in-place output, reset, callback failure and state compatibility tests pass. See NATIVE_API.md. ABI 1 graph compatibility is retained; native graph persistence and opaque plugin state are explicitly outside this parameter-only interface.

Phase 15 — External Plugin Hosting

Goal: Add external plugin support only after the internal node lifecycle is reliable.

Tasks

Evaluate candidate plugin formats for licensing, dependencies, maintenance, and Linux support.
Record the selected format and rationale in an architecture decision document.
Implement plugin discovery and loading outside the real-time callback.
Map plugin audio ports, parameters, MIDI/events, and channel layouts to the engine's node model.
Support plugin state save/load and clear reporting for missing or incompatible plugins.
Test plugins with different channel counts, parameter sets, and processing requirements.
Define how plugin failures are reported and how the engine recovers.
Document crash-isolation limitations; an in-process plugin must not be assumed safe merely because the host is safe.

Acceptance criteria

A small, documented set of compatible third-party plugins can be loaded, connected, saved, reopened, and played.
Missing or incompatible plugins do not silently corrupt the project.
Plugin loading and destruction do not occur in the real-time callback.
The chosen format's dependencies and licensing are documented.

Implemented: bounded LADSPA 1.1 C host with explicit file/index discovery, control-thread loading/lifecycle, mono source/effect graph mapping, independent stereo instances, metadata/range checks and v5 identity/control persistence. Public-API GUI load/configure commands support ordinary routing/save/reopen and undo. Fixture/error/retirement/GUI tests and installed amp/inverter/sine acceptance pass. See decision 0009, PLUGIN_HOSTING.md and LICENSES.md. MIDI, true multichannel layouts, opaque state, editors, latency compensation and crash isolation are unsupported; plugin realtime behavior and physical listening are unqualified.

Phase 16 — Automation and Expressive Control

Goal: Make automation and MIDI control reliable, sample-timed, and usable.

Tasks

Support automation for common parameters such as volume, pan, instrument parameters, and effect parameters.
Define interpolation modes and behavior at clip boundaries.
Evaluate automation at the correct time and sample offsets for each processing block.
Smooth parameter changes where needed to avoid zipper noise or audio artifacts.
Add MIDI controller mapping where appropriate.
Handle note-off, panic, seek, stop, project teardown, and device disconnect correctly.
Define deterministic ordering for MIDI and automation events that occur at the same sample position.
Test overlapping notes, repeated note-ons, and interrupted playback.

Acceptance criteria

Automation and MIDI control reproduce consistent results across repeated playback and project reloads.
Held notes are released safely on stop, panic, seek, and relevant failure paths.
Event ordering and interpolation behavior are documented and tested.

Implemented: persisted sample-evaluated LADSPA parameter lanes with linear/step modes, range/discrete validation and public GUI editing; absolute automation position through seek and plan handoff; fixed live CC7/10/64 mappings with volume/ pan ramps, sustain/retrigger safety, and exact block-partition regressions. Existing track Gain/Pan lanes cover audio and scheduled instrument volume. Format v6 migrates v1–v5. See CONTROL.md. MIDI capture/learn, pitch bend, new instrument timbres and physical listening remain outside the supported scope.

Phase 17 — Editing Workflow, Undo/Redo, and Usability

Goal: Make common editing tasks efficient and protect users from accidental changes.

Tasks

Make common operations undoable, including create, delete, move, trim, duplicate, and connect.
Define undo behavior for recording and destructive operations.
Add consistent keyboard shortcuts and context menus for frequently used actions.
Implement predictable snapping, grid settings, zoom, scrolling, and selection behavior.
Improve clip labels, track organization, and visual feedback.
Make destructive actions difficult to trigger accidentally.
Keep the GUI responsive while audio is running.
Ensure undo/redo updates project state and the active engine graph consistently.
Test keyboard focus and accessibility of essential controls where practical.

Acceptance criteria

Common editing workflows can be completed without unnecessary dialogs or manual workarounds.
Undo/redo restores the intended project state and corresponding engine state.
GUI operations do not block the real-time audio thread.
Interaction behavior is documented and covered by relevant tests.

Implemented: transactional full-source clip duplication, clip/track names, track ordering, configurable timeline snap, Ctrl+D/F2/Alt+arrow commands and a context menu; kind/name clip labels and focus regressions. Snapshot/GUI tests verify duplicate/rename/order undo/redo, source-note retention, capacity rollback and existing graph/backend history behavior. Recording undo removes references, never media. See WORKFLOW.md. Background loading, persisted UI layout and broad screen-reader/accessibility qualification remain explicit limits.

Phase 18 — Project Format, Compatibility, and Portability

Goal: Keep project files valid, recoverable, and maintainable over time.

Tasks

Version the project format and implement explicit migration logic when the format changes.
Validate project data before constructing engine objects from it.
Handle malformed files, unknown node types, missing assets, and unavailable plugins.
Define project-folder behavior and reliable media path handling.
Make saving robust against interrupted writes, for example by writing a temporary file and replacing the destination safely where supported.
Test save/load round trips and migration from every format version that is supported.
Keep the format documented and preferably human-inspectable.
Avoid silently discarding unknown data during load/save unless the format policy explicitly requires it.

Acceptance criteria

Supported older projects load correctly or produce clear, actionable compatibility errors.
Malformed project files do not crash the application or trigger unsafe allocations.
Missing media and plugins are reported clearly.
Save/load round trips and format migrations have automated tests.

Implemented: v7 folder-relative media persistence with absolute runtime references, transactional resolution independent of launch cwd, Save As identity preservation, and parent-directory fsync after atomic publication. Checked-in v1–v6 migrations (including missing plugins), moved-folder exact playback, missing-media retention, truncation/mutation and unknown-record/error tests pass. See PROJECT_FORMAT.md. No media is copied/deleted automatically; absolute external/plugin dependencies, path bounds, post-rename sync errors and physical power-loss limits are explicit.

Phase 19 — Performance, Scalability, and Stress Testing

Goal: Measure performance and establish predictable behavior as projects grow.

Tasks

Create repeatable benchmarks for increasing node counts and audio channel counts.
Measure processing time at supported sample rates and block sizes.
Profile graph compilation separately from real-time audio processing.
Identify unnecessary buffer copies, allocations, and redundant processing.
Test large arrangements, many clips, automation events, and active meters.
Define bounded processing limits and meaningful overload diagnostics.
Test under CPU pressure and during frequent GUI redraws.
Optimize only after profiling identifies a meaningful bottleneck.
Record baseline benchmark results so regressions can be detected.

Acceptance criteria

Performance targets and test conditions are documented.
Repeatable benchmarks cover representative small and large projects.
Overload behavior is defined and does not cause unbounded work in the callback.
Significant performance regressions can be detected through repeatable tests.

Implemented: 24-case node/channel/rate/block matrix with separate compilation and warmed process timings, recorded machine/compiler baseline and opt-in regression budgets; maximum track/clip/note/automation/meter capacity checks and publication/GUI tests under CPU contention. Measurements justified skipping unused live-controller processing; exact output tests remain passing. See PERFORMANCE.md and performance-baseline.json for results, thresholds and overload policy. Arbitrary plugin costs and physical realtime/endurance are unqualified.

Phase 20 — Release Engineering, Packaging, and Maintenance

Goal: Make the application straightforward to build, install, use, diagnose, and maintain.

Tasks

Provide reproducible release builds and clean build instructions.
Add Makefile targets for building, testing, installing, and uninstalling.
Package the application and required resources for the initial supported Linux target.
Review licenses and attribution for direct and bundled dependencies.
Document supported audio backends, required system packages, and configuration.
Add useful crash and error diagnostics without compromising real-time processing.
Test fresh installations, upgrades, missing dependencies, and removal.
Publish a basic user manual, developer documentation, and a known-limitations list.
Define a release checklist and a policy for handling regressions and project-format compatibility.

Acceptance criteria

A person other than the primary developer can build or install the application using the documented steps.
The installed application can complete the supported core workflow.
Installation and removal are tested on the initial target environment.
Dependencies, licensing, limitations, and troubleshooting steps are documented.
A release can be reproduced from a clean checkout with recorded build instructions.

Implemented: normalized Linux binary/development archives with SHA-256/file/ ELF-dependency manifests, headless compiled-feature diagnostics, repeat-install upgrade/repair and installed C/C++ save/reopen/render checks. Existing deterministic source/release, no-dependency, sanitizer, staged uninstall and GUI/live tests are retained. USER_MANUAL.md, KNOWN_LIMITATIONS.md and MAINTENANCE.md consolidate setup, operation, licensing/diagnostics, release and regression policy. No public release or distro registration is performed. Independent human installation/usability, physical-device/endurance and listening acceptance remain pending and must be completed before claiming production qualification.

Phase 21 — Advanced MIDI and Composition

Goal

Make MIDI composition expressive and efficient without turning the application into an unnecessarily complicated notation editor.

Tasks

Improve piano-roll editing for note creation, selection, movement, resizing, and deletion.
Support configurable snap and grid resolution, including triplets where practical.
Add velocity editing and editing for supported MIDI note properties.
Support MIDI channel and note-range filtering where appropriate.
Improve quantization, transposition, duplication, and pattern repetition.
Ensure MIDI event ordering is deterministic, especially when note-off and note-on events share a timestamp.
Define handling for overlapping notes, repeated notes, and malformed MIDI events.
Add regression tests for MIDI editing and playback scheduling.

Acceptance criteria

Common MIDI editing tasks can be completed without manually editing project files.
Editing preserves unrelated notes and event properties.
MIDI scheduling remains deterministic at buffer boundaries and under transport changes.
MIDI operations are covered by automated tests.

Implemented: transactional C filtered note transforms, nearest-grid quantization, velocity/channel edits, transposition, bounded fresh-ID repetition and deletion; piano-roll Notes menu, keyboard commands, configurable straight/triplet grids, channel/pitch filtering and filtered-set selection. Existing mouse move/resize and project undo/redo remain supported. Core and GUI regression tests demonstrate property/other-clip preservation, rollback, undo/redo, adjacent/overlapping notes, equal-offset caller ordering, exact block partitions and seek chase. See MIDI.md. No format change, MIDI capture, SMF import, lasso selection or piano-roll zoom; physical-device and listening validation remain pending.

Acceptance evidence:

Menu/keyboard/mouse commands edit notes without project-file editing.
Filtered batch tests preserve unmatched notes and unrelated properties.
Exact scheduling tests cover buffer boundaries and transport seeks.
Core composition and GUI undo/redo regressions exercise these operations.

Phase 22 — Audio Clip Editing and Utility Operations

Goal

Provide focused, non-destructive audio editing tools for arranging and preparing recorded or imported material.

Tasks

Support moving, trimming, splitting, duplicating, and deleting audio clips.
Define clip-boundary behavior, including fades and source offsets.
Add non-destructive clip gain and basic fade-in/fade-out controls.
Support time-stretching and pitch-shifting only after selecting a suitable implementation and quality target; otherwise document them as future work.
Ensure edits do not unexpectedly modify source audio files.
Add waveform display caching that never blocks the audio thread.
Test edits at project boundaries, source-file boundaries, and very short clip lengths.
Document which operations are destructive and non-destructive.

Acceptance criteria

Basic clip editing is predictable and undoable.
Source files remain unchanged unless a documented destructive operation is explicitly invoked.
Clip boundaries do not produce unintended clicks from invalid offsets or discontinuities.
Editing and waveform generation never perform blocking work in the real-time audio callback.

Implemented: transactional audio/silent-clip splitting with stable IDs and source offsets; persisted linear clip gain and explicit in/out fades in v8 (v1–v7 migrate to unity/no explicit fades); undoable sequencer menu/context/keyboard controls; immutable bounded source-peak summaries shared across clips and drawn from cached memory. Existing move/trim/duplicate/delete remain supported; very short clip hit testing now matches drawing. See AUDIO_FILES.md and PROJECT_FORMAT.md. Stretch/pitch processing and crossfades remain future work; waveform loading is synchronous on the control thread, and physical listening remains pending.

Acceptance evidence:

Core/GUI regressions cover split/duplicate/delete and snapshot undo.
Exact byte comparison verifies source files survive all metadata edits.
Boundary tests cover invalid offsets, short tails, one-frame media, explicit fade endpoints, gain, block partitions, seeks and capacity rollback.
Waveform construction stays on control-thread paths; redraw reads cached peaks and audio rendering retains immutable/preloaded callback storage.

Phase 23 — Modular Workflow and Routing Refinement

Goal

Preserve the modular spirit of the application while making complex projects understandable and manageable.

Tasks

Refine graph and routing views so signal paths are easy to inspect.
Make connections, disconnections, and invalid routing states clear.
Provide useful names and visual distinctions for tracks, instruments, effects, buses, and I/O ports.
Support track grouping or folders if the project model can represent them cleanly.
Add routing presets or reusable track templates only if they do not complicate the core model.
Define behavior for cycles and feedback paths; reject unsupported cycles explicitly.
Make graph changes transactional so failed edits do not leave partially updated routing.
Add tests for graph changes while playback is running.

Acceptance criteria

Users can inspect and understand a project's signal path.
Invalid graph edits fail safely and leave the previous valid graph intact.
Graph updates follow the documented real-time synchronization strategy.
GUI routing concepts map cleanly to the public C engine API.

Implemented: cached public C routing analysis (edge counts, longest-path levels, output reachability and external-input fallback); directional/highlighted wires, role colors/labels, no-output badges, selection inspection and keyboard navigation; scrollable signal-flow auto-layout and non-overlapping initial placement. Atomic unity-gain wire insertion is one undoable C edit using existing node persistence. Core and mock/live GUI tests cover rollback, complete plan adoption, cycles, disconnect/restore and undo/redo. See ROUTING.md. Flat tracks/shared audio/MIDI sources do not yet represent folders or per-track routing templates; these conditional tasks are deferred. No format change, feedback processing, latency compensation or physical listening qualification is claimed.

Acceptance evidence:

Direction/role labels, layout and public routing diagnostics expose paths.
Invalid/capacity/backend-failed commands retain the previous graph/plan.
Live JACK graph tests verify complete block-boundary plan adoption.
GUI routing analysis and edits use public C APIs; callback ownership is unchanged.

Phase 24 — Mixing and Mastering Essentials

Goal

Provide the essential mixing controls needed to finish a small or medium-sized project.

Tasks

Complete track and bus gain, pan, mute, solo, and metering behavior.
Define how solo states affect buses, sends, and sidechains.
Add peak meters with clear units and documented ballistics.
Add master-bus monitoring and clipping indicators.
Support routing to buses and auxiliary sends if the graph model supports them.
Make gain staging explicit and avoid hidden or surprising level changes.
Document meter tap points and whether values are pre-fader, post-fader, or post-effects.
Test mute, solo, pan, gain, and routing interactions.

Acceptance criteria

Mixer controls behave consistently across tracks, buses, and master output.
Meter readings correspond to documented signal points and units.
Solo and mute behavior is covered by automated tests.
No mixer operation introduces allocations, locks, or other prohibited work in the audio callback.

Implemented: one-level stereo mix buses with routing, shared gain/pan automation, inclusive solo and mute precedence; coherent audio/MIDI track and bus peaks; interval master peaks, dBFS ballistics and sticky clipping; v9 persistence reading v1–v8. See MIXER.md for exact taps, gain staging and callback scratch bounds. Independent per-track aux sends/sidechains and per-bus graph effects remain conditional/deferred because graph sources still expose shared mixes.

Validation: warning-enabled core/GUI builds and unit/integration tests, bus and backend fault tests, GUI plugin/workflow tests, software JACK GUI/audio/MIDI, allocation-failure/callback-allocation guard, static analysis, installation and package relocation, optional-dependency-free build, and core/GUI ASan+UBSan. The live MIDI connection test required one retry after a JACK connection failure; its full playback assertions passed on retry. GUI leak checks use the existing fontconfig suppression; core checks are unsuppressed. Physical hardware, human listening and extended high-density endurance remain unverified.

Phase 25 — Plugin and Instrument Usability

Goal

Make instruments and effects practical to use, manage, and diagnose in real projects.

Tasks

Improve plugin discovery, insertion, removal, replacement, and ordering.
Show useful plugin identity and status information, including load failures.
Define parameter metadata, ranges, defaults, units, and formatting.
Support parameter reset and safe default values.
Preserve plugin state across save/load where the plugin API supports it.
Define behavior when a saved plugin is missing or incompatible.
Manage plugin UI lifetime separately from engine object lifetime.
Add tests for plugin lifecycle, state restoration, and failure paths.
Document plugin API versioning and compatibility expectations.

Acceptance criteria

Users can identify and manage loaded instruments and effects without editing configuration files.
Missing or incompatible plugins produce actionable diagnostics and do not silently corrupt projects.
Plugin state restoration is tested for supported plugin types.
The engine remains safe if plugin initialization or processing fails, within the documented failure model.

Implemented for the supported LADSPA 1.1 mono effects/audio sources: explicit module descriptor browser, copied identity and control metadata, generic parameter editor with validated Apply/Cancel and defaults reset, compatible-layout replacement preserving node ID/wires, and atomic effect insertion on a selected wire. Graph connections define order and existing deletion removes incident wires. Edits integrate with undo/redo and compile before adoption. State uses existing v9 parameter/automation records; missing/incompatible plugins retain the current document and report recovery guidance. Native processor ABI 2 remains unchanged. See PLUGIN_HOSTING.md and RECOVERY.md.

Validation: warning-enabled core/GUI builds; full unit/integration suite; fixture and installed amp/inverter/sine plugin tests; actual chooser/editor GUI tests; reset/cancel, insertion, replacement, removal and undo; layout/init/missing module rollback; exact persisted rendering and noncommutative processing order; callback allocation/module-lifetime guards, reliability and static analysis; software JACK GUI/audio/MIDI and workflow; dependency-free build; installation and package relocation; ASan/UBSan including generic-dialog lifetimes (existing fontconfig leak suppression for GUI/system font allocations).

Qualification remains the documented in-process failure model: LADSPA cannot signal run failure or contain crashes/hangs. No external editor, opaque state, MIDI-capable plugin instrument, recursive scanner or new format was added. Physical listening and arbitrary third-party plugin/endurance qualification remain pending.

Phase 26 — Automation and Control Mapping

Goal

Enable repeatable changes to mix and instrument parameters over time, with clear timing and ownership rules.

Tasks

Define a common parameter identity and metadata model.
Support automation lanes for a carefully selected set of parameters.
Define interpolation modes and behavior at clip boundaries.
Specify how automation interacts with live parameter changes and MIDI control.
Add control mapping for selected external MIDI controllers if feasible.
Schedule automation deterministically without allocating memory in the audio callback.
Define behavior when a target parameter or plugin is missing.
Test automation at buffer boundaries, during seeks, and across loop points.
Document precedence rules for automation, controller input, and direct user changes.

Acceptance criteria

Supported parameters can be automated and saved in a project.
Playback produces deterministic automation values for a given project and transport position.
Missing targets fail safely and are reported to the user.
Automation processing meets the engine's real-time safety requirements.

Implemented: common stable owner/parameter keys and copied metadata for track/bus gain/pan, LADSPA input controls and live sine controller targets; validated common static/lane edit APIs; per-point linear/hold mixer automation; per-channel saved volume/pan/sustain CC bindings with explicit disable and reserved panic controllers. GUI adds Interpolation and Audio/MIDI controller mapping; edits participate in undo/redo. Project v10 reads v1–v9 with linear/default-map migration. CONTROL.md documents target identity, clip boundaries, precedence, missing-target handling, controller ramps and real-time ownership.

Validation: warning-enabled core/GUI builds and full tests; common metadata, missing owner/port/module failures and retained state; exact step/ramp endpoints, low-rate collisions, odd blocks, seeks and explicit backward wraps; default/ remapped/disabled/unmapped CCs and stereo pan, immutable maps after preparation; GUI map/interpolation/save/Open/undo/redo and invalid-edit rollback; v1–v9 migration, v10 exact persistence and malformed records; fixture/installed plugin tests, callback-allocation guards, reliability/static analysis, performance and capacity tests; software JACK GUI/audio/MIDI and workflow; dependency-free build, installation/package relocation, core/GUI ASan+UBSan (existing fontconfig leak suppression only for GUI/system font allocations).

No loop transport, MIDI learn/capture, write/touch/latch modes, arbitrary MIDI mapping to arranged faders/plugins, timbre parameter for the built-in sine or opaque-plugin seek restoration is claimed. Live MIDI targets have reset-default metadata and controller bindings, not timeline lanes. Physical controllers, listening and extended third-party-plugin endurance remain unverified.

Phase 27 — Editing Workflow, Undo/Redo, and Usability

Goal

Make common editing actions quick, discoverable, and safe to reverse.

Tasks

Audit user-visible editing operations for undo/redo support.
Implement command-based edits with explicit ownership and rollback behavior.
Group related low-level changes into one meaningful undo step.
Define undo behavior for operations affecting engine state or external files.
Improve keyboard shortcuts, selection behavior, focus handling, and context menus.
Use confirmation only for genuinely destructive or difficult-to-reverse actions.
Provide clear feedback for long-running operations and failures.
Add GUI tests or reproducible manual test procedures for critical workflows.
Keep presentation logic out of the core C engine.

Acceptance criteria

Documented editing operations have predictable undo/redo behavior.
Undo and redo restore the project model and relevant engine state consistently.
Failed operations do not leave partial changes behind.
Common tasks can be completed using documented keyboard and mouse interactions.

Implemented: operation-by-operation audit in EDITING.md; reserved history storage before GUI command mutation/candidate publication, followed by allocation-free snapshot capture; recording start creates no empty history entry and each completed take is one undoable reference edit; unavailable main-menu history steps disabled; surviving editor selections and open piano-roll context retained on undo; piano-roll history shortcuts/context menu and pointer-targeted graph context menus; input focus guards and synchronous busy feedback. Existing C graph/batch note commands and snapshot history remain the model boundary; FLTK presentation stays in C++. No project format change (v10 retained).

Validation: warning-enabled core/GUI builds and full tests; interposed allocation failure for each history reservation and capture with all allocations disabled; GUI history-reservation failure retains document, engine submission count and redo; completed-take undo grouping retains WAV; selection/context-target tests; existing grouped gestures/batches, candidate/backend rollback and save/reopen; workflow/software JACK GUI integration, reliability/callback guards, Clang static analysis, core/GUI ASan+UBSan, optional-dependency-free build, installation and package relocation. GUI sanitizer runs retain the existing fontconfig-only leak suppression. EDITING.md supplies a reproducible native manual procedure for popup dismissal, text focus, large synchronous operations and recorded takes.

Native manual popup/focus/large-file usability checks, broad accessibility and physical-device listening/endurance remain pending. History remains bounded and session-only; selection/layout history, arbitrary command grouping, background loading and destructive source-media editing are not supplied. Preparation failure can stop/reset transport while retaining the old document/history.

Phase 28 — Project Format, Compatibility, and Portability

Goal

Make project files robust, diagnosable, and maintainable across application versions and supported systems.

Tasks

Version the project format and document its compatibility policy.
Validate project input before applying it to the live engine.
Handle missing media, plugins, and external dependencies with clear diagnostics.
Define relative-path, absolute-path, and media-relocation behavior.
Add safe migration routines for supported older versions.
Preserve unknown optional fields where practical, or document when they cannot be preserved.
Test malformed files, truncated files, oversized input, and invalid values.
Make saves atomic where the platform permits, using a temporary file and replacement strategy.
Document portability limits, including plugin and audio-backend dependencies.

Acceptance criteria

Invalid project files are rejected safely without partially replacing the current project.
Save failures do not silently destroy the previous valid project file.
Version incompatibilities and missing dependencies are clearly reported.
Supported project versions have migration and regression tests.

Implementation status

Completed: version-10 compatibility policy and v1–v10 fixture migration; transactional diagnostic loading in the core and GUI; metadata-only dependency inspection with explicit availability limits; relocation and unknown-field policies; bounded-input and deterministic pre/post-rename save-failure coverage. No format bump was needed. Linux/POSIX, plugin ABI/path and audio-backend limits are documented in PROJECT_FORMAT.md and RECOVERY.md.

Validation: full core/GUI/plugin/JACK/workflow/recording/recovery tests, static analysis, staged installation and binary packaging; minimal no-JACK/no-LADSPA build and tests; ASan/UBSan core, reliability and recovery tests.

Phase 29 — Performance, Scalability, and Stress Testing

Goal

Establish measurable performance expectations and verify that larger projects remain stable.

Tasks

Define representative test projects and target buffer sizes.
Measure audio callback duration, deadline misses, CPU use, memory use, and graph rebuild costs.
Test projects with increasing numbers of tracks, graph nodes, connections, MIDI events, and automation points.
Test long playback sessions and repeated start, stop, seek, and loop operations.
Stress-test device changes, plugin failures, missing media, and project reloads.
Use profiling to identify bottlenecks before introducing optimizations.
Verify that the real-time callback does not allocate, block on mutexes, perform file I/O, or wait on GUI work.
Document expected limits and known performance bottlenecks.
Add sanitizers and static analysis to regular development builds where supported.

Acceptance criteria

Performance is measured against documented test cases, not subjective impressions alone.
Stress tests can run repeatedly and produce reproducible results.
No known real-time safety violation remains in the engine's own callback path.
Performance regressions can be detected by repeatable tests or benchmark reports.

Implementation status

Implemented with the existing graph/capacity/fault infrastructure plus Phase 29 project scaling matrices, CPU/RSS/deadline metrics, checked-in reports, virtual endurance, repeated reload/device/plugin fault suites, wider host callback guards and a combined development/sanitizer/static-analysis target. See PERFORMANCE.md for exact workloads, profiling evidence and qualification limits.

Validation: normal core/GUI/JACK/plugin/recovery/recording suites, three-round CPU-contention stress, 2.282-hour virtual playback, minimal build, ASan/UBSan, static analysis and benchmark-gate regression tests passed. Project timing comparison passed. Graph comparisons detect shared-host variation (including a 16-node mono/31-frame alert in a longer run); the prior baseline is retained and this limitation is recorded rather than suppressing the gate. Hardware and wall-clock endurance remain unqualified.

Phase 30 — Release Engineering, Packaging, and Maintenance

Goal

Turn the application into a maintainable release that users can build, install, run, and troubleshoot.

Tasks

Define supported operating systems, compiler versions, and audio backends.
Document build dependencies and provide clear build and test commands.
Add install and uninstall targets that respect PREFIX and standard directory variables.
Provide appropriate package metadata and desktop integration where relevant.
Verify installation paths for binaries, libraries, headers, resources, documentation, and example projects.
Add version reporting and a concise diagnostic mode where useful.
Prepare release notes, known limitations, and upgrade guidance.
Test clean builds from a fresh checkout and installation into a staging directory.
Define a release checklist covering tests, warnings, packaging, and project compatibility.
Document how users can report reproducible bugs and how maintainers should triage them.

Acceptance criteria

A clean checkout can be built and tested using documented commands.
Installation works with a configurable prefix and does not overwrite unrelated user files.
The release includes documentation, known limitations, and a reproducible version identifier.
The project has a repeatable process for preparing and validating releases.

Implementation status

Completed: configurable standard install directories with one shared owned-file inventory, staged file/symlink safety checks, installed metadata-only MIDI example and all performance resources, source SHA-256 sidecars, release notes, upgrades, support matrix and maintenance/triage guidance. Existing version/diagnostic modes, desktop metadata and normalized source/binary packaging are retained.

Acceptance verified with warning-enabled core/GUI builds and tests; default and custom-layout staged install/repair/uninstall with C/C++ consumers; minimal no-JACK/no-FLTK/no-LADSPA build; two clean source-export release builds with byte-identical binaries and repacks; and binary manifest/hash/relocation checks. No public release, tag, version bump or system install is performed. Physical qualification and the Phase 29 graph timing alert remain documented limitations.

Phase 31 — CLAP, VST2 and VST3 Plugin Loading

Goal

Load trusted Linux CLAP, VST2 and VST3 audio effects through the graph and GUI, with explicit lifecycle, format compatibility and realtime ownership contracts.

Tasks

Review and pin redistributable ABI headers and license notices; keep C99 adapters.
Add explicit format probing and compatible mono float32 effect initialization.
Integrate processing, immutable plans, retirement and failure rollback.
Share module entry lifetimes across overlapping instances; defer main-thread callbacks.
Add format/stable identity metadata with v11 migration and missing-module retention.
Generalize the GUI browser, insertion/replacement and identity presentation.
Test original fixtures for all three ABIs, partial failure cleanup, callback safety, save/reopen, missing dependencies and GUI lifecycle.
Document the initial default-configuration effect subset and unsupported extensions.

Acceptance criteria

Compatible fixtures for all three formats render exact expected audio in graphs.
Failed loading/identity/layout/initialization retains the current project/plan.
Loading and reclamation remain off the audio callback, with bounded host processing.
Project files preserve identity and missing references without executing plugins.
Core/GUI builds, regressions, sanitizers and release installation checks pass.

Implementation status

Implemented in C99 with pinned permissive ABI headers, shared entry lifetimes, CLAP main-thread scheduling, graph/GUI integration and v11 plugin identity. Normal/minimal builds, core and GUI plugin fixtures, live JACK/workflow, ASan/UBSan core and GUI checks, static analysis, staged installation and source/binary release checks pass. Tests include activation/start/process and restart errors, rejected layouts/identities, missing modules and retirement. GUI leak checking retains only the existing Fontconfig suppression; core checks use none. Only original ABI fixtures are qualified; arbitrary third-party plugins and physical audio remain unverified. See PLUGIN_HOSTING.md and decision 0010.

The initial subset excludes instruments/events, editable modern parameters, opaque state/custom editors, true stereo/multichannel and latency compensation. These require separate future work; they are not claimed as implemented by loading.

Phase 32 — MIDI Track Plugin Instruments

Goal

Play CLAP, VST2 and VST3 synthesizer/instrument plugins from MIDI clips and live MIDI.

Tasks and acceptance criteria

Discover and initialize compatible zero-input, mono float32, zero-latency instruments.
Bind independent instances to tracks; preserve built-in sine for unassigned tracks.
Deliver sample-offset notes and bounded event queues without callback allocations.
Apply track/bus mixing and provide an explicit saved live-MIDI target.
Handle discontinuity note chase, panic, teardown and failed preparation.
Save bindings in v12; migrate v1–v11 and retain missing module references.
Add GUI load/clear/live-target commands with undo and candidate preparation.
Test original fixtures for all three formats and document the supported subset.

Implementation status

Implemented with track-owned prepared instances and 256-frame processing chunks. Only original ABI fixtures are qualified; arbitrary third-party instruments and physical MIDI/audio hardware remain unverified. Mono/default configuration only; no custom editors, opaque state or modern parameter automation. Native-note CLAP and VST3 carry notes only; CLAP MIDI and VST2 also receive live controllers. Seeking retriggers held scheduled notes with fresh envelopes; plugin release tails can remain after note-off/panic. See PLUGIN_HOSTING.md and decision 0011.

Validation: normal/minimal core and GUI builds, core/instrument/GUI fixtures, JACK/workflow, reliability, ASan/UBSan core and GUI, static analysis, staged installation, reproducible source releases and relocatable binary packages pass.

Phase 33 — Flat Modern DAW Workspace

Goal

Give xtc a clear, modern DAW presentation for creating tracks and arranging music, with simple flat controls and no 3D styling or proprietary assets.

Tasks and acceptance criteria

Introduce one shared dark palette, typography, flat controls and focus/selection accents.
Make track creation, import, instrument loading and MIDI editing visible in a persistent sidebar.
Create/select MIDI tracks with clips and audio tracks transactionally, with undo and failure rollback.
Organize transport, musical position/BPM, main editors, inspector and status in a resizable workspace.
Draw colored track headers, clear clip selection, bar/beat grids and actual MIDI note previews.
Preserve existing editing, mixer/automation, graph, plugin, recording and keyboard behavior.
Add an original multi-track example and document the workflow and retained limitations.
Verify GUI actions, minimum/large layouts, core regressions and release packaging.

Implementation status

Implemented in the FLTK GUI without new dependencies, engine changes or a project format change. Default workspace 1280 × 800; supported minimum 1220 × 720. Track creation is a single undoable prepared-model edit. The transport and sidebar inspector are read-only displays; existing editors retain their controls. Original four-track example visually checked; GUI tests cover creation, selection, rollback, undo/reopen and minimum/large window sizes. This phase modernizes presentation and workflow; it does not claim commercial-DAW feature parity or add docking, scanning or mixer channel-strip functionality. See WORKSPACE.md for the workflow, tests and limits.

Phase 34 — Grid, Clip Editing and Track Instrument Controls

Goal

Expose common DAW editing actions directly in the flat workspace: selectable snap, MIDI clip double-click, individual note velocity and track instruments.

Tasks and acceptance criteria

Draw bar/beat/subdivision grid lines and expose a sequencer Snap dropdown.
Offer Off, straight, triplet, half-note and bar divisions; synchronize the existing snap menu.
Snap clip moves and both trim edges to absolute grid positions, including off-grid clips.
Open the selected MIDI clip's piano roll on left-button double-click without moving it.
Add a fixed velocity lane and selected-note slider with 1..127 validation and one undo step per edit.
Keep coincident chord notes individually editable and preserve timing/pitch/channel.
Add a dropdown to every non-bus track for built-in sine, project instruments and explicit plugin loading.
Preserve track identity through reorder, undo, clear and project reload; retain candidate failure rollback.
Keep controls flat, retain current project format and verify builds, GUI regressions and releases.

Implementation status

Implemented in the C++ GUI over existing C model APIs. Snap preferences are session UI state; note velocity and track instruments already persist in v12. The project instrument list is built from existing assignments, with Load plugin for other trusted binaries; automatic disk scanning is not introduced. At low zoom the visual grid coarsens for readability while snap remains exact to the selected tick division. Off uses pointer/model tick precision. MIDI velocity is a performance value, not a per-note dB gain stage; third-party instrument patches control its audible response. See WORKSPACE.md and MIDI.md.

Phase 35 — Application Preferences and Sequencer Looping

Goal

Persist application preferences in ~/.xtc.conf and provide selectable sequencer loops.

Tasks and acceptance criteria

Add a flat, tabbed Edit / Preferences dialog with Apply and Close.
Validate and atomically save all preference tabs as a private INI file; load at startup.
Expose audio, interface, editing, new-project, plugin-path and transport settings.
List plugin files from configurable CLAP, VST2, VST3 and LADSPA search paths without executing modules.
Select a snapped loop range by Shift-dragging the ruler or entering tick bounds.
Toggle looping and split audio processing at exact sample boundaries.
Preserve real-time constraints and reject recording with looping enabled.
Verify persistence, invalid input, GUI Apply/reload, backend wraps and existing regressions.

Implementation status

Implemented without dependencies or a project format change. Application settings are saved only with Apply; audio connection options take effect on Reconnect and project defaults on New. Existing projects retain their musical data. Loop ranges are global preferences, not project data. Enabled loops require at least 64 samples. See PREFERENCES.md for configuration, workflow and limitations.

Phase 36 — Studio Mixer Overview

Goal

Show every track and bus as a studio-style channel strip with direct level, pan, routing and metering controls in the flat workspace.

Tasks and acceptance criteria

Replace the single-track control panel with a horizontally scrolling bank of all tracks and buses.
Provide vertical dB faders, flat pan knobs, mute/solo switches and output routing per strip.
Show simultaneous stereo track/bus meters and keep the master output monitor visible while scrolling.
Retain selected-track gain/pan automation, interpolation, keyboard control and Add bus.
Preserve stable track identity, undo/redo, persistence and failure rollback across strip edits.
Verify empty/full sessions, reorder/remove, minimum/large layouts and independent meters.
Refresh the view screenshots and document mixer controls and metering limits.
Build and run GUI/core, live JACK, sanitizer and release checks.

Implementation status

Implemented in the C++ FLTK GUI using the existing C mixer and backend snapshot APIs. No audio callback, project format or dependency changes. The fixed master strip monitors graph output; it does not introduce a separate master gain stage. Faders edit static gain and do not chase automation. See MIXER.md and the updated screenshots.

Goal

Reduce menu hunting and make the workspace useful for everyday project editing with a direct transport, track inspector and searchable commands.

Tasks and acceptance criteria

Add Ctrl+P command search with filtering, keyboard navigation, Enter and Escape.
Expose active menu actions through existing callbacks, without duplicating command implementations.
Make project BPM editable from the transport with validation, undo and failed-preparation rollback.
Replace the passive sidebar with a context-aware gain/pan/mute/solo inspector.
Preserve unfinished numeric input across timer refreshes and avoid no-op history edits.
Add a session summary, Fit song and optional Follow playhead navigation.
Persist Follow playhead through the existing Preferences / Apply workflow.
Test command selection/cancellation, inspector edits, tempo rollback/undo and navigation.
Refresh all screenshots, including a command-palette view, and document the workflow.

Implementation status

Implemented over the existing C model, history and backend APIs, with no new dependencies or project format change. Tempo edits stop and rewind transport; track/clip and piano selections survive. Fit song uses the supported 24..384 pixels-per-beat zoom levels; very long projects still require scrolling. The inspector targets the selected mixer channel in Mixer and the arrangement track in other views. Command search lists active menu actions; it is not a plugin scanner or a key-binding editor. See WORKSPACE.md.

Future usability work

Independent track inserts and customizable shortcuts remain future work. Dockable editors and pinned headers are implemented in Phase 46; arrangement multiselection and phrase editing follow in Phases 47–51.

Phase 38 — Internal instruments and effects

Tasks and acceptance criteria

Add always-available Soft Keys and Sub Bass MIDI instrument presets.
Add Delay and Reverb with bounded controls and effect automation.
Integrate track selection, graph wire insertion, undo and saved projects.
Preserve older projects; reserve format 13 internal device identities.
Verify DSP tails, block partition consistency, note release/panic and persistence.
Refresh application screenshots and add internal device editor views.

Implementation status

Implemented for the bounded initial device set. Audited 2026-11-05 against src/plugin/builtin.c, the shared plugin host, track instrument selector, graph commands and v13 persistence. Soft Keys and Sub Bass are fixed 32-voice presets; Delay and Reverb each expose three bounded, automatable controls. Preparation owns buffer allocation; processing uses preallocated storage. Internal devices use virtual identities rather than loading external modules; the reader retains v1–v12 compatibility. Actual device control screenshots are listed in screenshots/README.md.

tests/unit/test_builtin.c covers both effect tails and block partitions, dry mix, invalid feedback, both instruments' release/panic, mix automation and a keys/delay project round trip. Shared GUI tests cover instrument selection, history and plugin editing, but do not constitute a dedicated end-to-end matrix for all four internal devices. Additional qualification is tracked in Phase 40.

The initial subset lacked editable presets, pitch bend, sample instruments, smooth/tempo-synced delay, stereo reverb, seek history policy and automatic tails. These audit gaps are addressed by Phases 41–44 below. See BUILTIN_DEVICES.md for controls and explicit limitations.

Phase 39 — Detachable transport and mixer

Tasks and acceptance criteria

Float/dock the existing transport and mixer without duplicating state.
Keep BPM and loop settings in the shared transport controls.
Recover arrangement space and retain resizable mixer channels.
Support close-to-dock, Dock all, floating playback shortcuts and safe shutdown.
Exercise lifecycle, settings and resizing in GUI tests and capture floating views.

Implementation status

Implemented for the transport and mixer. Audited 2026-11-05 against src/gui/main_window.cpp and tests/integration/test_gui.cpp. Detaching reparents the existing widgets on the GUI thread; BPM, loop settings and mixer state remain shared. Docking restores ownership and arrangement space, and the destructor docks panels before destroying their windows. Tests exercise repeated detach/dock, close-to-dock, shared BPM/loop state, floating playback shortcuts, main/floating resizing and failed/successful shutdown. Floating screenshots are listed in screenshots/README.md.

Define supported dock locations and layout ownership for sequencer, piano roll and modular graph panels.
Detach/dock each supported editor without duplicating project, selection or history state.
Support resizable pinned track headers and preserve editing coordinates, scrolling and focus after reparenting.
Integrate with Phase 45 layout persistence and provide a safe reset-layout action.
Verify minimum/large layouts, cross-panel editing, repeated reparenting and shutdown/error paths.

Tasks and acceptance criteria

Provide the control/model behavior and accessible GUI commands.
Validate bounds and failure rollback; preserve existing project compatibility and callback safety.
Test the new workflow and document scope and limitations.

Implementation status

Implemented: two independent GUI mixer comparison slots and public C snapshot capture/recall. Recall validates the stable track ID set, tolerates reorder and creates one undoable edit; New/Open clears slots. Core rollback/reorder, GUI recall/undo/document lifecycle, allocation-failure, persistence/render, sanitizer, static-analysis and installation checks qualify the integrated work. See MODERN_EDITING.md for scope and validation.

Integrated validation for Phases 47–57

Each phase has a separate implementation commit and warning-enabled model/GUI checks. The final suite includes allocation-failure rollback and ID preservation, clipboard track mapping, note/source bounds, grouped undo, persistence/render comparison, the complete GUI/plugin fixture matrix and software JACK lifecycle. ASan/UBSan, Clang analysis and both staged installation layouts cover integration. Project format remains 15; no new dependencies or callback work were introduced. See MODERN_EDITING.md for commands, scope and remaining DAW features. Human listening, physical hardware and arbitrary third-party plugins remain unqualified.

Phase 58 — Persistent Arrangement Markers

Goal

Store up to 128 named, tick-keyed markers with versioned migration, undoable GUI editing and ruler display.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: sorted tick-keyed markers, bounded UTF-8 names, undoable GUI editing and ruler display. Format 16 appends marker records and reads versions 1–15. Core, legacy migration, malformed-load rollback and focused GUI history/docking tests pass.

Goal

Navigate previous/next markers and loop the section between a marker and its successor or the song end.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: strict previous/next navigation and section queries, exposed through View commands. Navigation stops playback safely; section looping shares existing loop controls. Core boundaries/final-section and GUI navigation/loop tests pass.

Phase 60 — Ripple Time Editing

Goal

Insert or remove bounded timeline ranges atomically, shifting clips, markers and automation; reject clips crossing edit boundaries explicitly.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: atomic gap insertion/range removal shifts clips, markers and mixer/instrument/graph plugin automation. Crossing clips reject explicitly. Core position/automation/removal rollback tests and GUI edit/history checks pass.

Phase 61 — Complete Track Duplication

Goal

Duplicate a non-bus track with fresh IDs, clips, notes, mixer controls, routing, instrument settings and track automation in one transaction.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: complete non-bus track duplication with fresh IDs, adjacent ordering, source media/notes, instrument settings, mix, bus routing and automation. Core ownership/property checks and GUI undo tests pass.

Phase 62 — Nondestructive MIDI Clip Splitting

Goal

Split trimmed MIDI clips at the cursor while preserving source-relative note content and verifying boundary scheduling.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: trimmed MIDI splitting with fresh right-side clip/note IDs and complete retained source notes. Original sine rendering is identical across the split in regression tests; MIDI instruments may retrigger at boundaries. Core range/render and GUI split/undo tests pass.

Phase 63 — MIDI Clip Consolidation

Goal

Merge selected MIDI clips on one track into a fresh source, retaining audible notes and gaps with explicit boundary clipping and rollback.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: transactional consolidation of selected same-track MIDI clips into a fresh source. Visible note intersections are cropped, hidden notes dropped and gaps/overlaps retained. Core trim/timing/ID checks and GUI merge/undo tests pass.

Phase 64 — Deterministic MIDI Humanization

Goal

Apply seeded timing and velocity variation to MIDI clip sources with reproducible results, bounds checks and undo.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: seeded note-ID keyed timing/velocity humanization, independent of selection order. Timing overflow rejects atomically; velocity saturates to MIDI bounds. Core reproducibility/range/rollback and GUI undo tests pass.

Phase 65 — Chord Construction

Goal

Generate bounded custom chord intervals from source notes with fresh IDs, preserved articulation and transactional pitch/capacity checks.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: custom bounded chord intervals add independent notes with fresh IDs while retaining originals and articulation. Core pitch/duplicate-interval/capacity-bound rollback and GUI chord/history tests pass.

Phase 66 — Offline Arpeggio Generation

Goal

Convert source note chords into bounded ascending/descending stepped patterns with gate controls, deterministic ordering and undo.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: bounded offline ascending/descending arpeggio generation with equal-onset/channel chord grouping, step/gate controls and fresh note IDs. Core ordering/gate/capacity rollback and GUI generation/undo tests pass.

Phase 67 — Audio Peak Normalization

Goal

Analyze the audible source slice outside callbacks and adjust nondestructive clip gain to a requested sample-peak target; validate silence, missing media and gain limits.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Implemented: native-rate audible-slice sample-peak analysis adjusts nondestructive clip gain atomically. GUI accepts dBFS targets. Core exact gain, missing-media rollback, silence/gain-limit checks and GUI normalization/undo tests pass.

Phase 68 — Portable Project Collection

Goal

Collect referenced audio and sampler media into a new self-contained project folder, deduplicate references, preserve original files and reject existing destinations or unsupported references safely.

Tasks and acceptance criteria

Implement bounded C99 model/control APIs and accessible GUI commands.
Preserve transactional errors, history, compatibility and callback safety.
Verify the feature with automated model/GUI tests and document limitations.

Implementation status

Planned.

Recommended Execution Order

Reorder the phases when the audit reveals a blocking dependency. Do not mark a phase complete merely because code exists: its acceptance criteria must be demonstrated by builds, tests, or documented manual verification.

Definition of Done for Each Phase

A phase is complete only when:

The project builds with warnings enabled.
Relevant automated tests pass, and manual tests are documented where automation is impractical.
Error paths, resource ownership, and thread boundaries have been reviewed.
Real-time audio constraints remain satisfied.
Documentation is updated alongside API or behavior changes.
No unrelated functionality was silently removed.
Untested behavior and known limitations are reported honestly.
The phase's acceptance criteria are explicitly checked off.

Do not skip phases without documenting why and preserving acceptance criteria.

91 KiB Raw Blame History Unescape Escape

Roadmap

Phase 0 — Baseline

Phase 1 — C core and offline processing

Phase 2 — Real-time backend

Phase 3 — FLTK shell

Phase 4 — Modular editor

Phase 5 — Project and sequencer

Phase 6 — Audio clips and recording

Phase 7 — MIDI and instrument

Phase 8 — Mixer and editing

Phase 9 — Extensibility and release

Phase 10 — Engine Correctness and Reliability

Tasks

Acceptance criteria

Phase 11 — Complete Minimal Music-Making Workflow

Tasks

Acceptance criteria

Phase 12 — Audio Quality and Transport Correctness

Tasks

Acceptance criteria

Phase 13 — Recording and Recovery

Tasks

Acceptance criteria

Phase 14 — Native Plugin, Instrument, and Effect Architecture

Tasks

Acceptance criteria

Phase 15 — External Plugin Hosting

Tasks

Acceptance criteria

Phase 16 — Automation and Expressive Control

Tasks

Acceptance criteria

Phase 17 — Editing Workflow, Undo/Redo, and Usability

Tasks

Acceptance criteria

Phase 18 — Project Format, Compatibility, and Portability

Tasks

Acceptance criteria

Phase 19 — Performance, Scalability, and Stress Testing

Tasks

Acceptance criteria

Phase 20 — Release Engineering, Packaging, and Maintenance

Tasks

Acceptance criteria

Phase 21 — Advanced MIDI and Composition

Goal

Tasks

Acceptance criteria

Phase 22 — Audio Clip Editing and Utility Operations

Goal

Tasks

Acceptance criteria

Phase 23 — Modular Workflow and Routing Refinement

Goal

Tasks

Acceptance criteria

Phase 24 — Mixing and Mastering Essentials

Goal

Tasks

Acceptance criteria

Phase 25 — Plugin and Instrument Usability

Goal

Tasks

Acceptance criteria

Phase 26 — Automation and Control Mapping

Goal

Tasks

Acceptance criteria

Phase 27 — Editing Workflow, Undo/Redo, and Usability

Goal

Tasks

Acceptance criteria

Phase 28 — Project Format, Compatibility, and Portability

Goal

Tasks

Acceptance criteria

Implementation status

Phase 29 — Performance, Scalability, and Stress Testing

Goal

91 KiB

Raw Blame History