Nat20-Notes/README.md

Nat20 Notes

Turn a recorded tabletop RPG session (audio or video) into two documents: a full GM/DM session log, and a spoiler-free player recap — using local transcription (WhisperX) and either a local LLM (Ollama) or any OpenAI-compatible hosted API for summarization.

Requirements

• Docker + Docker Compose
• An NVIDIA GPU with drivers + NVIDIA Container Toolkit installed on the host (for transcription; CPU-only works but is much slower)
• A free HuggingFace token — needed for speaker diarization. You'll also need to accept the terms on the gated pyannote model page it links you to on first run.
• Either: Ollama running somewhere reachable from this app (local or LAN), or an API key for a hosted LLM (OpenAI, or any OpenAI-compatible provider)

Quick start

git clone <this-repo>
cd nat20-notes
# Review docker-compose.yml — see Configuration below for env vars
docker compose up -d --build

Open http://<your-server>:8020 (d20 nod) and log in with the default admin credentials (admin / admin, overridable via NAT20_ADMIN_USERNAME and NAT20_ADMIN_PASSWORD). The first user is created automatically on first startup — no separate registration step.

Then follow the setup wizard:

1. Choose a Whisper model size based on your GPU's available VRAM (guidance shown in-app)
2. Give your campaign a name
3. Choose local Ollama or a hosted API for summarization, and paste your HF token
4. Optionally paste campaign/world context (NPC names, places) so summaries recognise them correctly

A reference compose file using named volumes only (no host paths) is at docker-compose.example.yml.

Using it

1. Log in with your username and password. Admins can create additional users at /users.
2. Select a campaign from the sidebar (or use the default). Each campaign has its own settings, sessions, and player recaps.
3. Upload a recording (audio or video — video is auto-converted, audio-only files skip that step and are much faster). Files over 90 MB are auto-chunked with 3-way concurrent uploads.
4. Transcribe — runs in the background. On completion you're automatically taken to the speaker-naming screen.
5. Name your speakers — a waveform-style "session reel" shows each detected speaker's segments; click any point to jump the audio there and hear who's talking, then type in their name. Use the checkboxes to merge speakers (e.g. when diarization over-splits one person into SPEAKER_00, SPEAKER_05, etc.).
6. Generate notes — click "Done naming" and confirm; notes generation starts automatically and you're taken to the job progress screen. When finished, navigate to the notes viewer.
7. Review & tweak — regenerate notes, rename speakers, or delete jobs/sessions from the session detail page.

Data layout

The app stores everything under /data (inside the container):

Directory / File	Contents
campaigns/{id}/audio/	Uploaded recordings and extracted audio, organised per campaign
campaigns/{id}/transcriptions/	Per-session transcript JSON files
campaigns/{id}/notes/	Generated notes (GM log + player recap)
app.db	SQLite database (users, campaigns, campaign_shares, sessions, speakers, campaign/global settings, jobs)

Configuration

Environment variables (NAT20_*)

Set these under the backend service in docker-compose.yml to prefill the setup wizard and override defaults. All are optional — the wizard and Settings page can set them at runtime.

Transcription

Variable	What it does	Values	Default	Notes
NAT20_WHISPER_MODEL	Whisper model size	tiny base small medium large-v3	medium	Larger = more accurate but uses more VRAM. medium fits most 6-8 GB GPUs; large-v3 needs ~10 GB+
NAT20_WHISPER_COMPUTE_TYPE	Compute precision	int8 float16 float32	int8	int8 = fastest / least VRAM. float16 = more accurate, more VRAM. float32 = full precision, slowest
NAT20_HF_TOKEN	HuggingFace token for speaker diarization	hf_...	(none)	Required for speaker attribution. Must accept pyannote gated-model terms with the same account first

LLM backend

Variable	What it does	Values	Default	Notes
NAT20_OLLAMA_HOST	Ollama server URL	URL	http://localhost:11434	Set to your Ollama host
NAT20_OLLAMA_MODEL	Ollama model name	any model on your server	qwen2.5:7b
NAT20_API_BASE_URL	OpenAI-compatible API base	URL	https://api.openai.com/v1	Uncomment and set to switch from Ollama
NAT20_API_KEY	API key	string	(none)
NAT20_API_MODEL	API model name	string	gpt-4o-mini

Summarization

Variable	What it does	Values	Default	Notes
NAT20_CHUNK_WORD_TARGET	Target words per summarisation chunk	number	2500	Long transcripts are split into chunks, each summarised separately, then combined. Lower = more LLM calls but finer granularity (good for models with small context windows). Higher = more context per chunk but may exceed the model's window. 2500 is safe for most models (8K–128K context)
NAT20_WORLD_CONTEXT	Campaign context string	text	(none)	Injected into every summarisation prompt so the LLM recognises NPCs, places, and lore correctly
NAT20_WORLD_CONTEXT_PATH	Path to campaign context file inside container	container path	(none)	Alternative to NAT20_WORLD_CONTEXT for large campaign bibles you update independently
NAT20_PLAYER_RECAP_STYLE	Player recap format	story diary bullets custom	story
NAT20_PLAYER_RECAP_CUSTOM_PROMPT	Custom prompt (only when style is custom)	text	(none)

Auth

Variable	What it does	Values	Default	Notes
NAT20_ADMIN_USERNAME	Admin username	string	admin	Created on first startup if no users exist
NAT20_ADMIN_PASSWORD	Admin password	string	admin
NAT20_JWT_SECRET	JWT signing key	string	(random)	Set to a fixed value so tokens survive restarts

Setup wizard

Variable	What it does	Values	Default	Notes
NAT20_ONBOARDING_COMPLETED	Skip the setup wizard	true or false	false	Set to "true" after you finish the wizard once

Campaigns

Campaigns organise sessions, settings, and context into separate silos. On first run a default campaign is created automatically; you can name it during the setup wizard and rename it later in Settings.

Key features:

• Per-campaign settings — each campaign has its own Whisper model, LLM config, world context, and player recap style. Switch campaigns in the sidebar to change which settings apply to new sessions.
• Sharing — the admin can share a campaign with other registered users from the campaign's detail page. Shared users can upload sessions and generate notes within that campaign.
• User management — admins can create additional users via the Users page (/users). Every user authenticates with the same login form.

Campaign context

You can paste context directly in the Settings page, or point to a file inside the container using NAT20_WORLD_CONTEXT_PATH. The file version is useful for large campaign bibles that you update independently.

Notes on hardware

Transcription is GPU-bound and by far the slowest step for long sessions. Summarization is comparatively light — a 7-8B parameter local model is sufficient for most groups; only step up in size if you have the VRAM headroom after Whisper's footprint (they don't run at the same time, so you only need enough VRAM for whichever is currently running, plus normal system overhead from other GPU-using services).

Architecture

• backend/ — FastAPI, SQLite (no external DB needed), WhisperX as a library (no nested Docker), in-process ThreadPoolExecutor background jobs (no Redis/Celery). JWT auth with HMAC-SHA256 tokens, scrypt password hashing.
• frontend/ — React 18 + Vite + Tailwind, served via nginx (listens on port 8020) which proxies /api to the backend. Auth state managed via React context; global fetch interceptor adds Authorization: Bearer to all API calls.

CI/CD

The backend is split into two Docker images for fast rebuilds:

Image	Build time	Contents
whisperx-base (.deps)	5-10 min, only when requirements.txt changes	PyTorch 2.3.1 + cu121, WhisperX, ctranslate2, ffmpeg
backend (thin)	~10 seconds	App code only (FROM whisperx-base)

Both run as standard Docker Compose services — no special orchestration needed beyond GPU passthrough for the backend.