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
- sections[]
- instruments[]
- vocalists[]
- lyrics
- productionDirections[]
- 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[]

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.