StoryForge + TTS Studio — Build Recipe

Take a bare machine to a running copy of StoryForge + TTS Studio — two coupled self-hosted services that together do one distinctive thing: generate a story with an LLM, then read it aloud paragraph-by-paragraph in a real neural voice, with a 3-ahead audio prefetch pipeline, retry/backoff, and the active paragraph highlighted and auto-scrolling. StoryForge (:8234) is a family-style story generator — shared character pool, per-session context, 8 genres, a 300–5,000-word slider, exactly 5 AI plot hooks, SSE-streamed stories. TTS Studio (:8221) is a dual-backend voice browser (~54 Kokoro voices + 30 styled Gemini voices). StoryForge does no TTS itself — it proxies /api/voices and /api/tts to TTS Studio, which is the whole point of cloning them together.

Status: ✅ Verified 2026-08-02 — built from this clone on a Linux Docker host (docker compose up -d --build). All three services came up healthy (story-generator :8234, tts-studio :8221, bundled kokoro-fastapi-cpu); the DB seeded 6 fictional characters (Captain Nova, Pip the Fox, Luna Quill, Bramble, Mira Stoneweaver, Old Salt) + two sample stories, and the key-free Kokoro voice list loaded (/api/voices → 200) with no keys and no GPU. A browser pass showed the StoryForge sessions and the coupling to TTS Studio. All three tiers covered; the prebuilt tarball (docker save storyforge-tts-story-generator storyforge-tts-tts-studio + the pulled kokoro image) is recorded in ../PREBUILT_IMAGES.md.

Sensitive data: none. The live DBs (real family character names + TTS history) are never shipped — a synthetic fictional-character seed replaces them; home-LAN voice-service coupling was replaced with the bundled key-free Kokoro service.

Sensitive data — read this. StoryForge's real database is family data: 15 real first names and 5 stories written about those people. None of it is in this clone. The shipped stories.db is created empty on first boot and seeded with fully fictional characters (Captain Nova, Pip the Fox, Mira Stoneweaver, Bramble, Old Salt, Luna Quill) and two short original sample stories written for the demo. No TTS history ships (empty on first run). The one rule when reproducing: never copy a running stories.db or tts-studio.db — ship empty volumes, which this recipe does.

What it is

Three containers (the first two run by default; the LLM proxy is opt-in):

Both frontends are hand-built vanilla-JS SPAs (no build step). The read-aloud engine (3-ahead prefetch, retry/backoff, resume-from-failed-chunk, per-paragraph play + highlight) lives in story-generator/public/app.js.

Prerequisites

New machine? See ../SETUP.md. Then, per tier:

Configuration — nothing required

docker compose up needs no .env and no keys. What works at each level:

All documented one line at a time in clone/.env.example.

Tier 1 — Run the prebuilt containers (recommended)

Availability: the prebuilt images are available on request — they are not published or linked anywhere. Ask Kevin for them, or build from source via Tier 2. (The kokoro image is pulled from its public upstream either way.)

docker load -i storyforge-tts-clone-image.tar   # loads the two first-party images
cd clone
docker compose up -d                            # → http://localhost:8234  (StoryForge)
                                                #   http://localhost:8221  (TTS Studio)

To produce the tarball on a machine that has built the images (Tier 2): docker save clone-story-generator clone-tts-studio -o storyforge-tts-clone-image.tar. The kokoro image is large (several GB — voice models baked in) and is pulled from its public registry, not shipped in the tarball.

Tier 2 — Build from source

cd clone
docker compose up -d --build                    # → http://localhost:8234 and :8221
curl -s localhost:8234/health                   # → {"status":"ok"}
curl -s localhost:8221/health                   # → {"status":"ok"}

First boot: the kokoro image is pulled and loads its voice models (this is the slow part — several GB, a few minutes). Once TTS Studio's status dot goes KOKORO LIVE, open StoryForge → a seeded session (e.g. "The Comet's Secret") → Stories tab → expand a story → 🔊 Listen and it reads aloud in a real neural voice, highlighting each paragraph. StoryForge boots with the fictional seed already present; TTS Studio history starts empty.

Tier 3 — Bare-metal (two Node apps + a Kokoro server)

cd clone
# TTS Studio (Node 20+) — point it at any OpenAI-compatible TTS server
cd tts-studio && npm install --omit=dev
DB_PATH=./data/tts.db AUDIO_DIR=./public/audio \
  KOKORO_API_URL=http://localhost:8880 node server.js        # :8221

# StoryForge (Node 20+, separate shell, from clone/)
cd story-generator && npm install
DB_PATH=./data/stories.db AUDIO_DIR=./data/audio \
  TTSTUDIO_URL=http://localhost:8221 node server.js          # :8234 (seeds on first run)

You still need a Kokoro server for read-aloud — the easiest is docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.2. On Windows, set the same variables with $env: before node server.js.

Optional extras (all off by default)

• Live story generation + Gemini voices — docker compose --profile llm up -d --build. Put a provider key in .env (OPENAI_API_KEY for paid-chat, GEMINI_API_KEY for gemini-tts) and set LITELLM_URL=http://litellm:4000 + LITELLM_KEY=<any master key>. Then StoryForge's Generate Plot Suggestions and story streaming work, and TTS Studio's Gemini voices synthesize.
• Local key-free story generation (Ollama) — no proxy needed:

bash # in clone/.env LITELLM_URL=http://host.docker.internal:11434 # the app appends /v1/chat/completions LITELLM_KEY=ollama LITELLM_MODEL=llama3.2 # override the 'paid-chat' alias (Ollama covers story generation; Gemini voices still need a real Gemini key. Kokoro read-aloud is unaffected — always key-free.)

Verify

curl -s localhost:8234/health                       # StoryForge → {"status":"ok"}
curl -s localhost:8221/health                       # TTS Studio → {"status":"ok"}
curl -s localhost:8221/api/voices | head -c 300     # Kokoro voice list (once kokoro is warm) + 30 Gemini
curl -s localhost:8234/api/sessions                 # the two seeded fictional sessions
# key-free read-aloud (once Kokoro is live) — one chunk through the StoryForge→TTS-Studio proxy:
curl -s -X POST localhost:8234/api/tts -H 'Content-Type: application/json' \
  -d '{"text":"Hello from StoryForge.","voice":"af_bella"}' --output chunk.mp3 && ls -l chunk.mp3

Run StoryForge's tests (offline, zero keys — the LLM is mocked, :memory: DB):

cd clone/story-generator && npm install && npm test        # Jest + Supertest — 29 tests

What was stripped from the personal version (de-identification + minimalism)

• Family data → a synthetic seed. The real stories.db (15 real first names, 5 stories about real people) and the tts-studio.db history (which stores every synthesized input) are never shipped. Fresh empty volumes; StoryForge seeds fully fictional characters + two original sample stories on first boot (story-generator/seed.js), so read-aloud works immediately with no family exposure.
• Home-network coupling (tts-studio/server.js lines 10–14). Hardcoded env defaults pointed at a local (GPU PC) Kokoro server, a home-LAN Asset-Harvester, a LAN-IP public base URL, and a home LiteLLM gateway. All four were replaced with localhost / service-DNS / blank, and wired in docker-compose.yml to the bundled kokoro service.
• The Asset-Harvester hand-off. That button pushed audio to a companion home-LAN service; it is dropped from the UI and its route is off unless you set ASSET_HARVESTER_URL.
• The hard LiteLLM coupling. Story generation and Gemini voices now activate only when LITELLM_URL is set (any OpenAI-compatible endpoint; Ollama key-free for stories). The model aliases paid-chat / gemini-tts / best-tts are env-overridable so no personal gateway is assumed.
• The multi-service home compose (compose/apps.yml, the homeserver network, /mnt/... mounts, the shared LiteLLM gateway + injected keys) → a standalone docker-compose.yml with named volumes, a bridge network, and an opt-in --profile llm.
• Dev artifacts — the .superpowers/ brainstorm droppings and docs/ design specs were not copied (not needed to run).

Known limitations (stated honestly)

• Personal-LAN tools: no authentication. Both apps are unauthenticated and bind all interfaces. Put them behind a reverse proxy with auth before exposing anything.
• Kokoro-CPU is real but slow, and the kokoro image is large (several GB — voice models baked in), so the first up is a long pull. GPU is not required; if you have one you can point KOKORO_API_URL at a GPU Kokoro instead.
• Story generation needs an LLM. By design it is off by default and fails with a clear message; the seeded stories exist precisely so read-aloud is demonstrable without one.
• Gemini voices need a real Gemini key (via LiteLLM). Without it they list in the UI but return a clear "pick a Kokoro voice" error — the key-free voice path is Kokoro (and browser Web-Speech).
• Legacy audio route. StoryForge keeps a per-story /api/stories/:id/audio/:voice cache route (best-tts via /audio/speech) that was already effectively dead upstream (0 rows in the live DB); it is left as honest legacy and is LLM-gated like the rest.
• Backend is chosen by voice-name shape (xx_name = Kokoro, else Gemini) — a deliberate convention, not validation.
• The containers run as root (as the originals did); hardening is left to the deployer.

Provenance — data / model (no training, no GPU required)

Neither app trains anything and no model weights ship in the first-party images. The only bundled model is the upstream remsky/kokoro-fastapi-cpu image (Kokoro-82M voices, CPU), pulled from its public registry. The seeded characters and the two sample stories are original fiction written for this clone — no real people, no data from any running instance. Measured facts (from the dossier): StoryForge = 6-table SQLite, 8 genres, 300–5,000-word slider, exactly 5 plot hooks, SSE streaming, 29 Jest tests; read-aloud LOOKAHEAD=3, retry 3× linear backoff, chunk sizes 4000/600/220 (Kokoro/ Gemini/browser). TTS Studio = ~54 Kokoro + 30 Gemini voices, 5,000-char cap, PCM16→WAV via a hand-built 44-byte RIFF header.