booth-musicgpt/README.md

# Theme Song Booth (MusicGPT Edition)

**Version:** `v0.7.0`

A Flask web application for running a convention booth where visitors request a custom AI-generated theme song. Operators manage the queue from an admin dashboard, generate prompts via Hermes, queue generations through the MusicGPT API, and deliver final songs by email.

The MusicGPT fork automates song generation: instead of manually creating songs in Suno and uploading MP3s, the operator saves a title/style/lyrics prompt and clicks **Generate A/B with MusicGPT**. The API returns two MP3 versions (plus WAVs and an album cover) and posts status updates to a webhook.

---

## Table of contents

1. [What the booth does](#what-the-booth-does)
2. [Customer-facing pages](#customer-facing-pages)
3. [Operator / admin pages](#operator--admin-pages)
4. [Status flow](#status-flow)
5. [Settings page explained](#settings-page-explained)
6. [Docker installation](#docker-installation)
7. [Environment variables](#environment-variables)
8. [File layout](#file-layout)
9. [Local development](#local-development)
10. [Common troubleshooting](#common-troubleshooting)
11. [License / ownership](#license--ownership)

---

## What the booth does

1. A visitor fills out a short form at `/request`.
2. The operator reviews the request in the admin dashboard and generates a prompt for MusicGPT (manually or via the `/api/prompt` Hermes callback).
3. The operator saves the title, style, and lyrics to the request.
4. The operator clicks **Generate A/B with MusicGPT**, selects a model, and waits for the webhook to complete. MusicGPT produces two MP3 versions, WAVs, and an album cover.
5. The operator sends a preview email; the customer visits their private player page, listens to both versions, and either approves one/both or requests changes.
6. After the customer approves and pays, the operator records the payment reference and delivers the selected MP3(s) — optionally with WAV files and the album cover — by email.
7. Optional STEMS can be generated for an extra fee and delivered via a share link.

---

## Customer-facing pages

| Page | Path | Purpose |
|------|------|---------|
| Request form | `/request` | Visitors enter email, name, pronouns, hobbies, notable facts, and extra requests. The music style is picked from three dropdowns: **Decade** (required), **Basic style** (required), and **Additional style** (optional). Decades and genres are loaded from `/mnt/Storage/Decades.txt` and `/mnt/Storage/Music Genres.txt`. Rate limited to 5 submissions per minute per IP. |
| Closed page | `/request` (when booth is closed) | Shows a friendly closed banner instead of the form when the operator marks the booth closed. |
| Thanks | `/thanks/<id>` | Confirmation page shown after a request is submitted. |
| Order status | `/status` | Customers enter their email to see all their requests and statuses. |
| FAQ | `/faq` | Answers common customer questions. |
| Private player | `/play/<token>` | Secret link emailed to the customer. Streams Version A and B, lets them approve or request revisions, and later download delivered files / stems. |
| Kiosk | `/kiosk` | Public full-screen display for a booth tablet. Cycles between a QR code for `/request` and the configured price list. Updates automatically when pricing or booth state changes. |

### Style selection

The request form no longer has a free-text genre field. Instead, customers choose:

1. **Decade / era** — required (e.g. `1980's`).
2. **Basic style** — required (e.g. `Pop`).
3. **Additional style** — optional (e.g. `Funk`).

These are stored together in the `style_genre` column as a comma-separated string (e.g. `1980's, Pop, Funk`) so no schema change is required. The admin request page shows the same dropdowns for corrections, and the copy-to-Hermes prompt formats the style as a clean sentence like "1980's-era Pop with Funk influences" for better Suno results.

### Pronouns

A required **Pronouns** dropdown is shown just below the name field, with options:

- He/Him/His
- She/Her/Hers
- They/Them/Their

The selected pronouns are stored in the `pronouns` column and included in confirmation emails and Hermes prompt copy.

---

## Operator / admin pages

| Page | Path | Purpose |
|------|------|---------|
| Login | `/admin/login` | Simple session-based login. Password comes from the `ADMIN_PASSWORD` environment variable. |
| Dashboard | `/admin` | Main queue. Filter by status and auto-refresh at a configurable interval. |
| Request detail | `/admin/request/<id>` | Full control of one request: edit customer info, save prompt, copy Hermes callback, queue MusicGPT generation, view status/cost, view revision history, upload MP3 overrides, send preview, record payment, deliver files (MP3/WAV/cover), add operator notes, cancel generation, and generate STEMS. |
| Pricing | `/admin/pricing` | Configure fixed prices and up to 5 custom items. Also shows running MusicGPT cost totals in USD. |
| Sales | `/admin/sales` | Report of all delivered requests with customer details and Square payment references. |
| Settings | `/admin/settings` | Database health, backups, SMTP config, MP3 metadata defaults, revision limit, auto-refresh interval, kiosk mode, booth open/closed switch, Hermes API key management, MusicGPT webhook URL, album cover delivery toggle, and system reset. |
| Reset | `/admin/reset` | Clears all requests and uploaded files. Requires admin password confirmation. |

---

## Status flow

```
pending → prompt_ready → songs_uploaded → awaiting_payment → paid → delivered
```

| Status | Meaning |
|--------|---------|
| `pending` | Customer submitted; waiting for a prompt. |
| `prompt_ready` | Prompt saved; ready to generate songs. |
| `songs_uploaded` | Both MP3s are ready; preview link can be sent. |
| `revisions_requested` | Customer asked for changes; current files archived. |
| `awaiting_payment` | Customer approved a version; waiting for payment. |
| `paid` | Payment recorded. |
| `delivered` | Final MP3(s) emailed to the customer. |
| `cancelled` | Request cancelled by the operator. |

---

## Settings page explained

The `/admin/settings` page is split into functional sections:

### Booth state
- **Booth open / closed** — When closed, `/request` and `/kiosk` show the closed banner.

### Hermes API key
- Displays whether a key is configured.
- **Regenerate API Key** creates a new random key stored in runtime settings.
- The key is used by the `/api/prompt/<id>` callback and by the `/api/key-test` diagnostic endpoint.
- Copy this key into your Hermes skill or AI assistant config.

### Customer revision limit
- Maximum number of times a customer can click **Request Changes** on the player page.
- Default is controlled by `MAX_REVISIONS` env var; can be overridden here.

### Dashboard refresh
- How often `/admin` reloads automatically (10, 20, or 30 seconds).

### Kiosk display
- **QR only** — shows the QR code permanently.
- **Pricing only** — shows the price list permanently.
- **Cycle every N seconds** — alternates between QR and pricing.

### SMTP settings
- Host, port, username, from address, and password for sending customer emails.
- The password is encrypted using `APP_SECRET_KEY` before being saved.
- **Send Test Email** verifies the configuration.

### MP3 metadata defaults
- Artist, album, year, and comment tags applied automatically to uploaded MP3s.
- The title tag is taken from the saved Suno prompt.

### Database maintenance
- **Health Check** — verifies all expected tables and columns exist.
- **Fix Database Schema** — adds missing tables/columns without deleting data.
- **Download Database Backup** — downloads the SQLite file.
- **Restore Database Backup** — replaces the live DB with an uploaded backup.
- **Download Uploads Backup** — ZIPs all uploaded MP3s for offline storage.
- **System Reset** — deletes all requests and uploaded files for a fresh event.

---

## Docker installation

### 1. Prepare environment variables

Generate values for the required secrets:

```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

Use the output for `APP_SECRET_KEY`.

### 2. Deploy with Portainer

1. Log in to Portainer.
2. Go to **Stacks** → **Add stack**.
3. Choose **Repository**:
   - URL: `https://gitlab.hallsworth.ca/yrtria/booth-musicgpt.git`
   - Branch: `main`
   - Compose path: `docker-compose.yml`
4. Add the environment variables listed in the section below.
5. Deploy the stack.
6. Open a console in the running `booth-musicgpt` container and run once:

```bash
python init_db.py
```

7. Point your reverse proxy at the host port you chose (default `127.0.0.1:8000`).
8. Visit `/admin/settings`, confirm the MusicGPT webhook URL, and configure the MusicGPT account webhook endpoint.
9. Copy the Hermes API key to your Hermes skill / AI assistant.
10. Print or display a QR code pointing to `https://your-domain/request`.

### Updating the deployment

After each push to Gitea:

```text
Portainer → Stacks → booth-musicgpt → Pull and redeploy
```

Persistent volumes keep the database and uploads safe across redeploys.

---

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `APP_SECRET_KEY` | Yes | — | Long random string for Flask sessions and for encrypting stored settings such as the SMTP password and legacy stored API key. |
| `ADMIN_PASSWORD` | Yes | — | Password used to log in to `/admin`. |
| `SMTP_PASS` | Yes | — | Password for the SMTP account used to send customer emails. |
| `PUBLIC_BASE_URL` | Yes | — | Public HTTPS URL of the booth, e.g. `https://booth.dionysismedia.ca`. Used in player links, emails, and callback URLs. |
| `SMTP_HOST` | No | `mailroot8.namespro.ca` | SMTP server hostname. |
| `SMTP_PORT` | No | `465` | SMTP server port. |
| `SMTP_USER` | No | `ai@hallsworth.ca` | SMTP username. |
| `SMTP_FROM` | No | `ai@hallsworth.ca` | From address for customer emails. |
| `BOOTH_NAME` | No | `Trollgorithm Theme Songs` | Display name used in email subjects and page titles. |
| `HOST_PORT` | No | `127.0.0.1:8000` | Host-side `ip:port` mapping for the container. |
| `INTERNAL_PORT` | No | `8000` | Port gunicorn binds to inside the container. |
| `PRICE_PER_VERSION` | No | `10.00` | Legacy price label shown in some templates; current pricing is configured from `/admin/pricing`. |
| `CURRENCY` | No | `CAD` | Currency label shown with prices. |
| `MAX_REVISIONS` | No | `2` | Default customer revision limit before an operator override. |
| `HERMES_API_KEY` | No | — | API key for the `/api/prompt` callback. |
| `MUSICGPT_API_KEY` | Yes | — | API key for MusicGPT generation and status polling. |
| `DATABASE` | No | `/app/data/booth.db` | Path to the SQLite database inside the container. |
| `UPLOAD_FOLDER` | No | `/app/uploads` | Path to uploaded/downloaded song storage inside the container. |

---

## File layout

| File | Purpose |
|------|---------|
| `app.py` | Flask routes, helpers, email layer, runtime settings, MP3 tagging, rate limiting, database maintenance, Hermes callback, kiosk, pricing, and sales report. |
| `config.py` | Environment-variable based configuration with sensible defaults. |
| `models.py` | SQLite schema, CRUD helpers, and revision history. |
| `init_db.py` | Standalone script to create or migrate the database. |
| `templates/` | Jinja2 templates for customer pages, admin pages, and kiosk display. |
| `static/` | Banner images, closed banner, email logo, and kiosk QR code. |
| `lists/` | Bundled copies of `decades.txt` and `music_genres.txt` used as fallback for the style dropdowns. |
| `Dockerfile` | Production container image definition. |
| `docker-compose.yml` | Portainer stack definition. |
| `requirements.txt` | Python dependencies. |
| `.env.example` | Local development environment template. |

---

## Local development

```bash
cd /home/jess/workspace/booth-musicgpt
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# Edit .env and set APP_SECRET_KEY, ADMIN_PASSWORD, SMTP_PASS, PUBLIC_BASE_URL
.venv/bin/python init_db.py
.venv/bin/python -m flask --app app run --host=0.0.0.0
```

Visit:
- Customer form: http://127.0.0.1:5000/request
- Admin login: http://127.0.0.1:5000/admin
- Kiosk: http://127.0.0.1:5000/kiosk

---

## Common troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| Emails not arriving | SMTP settings wrong or messages in spam. | Use **Send Test Email** on `/admin/settings`; verify host/port/password. |
| Can't reach app through domain | Reverse proxy points to wrong host port. | Match `HOST_PORT` to your proxy upstream. |
| Static banner not showing | Browser cached old image. | Hard-refresh or redeploy stack. |
| Logo missing from email | Logo file missing from `static/`. | Ensure `static/DM-Logo_email.png` is in the container. |
| Database schema mismatch | New column/table added but old DB not migrated. | Go to `/admin/settings` and click **Fix Database Schema**, or run `python init_db.py`. |
| Kiosk shows old prices | Page auto-refreshes every 30s; check `/admin/pricing`. | Verify pricing values and redeploy if templates changed. |
| `/api/prompt` returns 401 | Callback token expired or API key mismatch. | Copy a fresh callback URL from `/admin/request/<id>` and verify the key with `/api/key-test`. |

---

## License / ownership

Built for Jess's Trollgorithm theme-song booth. All code and assets are private to that project.