# Orpheus: Your AI Co-Producer

Orpheus is an AI-powered music creation assistant that helps you write, generate, and collaborate on new music. It combines the power of large language models for creative brainstorming with a robust music generation API to turn your ideas into audible tracks.

The application features a real-time chat interface where you can interact with the assistant, generate songs, create covers, get help with lyrics, and manage your creative workflow.

## Key Features

- **Conversational AI**: Chat with a co-producer AI persona to get ideas and feedback.
- **Song Generation**: Create full songs from a text prompt, specifying style, title, and lyrics.
- **Song Covers & Extensions**: Transform existing songs into different styles or extend them with new sections.
- **Lyrics Generation**: Get help writing or refining lyrics for your tracks.
- **Real-time Progress**: The UI provides live updates as your songs are being generated, from "pending" to "streaming" to "complete."
- **Persistent Chat History**: Each chat session is saved, allowing you to reference past creations.

---

## Architecture

The application is built with a decoupled frontend and backend architecture to enable a responsive user experience with background processing for long-running tasks like music generation.

```mermaid
graph TD
    User["👤 User"] --> FE["🖥️ Frontend<br/>(JavaScript)"]
    
    FE --> |"POST /api/chat/{uuid}/message"| BE["⚙️ FastAPI Backend<br/>(Python)"]
    FE --> |"GET /api/chat/{uuid}/messages<br/>(polling)"| BE
    
    BE --> |"Store messages"| ChatDB[("📁 Chat History<br/>(JSONL files)")]
    
    BE --> |"Process user message"| OpenAI["🤖 OpenAI GPT-4<br/>(Assistant with tools)"]
    
    OpenAI --> |"Function calls"| Tools["🛠️ Tool Execution"]
    
    Tools --> SunoAPI["🎵 Suno Studio API<br/>(Music Generation)"]
    Tools --> |"Search chat history"| ChatDB
    Tools --> |"Get clip details"| SunoAPI
    
    SunoAPI --> |"Async song generation"| BG["⏳ Background Tasks<br/>(Polling & Updates)"]
    
    BG --> |"Update pending messages"| ChatDB
    
    BE --> |"Return messages"| FE
    
    FE --> |"Direct polling for audio<br/>(client-side)"| SunoAPI
    
    subgraph "💿 Music Generation Flow"
        SunoAPI --> |"Generate song"| Audio["🎧 Audio URL"]
        SunoAPI --> |"Generate lyrics"| Lyrics["📝 Lyrics"]
        SunoAPI --> |"Create covers"| Covers["🎭 Song Covers"]
    end
    
    subgraph "🔄 Real-time Updates"
        FE --> |"Message polling<br/>(1-3s intervals)"| BE
        FE --> |"Audio status polling<br/>(5s intervals)"| SunoAPI
    end
    
    style User fill:#4a90e2
    style FE fill:#7b68ee
    style BE fill:#ff6b6b
    style OpenAI fill:#4ecdc4
    style SunoAPI fill:#45b7d1
    style ChatDB fill:#96ceb4
    style BG fill:#feca57
```

---

## Song Creation Sequence

This diagram illustrates the step-by-step process of generating a new song, from the user's initial prompt to the final audio playback. It highlights the parallel polling mechanisms that enable real-time updates.

```mermaid
sequenceDiagram
    participant User
    participant Frontend as "Frontend<br/>(JavaScript)"
    participant Backend as "FastAPI<br/>Backend"
    participant OpenAI as "OpenAI<br/>GPT-4"
    participant SunoAPI as "Suno Studio<br/>API"
    participant ChatDB as "Chat Storage<br/>(JSONL)"

    User->>Frontend: "Create a song about love"
    Frontend->>Backend: POST /api/chat/{uuid}/message<br/>{"content": "Create a song...", "token": "..."}
    
    Backend->>ChatDB: Store user message
    Backend->>ChatDB: Store pending assistant message
    Backend-->>Frontend: Return messages (with pending)
    
    Note over Frontend: Shows "Orpheus is working..."
    
    Backend->>OpenAI: Chat completion with tools<br/>+ chat history context
    OpenAI->>Backend: Response with function call:<br/>"generate_song"
    
    Backend->>Backend: Update pending message:<br/>"Executing tool: generate_song"
    
    Backend->>SunoAPI: POST /api/generate/v2-web<br/>{"prompt": "...", "tags": "...", "title": "..."}
    SunoAPI->>Backend: {"clips": [{"id": "clip-123", "status": "pending"}]}
    
    Backend->>ChatDB: Update message with clip info<br/>+ song:clip-123 reference
    
    par Background Polling
        Backend->>SunoAPI: GET /api/feed/v2?ids=clip-123
        SunoAPI->>Backend: {"clips": [{"status": "streaming", "audio_url": "..."}]}
        Backend->>ChatDB: Update clip with audio URL
        
        Backend->>SunoAPI: GET /api/feed/v2?ids=clip-123
        SunoAPI->>Backend: {"clips": [{"status": "complete", "audio_url": "..."}]}
        Backend->>ChatDB: Mark song as complete
    and Frontend Message Polling
        loop Every 1-3 seconds
            Frontend->>Backend: GET /api/chat/{uuid}/messages
            Backend->>Frontend: Updated messages array
            Note over Frontend: Updates UI with new content
        end
    and Frontend Audio Polling
        loop Every 5 seconds
            Frontend->>SunoAPI: GET /api/v2/external/oauth/clips?ids=clip-123
            SunoAPI->>Frontend: Clip status + audio URL
            Note over Frontend: Updates audio player when ready
        end
    end
    
    Note over Frontend: Shows audio player with<br/>completed song
    
    Frontend->>User: 🎵 Song ready to play!
```