Eve library

Euterpe-studio-web — Systems Deep Dive

Guide

Revision 1

On this page

The shipping browser-delivered DAW: a Next.js (App Router) + React product shell, a desktop Tauri wrapper, and ~135 framework-free DAW domain modules that drive the Rust/WASM real-time audio engine.

What this area is#

apps/euterpe/studio-web/ is a single Nx application — project name @euterpe/studio-web — that ships Euterpe Studio, the browser-delivered digital audio workstation. It is the product front end for the whole Euterpe domain: the place where a user actually arranges, synthesizes, mixes, masters, and exports music. It is delivered three ways from one codebase — as a Next.js web app, as an installable PWA (public/sw.js, public/manifest.webmanifest), and as a native desktop binary via the Tauri v2 shell under src-tauri/.

The app is deliberately split into two layers. The framework-free product runtime lives under src/ and is pure deterministic TypeScript with no React/Next imports: src/index.ts re-exports four product modules — shell-runtime, identity-billing, telemetry-launch, and realtime-mrt2 — plus the large src/daw/ directory of ~135 DAW domain modules (synthesis, mixing, mastering, notation, MIDI/MPE/MIDI2, audio analysis, watermarking, C2PA provenance, project I/O, and interchange formats such as DAWproject, FCPXML, and SMF). The framework binding layer lives under app/ (the App Router routes) and src/components/daw/ (57 React panels: channel strips, piano roll, drum rack, arrangement view, mixer buses, mastering, and so on) — thin views that render the deterministic logic and own the actual browser APIs (WebAudio, WebMIDI, WebGPU, OPFS). This separation is why nearly every module ships with a .spec.ts next to it: the logic is unit-testable without a DOM.

The DSP itself is not here — it is the Rust/WASM real-time engine @euterpe/audio-engine-web, consumed as a workspace dependency. The /daw route's DawApp client component drives that engine through the unit-tested DAW session reducer (src/daw/daw-session.ts). The engine worklet + .wasm are served from /audio, synced into public/audio by scripts/sync-engine-assets.mjs on predev/prebuild — a stale-aware gate that rebuilds the worklet when the engine source hash changed so a Rust edit can't silently ship last build's DSP.

How the app is shaped#

The App Router surface (app/) is intentionally thin:

  • app/page.tsx — the studio home, whose panel visibility is computed by the framework-agnostic resolveLayout from shell-runtime.
  • app/daw/page.tsx — the DAW route; a LocaleProvider wrapping the DawApp client component, which wires @euterpe/audio-engine-web's AudioEngine to the session reducer and the full panel set.
  • app/realtime/page.tsx — the Magenta RealTime 2 panel; a thin WebSocket / WebAudio / WebMIDI binding over the deterministic realtime-mrt2 controller.
  • app/api/copilot/route.ts — a same-origin Node route that translates a natural-language instruction into validated DawActions via the Anthropic Messages API (tool use), fail-closed (503 copilot_not_configured with no key) and always re-validated server-side by validateActions.

The four src/ product modules are large, pure, and self-documenting (numbered against an internal 38.45.x spec): shell-runtime.ts (~1009 LOC) owns route registry/resolution, the DAW-engine handshake, timeline renderer math (viewport culling / LOD / frame budget), service-worker cache + OPFS layout, PWA install eligibility, the Tauri menu model, the responsive layout resolver, keyboard-shortcut sets, the MIDI/audio permission state machine, and crash-safe autosave. identity-billing.ts (~973 LOC) and telemetry-launch.ts (~1017 LOC) cover the account lifecycle and the launch-readiness surface respectively.

How it fits the wider system#

This app sits at the very top of the Euterpe stack: it is a leaf consumer, not a dependency of anything else. Its package.json declares workspace:* dependencies on the Euterpe engine and content libraries — @euterpe/studio, @euterpe/projects, @euterpe/studio-runtime, @euterpe/audio-engine-web, @euterpe/core, @euterpe/master, @euterpe/transcribe, @euterpe/genesis, and @euterpe/lyrics — and composes them into a shippable product. The real-time generation panel talks to the Oshun BFF over a WebSocket (/v1/generation/realtime) using the BFF's generation-control envelope contract; the copilot route talks to Anthropic. Both integrations fail closed and honestly report "not configured" rather than fabricating a stream or an action. The Tauri shell adds the native capabilities a sandboxed browser cannot (folder-wide stem export, arbitrary project-file read/write for the .eup association, reveal-in-file-manager) and serves the COOP/COEP cross-origin-isolation headers the threaded audio worklet's SharedArrayBuffer requires.

Entity reference#

@euterpe/studio-web#

The Euterpe Studio DAW application — the single Nx project in this area (apps/euterpe/studio-web/, projectType: "application", tags scope:euterpe / layer:app / type:app). It is a fully implemented product, not a scaffold: a Next.js App Router web app (app/) over a deterministic, extensively unit-tested product runtime (src/). The barrel src/index.ts exposes four framework-free modules — shellRuntime (route registry, engine handshake, timeline math, SW/OPFS, PWA, Tauri menu, layout, shortcuts, permission state machine, autosave; src/shell-runtime/shell-runtime.ts), identityBilling (onboarding, WebAuthn auth, tier gating, billing/proration, entitlements, tax/VAT, referrals/seats, legal gates, team provisioning), telemetryLaunch (consent-gated analytics, bug-report bundles, feature-flag rollout with consistent-hash bucketing, TF-IDF/BM25 help search, A/B two-proportion testing, SLO aggregation, artifact promotion, the staged launch playbook), and realtimeMrt2 (a pure WS session controller for the Magenta RealTime 2 generation stream). The bulk of the DAW lives in src/daw/ (~135 domain modules driving @euterpe/audio-engine-web, the Rust/WASM real-time engine, via the daw-session.ts reducer) rendered by 57 React panels under src/components/daw/. Native desktop delivery is the Tauri v2 shell in src-tauri/ (Rust commands save_project / load_project / export_stems / reveal_in_file_manager, with path-safe logic factored into the unit-tested euterpe-desktop-core crate; the src-tauri/README.md records an on-box cargo check of the full tauri 2.11 tree). External integrations — the /api/copilot Anthropic tool-use route and the BFF realtime WebSocket — are fail-closed: with no credentials they return 503 / show "not configured" rather than fabricating output.