diff --git a/README.md b/README.md index c3378f3..28ce96c 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,19 @@ ![xtc promotional overview: arrangement, piano roll, mixer and modular effects](screenshots/overview.png) +## Table of contents + +- [Design decisions](#design-decisions) +- [Current status](#current-status) +- [Build](#build) +- [Run](#run) +- [Using the GUI](#using-the-gui) +- [Features](#features) +- [Documentation](#documentation) +- [Diagnostics](#diagnostics) +- [Suggested first agent task](#suggested-first-agent-task) +- [License](#license) + ## Design decisions - **Modular engine first:** sequencer, instruments, effects, mixers and I/O are nodes in one processing graph. @@ -15,6 +28,7 @@ ## Current status This repository is a starter scaffold, not a production DAW. It currently provides: + - a small C library/API; - a mono graph model with port validation, cycle rejection and topological ordering; - compiled offline plans with preallocated buffers, sine oscillator, audio source, gain, meter and output nodes; @@ -33,16 +47,11 @@ This repository is a starter scaffold, not a production DAW. It currently provid - native C processors, deterministic source packaging and staged install/uninstall; - architecture, format, GUI, roadmap, and decision documents. -The JACK backend has passed software-loopback testing; physical-device playback -and capture are unverified. MIDI recording remains deferred. Bounded LADSPA -hosting supports the compatible mono processors documented in -[PLUGIN_HOSTING.md](docs/PLUGIN_HOSTING.md). +The JACK backend has passed software-loopback testing; physical-device playback and capture are unverified. MIDI recording remains deferred. Bounded LADSPA hosting supports the compatible mono processors documented in [PLUGIN_HOSTING.md](docs/PLUGIN_HOSTING.md). ## Build -Requirements: CMake 3.25+, a C99 compiler, Python 3.12+ and a build backend -such as Ninja or Unix Makefiles. The optional GUI needs C++17 and FLTK; JACK and -LADSPA development files enable their optional integrations. +Requirements: CMake 3.25+, a C99 compiler, Python 3.12+ and a build backend such as Ninja or Unix Makefiles. The optional GUI needs C++17 and FLTK; JACK and LADSPA development files enable their optional integrations. ```sh cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug @@ -60,16 +69,11 @@ make run # build and launch it make clean # clean products; keep the CMake cache ``` -Override `BUILD_DIR`, `BUILD_TYPE` or `JOBS` as needed, for example -`make BUILD_DIR=build/release BUILD_TYPE=Release JOBS=8`. Pass additional options -with `CMAKE_ARGS` and `CTEST_ARGS`. CMake remains the authoritative build system. +Override `BUILD_DIR`, `BUILD_TYPE` or `JOBS` as needed, for example `make BUILD_DIR=build/release BUILD_TYPE=Release JOBS=8`. Pass additional options with `CMAKE_ARGS` and `CTEST_ARGS`. CMake remains the authoritative build system. -This builds `libxtc.a`, the headless `xtc-check`, tests, examples and the FLTK -application when available. Live JACK tests are opt-in. Use `-DXTC_BUILD_GUI=OFF` -for the C-only build, or the `debug`, `release`, `minimal` and `sanitize` presets -for separate configurations. See [docs/BUILD.md](docs/BUILD.md) for options, -focused tests, installation and IDE setup. [Phase 108](docs/ROADMAP.md#phase-108--complete-cmake-build-migration) records -the CMake migration. +This builds `libxtc.a`, the headless `xtc-check`, tests, examples and the FLTK application when available. Live JACK tests are opt-in. Use `-DXTC_BUILD_GUI=OFF` for the C-only build, or the `debug`, `release`, `minimal` and `sanitize` presets for separate configurations. See [docs/BUILD.md](docs/BUILD.md) for options, focused tests, installation and IDE setup. [Phase 108](docs/ROADMAP.md#phase-108--complete-cmake-build-migration) records the CMake migration. + +## Run Run the GUI: @@ -77,44 +81,7 @@ Run the GUI: ./build/xtc ``` -See [the minimal music-making workflow](docs/WORKFLOW.md) for creating, saving, -reopening and playing a project. - -The GUI opens JACK and offers Play/Pause/Stop/To start/Reconnect, backend status and view -switching. The initial empty graph is silent. Modular Graph supports adding, -moving and deleting oscillator/audio/instrument/gain/meter/output nodes and connecting ports. -Import WAV (Ctrl+I) creates playable clips; Add region creates silent placeholders. -Record captures JACK input to a chosen WAV; Stop finalizes and adds the take. -Save the project after recording. External asset paths must remain available; -select a missing clip and use File/Relink selected audio to repair it. -Add MIDI clip on an existing track, then open Piano roll (or Ctrl+5 for the selected track) to draw notes. -Connect a MIDI source to the JACK `midi_in` port for live playing; Panic/F9 -silences held notes. See [MIDI workflow and limits](docs/MIDI.md). -See [audio workflow and limits](docs/AUDIO_FILES.md) and the -[sample editor workflows](docs/AUDIO_EDITOR.md). -Mixer (Ctrl+2) selects a track for gain/pan/mute/solo and automation editing. -Ctrl+Z undoes; Ctrl+Shift+Z or Ctrl+Y redoes up to 32 edits. -The GUI now exposes left `output` and `output_right` JACK ports; route both -explicitly for stereo. See [mixer workflow and limits](docs/MIXER.md). -Use Add track/Add region, drag regions or their edges, and Zoom +/-; scrollbars pan. -Ctrl+N/O/S creates, opens or saves a project; Save As chooses another path. -Arrangement edits stop playback; graph edits remain live. -The ruler seeks while stopped. Stop pauses; Reconnect and project load reset position. F5 starts, F8 stops, Space toggles, F6 reconnects, and Ctrl+1/2/3 -switches views. Ctrl+Q closes the client and window. No physical ports are -connected automatically. In Modular Graph, drag output to input to connect; -select a node or wire and press Delete to remove it. Invalid edits leave the -active graph intact; queued changes are labeled until the engine adopts them. -See [GUI documentation](docs/GUI.md). -For Linux installation, routing and CLI options see [LINUX.md](docs/LINUX.md); -for native effects/instruments see [NATIVE_API.md](docs/NATIVE_API.md). -The release preset and CMake’s `dist`, `test-install`, `test-release` and -`test-package` targets provide release preparation; see -[RELEASING.md](docs/RELEASING.md) for exact guarantees. -With JACK development files and an existing JACK-compatible server, configure -with `-DXTC_ENABLE_LIVE_TESTS=ON`, build, and run -`ctest --test-dir build --output-on-failure -L live`. These software-loopback -checks connect only test clients. See [engine documentation](docs/AUDIO_ENGINE.md) -for configuration, routing, ownership and recovery. +See [the minimal music-making workflow](docs/WORKFLOW.md) for creating, saving, reopening and playing a project. Clean generated files: @@ -122,102 +89,80 @@ Clean generated files: cmake --build build --target clean ``` +## Using the GUI + +- The GUI opens JACK and offers Play/Pause/Stop/To start/Reconnect, backend status and view switching. The initial empty graph is silent. +- Modular Graph supports adding, moving and deleting oscillator/audio/instrument/gain/meter/output nodes and connecting ports. +- Import WAV (Ctrl+I) creates playable clips; Add region creates silent placeholders. +- Record captures JACK input to a chosen WAV; Stop finalizes and adds the take. +- Save the project after recording. External asset paths must remain available; select a missing clip and use File/Relink selected audio to repair it. +- Add MIDI clip on an existing track, then open Piano roll (or Ctrl+5 for the selected track) to draw notes. +- Connect a MIDI source to the JACK `midi_in` port for live playing; Panic/F9 silences held notes. See [MIDI workflow and limits](docs/MIDI.md). +- See [audio workflow and limits](docs/AUDIO_FILES.md) and the [sample editor workflows](docs/AUDIO_EDITOR.md). +- Mixer (Ctrl+2) selects a track for gain/pan/mute/solo and automation editing. +- Ctrl+Z undoes; Ctrl+Shift+Z or Ctrl+Y redoes up to 32 edits. +- The GUI now exposes left `output` and `output_right` JACK ports; route both explicitly for stereo. See [mixer workflow and limits](docs/MIXER.md). +- Use Add track/Add region, drag regions or their edges, and Zoom +/-; scrollbars pan. +- Ctrl+N/O/S creates, opens or saves a project; Save As chooses another path. +- Arrangement edits stop playback; graph edits remain live. +- The ruler seeks while stopped. Stop pauses; Reconnect and project load reset position. F5 starts, F8 stops, Space toggles, F6 reconnects, and Ctrl+1/2/3 switches views. Ctrl+Q closes the client and window. No physical ports are connected automatically. +- In Modular Graph, drag output to input to connect; select a node or wire and press Delete to remove it. Invalid edits leave the active graph intact; queued changes are labeled until the engine adopts them. See [GUI documentation](docs/GUI.md). +- For Linux installation, routing and CLI options see [LINUX.md](docs/LINUX.md); for native effects/instruments see [NATIVE_API.md](docs/NATIVE_API.md). +- The release preset and CMake's `dist`, `test-install`, `test-release` and `test-package` targets provide release preparation; see [RELEASING.md](docs/RELEASING.md) for exact guarantees. +- With JACK development files and an existing JACK-compatible server, configure with `-DXTC_ENABLE_LIVE_TESTS=ON`, build, and run `ctest --test-dir build --output-on-failure -L live`. These software-loopback checks connect only test clients. See [engine documentation](docs/AUDIO_ENGINE.md) for configuration, routing, ownership and recovery. + +## Features + +### Audio + +- Audio timing, transitions, latency limits and listening previews are described in [docs/AUDIO_QUALITY.md](docs/AUDIO_QUALITY.md). Human listening acceptance of the transitions remains pending. +- Non-destructive audio splitting, clip gain/fades and cached timeline waveforms are supported, with undo and v8 persistence (reading v1–v7). See [AUDIO_FILES.md](docs/AUDIO_FILES.md#non-destructive-clip-editing). `cmake --build build --target test-audio-editing` checks source preservation and exact boundary output. Time stretching and independent pitch shifting remain deferred. + +### Mixing and routing + +- Signal-flow graph layout, routing diagnostics, direction/role indicators and atomic unity-gain insertion into a wire are supported. See [ROUTING.md](docs/ROUTING.md); `cmake --build build --target test-routing` verifies the C routing contract. +- One-level mix buses, routing, coherent track/bus peaks and master clipping indicators are supported, persisted in v9 (reading v1–v8). See [MIXER.md](docs/MIXER.md). + +### Plugins and instruments + +- LADSPA descriptor browsing, an identity/parameter editor with reset, transactional replacement and insertion into graph wires are supported. See [PLUGIN_HOSTING.md](docs/PLUGIN_HOSTING.md) for compatibility and lifecycle limits. +- Common parameter targets, Linear/Hold mixer automation and saved per-channel live MIDI CC bindings are supported. Project v10 reads v1–v9. See [CONTROL.md](docs/CONTROL.md) for timing, precedence and qualification limits. +- `File → Load plugin` supports LADSPA plus an initial Linux CLAP/VST2/VST3 effect subset. Select the actual module binary (`.clap` or `.so`, including a VST3 bundle's inner binary). Modern effects require one mono input and output, float32 and zero latency; they use default configuration. Instruments, modern parameter editing/automation, opaque state and custom editors are not implemented. Projects now save v11 and read v1–v11. See PLUGIN_HOSTING.md for the full contract and test/qualification limits. +- [Steinberg SDK integration (Phase 106)](docs/STEINBERG.md) adds conventional Linux VST3 bundle loading, transport context, official-SDK gain/synth examples and validator checks. Run `cmake -S . -B build -DXTC_VST3_SDK_ROOT=/path/to/vst3sdk -DXTC_BUILD_STEINBERG=ON && cmake --build build --target test-steinberg-sdk` for optional SDK qualification. A Windows ASIO device diagnostic is provided; a native ASIO playback/capture backend remains planned. +- [JUCE integration (Phase 107)](docs/JUCE.md) provides an optional VST3/standalone Soft Keys instrument with a native editor, DSP effects, presets, MIDI-to-WAV rendering and VST3 hosting examples. Build and qualify it with `cmake -S . -B build -DXTC_JUCE_ROOT=/path/to/JUCE -DXTC_BUILD_JUCE=ON && cmake --build build --target test-juce`; review JUCE's AGPLv3/commercial licence before distributing linked binaries. See [the examples](examples/juce/README.md). + +### MIDI and composition + +- MIDI devices and defaults are configurable in **Preferences → midi**, including JACK/PipeWire input/output choices, channel filtering and optional thru. Use **File → Import MIDI** or **Export selected clip as MIDI** to exchange note clips. Application preferences load from **`~/.xtc.conf`** at startup and save on Apply and clean exit. See [configuration and MIDI workflows](docs/MIDI_WORKFLOWS.md) for file support, routing and persistence details. + +### Editing and project workflow + +- Undo storage is reserved before edits/publication, completed takes are grouped, surviving editor selections are preserved and context menus/focus feedback are improved. See [EDITING.md](docs/EDITING.md) for the workflow audit and failure boundaries. +- A compact sequencer Create menu, optional track inspector and per-track modular effect chains are supported. Open **View → Track inserts** (or Ctrl+5 for the selected track) to add, search, reorder, bypass, inspect and mix mono LADSPA/VST2/VST3/CLAP effects or internal devices. Chains support undo, presets, audio/MIDI rendering and export. Projects save format 17 and read formats 1–17. See [track insert workflows and limits](docs/TRACK_INSERTS.md) and the [screenshot gallery](screenshots/README.md). +- Direct selected-track inserts, effect duplication, chain copy/paste, A/B snapshots, three internal effect templates, bulk rack actions, insert peak meters, tap tempo, audio crossfades and MIDI chord strumming are supported. See [creative workflows and limits](docs/CREATIVE_WORKFLOWS.md). + +### Engine and release + +- The engine adds no-clobber recording/recovery, parameterized native C processors, and trusted in-process LADSPA hosting with persisted identity/control values. See [RECOVERY.md](docs/RECOVERY.md), [NATIVE_API.md](docs/NATIVE_API.md) and [PLUGIN_HOSTING.md](docs/PLUGIN_HOSTING.md) for commands and limits. +- Effect automation/controllers, editing commands, v7 project-folder media paths, performance baselines and release/installation checks are also supported. +- Audio timing, transitions, latency limits and listening previews are described in [docs/AUDIO_QUALITY.md](docs/AUDIO_QUALITY.md). Human listening acceptance of the transitions remains pending. + +## Documentation + +For everyday use see [USER_MANUAL.md](docs/USER_MANUAL.md), [KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) and [MAINTENANCE.md](docs/MAINTENANCE.md). `xtc-check --diagnose` reports build features; `cmake --build build --target test-package` checks a local system-linked Linux binary archive. + +## Diagnostics + +Project troubleshooting: `xtc-check --validate PROJECT.xtc` reports metadata errors with the expected record and syntax line. `xtc-check --inspect PROJECT.xtc` lists resolved media/module paths and plugin identities without executing plugins or starting JACK. Exit codes: 0 = valid metadata and available files, 2 = missing or unreadable references, 1 = metadata/I/O error. File availability does not certify WAV contents or plugin compatibility. See [PROJECT_FORMAT.md](docs/PROJECT_FORMAT.md) for the compatibility and relocation policy. + ## Suggested first agent task Read `AGENT.md` and `docs/ARCHITECTURE.md`. Inspect the existing implementation, run `cmake --build build --target check`, and report gaps before adding the next feature. Do not jump directly to plugin hosting or a full sequencer. +## Authors + +- Johannes Findeisen — Core developer and Founder + ## License -The project is scaffolded under the MIT License; see `LICENSE`. Review the licenses of any future dependencies before distribution. - -Audio timing, transitions, latency limits and listening previews are described -in [docs/AUDIO_QUALITY.md](docs/AUDIO_QUALITY.md). Human listening acceptance -of the transitions remains pending. - -The engine adds no-clobber recording/recovery, parameterized native C processors, -and trusted in-process LADSPA hosting with persisted identity/control values. -See [RECOVERY.md](docs/RECOVERY.md), [NATIVE_API.md](docs/NATIVE_API.md) and -[PLUGIN_HOSTING.md](docs/PLUGIN_HOSTING.md) for commands and limits. - -For everyday use see [USER_MANUAL.md](docs/USER_MANUAL.md), -[KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) and -[MAINTENANCE.md](docs/MAINTENANCE.md). `xtc-check --diagnose` reports build features; -`cmake --build build --target test-package` checks a local system-linked Linux binary archive. -Effect automation/controllers, editing commands, v7 project-folder media paths, -performance baselines and release/installation checks are also supported. - -Non-destructive audio splitting, clip gain/fades and cached timeline waveforms -are supported, with undo and v8 persistence (reading v1–v7). See -[AUDIO_FILES.md](docs/AUDIO_FILES.md#non-destructive-clip-editing). -`cmake --build build --target test-audio-editing` checks source preservation and exact boundary output. -Time stretching and independent pitch shifting remain deferred. - -Signal-flow graph layout, routing diagnostics, direction/role indicators and -atomic unity-gain insertion into a wire are supported. See -[ROUTING.md](docs/ROUTING.md); `cmake --build build --target test-routing` verifies the C routing contract. - -One-level mix buses, routing, coherent track/bus peaks and master clipping -indicators are supported, persisted in v9 (reading v1–v8). See [MIXER.md](docs/MIXER.md). - -LADSPA descriptor browsing, an identity/parameter editor with reset, -transactional replacement and insertion into graph wires are supported. See -[PLUGIN_HOSTING.md](docs/PLUGIN_HOSTING.md) for compatibility and lifecycle limits. - -Common parameter targets, Linear/Hold mixer automation and saved per-channel -live MIDI CC bindings are supported. Project v10 reads v1–v9. See -[CONTROL.md](docs/CONTROL.md) for timing, precedence and qualification limits. - -Undo storage is reserved before edits/publication, completed takes are grouped, -surviving editor selections are preserved and context menus/focus feedback are -improved. See [EDITING.md](docs/EDITING.md) for the workflow audit and failure -boundaries. - -Project troubleshooting: `xtc-check --validate PROJECT.xtc` reports metadata -errors with the expected record and syntax line. `xtc-check --inspect PROJECT.xtc` -lists resolved media/module paths and plugin identities without executing plugins -or starting JACK. Exit codes: 0 = valid metadata and available files, 2 = missing -or unreadable references, 1 = metadata/I/O error. File availability does not -certify WAV contents or plugin compatibility. See [PROJECT_FORMAT.md](docs/PROJECT_FORMAT.md) -for the compatibility and relocation policy. - -**File → Load plugin** supports LADSPA plus an initial Linux -CLAP/VST2/VST3 effect subset. Select the actual module binary (`.clap` or `.so`, -including a VST3 bundle's inner binary). Modern effects require one mono input -and output, float32 and zero latency; they use default configuration. Instruments, -modern parameter editing/automation, opaque state and custom editors are not -implemented. Projects now save v11 and read v1–v11. See PLUGIN_HOSTING.md for the -full contract and test/qualification limits. - - -A compact sequencer Create menu, optional track inspector and per-track modular -effect chains are supported. Open **View → Track inserts** (or Ctrl+5 for the selected track) to add, -search, reorder, bypass, inspect and mix mono LADSPA/VST2/VST3/CLAP effects or -internal devices. Chains support undo, presets, audio/MIDI rendering and export. -Projects save format 17 and read formats 1–17. See -[track insert workflows and limits](docs/TRACK_INSERTS.md) and the -[screenshot gallery](screenshots/README.md). - -Direct selected-track inserts, effect duplication, chain copy/ -paste, A/B snapshots, three internal effect templates, bulk rack actions, insert -peak meters, tap tempo, audio crossfades and MIDI chord strumming are supported. See -[creative workflows and limits](docs/CREATIVE_WORKFLOWS.md). - -MIDI devices and defaults are configurable in **Preferences → midi**, including -JACK/PipeWire input/output choices, channel filtering and optional thru. Use -**File → Import MIDI** or **Export selected clip as MIDI** to exchange note clips. -Application preferences load from **`~/.xtc.conf`** at startup and save on Apply -and clean exit. See [configuration and MIDI workflows](docs/MIDI_WORKFLOWS.md) -for file support, routing and persistence details. - - -[Steinberg SDK integration (Phase 106)](docs/STEINBERG.md) adds conventional Linux -VST3 bundle loading, transport context, official-SDK gain/synth examples and -validator checks. Run `cmake -S . -B build -DXTC_VST3_SDK_ROOT=/path/to/vst3sdk -DXTC_BUILD_STEINBERG=ON && cmake --build build --target test-steinberg-sdk` -for optional SDK qualification. A Windows ASIO device diagnostic is provided; -a native ASIO playback/capture backend remains planned. - -[JUCE integration (Phase 107)](docs/JUCE.md) provides an optional VST3/standalone -Soft Keys instrument with a native editor, DSP effects, presets, MIDI-to-WAV -rendering and VST3 hosting examples. Build and qualify it with -`cmake -S . -B build -DXTC_JUCE_ROOT=/path/to/JUCE -DXTC_BUILD_JUCE=ON && cmake --build build --target test-juce`; review JUCE’s AGPLv3/commercial licence -before distributing linked binaries. See [the examples](examples/juce/README.md). +The project is scaffolded under the MIT License; see `LICENSE`. Review the licenses of any future dependencies before distribution. See also [docs/LICENSES.md](docs/LICENSES.md). \ No newline at end of file