MelodyMuse/README.md

MelodyMuse

Generate all assets needed for a Suno AI song from a free-text description — titles, lyrics, style prompt, video prompts (Abstract / Cinematic / Hybrid), and a YouTube description, then download everything as a ZIP.

The app runs entirely in your browser as a single static SPA. There is no backend, no database, no third-party services: the only network calls are direct fetch requests from your browser to the AI provider's OpenAI-compatible /chat/completions endpoint, using credentials that you paste into the Settings page. Those credentials are kept in this browser's localStorage.

Tech stack

• React 18 + TypeScript + Vite
• Tailwind CSS (dark by default, light theme via html.light)
• JSZip for client-side ZIP generation
• react-router-dom for the two routes (/, /settings)

Repository layout

MelodyMuse/
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── index.css                # Tailwind layers + design-system components
│   ├── components/              # UI building blocks
│   │   └── cards/               # The five result cards
│   ├── pages/                   # HomePage, SettingsPage
│   ├── lib/
│   │   ├── llm.ts               # direct fetch → provider, JSON extraction, config persistence
│   │   ├── prompts.ts           # system + user prompt construction
│   │   ├── types.ts             # shared TypeScript types
│   │   ├── zip.ts               # JSZip layout
│   │   ├── theme.ts             # dark/light mode
│   │   └── toast.tsx            # toast context
│   └── vite-env.d.ts
├── public/favicon.svg
├── index.html
├── tailwind.config.js
├── vite.config.ts
├── tsconfig*.json
└── package.json

Getting started

1. Install dependencies

   npm install
   

2. Start the dev server

   npm run dev
   

   Open http://localhost:5173 in your browser.

3. Open Settings and fill in:

   • API Endpoint URL — e.g. https://api.minimax.chat/v1
   • API Key — your provider's secret key
   • Model Name — e.g. MiniMax-M3

   Click Save Configuration, then Test Connection to confirm everything is wired up.

4. Generate. Return to the home page, type a music idea, click Generate Song Assets.

Build for production

npm run build

Outputs static assets in dist/. The dist/ folder is a normal SPA — serve it from any static host (GitHub Pages, Netlify, Vercel, python -m http.server, …).

⚠️ Heads up about deployment. Because the API key is stored in the browser's localStorage, you should not serve a public deployment of this app and use it with a real key on a shared device. For personal/local use this is fine.

CORS

The app makes direct cross-origin requests from the browser to your provider. If your provider does not send the right Access-Control-Allow-* headers for your origin, the request will fail with a CORS error. The generated error message will explicitly call this out. Workarounds:

• Pick a provider/endpoint that already permits browser CORS (most managed OpenAI-compatible services do).
• Run the app on the same origin as the API (i.e. front it with a tiny proxy).
• Use a CORS-permissive browser extension during local development.

Provider format

The configured endpoint must expose an OpenAI-compatible POST {api_endpoint}/chat/completions route that accepts { model, messages, max_tokens } and returns { choices: [{ message: { content } }] }.

Security notes

• The API key is held in localStorage and is only sent to the endpoint you configure. No analytics, no telemetry, no third-party calls.
• The MelodyMuse-config localStorage key contains your endpoint URL, model name, and key. You can clear it at any time from your browser's devtools (Application → Local Storage).

License

Personal use. Do whatever you want with it.