ZHILA

Sound is terrain. A sampling instrument where 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 P1a: the engine, the wire, the descent, and the material room. A found sound can be imported, decoded and cut into sixteen faces, struck on its own, or laid on a vein and heard in the loop. The visual demo in reference/demo remains a design reference, not the codebase. The roadmap is in docs/PLAN.md.

What is real

Rust engine. cpal output at 48 kHz, five veins, a sixteen-step phrase, a fixed voice pool, per-vein levels and gains, a bar clock. Procedural voices for empty pattern rows; real sample voices for rows with a face. No Web Audio.
Material. Import through the local wire; symphonia decodes WAV/FLAC/MP3/OGG; onset analysis finds seams and cuts sixteen faces with RMS, rank and waveform peaks; the archive keeps the mono f32 samples. The sample rate is preserved and the engine handles the playback ratio.
Quarry. Import, core strip, zoomed waveform with face boundaries, sixteen-face wall, face audition, seal and stats; assign a face to a pattern row; edit the sixteen steps; strike a face; all against the live session.
Protocol v1. JSON control frames, a 31-byte binary meter frame, and a binary import path (an import header followed by the audio bytes). Snapshot, results, events, token and origin guard.
Session + journal. Validation, revisions, a journal for project edits (tempo, gains, pattern faces and steps); play, stop and strikes are performance, not history.
Surface. A Svelte 5 descent whose terrain, eye, city, road, stones and playhead react to the five levels and the master; a real wire log; engine facts; cilia; a master signal trace; vein gains; transport; keyboard.
Verification. Rust unit tests, a live wire test, a material import test, a browser quarry test and the P0 regression smoke, plus svelte-check and 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 path.

Quick start

Requirements: Rust (tested on 1.99), Node 22, ALSA. The daemon uses the default output device; without one 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 the two halves separately:

cargo run -p zhila-daemon -- --port 4317
npm --prefix ui run dev

Try the material loop

Open quarry in the top rail.
take a core and choose a WAV (a short field recording works; the fixture fixtures/clicks-01.wav is one).
The file is decoded, the seams are found and sixteen faces are cut. Click a face, then lay on bass.
space plays the loop; the bass row now triggers the sample while the other veins keep their procedural voices. Edit steps in the pattern; each edit goes to the engine and the journal.
Go back to nave to see the pattern on the road and the levels in the room.

Controls: space play/stop · s strike the selected face in the quarry or the selected vein in the nave · 1–5 select a vein (nave) or a pattern row (quarry) · click a face to select, double-click to strike · tempo − / +.

The daemon prints the audio device, rate, buffer 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.

Layout

crates/zhila-protocol   wire types, binary meter frame, cores/faces, tests
crates/zhila-core       session, journal, material snapshot, engine trait
crates/zhila-engine     cpal stream, procedural + sample voices, levels
crates/zhila-material   decode, onset analysis, sixteen faces, peaks
crates/zhila-daemon     WebSocket daemon, auth, binary import
ui                      Svelte 5 surface: descent + quarry
fixtures                a small click track for the smoke tests
app                     Tauri 2 shell (scaffolded; system deps missing)
docs                    plan, protocol, P0/P1 notes
reference/demo          the earlier design demo

Tests

./scripts/check.sh                    # fmt, clippy, cargo tests, svelte-check, build
node scripts/wire-smoke.mjs           # daemon running
node scripts/material-smoke.mjs       # daemon running: import, face, play
npm --prefix ui run smoke             # daemon + Vite: P0 regression, screenshots
npm --prefix ui run quarry-smoke      # daemon + Vite: import, assign, play, screenshots

npm --prefix ui run smoke writes preview-p0*.png; quarry-smoke writes preview-p1-*.png.

P1a limits (next, not hidden)

The archive is in memory. There is no save/load yet; a daemon restart loses imported cores and pattern edits. Persistence is the next slice.
No recording, no waveform trimming, no manual cut/loop points; the sixteen faces are automatic seams.
No undo/redo for pattern edits yet; the journal records them, the surface does not expose history.
One fixed two-bar phrase and five veins; pattern rows are veins, one face per row, no per-step face or pitch.
Formats depend on symphonia; WAV is the tested path. AIFF, multi-channel files and very long files are not specifically handled.
No agent/MCP in this phase.
The Tauri shell is not verified; see the blocker.

The next slice is P1b: a project file and SQLite journal, an asset archive, autosave and reload, undo for pattern edits, recording, and waveform trimming. Then the arrangement and the agent. The plan is in docs/PLAN.md; the P1a notes are in docs/P1.md.

5.9 KiB Raw Blame History Unescape Escape