# Euterpe Domain — Architecture > **Tags:** `scope:euterpe` · `layer:domain` · `type:lib` --- ## Overview Euterpe is the comprehensive music technology domain for the Oshun ecosystem. Named after the Greek Muse of music and lyric poetry, Euterpe answers a fundamental question every creative platform faces: where does the music intelligence live? Rather than scattering pitch math, audio analysis, AI generation, mastering logic, and voice synthesis across dozens of application teams, Euterpe centralises all of it in a single, well-layered library tier. Any application in the ecosystem — Calliope's AI artist platform, Yemaya's creative studio, Isis's generative factory — can import the same primitives rather than reinventing them. Euterpe is a **library-only domain** — it exposes no standalone services. Most functionality is provided as TypeScript (ESM) packages consumed by higher-level applications and other domains, **alongside a Rust DSP and realtime-audio subsystem** — the `audio-engine` (with the `dsp-core`, `dsp-graph`, and `dsp-wasm` crates), `realtime-engine` (`mrt2-core`, `mrt2-engine`, `mrt2-native`), and `instrument` crates, **62 `.rs` files across 9 `Cargo.toml` manifests** — for the latency-critical signal processing that ESM cannot serve. The domain is organized into distinct functional layers, with a strict bottom-up dependency graph ensuring that primitive abstractions never depend on higher-level concerns. The domain ships **~47 TypeScript packages** under `libs/euterpe/`: the original 34 from TODO Phase 38 sections 38.1–38.34, `@euterpe/ai-scoring` (Phase 70.6), and the **10 packages that earlier revisions listed as planned** — `@euterpe/providers`, `elevenlabs`, `lyria`, `projects`, `workflows`, `api`, `provenance`, `evals`, `ops`, `studio-runtime` (Phase 38.35–38.44) — which are **now implemented with real TypeScript source**. The only still-pending Phase-38 deliverable is the browser DAW application (`apps/euterpe/studio-web`, Phase 38.45), which is so far a placeholder directory (a `.gitignore` only). See `specifications.md` §1 for the full inventory. --- ## Layer Architecture The seven foundational libraries are arranged in four conceptual layers. Each layer builds on the one below it: higher layers may use lower-layer primitives, but lower layers never import higher-layer code. This keeps the foundational libraries lean, universally reusable, and free of circular dependencies. ``` +────────────────────────────────────────────────────────────────────────+ │ PRODUCTION LAYER │ │ │ │ @euterpe/studio @euterpe/master @euterpe/voice │ │ (DAW engine, (mastering chain, (cloning, │ │ timeline, mixer, mix analysis, conversion, │ │ effects, instruments, stem mastering, TTS, singing, │ │ automation, AI) format masters, choir, │ │ AI mix assistant) analysis) │ │ │ │ @euterpe/spatial │ │ (Dolby Atmos, binaural, │ │ ambisonics, VR audio, │ │ AI spatial upmix) │ +────────────────────────────────────────────────────────────────────────+ | +────────────────────────────────────────────────────────────────────────+ │ GENERATION LAYER │ │ │ │ @euterpe/genesis │ │ (text-to-music, stem separation, voice generation, │ │ melody generation, arrangement, inpainting, │ │ style transfer, conditional generation, │ │ quality assessment, model infrastructure) │ +────────────────────────────────────────────────────────────────────────+ | +────────────────────────────────────────────────────────────────────────+ │ THEORY LAYER │ │ │ │ @euterpe/theory │ │ (harmony, counterpoint, melody, progressions, │ │ groove, set theory, orchestration, genre, │ │ ear training, notation) │ +────────────────────────────────────────────────────────────────────────+ | +────────────────────────────────────────────────────────────────────────+ │ CORE LAYER │ │ │ │ @euterpe/core (zero dependencies) │ │ (notes, intervals, scales, chords, rhythm, │ │ keys, form, dynamics, audio, MIDI) │ +────────────────────────────────────────────────────────────────────────+ ``` Beyond these seven foundational libraries, the domain ships an additional 28 implemented libraries at the production and application tier — `virtuoso`, `stage`, `conservatory`, `score`, `collab`, `discover`, `chain`, `synth`, `lyrics`, `iot`, `agents`, `distribution`, `sacred`, `history`, `philosophy`, `acoustics`, `protect`, `video`, `samples`, `restore`, `marketing`, `analytics`, `transcribe`, `accompany`, `guitar`, `access`, `podcast`, and `ai-scoring` — all catalogued in `features.md` and `specifications.md`. --- ## Library Organization ### Layer 1: Core (`@euterpe/core`) The foundation layer with zero runtime dependencies. Every other Euterpe library depends on it (directly or transitively). `@euterpe/core` is suitable for use in any JavaScript environment — browser, Node.js, edge runtime, or WASM host — because it carries no external dependencies. It contains ten sub-modules: | Sub-module | Purpose | | ----------- | ----------------------------------------------------------------------------------- | | `notes` | Pitch classes, notes, tuning systems, frequency/MIDI conversion, microtonal support | | `intervals` | Interval construction, inversion, quality classification | | `scales` | Western scales, modes, ragas, maqamat, Japanese scales, mode rotation | | `chords` | Chord construction, voicings, inversions, chord symbol parsing | | `rhythm` | Time signatures, note durations, tempo, tuplets | | `keys` | Key signatures, relative/parallel keys, key detection, modulation paths | | `form` | Musical form templates (sonata, rondo, binary, ternary, strophic) | | `dynamics` | Dynamic markings, hairpins, articulations, tempo modifiers | | `audio` | Audio buffer management, sample rate conversion, format detection | | `midi` | MIDI message types, 16-channel management, SMF parsing and generation | ### Layer 2: Theory (`@euterpe/theory`) Builds on core to add music intelligence — analysis, rule-checking, and generation grounded in centuries of compositional practice. Ten sub-modules: | Sub-module | Purpose | | --------------- | -------------------------------------------------------------------------------------------------- | | `harmony` | Roman numeral analysis, functional harmony, secondary dominants, borrowed chords, pivot modulation | | `counterpoint` | Species counterpoint rules, voice leading validation, dissonance treatment | | `melody` | Contour analysis, climax detection, motivic patterns, melody generation | | `progressions` | Progression catalog by genre, voice-led generation, functional analysis | | `groove` | Quantization, groove templates, humanization, groove extraction | | `set-theory` | Prime form, normal order, Forte numbers, interval vectors, Z-relations | | `orchestration` | Instrument ranges, transpositions, scoring guidelines, balance analysis | | `genre` | Genre classification and stylistic feature extraction | | `ear-training` | Recognition exercise generation and performance tracking | | `notation` | Notation rendering data, clef/beam/tie/slur logic | ### Layer 3: Generation (`@euterpe/genesis`) AI-powered music creation. Depends on both `core` and `theory`, using theory primitives (scales, progressions, orchestration ranges) to constrain and evaluate the output of neural generative models. Ten sub-modules: | Sub-module | Purpose | | ---------------- | --------------------------------------------------------------------- | | `text-to-music` | Prompt-to-audio generation via diffusion and transformer models | | `stems` | Neural stem separation (vocals, drums, bass, other) | | `voice` | Singing synthesis, vocal style transfer, voice-conditioned generation | | `melody` | Rule-based and neural melody generation | | `arrangement` | Automated arrangement from lead sheets | | `inpainting` | Context-aware audio region infilling | | `style-transfer` | Cross-genre style transformation | | `conditional` | Multi-constraint simultaneous conditioning | | `quality` | Perceptual quality metrics and artifact detection | | `infrastructure` | Model loading, GPU/CPU dispatch, caching, model versioning | ### Layer 4: Production Libraries Four libraries form the production tier, each targeting a distinct professional discipline. `@euterpe/studio`, `@euterpe/master`, and `@euterpe/voice` build conceptually on `core` and `theory`; `@euterpe/studio` also builds on `genesis` for its AI-assisted production features. `@euterpe/spatial` builds on `core` alone, because spatial audio processing is a signal-processing discipline that operates on audio buffers independently of music theory. As noted in Design Pattern 1, this layering is conventional — none of these relationships is a declared `package.json` dependency. #### `@euterpe/studio` (DAW Engine) A full Digital Audio Workstation engine in library form. Ten sub-modules: `daw-engine`, `timeline`, `clip-editing`, `midi-editing`, `mixer`, `effects`, `instruments`, `automation`, `project-management`, `ai-features`. Yemaya embeds this library as its DAW engine. #### `@euterpe/master` (Mastering) Professional audio mastering — the final stage of music production before distribution. Five sub-modules: `mastering-chain`, `mix-analysis`, `stem-mastering`, `format-masters`, `mix-assistant`. Also owns the loudness math for V2 commentary mix ducking (see Cross-Domain Integration Points). #### `@euterpe/spatial` (Spatial Audio) Immersive audio processing for cinema, VR, and broadcast. Five sub-modules: `atmos`, `binaural`, `ambisonics`, `vr-audio`, `spatial-upmix`. #### `@euterpe/voice` (Voice Technology) Voice synthesis and processing across seven sub-modules: `voice-cloning`, `voice-conversion`, `tts`, `text-to-singing`, `vocal-processing`, `choir`, `voice-analysis`. All voice-cloning and conversion operations are consent-gated at the type level (see Design Pattern 5). --- ## Dependency Topology The topology below shows the conceptual layering among the seven foundational libraries. Arrows run from a library toward its dependencies; a higher library uses primitives from a lower one. These are not declared `package.json` dependencies — see Design Pattern 1. ``` @euterpe/core │ ├─── @euterpe/theory ──────────────────────────────────────────┐ │ │ │ │ ├─── @euterpe/genesis ────────────────────────────┐ │ │ │ │ │ │ │ │ └─── @euterpe/studio ◄──────────────────┘ │ │ │ │ │ ├─── @euterpe/master ◄───────────────────────────── │ │ │ │ │ └─── @euterpe/voice ◄────────────────────────────── │ │ │ └─── @euterpe/spatial (core layer only) ◄──────────────────────┘ ``` `@euterpe/spatial` is intentionally isolated from the theory layer. Spatial audio processing is fundamentally a signal-processing discipline that operates on audio buffers — knowing that a chord is a ii7 chord adds nothing to an HRTF convolution. Keeping the theory layer out of `spatial` means the spatial library stays conceptually lightweight and universally applicable, even in contexts (such as game audio or film post-production) where no music theory is present. The remaining 28 implemented libraries (`virtuoso`, `stage`, `conservatory`, `score`, `collab`, `discover`, `chain`, `synth`, `lyrics`, `iot`, `agents`, `distribution`, `sacred`, `history`, `philosophy`, `acoustics`, `protect`, `video`, `samples`, `restore`, `marketing`, `analytics`, `transcribe`, `accompany`, `guitar`, `access`, `podcast`, `ai-scoring`) sit at the production and application tier and build conceptually on the lower layers. --- ## Design Patterns ### 1. Layered Dependency Direction The domain enforces a strict bottom-up layering: a lower layer never imports a higher one. In practice, the libraries do not declare each other in `package.json` — every Euterpe `package.json` carries an empty `dependencies` map and `vitest` as the only dev dependency. Inter-package use, where it occurs, resolves through the monorepo's TypeScript path mappings, and the layering is maintained by convention and by the dependency direction shown in the topology diagram above. ### 2. Sub-module Organization Each library is internally organized into per-feature sub-modules under `src/` (e.g. `core/src/scales`, `theory/src/harmony`), each with its own `types.ts`, implementation file, and spec file. The sub-modules are re-exported through a single barrel — every `package.json` declares one export, `"."`, mapping to `src/index.ts`. Consumers import from the package root, not from per-sub-module paths, which keeps the internal structure freely refactorable. ### 3. Pure Functional Core The core and theory layers are implemented as pure functions and immutable data structures wherever possible. This design supports testability (no side effects to mock), composability (outputs can be fed into subsequent operations without copying), and concurrent use without shared mutable state. ### 4. Infrastructure Abstraction in Genesis The `infrastructure` sub-module in `@euterpe/genesis` abstracts model loading, GPU/CPU dispatch, and batching behind a stable interface. Model backends can therefore be swapped (diffusion → transformer, local → cloud) without changing the API surface of generation functions. The planned `@euterpe/providers` package will own actual provider connectivity on top of this abstraction. ### 5. Consent-Gated Voice Operations Voice cloning and conversion operations require a `ConsentRecord` on the source `VoiceModel`. This is enforced at the type level — operations that modify voice identity will not compile without a consent record, making consent a structural requirement rather than a runtime check. `@euterpe/protect` voice deepfake detection also cross-references `ConsentRecord` to determine whether a detected synthetic voice is authorized. --- ## Technology Stack The following table summarises the technologies used across the Euterpe libraries. | Component | Technology | | --------------- | ----------------------------------------------------------------------- | | Language | TypeScript (ESM, strict mode) | | Runtime | Node.js (primary) / Browser-compatible for core and spatial | | Build | Nx with `@nx/js:tsc` executor | | Testing | Vitest (per-library configs) | | Audio DSP | Web Audio API compatible, custom DSP implementations | | Spatial formats | Dolby Atmos ADM, Ambisonics B-format and HOA | | MIDI | Full MIDI 1.0 protocol, Standard MIDI File (Type 0 and 1) | | AI/ML backends | Diffusion, transformer, GAN-based models via infrastructure abstraction | --- ## Build and Development The commands below assume a working Nx monorepo setup. Because Euterpe has no services to start, development is entirely build-and-test. ```bash # Test a specific library pnpm nx test @euterpe/core # Build all Euterpe libraries pnpm nx run-many --target=build --projects=tag:scope:euterpe # Lint a specific library pnpm nx lint @euterpe/theory # Run all domain tests pnpm nx run-many --target=test --projects=tag:scope:euterpe # Type check without building (Nx worktree conflict avoidance) cd libs/euterpe/core && npx tsc --noEmit ``` --- ## Service Topology Euterpe has no services. There is no database, no HTTP server, no event bus, and no background workers. The domain is a pure library tier. Applications that embed Euterpe libraries (such as Calliope, Isis, or Yemaya) are responsible for their own service infrastructure. Euterpe provides the music intelligence; the host application provides the runtime context, persistence, and network exposure. --- ## Domain Boundaries Understanding what Euterpe does and does not own is essential for engineers routing new features to the right domain. **Euterpe provides:** - All music theory logic, analysis, and generation - All audio DSP, format handling, and MIDI protocol - All spatial audio processing - All voice synthesis and processing **Euterpe does not provide:** - Storage or persistence — the host application owns this; Euterpe data structures live in memory only - Authentication or authorization - HTTP APIs — no REST or GraphQL server; the planned `@euterpe/api` package provides typed contracts that a host application mounts on its own HTTP runtime - Event bus integration — no NATS or message queue - Copyright adjudication — analysis and similarity scoring belong to `@euterpe/protect`; legal determination is delegated to the Themis domain (Music Shield and Universal Originality Shield) --- ## Cross-Domain Integration Points Euterpe functions as a shared music intelligence layer for several other domains. The table below lists each consuming domain, what it consumes, and why the boundary is drawn where it is. | External Domain | Relationship and boundary rationale | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Calliope** | AI artist creation platform; consumes `@euterpe/genesis`, `@euterpe/voice`, `@euterpe/theory`. Calliope owns persona psychology, fandom, and career arc — Euterpe owns the music production. | | **Isis** | Generative factory; uses Euterpe as the music production layer for generated content. Isis owns orchestration pipelines; Euterpe owns every music primitive those pipelines call. | | **Nous** | AI audio intelligence; shares model infrastructure with `@euterpe/genesis`. Nous owns the AI reasoning layer; Euterpe owns the music-specific model abstractions. | | **Themis** | Music Shield and Universal Originality Shield consume `@euterpe/core` note and audio primitives for copyright analysis. Euterpe scores similarity; Themis makes the legal determination. | | **Iris** | Conversational voice platform; consumes `@euterpe/voice` for TTS and voice synthesis. Iris owns conversation state; Euterpe owns voice technology. | | **Yemaya** | Creative Studio; embeds `@euterpe/studio` as its DAW engine. Yemaya owns the product UX and persistence; Euterpe owns the DAW engine logic. | Two V2 game-stack bridge services also consume Euterpe libraries directly: - **`apps/v2/euterpe-commentary-ducking`** — consumes `@euterpe/master` mastering primitives (loudness delta, dB/linear conversion, sidechain envelope math) to lower the `V2.DynamicMusic` bus under the `V2.Commentary` bus. The mastering boundary exists because the loudness math is domain knowledge that belongs in the mastering library, not scattered across bridge code. - **`apps/v2/karaoke-rhythm-combat-bridge`** — consumes `@euterpe/genesis`, `@euterpe/accompany`, and `@euterpe/protect` for procedural backing tracks, adaptive accompaniment, and streamer-safe music swap. V2 owns final scoring thresholds and rollback state; Euterpe owns the music production.