# bazedfrog/songgeneration-studio architecture

> Architecture diagram of the GitHub repository bazedfrog/songgeneration-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bazedfrog/songgeneration-studio
- Repository: https://github.com/bazedfrog/songgeneration-studio

## Overview

SongGeneration Studio is a local web app for creating complete AI-generated songs. A creator configures lyrics and style in the browser, optionally uploads reference audio, and submits a generation that the API queues and the generation service sends to the persistent LeVo model server. Results feed the song library for playback and export. The README also advertises model selection, batch queueing, stem output, and cover/metadata management. Some backend wiring and UI behavior are unsampled, so uncertain links are omitted.

Main entry points: [`web/static/app.js`](https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/app.js) (Studio interface), [`main.py`](https://github.com/bazedfrog/songgeneration-studio/blob/main/main.py) (FastAPI routes), [`generation.py`](https://github.com/bazedfrog/songgeneration-studio/blob/main/generation.py) (Generation workflow), [`patches/gradio/levo_inference_lowmem.py`](https://github.com/bazedfrog/songgeneration-studio/blob/main/patches/gradio/levo_inference_lowmem.py) (LeVo inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_studio["Studio interface<br/>[app.js]"]
  node_ui_components["Audio and song UI<br/>[components.js]"]
  node_ui_hooks["Client state hooks<br/>[hooks.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_backend["API and workflow"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_generation["Generation workflow<br/>[generation.py]"]
  node_timing["Timing estimates<br/>[timing.py]"]
end

subgraph group_inference["Music inference"]
  node_model_server["Model server<br/>[model_server.py]"]
  node_levo["LeVo inference"]
  node_builders["Model builders<br/>[builders.py]"]
  node_demucs["Audio separation<br/>[apply.py]"]
end

subgraph group_results["Library and outputs"]
  node_song_library[("Song library<br/>[generation.py]")]
  node_audio_outputs["Generated audio<br/>[main.py]"]
  node_cover_video["Cover and video export<br/>[main.py]"]
end

node_creator(("Music creator"))
node_reference_audio["Reference audio"]

node_creator -->|"configures songs"| node_studio
node_studio -->|"renders controls"| node_ui_components
node_studio -->|"tracks state"| node_ui_hooks
node_studio -->|"requests data"| node_api_client
node_api_client -->|"calls routes"| node_api
node_reference_audio -->|"uploads reference"| node_api
node_api -->|"submits work"| node_generation
node_generation -->|"requests generation"| node_model_server
node_generation -->|"records timing"| node_timing
node_model_server -->|"runs inference"| node_levo
node_levo -->|"builds models"| node_builders
node_levo -.->|"separates audio"| node_demucs
node_generation -->|"updates generations"| node_song_library
node_api -->|"lists generations"| node_song_library
node_api -->|"serves audio"| node_audio_outputs
node_api -->|"serves exports"| node_cover_video
node_song_library -->|"refreshes library"| node_studio
node_studio -->|"fetches status"| node_api_client

click node_studio "https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/app.js"
click node_ui_components "https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/components.js"
click node_ui_hooks "https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/hooks.js"
click node_api_client "https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/api.js"
click node_api "https://github.com/bazedfrog/songgeneration-studio/blob/main/main.py"
click node_generation "https://github.com/bazedfrog/songgeneration-studio/blob/main/generation.py"
click node_timing "https://github.com/bazedfrog/songgeneration-studio/blob/main/timing.py"
click node_model_server "https://github.com/bazedfrog/songgeneration-studio/blob/main/model_server.py"
click node_levo "https://github.com/bazedfrog/songgeneration-studio/blob/main/patches/gradio/levo_inference_lowmem.py"
click node_builders "https://github.com/bazedfrog/songgeneration-studio/blob/main/patches/builders.py"
click node_demucs "https://github.com/bazedfrog/songgeneration-studio/blob/main/patches/demucs/apply.py"
click node_song_library "https://github.com/bazedfrog/songgeneration-studio/blob/main/generation.py"
click node_audio_outputs "https://github.com/bazedfrog/songgeneration-studio/blob/main/main.py"
click node_cover_video "https://github.com/bazedfrog/songgeneration-studio/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_studio,node_ui_components,node_ui_hooks,node_api_client toneBlue
class node_api,node_generation,node_timing toneAmber
class node_model_server,node_levo,node_builders,node_demucs toneMint
class node_song_library,node_audio_outputs,node_cover_video toneRose
class node_creator,node_reference_audio toneIndigo
```

## Components

### Web experience

- [Studio interface](https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/app.js): `web/static/app.js`
- [Audio and song UI](https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/components.js): `web/static/components.js`
- [Client state hooks](https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/hooks.js): `web/static/hooks.js`
- [API client](https://github.com/bazedfrog/songgeneration-studio/blob/main/web/static/api.js): `web/static/api.js`

### API and workflow

- [FastAPI routes](https://github.com/bazedfrog/songgeneration-studio/blob/main/main.py): `main.py`
- [Generation workflow](https://github.com/bazedfrog/songgeneration-studio/blob/main/generation.py): `generation.py`
- [Timing estimates](https://github.com/bazedfrog/songgeneration-studio/blob/main/timing.py): `timing.py`

### Music inference

- [Model server](https://github.com/bazedfrog/songgeneration-studio/blob/main/model_server.py): `model_server.py`
- [LeVo inference](https://github.com/bazedfrog/songgeneration-studio/blob/main/patches/gradio/levo_inference_lowmem.py): `patches/gradio/levo_inference_lowmem.py`
- [Model builders](https://github.com/bazedfrog/songgeneration-studio/blob/main/patches/builders.py): `patches/builders.py`
- [Audio separation](https://github.com/bazedfrog/songgeneration-studio/blob/main/patches/demucs/apply.py): `patches/demucs/apply.py`

### Library and outputs

- [Song library](https://github.com/bazedfrog/songgeneration-studio/blob/main/generation.py): `generation.py`
- [Generated audio](https://github.com/bazedfrog/songgeneration-studio/blob/main/main.py): `main.py`
- [Cover and video export](https://github.com/bazedfrog/songgeneration-studio/blob/main/main.py): `main.py`

### Other components

- **Music creator**
- **Reference audio**

## Connections

- Music creator → Studio interface: configures songs
- Studio interface → Audio and song UI: renders controls
- Studio interface → Client state hooks: tracks state
- Studio interface → API client: requests data
- API client → FastAPI routes: calls routes
- Reference audio → FastAPI routes: uploads reference
- FastAPI routes → Generation workflow: submits work
- Generation workflow → Model server: requests generation
- Generation workflow → Timing estimates: records timing
- Model server → LeVo inference: runs inference
- LeVo inference → Model builders: builds models
- LeVo inference → Audio separation: separates audio
- Generation workflow → Song library: updates generations
- FastAPI routes → Song library: lists generations
- FastAPI routes → Generated audio: serves audio
- FastAPI routes → Cover and video export: serves exports
- Song library → Studio interface: refreshes library
- Studio interface → API client: fetches status