music-assistant/docs/PRODUCT.md

Product Definition --- AI Music Studio for macOS

Vision

A native macOS application that helps users design a complete song concept through a natural chat interface, using OpenAI as the planning and writing engine, then prepares final lyrics and style instructions.

Core Flow

1. User starts a new song project in a natural chat.
2. User describes the song idea and optionally selects duration, genres/styles, instruments, vocals, language/dialect, structure and musical parameters.
3. OpenAI applies product rules and completes missing creative details. An optional discussion mode lets the AI ask the user before making decisions.
4. User reviews and manually edits every generated component.
5. Project versions are saved.

Song Controls

• Multiple genres/styles can be blended.
• Genres and styles can be selected from a large worldwide catalog with search, category/region browsing and checkbox-based multi-select.
• Instruments can be selected from a large worldwide instrument catalog.
• Instruments can be searched by name, browsed by family/category and browsed by region/origin where useful.
• Multiple instruments can be selected and deselected using checkboxes.
• Selected instruments belong to the current Song Project.
• Each instrument can have a role and entry/exit timing.
• Instrument timing supports both timestamps and song sections.
• Arrangement supports Manual and Auto modes.
• Song structure supports Manual and Auto modes.
• BPM, key/scale and maqam support Manual and Auto modes.
• Multiple vocalists/voices can exist in one song.
• Vocalists can be selected from a local catalog of voice roles and presets using checkbox multi-select.
• User controls vocal gender/type, rap/singing mode, delivery and section-specific performance.
• Multiple languages and dialects can be used in one song.
• Languages can be selected from a large local catalog with search, category browsing and checkbox multi-select.
• Arabic receives dedicated diacritics/harakat/tanween handling for pronunciation.
• Energy and emotional progression can change throughout the song.
• Effects, transitions, build-ups, drops, bass intensity and vocal processing can be manually specified or AI-assisted.

Lyrics

The user can either: - provide only an idea and have AI write the lyrics; or - provide existing lyrics and ask AI to correct, improve, restructure or complete them.

Instrument Selector

The application provides a names-and-metadata Instrument Selector. The catalog should cover as many musical instruments as reasonably possible, including Western, Middle Eastern, African, South Asian, East Asian, Southeast Asian, Latin American, traditional, folk, orchestral, electronic and modern instruments.

Instrument catalog data must not be hardcoded directly inside SwiftUI views. Each catalog entry should support structured metadata:

• id
• name
• family/category
• optional region/origin
• optional aliases/search terms

Selected instruments must be available as part of the Song Project and later available to the OpenAI/song-generation layer so they can influence arrangement, instrument roles, entry/exit timing, song structure where relevant and the final style prompt.

Instrument images, audio previews, sound samples, audio playback, Freesound, an Instrument API and external API calls for instrument data are not part of the current product requirement.

Genre & Style Selector

The application provides a large, curated local catalog of worldwide music genres and styles. Users can search it, browse by category and region/origin where useful, and select or deselect multiple entries with checkboxes. Catalog data is structured and separate from SwiftUI views; it does not require an external API.

Vocalist Selector

The application provides a local catalog of vocalist roles and voice presets. Users can search, browse by category and select or deselect multiple vocalists with checkboxes. Each preset supplies a role label, voice type, gender selection and performance style for the Song Project.

Language Selector

The application provides a large curated local language catalog. Users can search, browse by regional category and select or deselect multiple languages with checkboxes. Removing a language also removes any dialect entries attached to it from the Song Project.

Project Management

Every song is stored as a project. Important changes can create versions so previous states remain recoverable. A project can be deleted after explicit user confirmation.

AI Rules

The product owner has private system rules that govern OpenAI behavior. Normal users cannot view or modify these rules in the initial version.

Initial Boundary

The macOS app prepares and stores the final lyrics and style prompt only. It does not open, embed or control an external music-generation website.