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.

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.

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:

Note — fully specified note:

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 ChannelMixPresets, 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 InstrumentTracks holds TimedHits 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.