65 lines
4.0 KiB
Markdown
65 lines
4.0 KiB
Markdown
# P0 · hello engine
|
|
|
|
The first phase proves the spine: Rust audio, a session with a journal, a protocol with two transports, and a surface that reacts to the sound. The demo in `reference/demo` is the visual reference; none of its code is used here.
|
|
|
|
## What was built
|
|
|
|
| Area | Deliverable |
|
|
|---|---|
|
|
| Protocol | `zhila-protocol`: JSON messages, five veins, pattern, state, binary meter frame; unit tests |
|
|
| Session | `zhila-core`: engine trait, validation, revisions, journal for tempo/gain, default sixteen-step phrase; tests |
|
|
| Engine | `zhila-engine`: cpal 0.18, 48 kHz stereo, fixed 256-frame buffer where available, 32-voice pool, five vein timbres, phrase clock, per-vein levels, master level; no allocation on the audio path |
|
|
| Daemon | `zhila-daemon`: WebSocket, hello/token/protocol/origin checks, snapshot, results, broadcast events, 30 Hz binary meters, current-thread Tokio, graceful Ctrl-C |
|
|
| Surface | Svelte 5 + Vite: audio-reactive descent, wire log, engine facts, cilia, signal trace, per-vein gain sliders, transport, keyboard |
|
|
| Verification | `cargo test`, `cargo clippy`, `svelte-check`, production build, live wire test, browser smoke + screenshots |
|
|
| Shell | Tauri 2 scaffold in `app`; build blocked by missing system development packages (below) |
|
|
|
|
## Decisions taken in P0
|
|
|
|
- **cpal, not Web Audio.** The browser is a surface; sound is native Rust. The cpal 0.18 API uses a unified `cpal::Error`, `SampleRate = u32`, `Display` for the device name and a by-value `StreamConfig`.
|
|
- **JSON control + binary meters.** Control metadata is small and debuggable; meters are 31-byte frames at 30 Hz.
|
|
- **One daemon, one session.** Loopback + token + origin guard are the P0 security boundary. No production auth yet.
|
|
- **The journal is for project edits.** Play/stop/strike are performance and do not pollute undo.
|
|
- **The surface is a projection.** The server owns state; the UI applies snapshots, results and events. The canvas owns only its visual phase.
|
|
- **Every layer reacts to sound.** The terrain alpha/offset, eye size/glow/rings, city lights, dust, road bands, stone glow, playhead, lane fills, chrome hairlines, cilia, signal trace and master line all read the five vein levels and the master. No decorative animation is independent of the audio.
|
|
|
|
## Tauri blocker
|
|
|
|
`cargo check` in `app/src-tauri` failed on this machine because the GTK/WebKit/dbus development packages are absent and `sudo` needs a password:
|
|
|
|
```
|
|
Package 'dbus-1' was not found
|
|
The system library `dbus-1` required by crate `libdbus-sys` was not found.
|
|
```
|
|
|
|
`pkg-config` also reports missing `webkit2gtk-4.1` and `gtk+-3.0`. The shell is scaffolded, not verified.
|
|
|
|
Install the Fedora development packages (one command, needs your password):
|
|
|
|
```bash
|
|
sudo dnf install dbus-devel webkit2gtk4.1-devel gtk3-devel libappindicator-gtk3-devel \
|
|
librsvg2-devel openssl-devel libsoup3-devel javascriptcoregtk4.1-devel pkgconf-pkg-config
|
|
```
|
|
|
|
Then:
|
|
|
|
```bash
|
|
cargo check --manifest-path app/src-tauri/Cargo.toml
|
|
npm --prefix ui run build
|
|
npm --prefix app run tauri dev # expects the daemon and Vite to be running
|
|
```
|
|
|
|
The Tauri window loads `http://127.0.0.1:5173`; the daemon remains a separate process in P0. Embedding the engine in the Tauri backend is P1 work, after the engine's lifecycle is settled.
|
|
|
|
## P0 exit criteria
|
|
|
|
- A browser surface talks to a Rust daemon over a local protocol: **passed**.
|
|
- Real cpal output with five veins and non-zero meters: **passed** (Default Audio Device, 48 kHz, 256-frame buffer, master peak ~0.45 in the wire test).
|
|
- A session that validates and journals project edits: **passed** (Rust tests).
|
|
- A surface that visibly reacts to the five levels: **passed** (canvas, cilia, trace, gains; screenshots).
|
|
- A Tauri window on Linux: **blocked** by system development packages; the exact command is above.
|
|
|
|
## Next
|
|
|
|
P1: core session and material. Import/record, analysis, cores and faces, a zoomable waveform, a real pattern model, a flat precision view while the descent remains the primary arrangement, and the first journal-backed undo. The plan and cut lines are in `PLAN.md`.
|