Your wish is composed.

🎶 Pick genres, artists, lyric sparks, instruments, and vibe. Get an original song, real audio included. 🎶

Magic Music Maker is a six-step creative workshop that turns what you actually love into an original, AI-generated song you can listen to inside the app, no bouncing out to another site required.

%%{init: {'theme': 'dark'}}%%
flowchart TB
  A["🎼 1. Genres"] --> B["🎤 2. Artists"]
  B --> C["✍️ 3. Lyrics"]
  C --> D["🥁 4. Instruments"]
  D --> E["🌊 5. Sound & Vibe"]
  E --> F["🪄 6. Creation"]
  F --> G["🔊 Real audio, in-app"]

  style A fill:#1b1b1f,stroke:#7b4fff,color:#faf8f4
  style B fill:#1b1b1f,stroke:#7b4fff,color:#faf8f4
  style C fill:#1b1b1f,stroke:#7b4fff,color:#faf8f4
  style D fill:#1b1b1f,stroke:#7b4fff,color:#faf8f4
  style E fill:#1b1b1f,stroke:#7b4fff,color:#faf8f4
  style F fill:#1b1b1f,stroke:#d4ff00,color:#faf8f4
  style G fill:#1b1b1f,stroke:#d4ff00,color:#faf8f4

Loading

• 🎼 Genres & Artists — real AI reads what you actually type and suggests genuine musical neighbors, not a fixed rotation.
• ✍️ Lyric sparks, not full verses — you pick images/themes/hooks, the AI writes the actual song around them.
• 🥁 Instruments & Sound — concrete, specific texture picks (Fender Rhodes, tape saturation, half-time groove) instead of vague mood words.
• 🌊 Vibe — a short energy/trajectory description auto-drafted, editable by hand.
• 🪄 Creation — everything gets synthesized into an original title, concept, lyrics, and Suno-style production prompt. Fresh every time, verified: two runs on identical ingredients produce two different songs.
• 🔊 Real playable audio — hits GoAPI's Udio-backed model and streams back an actual .mp3, right inside the app.
• ⏮️ Jump between steps freely — click any of the 6 step tabs to go back and change your picks without losing progress.
• 🖼️ Gallery — save your finished song with a display name (needs Vercel Blob storage configured, see below).

The text-generation side (genres/artists/lyrics/vibe/mashup) is provider-agnostic, not locked to one company. It auto-detects whichever key is set:

Provider	Env var	Notes
🐋 DeepSeek	DEEPSEEK_API_KEY	Cheapest option, OpenAI-compatible Chat Completions API
🟢 OpenAI	OPENAI_API_KEY	gpt-4o-mini by default
🟣 Anthropic	ANTHROPIC_API_KEY	claude-haiku-4-5 by default

Override the model/base URL with AI_TEXT_MODEL / AI_TEXT_BASE_URL if you want something else entirely.

⚠️ MUSIC_MASH_DEMO_MODE must be 0 (or unset) for real AI to run. If it's 1, the app always uses a fixed offline template instead, even with a real key set.

npm install
npm run dev

Runs at http://localhost:3000. 🖥️

Offline dev/test mode (no AI keys needed):

$env:MUSIC_MASH_TEST_MODE="1"
npm run dev

Checks before you push:

npm run test
npm run typecheck
npm run lint
npm run build

Variable	What it does
🐋 DEEPSEEK_API_KEY / 🟢 OPENAI_API_KEY / 🟣 ANTHROPIC_API_KEY	Real AI text generation (set exactly one, or TEXT_PROVIDER to force which)
🚫 MUSIC_MASH_DEMO_MODE	1 = fixed offline template · 0/unset = real AI
🎧 GOAPI_API_KEY	Real full-song audio generation via GoAPI (never put this in GitHub Pages or client code)
🎚️ MUSIC_PROVIDER	goapi (default) · musicapi · sunoapi
📦 BLOB_READ_WRITE_TOKEN	Vercel Blob storage, required for "Save to Gallery"
🧪 MUSIC_MASH_TEST_MODE	1 = offline dev/test mode, local only
🛑 MUSIC_GEN_DAILY_LIMIT	Max full-song generations per day across all visitors, default 20
🛑 MUSIC_GEN_HOURLY_LIMIT_PER_IP	Max full-song generations per IP per hour, default 5
🛑 AI_MASHUP_HOURLY_LIMIT_PER_IP	Max song compositions (text) per IP per hour, default 20. Only the "mashup" step is limited, not the cheap suggestion calls.
🖼️ IMAGE_MODEL	Cover art model on GoAPI, default Qubico/flux1-dev (same GOAPI_API_KEY as music, no separate key needed)
🛑 COVER_ART_DAILY_LIMIT	Max cover art generations per day across all visitors, default 20
🛑 COVER_ART_HOURLY_LIMIT_PER_IP	Max cover art generations per IP per hour, default 5

GitHub Pages can only serve static files, it can't keep API keys private or run the /api routes, so the static demo (/docs) is a browser-only fallback. The real app runs on Render.

1. Render → New Web Service → connect DaCameraGirl/Magic_Music_Maker.
2. Render reads render.yaml automatically for build/start commands.
3. Environment tab → add GOAPI_API_KEY 🎧
4. Environment tab → add a text-AI key (🐋 DEEPSEEK_API_KEY recommended, cheapest) and set MUSIC_MASH_DEMO_MODE=0 🧠
5. (Optional) add BLOB_READ_WRITE_TOKEN for Gallery saving 📦
6. Save → Render redeploys automatically.
7. Live app: music-mash-lab.onrender.com ✅

Built by Angela Hudson · DaCameraGirl 💜