sagaphone/SPEC.md

Sagaphone — Spec

A web-based, procedural family-saga narrator with TTS. Sagaphone generates a random family tree and narrates its story via text-to-speech in the browser. It's meant as a "fall asleep" tool: open it on an iPad or phone, set a timer, and it reads family sagas until the timer runs out.

Language of narration: English. Tone: fantasy-medieval.

Architecture

• Frontend: SvelteKit — audio playback + UI only, no business logic.
• Backend: FastAPI, deployed on Zeus, reachable via a URL (e.g. sagaphone.orbitstack.casa).
• Reverse proxy: Caddy.
• TTS: Piper, runs server-side, audio streamed to the browser. Deliberately not Web Speech API — avoids iOS Audio Session issues, works in all browsers.
• Narration: Anthropic Haiku API, called server-side only (~$1.50/month at daily use). API key is never exposed to the client — no API keys in the frontend at all.

Flow

1. User opens Sagaphone in the browser and sets a timer.
2. On start: a family tree up to generation 6 is pre-generated as JSON — pure random logic, no LLM involved, runs in milliseconds.
3. An active line (branch) is picked at random.
4. The LLM generates a paragraph for the active person's current life stage.
5. TTS reads the paragraph aloud; the next paragraph is fetched in the background while it plays.
6. When a person's story is fully told: move to the next person in the active line, or switch lines if the line has died out.
7. Repeat until the timer runs out.

Features / Design Areas

• Data Model — enums, Person, Stage, EventEntry, FamilyTree, World.
• Event System — event categories, death probability, event tables, follow-bonus map.
• Line Logic — how the active family branch is chosen and switched.
• Implementation Notes — event weights/stage locks, living-family lookup, location/name/appearance generators.

Open Questions (from planning, still unresolved)

• Tune magic_factor and death probabilities via playtesting.
• Fill event tables with more concrete fantasy events.
• Define appearance generation in more detail.
• Work out the LLM prompt structure per life stage.
• Test the audio-loop workaround on iOS.
• Decide name / seed mechanism for the first test person.
• Plan deployment on Zeus.

Source

Planning originally done in Notion ("Sagaphone" page under "Dokumentation"). This repo is the implementation target; specs here are the source of truth going forward — update them alongside the code, don't let Notion and the repo drift apart.