# Euterpe Domain — Technical Specifications

> **Tags:** `scope:euterpe` · `layer:domain` · `type:lib`

Euterpe is the music creation and production domain for the Oshun monorepo. It
is a **library-only domain** — no applications, no services, no database, no
HTTP server. Every capability ships as a TypeScript (ESM) package under
`libs/euterpe/*` and is consumed by higher-level domains.

This specification documents the **type-level contracts** of the implemented
libraries — the exact TypeScript types, enums, and interfaces that callers
depend on. For a human-readable explanation of what each library does, see
`features.md`. For the layer architecture and dependency topology, see
`architecture.md`.

Where a package is part of the Phase 38 backlog but not yet built, it is
labelled `(planned)` and described from the phase document rather than from
source.

---

## 1. Library Inventory

### 1.1 Implemented libraries (35)

All 35 directories below contain a real `src/` tree with per-module
implementations and Vitest specs. Thirty-four trace to TODO Phase 38 sections
38.1–38.34; `@euterpe/ai-scoring` traces to Phase 70.6.

| Package                 | Path                        | Sub-modules under `src/`                                                                                                   |
| ----------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `@euterpe/core`         | `libs/euterpe/core`         | notes, intervals, scales, chords, rhythm, keys, form, dynamics, audio, midi                                                |
| `@euterpe/theory`       | `libs/euterpe/theory`       | harmony, counterpoint, melody, progressions, groove, set-theory, orchestration, genre, ear-training, notation              |
| `@euterpe/genesis`      | `libs/euterpe/genesis`      | text-to-music, stems, voice, melody-gen, arrangement, inpainting, style-transfer, conditional, quality, infrastructure     |
| `@euterpe/studio`       | `libs/euterpe/studio`       | daw-engine, timeline, clip-editing, midi-editing, mixer, effects, instruments, automation, project-management, ai-features |
| `@euterpe/master`       | `libs/euterpe/master`       | mastering-chain, mix-analysis, stem-mastering, format-masters, mix-assistant                                               |
| `@euterpe/spatial`      | `libs/euterpe/spatial`      | atmos, binaural, ambisonics, vr-audio, spatial-upmix                                                                       |
| `@euterpe/voice`        | `libs/euterpe/voice`        | voice-cloning, voice-conversion, tts, text-to-singing, vocal-processing, choir, voice-analysis                             |
| `@euterpe/virtuoso`     | `libs/euterpe/virtuoso`     | artist-identity, content-generation, avatar-system, social-engagement, performance, business                               |
| `@euterpe/stage`        | `libs/euterpe/stage`        | real-time-audio, dj-tools, virtual-concert, crowd-interaction, lighting-visuals                                            |
| `@euterpe/conservatory` | `libs/euterpe/conservatory` | adaptive-learning, piano, guitar, vocal, drums, theory-curriculum, ear-training, practice-tools                            |
| `@euterpe/score`        | `libs/euterpe/score`        | video-analysis, film-scoring, adaptive-music, procedural-audio, fmod, wwise                                                |
| `@euterpe/collab`       | `libs/euterpe/collab`       | audio-streaming, sync-engine, project-mgmt, rights-mgmt, video-conf, file-sharing                                          |
| `@euterpe/discover`     | `libs/euterpe/discover`     | audio-features, semantic-analysis, similarity, recommendation, playlist                                                    |
| `@euterpe/chain`        | `libs/euterpe/chain`        | royalties, nfts, fractional, distribution, rights-registry                                                                 |
| `@euterpe/synth`        | `libs/euterpe/synth`        | traditional-synth, neural-synth, sample-manipulation, preset-intelligence                                                  |
| `@euterpe/lyrics`       | `libs/euterpe/lyrics`       | generation, rhyme-meter, refinement, translation                                                                           |
| `@euterpe/iot`          | `libs/euterpe/iot`          | smart-instrument, gesture-capture, smart-studio, environmental-music                                                       |
| `@euterpe/agents`       | `libs/euterpe/agents`       | release-agent, ar-agent, mix-agent, content-agent, royalty-agent                                                           |
| `@euterpe/distribution` | `libs/euterpe/distribution` | dsp-integration, distributor, metadata, analytics-reporting                                                                |
| `@euterpe/sacred`       | `libs/euterpe/sacred`       | traditions, sound-healing, frequencies, ceremonial                                                                         |
| `@euterpe/history`      | `libs/euterpe/history`      | ancient-medieval, renaissance-baroque, classical-romantic, twentieth-century, popular-music, ethnomusicology               |
| `@euterpe/philosophy`   | `libs/euterpe/philosophy`   | philosophy, psychology, society                                                                                            |
| `@euterpe/acoustics`    | `libs/euterpe/acoustics`    | room-acoustics, psychoacoustics, musical-acoustics                                                                         |
| `@euterpe/protect`      | `libs/euterpe/protect`      | fingerprinting, ai-detection, voice-deepfake, plagiarism                                                                   |
| `@euterpe/video`        | `libs/euterpe/video`        | beat-sync, ai-video, lyric-video, audio-reactive                                                                           |
| `@euterpe/samples`      | `libs/euterpe/samples`      | sample-gen, beat-gen, sample-search, sample-market                                                                         |
| `@euterpe/restore`      | `libs/euterpe/restore`      | noise-reduction, enhancement, vintage-restore, ai-remaster                                                                 |
| `@euterpe/marketing`    | `libs/euterpe/marketing`    | social-content, tiktok, advertising, pr-press                                                                              |
| `@euterpe/analytics`    | `libs/euterpe/analytics`    | streaming, social, revenue, market-intel                                                                                   |
| `@euterpe/transcribe`   | `libs/euterpe/transcribe`   | audio-to-midi, audio-to-score, instrument-specific, transcription-edit                                                     |
| `@euterpe/accompany`    | `libs/euterpe/accompany`    | backing-band, practice-accomp, jam-partner                                                                                 |
| `@euterpe/guitar`       | `libs/euterpe/guitar`       | amp-modeling, pedal-modeling, cab-mic, guitar-ai                                                                           |
| `@euterpe/access`       | `libs/euterpe/access`       | visual, hearing, motor, cognitive                                                                                          |
| `@euterpe/podcast`      | `libs/euterpe/podcast`      | podcast-music, jingle, voice-integration                                                                                   |
| `@euterpe/ai-scoring`   | `libs/euterpe/ai-scoring`   | flat `lib/` tree: provider adapters (Suno, Udio, AIVA, Boomy, Google Lyria), routing, scoring, sync                        |

### 1.2 Planned libraries (10) — Phase 38.35–38.44

These appear in TODO Phase 38 but have **no directory** under `libs/euterpe/`
and no source. Their Phase 38 task blocks are entirely unchecked.

| Package                   | Phase | Scope                                             |
| ------------------------- | ----- | ------------------------------------------------- |
| `@euterpe/providers`      | 38.35 | Provider connectivity and capability intelligence |
| `@euterpe/elevenlabs`     | 38.36 | ElevenLabs music/voice SOTA integration           |
| `@euterpe/lyria`          | 38.37 | Google Lyria + OpenRouter SOTA integration        |
| `@euterpe/projects`       | 38.38 | Project persistence, asset graph, versioning      |
| `@euterpe/workflows`      | 38.39 | Generation orchestration and editing runtime      |
| `@euterpe/api`            | 38.40 | Service layer, contracts, realtime delivery       |
| `@euterpe/provenance`     | 38.41 | Provenance, rights, compliance runtime            |
| `@euterpe/evals`          | 38.42 | Quality evaluation, benchmarks, release gates     |
| `@euterpe/ops`            | 38.43 | Observability, reliability, cost governance       |
| `@euterpe/studio-runtime` | 38.44 | Product experience and directed SOTA workflows    |

A browser DAW application (`apps/euterpe/studio-web`, Phase 38.45) is also
planned and has no app directory.

### 1.3 Project configuration

Every implemented package shares the same structural configuration. This
consistency is intentional — it means any engineer can navigate from package to
package without re-learning the build setup.

Every implemented package is an Nx library tagged
`["scope:euterpe", "layer:domain", "type:lib"]`, built with the `@nx/js:tsc`
executor, linted with `@nx/eslint:lint`, and tested with `@nx/vite:test`. Each
`package.json` declares `"type": "module"`, version `0.1.0`, `private: true`, an
empty `dependencies` map, and `vitest` from the pnpm catalog as the only dev
dependency. Inter-package code reuse happens via the workspace path mappings,
not via declared `dependencies`.

---

## 2. `@euterpe/core` — Music Primitives

The foundation layer on which all other Euterpe libraries depend. Ten
sub-modules, each with a `types.ts`, an implementation file, and a spec file.
All types are immutable (`readonly` throughout) to support concurrent use and
pure-functional composition. The sections below document the key types exported
by each sub-module; use these as the canonical reference when writing code that
works with music primitives.

### 2.1 Notes and pitch (`notes`)

This sub-module defines the two core pitch representations — `PitchClass` (an
octave-independent tone) and `Note` (a fully specified pitch with octave, MIDI
number, and frequency) — plus tuning systems, microtonal offsets, and the six
notation systems Euterpe supports. Every higher-level type builds on these
primitives.

**`PitchClass`** — one of 12 chromatic tones, octave-independent:

| Field        | Type         | Meaning                                                       |
| ------------ | ------------ | ------------------------------------------------------------- |
| `semitone`   | `number`     | 0–11, C = 0                                                   |
| `name`       | `NoteName`   | Display name including accidentals                            |
| `letter`     | `LetterName` | Base letter `A`–`G`                                           |
| `accidental` | `Accidental` | `natural` / `sharp` / `flat` / `double-sharp` / `double-flat` |

**`Note`** — fully specified note:

| Field        | Type         | Meaning                                |
| ------------ | ------------ | -------------------------------------- |
| `pitchClass` | `PitchClass` | The pitch class                        |
| `octave`     | `number`     | Scientific pitch octave, −1 to 10      |
| `midi`       | `number`     | MIDI note number, 0–127 (extensible)   |
| `frequency`  | `number`     | Frequency in Hz at the current tuning  |
| `cents`      | `number`     | Cents deviation from equal temperament |

**`TuningSystem`** — `name`, `referenceFrequency` (Hz for A4, default 440),
`referenceMidi` (default 69), optional `ratios` (length-12 ratio array for
non-equal temperament).

**`PitchBend`** — `baseNote`, `bendSemitones` (fractional), `resultFrequency`.

**Type unions:** `PitchClassName` (12 sharp names), `FlatPitchClassName` (12
flat names), `NoteName` (33 spellings including double accidentals),
`Accidental`, `LetterName`.

**Notation systems:** `SolfegeSyllable` (17 chromatic syllables Do–Ti),
`NashvilleNumber` (`degree`, `quality`, `accidental`), `SargamSyllable` (12
Indian sargam syllables), `ByzantineNeume` (`ison`, `oligon`, `petaste`,
`kentemata`, `hypsele`, `apostrophos`, `elaphron`, `chamele`) with
`ByzantineElement` (`neume`, `intervalSteps`, `direction`), `HelmholtzOctave`
(10 octave designations sub-contra…six-line). `SpellingContext` (`keySignature`,
`preferSharps`) governs sharp-vs-flat choice.

### 2.2 Intervals (`intervals`)

This sub-module types every way intervals can be classified, measured, and
evaluated — from standard quality/number notation through microtonal cent
offsets, consonance scoring, and the Plomp-Levelt roughness model. The
`RoughnessResult` type is used by mastering and analysis code to model
psychoacoustic clash between simultaneous tones.

**`Interval`** — `quality` (`IntervalQuality`: perfect / major / minor /
augmented / diminished / doubly-augmented / doubly-diminished), `number`
(`IntervalNumber` 1–15), `semitones`, `direction` (ascending / descending /
unison), `shortName` (e.g. `P5`, `m3`), `fullName`, `isCompound`.

Other types: **`JustIntonationRatio`** (`numerator`, `denominator`, `decimal`,
`cents`); **`ConsonanceScore`** (`score` 0–1, `classification` —
perfect-consonance / imperfect-consonance / mild-dissonance / sharp-dissonance —
`description`); **`MicrotonalInterval`** (`cents`, `semitones`,
`remainderCents`, `isStandard`, `isQuarterTone`, `nearestStandard`,
`deviationFromStandard`); **`IntervalClass`** (`value` 0–6);
**`IntervalVector`** (`ic1`…`ic6` plus a 6-tuple `vector`);
**`TritoneResolution`** (`tritone` pair, `inwardResolution`,
`outwardResolution`); **`RoughnessResult`** (Plomp-Levelt critical-bandwidth
model: `roughness` 0–1, `frequencies`, `criticalBandwidth`, `cbRatio`); training
types **`ExerciseConfig`** and **`TrainingExercise`** with `ExerciseDifficulty`
(beginner / intermediate / advanced / expert).

### 2.3 Scales (`scales`)

The scales sub-module separates the root-independent scale template
(`ScaleDefinition`) from a rooted scale (`Scale`). This distinction matters
because most theory operations (mode rotation, scale-to-chord mapping) work on
the template, while pitch generation needs a rooted scale. The `ScaleCategory`
enum lists every scale family the library knows about.

**`ScaleDefinition`** — root-independent template: `name`, `intervals` (semitone
array starting at 0), `category` (`ScaleCategory`), optional `aliases`.
**`Scale`** — `root` (`PitchClass`), `definition`, `pitchClasses`.

`ScaleCategory` values: `diatonic`, `pentatonic`, `blues`, `symmetric`, `bebop`,
`exotic`, `raga`, `maqam`, `japanese`, `chromatic`.

`ScaleDegree` functional names: `tonic`, `supertonic`, `mediant`, `subdominant`,
`dominant`, `submediant`, `leading-tone`, `subtonic`. **`ScaleDegreeChord`**
maps a degree to its diatonic triad and seventh-chord quality
(`ScaleChordQuality`, 14 values) with a `roman` label. **`ScaleSearchCriteria`**
supports search by category, contained intervals, note count, or fuzzy name.

### 2.4 Chords (`chords`)

Chord types follow the same template/instance pattern as scales: a
`ChordDefinition` is root-independent, while a `Chord` is rooted. The
`VoicedChord` type adds concrete octave-positioned notes, which is what MIDI
output and the DAW piano roll consume.

**`ChordDefinition`** — `name`, `symbol` (e.g. `maj7`, `m7b5`), `intervals`
(from root, first element 0), `quality` (`ChordQuality`: major, minor,
diminished, augmented, dominant, half-diminished, minor-major, augmented-major,
sus2, sus4, power).

**`Chord`** — `root` (`PitchClass`), `definition`, `pitchClasses`, optional
`bass` (slash chords), `inversion` (0 = root position).

**`VoicedChord`** — `chord`, `voicing` (`VoicingType`: close / open / drop-2 /
drop-3 / drop-2-4 / spread), `notes` (concrete `Note[]` with octaves).
**`Polychord`** (`upper`, `lower`); **`ClusterChord`** (`root`, `stepType` —
chromatic / whole-tone — `size`, `pitchClasses`); **`ParsedChordSymbol`**
(result of parsing strings like `Dm7b5/A`: `input`, `rootName`, `suffix`,
`bassName?`, `definition`).

### 2.5 Rhythm (`rhythm`)

The rhythm sub-module models time at every level — individual note durations,
tuplets, time signatures, tempo markings, and complex polyrhythms. The internal
tick unit (480 ticks per quarter note) is the coordinate system used throughout
the DAW timeline and MIDI file I/O.

**`Duration`** — `base` (`DurationBase`: double-whole…sixty-fourth), `dots`
(0–3), `ticks` (quarter note = 480 ticks). **`Tuplet`** — `actual`, `normal`,
`baseDuration`, `effectiveTicks`.

**`TimeSignature`** — `numerator`, `denominator`, `type` (`MeterType`: simple /
compound / complex / additive), optional `beatGrouping`, plus computed
`measureTicks`, `beatsPerMeasure`, `ticksPerBeat`.

**`Tempo`** — `bpm`, `beatUnit`, optional `marking` (`TempoMarking`:
Larghissimo…Prestissimo, 13 values); **`TempoMarkingRange`** gives BPM bounds
per marking. **`MetricModulation`** carries old/new durations, BPM, and beat
units. **`SwingConfig`** — `ratio` (0.5 straight … 0.75 hard swing),
`subdivision`. **`RhythmicEvent`** / **`RhythmPattern`** model event sequences;
**`Polyrhythm`** and **`Polymeter`** model simultaneous layers;
**`BeatSubdivision`** and **`DisplacementConfig`** support beat splitting and
time shifting.

### 2.6 Keys (`keys`)

Key management covers both simple key metadata (sharps, flats, accidentals) and
the deeper tonal-analysis types needed by the harmony and theory layers:
Krumhansl-Schmuckler key detection, modulation analysis (six modulation types),
pivot chord identification, and modal interchange. The `KeyDetectionResult` type
is the primary output when key must be inferred from a note set.

**`KeySignature`** — `tonic` (`PitchClass`), `mode` (`KeyMode` major/minor),
`sharps` (0–7), `flats` (0–7), `accidentals` (`PitchClass[]`). `KeyQuality`
distinguishes major / natural-minor / harmonic-minor / melodic-minor.

**`KeyDetectionResult`** — Krumhansl-Schmuckler output: best `key`, `confidence`
(Pearson correlation), `candidates` (`KeyCandidate[]`).
**`TonalAmbiguityScore`** scores ambiguity from the gap between the top two
candidates (`assessment`: clear / moderate / ambiguous / highly-ambiguous).

Relationship and chromatic-harmony types: **`KeyRelationship`**
(`KeyRelationshipType`: relative / parallel / dominant / subdominant /
enharmonic / chromatic-mediant), **`CommonToneAnalysis`**, **`TriadInfo`**,
**`PivotChord`** / **`PivotChordAnalysis`**, **`SecondaryDominant`**,
**`BorrowedChord`**, **`ModalInterchangeChord`** /
**`ModalInterchangeAnalysis`** (`ModalInterchangeMode`: the 7 modes),
**`Modulation`** / **`ModulationAnalysis`** (`ModulationType`: pivot-chord /
direct / sequential / chromatic / enharmonic / phrase), **`Tonicization`** /
**`TonicizationAnalysis`**, **`CircleOfFifthsPosition`**. **`ChordInput`**
(`root`, `quality` strings) is the lightweight input for modulation/tonicization
analysis.

### 2.7 Form (`form`)

The form sub-module models large-scale musical structure — from individual
phrases and sentences through sections and complete formal templates. The 20
`SectionType` values cover both popular song forms (verse, chorus, bridge, drop)
and classical forms (exposition, development, recapitulation, stretto).
`FormAnalysisResult` is the comprehensive analysis output used by scoring and
arrangement tools.

**`Section`** — `type` (`SectionType`, 20 values incl. intro, verse, chorus,
drop, exposition, development, recapitulation, stretto), `label`,
`startMeasure`, `endMeasure`, `measures`, `repeatCount`, optional `keySemitone`
/ `tempo` / `dynamic`. **`Measure`** carries optional `timeSignature`
(`TimeSignatureSpec`), `tempoChange`, `rehearsalMark`, repeat barlines,
`endingNumber`, `chordSymbols`.

**`FormTemplate`** — `name`, `category` (`FormCategory`: popular / jazz /
classical / blues / electronic), `sections`, `totalMeasures`, `description`,
optional `measures`.

`CadenceType` (perfect-authentic, imperfect-authentic, half, plagal, deceptive,
phrygian) feeds **`CadenceDetectionResult`** (`cadence`, `penultimate`/`final`
`ChordInContext`, `confidence`, `description`). **`Phrase`** (`PhraseType`:
antecedent / consequent / continuation / presentation / fragmentation),
**`Period`** (antecedent + consequent, parallel or contrasting), **`Sentence`**
(presentation + continuation). Specialised detail types: **`SonataFormDetail`**
(`TonalArea[]`), **`FugueStructureDetail`** (`FugueVoiceEntry[]`),
**`Variation`** (`VariationTechnique`, 16 values), **`ThroughComposedSection`**,
**`BluesRow`** / **`BluesChordChange`**. **`FormAnalysisResult`** combines
sections, `FormPhraseBoundary[]`, a cadence map, periods, sentences, and a
`formLabel`.

### 2.8 Dynamics and expression (`dynamics`)

This sub-module covers everything that controls how a note sounds beyond its
pitch and duration: dynamic markings, crescendo/diminuendo hairpins,
articulations, ornaments, humanization parameters, and extended techniques. The
`HumanizationConfig` / `HumanizedNote` pair is the primary mechanism for adding
natural variation to programmatic performances — timing, velocity, and duration
micro-variation with an optional `randomSeed` for reproducibility.

**`DynamicLevel`** — `marking` (`DynamicMarking`: ppp…fff plus sfz, sfzp, fp,
rfz, fz), `velocity` (0–127), `label`. **`DynamicChange`** ramps between two
levels (`DynamicChangeType`: crescendo / decrescendo / diminuendo / subito) with
a `CurveType` (linear / exponential / logarithmic / s-curve).

**`Articulation`** — `type` (`ArticulationType`, 8 values),
`durationMultiplier`, `velocityMultiplier`, `description`. **`Ornament`** /
**`ResolvedOrnament`** (`OrnamentType`, 10 values; `OrnamentSpeed`).
**`GraceNote`** (acciaccatura / appoggiatura), **`Vibrato`** (`rate`, `depth`,
`delay`, `shape`). **`ExpressionCurve`** of **`ExpressionPoint`**s.
**`HumanizationConfig`** / **`HumanizedNote`** add timing, velocity, and
duration micro-variation with an optional `randomSeed` for determinism.
**`TimingVariation`** (push / pull, measured in cents of a beat),
**`VelocityVariationCurve`**, **`PerformanceInstruction`** with
`InstructionCategory` (tempo / dynamics / expression / technique / mood),
**`Fermata`**, **`Rubato`** (`RubatoStyle`), **`BreathMark`** (breath / caesura
/ luftpause), **`ExtendedTechnique`** (16 values incl. harmonics, col-legno,
pizzicato variants, sul-ponticello, flutter-tongue, multiphonics) with
**`ExtendedTechniqueInstruction`**, and **`ItalianTermEntry`** for term parsing.

### 2.9 Audio (`audio`)

The audio sub-module defines the raw audio buffer type and every codec-level
format type that the mastering, spatial, and voice libraries pass data through.
`AudioBuffer` is the universal in-memory representation; the codec types
(`Mp3Codec`, `FlacCodec`, etc.) define how buffers serialize to and from files.
All processing functions in the mastering and spatial libraries receive and
return `AudioBuffer`-derived types.

**`AudioBuffer`** — deinterleaved Float32 sample data normalised to [−1, 1]:
`sampleRate`, `channels`, `channelLayout` (`ChannelLayout`: mono / stereo /
surround-5.1 / surround-7.1 / quad / custom), `sampleFormat` (`int16` / `int24`
/ `float32`), `bitDepth` (16 / 24 / 32), `data` (`Float32Array[]`), `length`,
`duration`.

**`AudioFormat`** — `codec` (`pcm`, `mp3`, `flac`, `vorbis`, `aac`, `aiff-pcm`),
`sampleRate`, `channels`, `bitDepth`, optional `bitrate`, `lossless`.
**`AudioMetadata`** holds ID3v2 / Vorbis common tags.

Codec interfaces: abstract **`AudioEncoder`** / **`AudioDecoder`**; concrete
**`Mp3Codec`**, **`FlacCodec`**, **`OggVorbisCodec`**, **`AacCodec`** with
format-specific option and header types (`Mp3EncoderOptions`, `Mp3FrameHeader`,
`FlacStreamInfo`, `FlacEncoderOptions`, `VorbisInfo`, `VorbisComment`,
`OggVorbisEncoderOptions`, `AacEncoderOptions`, `AacProfile` — AAC-LC, HE-AAC,
HE-AAC-v2, AAC-LD, AAC-ELD, `M4aMetadata`). WAV and AIFF binary read/write are
modelled by `WavFormatInfo` / `WavWriteOptions` and `AiffCommInfo` /
`AiffWriteOptions`.

Processing: **`NormalizationConfig`** (`NormalizationType`: peak / rms / lufs),
**`AudioLevelMeasurement`** (`peakDb`, `rmsDb`, `lufs`, `crestFactor`, …),
**`SrcOptions`** (`SrcQuality`: linear / sinc), **`ChannelMixMatrix`** with
`ChannelMixPreset`s, **`SampleRange`** / **`TimeRange`**, ID3v2 types
(`Id3v2Header`, `Id3v2Frame`, `Id3v2FrameId`). `StandardSampleRate` enumerates
8000–192000 Hz.

### 2.10 MIDI (`midi`)

The MIDI sub-module covers three protocol generations. MIDI 1.0 handles the vast
majority of existing hardware and software. MIDI 2.0 (UMP) adds 32-bit
resolution and per-note controllers for expressive performance. MPE (MIDI
Polyphonic Expression) adds per-note pitch bend, slide, and pressure on
dedicated channels — used by instruments like the Roli Seaboard. All three
protocol types are represented as discriminated unions so a caller can pattern-
match on event type without manual byte decoding.

**MIDI 1.0 messages.** Discriminated union `MidiEvent` over `MidiMessageType`
(note-on, note-off, control-change, program-change, pitch-bend,
channel-aftertouch, poly-aftertouch, sysex, meta, plus system real-time:
timing-clock, start, stop, continue, active-sensing, system-reset). Each member
extends `MidiMessage` (`type`, optional `channel` 0–15, `deltaTime`,
`absoluteTime`): `NoteOnMessage`, `NoteOffMessage`, `ControlChangeMessage`,
`ProgramChangeMessage`, `PitchBendMessage` (signed 14-bit),
`ChannelAftertouchMessage`, `PolyAftertouchMessage`, `SysExMessage` (`data`,
`manufacturerId`), `MetaMessage` (`MidiMetaType`, 14 values).

**SMF.** `MidiFile` — `format` (`0 | 1 | 2`), `ticksPerQuarterNote`, `tracks`
(`MidiTrack[]`), and extracted sorted `tempoMap`, `timeSignatures`,
`keySignatures` (`TempoEvent`, `TimeSignatureEvent`, `KeySignatureEvent`).
`MidiChannel` tracks per-channel program/volume/pan and `isDrum`.

**MIDI 2.0.** `UniversalMidiPacket` (UMP) over `Midi2MessageType` (8 groups);
`Midi2Event` union — `Midi2NoteOnMessage` / `Midi2NoteOffMessage` (16-bit
velocity, attribute fields), `Midi2PerNoteControllerMessage`,
`Midi2PerNotePitchBendMessage` (32-bit),
`Midi2RegisteredPerNoteControllerMessage`.

**MPE.** `MpeZone` (master + member channels, pitch-bend range), `MpeConfig`
(lower/upper zones), `MpeNoteState` (per-note channel, pitch-bend, slide,
pressure).

**Utilities.** `QuantizeOptions` (`gridSize`, `strength`, `swingAmount`,
`humanize`), `VelocityCurve` (`VelocityCurveType`: linear / logarithmic /
exponential / s-curve / fixed), `GmInstrumentFamily` (16 GM families),
`GmDrumNote`, `MidiControllerDef`, `PitchBendRange`, `SmpteOffset` (frame rates
24 / 25 / 29.97 / 30).

---

## 3. `@euterpe/theory` — Music Theory Intelligence

`@euterpe/theory` has ten sub-modules, each covering a different aspect of
compositional analysis and generation. The library works on string-based note
and chord symbols (`NoteName`, `ChordSymbol`, `RomanNumeralString`, `KeyString`
are all `string` type aliases) and on MIDI note number arrays for line-based
analysis (melody, counterpoint). Sub-module headers carry Phase 38.2.x task IDs
for cross-referencing with the TODOS.

The types in this section are what higher-level libraries like `@euterpe/studio`
ai-features, `@euterpe/score`, and `@euterpe/conservatory` depend on for
harmonic analysis, melody grading, and curriculum exercises.

### 3.1 Harmony (`harmony`)

Covers 15 subtasks (38.2.1.1–38.2.1.15). Key types:

- **`RomanNumeralAnalysis`** — `chord`, `roman`, `scaleDegree`, `quality`
  (`RomanNumeralQuality`, 10 values), `isDiatonic`, `inversion`.
- **`FunctionalHarmonyResult`** — `function` (`HarmonicFunction`: tonic /
  subdominant / dominant), short `label` (`T` / `S` / `D`), `strength`.
- **`ChordFunctionInContext`** — `role` (`ChordContextRole`, 10 values incl.
  passing, neighbor, pedal, secondary-dominant, pivot), `resolvesTo`.
- **`VoiceLeadingAnalysis`** — `VoiceMovement[]`, `totalMotion`, common-tone
  counts, `MotionPair[]` (`MotionCategory`: parallel / similar / contrary /
  oblique), `isSmooth`.
- **`ParallelViolation`** / **`ParallelViolationResult`** — parallel fifths /
  octaves / unisons, direct vs explicit.
- **`ResolutionPattern`** — `ResolutionPatternType` (10 cadence/resolution
  kinds); **`TendencyTone`** / **`TendencyToneAnalysis`**;
  **`HarmonicRhythmAnalysis`** (`rate`: slow / moderate / fast / irregular).
- Pattern detection: **`ProgressionPattern`** / **`ProgressionPatternMatch`**,
  **`IIVIDetection`**, **`TurnaroundDetection`** (`TurnaroundType`, 9 values),
  **`DeceptiveCadenceDetection`**.
- Chromatic harmony: **`ChromaticHarmonyEvent`** /
  **`ChromaticHarmonyAnalysis`** (`ChromaticHarmonyType`, 9 values;
  `AugmentedSixthType`: Italian / French / German),
  **`TritoneSubstitutionDetection`**.
- Schenkerian primitives: **`SchenkerianNode`** (`SchenkerianLevel`: foreground
  / middleground / background), **`Prolongation`** (`ProlongationType`, 11
  values), **`Bassbrechung`**, **`Urlinie`** (`UrlinieStart` 3 / 5 / 8),
  **`Ursatz`**, **`SchenkerianReduction`**.

### 3.2 Counterpoint (`counterpoint`)

Covers 38.2.2.1–38.2.2.15. Lines are `CounterpointNote[]` (MIDI + duration
weight). **`CounterpointInput`** carries `cantusFirmus`, `counterpoint`,
`species` (`Species` 1–5), `cantusFirmusPosition` (upper / lower), `keyRoot`,
`mode`. **`CounterpointValidation`** returns `isValid`, `violations`
(`CounterpointViolation[]` with `ViolationSeverity` error / warning /
suggestion), error/warning counts, `species`, `summary`.

Per-species result types — **`FirstSpeciesResult`** (with `FirstSpeciesInterval`
analysis, `HarmonicIntervalClass`, `ConsonanceType`), **`SecondSpeciesResult`**,
**`ThirdSpeciesResult`** (cambiata detection), **`FourthSpeciesResult`**
(`SuspensionType`: 7-6 / 4-3 / 9-8 / 2-3 / none), **`FifthSpeciesResult`**
(`FloridNoteType`, 7 values). Additional checks: **`VoiceCrossingResult`**,
**`VoiceOverlapResult`**, **`DirectIntervalResult`** (direct/hidden fifths and
octaves), **`MelodicIntervalResult`** (`MelodicIntervalType`: step / skip / leap
/ unison), **`ClimaxAnalysis`**, **`MotionSummary`** (`MotionType` counts and
percentages), **`FugueSubjectAnalysis`** (`AnswerType`: real / tonal),
**`InvertibleCounterpointResult`** (`InversionInterval` 8 / 10 / 12),
**`CanonValidation`** (`CanonType`: strict / free / inversion / retrograde /
augmentation / diminution).

### 3.3 Melody (`melody`)

Covers 38.2.3.1–38.2.3.15. Lines are `MelodyNote[]` (MIDI + duration).
**`ContourAnalysis`** (`ContourType`: arch / inverted-arch / ascending /
descending / wave / static), **`IntervalDistribution`**, **`StepSkipRatio`**,
**`MelodicRange`** (`rangeClass`: narrow / moderate / wide / very-wide),
**`Tessitura`** (`placement`: high / middle / low), **`MotifDetectionResult`**
(`Motif` with interval pattern, occurrences, `prominence`),
**`SequenceDetectionResult`** (`MelodicSequence`, `SequenceType` real / tonal).
Transformations: **`MelodicVariation`** (`VariationType`, 5 values),
**`RetrogradeResult`**, **`InversionResult`**, **`AugDimResult`**.
**`FragmentationAnalysis`**, **`PhraseStructureAnalysis`** (`PhraseRole`,
`PhraseCadence`), **`TensionCurveAnalysis`** (`TensionPoint[]`),
**`HookDetectionResult`** (`Hook`).

### 3.4 Progressions (`progressions`)

Genre-aware progression catalogue and generation. `Genre` and `ModalScale`
unions classify input. **`ProgressionGenerationOptions`** /
**`GeneratedProgression`** drive generation; **`ProgressionTemplate`** and
**`GenreTemplateCollection`** hold catalogued patterns with genre-specific
sub-types (`PopRockPattern`, `JazzPattern`, `BluesVariation`, `ModalPattern`,
`NeoSoulPattern`, `ClassicalPattern`). **`TransitionModel`** /
**`TransitionProbability`** model chord-to-chord likelihoods;
**`ChordSuggestion`** / **`SuggestionResult`** / **`CompletionResult`** drive
next-chord prediction. **`ProgressionVariation`**, **`TensionAnalysis`**
(`ChordTensionScore`, `TensionFactor`), **`ModulationPath`** (`ModulationStep`),
and **`MelodyFittingResult`** (`FittedNote`) round it out.

### 3.5 Groove (`groove`)

Rhythmic-feel analysis. `DrumPattern` of `InstrumentTrack`s holds `TimedHit`s
keyed by `DrumInstrument`. Analyses: **`BeatPatternAnalysis`**
(`BeatPositionAnalysis`, `BeatStrength`), **`SyncopationAnalysis`**
(`SyncopationEvent`, `SyncopationType`), **`GrooveTemplateMatch`**
(`GrooveTemplate`, `GrooveGenre`), **`SwingAnalysis`** (`SwingType`),
**`MicroTimingAnalysis`** (`MicroTimingDeviation`), **`PocketAnalysis`**
(`GrooveFeel`), **`PolyrhythmAnalysis`**, **`RhythmicDensityAnalysis`**
(`DensityLevel`: sparse…saturated), **`AccentPatternAnalysis`**,
**`MetricAmbiguityAnalysis`**, **`DrumPatternClassification`**
(`DrumPatternStyle`), **`BassDrumsAnalysis`** (`BassKickRelationship`),
**`RhythmicTensionAnalysis`**, **`TempoVariationAnalysis`** (`TempoChange`,
`TempoChangeType`), **`RhythmicMotifAnalysis`**.

### 3.6 Set theory (`set-theory`)

Pitch-class set theory. `PitchClass` = `number`, `PitchClassSet` =
`readonly PitchClass[]`, `IntervalClass` = `1|2|3|4|5|6`, `IntervalVector` =
6-tuple. Types: **`PitchClassSetInfo`** (`cardinality`, `noteNames`),
**`PrimeFormResult`**, **`NormalFormResult`**, **`IntervalVectorResult`**,
**`SetClassInfo`**, **`ZRelationResult`**, **`ComplementResult`**,
**`SubsetSupersetResult`**, **`ForteLookupResult`** (`ForteEntry`). Twelve-tone:
`TwelveToneRow` (12-tuple), **`ToneRowMatrix`**, **`RowTransformation`**
(`RowTransformationType`: `P` / `R` / `I` / `RI`), **`CombinatorialityResult`**
(`CombinatorialityType`), **`HexachordAnalysis`** / **`RowHexachordAnalysis`**,
**`AggregateAnalysis`** (`AggregateTimelineEntry`, `AggregateCompletionState`).

### 3.7 Orchestration (`orchestration`)

**`InstrumentDefinition`** holds range, `TranspositionInfo`, `ClefType`,
`InstrumentFamily`, register data. **`PlayabilityResult`**
(`PlayabilityFactors`), **`IdiomaticPassage`** (`IdiomaticPatternType`),
**`InstrumentClassification`** (`InstrumentSubfamily`),
**`InstrumentRegisterMap`** (`RegisterCharacteristic`, `RegisterDescriptor`),
**`BalanceAnalysis`** (`BlendPair`, `ScoringAssignment`),
**`DoublingSuggestion`** (`DoublingReason`), **`SpacingAnalysis`** /
**`OptimizedSpacing`**, **`TranspositionResult`**, **`DivisiAssignment`**
(`DivisiType`), **`BrassMuteSpec`** (`BrassMuteType`),
**`FingeringOptimizationResult`** (`FingeringDifficulty`),
**`PercussionNotation`** (`PercussionCategory`, `NoteheadShape`),
**`OrchestraReduction`** (`ReductionTarget`), **`PartsExtraction`**
(`ExtractedPart`, `CueNote`).

### 3.8 Genre (`genre`)

Genre / era / regional-style classification. **`MusicalFeatures`** and
**`GenreProfile`** drive **`GenreClassification`** (`GenreMatch[]`).
**`StyleFingerprint`** (`StyleTrait[]`), **`EraDetection`** (`EraProfile`,
`MusicalEra`), **`SubgenreIdentification`**, **`FusionDetection`**
(`FusionComponent`), **`InfluenceMap`** (`GenreInfluence`), **`GenreRuleSet`** /
**`RuleSetEvaluation`**, **`StyleTransferInstruction`** (`StyleTransferParams`),
**`AuthenticityScore`** (`DimensionAuthenticityScore`),
**`CrossGenreCompatibility`**, **`ProductionStyleDetection`** /
**`ArrangementStyleDetection`** / **`RegionalStyleDetection`**,
**`StyleEvolution`** (`StylePhase`, `StyleSnapshot`), **`ArtistFingerprint`** /
**`ArtistSimilarity`**.

### 3.9 Ear training (`ear-training`)

Exercise generation and learner tracking. Exercise types cover intervals,
chords, scale degrees, melodic / harmonic / rhythmic dictation, sight-singing,
progression recognition, and error detection — each with a matching result type.
Adaptive layer: **`PerformanceMetrics`**, **`AdaptiveDifficultyConfig`** /
**`DifficultyAdjustment`**, **`SpacedRepetitionItem`** /
**`SpacedRepetitionReview`** (`ReviewQuality` 0–5) /
**`SpacedRepetitionSession`**, **`Competency`** / **`CompetencyAssessment`**
(`AssessmentRubric`), **`Curriculum`** / **`CurriculumUnit`** /
**`CurriculumSequenceResult`**, **`StudentProfile`** /
**`PersonalizedLearningPath`** (`LearningPathStep`), **`ProgressAnalytics`**
(`CategoryProgress`, `Milestone`), **`StudentStats`**.

### 3.10 Notation (`notation`)

Notation rendering data. **`Score`** of **`Part`**s of **`Measure`**s of
**`NotationNote`** / **`NotationRest`** / **`ChordSymbol`**. Output formats:
**`MusicXMLOptions`**, **`LilyPondOptions`**, **`ABCTune`** (`ABCHeader`),
**`LeadSheet`** (`LeadSheetBar`), **`ChordChart`** (`ChordChartSection`),
**`TabMeasure`** (`TabBeat`, `TabNote`, `TablatureTuning`,
`TablatureInstrument`), **`DrumPatternBar`** (`DrumHit`, `DrumInstrument`),
**`NashvilleChart`** (`NashvilleSection`, `NashvilleBar`),
**`FiguredBassAnnotation`**, **`BrailleMusic`**, **`ScoreLayout`** (`System`,
`ScoreLayoutOptions`), **`ExtractedPart`** (`PartExtractionOptions`),
**`RehearsalMark`** (`RehearsalMarkStrategy`), **`PDFRenderResult`**
(`PDFRenderOptions`).

---

## 4. `@euterpe/genesis` — AI Music Generation

`@euterpe/genesis` models AI music generation as a pipeline of structured intent
and result types. Critically, it does not call external AI model APIs itself —
that responsibility belongs to the planned `@euterpe/providers` package. Genesis
defines what a generation request looks like and what the result carries; the
infrastructure sub-module abstracts how models are loaded and dispatched. No
source file in `libs/euterpe/` reads environment variables: all behaviour is
driven by the typed config objects passed into each function.

Ten sub-modules span the pipeline from raw prompt parsing (`text-to-music`)
through generation (`stems`, `voice`, `melody-gen`, `arrangement`, `inpainting`,
`style-transfer`, `conditional`) to evaluation (`quality`) and model management
(`infrastructure`).

### 4.1 Text-to-music (`text-to-music`)

Covers 38.3.1.1–38.3.1.15. The central type is **`MusicalIntent`** parsed from a
prompt — optional `genre`, `mood`, `tempo` (`TempoInference`), `instruments`,
`structure` (`StructureInference`), `duration` (`DurationSpec`), `energy`
(`EnergySpec`), `era` (`EraSpec`), `key`, `timeSignature`, `lyrics`
(`LyricsIntegration`), `negativePrompts` (`NegativePrompt[]`), `referenceTrack`
(`ReferenceTrack`), and a required `confidence`. Supporting types:
**`PromptToken`** (typed prompt fragment), **`GenreExtraction`**,
**`MoodMapping`** (valence / arousal / dominance, `MoodMusicalAttributes`),
**`TempoInference`**, **`InstrumentSuggestion`**, **`StructureInference`**
(`StructureSection[]`), **`LyricsIntegration`** (`LyricsSection[]`),
**`LanguageDetection`** with `SupportedLanguage` (12 ISO codes),
**`NegativePrompt`**, **`EnhancedPrompt`**, **`ReferenceTrack`**
(`ReferenceAttribute[]`), **`DurationSpec`**, **`EnergySpec`**
(`EnergyPoint[]`), **`EraSpec`**, **`PromptTemplate`** (`TemplateVariable[]`,
`PromptCategory`).

### 4.2 Stems (`stems`)

**`StemSpec`** describes a stem to generate; `StemRole` = drums / bass / harmony
/ melody / pad / vocal / fx. **`GeneratedStem`** carries `StemNote[]` and
`StemMetadata`; **`CoherenceConstraints`** keep stems mutually consistent.
**`StemMixPosition`** / **`StemEffect`** position stems in a mix.
**`StemExportResult`** targets a `DAWFormat` (midi / musicxml / wav / stems-json
/ ableton-als / logic-band). **`StemVariationParams`** and
**`StemReplacementSpec`** support regeneration and substitution.

### 4.3 Voice (`voice`)

Singing-voice generation primitives. **`VoicePersona`** (`VoiceGender`,
`VoiceAge`, `VocalStyle`), **`VocalLine`** of **`SingingNote`**s with
**`BreathMark`**s, `VibratoParams`, `EmotionalExpression`. Ensemble types:
**`HarmonyVoice`**, **`ChoirSection`**, **`VocalRunSpec`**,
**`VoiceBlendSpec`**.

### 4.4 Melody generation (`melody-gen`)

**`Melody`** of **`MelodyNote`**s with **`MelodyMetadata`**. Generation configs
are intent-specific: **`ChordMelodyConfig`** (over a `ChordSymbol` sequence),
**`LyricsMelodyConfig`** (`LyricsSyllable[]`), **`StyleConditioningParams`**
(`MelodicStyle`), **`HookMelodyConfig`** / **`VerseMelodyConfig`** /
**`BridgeMelodyConfig`**, **`VariationConfig`** (`VariationType`),
**`CounterMelodyConfig`** (`CounterMotionType`), **`FillConfig`**,
**`InstrumentMelodyConfig`** (`InstrumentType`, `InstrumentRange`),
**`QuestionAnswerConfig`** (`QuestionAnswerPair`), **`ContourConfig`**
(`ContourShape`). Analysis: **`TensionAnalysis`** (`TensionPoint`,
`TensionSource`), **`CatchinessScore`**, **`ComplexityAnalysis`**.

### 4.5 Arrangement (`arrangement`)

**`Arrangement`** of **`ArrangementSection`**s, each holding
**`InstrumentPart`**s (`InstrumentRole`) of **`ArrangementNote`**s, with
**`ArrangementMetadata`**. Built from a **`LeadSheet`** via
**`ArrangementConfig`** / **`ArrangementTemplate`** (`ArrangementGenre`).
Dynamic shaping: **`DynamicArrangementConfig`** (`DynamicSectionType`),
**`Transition`** (`TransitionType`), **`LayerDensityConfig`** /
**`LayerDensityResult`**, **`BreakdownConfig`** / **`BuildUpConfig`** /
**`OutroConfig`** (`OutroStyle`), **`ExtensionConfig`** /
**`CondensingConfig`**. Ensemble-specific: **`OrchestralArrangement`**
(`OrchestralConfig`, `OrchestraSection`), **`BandArrangementResult`**
(`BandArrangementConfig`, `BandInstrument`), **`ArrangementComparison`** and
**`ArrangementStyleDifferences`** (`PerformanceContext`: live / studio).

### 4.6 Inpainting (`inpainting`)

Region infilling and audio editing. **`MusicPiece`** of **`MusicNote`**s with
**`MusicRegion`**s. **`InpaintRequest`** (`InpaintConstraints`, `StyleProfile`)
→ **`InpaintResult`** (`InpaintMetadata`). Edit operations:
**`TransitionResult`** (`TransitionCurve`), **`StyleEditResult`**,
**`GapFillConfig`** (`GapFillApproach`), **`ExtensionConfig`**
(`ExtensionMode`), **`IntroConfig`** / **`OutroConfig`** (`IntroOutroStyle`),
**`KeyChangeResult`**, **`TempoChangeResult`**,
**`InstrumentSubstitutionConfig`** (`InstrumentDef`),
**`VocalReplacementResult`**, **`ErrorCorrectionResult`** (`DetectedError`,
`ErrorType`), **`ResolutionEnhanceResult`** (`ArticulationType`),
**`ArtifactRemovalResult`** (`DetectedArtifact`, `ArtifactType`),
**`NoiseReductionResult`**, **`QualityEnhanceResult`** (`QualityPass`,
`PassSummary`).

### 4.7 Style transfer (`style-transfer`)

Cross-style transformation. **`MusicPiece`** of **`MusicNote`**s →
**`TransferResult`** (`TransformChange[]`) under a **`StyleProfile`**. Configs:
**`GenreTransformConfig`** (`Genre`), **`EraTransferConfig`** (`MusicalEra`),
**`ArtistEmulationConfig`** (`ArtistStyle`, `ArtistCharacteristics`),
**`ProductionTransferConfig`** (`ProductionStyle`, `ProductionCharacteristics`),
**`InstrumentSwapConfig`** (`InstrumentMapping`, `InstrumentRangeDef`),
**`TempoTransformConfig`** (`RhythmicFeel`), **`MoodTransformConfig`**
(`MoodCharacteristics`), **`EnergyTransformConfig`**,
**`AcousticElectronicConfig`** (`ConversionDirection`), **`LiveStudioConfig`**
(`LiveStudioDirection`), **`OrchestralConfig`**, **`EDMRemixConfig`**
(`EDMSubgenre`), **`JazzArrangementConfig`** (`JazzStyle`), and effect-style
configs **`LofiConfig`**, **`SlowedReverbConfig`**, **`NightcoreConfig`**.

### 4.8 Conditional generation (`conditional`)

Generation conditioned on non-musical input. **`MusicParams`** /
**`MusicSection`** / **`GeneratedMusicSpec`** are the output. Condition sources
each have a config: **`VideoToMusicConfig`** (`VideoFrame`, `SceneType`),
**`ImageToMusicConfig`** (`ImageFeatures`, `ImageSubject`),
**`MotionToMusicConfig`** (`MotionData`, `MotionPattern`), **`NarrativeConfig`**
(`NarrativePoint`, `NarrativeEmotion`), **`EmotionCurveConfig`**
(`EmotionPoint`, `EmotionLabel`), **`GameStateConfig`** (`GameState`,
`GameScene`, `GamePace`), **`BiometricConfig`** (`BiometricData`),
**`TimeOfDayConfig`** (`TimeOfDay`, `Season`), **`WeatherConfig`**
(`WeatherData`, `WeatherCondition`), **`TrendConfig`** (`TrendData`,
`ViralContentType`), **`PersonalizationConfig`** (`UserProfile`,
`HistoryEntry`), **`CollaborativeFilterConfig`** (`CollaborativeUser`).
Multi-constraint: **`ConstraintSatisfactionConfig`** /
**`ConstraintSatisfactionResult`** (`Constraint`, `ConstraintType`),
**`MultiModalConfig`** (`ModalCondition`, `Modality`),
**`FeedbackRefinementConfig`** / **`FeedbackRefinementResult`**.

### 4.9 Quality (`quality`)

Generated-audio quality measurement. **`MusicSample`** of **`MusicNote`**s.
**`QualityScore`** (with `QualityIssue[]`, `QualityIssueType`),
**`MusicalityScore`**, **`PromptAdherenceScore`** (against a `PromptSpec`),
**`ArtifactDetectionResult`**, **`ClippingDetectionResult`** (`ClippingEvent`),
**`SilenceDetectionResult`** (`SilenceGap`), **`RepetitionDetectionResult`**
(`RepeatedPattern`), **`CoherenceScore`**. Comparison and ranking:
**`ABTestAnalysis`** (`ABTest`, `ABResult`), **`PreferenceModel`**
(`UserPreference`, `UserRating`), **`RankedGeneration`**, **`DiversityMetrics`**
/ **`DiversityEnforcementResult`**. Originality and safety:
**`SimilarityResult`** (`MatchedSegment`), **`CopyrightSimilarityScore`**,
**`ContentFlags`** (`ContentIssue`, `ContentCategory`).

### 4.10 Infrastructure (`infrastructure`)

Model-orchestration abstractions. `ModelType` = transformer / diffusion /
autoregressive / vae / gan / ensemble; `JobStatus` = pending / running /
completed / failed / cancelled. **`ModelConfig`**, **`InferenceRequest`** /
**`InferenceResult`**, per-architecture config/result types
(`TransformerPipeline`, `DiffusionResult`, `AutoregressiveState`,
`VAEEncodeResult` / `VAEDecodeResult`, `GANResult`), **`EnsembleConfig`**
(`EnsembleStrategy`: average / voting / weighted / cascade / best-of-n).
Training and optimisation: **`FineTuneJob`** (`FineTuneMetrics`),
**`LoRAAdapter`** / **`LoRAAppliedModel`**, **`QuantizedModel`**
(`QuantizationMethod`: int8 / int4 / fp16 / mixed; `QuantizationBenchmark`).
Serving: **`BatchJob`**, **`StreamSession`**, **`ModelVersionHistory`**
(`ModelVersion`, `VersionMetrics`), **`ModelABTestAnalysis`**,
**`MonitoringData`** (`PerformanceMetrics`, `LatencySample`),
**`RoutingDecision`** (`RoutingConfig`), **`ModelRegistry`**
(`ModelCapability`).

---

## 5. `@euterpe/studio` — Digital Audio Workstation

`@euterpe/studio` is a complete DAW in library form — ten sub-modules covering
the full production workflow from the audio processing graph and timeline
through MIDI editing, mixing, effects, virtual instruments, automation, project
management, and AI-assisted production. These types are what the Yemaya
application's DAW UI binds to; they are also the types that `@euterpe/collab`
project synchronization uses as its shared project state model.

Ten sub-modules, listed in order from the audio graph at the bottom up to the AI
feature layer at the top.

### 5.1 DAW engine (`daw-engine`)

Audio-processing graph and transport. Fixed unions: `SampleRate` (22050–192000),
`BitDepth` (16 / 24 / 32), `BufferSize` (32–4096), `ChannelCount` (1 / 2).
**`ManagedAudioContext`** (`AudioContextConfig`, `AudioContextState`),
**`AudioNodeGraph`** of **`AudioNode`**s (`AudioNodeType`),
**`BufferPoolConfig`** / **`BufferPoolStats`** (`PooledBuffer`),
**`WorkerStatus`** / **`RegisteredWorklet`** (`WorkletDescriptor`),
**`WasmDspModule`** / **`DspResult`**, **`LatencyInfo`**, **`MidiDeviceInfo`** /
**`AudioDeviceInfo`** / **`AudioDeviceSelection`**, **`OfflineRenderResult`**
(`OfflineRenderConfig`), **`StreamStatus`** (`StreamConfig`),
**`TransportControls`** (`TransportState`: stopped / playing / recording /
paused), **`TimingInfo`**.

### 5.2 Timeline (`timeline`)

Arrangement view. **`Track`** (`TrackType`: audio / midi / instrument / bus /
master / folder / send; `TrackColor`), **`Clip`** with **`WaveformData`** or
**`MidiNoteDisplay`**, **`AutomationLane`** of **`AutomationPoint`**s,
**`Marker`**, **`LoopRegion`**, **`TempoEvent`** / **`TimeSignatureEvent`**,
**`ArrangementSection`**, **`FolderTrack`**, **`TimelineViewport`**
(`ZoomLevel`, `ScrollPosition`, `TimeFormat`).

### 5.3 Clip editing (`clip-editing`)

Non-destructive clip operations. **`EditableClip`** (`ClipType`),
**`ClipSelection`**, results for move / split / join / crossfade
(`CrossfadeType`), **`FadeConfig`** (`FadeCurve`: linear / exponential /
logarithmic / s-curve / equal-power), **`StretchConfig`** (`StretchAlgorithm`:
repitch / elastique / granular / phase-vocoder), **`QuantizeConfig`**
(`QuantizeGrid`), **`ClipAutomationLane`**, **`DuplicateResult`**,
**`GainAdjustConfig`** (`GainAdjustMode`).

### 5.4 MIDI editing (`midi-editing`)

Piano roll, step sequencer, drum editor. **`PianoRollGridConfig`**
(`GridResolution`, `SnapMode`), **`MidiNote`**, drawing tools (`DrawingTool`:
pencil / line / eraser / select; `NoteDrawParams`, `LineDrawConfig`), note edit
results (`NoteEditOperation`), **`VelocityCurveConfig`** (`VelocityCurveType`),
**`QuantizeResult`** / **`HumanizeResult`**, chord input (`ChordQuality`,
`ChordVoicing`, `ChordInputConfig`), scale highlight (`ScaleType`,
`ScaleHighlightConfig`), **`DetectedChord`**, CC editing (`MidiCCLaneConfig`,
`CCInterpolationType`), pitch-bend editing, **`MidiLearnMapping`** /
**`MidiLearnState`**, **`StepSequencerPattern`** (`StepState`),
**`DrumPatternConfig`** (`DrumKitAssignment`, `DrumHit`, `GMDrumMapEntry`).

### 5.5 Mixer (`mixer`)

Channel-strip mixing. **`ChannelStrip`** (`ChannelType`: audio / instrument /
aux / bus / master / vca) with **`FaderState`**, **`MeterReading`**,
**`PanState`** (`PanLaw`: linear / constantPower / compensated;
`SurroundFormat`, `SurroundGains`), **`ChannelControls`** (`SoloMode`). Effects
routing: **`InsertSlot`** (`EffectType`), **`SendConfig`** (`SendType`:
pre-fader / post-fader / post-pan), **`ReturnConfig`**, **`BusChannel`**. Master
and sidechain: **`MasterBusConfig`** (`LimiterConfig`, `LimiterState`),
**`SidechainConfig`** (`SidechainSource`). Routing matrix: **`RoutingMatrix`**
(`RoutingPoint`, `RoutingConnection`, `RoutingPointType`), **`VCAGroup`**.
Monitoring and metering: **`MonitorConfig`** (`MonitorSource`),
**`MeteringConfig`** (`MeterType`: peak / rms / lufs / vu / ppm; `MeterScale`),
**`LufsMeasurement`**. State: **`MixerSnapshot`**, **`ChannelStripPreset`**,
**`MixerState`**.

### 5.6 Effects (`effects`)

DSP processors operating on a **`StereoBuffer`**, each returning an
**`EffectResult`**. Processors: **`ParametricEQConfig`** (`EQBand`,
`EQBandType`, `EQResponsePoint`), **`CompressorConfig`** (`CompressorMode`: vca
/ fet / opto) with `CompressorState`, **`TruePeakLimiterConfig`**,
**`ReverbConfig`** (`ReverbType`: algorithmic / convolution; `ReverbAlgorithm`:
hall / room / plate / chamber / spring; `EarlyReflection`), **`DelayConfig`**
(`DelayMode`: stereo / pingPong / tape; `DelaySyncValue`),
**`ModulationConfig`** (`ModulationType`: chorus / flanger / phaser;
`LFOWaveform`), **`DistortionConfig`** (`DistortionType`: tube / transistor /
tape / digital / fuzz), **`FilterConfig`** (`FilterType`, `FilterSlope` 6–48
dB/oct), **`GateConfig`** (`GateMode`: gate / expander), **`DeEsserConfig`**
(`DeEsserMode`), **`PitchCorrectionConfig`** (`PitchCorrectionScale`,
`RootNote`, `NoteEnableMap`; `PitchDetectionResult`), **`VocoderConfig`**,
**`StereoWidenerConfig`** (`StereoAnalysis`), **`MultibandDynamicsConfig`**
(`CrossoverPoint`, `MultibandBandConfig`), **`TransientShaperConfig`**.
**`BiquadCoefficients`** / **`BiquadState`** are the DSP filter primitive.

### 5.7 Instruments (`instruments`)

Virtual instruments. Branded numeric aliases (`MidiNote`, `Velocity`,
`Frequency`, `Seconds`, `Decibels`, …). Shared: **`ADSREnvelope`**,
**`LFOConfig`**, **`ModulationRoute`**. Engines, each with a config / voice /
state triple: sampler (**`SampleInstrumentConfig`**, `SampleMapping`,
`SampleVoice`), wavetable (**`WavetableSynthConfig`**, `Wavetable`,
`WavetableBank`, `WavetableVoice`), subtractive (**`SubtractiveSynthConfig`**,
`SubtractiveOscillator`, `SubtractiveVoice`), FM (**`FMSynthConfig`**,
`FMOperator`, `FMAlgorithm`, `FMVoice`), granular (**`GranularSynthConfig`**,
`Grain`, `GranularSynthState`), drum machine (**`DrumMachineConfig`**,
`DrumPad`, `DrumKit`, `DrumPattern`, `DrumVoice`), bass synth
(**`BassSynthConfig`**, `BassSynthPreset`, `BassVoice`), pad synth
(**`PadSynthConfig`**, `UnisonConfig`, `PadVoice`).

### 5.8 Automation (`automation`)

Parameter automation. **`AutomatableParameter`**, **`AutomationLane`** of
**`AutomationPoint`**s (`CurveType`: linear / bezier / step / smooth /
exponential / logarithmic), drawing modes (`DrawingMode`: freehand / line /
parabolic / sine; `DrawConfig` union), **`AutomationRecordingState`**
(`AutomationRecordMode`: read / touch / latch / write), **`AutomationRegion`**
with paste / scale operations (`ScaleOperation`), **`TempoSyncConfig`**
(`NoteValue`, `TempoMapEntry`), **`AutomationSnapshot`**. Modulation:
**`ModulationSource`** / **`ModulationRouting`** (`ModulationSourceType`: lfo /
envelope / random / midi / sidechain / macro), **`LFOConfig`** (`LFOShape`),
**`EnvelopeFollowerConfig`**, **`RandomModulationConfig`** (`RandomMode`: random
/ sampleAndHold / smoothRandom / walk / perlin), **`MidiAutomationMapping`**
(`MidiSourceType`, `MidiMappingCurve`), **`ThinningConfig`** /
**`ThinningResult`** (`ThinningAlgorithm`). **`AutomationSystemState`** is the
aggregate.

### 5.9 Project management (`project-management`)

Project persistence model. **`ProjectState`** holds **`ProjectTrack`**s
(`TrackType`), **`ProjectClip`**s, **`ProjectEffect`**s, **`MasterSettings`**,
**`ProjectMarker`**s. Save/load: **`SaveOptions`** / **`SaveResult`**,
**`LoadOptions`** / **`LoadResult`** (`SerializedProject` is a string).
Versioning: **`VersionHistory`** of **`VersionSnapshot`**s and
**`ChangeEntry`**s (`ChangeType`), **`AutosaveState`** (`AutosaveConfig`,
`AutosaveEntry`). **`ProjectTemplate`** (`TemplateCategory`), import
(`ImportFormat`: midi / aaf / omf / xml / als / flp / dawproject;
`MidiFileHeader`, `MidiTrackEvent`), export (`ExportFormat`, `ExportType`:
mixdown / stems / individual-tracks / selection; `StemGroup`, `ExportedFile`).
Collaboration and assets: **`Collaborator`** (`PermissionLevel`),
**`ShareLink`**, **`ArchiveEntry`** (`ArchiveStatus`), **`AssetLibrary`**
(`AssetReference`, `AssetType`, `AssetFolder`), **`MissingFileScanResult`**
(`MissingFileStatus`, `PathResolutionStrategy`), **`ProjectNote`** (`NoteType`),
**`ProjectStatistics`**, backup types (`BackupType`).

### 5.10 AI features (`ai-features`)

AI-assisted production. **`StemGenerationRequest`** → **`GeneratedStem`**
(`StemType`, `GeneratedNote`), **`ArrangementAnalysis`** (`TrackSummary`,
`DetectedSection`, `ArrangementSuggestion`), **`MixingCommandResult`**
(`MixerAction`, `MixerActionType`), **`MasteringChain`** (`MasteringEffect`,
`MasteringEffectType`, `MasteringAnalysisInput`), **`HarmonyDetectionResult`**
(`DetectedChord`, `DetectedScale`), **`VocalTuningResult`** (`VocalPitchPoint`,
`VocalCorrection`), **`DrumReplacementResult`** (`DetectedDrumHit`,
`DrumHitType`, `DrumPattern`), **`SampleSuggestionResult`** (`SampleSuggestion`,
`SampleSuggestionContext`), **`MixAnalysisResult`** (`SpectralProfile`,
`MixAdjustment`, `MixIssue`, `MixQualityScores`, `ReferenceMatchResult`),
**`CollaborationAnalysisResult`** (`CollaborationSuggestion`,
`ExistingTrackInfo`). Confidence / priority / severity scalars are shared
branded types.

---

## 6. `@euterpe/master` — Mastering

`@euterpe/master` has five sub-modules that cover the complete mastering
workflow: signal processing chain, measurement, stem-level mastering,
platform-specific format output, and AI mix advice. All processors operate on a
local buffer type (`MasteringAudioBuffer`, `AnalysisAudioBuffer`,
`StemAudioBuffer`, `FormatAudioBuffer`) and return a `*Result` type that carries
both the processed audio and measurement metrics — so a caller always gets
quantified feedback alongside the output.

### 6.1 Mastering chain (`mastering-chain`)

**`MasteringChainConfig`** / **`MasteringChainResult`**
(`MasteringStageResult[]`) sequences the full chain. Stages:
**`GainStagingConfig`**, **`EqMatchingConfig`** (`FrequencyBand`),
**`MultibandCompressionConfig`** (`CompressionBand`, `BandCompressionStats`),
**`StereoEnhancementConfig`** (`StereoEnhancementMode`: widen / narrow / auto),
**`HarmonicExcitementConfig`** (`HarmonicType`: even / odd / both),
**`FinalLimiterConfig`**, **`LoudnessNormalizationConfig`** (`LoudnessStandard`:
EBU-R128 / ATSC-A85 / ASWG-R001 / custom), **`MidSideProcessingConfig`**
(`MidSideSignal`), **`DynamicEqConfig`** (`DynamicEqBand`),
**`SaturationConfig`** (`SaturationType`: tube / tape / transformer /
soft-clip), **`DitheringConfig`** (`DitherType`, `NoiseShapingType`),
**`IspDetectionConfig`** / **`IspPreventionResult`** (`IspDetectionMethod`,
`IspEvent`). **`MasteringProfile`** (`MasteringGenre`) and
**`ReferenceMatchingConfig`** (`TrackAnalysis`) drive genre / reference
targeting; **`ABComparisonConfig`** compares masters.

### 6.2 Mix analysis (`mix-analysis`)

Measurement only. **`SpectrumAnalysisResult`** (`SpectrumBin`,
`FrequencyRange`), **`DynamicRangeResult`**, **`StereoFieldResult`**
(`BandStereoWidth`), **`PhaseCorrelationResult`** (`PhaseIssue`),
**`LoudnessMeteringResult`** (`LoudnessStandard`), **`CrestFactorResult`**,
**`GenreComparisonResult`** (`GenreBenchmark`, `AnalysisGenre`),
**`ProblemDetectionResult`** (`MixProblem`, `MixProblemType`,
`ProblemSeverity`), **`HeadroomResult`**, **`TransientAnalysisResult`**
(`TransientEvent`), **`BassMonoResult`** / **`SubBassAnalysis`**,
**`TranslationPredictionResult`** (`SystemProfile`, `PlaybackSystem`),
**`EarFatigueResult`** (`FatigueFactor`), **`MixComparison`** (`MixSnapshot`),
**`AnalysisReport`** (`ReportConfig`, `ReportFormat`: text / json / html;
`ReportMetrics`).

### 6.3 Stem mastering (`stem-mastering`)

`StemType` = vocals / drums / bass / other; `ExtendedStemType` adds piano /
guitar / strings / synth / fx. **`Stem`**, **`StemSeparationResult`**
(`BleedMetric`), **`StemProcessingChainResult`** (`StemProcessor`,
`AppliedProcessorInfo`). Per-stem processors: **`StemEqConfig`** (`EqBand`),
**`StemDynamicsConfig`** (`DynamicsMode`: compress / expand / gate / limit),
**`StemBalanceConfig`**, **`StemWidthConfig`**, **`StemSaturationConfig`**
(`StemSaturationType`), **`VocalEnhancementConfig`** /
**`DrumEnhancementConfig`** / **`BassOptimizationConfig`**. Output:
**`StemRecombinationResult`**, **`PrintStemGenerationResult`** (`PrintStem`,
`PrintStemFormat`, `PrintStemGroup`), **`StemExportResult`**
(`DistributionFormat`, `LossyQuality`), **`AtmosConversionResult`**
(`AtmosObject`, `AtmosBedLayout`: 7.1.4 / 7.1.2 / 5.1.4 / 5.1.2 / 5.1),
**`StemArchiveResult`** (`StemArchiveMetadata`).

### 6.4 Format masters (`format-masters`)

Platform-targeted master generation. **`ComplianceResult`** (`ComplianceCheck`,
`LoudnessMeasurement`). Per-target config / result pairs: Spotify
(`SpotifyNormalizationMode`: quiet / normal / loud), Apple Music
(`AppleMusicCodec`: AAC / ALAC / Dolby-Atmos), YouTube, short-form
(`ShortFormPlatform`: tiktok / instagram-reels / youtube-shorts / snapchat),
vinyl (`VinylFormat`, `VinylSpeed` 33 / 45 / 78), CD (`PQCodeEntry`), broadcast
(`BroadcastStandard`: EBU-R128 / ATSC-A85 / ARIB-TR-B32 / OP-59), podcast,
audiobook (`AudiobookStandard`: ACX / Audible / Findaway / generic), mobile
(`MobileSpeakerType`), club (`ClubSystemType`), instrumental, radio edit
(`EditRegion`), clean version (`ExplicitRegion`). **`BatchExportConfig`** /
**`FormatExportEntry`** (`ExportFormat`, `ParsedExportFormat`, `ExportMetadata`)
fans one source to many formats.

### 6.5 Mix assistant (`mix-assistant`)

Mix advice from **`TrackDescriptor`**s (`InstrumentCategory`,
`FrequencyBandLabel`) within a **`MixContext`** (`MixGenre`). Recommendation
result types: **`LevelBalancingResult`** (`LevelSuggestion`),
**`PanningSuggestionResult`**, **`EqRecommendationResult`**
(`EqBandRecommendation`, `EqFilterType`, `FrequencyMaskingConflict`),
**`CompressionRecommendationResult`** (`TrackCompressionRecommendation`,
`CompressorType`, `BusCompressionSuggestion`), **`ReverbRecommendationResult`**
(`ReverbType`), **`DelaySuggestionResult`** (`DelayType`),
**`VocalChainResult`** (`VocalChainStep`), **`DrumProcessingResult`**,
**`BassTreatmentResult`**, **`MixCritiqueResult`** (`CritiquePoint`,
`CritiqueSeverity`, `CritiqueCategory`), **`OneClickMixResult`**
(`MixImprovementAction`), **`GenreTemplateResult`** (`GenreMixTemplate`),
**`ReferenceMixMatchResult`** (`ReferenceMixAnalysis`,
`ReferenceMatchAdjustment`), **`MixRevisionResult`** (`MixVersionSnapshot`,
`MixVersionChange`), **`CollaborativeFeedbackResult`** (`ReviewerFeedback`,
`ReviewerRole`, `FeedbackConsensus`).

---

## 7. `@euterpe/spatial` — Immersive Audio

`@euterpe/spatial` covers every major spatial audio format across five
sub-modules: Dolby Atmos object/bed authoring (`atmos`), HRTF binaural rendering
(`binaural`), higher-order ambisonics (`ambisonics`), real-time VR/game audio
(`vr-audio`), and AI stereo-to-immersive conversion (`spatial-upmix`). These
types are consumed by the V2 game engine audio architecture and by the Virtuoso
virtual concert renderer.

### 7.1 Atmos (`atmos`)

Dolby Atmos object/bed authoring. `AtmosBedFormat` = 7.1.2 / 7.1.4 / 5.1.2 /
5.1.4. **`AtmosObject`** carries an **`AtmosPosition`** plus gain and size;
**`AtmosBed`** holds **`BedChannel`**s (`BedChannelLabel`).
**`AutomationTrajectory`** of **`AutomationKeyframe`**s (`InterpolationType`:
linear / cubic / step / sine; `TrajectoryConfig`). Monitoring / fold-down:
**`BinauralDownmixResult`** (`HrtfModel`, `BinauralDownmixConfig`),
**`FoldDownResult`** (`DownmixFormat`), **`MonitoringSimResult`**
(`VirtualSpeaker`, `SpeakerConfiguration`). ADM/BWF: **`AdmProgramme`** →
**`AdmContent`** → **`AdmObject`** → **`AdmBlockFormat`**,
**`AdmBwfExportResult`** (`AdmProfile`, `ChnaEntry`). Rendering and delivery:
**`AtmosRendererConfig`** (`RendererMode`: realtime / offline;
`RenderBlockResult`), **`ImfExportResult`** (`IabFrame`),
**`AtmosMusicDeliverySpec`** (`MusicPlatform`) / **`MusicDeliveryValidation`**,
**`ReRenderResult`**, **`QCReport`** (`QCIssue`, `QCSeverity`, `QCConfig`),
**`AtmosSession`** (`AtmosMetadata`).

### 7.2 Binaural (`binaural`)

HRTF binaural rendering. Spatial primitives: **`Position3D`**,
**`SphericalCoord`**, **`HeadOrientation`**. HRTF data: **`HrtfMeasurement`**,
**`HrtfDataset`** (`HrtfDatabaseFormat`: sofa / mit-kemar / cipic / listen / ari
/ custom; `SofaConvention`), **`HrtfDatabaseConfig`** (`HrtfInterpolation`:
nearest / bilinear / spherical-harmonic / vbap). Personalisation:
**`HrtfPersonalizationConfig`** (`EarMeasurements`) /
**`PersonalizedHrtfResult`**. Rendering: **`BinauralPannerConfig`** /
**`BinauralPanResult`**, **`DistanceModelConfig`** (`DistanceModel`: inverse /
linear / exponential / custom), **`EarlyReflectionResult`** (`RoomConfig`,
`RoomDimensions`, `SurfaceProperties`, `SurfaceMaterial`, `Reflection`),
**`HeadTrackingResult`** (`HeadTrackingConfig`, `TrackingCoordinateSystem`:
opengl / unity / unreal / raw), **`ItdIldResult`** (`ItdModel`: woodworth / kuhn
/ spherical-head / measured), **`ExternalizationResult`**,
**`HeadphoneCompensationResult`** (`HeadphoneProfile`, `HeadphoneType`),
**`CrossFeedResult`**, **`BinauralReverbResult`** (`ReverbAlgorithm`:
feedback-delay / convolution / hybrid), **`SpatialBlurResult`**,
**`StereoToBinauralResult`**, **`BinauralQualityReport`** (`QualityMetric`,
`QualityMetricResult`).

### 7.3 Ambisonics (`ambisonics`)

Scene-based spatial audio. `AmbisonicNormalization` = SN3D / N3D / FuMa / maxN;
`AmbisonicOrdering` = ACN / FuMa / SID; `AmbisonicFormat` = AmbiX / FuMa /
custom. **`FoaBformat`** (first-order B-format) and **`HoaSignal`** (higher
order) with **`SphericalHarmonicValue`**; **`AmbisonicEncodeConfig`** /
**`AmbisonicEncodeResult`**. Decoding: **`SpeakerDecodeResult`**
(`SpeakerLayout`, `SpeakerPosition`, `SpeakerLayoutPreset`, `DecoderType`: basic
/ mode-matching / pseudo-inverse / allrad / max-rE), **`BinauralDecodeResult`**
(`BinauralDecodingMethod`: virtual-speakers / sh-hrtf / magls). Soundfield
transforms: **`AmbisonicRotationResult`** (`SoundfieldRotation`),
**`AmbisonicMirrorResult`** (`MirrorAxis`), **`AmbisonicZoomResult`**,
**`AmbisonicPanResult`**, **`AmbisonicReverbResult`** (`FdnTopology`: hadamard /
householder / random-orthogonal). Format conversion: **`AmbiXDescriptor`** /
**`FuMaDescriptor`** / **`FormatConversionResult`**, mic-array A-to-B conversion
(**`MicArrayDefinition`**, `MicArrayType`: tetrahedral / octet / eigenmike /
custom; `AFormatToBFormatResult`), **`Video360SyncResult`** (`VideoProjection`:
equirectangular / cubemap / equi-angular-cubemap).

### 7.4 VR audio (`vr-audio`)

Real-time game/VR audio. **`ListenerState`** and **`SpatialAudioSource`** drive
**`SpatialRenderResult`** (`SpatialRenderConfig`, `SpatialDistanceModel`).
Geometry effects: **`OcclusionResult`** (`Occluder`, `AcousticMaterial`),
**`ObstructionResult`** (`DiffractionEdge`), **`RoomAcousticsResult`**
(`RoomMaterial`, `SurfaceAbsorption`, `EarlyReflection`), **`ReverbZoneResult`**
(`ReverbZone`, `ReverbZoneShape`: box / sphere; `ReverbParameters`),
**`PortalResult`** (`AudioPortal`), **`PropagationResult`** (`PropagationPath`,
`PropagationSegment`, `PropagationSegmentType`: direct / reflection /
diffraction / transmission), **`DopplerResult`**, **`NearFieldResult`**.
Performance management: **`AudioFocusResult`** (`AttentionState`),
**`PriorityResult`** (`SourcePriorityData`, `SourceImportance`),
**`AudioLodResult`** (`AudioLodTier`: full / high / medium / low / minimal /
silent; `LodTierCapabilities`). Unity interop types (`UnityVector3`,
`UnityAudioSourceParams`) are provided.

### 7.5 Spatial upmix (`spatial-upmix`)

AI stereo→immersive conversion. `ChannelLayout` = mono / stereo / 5.1 / 7.1 /
7.1.4 / atmos; `UpmixQuality` = draft / standard / high / mastering. Per-target
config/result pairs: **`StereoTo51Result`**, **`StereoTo714Result`**,
**`StereoToAtmosResult`** (`SpatialObject`, `AtmosMetadata`),
**`MonoToStereoResult`**. Intelligent placement: **`ElementPlacementResult`**
(`DetectedElement`, `AudioElementType`), **`GenreSpatializationResult`**
(`GenreSpatialProfile`, `MusicGenre`), **`VocalCenterResult`**,
**`InstrumentSeparationResult`** (`SeparatedSource`), **`HeightChannelResult`**,
**`AmbienceExtractionResult`**, **`LegacyConversionResult`**. Batch and review:
**`BatchPipelineResult`** (`BatchJob`, `BatchJobStatus`),
**`QualityPreservationResult`**, **`UpmixComparisonResult`**
(`ComparisonMetric`, `ComparisonMetricResult`), **`ManualRefinementResult`**
(`ChannelAdjustment`, `ElementAdjustment`).

---

## 8. `@euterpe/voice` — Voice Technology

`@euterpe/voice` has seven sub-modules covering the full range of voice
technology. A key design point: `voice-cloning` enforces consent at the type
level. The `ConsentRecord` type carries consent status, scope, and ownership
information; cloning and conversion operations require it as a parameter. This
means a missing consent record is a compile error, not a runtime failure. The
`WatermarkConfig`/`WatermarkResult` types in the same sub-module embed
provenance watermarks in cloned voice output for traceability.

### 8.1 Voice cloning (`voice-cloning`)

Synthetic voice models with structural consent gating. **`VoiceSample`**
(`AudioFormat`, `SampleQuality`) / **`SampleCollection`**. Feature extraction:
**`VoiceFeatures`** aggregating **`PitchFeatures`**, **`FormantFeatures`**,
**`TimbreFeatures`**, **`SpectralFeatures`**; **`SpeakerEmbedding`** /
**`EmbeddingSimilarity`**. Training: **`TrainingJob`** (`TrainingStatus`,
`TrainingConfig`, `TrainingProgress`), **`FewShotResult`**, **`ZeroShotResult`**
(`VoiceDescription`, `VoiceGender`, `AgeRange`, `VoiceCharacter`),
**`FineTuneResult`**. Model lifecycle: **`VoiceModelHistory`**
(`VoiceModelVersion`), **`ExportedModel`** (`ModelFormat`: onnx / torchscript /
tflite / coreml / internal), **`ImportResult`**.

**Consent and ownership** — **`ConsentRecord`** (`ConsentStatus`: pending /
granted / denied / revoked / expired; `ConsentScope`) and
**`ConsentVerification`** make consent a checkable structure;
**`VoiceOwnershipRecord`** / **`OwnershipTransfer`** /
**`OwnershipVerification`** track ownership; **`WatermarkConfig`**
(`WatermarkStrength`: subtle / moderate / strong) / **`WatermarkResult`** embed
provenance watermarks.

### 8.2 Voice conversion (`voice-conversion`)

Speaker-identity conversion preserving content. **`VoiceProfile`** is the
target; **`RealtimeConversionState`** / **`RealtimeConversionResult`** and
**`OfflineConversionResult`** are the two modes (`ConversionQuality`: draft /
standard / high / ultra). Stages: **`SourceAnalysisResult`**,
**`TargetMatchResult`**, **`ConversionParameters`**,
**`PitchPreservationResult`**. Transformations: **`ExpressionTransferResult`**
(`ExpressionProfile`, `EmotionCategory`), **`AccentModificationResult`**
(`AccentProfile`, `AccentType`, `VowelShift`, `ConsonantRule`,
`ProsodicPattern`), **`AgeTransformResult`**, **`GenderTransformResult`**
(`GenderTarget`), **`EmotionalToneResult`**, **`SingingConversionResult`**,
**`SpeechToSingingResult`** (`DetectedNote`, `MelodyNote`),
**`WhisperConversionResult`**, **`NoiseRobustResult`** (`NoiseType`).

### 8.3 Text-to-speech (`tts`)

Multi-language TTS. Pipeline: **`TextNormalizationResult`** (`NormalizedToken`)
→ **`PhonemizationResult`** (`PhonemeToken`) → **`SynthesisResult`**
(`SynthesisConfig`, `TTSEngineState`). `SupportedLanguage` enumerates the
language set; **`LanguageDetectionResult`** (`LanguageCandidate`,
`LanguageProfile`). SSML: **`SSMLParseResult`** (`SSMLNode`, `SSMLTagName`,
`SSMLProsodyParams`, `SSMLBreak`, `SSMLEmphasis`, `SSMLSayAs`). Prosody and
emotion: **`ProsodyAdjustment`** (`ProsodyContour`, `ProsodyRange`),
**`EmotionAnalysis`** (`EmotionType`, `EmotionSpec`, `EmotionProsodyMapping`,
`EmotionTransition`). Voices: **`CharacterVoiceLibrary`** (`CharacterVoice`,
`CharacterVoicePreset`), **`MixedVoiceStyle`** (`VoiceStyleComponent`,
`StyleBlendConfig`). Pronunciation control: **`PronunciationDictionary`**
(`PronunciationEntry`), **`PhonemeSequenceControl`** (`PhonemeControl`,
`PhonemeTimingAdjustment`), **`PauseSpec`** / **`BreathSpec`** (`PauseType`,
`BreathType`).

### 8.4 Text-to-singing (`text-to-singing`)

Singing synthesis from lyrics and melody. **`MelodyNote`**, **`LyricSyllable`**,
**`AudioBuffer`** are the inputs. **`LyricsToMelodyResult`** (`VocalRange`),
**`MelodyGuidedResult`**, **`PitchAccuracyResult`**. Expressive techniques:
**`VibratoResult`** (`VibratoStyle`: classical / pop / opera / gospel / rock /
jazz / none), **`BreathSimResult`** (`BreathEvent`, `BreathIntensity`,
`BreathPosition`), **`RegisterTransitionResult`** (`VocalRegister`: chest / head
/ mixed / falsetto / whistle / fry; `RegisterSegment`), **`BeltingResult`**
(`BeltingIntensity`), **`FalsettoResult`**, **`VocalEffectResult`**
(`VocalEffect`: fry / growl / rasp / distortion / scream / whisper / creak),
**`MelismaResult`** (`MelismaPattern`), **`RiffResult`** (`RiffStyle`),
**`GenreVocalConfig`** (`VocalGenre`).

### 8.5 Vocal processing (`vocal-processing`)

Vocal effects rack. **`PitchCorrectionResult`** (`MusicalScale`, `NoteName`) and
**`NaturalPitchCorrectionResult`** (transparent vs hard tuning),
**`TimeAlignmentResult`**, **`DeEssingResult`**, **`BreathReductionResult`**
(`BreathRegion`), **`PlosiveRemovalResult`** (`PlosiveRegion`),
**`SibilanceControlResult`** (`SibilanceBand`), **`ReverbRemovalResult`**,
**`NoiseReductionResult`** (`WindowFunction`), **`VocalIsolationResult`**,
**`FormantShiftResult`**, **`DoublingResult`**, **`HarmonyResult`**
(`HarmonyVoiceCharacter`: soprano / alto / tenor / bass / unison),
**`VocalChopResult`** (`ChopPattern`, `ChopPosition`), **`VocoderResult`**
(`VocoderMode`: classic / phase / channel / formant).

### 8.6 Choir (`choir`)

Ensemble vocal synthesis. **`ChoirVoice`** (`VoicePart`: soprano / alto / tenor
/ bass; `VoicePartRange`). Core operations: **`ChoirMultiplicationResult`**,
**`SectionBalancingResult`**, **`TimingVariationResult`**,
**`PitchVariationResult`**, **`RoomPositioningResult`** (`Position3D`),
**`BreathCoordinationResult`**, **`VowelMatchingResult`** (`VowelType`,
`VowelFormants`), **`ConsonantAlignmentResult`**. Genre presets:
**`GospelChoirResult`**, **`ClassicalChoirResult`**,
**`PopVocalStackingResult`**, **`BarbershopQuartetResult`** (`BarbershopPart`:
lead / tenor / baritone / bass), **`GregorianChantResult`** (`ChantMode`:
monophonic / parallel-organum / free-organum / melismatic),
**`ACappellaResult`** (`ACappellaRole`), **`EnsembleBlendResult`**.

### 8.7 Voice analysis (`voice-analysis`)

Vocal-performance analysis. **`PitchDetectionResult`**, **`VocalRangeResult`**,
**`VoiceClassificationResult`** (`VoiceType`), **`FormantAnalysisResult`**
(`FormantFrame`), **`BreathinessResult`**, **`VibratoResult`**
(`VibratoSegment`), **`VocalEffortResult`**, **`IntonationResult`**,
**`TimingResult`** (`OnsetInfo`), **`ExpressionResult`** (`ExpressionType`),
**`VocalHealthResult`** (`VocalHealthFlag`), **`FatigueResult`**
(`FatigueSegment`), **`TechniqueResult`** (`TechniqueAspect`, `TechniqueScore`),
**`StyleFingerprintResult`** (`StyleFingerprint`), **`ComparisonResult`**
(`ComparisonDimension`).

---

## 9. `@euterpe/ai-scoring` — AI Music Generation for Film & Games

`@euterpe/ai-scoring` was added in Phase 70.6, after the Phase 38 foundational
libraries, to address the specific needs of film and game production workflows.
Where `@euterpe/score` provides the composition tooling and leitmotif system,
`ai-scoring` drives external AI music generators (Suno, Udio, AIVA, Boomy,
Google Lyria) and shapes their output to picture and game state. Unlike the
Phase 38 libraries, `ai-scoring` uses a flat `src/lib/` layout rather than
per-feature sub-module directories. The barrel (`src/index.ts`) re-exports each
module with its constants, factory functions, and types.

**Provider adapters** — one module per generator, each exporting an adapter
class, a `create*` factory, job-state / model / profile constants, and request /
result / payload types:

- `suno-provider-adapter` — `SunoAiScoringProviderAdapter`,
  `SUNO_AI_SCORING_MODELS`, `SUNO_AI_SCORING_STYLE_PROFILES`,
  `SUNO_AI_SCORING_VOCAL_MODES`, `SUNO_AI_SCORING_JOB_STATES`.
- `udio-provider-adapter` — `UdioAiScoringProviderAdapter`,
  `UDIO_AI_SCORING_MODELS`, `UDIO_AI_SCORING_LYRICS_MODES`,
  `UDIO_AI_SCORING_STRUCTURE_PROFILES`.
- `aiva-provider-adapter` — `AivaAiScoringProviderAdapter`, with
  `AIVA_AI_SCORING_LICENSE_TIERS` among its constants.
- `boomy-provider-adapter`, `google-lyria-provider-adapter` — analogous
  adapters.

**Orchestration and scoring modules** (`src/lib/`): `ai-scoring-foundation`
(`AI_SCORING_PROVIDERS`, `AI_SCORING_CAPABILITIES`, `AI_SCORING_WORKFLOWS`,
`createAiScoringLibraryManifest`), `multi-provider-ensemble-routing`,
`generation-cost-optimizer`, `prompt-to-score-pipeline`, `scene-mood-analyzer`,
`tempo-intensity-matching`, `style-consistent-generation`, `leitmotif-system`,
`adaptive-game-music-system`, `music-to-video-sync`,
`generated-music-stem-separation`, `commercial-licensing-verification`,
`midi-export-for-daw-refinement`. Each module ships its own implementation file
and a co-located spec.

---

## 10. Other Implemented Libraries (Summary)

Sections 2–9 above document the seven foundational libraries plus
`@euterpe/ai-scoring` at full type-level depth. The remaining 24 implemented
libraries — `@euterpe/virtuoso`, `stage`, `conservatory`, `score`, `collab`,
`discover`, `chain`, `synth`, `lyrics`, `iot`, `agents`, `distribution`,
`sacred`, `history`, `philosophy`, `acoustics`, `protect`, `video`, `samples`,
`restore`, `marketing`, `analytics`, `transcribe`, `guitar`, `access`, `podcast`
— follow the same construction as the core seven: per-feature sub-modules under
`src/`, each with a `types.ts` plus implementation and spec files,
barrel-exported from `src/index.ts`. Their sub-module sets are listed in §1.1.
Their product-facing feature surface is documented in `features.md`; this
specification does not re-enumerate every type for them.

Three libraries have notable domain-boundary implications worth calling out
explicitly:

- **`@euterpe/virtuoso`** owns AI virtual-artist catalogue, avatar, and business
  concerns. It is a companion to the Calliope domain: Calliope owns persona
  psychology, fandom, and career arc; Virtuoso owns the music catalog, release
  pipeline, and avatar.
- **`@euterpe/protect`** performs originality, deepfake, and plagiarism
  **analysis** and scoring; legal copyright adjudication is out of scope and
  delegated to the Themis domain (Music Shield and Universal Originality Shield,
  Phase 74).
- **`@euterpe/chain`** composes on-chain rights and royalty data structures and
  verifies on-chain state. It holds no private keys and broadcasts no
  transactions — those are the host application's responsibility.

---

## 11. Persistence, Configuration, and Runtime

This section summarises the operational contract engineers must respect when
working on or consuming Euterpe libraries.

- **Persistence.** Euterpe persists nothing. Project, version, and asset models
  exist as in-memory types (`@euterpe/studio` `project-management`,
  `@euterpe/collab` `project-mgmt`); durable storage is the host application's
  responsibility. There is no database, no migration, no ORM schema.
- **Configuration.** No Euterpe source file reads `process.env`. There are no
  Euterpe environment variables. Behaviour is driven entirely by the typed
  config objects passed into each function. This keeps libraries environment-
  agnostic and fully testable without environment setup.
- **Build.** Nx `@nx/js:tsc` executor, output to `dist/libs/euterpe/<library>`.
  ESM, strict TypeScript.
- **Testing.** Vitest, one `vitest.config.ts` per library, co-located
  `*.spec.ts` files.
- **Runtime.** Pure-functional, immutable data structures. No event bus, no
  background workers, no message queue.

---

## 12. Cross-Domain Integration

Euterpe libraries are consumed by other Oshun domains and by the V2 game stack.
High-level integration relationships are described in `architecture.md`
§"Cross-Domain Integration Points" and `features.md`. This section documents the
two V2 bridge services that are concretely implemented and have their own
`package.json`, `project.json`, and test files under `V2/services/`.

- **V2 commentary mix ducking** — `apps/v2/euterpe-commentary-ducking` consumes
  `@euterpe/master` mastering primitives (loudness delta, dB/linear gain,
  sidechain envelope) and `@euterpe/accompany` dynamic-music context to duck
  `V2.DynamicMusic` under `V2.Commentary`. The bridge is off-rollback and emits
  only audio-mix automation.
- **V2 karaoke + rhythm-combat fusion** — `@v2/karaoke-rhythm-combat-bridge`
  (`apps/v2/karaoke-rhythm-combat-bridge`) consumes `@euterpe/genesis`,
  `@euterpe/accompany`, and `@euterpe/protect` for procedural backing-track
  source material, adaptive accompaniment, and streamer-safe music swap (the
  protect gate fails any swap that is not streamer-safe). The bridge exports
  only cook-time manifests; V2 owns final scoring thresholds and rollback state.
  CI coverage is anchored by
  `V2/ue/Tools/check-v2-karaoke-rhythm-combat-bridge.py`.

### 12.1 V2 Karaoke Pitch And Scoring Rubric Surface

The **V2 Karaoke Pitch And Scoring Rubric Surface** is the cook-time output of
`@v2/karaoke-rhythm-combat-bridge` that turns Euterpe music intelligence into
the deterministic **pitch and rhythm scoring rubric** the V2 karaoke and
rhythm-combat modes evaluate at runtime. The rubric is a pure, deterministic
summary (`deterministic: true`): given a melody (from `@euterpe/genesis`
`generateMelodyFromLyrics`), an adaptive-accompaniment context (from
`@euterpe/accompany`), and an originality clearance (from `@euterpe/protect`),
it emits fixed pitch-tolerance cents, timing-tolerance milliseconds,
perfect/good hit windows, groove-lock minimums, and pitch/timing/style weights.
Calliope sound-design (`@calliope/sound-design`) and Iris voice (`@iris/voice`)
supply the guide-voice and mix layers.

Because the rubric is deterministic, the V2 engine can reproduce identical
scoring across clients and replays without re-running any Euterpe service
mid-match. The surface is **off rollback**: it is produced at cook time only,
the bridge guards every call with a `calledFromLiveCombatFrame` check
(`rejectsLiveCombatFrameRpc: true`, `mayInfluenceRollback: false`), and the
rubric manifest targets the `V2Mode_Karaoke`, `V2Mode_RhythmCombat`, and
`V2DynamicMusic` runtimes without ever feeding deterministic combat simulation
or rollback inputs. The integration contract is specified in full at
`V2/docs/integration/karaoke-rhythm-combat-bridge.md`.

Both V2 bridge services exist under `V2/services/` with their own
`package.json`, `project.json`, and specs.

---

## 13. Acceptance Criteria

Before merging any change to an Euterpe library, all of the following conditions
must hold. These criteria are not aspirational — they are the minimum bar for a
change to be considered complete.

A change to an Euterpe library is acceptable when:

1. The package builds via `@nx/js:tsc` to `dist/libs/euterpe/<library>` with no
   type errors under strict mode.
2. `pnpm nx lint <project>` passes.
3. The library's Vitest suite passes; new behaviour is covered by tests that
   assert specific computed values (e.g. a known Forte number for a pitch-class
   set, a known LUFS for a reference buffer), not merely shape or truthiness.
4. Public functions have real domain-specific implementations — no stubs,
   placeholders, or `Math.random()` standing in for a computed result.
5. Inter-package use stays within the established dependency direction (see
   `architecture.md`): a lower layer never imports a higher one.
6. Consent-gated voice operations (`@euterpe/voice` `voice-cloning`) continue to
   require a `ConsentRecord`.