commit f2401d0c573624dbf5975704dd8cd683e5eb66a3 Author: orfelorfel23 Date: Wed Jun 3 01:07:07 2026 +0200 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..2a757b1 --- /dev/null +++ b/README.md @@ -0,0 +1,410 @@ +\# ๐ŸŽต 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/ + + โ””โ”€โ”€ functions/ + + โ”œโ”€โ”€ save-config/ # Saves API credentials server-side + + โ”œโ”€โ”€ get-config-display/ # Returns masked config for settings UI + + โ”œโ”€โ”€ test-connection/ # Tests the configured API + + โ””โ”€โ”€ 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: + + + +```sql + +CREATE TABLE app\_settings ( + + id INT PRIMARY KEY DEFAULT 1, + + api\_endpoint TEXT NOT NULL DEFAULT '', + + api\_key TEXT NOT NULL DEFAULT '', + + model\_name TEXT NOT NULL DEFAULT '', + + 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. + + + +\--- + + + +\*Powered by Supabase ยท Made for \[Suno AI](https://suno.com)\* +