54 lines
3.0 KiB
Markdown
54 lines
3.0 KiB
Markdown
---
|
||
status: approved
|
||
---
|
||
|
||
# Real content from a mounted folder (audio, timed lyrics, Homer)
|
||
|
||
Status: approved by user 2026-10-30 · Date: 2026-10-30
|
||
|
||
## Intent
|
||
|
||
The user added the real content in `~/epic-the-musical-content/`: all 40 *EPIC* songs as FLAC, timed
|
||
lyrics (`.lrc`) for 37 of them and plain-text lyrics for 3, saga cover art, and Samuel Butler's
|
||
public-domain prose translations of the *Odyssey* and the *Iliad* (Project Gutenberg #1727, #2199).
|
||
Mockups (starting with 17) and later the real app should use this content: real playback, line-synced
|
||
lyrics, and the actual Odyssey passage for a song.
|
||
|
||
The audio, lyrics and cover art are Jorge Rivera-Herrans' copyrighted work. The user chose (2026-10-30):
|
||
**"Mount it, never commit"** — the folder stays out of git and out of the Docker image; the server reads
|
||
it from a path given by `CONTENT_DIR`, mounted read-only into the container.
|
||
|
||
## Goals
|
||
|
||
1. **Server serves the mounted folder** when `CONTENT_DIR` is set:
|
||
- `GET /content/library.json` — every saga (name, year, cover URL) with its songs (track, title,
|
||
audio URL, lyrics URL and whether they are timed), built by scanning the folder.
|
||
- `GET /content/files/<path>` — the file at that path inside `CONTENT_DIR`, with the right content
|
||
type and HTTP range support so audio can seek. Paths outside `CONTENT_DIR` are refused.
|
||
- `GET /content/homer/<odyssey|iliad>/<book>.json` — one book: number, heading, summary line,
|
||
paragraphs. Prefers the Greek-names translations (Butcher & Lang's Odyssey, #1728; Lang, Leaf &
|
||
Myers' Iliad, #3059) when present in the folder, else Butler's (#1727, #2199).
|
||
- Without `CONTENT_DIR` (or with a missing folder), all `/content/*` routes answer 404 and every
|
||
other route works as before.
|
||
2. **Shared helpers** for clients: an LRC parser (timed lines, sorted, multi-stamp lines, metadata tags
|
||
skipped) and the library types.
|
||
3. **Nothing copyrighted is committed or baked into the image.** `.gitignore` and `.dockerignore`
|
||
guard against a copy inside the repo.
|
||
4. **Docs**: AGENTS.md lyrics rule updated (real lyrics only from the mounted folder, never in the
|
||
repo); ARCHITECTURE, DECISIONS; the preview container run command mounts the folder.
|
||
|
||
## Non-goals
|
||
|
||
- Changing existing mockups 01–16 to use real content.
|
||
- Transcoding FLAC (browsers play FLAC); caching or a CDN.
|
||
- Mapping songs to Odyssey passages (that is content work for the real app).
|
||
|
||
## Acceptance criteria
|
||
|
||
- `bun test` covers: library scan of a fixture folder (sagas in story order, songs by track, `.lrc`
|
||
preferred over `.txt`), LRC parsing, Homer book splitting, the `/content/*` routes with and without `CONTENT_DIR`,
|
||
path-traversal refusal, and a range request returning 206.
|
||
- The preview container, run with `-v ~/epic-the-musical-content:/content:ro -e CONTENT_DIR=/content`,
|
||
serves `/content/library.json` listing 9 sagas and 40 songs, and an audio file plays with seeking.
|
||
- `git status` shows no content files; the Docker image contains none.
|