Initial commit

docs/PRODUCT.md

@@ -0,0 +1,96 @@
+# 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 opens Suno and fills the appropriate fields. It does not
+    trigger Generate.
+
+## 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 prepares the project and fills Suno fields only. Generated songs do
+not need to return to the app in the initial version.