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
- Install ComfyUI and a checkpoint. Any SDXL-class checkpoint works; the setting supplies the style.
- Start it on
http://127.0.0.1:8188(from Docker:http://host.docker.internal:8188). - In Admin, Images, choose ComfyUI, confirm the URL, and pick a checkpoint, or leave Auto to take the first one listed.
The server submits a plain text-to-image workflow (25 steps, CFG 6, sizes clamped to a 1024 or 1344 long side) 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); blank model means gpt-image-1; OPENAI_IMAGE_BASE_URL for a proxy. Fast and slow map to the model's medium and high quality. 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 narration 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. Campaigns pick from the voices that server lists, or type a custom one, and Game settings, Voices gives the party, the cast and each kind of monster a voice of its own. For Kokoro:
- Run Kokoro-FastAPI on
http://127.0.0.1:8880. - Set the URL in Admin, Speech, or
KOKORO_URL. - Turn Narration on in a campaign's Setup 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, with STT_MODEL defaulting to distil-large-v3. 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.
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
Image generation and text-to-speech share a serial media queue, with a separate lane for narration so a read-aloud never waits on a render. On an integrated GPU the image model and the Dungeon Master model compete for one memory pool, so jobs are queued rather than run in parallel; a scene picture can arrive a little after its paragraph, and a turn can wait behind a render.
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 Setup tab reports the campaign's actual image capability, so a table can see whether pictures will paint before asking for one.