Document instrument selector requirement
This commit is contained in:
Codex
@@ -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.
|
||||
+135
@@ -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.
|
||||
Reference in New Issue
Block a user