Art, narration and speech services

Every service on this page is optional. Each stays off, or falls back to a placeholder, when it is missing, and the session carries on. All are configured under Admin, Server settings, Images and Speech, or with environment variables; the guided setup finds ComfyUI, Kokoro and Whisper running on the machine and lists their checkpoints and voices. The repository's media setup guide walks each install step by step.

Pictures

ComfyUI

1. Install ComfyUI and the files for your selected catalog model or checkpoint. SDXL is one option; the setting supplies the style.
2. Start it on http://127.0.0.1:8188 (from Docker: http://host.docker.internal:8188).
3. In Admin, Images, choose ComfyUI, confirm the URL, and pick an installed checkpoint or a catalog model. A blank choice no longer takes the first checkpoint; it means no pictures.

The server submits a workflow suited to the selected model for portraits at creation, inline scene art, location pictures and campaign covers. Z-Image Turbo is offered beside the checkpoints: the server finds its files from ComfyUI's own lists and names a missing one before a job is sent. At a table playing in another language, the picture prompt is rewritten into English first. The reachability probe is administrator-only.

OpenAI-compatible images

No GPU. Set the key in Admin, Images, or OPENAI_IMAGE_API_KEY (falling back to OPENAI_API_KEY); choose an image model from the provider's list (blank means no pictures); OPENAI_IMAGE_BASE_URL for a proxy. Fast and slow request medium and high quality where supported. A model that refuses a requested shape can fall back to a supported size; a generic non-square refusal gets one square retry. A campaign whose text model points at api.openai.com lends its own key to this backend for that campaign's pictures, so one key covers storytelling and art; a key for any other host is never sent to OpenAI. Covers and library portraits paint from the server's defaults, not a campaign key.

The FLUX worker

An HTTP worker at FLUX_WORKER_URL (default :7869) wrapping the FLUX.2-klein backends from ultra-fast-image-gen: 1024 long side at four steps, 2048 for slow, up to two reference images. Choose MFLUX (home server) on a Mac or SDNQ (home server) elsewhere. AMD on Linux runs the worker on ROCm with IMAGE_SERVER_DEVICE=cuda; older AMD cards should use ComfyUI or the CPU.

Narration

Admin, Speech, Narration server picks Kokoro, any server that speaks OpenAI's speech endpoint (OpenAI itself included, with its own address, model and key), or off. Test narration speaks a line through the settings as typed. Choose a narration model; a non-OpenAI compatible speech server with exactly one listed model can supply it automatically. A blank field names the model it inherits or says no narration. Campaigns pick from the voices that server lists, or type a custom one, and Table settings, Narration and character voices gives the party, the cast and each kind of monster a voice of its own. For Kokoro:

1. Run Kokoro-FastAPI on http://127.0.0.1:8880.
2. Set the URL in Admin, Speech, or KOKORO_URL.
3. Turn Narration on in a campaign's Settings tab and pick a voice. Kokoro offers ten; Heart is the default.

Each Dungeon Master passage is split at sentence boundaries into chunks of up to 1,800 characters, rendered to MP3 under public/generated-audio/<campaign>/, and announced to the table; a passage starts playing as soon as its first clip is rendered, and playback is latest-only with per-listener mute, volume and replay. A quoted line is rendered in the voice of whoever the prose says spoke it. TTS_CONCURRENCY (default 2) caps speech requests at once, and a passage that could not be read aloud says why at the table.

Speech to text: faster-whisper

A faster-whisper server speaking the OpenAI transcription shape on http://127.0.0.1:8870, set in Admin, Speech, or STT_URL, and a model selected from the service's list. Blank uses its only model when there is exactly one; otherwise select STT_MODEL. It powers the push-to-talk button beside the message box (record, transcribe, confirm, send), a human DM's dictation, and, when a human-DM campaign turns it on, the transcription that drafts story beats and chapter summaries. With no Whisper service, install the built-in Whisper from Admin, Speech: it downloads on demand and, under Docker, lives in the odm-speech volume. Dictation can also fall back to OpenAI on the server's key after a transcription model is chosen in Admin, Speech or STT_OPENAI_MODEL. The desktop Story AI screen offers the built-in speech-to-text install too.

The sound library

The library ships with the project in public/ambience, and the Docker image carries it: 89 open-licensed recordings (public domain, Creative Commons and OpenGameArt) for 77 of the 78 cues, encoded as Opus, each credited in public/ambience/manifest.json and on the server's /licenses page. Nothing has to be installed. A release also attaches ambience-pack.zip, the same library as one file: Sound library in the admin panel installs it with progress, or npm run fetch-ambience -- --pack on the command line. npm run fetch-ambience curates more from OpenGameArt, Kevin MacLeod's catalogue, Wikimedia Commons and, with FREESOUND_API_KEY, Freesound. The desktop and Android apps download the library on demand instead of shipping it.

One GPU, one queue

Checking it works

• A missing image backend shows placeholder plates and, on an old request, Image tool requested with a Generate button.
• A narration switch that does nothing means the speech server is unreachable or switched off: press Test narration in Admin, Speech. The passage says why at the table, and the server log names the failed request.
• The Settings tab reports the campaign's actual image capability, so a table can see whether pictures will paint before asking for one.