# 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**

   ```sh
   npm install
   ```

2. **Start the dev server**

   ```sh
   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

```sh
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.