xtc/README.md

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.

Table of contents

• Design decisions
• Current status
• Build
• Run
• Using the GUI
• Features
• Documentation
• Diagnostics
• Suggested first agent task
• License

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.

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.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel
ctest --test-dir build --output-on-failure

For quick development, the optional Make wrapper provides the same workflow:

make          # configure and build
make test     # build and run CTest
make gui      # build just the FLTK application
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.

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 for options, focused tests, installation and IDE setup. Phase 108 records the CMake migration.

Run

Run the GUI:

./build/xtc

See the minimal music-making workflow for creating, saving, reopening and playing a project.

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.
• See audio workflow and limits and the sample editor workflows.
• 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.
• 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.
• For Linux installation, routing and CLI options see LINUX.md; for native effects/instruments see NATIVE_API.md.
• The release preset and CMake's dist, test-install, test-release and test-package targets provide release preparation; see 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 for configuration, routing, ownership and recovery.

Features

Audio

• Audio timing, transitions, latency limits and listening previews are described in 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. 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; 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.

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

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 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 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 and the screenshot gallery.
• 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.

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, NATIVE_API.md and 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. Human listening acceptance of the transitions remains pending.

Documentation

For everyday use see USER_MANUAL.md, KNOWN_LIMITATIONS.md and 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 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 you@hanez.org — Core developer and Founder

License

The project is scaffolded under the MIT License; see LICENSE. Review the licenses of any future dependencies before distribution. See also docs/LICENSES.md.