STT stacks together (analysis + host whispermlx + optional WhisperX / WebUI)¶

TranscriptX analysis and speech-to-text are separate processes. There is no single Compose file that starts Whisper inside transcriptx-web. This page is the operator recipe for running the pieces at the same time and sharing folders so Import / Admit work.

whispermlx must run on the macOS host. It is a Metal/MLX binary. It cannot run in the Linux analysis image, and Docker Desktop on Mac cannot give it GPU.

Engines stay out of transcriptx:latest. The GUI can orchestrate them only when those binaries are visible to the Streamlit process. Canonical Compose does not mount /var/run/docker.sock and does not ship a docker CLI (analysis-only image).

Mainstream Transcribe Audio steps: transcription.md. Bulk host scripts: host-stt.md.

What runs where¶

Piece	Process	Typical URL / command	Role
TranscriptX GUI	`transcriptx-web` Compose or native `./transcriptx.sh`	http://127.0.0.1:8501	Import, admit, analysis. Run in app only if providers are visible.
whispermlx	macOS host (`PATH` or `WHISPERMLX`)	`whispermlx …` / `whispermlx-missing` / `inbox-watch`	Preferred STT on Apple Silicon. Not on Windows/Linux.
Granite Speech	macOS host (`MLX_AUDIO_PYTHON` + mlx-audio)	Transcribe Audio → Granite Speech (MLX)	Apache-2.0; keyword lists; Plus speaker attribution. Not in analysis venv. granite-speech.
WhisperX	Host `docker run` (Copy command; POSIX or PowerShell)	Transcribe Audio → Copy command	Diarized JSON when Docker is on the host. Primary STT on Linux/Windows.
NeMo Parakeet / Canary	CUDA host `docker run` + JSONL converter (Theme K; optional Run in app `parakeet_docker`)	Transcribe Audio → Copy command → NeMo presets	WhisperX-shaped JSON via `nemo_json_to_whisperx` — parakeet/README.md. Not on macOS Run-in-app.
Whisper-WebUI	Optional extra Compose service	http://127.0.0.1:7860	Gradio UI → SRT/VTT → Import Transcript.
inbox-watch (non-Mac)	Host Python	`--transcribe none` or `command`	Convert/copy/admit; STT via WhisperX argv or BYO.

Pick one Streamlit process for a given library (TRANSCRIPTX_DATA_DIR / HOST_TRANSCRIPTS_DIR). Do not run Compose GUI and native GUI against the same data dir at once.

Shared folders (the wiring)¶

Use the same host paths in .env, whisperx.env, and host JSON configs. Do not point WhisperX’s recipe-local ./data/transcripts at a clone-relative folder if your library lives elsewhere.

Host path (examples)	Who writes	Who reads
`HOST_RECORDINGS_DIR`	recorder, `inbox-watch` convert, Tools → Merge	STT, playback, Compose `/mnt/recordings`
`HOST_TRANSCRIPTS_DIR/originals/`	whispermlx-missing, WhisperX JSON, host watchers	Admit from originals/, `inbox-watch --admit`
Managed library root (`HOST_TRANSCRIPTS_DIR`)	Import / Admit	analysis
`HOST_TRANSCRIPT_INBOX_DIR`	you drop BYO files	Import all from folder / in-app watcher — not `originals/`
`whisperx.env` (`HF_TOKEN`, `WHISPERMLX`)	you	host STT and Copy command env-file field

originals/ is not the import inbox. If STT succeeds but the library looks empty, admit from originals/ — see ROADMAP Now (folder hygiene).

Choose a topology¶

A — Compose GUI + host whispermlx (recommended on this Mac)¶

Use when analysis should stay in Docker and STT should use Metal.

.env with HOST_RECORDINGS_DIR (absolute, outside the clone).
Analysis GUI:
```
docker compose up -d transcriptx-web
```
Host STT (pick one):
- USB / drop folder: inbox-watch with --transcribe whispermlx-missing and optional --admit — host-stt.md
- Batch folder: whispermlx-missing writing JSON under …/originals/
- One-off: Transcribe Audio → Copy command → whispermlx / whispermlx-missing, paste into a host terminal (not docker exec into transcriptx-web)
In the GUI: Import Transcript or Admit from originals/.

Run in app and watcher auto_transcribe inside Compose will usually show providers unavailable (no whispermlx, no docker CLI). That is expected. Use Copy command or host inbox-watch.

B — Native GUI + host whispermlx (Run in app)¶

Use when you want Transcribe Audio → Run in app to call whispermlx itself.

whispermlx on PATH, or WHISPERMLX in repo-root whisperx.env.
./transcriptx.sh (or python -m transcriptx.web).
Transcribe Audio → Run in app → whispermlx.
Optional: same machine can still docker run WhisperX if Docker Desktop is up (Run in app → WhisperX Docker), because native Streamlit sees the host docker CLI.

Do not also docker compose up transcriptx-web against the same library.

C — Compose GUI + WhisperX on the host¶

Use when you need CUDA WhisperX (Linux NVIDIA) or CPU WhisperX in Docker, with analysis still in Compose.

docker compose up -d transcriptx-web
Transcribe Audio → Copy command → WhisperX Docker → run the snippet on the host.
Point output at HOST_TRANSCRIPTS_DIR/originals/ (or import the JSON file).
Full flags / HF_TOKEN: WhisperX recipe

The idle docker-compose.whisperx.yml service (docker exec into a long-running container) is a standalone reference. It is not what Run in app calls. Run in app uses docker run --rm.

D — Optional Whisper-WebUI beside analysis Compose¶

Gradio is a third container. It does not speak to Streamlit except through files you import.

From the repo root (loads .env; keep local override if you use it):

export CLONE_DIR="${CLONE_DIR:-$HOME/Whisper-WebUI}"
export OUTDIR="${OUTDIR:-$HOME/whisper-webui-outputs}"
mkdir -p "$OUTDIR" "$CLONE_DIR/models" "$CLONE_DIR/outputs" "$CLONE_DIR/configs"

docker compose \
  -f docker-compose.yml \
  -f docker-compose.override.yml \
  -f docs/recipes/stt-stacks/docker-compose.stt-stacks.yml \
  up -d

Omit -f docker-compose.override.yml if that file is absent. Open http://127.0.0.1:8501 (analysis) and http://127.0.0.1:7860 (WebUI). Export SRT/VTT → Import Transcript. Details: Whisper-WebUI recipe.

Validate without pulling images:

docker compose \
  -f docker-compose.yml \
  -f docs/recipes/stt-stacks/docker-compose.stt-stacks.yml \
  config

(HOST_RECORDINGS_DIR must be set in .env for the analysis service.)

E — Windows / Linux host inbox (no whispermlx)¶

Use when analysis is Compose and the host is not macOS.

docker compose up -d transcriptx-web (on Windows: Docker Desktop or WSL2).

Host convert + optional admit (no MLX):

# Linux
python3 scripts/inbox-watch.py --once --transcribe none --admit \
  --inbox … --recordings … --transcripts …/originals

# Windows (PowerShell / cmd)
py -3 scripts\inbox-watch.py --once --transcribe none --admit ^
  --inbox … --recordings … --transcripts …\originals

STT: either
- Transcribe Audio → Copy command → WhisperX Docker (PowerShell builder on Windows), paste on the host; or
- inbox-watch --transcribe command with a transcribe_cmd argv (WhisperX docker run or BYO) — host-stt.md.
Import / Admit into the library as usual.

Not available on Windows/Linux: whispermlx, whispermlx-missing as a working STT binary, macOS launchd agent, auto USB stage detection (use --stage-local if needed). There is no Task Scheduler sample yet; run --once from Task Scheduler yourself or keep a console --watch.

What this recipe will not do¶

Put whispermlx inside transcriptx-web.
Mount the Docker socket into the analysis container (forbidden by analysis-only invariants).
Start Parakeet / Canary / YouTube (theme H5+, deferred).
Auto-join meeting bots.
Ship whispermlx or a Mac-parity login agent on Windows.

Troubleshooting¶

Symptom	Likely cause
Run in app: provider unavailable in Compose GUI	Expected. Use topology A Copy command / host watchers, or topology B native GUI.
whispermlx not found	Install on macOS host; `which whispermlx`; set `WHISPERMLX` in `whisperx.env`. On Windows/Linux use topology C or E instead.
`--admit` cannot find Python on Windows	Use `.transcriptx\Scripts\python.exe` or pass `--admit-python`.
JSON on disk, empty library	Wrote `originals/` but did not Admit; or Import all from folder pointed at the wrong inbox.
WhisperX 403 / gated model	`HF_TOKEN` + accept pyannote terms — WhisperX recipe.
Two GUIs fighting	Stop Compose or native; one Streamlit per library.