209 lines
11 KiB
Markdown
209 lines
11 KiB
Markdown
# xtc — a lightweight, modular DAW
|
||
|
||
`xtc` is a new, energyXT-inspired digital audio workstation project. It is not a clone and contains no energyXT source code or assets.
|
||
|
||
|
||
|
||
## Design decisions
|
||
|
||
- **Modular engine first:** sequencer, instruments, effects, mixers and I/O are nodes in one processing graph.
|
||
- **C core:** project model, graph, DSP and audio engine are implemented in C.
|
||
- **FLTK/C++ GUI:** C++ is confined to the graphical interface and calls the core through a C API.
|
||
- **Linux first:** keep backend-specific details behind an interface.
|
||
- **Small increments:** build and test each milestone before adding features.
|
||
|
||
## 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;
|
||
- C tests for deterministic rendering, routing, validation and lifecycle;
|
||
- an optional JACK-compatible backend with mono input and mono/stereo output with start/stop, routing and status;
|
||
- safe control/audio plan handoff and concurrent replacement tests;
|
||
- an optional FLTK shell with engine controls, view switching and backend status;
|
||
- a modular graph editor with transactional edits and live plan adoption status;
|
||
- versioned project save/load and a timeline for tracks and clips;
|
||
- sample-counted transport, selection, move/trim, timeline zoom and scrolling;
|
||
- WAV import/graph playback, bounded recording and missing-asset relinking;
|
||
- MIDI clips, a sine instrument, JACK MIDI input and a basic piano roll;
|
||
- stereo track/bus gain/pan/mute/solo, dBFS peak meters and gain/pan automation lanes;
|
||
- bounded undo/redo with keyboard shortcuts;
|
||
- configurable boundary fades, gain ramps and graceful GUI playback transitions;
|
||
- 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).
|
||
|
||
## Build
|
||
|
||
Requirements: a C compiler, a C++ compiler, GNU Make, and `pkg-config`. FLTK is optional for the core and tests.
|
||
|
||
```sh
|
||
make
|
||
make test
|
||
```
|
||
|
||
`make` also builds `build/xtc-check`, a headless core startup/shutdown
|
||
check. Use `make debug` for a separate debug build and test run. See
|
||
[docs/BUILD.md](docs/BUILD.md) for the inspected toolchain and baseline limits.
|
||
|
||
Build the optional FLTK GUI if FLTK is installed:
|
||
|
||
```sh
|
||
make gui
|
||
```
|
||
|
||
Run the GUI:
|
||
|
||
```sh
|
||
./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).
|
||
`make release`, `make dist`, `make test-install` and `make test-release` provide
|
||
release preparation; see [RELEASING.md](docs/RELEASING.md) for exact guarantees.
|
||
With JACK development files and an existing JACK-compatible server, run the
|
||
isolated software-loopback test with `make test-jack` and the record/reopen/play
|
||
acceptance test with `make test-jack-audio` and MIDI acceptance with
|
||
`make test-jack-midi`. It connects only test
|
||
clients. See [engine documentation](docs/AUDIO_ENGINE.md) for configuration,
|
||
routing, ownership and recovery.
|
||
|
||
Clean generated files:
|
||
|
||
```sh
|
||
make clean
|
||
```
|
||
|
||
## Suggested first agent task
|
||
|
||
Read `AGENT.md` and `docs/ARCHITECTURE.md`. Inspect the existing implementation, run `make test`, and report gaps before adding the next feature. Do not jump directly to plugin hosting or a full sequencer.
|
||
|
||
## 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;
|
||
`make 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).
|
||
`make 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); `make 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 `make VST3_SDK_ROOT=/path/to/vst3sdk 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
|
||
`make JUCE_ROOT=/path/to/JUCE test-juce`; review JUCE’s AGPLv3/commercial licence
|
||
before distributing linked binaries. See [the examples](examples/juce/README.md).
|