78 lines
4.1 KiB
Markdown
78 lines
4.1 KiB
Markdown
# ZHILA
|
||
|
||
Sound is terrain. A sampling instrument where the material is cut in a quarry, laid as stones in a nave, and played by a hand or an agent through the same verbs.
|
||
|
||
This repository is **P0**: the engine, the wire, and the first descent surface. The visual demo lives in [`reference/demo`](reference/demo) as a design reference — not as the codebase. The roadmap is in [`docs/PLAN.md`](docs/PLAN.md).
|
||
|
||
|
||
|
||
## What is real in P0
|
||
|
||
- **Rust engine.** `cpal` output stream, 48 kHz, five veins, a sixteen-step phrase, a fixed voice pool, per-vein gains and levels, a bar clock. No Web Audio.
|
||
- **Protocol v1.** JSON control frames and a 31-byte binary meter frame over a local WebSocket.
|
||
- **Session + journal.** Validation, revisions, a journal for project edits (tempo, gains), performance events that are not history.
|
||
- **Daemon.** Loopback-only, token in the hello, origin guard, snapshot on connect, results and events, binary meters at 30 Hz.
|
||
- **Surface.** A Svelte 5 descent whose terrain, eye, city, road, stones and playhead react to the five vein levels and the master; a real wire log; engine facts; cilia; a master signal trace; vein gain sliders; transport; keyboard control.
|
||
- **Verification.** Rust unit tests, a wire smoke test against live audio, a browser smoke test with screenshots, `svelte-check`, a production build.
|
||
|
||
The Tauri 2 shell is scaffolded in [`app`](app), but **it has not been built on this machine**: the system is missing the GTK/WebKit/dbus development packages and `sudo` requires a password. The exact blocker and the install command are in [`docs/P0.md`](docs/P0.md). The browser surface is the working P0 path.
|
||
|
||
## Quick start
|
||
|
||
Requirements: Rust (tested on 1.99), Node 22, ALSA (present on this machine). The daemon uses the default output device; if there is none it reports offline and the surface still connects.
|
||
|
||
```bash
|
||
./scripts/dev.sh
|
||
```
|
||
|
||
Open **http://127.0.0.1:5173**. The daemon listens on `ws://127.0.0.1:4317` with the development token `dev`.
|
||
|
||
Or run the two halves separately:
|
||
|
||
```bash
|
||
cargo run -p zhila-daemon -- --port 4317
|
||
npm --prefix ui run dev
|
||
```
|
||
|
||
Controls: `space` play/stop · `s` strike the selected vein · `1`–`5` select a vein · click a lane label to select; double-click to strike · tempo `−` / `+`.
|
||
|
||
The daemon prints the audio device, rate, buffer, sample format and session id. Use `--no-audio` for UI/protocol tests, `--port` to change the port, and `ZHILA_TOKEN` or `--token` to change the dev token. The surface reads `VITE_ZHILA_WS` and `VITE_ZHILA_TOKEN` at build time; both default to the values above.
|
||
|
||
## Layout
|
||
|
||
```
|
||
crates/zhila-protocol wire types, binary meter frame, tests
|
||
crates/zhila-core session, journal, validation, engine trait
|
||
crates/zhila-engine cpal stream, voices, phrase, levels
|
||
crates/zhila-daemon WebSocket daemon, auth, broadcast
|
||
ui Svelte 5 surface (browser-first)
|
||
ui/src/lib/descent.ts the reactive canvas
|
||
app Tauri 2 shell (scaffolded, system deps missing)
|
||
docs plan, protocol, P0 notes
|
||
reference/demo the earlier design demo
|
||
```
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
cargo test --workspace
|
||
cargo clippy --workspace --all-targets -- -D warnings
|
||
npm --prefix ui run check
|
||
npm --prefix ui run build
|
||
node scripts/wire-smoke.mjs # daemon running
|
||
npm --prefix ui run smoke # daemon + vite dev running
|
||
```
|
||
|
||
`npm --prefix ui run smoke` writes `preview-p0.png` and `preview-p0-playing.png` and asserts the wire, the pattern, the cilia and the live levels.
|
||
|
||
## P0 limits (next, not hidden)
|
||
|
||
- One fixed phrase; patterns are not editable in the surface yet.
|
||
- Five veins are fixed; the engine has per-vein gain, no sends or automation.
|
||
- The surface is read-only except transport, strike, tempo and gains.
|
||
- No session persistence, project file or archive yet.
|
||
- No agent and no MCP in this phase; the command bus and the journal are the ground for them.
|
||
- The Tauri shell is not verified; see the blocker.
|
||
|
||
P1 is the core session and the material room: import/record, analysis, cores and faces, a zoomable waveform and a real pattern model. The plan is in [`docs/PLAN.md`](docs/PLAN.md).
|