58 lines
2.6 KiB
Markdown
58 lines
2.6 KiB
Markdown
|
# 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](spec/data-model.md) — enums, `Person`, `Stage`, `EventEntry`, `FamilyTree`, `World`.
|
||
|
|
- [Event System](spec/event-system.md) — event categories, death probability, event tables, follow-bonus map.
|
||
|
|
- [Line Logic](spec/line-logic.md) — how the active family branch is chosen and switched.
|
||
|
|
- [Implementation Notes](spec/implementation-notes.md) — 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.
|