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

Add inline comments and update README for MusicGPT workflow

Browse source
This commit is contained in:
Troll (Hermes Agent) 2026-08-10 23:45:28 +00:00
parent 2ec73dee0f
commit 530e9e53ff
5 changed files with 149 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

99
README.md
View file

@ -14,13 +14,14 @@ The MusicGPT fork automates song generation: instead of manually creating songs
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)
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)
---
@ -29,7 +30,7 @@ The MusicGPT fork automates song generation: instead of manually creating songs
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.
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.
@ -75,11 +76,11 @@ The selected pronouns are stored in the `pronouns` column and included in confir
| 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. |
| Dashboard | `/admin` | Main queue. Filter by status and auto-refresh at a configurable interval. Includes a **Refresh MusicGPT Status** button to manually poll all in-flight tasks. |
| Request detail | `/admin/request/<id>` | Full control of one request: edit customer info, save prompt, copy Hermes callback, queue MusicGPT generation, poll a single MusicGPT task, 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. |
| 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, automatic MusicGPT polling toggle, and system reset. |
| Reset | `/admin/reset` | Clears all requests and uploaded files. Requires admin password confirmation. |
---
@ -103,6 +104,56 @@ pending → prompt_ready → songs_uploaded → awaiting_payment → paid → de
---
## MusicGPT workflow
### Supported models
The available MusicGPT models are limited by the API key. The deployed key supports `v6` and `v6-pro`; `v6-pro` is the default. The model dropdown on `/admin/request/<id>` only shows models returned by the MusicGPT API for the configured key.
### Generating songs
1. On `/admin/request/<id>`, enter or paste the **Title**, **Style**, and **Lyrics**.
2. Click **Save Prompt**.
3. Choose a model and whether to include WAV files.
4. Click **Generate A/B with MusicGPT**.
The app queues two conversions (Version A and Version B) with MusicGPT. It stores the task ID, both conversion IDs, the webhook URL, and an estimated cost.
### Webhook
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.
- 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.
### Polling
Three ways to poll MusicGPT:
| Method | How | When to use |
|--------|-----|-------------|
| Automatic | Background job hits `/admin/musicgpt/autopoll` every 3 minutes | Set-and-forget; enabled by default and can be turned off in `/admin/settings`. |
| Dashboard refresh | **Refresh MusicGPT Status** button on `/admin` | Manual check of all in-flight tasks. |
| Per-request | **Poll MusicGPT** button on `/admin/request/<id>` | Force a single request to update now. |
All polling paths call `musicgpt_poll_status()` and run `download_musicgpt_outputs()` when the API reports `COMPLETED`, so MP3s/WAVs arrive without further operator action once they are available.
### 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`.
### WAV delivery
A per-request checkbox **Include WAV files with delivery** stores `deliver_wav=1`. When enabled, WAV files are downloaded alongside MP3s and attached to the delivery email.
### Album cover
A global toggle in `/admin/settings` controls whether the generated album cover is attached to delivery emails. The cover is always downloaded and shown on the admin request page.
---
## Settings page explained
The `/admin/settings` page is split into functional sections:
@ -112,8 +163,7 @@ The `/admin/settings` page is split into functional sections:
### 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.
- The key is used by the `/api/prompt/<id>` callback.
- Copy this key into your Hermes skill or AI assistant config.
### Customer revision limit
@ -134,8 +184,14 @@ The `/admin/settings` page is split into functional sections:
- **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.
- Artist, album, year, and comment tags applied automatically to downloaded MP3s.
- The title tag is taken from the saved Suno/MusicGPT prompt title.
### MusicGPT settings
- **API key configured** indicator.
- **Webhook URL** — shown for reference; sent per-conversion with every generation request.
- **Album cover delivery** — attach cover to delivery emails.
- **Automatic MusicGPT polling** — enable/disable the background poll that downloads ready files without operator action.
### Database maintenance
- **Health Check** — verifies all expected tables and columns exist.
@ -176,7 +232,7 @@ 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.
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`.
@ -196,10 +252,10 @@ Persistent volumes keep the database and uploads safe across redeploys.
| 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. |
| `APP_SECRET_KEY` | Yes | — | Long random string for Flask sessions and for encrypting stored settings such as the SMTP password. |
| `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. |
| `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. |
| `SMTP_HOST` | No | `mailroot8.namespro.ca` | SMTP server hostname. |
| `SMTP_PORT` | No | `465` | SMTP server port. |
| `SMTP_USER` | No | `ai@hallsworth.ca` | SMTP username. |
@ -221,8 +277,9 @@ Persistent volumes keep the database and uploads safe across redeploys.
| File | Purpose |
|------|---------|
| `app.py` | Flask routes, helpers, email layer, runtime settings, MP3 tagging, rate limiting, database maintenance, Hermes callback, kiosk, pricing, and sales report. |
| `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. |
| `init_db.py` | Standalone script to create or migrate the database. |
| `templates/` | Jinja2 templates for customer pages, admin pages, and kiosk display. |
@ -242,7 +299,7 @@ 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
# Edit .env and set APP_SECRET_KEY, ADMIN_PASSWORD, SMTP_PASS, PUBLIC_BASE_URL, MUSICGPT_API_KEY
.venv/bin/python init_db.py
.venv/bin/python -m flask --app app run --host=0.0.0.0
```
@ -265,6 +322,8 @@ Visit:
| 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`. |
| 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. |
---