Document instrument selector requirement

2026-09-13 02:42:49 +02:00
commit 57867bb3cc
6 changed files with 495 additions and 0 deletions
@@ -0,0 +1,68 @@
 # Agent Guide
 This file is the permanent operating guide for any coding agent working on this
 project.
 ## Project Scope
 - This project is a native macOS application.
 - The minimum deployment target is macOS 14.0.
 - Use Swift and SwiftUI according to the architecture documented for this
  project.
 - Do not invent undocumented features or requirements.
 - Any substantial change to the architecture or product scope must be documented
  before implementation.
 ## Required Reading
 Before making significant changes, read:
 - `docs/PRODUCT.md`
 - `docs/ARCHITECTURE.md`
 - `docs/DATA_MODEL.md`
 - `docs/TASKS.md`
 - `docs/OPEN_QUESTIONS.md`
 Use these documents as the project references:
 - `docs/PRODUCT.md` is the source of truth for product requirements.
 - `docs/ARCHITECTURE.md` is the reference for architecture decisions.
 - `docs/DATA_MODEL.md` is the reference for data models.
 - `docs/TASKS.md` is the reference for implementation phases and tasks.
 - `docs/OPEN_QUESTIONS.md` contains decisions that are not resolved yet.
 ## Decision Rules
 - If documents conflict, do not guess. State the conflict before making a
  decision.
 - Do not decide anything listed in `docs/OPEN_QUESTIONS.md` on your own.
 - Do not automatically move to a new phase in `docs/TASKS.md` unless explicitly
  asked.
 - Update `docs/TASKS.md` when tasks are completed.
 - Preserve version history and the Song Project concept as documented.
 ## Code Standards
 - Write organized code that is maintainable and extensible.
 - Keep clear separation between UI, Models, Services, Persistence, and
  Integrations.
 - Keep OpenAI, instrument catalog/selector, and Suno integrations separated from
  UI logic as much as possible.
 - In the current scope, Suno handoff fills the fields only and does not press
  Generate.
 - Do not modify files outside the task scope without a clear reason.
 - Do not perform a broad refactor while implementing a small task unless it is
  explicitly required.
 ## Secrets And Configuration
 - Do not place API keys, tokens, or secrets in source code or Git.
 - Read secrets only from secure environment or configuration mechanisms.
 - Do not log secrets.
 ## Verification
 - Run a build after code changes.
 - Run relevant tests when they are available.
 - Do not consider a task complete if the project fails to build because of new
  changes.
@@ -0,0 +1,85 @@
 # Architecture --- Initial Direction
 ## Principle
 Keep UI, domain data, AI orchestration, external integrations and
 persistence separated. Do not hard-code provider behavior into SwiftUI
 views.
 ## Suggested Layers
 ``` text
 macOS App
 ├── Presentation (SwiftUI)
 ├── Domain
 │   ├── SongProject
 │   ├── SongVersion
 │   ├── Lyrics
 │   ├── SongStructure
 │   ├── Genre/Style
 │   ├── Instrument
 │   ├── Vocal
 │   ├── Arrangement
 │   └── MusicalParameters
 ├── Application Services
 │   ├── AI Director
 │   ├── Prompt Compiler
 │   ├── Instrument Catalog
 │   ├── Arabic Pronunciation Processor
 │   ├── Project Versioning
 │   └── Validation
 ├── Integrations
 │   ├── OpenAI
 │   └── Suno Field-Fill Integration
 └── Persistence
    └── Local project/version storage
 ```
 ## AI Director
 OpenAI receives the user's intent plus private application rules and
 structured project state. AI output should be requested as structured
 data wherever possible, not treated as an unstructured chat transcript.
 ## Prompt Compiler
 A deterministic layer converts the approved SongProject into the final
 Suno-facing lyrics/style content. User choices override AI suggestions.
 ## Security
 -   Never commit API keys to source control.
 -   Keep secrets outside source code.
 -   Design provider clients behind protocols/interfaces so credentials
    and providers can be changed later.
 -   Do not log secrets or full authorization headers.
 ## Suno Boundary
 The initial requirement is browser/site handoff that fills fields but
 does not press Generate. Treat this integration as replaceable because
 website UI/behavior can change.
 ## Instrument Selector Boundary
 Instrument catalog data is structured names and metadata, not SwiftUI
 view code. The Presentation layer may search, filter and toggle
 selections, but catalog loading, search normalization and selected
 instrument state should live in Domain/Application Services and the
 SongProject model.
 Catalog entries should include stable ids, display names,
 family/category, optional region/origin and optional aliases/search
 terms. The catalog should support worldwide coverage across Western,
 Middle Eastern, African, South Asian, East Asian, Southeast Asian, Latin
 American, traditional, folk, orchestral, electronic and modern
 instruments.
 Selected instruments are part of the SongProject and must be available
 to the AI Director and Prompt Compiler so they can influence
 arrangement, roles, entry/exit timing, relevant structure decisions and
 the Suno Style Prompt.
 The current architecture does not include instrument images, audio
 previews, sound samples, playback, Freesound, an Instrument API or
 external API calls for instrument data.
@@ -0,0 +1,87 @@
 # Song Project --- Draft Data Model
 This schema is intentionally provider-neutral and should evolve before
 implementation is locked.
 ``` text
 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.
@@ -0,0 +1,24 @@
 # Open Questions
 These items must be resolved before their dependent implementation is
 finalized.
 -   Resolved: minimum macOS deployment target is macOS 14.0.
 -   Exact Swift/SwiftUI architecture conventions for the repository.
 -   OpenAI model(s) and API endpoint strategy.
 -   Exact private AI rules/system prompt.
 -   Complete genre/style taxonomy and whether it is curated locally or
    AI-assisted.
 -   Complete worldwide instrument catalog taxonomy, family/category
    groups, region/origin coverage, aliases/search terms and maintenance
    strategy.
 -   Exact list of supported languages/dialects for MVP.
 -   Arabic diacritization policy: full tashkeel vs
    pronunciation-targeted tashkeel.
 -   Exact Suno fields to populate and supported handoff mechanism.
 -   Whether Suno integration is permitted/reliable under the intended
    account/workflow and current terms.
 -   Project storage technology and whether cloud sync is required later.
 -   Whether users supply their own OpenAI/API credentials or the product
    owner supplies service credentials.
 -   Authentication/subscription/usage-limit requirements, if any.
@@ -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.
@@ -0,0 +1,135 @@
 # Agent Task Plan --- AI Music Studio macOS
 ## Operating Rule
 Work incrementally. Do not invent product requirements. When a
 requirement is missing and blocks implementation, record it in
 `OPEN_QUESTIONS.md` instead of silently deciding it.
 ## Phase 0 --- Repository Foundation
 -   [x] Inspect existing repository and document current state.
 -   [x] Create/confirm native macOS project structure.
 -   [x] Establish clear Presentation / Domain / Services / Integrations
    / Persistence boundaries.
 -   [x] Add configuration strategy for development secrets without
    committing keys.
 -   [x] Add basic unit-test target.
 -   [x] Ensure project builds cleanly.
 ## Phase 1 --- Domain Model
 -   [ ] Implement `SongProject` and supporting models from
    `DATA_MODEL.md`.
 -   [ ] Model genres/styles as multi-select.
 -   [ ] Model song sections with order and optional timestamps.
 -   [ ] Model instruments, variants, roles and placements.
 -   [ ] Model multiple vocalists and section assignments.
 -   [ ] Model language/dialect and Arabic pronunciation settings.
 -   [ ] Model BPM, key, scale and maqam with Manual/Auto state.
 -   [ ] Model emotional arc and production directions.
 -   [ ] Add serialization tests.
 ## Phase 2 --- Project Persistence & Versions
 -   [ ] Create new/open/save song projects locally.
 -   [ ] Implement project list.
 -   [ ] Implement immutable or snapshot-based version history.
 -   [ ] Restore a previous version without destroying later versions.
 -   [ ] Add autosave strategy that does not create excessive versions.
 ## Phase 3 --- Core macOS UI
 -   [ ] Build project browser.
 -   [ ] Build natural chat workspace as the primary entry point.
 -   [ ] Build editable project inspector for duration, genres,
    instruments, vocals and language.
 -   [ ] Build song structure editor.
 -   [ ] Build arrangement editor supporting section-based and
    timestamp-based placement.
 -   [ ] Add Manual/Auto toggles for supported controls.
 -   [ ] Build final review screen where every generated field can be
    edited.
 ## Phase 4 --- OpenAI Integration
 -   [ ] Create provider-independent `AIService` interface.
 -   [ ] Implement OpenAI client.
 -   [ ] Define private application-rule injection mechanism.
 -   [ ] Define structured AI response schema for SongProject updates.
 -   [ ] Implement idea → complete project generation.
 -   [ ] Implement existing lyrics → correction/improvement flow.
 -   [ ] Implement Auto mode for structure, arrangement, BPM/key/maqam
    and production decisions.
 -   [ ] Implement optional Discuss mode.
 -   [ ] Enforce user-lock/manual-value precedence over AI output.
 -   [ ] Add error, retry, cancellation and rate-limit handling.
 ## Phase 5 --- Arabic Lyrics Processing
 -   [ ] Add Arabic-specific settings UI.
 -   [ ] Support diacritics/harakat/tanween processing.
 -   [ ] Preserve intentional spelling/dialect choices where possible.
 -   [ ] Allow user to compare/edit processed Arabic before Suno handoff.
 -   [ ] Add Arabic test fixtures covering multiple dialects.
 ## Phase 6 --- Instrument Selector & Catalog
 -   [ ] Create structured catalog models for instrument id, name,
    family/category, optional region/origin and aliases/search terms.
 -   [ ] Provide large worldwide catalog data covering Western, Middle
    Eastern, African, South Asian, East Asian, Southeast Asian, Latin
    American, traditional, folk, orchestral, electronic and modern
    instruments.
 -   [ ] Keep catalog data out of SwiftUI views.
 -   [ ] Build searchable instrument browser.
 -   [ ] Add browsing/filtering by family/category.
 -   [ ] Add browsing/filtering by region/origin where useful.
 -   [ ] Add checkbox-based multi-select and deselect behavior.
 -   [ ] Persist selected instruments on the current Song Project.
 -   [ ] Make selected instruments available to OpenAI/song-generation
    logic for arrangement, roles, entry/exit timing, relevant structure
    decisions and Suno Style Prompt generation.
 -   [ ] Preserve existing Manual/Auto arrangement behavior.
 -   [ ] Add tests for catalog search, category/region filtering,
    selection persistence and SongProject serialization.
 ## Phase 7 --- Prompt Compiler
 -   [ ] Create deterministic compiler from approved SongProject → Suno
    output.
 -   [ ] Generate lyrics text with section/performance directives where
    appropriate.
 -   [ ] Generate style prompt from genre blend, instrumentation, vocals,
    tempo, harmony, emotion and production instructions.
 -   [ ] Validate output before handoff.
 -   [ ] Keep compiler independent from UI and OpenAI client.
 ## Phase 8 --- Suno Handoff
 -   [ ] Implement explicit `Send to Suno` action.
 -   [ ] Open the appropriate Suno creation surface.
 -   [ ] Fill supported fields with approved project output.
 -   [ ] Never trigger Generate automatically.
 -   [ ] Detect/report when fields cannot be filled rather than silently
    failing.
 -   [ ] Keep integration isolated because Suno UI can change.
 ## Phase 9 --- Quality
 -   [ ] Add validation for contradictory/invalid project settings.
 -   [ ] Add loading, offline and provider-error states.
 -   [ ] Add accessibility labels and keyboard navigation.
 -   [ ] Test project/version recovery.
 -   [ ] Test AI output against locked user choices.
 -   [ ] Test selected instruments influence compiled song-generation
    context.
 -   [ ] Test Suno handoff without generation.
 ## Definition of MVP Done
 A user can create a macOS song project through chat, manually or
 automatically configure the agreed song parameters, generate/edit lyrics
 and song planning through OpenAI, select instruments, review
 the complete project, save versions, and send the approved lyrics/style
 data to Suno where the app fills fields without initiating generation.