yrtria/booth-musicgpt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

v0.8.7: update VERSION, README, and code comments

Browse source 
- VERSION bumped to 0.8.7
- README.md: comprehensive update with Gokapi integration, stems radio
  buttons, download button, cost tracking improvements, stepper fixes,
  error recovery, new env vars, new troubleshooting entries
- app.py: updated module docstring with all current routes
- helpers.py: updated module docstring with function group overview,
  added section header for Gokapi integration
- config.py: added Gokapi env vars to docstring
- models.py: updated schema comments for per-version costs and
  stems_link/stems_url distinction
This commit is contained in:
Troll (Hermes Agent) 2026-08-11 21:08:38 +00:00
parent 59d79cd03d
commit 8df735d88c
6 changed files with 119 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

89
README.md
View file

@ -1,10 +1,10 @@
# Theme Song Booth (MusicGPT Edition)
**Version:** `v0.7.0`
![Version](https://img.shields.io/badge/version-v0.8.7-blue)
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.
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. Stems are extracted on demand and uploaded to a Gokapi file-sharing server for expiring download links.
---
@ -15,13 +15,14 @@ The MusicGPT fork automates song generation: instead of manually creating songs
3. [Operator / admin pages](#operator--admin-pages)
4. [Status flow](#status-flow)
5. [MusicGPT workflow](#musicgpt-workflow)
6. [Settings page explained](#settings-page-explained)
7. [Docker installation](#docker-installation)
8. [Environment variables](#environment-variables)
9. [File layout](#file-layout)
10. [Local development](#local-development)
11. [Common troubleshooting](#common-troubleshooting)
12. [License / ownership](#license--ownership)
6. [Stems extraction](#stems-extraction)
7. [Settings page explained](#settings-page-explained)
8. [Docker installation](#docker-installation)
9. [Environment variables](#environment-variables)
10. [File layout](#file-layout)
11. [Local development](#local-development)
12. [Common troubleshooting](#common-troubleshooting)
13. [License / ownership](#license--ownership)
---
@ -33,7 +34,7 @@ The MusicGPT fork automates song generation: instead of manually creating songs
4. The operator clicks **Generate A/B with MusicGPT**, selects a model, and waits for MusicGPT to finish. MusicGPT produces two MP3 versions, optional 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.
7. Optional STEMS can be generated for an extra fee. The operator selects which MP3 version to extract stems from via radio buttons, and the completed stems are automatically zipped and uploaded to Gokapi as a single expiring download link.
---
@ -124,7 +125,7 @@ The app queues two conversions (Version A and Version B) with MusicGPT. It store
MusicGPT POSTs to `/api/musicgpt/webhook` when each conversion completes. The handler:
- Matches the payload to the request by `task_id` and `conversion_id`.
- Updates the request status and cost.
- Updates the request status and cost. Per-version costs are accumulated into a total (`musicgpt_cost`), with per-version breakdowns stored in `musicgpt_cost_a` and `musicgpt_cost_b`.
- Downloads album cover, MP3s, and WAVs when the payload includes URLs.
- Webhooks often arrive before audio URLs are ready; missing files are filled in by polling.
@ -142,7 +143,13 @@ All polling paths call `musicgpt_poll_status()` and run `download_musicgpt_outpu
### Cost tracking
The `/admin/pricing` page shows aggregate MusicGPT costs in USD. The per-request cost is recorded from the webhook/poll payload (`conversion_cost`) when MusicGPT provides it; otherwise the queued estimate is shown. Stems are tracked separately by `stems_cost`.
The per-request **LLM Cost** display on `/admin/request/<id>` shows the combined total of song generation costs and stems extraction costs, with a breakdown in smaller text:
```
LLM Cost: $0.2740 USD (songs: $0.1370 USD + stems: $0.1370 USD)
```
Per-version costs are accumulated from separate webhook payloads rather than overwritten, so the total reflects both Version A and Version B. The `/admin/pricing` page shows aggregate MusicGPT costs across all requests in USD.
### WAV delivery
@ -154,6 +161,42 @@ A global toggle in `/admin/settings` controls whether the generated album cover
---
## Stems extraction
### Generating stems
1. On `/admin/request/<id>`, scroll to the **Stems** section in the Songs panel.
2. Select the source MP3 using the **radio buttons** — Version A or Version B. Only versions with files ready are selectable; unavailable versions are greyed out.
3. Click **Generate Stems**.
The app constructs a public URL for the selected MP3 via the `/api/audio-source/<token>/<version>.mp3` endpoint and sends it to the MusicGPT Extraction API. The Extraction API downloads the audio, separates vocals and instrumental tracks, and posts the result to the webhook.
### Stems webhook and Gokapi upload
When the Extraction webhook fires with `COMPLETED` status:
1. The app parses the individual stem URLs (vocals, instrumental) from the webhook payload.
2. Downloads each stem file from the MusicGPT CDN.
3. Bundles them into a single zip archive named `stems_<song title>.zip`.
4. Uploads the zip to Gokapi (`GOKAPI_URL`) with a configurable expiry (default 30 days).
5. Saves the Gokapi download URL to `stems_link` in the database.
The **Download Stems** button on the admin request page links directly to the Gokapi download page. The `stems_link` is also included in the delivery email when stems are part of the order.
### Error recovery
If stems extraction fails, the error message is displayed on the admin request page but is automatically cleared on the next retry attempt. The **Generate Stems** button remains enabled when the status is `ERROR`, so the operator can retry without navigating away.
### Re-uploading existing stems
If the webhook completed before Gokapi was configured (or the Gokapi upload failed), a **Re-upload to Gokapi** button appears in the Stems / Extras Link section. This manually triggers the download-zip-upload flow for the existing stem files.
### Manual download fallback
If `stems_link` is empty but `stems_url` contains raw CDN URLs, the Download Stems button falls back to the `/admin/request/<id>/download-stems` endpoint, which downloads the stem files on the fly, zips them, and serves the zip as a browser download.
---
## Settings page explained
The `/admin/settings` page is split into functional sections:
@ -231,7 +274,7 @@ Use the output for `APP_SECRET_KEY`.
python init_db.py
```
7. Point your reverse proxy at the host port you chose (default `127.0.0.1:8000`).
7. Point your reverse proxy at the host port you chose (default `0.0.0.0:8500`).
8. Visit `/admin/settings`, confirm the MusicGPT webhook URL, and configure the MusicGPT account webhook endpoint to the same URL.
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`.
@ -256,18 +299,21 @@ Persistent volumes keep the database and uploads safe across redeploys.
| `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://music.dionysismedia.ca`. Used in player links, emails, callback URLs, and the MusicGPT webhook URL. |
| `MUSICGPT_API_KEY` | Yes | — | API key for MusicGPT generation, polling, and stems extraction. |
| `GOKAPI_URL` | No | — | Base URL of the Gokapi file-sharing server, e.g. `https://files.dionysismedia.ca`. Required for automatic stems upload. |
| `GOKAPI_API_KEY` | No | — | API key for the Gokapi REST API. Required for automatic stems upload. |
| `GOKAPI_EXPIRY_DAYS` | No | `30` | Number of days before uploaded stems files expire on Gokapi. |
| `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. |
| `HOST_PORT` | No | `0.0.0.0:8500` | 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. |
@ -277,10 +323,10 @@ Persistent volumes keep the database and uploads safe across redeploys.
| File | Purpose |
|------|---------|
| `app.py` | Flask routes, runtime settings, email layer, MP3 tagging, rate limiting, database maintenance, Hermes callback, kiosk, pricing, sales report, MusicGPT webhooks, polling, and file downloads. |
| `config.py` | Environment-variable based configuration with sensible defaults. |
| `helpers.py` | MusicGPT API client, polling, downloads, email helpers, MP3 metadata, settings persistence, and utility functions. |
| `models.py` | SQLite schema, CRUD helpers, and revision history. |
| `app.py` | Flask routes, runtime settings, email layer, MP3 tagging, rate limiting, database maintenance, Hermes callback, kiosk, pricing, sales report, MusicGPT webhooks, polling, file downloads, stems download-zip endpoint, audio-source endpoint, and Gokapi upload trigger. |
| `config.py` | Environment-variable based configuration with sensible defaults. Includes MusicGPT and Gokapi settings. |
| `helpers.py` | MusicGPT API client, polling, downloads, email helpers, MP3 metadata, settings persistence, Gokapi upload, stems-to-Gokapi processing, cost formatting, and utility functions. |
| `models.py` | SQLite schema, CRUD helpers, and revision history. Includes per-version cost columns (`musicgpt_cost_a`, `musicgpt_cost_b`). |
| `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. |
@ -289,6 +335,7 @@ Persistent volumes keep the database and uploads safe across redeploys.
| `docker-compose.yml` | Portainer stack definition. |
| `requirements.txt` | Python dependencies. |
| `.env.example` | Local development environment template. |
| `VERSION` | Current version string (read by `config.py` and displayed on `/admin/settings`). |
---
@ -300,6 +347,7 @@ 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, MUSICGPT_API_KEY
# Optional: GOKAPI_URL, GOKAPI_API_KEY, GOKAPI_EXPIRY_DAYS
.venv/bin/python init_db.py
.venv/bin/python -m flask --app app run --host=0.0.0.0
```
@ -324,6 +372,9 @@ Visit:
| `/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`. |
| MusicGPT generation fails | API key lacks access to the selected model. | Only `v6` and `v6-pro` are supported by the current key; choose from the dropdown. |
| Webhook arrives but no files download | MusicGPT webhook fires before audio URLs are ready. | Wait for the automatic background poll, click **Poll MusicGPT** on the request, or use **Refresh MusicGPT Status** on the dashboard. |
| Stems extraction returns HTTP 500 | Transient MusicGPT API error. | Retry by clicking **Generate Stems** again. The error message is cleared automatically on the next attempt. |
| Stems completed but no Gokapi link | Webhook fired before Gokapi was configured, or Gokapi upload failed. | Click **Re-upload to Gokapi** in the Stems / Extras Link section. |
| LLM Cost shows $0 for songs | Old webhook zeroed the cost estimate before the accumulation fix. | New requests will accumulate correctly. Historical data cannot be recovered. |
---

2
VERSION
View file

@ -1 +1 @@
0.7.0
0.8.7

13
app.py
View file

@ -1,7 +1,7 @@
"""
app.py
======
Main Flask application for the Theme Song Booth.
Main Flask application for the Theme Song Booth (MusicGPT Edition).
This module defines all HTTP routes, helper functions, the email layer,
runtime settings persistence, MP3 metadata tagging, rate limiting, and
@ -16,7 +16,9 @@ Public routes (customers):
- /play/<token> -> private player page with Version A and B
- /play/<token>/approve -> customer picks a version
- /play/<token>/revise -> customer asks for changes
- /audio/<token>/<v>.mp3 -> serves the uploaded MP3 files
- /api/stream/<token>/<v>.mp3 -> streams uploaded MP3s (requires both A and B)
- /api/audio-source/<token>/<v>.mp3 -> serves a single MP3 for stems extraction API
- /audio/<token>/<v>.mp3 -> legacy, returns 404
Admin routes:
- /admin/login -> password login
@ -25,7 +27,14 @@ Admin routes:
- /admin/settings -> runtime settings, health check, DB stats, backup/restore, reset
- /admin/request/<id> -> detail/edit page for a single request
- /admin/request/<id>/delete -> deletes one request and its uploaded files
- /admin/request/<id>/download-stems -> downloads all stems as a zip archive
- /admin/reset -> deletes ALL requests and ALL files
API routes:
- /api/musicgpt/webhook -> MusicGPT async callback (generation + stems)
- /api/musicgpt/autopoll -> background poll for all in-flight tasks
- /api/prompt/<id> -> Hermes callback for generated prompts
- /api/key-test -> tests the Hermes API key
"""
# Standard library imports

3
config.py
View file

@ -31,6 +31,9 @@ Environment variables (defaults shown):
- HERMES_API_KEY API key for the /api/prompt callback (optional, can be set in settings)
- MUSICGPT_DEFAULT_MODEL default model selected in the admin dropdown (default v6-pro)
- MUSICGPT_MODELS comma-separated list of models available to the API key (default v6,v6-pro)
- GOKAPI_URL base URL of the Gokapi file-sharing server (optional, for stems upload)
- GOKAPI_API_KEY API key for the Gokapi REST API (optional)
- GOKAPI_EXPIRY_DAYS days before uploaded stems expire on Gokapi (default 30)
"""
import os

13
helpers.py
View file

@ -5,6 +5,15 @@ Utility and configuration helpers for the Theme Song Booth Flask app.
These functions are stateless (or use Flask's current_app / session context)
and are imported by app.py. Keeping them here reduces the size of the route file.
Key function groups:
- Genre/decade parsing and style formatting
- Admin auth, settings persistence, encryption helpers
- Email sending (SMTP) and ntfy notifications
- Hermes API key management and prompt callback signing
- MusicGPT API client: generation, polling, file downloads, cost tracking
- Gokapi integration: stems upload, zip bundling, share link generation
- MP3 metadata tagging (mutagen)
"""
import os
@ -797,6 +806,10 @@ def get_musicgpt_cost_totals():
}
# ---------------------------------------------------------------------------
# Gokapi file-sharing integration (stems upload)
# ---------------------------------------------------------------------------
def parse_stems_urls(stems_url_field):
"""
Parse the stems_url DB field into a list of (label, url) tuples.

11
models.py
View file

@ -10,8 +10,11 @@ Schema overview (see SCHEMA constant):
- requests table stores customer data, generated prompts, file paths,
approval state, email timestamps, payment reference, player token,
vocal gender preference, revision count, revision note, and operator notes.
- MusicGPT integration fields store task/conversion IDs, status, cost, error,
album cover URL, WAV paths, and stems task/cost/URL.
- MusicGPT integration fields store task/conversion IDs, status, per-version
costs (musicgpt_cost_a/b accumulated into musicgpt_cost), error, album cover
URL, WAV paths, and stems task/cost/URL.
- Stems integration: stems_url holds raw CDN URLs from the webhook, stems_link
holds the Gokapi share link (auto-generated on completion or manually uploaded).
- Revisions: when a customer requests changes, the current A/B MP3 files are
renamed to archived "RevN-" copies and new versions are uploaded later.
- operator_notes is an internal column for the booth team and is never shown
@ -54,7 +57,7 @@ CREATE TABLE IF NOT EXISTS requests (
revision_count INTEGER DEFAULT 0,
revision_note TEXT,
operator_notes TEXT,
stems_link TEXT,
stems_link TEXT, -- Gokapi share link for stems (auto-generated, also editable by operator)
stems_interest INTEGER DEFAULT 0,
musicgpt_task_id TEXT, -- MusicGPT Music AI task ID shared by Version A and B
musicgpt_conversion_id_1 TEXT, -- conversion ID for Version A
@ -71,7 +74,7 @@ CREATE TABLE IF NOT EXISTS requests (
stems_task_id TEXT, -- MusicGPT Extraction task ID for optional stems
stems_status TEXT, -- status of the Extraction job
stems_cost REAL, -- API-reported stems cost in USD credits
stems_url TEXT, -- download / share link for stems
stems_url TEXT, -- raw stem URLs from MusicGPT webhook (label: url; label: url)
stems_error TEXT -- error message from stems job
);