Epic-The-Musical-Timeline/docs/specs/003-content-mount.md

status

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.