commit 57867bb3cccf9aeeebd53c194d66c1bf3d4b5ede Author: Codex Date: Sun Sep 13 02:41:58 2026 +0200 Document instrument selector requirement diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d5f34e7 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..84556ec --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -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. diff --git a/docs/DATA_MODEL.md b/docs/DATA_MODEL.md new file mode 100644 index 0000000..31bf731 --- /dev/null +++ b/docs/DATA_MODEL.md @@ -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. diff --git a/docs/OPEN_QUESTIONS.md b/docs/OPEN_QUESTIONS.md new file mode 100644 index 0000000..71873d2 --- /dev/null +++ b/docs/OPEN_QUESTIONS.md @@ -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. diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md new file mode 100644 index 0000000..86f010b --- /dev/null +++ b/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. diff --git a/docs/TASKS.md b/docs/TASKS.md new file mode 100644 index 0000000..f253bc6 --- /dev/null +++ b/docs/TASKS.md @@ -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.