hanez/xtc
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
xtc/README.md

7 KiB
Raw Blame History

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 gain/pan/mute/solo, output 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: a C compiler, a C++ compiler, GNU Make, and pkg-config. FLTK is optional for the core and tests.

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 for the inspected toolchain and baseline limits.

Build the optional FLTK GUI if FLTK is installed:

make gui

Run the GUI:

./build/xtc

See the minimal music-making workflow 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 (Ctrl+4) 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. 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. make release, make dist, make test-install and make test-release provide release preparation; see 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 for configuration, routing, ownership and recovery.

Clean generated files:

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. Human listening acceptance for the Phase 12 transitions remains pending.

Phases 13–15 add 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.

For everyday use see USER_MANUAL.md, KNOWN_LIMITATIONS.md and MAINTENANCE.md. xtc-check --diagnose reports build features; make test-package checks a local system-linked Linux binary archive. Phases 16–20 add effect automation/controllers, editing commands, v7 project-folder media paths, performance baselines and release/installation checks.

Phase 22 adds non-destructive audio splitting, clip gain/fades and cached timeline waveforms, with undo and v8 persistence (reading v1–v7). See AUDIO_FILES.md. make test-audio-editing checks source preservation and exact boundary output. Time stretching and independent pitch shifting remain deferred.