# 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 the final lyrics and style
instructions for Suno.

## 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.
6.  User presses **Send to Suno**.
7.  The app presents the Suno Create page in an app-managed web surface
    in Custom mode and fills the
    supported title, lyrics and style fields. It does not trigger
    Generate. If a field cannot be filled, the app reports that result
    and keeps its approved text ready for the user to copy.

## Song Controls

-   Multiple genres/styles can be blended.
-   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.
-   User controls vocal gender/type, rap/singing mode, delivery and
    section-specific performance.
-   Multiple languages and dialects can be used in one song.
-   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 Suno 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.

## Project Management

Every song is stored as a project. Important changes can create versions
so previous states remain recoverable.

## 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

Suno remains responsible for music generation and playback. The macOS
app opens the browser-based Suno Create page in Custom mode and fills
the supported title, lyrics and style fields only. It never triggers
Generate. If Suno changes its interface and a field cannot be filled,
the app reports that field and keeps the approved text available to
copy. Generated songs do not need to return to the app in the initial
version.