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 as a design reference — not as the codebase. The roadmap is in docs/PLAN.md.
What is real in P0
- Rust engine.
cpaloutput 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, 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. 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.
./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:
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
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.