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.

## 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, gain, meter and output nodes;
- C tests for deterministic rendering, routing, validation and lifecycle;
- an optional JACK-compatible mono backend 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;
- architecture, format, GUI, roadmap, and decision documents.

The JACK backend has passed software-loopback testing; physical-device playback
is unverified. Recording, MIDI, plugin hosting, project persistence, and the
actual sequencer UI are not implemented yet.

## 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
```

The GUI opens JACK and offers Play/Stop/Reconnect, backend status and view
switching. Play starts the engine in silence; playback content and editors are
not implemented. 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. See [GUI documentation](docs/GUI.md).
With JACK development files and an existing JACK-compatible server, run the
isolated software-loopback test with `make test-jack`. 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.