music-assistant/docs/DATA_MODEL.md

Song Project --- Draft Data Model

This schema is intentionally provider-neutral and should evolve before implementation is locked.

SongProject
- id
- title
- idea
- duration
- conversationMode: auto | discuss
- languages[]
- dialects[]
- arabicPronunciationSettings
- genres[]
- moods[]
- emotionalArc[]
- bpm
- key
- scale
- maqam
- structureMode: manual | auto
- sections[]
- instruments[]
- vocalists[]
- lyrics
- productionDirections[]
- productionMode: manual | auto
- sunoOutput
- versions[]
- createdAt
- updatedAt

InstrumentCatalogItem
- id
- name
- familyCategory
- regionOrigin (optional)
- aliases[]
- searchTerms[]

SongSection
- id
- type (intro, verse, preChorus, chorus, bridge, outro, custom)
- title
- startTime
- endTime
- lyrics
- emotion
- energy
- vocalDirection
- productionDirection

InstrumentTrack
- instrumentId
- selected
- variant
- playingStyle
- role
- autoArrangementEnabled
- placements[]

Auto-decision behavior
- The AI may update song sections only when structureMode is auto.
- The AI may update an instrument's role, playing style and placements only
  when autoArrangementEnabled is true for that selected instrument.
- The AI may fill BPM, key, scale and maqam only when their individual
  ManualAutoValue mode is auto.
- The AI may update production directions only when productionMode is auto.
- Manual values remain authoritative when automatic decisions are applied.

Discuss mode behavior
- When conversationMode is discuss, the AI receives the current Song Project
  and conversation context, then returns follow-up questions before a project
  decision is applied.
- A discussion response does not itself modify the Song Project.

InstrumentPlacement
- sectionId (optional)
- startTime (optional)
- endTime (optional)
- direction

Vocalist
- id
- label
- voiceType
- genderSelection
- performanceStyle
- assignedSections[]

SunoOutput
- lyricsText
- stylePrompt
- additionalFields
- generatedAt

Override Rule

Explicit user values are authoritative. AI may fill missing values or propose changes, but must not silently replace locked/manual user choices.