# Euterpe — Systems Deep Dive

> The `libs/euterpe/` area: ~49 Nx libraries that make up Oshun's
> music-and-audio domain — everything from music-theory primitives and a
> pure-Rust DSP engine to AI generation, voice, mastering, distribution, live
> performance, and the compliance runtime around it. This page is the
> entity-catalog view of the area.

## What this area is

Euterpe (the Greek muse of music) is Oshun's music creation and production
platform, decomposed into ~49 independently-built Nx libraries under
`libs/euterpe/`. Almost every package is a TypeScript domain library exporting
provider-agnostic, network-free domain logic from a `src/index.ts` barrel; the
exceptions are the Rust Cargo workspaces — the real-time audio engines
(`audio-engine/crates`, `realtime-engine/crates`) plus the `instrument` plugin
crate (CLAP/VST3) — bridged into the JS world via WebAssembly and napi-rs. The
libraries are large and real — many are 5K–27K lines of source — and organised
by music-domain concern rather than as generic CRUD.

The packages layer roughly from the bottom up. **Foundations** (`@euterpe/core`,
`@euterpe/theory`, `@euterpe/acoustics`, `@euterpe/history`,
`@euterpe/philosophy`, `@euterpe/sacred`) own the musical primitives and the
academic/analytical knowledge. The **DSP engine** (`@euterpe/audio-engine`,
`@euterpe/audio-engine-web`, plus `@euterpe/realtime-engine` /
`@euterpe/realtime-gen` for on-device generative audio) is the real-time signal
floor. On top sit **synthesis and sound** (`@euterpe/synth`, `@euterpe/samples`,
`@euterpe/guitar`), **AI generation** (`@euterpe/genesis`,
`@euterpe/ai-scoring`, `@euterpe/lyria`, `@euterpe/elevenlabs`,
`@euterpe/providers`), and **voice/lyrics/transcription** (`@euterpe/voice`,
`@euterpe/lyrics`, `@euterpe/transcribe`).

Above those are the **authoring surfaces** — the DAW domain logic
(`@euterpe/studio`, `@euterpe/studio-runtime`), orchestration
(`@euterpe/workflows`), collaboration and project persistence
(`@euterpe/collab`, `@euterpe/projects`), live performance (`@euterpe/stage`),
accompaniment (`@euterpe/accompany`), virtual artists (`@euterpe/virtuoso`), and
education (`@euterpe/conservatory`) — and the **post-production** chain
(`@euterpe/master`, `@euterpe/restore`, `@euterpe/spatial`, `@euterpe/score`,
`@euterpe/video`, `@euterpe/podcast`). Finally the **business and platform**
tier handles release and money (`@euterpe/distribution`, `@euterpe/chain`,
`@euterpe/marketing`, `@euterpe/analytics`, `@euterpe/agents`,
`@euterpe/discover`) and the cross-cutting runtime (`@euterpe/api`,
`@euterpe/ops`, `@euterpe/evals`, `@euterpe/provenance`, `@euterpe/protect`,
`@euterpe/access`, `@euterpe/iot`).

A recurring pattern across the AI-facing libraries is the **SOTA sub-module**
(e.g. `frontier-analytics-sota`, `neural-capture-sota`, `stem-separation-sota`,
`runtime-sota`): a namespaced module that captures the state-of-the-art
provider/model surface for that concern, kept separate from the baseline in-repo
logic. Provider integrations are consistently written as **provider-agnostic
domain logic with fail-closed seams** rather than live network clients — the
`realtime-engine` README is explicit that no code path fabricates audio,
returning `not_configured` until a real engine is bridged.

## How it fits the wider system

These libraries are the domain core consumed by the Euterpe applications — most
visibly the DAW web app referenced as `apps/euterpe/studio-web` (the
`@euterpe/studio-runtime` barrel notes the shipped DAW lives there). The Rust
DSP engine (`@euterpe/audio-engine`) compiles to WebAssembly and is driven on
the audio thread by `@euterpe/audio-engine-web`'s AudioWorklet control surface;
the on-device generative engine (`@euterpe/realtime-engine`) is bridged to TS
via `@euterpe/realtime-gen`. `@euterpe/api` is the service/REST/GraphQL/realtime
delivery surface, `@euterpe/ops` the observability/cost runtime, and
`@euterpe/provenance` / `@euterpe/protect` the rights and content-safety
boundary. Within the area the dependency flow is bottom-up: theory and core
primitives feed generation, synthesis, and authoring; those feed mastering,
distribution, and analytics. Walk the "used by" edges on any node to see exact
consumers.

## Entity reference

### @euterpe/access

Accessibility library for music (`libs/euterpe/access/src`): `visual`,
`hearing`, `motor`, and `cognitive` accessibility modules — the inclusive-design
surface for the platform.

### @euterpe/accompany

Accompaniment and practice tools (`libs/euterpe/accompany/src`): `backing-band`
(genre-preset generation), `practice-accomp` (tempo following), `jam-partner`
(call-and-response / style matching), and a neutral `drum-accompaniment` toggle
(provider-native or in-repo fallback).

### @euterpe/acoustics

Acoustics knowledge library (`libs/euterpe/acoustics/src`): `room-acoustics`,
`psychoacoustics`, and `musical-acoustics`. The physical-acoustics counterpart
to the theory libraries.

### @euterpe/agents

Autonomous music-AI workflow agents (`libs/euterpe/agents/src`, ~5K lines):
`release-agent`, `ar-agent` (A&R scout), `mix-agent`, `content-agent`, and
`royalty-agent` (reconciliation/audit). Agent toolkits for music-industry
workflows.

### @euterpe/ai-scoring

Multi-provider AI music generation/scoring orchestration for film and games
(`libs/euterpe/ai-scoring/src`, ~9K lines). A foundation module plus
per-provider adapters (Suno, Udio, AIVA, Google Lyria, …), each with their own
models/job-states/style-profiles and a polling policy — provider-agnostic
generation plans, not live API clients.

### @euterpe/analytics

Music analytics and intelligence (`libs/euterpe/analytics/src`): `streaming`,
`social`, `revenue`, and `market-intel` analytics, plus a
`frontierAnalyticsSota` SOTA module.

### @euterpe/api

Public service surface (`libs/euterpe/api/src`, ~7.5K lines): namespaced
`publicSurface` (REST/GraphQL/gRPC/OpenAPI), `realtimeStreaming`,
`platformIntegration` (webhooks/OAuth/partner), and `clientSdk`. The
API/delivery domain layer for the Euterpe platform.

### @euterpe/audio-engine-web

Browser front-end for the DSP engine (`libs/euterpe/audio-engine-web/src`). The
main-thread `AudioEngine` control surface plus the AudioWorklet processor and
the WASM artifact built from the Rust `audio-engine`; also owns audio encoders
(`encodeWav`/`encodeFlac`/`encodeAiff`/`encodeAlac`, a multi-codec
`encodeCodec`), ADM-BWF/surround-pan helpers, and WASM-SIMD capability
detection. Control is one-way `postMessage`; metering streams back as events.

### @euterpe/audio-engine

The pure-Rust real-time DSP engine (`libs/euterpe/audio-engine/crates`, ~24K
lines), a Cargo workspace of three crates: `dsp-core` (real-time-safe primitives
— PolyBLEP oscillators, ADSR, RBJ biquads, dynamics, delay, reverb, EQ, mixer,
meters, plus chorus/flanger/phaser/saturator/timestretch/FFT), `dsp-graph` (the
block-based node graph: engine/track/clip/effect/tempo-map/arp/SIMD/surround),
and `dsp-wasm` (the `wasm-bindgen` AudioWorklet surface). All three are fully
implemented and unit-tested against known DSP truths (e.g. −3 dB at cutoff); the
README's "next" labels on `dsp-graph`/`dsp-wasm` are stale.

### @euterpe/chain

Blockchain/Web3 music infrastructure (`libs/euterpe/chain/src`): `royalties`,
`nfts`, `fractional` ownership, on-chain `distribution`, `rights-registry`, and
a `royaltyLiquidity` module.

### @euterpe/collab

Collaboration and project management (`libs/euterpe/collab/src`, ~9K lines):
`sync-engine`, `audio-streaming`, `video-conf`, `file-sharing`, `project-mgmt`
(workspaces/members/roles/tasks/milestones/notifications), and `rights-mgmt`.
The barrel carefully de-collides `hasPermission` (file-sharing) vs
`hasProjectPermission` (project-mgmt).

### @euterpe/conservatory

Music-education platform (`libs/euterpe/conservatory/src`, ~10K lines): adaptive
learning, instrument tracks (piano/guitar/vocal/drums), theory curriculum, ear
training, practice tools, plus namespaced `referenceEarTraining` and
`practiceCoachingSota` modules.

### @euterpe/core

Core music primitives (`libs/euterpe/core/src`, ~22K lines): notes/pitch,
intervals, scales/modes/ragas/maqamat, chords/voicings, rhythm, keys/tonality,
form, dynamics, audio buffers/format handling, MIDI, and a neural audio-codec
module (`audio-codec`, SpectroStream/MRT2). The foundational theory+audio layer
the rest of the area builds on.

### @euterpe/discover

Music intelligence and recommendation (`libs/euterpe/discover/src`):
`audio-features` extraction, `semantic-analysis` (genre/mood/energy),
`recommendation` (collaborative/content/hybrid/contextual), `playlist`
generation, and `similarity` (embedding/LSH/multi-modal).

### @euterpe/distribution

Multi-platform release management (`libs/euterpe/distribution/src`):
`dsp-integration`, `distributor`, `metadata`, `analytics-reporting`, and a
`distributionSota` SOTA module. The release-to-DSPs domain layer.

### @euterpe/elevenlabs

ElevenLabs Music SOTA integration (`libs/euterpe/elevenlabs/src`, ~8.5K lines):
namespaced `composeStream`, `inpaintFinetune`, `variantsSections`,
`reliabilitySafety`, and `surfaceCoverage`. Provider-agnostic client-side domain
logic for the Compose/Stream API surface, not a live SDK.

### @euterpe/evals

Quality evaluation, benchmarks, and release gates (`libs/euterpe/evals/src`):
namespaced `goldenSets`, `automatedEval`, `humanEval`, `releaseGates`, and
`providerBenchmarks`. The quality-gate domain for generated audio/structure.

### @euterpe/genesis

AI music-generation engine (`libs/euterpe/genesis/src`, ~26K lines). Namespaced
modules for `textToMusic`, `stems`, `voice`, `melodyGen`, `arrangement`,
`inpainting`, `styleTransfer`, `conditional`, `quality`, `infrastructure`,
`frontier`, and `sfxFoley` — the largest generation library, provider-agnostic
domain logic over generative-music pipelines.

### @euterpe/guitar

Guitar-tone modeling library (`libs/euterpe/guitar/src`): `amp-modeling`,
`pedal-modeling`, `cab-mic` (cabinet/mic IR), `guitar-ai`, and a
`neuralCaptureSota` neural amp-capture SOTA module.

### @euterpe/history

Music-history library (`libs/euterpe/history/src`): era modules
(`ancient-medieval`, `renaissance-baroque`, `classical-romantic`,
`twentieth-century`, `popular-music`) plus `ethnomusicology`. Reference/analysis
knowledge, not runtime signal processing.

### @euterpe/iot

Internet-of-Musical-Things toolkit (`libs/euterpe/iot/src`): `smart-instrument`
(MIDI-over-BLE/OSC/sensor fusion), `gesture-capture`, `smart-studio` hub,
`environmental-music` (weather/time/biometric reactive), and a
`hardwareEcosystemSota` module.

### @euterpe/lyria

Google Lyria + OpenRouter SOTA integration (`libs/euterpe/lyria/src`, ~8.7K
lines): namespaced `openrouterAudio`, `modelRouting`, `promptingAssets`,
`reliabilityGates`, and `proWatermarkRouting`. Provider-agnostic, network-free
Lyria routing/prompting domain logic.

### @euterpe/lyrics

Lyrics generation and analysis (`libs/euterpe/lyrics/src`, ~6.8K lines):
`generation` (theme/mood/genre), plus rhyme/meter analysis (rhyme schemes,
metrical feet, phonemes, singability, rap-flow), refinement, and
rhyme/syllable-preserving translation. The barrel selectively re-exports
rhyme/meter symbols to avoid collisions with `generation`.

### @euterpe/marketing

Music marketing and promotion (`libs/euterpe/marketing/src`): `social-content`,
`tiktok` trend detection, `advertising` campaign management, and `pr-press`
press-kit assembly.

### @euterpe/master

Mastering and mix-analysis suite (`libs/euterpe/master/src`, ~20K lines):
namespaced `masteringChain`, `mixAnalysis`, `stemMastering`, `formatMasters`,
`mixAssistant`, and `frontierMastering`. Real-audio mastering domain logic.

### @euterpe/ops

Observability, reliability, and cost governance (`libs/euterpe/ops/src`):
namespaced `observability` (metrics/logs/traces/SLIs), `reliabilityEngineering`
(SLOs/circuit-breakers/autoscale), `costQuotas`, and `releaseSecurity`. The
platform runtime-governance layer.

### @euterpe/philosophy

Music-in-context library (`libs/euterpe/philosophy/src`, ~2K lines):
`philosophy`, `psychology`, and `society` modules covering philosophy of music,
music psychology, and music's social dimension. Knowledge domain.

### @euterpe/podcast

Podcast/jingle audio library (`libs/euterpe/podcast/src`, ~1.6K lines):
`podcast-music`, `jingle`, and `voice-integration`. One of the smaller packages.

### @euterpe/projects

Project persistence, asset graph, and versioning (`libs/euterpe/projects/src`):
namespaced `domainModel` (music-project model), `storageIndexing`
(content-addressed storage), `versioningLineage` (git-like
versioning/lineage/branching), and `searchDiscovery`.

### @euterpe/protect

Content-protection library (`libs/euterpe/protect/src`): `fingerprinting`,
`ai-detection`, `voice-deepfake` detection, and `plagiarism` detection. Pairs
with `@euterpe/provenance` on the rights/safety boundary.

### @euterpe/provenance

Provenance, rights, and compliance runtime (`libs/euterpe/provenance/src`, ~10K
lines): namespaced `watermarkCapture`, `rightsConsent`, `copyrightSafety`,
`complianceOps`, `providerProofs`, and `musicLaw` (AI-music-law compliance
runtime).

### @euterpe/providers

Provider connectivity and capability intelligence
(`libs/euterpe/providers/src`): namespaced `unifiedContracts`,
`capabilityRouting`, `promptNormalization`, `openrouterControlPlane`, and
`magentaRt`. The unified control plane for routing across external music models.

### @euterpe/realtime-engine

On-device Rust engine for Magenta RealTime 2
(`libs/euterpe/realtime-engine/crates`): `mrt2-core` (frame/token budget math,
device feasibility, 2.4B/230M tier selection, MIDI/text/audio-ref conditioning,
SpectroStream codec descriptor), `mrt2-engine` (real `.safetensors` header
parsing, bundle discovery/validation, feasibility-gated load, fail-closed
inference seam), and `mrt2-native` (napi-rs bridge). Honestly **fail-closed**:
no path returns invented PCM; it reports `not_configured` until the official
MLX/`magenta-rt` engine is bridged.

### @euterpe/realtime-gen

TypeScript runtime seam for the MRT2 engine above
(`libs/euterpe/realtime-gen/src`, ~780 lines). Owns the runtime +
generation-source interfaces (`runtime/types`), the fail-closed native loader
(`loadMrt2Native`, `candidatePaths`), the device-feasibility tier gate
(`selectTier`, `MACBOOK_AIR_16GB`, MRT2 param constants), and the session that
drives the engine as a realtime source. Thin by design — the seam, not the
model.

### @euterpe/restore

Audio restoration and enhancement (`libs/euterpe/restore/src`):
`noise-reduction` (spectral subtraction/Wiener/gate/hum), `enhancement`
(bandwidth extension/bass/ stereo widening), `vintage-restore` (vinyl/tape/78
RPM EQ), `ai-remaster`, and a `frontierRestorationSota` module.

### @euterpe/sacred

Sacred music and sound-healing library (`libs/euterpe/sacred/src`):
`frequencies`, `traditions`, `sound-healing`, `ceremonial`, plus a
`wellnessSoundscapeSota` SOTA module.

### @euterpe/samples

Sample and beat library (`libs/euterpe/samples/src`): `sample-gen`, `beat-gen`,
`sample-search`, `sample-market`, and a `stemSeparationSota` SOTA module.

### @euterpe/score

Music scoring, audio middleware, and video analysis (`libs/euterpe/score/src`,
~12K lines): namespaced `videoAnalysis` (SMPTE timecode/scene-detection/hit
points), `adaptiveMusic` (vertical layering/horizontal resequencing), `fmod`,
`wwise`, `filmScoring`, `proceduralAudio`, and `middlewareInteropSota`.
Game/film audio integration.

### @euterpe/spatial

Immersive/spatial audio platform (`libs/euterpe/spatial/src`, ~16.6K lines):
namespaced `atmos` (Dolby Atmos), `binaural`, `ambisonics`, `vrAudio`, and
`spatialUpmix` (AI upmixing). Substantial spatial-DSP domain logic.

### @euterpe/stage

Live performance and events engine (`libs/euterpe/stage/src`, ~11.7K lines):
`real-time-audio`, DJ tools (decks/crossfader/beatmatch/harmonic-mix, with
collision-aliased exports), virtual concerts, and interactive shows. The barrel
is large (~200 lines) due to careful symbol de-collision.

### @euterpe/studio-runtime

Section/lyrics/arrangement editors (`libs/euterpe/studio-runtime/src`, ~2K
lines). Currently exports only `sectionLyricsEditors`
(verse/chorus/energy-curve/ density-grid/transition-designer +
lyric/vocal-arrangement editor); the barrel documents that the other former
runtime surfaces were **removed 2026-06-09** as superseded by the shipped DAW,
`@euterpe/workflows`, `@euterpe/master`/ `distribution`, and
`@euterpe/ops`/`evals`. Retained to be wired into the DAW.

### @euterpe/studio

DAW domain engine (`libs/euterpe/studio/src`, ~24K lines): namespaced
`dawEngine`, `clipEditing`, `mixer`, `effects`, `instruments`, `automation`,
`projectManagement`, `aiFeatures`, `clipHygiene`, `runtimeSota`, and
`generatorTrack`. The core DAW logic behind `apps/euterpe/studio-web`.

### @euterpe/synth

Synthesizer and sound-design library (`libs/euterpe/synth/src`): `neural-synth`,
`traditional-synth` (subtractive/FM/wavetable/granular), `sample-manipulation`
(time-stretch/pitch-shift/slice), `preset-intelligence`, and a `neuralAudioSota`
SOTA module.

### @euterpe/theory

Music-theory intelligence engine (`libs/euterpe/theory/src`, ~27K lines).
Namespaced modules for `harmony`, `counterpoint`, `melody`, `progressions`,
`groove`, `setTheory`, `orchestration`, `genre`, `earTraining`, and `notation` —
deep structural analysis on top of `@euterpe/core`'s primitives.

### @euterpe/transcribe

Audio-to-notation transcription engine (`libs/euterpe/transcribe/src`):
`audio-to-midi` (pitch/onset-offset/velocity/polyphony), `audio-to-score`
(notation values/key/time-sig/dynamics), `instrument-specific` (guitar
tab/piano/ drums/bass/vocal), and `transcription-edit` (edit/undo/export/diff).

### @euterpe/video

Video production and audio-visual integration (`libs/euterpe/video/src`, ~5.7K
lines): `beat-sync` editing, AI video generation (namespaced/collision-aliased
exports — styles/camera/composition/render configs), lyric-video creation with
subtitle export, and audio-reactive visuals.

### @euterpe/virtuoso

AI virtual-artists platform (`libs/euterpe/virtuoso/src`, ~19.6K lines):
`artist-identity`, `content-generation`, `avatar-system`, `social-engagement`,
`performance`/touring, and `business`/revenue. Creates and manages autonomous AI
musicians; the barrel aliases the duplicate `RevenueSplit` types.

### @euterpe/voice

Voice processing suite (`libs/euterpe/voice/src`, ~25K lines): namespaced
`voiceCloning`, `voiceConversion`, `tts`, `textToSinging`, `vocalProcessing`,
`choir`, `voiceAnalysis`, `frontierVoice`, and `vocalCoaching`. One of the
largest packages.

### @euterpe/workflows

Generation orchestration and editing runtime (`libs/euterpe/workflows/src`):
namespaced `asyncJobEngine`, `ideaToSong` (workflow templates),
`editingIteration`, and `collaborativeAgentic`. The job/orchestration layer that
drives generation end-to-end. </content>

### @euterpe/training-data

Phase 85–86 flywheel producer for the music domain
(`libs/euterpe/training-data/src`): `EuterpeTrainingDataPipeline` normalizes
thirteen `EuterpeTrainingKind` signals — `music-preference`, `audio-generation`,
`audio-mastering`, `spatial-audio`, `payment-behavior`, `consent-safety`, and
peers — into typed `EuterpeTrainingRecord`s carrying `consentState`/`anonymized`
fields, and emits them through a pluggable `EuterpeTrainingSink`; storage and
model training live in Nous, not here.