Create	Models	Training
Generate music from text or full custom parameters	One-click model downloads and management	LoRA fine-tuning with dataset management

• Text-to-Music (Simple Mode) — describe what you want, get a song
• Custom Mode — full control over caption, lyrics, BPM, key, time signature, duration
• Remix (Cover) — upload or pick an existing song, transform it with AI
• Repaint — selectively regenerate portions of existing audio
• Extract — isolate individual tracks (vocals, drums, bass, etc.)
• Lego — generate a new track layer based on audio context
• Complete — fill in missing track classes for a partial mix
• AutoGen — automatic batch generation with optional auto-save

• Conversational music generation — chat naturally to describe what you want to hear
• Multiple LLM providers — built-in MLX (Apple Silicon), Ollama (install separately), OpenAI and Anthropic via your API key
• Conversation history — pick up where you left off with saved chat sessions
• Auto-titling — conversations are automatically named based on content

• Jukebox mode — continuous, hands-free music generation
• Station presets & custom stations — create stations with specific genres, moods, and parameters
• Auto-save to playlists — automatically collect generated tracks
• Radio ambiance — vinyl crackle, static, and brown noise effects for that analog feel

• Library — browse, search, filter, rate, and organize your generated music
• Playlists — create playlists with drag-and-drop reordering
• Full Audio Player — mini-player, full-screen overlay, queue, keyboard shortcuts

• Model management — one-click downloads, model switching, and status tracking from the Models page
• HeartMuLa backend — alternative generation engine with great lyrics controllability
• LoRA fine-tuning — fine-tune models on your own audio datasets with presets

• 11 built-in themes — Midnight, Daylight, Ocean, Sunset, Sakura, Neon, Retro, Ember, Cafe, Vapor, Slate
• Custom themes — import your own CSS themes
• GPU throttle tuning — some tricks to minimize audio stuttering on Apple Silicon unified memory during continous generation

git clone https://github.com/proximasan/tadpole-studio.git
cd tadpole-studio
python3 start.py        # macOS / Linux
python start.py         # Windows

That's it. The launcher:

• Checks prerequisites (Python, uv, Node.js, pnpm)
• Installs dependencies automatically on first run
• Starts the backend (port 8000) and frontend (port 3000)
• Opens your browser automatically once ready

On first launch the backend auto-downloads the default models from HuggingFace (~10 GB total):

• acestep-v15-turbo — DiT music generation model
• acestep-5Hz-lm-1.7B — lyrics formatting language model
• Qwen2.5-1.5B-Instruct-4bit — chat LLM for AI DJ & title generation

Make sure you have at least 10 GB of free disk space.

Press Ctrl+C to stop both servers.

The default turbo DiT (8-step) and 1.7B LM auto-download at startup. Additional models are available from the Models page:

DiT models — turbo (default), turbo-shift1, turbo-shift3, turbo-continuous, sft (50-step), base (50-step)

Language models — 1.7B (default), 0.6B (lightweight), 4B (best quality)

Recommended LM model by VRAM:

HeartMuLa is also available as an alternative backend with its own 3B model (~21 GB download). It uses lazy-loading on macOS to fit in memory but runs slowly on Apple Silicon — a CUDA GPU is recommended for HeartMuLa.

python3 start.py --install   # Force reinstall all dependencies
python3 start.py --no-open   # Don't auto-open browser

git pull
python3 start.py        # macOS / Linux
python start.py         # Windows

The launcher automatically detects dependency changes after git pull and reinstalls as needed — including CUDA PyTorch on Windows.

To force a full reinstall: python3 start.py --install

# Backend
cd backend
uv sync
uv sync --extra cloud-llm   # Optional: adds OpenAI & Anthropic for AI DJ
uv run tadpole-studio       # Starts on :8000

# Frontend (separate terminal)
cd frontend
pnpm install
pnpm dev                     # Starts on :3000

Environment variables (all optional, sensible defaults provided):

Cloud LLM keys (OpenAI, Anthropic) are configured through the Settings page in the UI — no env vars needed.

tadpole-studio/
├── start.py                  # One-command launcher
├── backend/                  # Python — FastAPI + SQLite + ACE-Step
│   ├── src/tadpole_studio/
│   │   ├── main.py           # App entry, CORS, routers
│   │   ├── config.py         # Environment settings
│   │   ├── ace_handler.py    # TadpoleHandler (checkpoint resolution)
│   │   ├── backends/         # Music generation backends (ACE-Step, HeartMuLa)
│   │   ├── db/               # SQLite schema, connection, indexes
│   │   ├── routers/          # REST + WebSocket endpoints
│   │   │   ├── generation.py # Music generation
│   │   │   ├── dj.py         # AI DJ chat
│   │   │   ├── radio.py      # Radio stations
│   │   │   ├── themes.py     # Custom themes
│   │   │   └── ...           # Songs, playlists, models, training, etc.
│   │   ├── services/         # Generation, training, DJ, radio, LLM providers
│   │   ├── models/           # Pydantic request/response schemas
│   │   └── ws/               # WebSocket handlers
│   ├── data/                 # Runtime data (gitignored)
│   │   ├── checkpoints/      # ACE-Step model weights (auto-downloaded)
│   │   ├── audio/            # Generated music files
│   │   ├── loras/            # LoRA adapters
│   │   ├── datasets/         # Training datasets
│   │   ├── chat-llm/         # Local chat LLM weights
│   │   └── heartmula/        # HeartMuLa model weights
│   └── tests/                # pytest + httpx
├── frontend/                 # TypeScript — Next.js + React 19
│   └── src/
│       ├── app/              # Page routes (create, dj, radio, library, etc.)
│       ├── components/       # UI components by feature
│       │   ├── create/       # Music generation forms
│       │   ├── dj/           # AI DJ chat interface
│       │   ├── radio/        # Radio station player
│       │   ├── settings/     # Settings & theme picker
│       │   └── ...           # Library, playlists, models, training, layout
│       ├── hooks/            # Custom React hooks
│       ├── stores/           # Zustand state management
│       ├── themes/           # Built-in themes (11 themes)
│       ├── lib/              # API client, utilities, audio helpers
│       └── types/            # TypeScript interfaces
├── screenshots/              # README screenshots
└── LICENSE

# Backend
cd backend && uv run pytest -v

# Frontend
cd frontend && pnpm test --run

Tadpole Studio is built on top of ACE-Step 1.5.

Community inspirations:

• AI DJ — inspired by clockworksquirrel/ace-step-apple-silicon
• Radio — inspired by nalexand/ACE-Step-1.5-OPTIMIZED and PasiKoodaa/ACE-Step-RADIO

Licensed under the MIT License.