# Suno Helper User Manual

Welcome to Suno Helper — the creator companion that turns your playlist videos into complete Suno songs with a consistent musical style, then masters and uploads them to YouTube automatically. Everything runs on your own PC; your content is never uploaded or collected by Whick.

## Requirements

- Windows 10 or 11 (64-bit)
- Python 3.11 or later (the installer guides you)
- ffmpeg (the installer offers to set it up)
- An AI provider API key (OpenRouter, OpenAI, Anthropic, or Google — one is enough for AI lyric/prompt work)
- A free Whick account with an API key (activation)

## 1. Download and install

1. Open the [Suno Helper page](/suno.html) and click **Install**.
2. The downloaded `Setup.bat` — double-click it. The rest is automatic:
   - Installs the backend (Python) and frontend (web UI) locally
   - Registers the `suno-helper://` protocol so the site can launch the app
   - Prepares ffmpeg if missing
3. When finished, Suno Helper is registered on this PC.

> Note: You can download and install without signing in. To **run** the app you need a Whick account and an API key (see section 3).

## 2. First run and activation

1. On the [Suno Helper page](/suno.html) click **Run** — the app opens in a new tab at `127.0.0.1:8765`.
2. Go to **Settings → Whick API key** in the app.
3. Paste your API key (starts with `whick_`) and click **Activate**.
   - No key yet? Sign in at [whick.org](/) → open the [API page](/api.html) → issue your key.
   - One key per account — the same key works in Suno Helper, WAMSS and future Whick apps.
4. Lost or revoked the key? Issue a new one on the API page and activate again.

## 3. AI provider API key

Suno Helper uses **your own key from an AI provider** for AI lyric writing, paraphrasing and prompt generation. Any one of the following is enough, and you can switch freely.

| Provider | Get a key |
|---|---|
| **OpenRouter** (recommended — many models, one key) | [openrouter.ai](https://openrouter.ai) (free credits available) |
| OpenAI | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
| Anthropic | [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) |
| Google Gemini | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |

1. Get a key from one of the providers above.
2. In the app: **Settings → AI provider API keys**, choose your provider, paste the key and save.
3. Click **Connection test** — that provider's model list is filled in automatically.
4. **Thumbnail image generation** (not lyrics/prompts) uses its own image provider setting (OpenRouter, Google, or OpenAI).

## 4. Make your first album

An **album** is the working unit of Suno Helper — a theme, a playlist of songs, and their artwork.

1. **Albums → New album** — enter a title, story/theme and mood keywords (e.g. *dreamy, melancholic, hopeful*).
2. **Home → Taste song analysis** — paste a YouTube playlist of songs you love. The app analyzes them and builds your musical taste profile (genre, instruments, vocals, mood).
3. **Style presets** — pick or create a preset that matches your style. Presets keep every song in the album consistent.
4. Open an album and add a song — the app drafts Korean and English lyrics, an instrument setting and a Suno style prompt from your theme and taste profile.
5. Review with **A/B compare** (two variants side by side), then copy the lyrics and prompt into Suno, or let the pipeline do it.

## 5. Video editing and remaster

Open an album song in **Video editor** to finish the release:

- **Templates, backgrounds, text boxes** — build the video look track by track.
- **Per-track style presets** — colors and text styles follow your album preset.
- **Remaster (voice)** — audio-only remaster of each track.
- **Full video encoding** — encode the final video.
- **Description** — auto (track list · specs · tags) or manual input, with your channel brand block.

## 6. YouTube studio

1. Connect your YouTube channel in **Settings → YouTube auto-upload**.
2. **YouTube studio** shows the pipeline queue — remaster, video and upload jobs run in the background.
3. Upload finished projects with one click; the description, tags and thumbnail footer are filled from your album data.

## 7. Search

**Search** finds songs across all your albums — lyrics, prompts and titles included.

## 8. Data and privacy

- Everything is stored locally on your PC:
  - Install folder `data` — settings and database
  - Work root folder — audio and video files
- Your content is never uploaded to or collected by Whick.
- Closing the app tab stops the background app.

## 9. Updates

The app checks for updates automatically. When a new version is available, a banner appears — click it to download, then run the new `Setup.bat`. Your data and settings are preserved.

## 10. Troubleshooting

- **Run button does nothing** — install first (Setup.bat), then run. The `suno-helper://` protocol must be registered.
- **"An older install was detected"** — run Install again to upgrade the launcher.
- **AI steps fail** — check your AI provider key in Settings and make sure the **Connection test** passes.
- **Activation fails** — the key must start with `whick_`, be active on your account, and the PC needs internet access.
- **App tab is blank** — the backend takes a few seconds to start; refresh the tab.