# 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 OpenRouter API key (used by the app 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. OpenRouter API key

Suno Helper uses your own OpenRouter key for AI lyric writing, paraphrasing and prompt generation.

1. Get a key at [openrouter.ai](https://openrouter.ai) (free credits available).
2. In the app: **Settings → AI provider API keys → OpenRouter**, paste and save.
3. Model lists are filled in automatically after a connection test.

## 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 OpenRouter key in Settings.
- **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.