MelodyMuse

Jannik/MelodyMuse

Fork 0

T

Jannik f2401d0c57 first commit

2026-06-03 01:07:07 +02:00

README.md

first commit

2026-06-03 01:07:07 +02:00

README.md

# 🎵 MelodyMuse

AI-powered song asset generator for [Suno AI](https://suno.com) — lyrics, style prompts, video loops, and YouTube descriptions in one click.

---

## What is MelodyMuse?

MelodyMuse is a personal web app that takes a music idea as input and uses an AI (via any OpenAI-compatible API) to generate everything you need to publish a Suno AI song:

- ✍️ **Lyrics** — rhyming, structured with Suno section tags, free of genre references

- 🎵 **Style Prompt** — ready to paste into Suno's "Style of Music" field

- 🚫 **Negative Style Prompt** — what Suno should avoid

- 🏷️ **3 Song Title Suggestions** — atmospheric, direct, and abstract

- 🎬 **3 Video Loop Prompts** — abstract, cinematic, and hybrid, with AI tool recommendations

- 📺 **YouTube Description** — with embedded lyrics, hashtags, and a call to action

All results are editable before download. Everything packages into a single .zip file named after your chosen song title.

---

## Features

| Feature | Details |

|---|---|

| Free-text input | Describe your music idea in natural language |

| Optional parameters | Language, mood, vocals vs. instrumental |

| Inline editing | Edit any generated section before downloading |

| Per-section regeneration | Regenerate only lyrics, style, titles, etc. |

| Full regeneration | Re-run everything with one click |

| ZIP download | Style.txt, Text.txt, Videodescription.txt, Videoprompt.txt |

| Dark / Light mode | Toggle in the top-right corner |

| Secure API key storage | Key lives on the server only — never in the browser |

| Provider-agnostic | Works with any OpenAI-compatible API (MiniMax, OpenAI, Mistral, etc.) |

---

## Tech Stack

- **Frontend:** React 18 + TypeScript + Tailwind CSS

- **Backend:** Supabase Edge Functions (Deno)

- **Database:** Supabase PostgreSQL (app config only)

- **ZIP generation:** JSZip (client-side)

---

## Project Structure


/

├── src/

│   ├── pages/

│   │   ├── Index.tsx          # Main generator page

│   │   └── Settings.tsx       # API configuration page

│   ├── components/

│   │   ├── InputPanel.tsx     # Left panel: text input + options

│   │   ├── ResultsPanel.tsx   # Right panel: all result cards

│   │   ├── TitlesCard.tsx     # Song title chips + selection

│   │   ├── LyricsCard.tsx     # Editable lyrics textarea

│   │   ├── StyleCard.tsx      # Style + negative style

│   │   ├── VideoPromptsCard.tsx  # Tabbed video prompt variations

│   │   ├── YoutubeCard.tsx    # YouTube description

│   │   └── DownloadBar.tsx    # Sticky ZIP download bar

│   └── lib/

│       └── zip.ts             # ZIP file generation logic

└── supabase/

&#x20;   └── functions/

&#x20;       ├── save-config/       # Saves API credentials server-side

&#x20;       ├── get-config-display/ # Returns masked config for settings UI

&#x20;       ├── test-connection/   # Tests the configured API

&#x20;       └── generate-song/     # Calls AI and returns generated assets

---

## Setup

### 1. Prerequisites

- A [Supabase](https://supabase.com) project (free tier is sufficient)

- An API key from any OpenAI-compatible provider (e.g. MiniMax, OpenAI, Mistral)

---

### 2. Supabase — Create the config table

In your Supabase project, open the **SQL Editor** and run:


CREATE TABLE app\_settings (

&#x20; id INT PRIMARY KEY DEFAULT 1,

&#x20; api\_endpoint TEXT NOT NULL DEFAULT '',

&#x20; api\_key      TEXT NOT NULL DEFAULT '',

&#x20; model\_name   TEXT NOT NULL DEFAULT '',

&#x20; updated\_at   TIMESTAMPTZ DEFAULT NOW()

);



INSERT INTO app\_settings (id, api\_endpoint, api\_key, model\_name)

VALUES (1, '', '', '')

ON CONFLICT DO NOTHING;

**Important:** Row Level Security (RLS) must be **disabled** for this table.

The table is only ever accessed by Edge Functions using the service_role key —

never directly from the browser.

---

### 3. Configure your API key in the app

1. Open the deployed app and navigate to **Settings** (link below the Generate button)

2. Enter your:

- **API Endpoint URL** — e.g. https://api.minimax.chat/v1

- **API Key** — your provider's secret key

- **Model Name** — e.g. MiniMax-Text-01 or gpt-4o

3. Click **Save Configuration**

4. Use **Test Connection** to verify everything works

Your API key is sent to the server via an Edge Function and stored in the database.

It is **never** returned to the browser or stored in localStorage.

---

## Usage

1. Open the app at your URL

2. Enter a music idea in the text field

> _Example: "Melancholic lo-fi house beat for a rainy Sunday morning"_

3. Optionally expand **Options** to set language, mood, and vocal preference

4. Click **✦ Generate Song Assets**

5. Review and edit any section inline

6. Select your preferred song title from the 3 suggestions

7. Click **⬇ Download ZIP** — you'll get YourTitle.zip containing:

| File | Contents |

|---|---|

| Style.txt | Suno style prompt + negative style (always English) |

| Text.txt | Song lyrics with Suno section tags |

| Videodescription.txt | Full YouTube description (in lyrics language) |

| Videoprompt.txt | 3 video loop prompts with tool recommendations |

---

## AI Output Rules

The AI follows these rules automatically — no manual configuration needed:

**Lyrics**

- Must rhyme (AABB or ABAB scheme)

- Must NOT reference the genre, instruments, or music production

_(e.g. a classical piano piece will not have lyrics about pianos or orchestras)_

- Structured with Suno section tags: \[Verse], \[Chorus], \[Bridge], \[Outro], etc.

**Style Prompt**

- Max 120 words, comma-separated

- Includes: tempo (BPM), instruments, production style, texture, energy, mood, vocal style

- Never references artists or bands by name

**Video Prompts**

- 3 variations: Abstract, Cinematic, Hybrid

- Optimized for 5-second seamless loops at 16:9

- Looping logic: if reverse playback is used, only physically sensible elements

_(e.g. pulsing light — never reversed rainfall)_

- No text, logos, faces, or hands in any prompt

- Includes tool recommendation (Runway, Kling, Luma, Pika, Haiper — never Sora)

**Language**

- Style, negative style, and video prompts → always **English**

- Lyrics, titles, YouTube description → in the **user's selected language**

---

## Supported API Providers

MelodyMuse works with any OpenAI-compatible API:

| Provider | Endpoint | Notes |

|---|---|---|

| MiniMax | https://api.minimax.chat/v1 | Recommended default |

| OpenAI | https://api.openai.com/v1 | GPT-4o works well |

| Mistral | https://api.mistral.ai/v1 | Fast and cost-effective |

| Groq | https://api.groq.com/openai/v1 | Very fast inference |

| Any other OpenAI-compatible provider | custom URL | Should work out of the box |

---

## Security Notes

- The API key is stored in the Supabase database and is only accessible

to Edge Functions via the service\_role key

- The browser client never queries the app\_settings table directly

- The get-config-display endpoint returns only the endpoint URL, model name,

and a boolean api\_key\_set — the actual key is never returned

- There is no user authentication (this app is intended for personal/single-user use)

- If you deploy this publicly, consider adding basic auth or Supabase Auth

---

## License

Personal use. Do whatever you want with it.

---