Transcription (bring your own files, optional in-app STT)

TranscriptX analyses transcripts after they are in the library.

Import Transcript admits JSON, SRT, VTT, and other supported files in the web UI. Transcribe Audio can run a host-orchestrated provider (whispermlx on macOS, WhisperX Docker when the daemon is reachable) or generate a copyable command for host-side tools. Engines stay out of the analysis image. Running Compose analysis, host whispermlx, and optional WhisperX/WebUI together: STT stacks.

This page is the mainstream path: you already have a transcript, or you have audio and will transcribe it here or on the host. Host watchers, bulk scripts, merge profiles, and the Python import API are under Host STT automation and Audio prep.

If you already have a transcript

  1. Open Import Transcript and upload the file (JSON, SRT, VTT, TXT, or HTML — formats).

  2. Optionally attach the source recording, or place same-stem audio in the mounted recordings folder so playback can link.

  3. If labels look like SPEAKER_00, name the speakers before you analyse. Most Balanced modules skip until speakers are named. Host USB ingest can auto-name after admit: auto-identify.md.

  4. Open Run Analysis, keep Balanced, and run it.

  5. Read Overview. If you already ran on placeholder labels, name the speakers and run again.

Walkthrough with screenshots: First analysis.

If you still need to transcribe audio

Host OS

Analysis

Preferred STT

macOS

Compose or native

Host whispermlx or Granite Speech mlx-audio (Run in app when native; Copy command / inbox-watch when Compose)

Linux

Compose

Host WhisperX Docker (Copy command or inbox-watch --transcribe command)

Windows

Docker Desktop / WSL2 Compose

Same WhisperX / WebUI path; Transcribe Audio PowerShell Copy command. No whispermlx. Host convert/admit: py -3 scripts\inbox-watch.py --transcribe none

Backend decision tree (same terms as the hardware probe)

Transcribe Audio captions a recommendation from the shared hardware probe (hardware.md). Engines stay on the host or in a separate Docker recipe — not in the analysis image.

  1. macOS + whispermlx available → prefer whispermlx (MLX). Optional Granite Speech (MLX) for Apache-2.0 keyword biasing and native speaker attribution without HF_TOKEN. WhisperX Docker on Apple Silicon is usually CPU-only.

  2. CUDA visible to this process and not TRANSCRIPTX_FORCE_CPU → WhisperX Docker cuda (--gpus all). Confirm the host GPU is passed into the STT container.

  3. Analysis container without CUDA → WhisperX Docker cpu for orchestration from this process; the host may still run a CUDA recipe via Copy command.

  4. Parakeet Docker → intended for CUDA Linux hosts; default device follows the same cuda/cpu honesty.

  5. Nemotron 3.5 Transcribe → last-resort CUDA path after Whisper/Parakeet; needs a local vLLM at 127.0.0.1. Not a Mac Run-in-app engine.

No STT wall-clock ETA in v1. Stacks and shared folders: STT stacks.

  1. Put the audio files in one folder on your computer (absolute path the Streamlit process can read).

  2. Open Transcribe Audio.

  3. Prefer Run in app when a provider is available (native GUI on the Mac for whispermlx; see STT stacks):

    • whispermlx — macOS host with whispermlx on PATH (or WHISPERMLX in whisperx.env).

    • Granite Speech (MLX) — macOS host with mlx-audio in a separate Python (MLX_AUDIO_PYTHON). Apache-2.0. 5.0-2b for accuracy and keyword lists (default off); 5.0-470m-turboctc for speed (undiarized); Plus speaker attribution when Diarize is on. Recipe: granite-speech.

    • WhisperX Docker — docker on PATH and a reachable daemon; CUDA uses --gpus all.

    • Nemotron 3.5 Transcribe — CUDA host with a local vLLM/NIM at 127.0.0.1:8000. Recipe: nemotron-transcribe.

  4. If no provider is available from this process (typical when Streamlit runs inside transcriptx-web), switch to Copy command, pick a tool, and run the snippet on the host.

  5. POSIX snippets paste into macOS, Linux, Git Bash, or WSL. PowerShell snippets are a second builder for Windows hosts. Streamlit does not execute copied snippets.

  6. With Import result into library on, a successful Run admits JSON automatically. Otherwise open Import Transcript.

Saved presets: on Copy command, save/load/delete command-gen fields under .transcriptx/profiles/stt_commands/. Presets store host paths and flags only — never HF_TOKEN (tokens stay in whisperx.env).

Keyword lists: Settings → Keywords (named lists under .transcriptx/profiles/keyword_lists/). Transcribe Audio Keyword biasing is off by default. Granite applies the selected list at decode time (max 2,000 terms); Nemotron appends them as Context terms:. Whisper providers ignore the lists in this version.

Step

Typical corpus path (whispermlx-missing)

1

Put audio files in one folder

2

Transcribe Audio → whispermlx-missing → set source + output folders → enable Dry-run → copy/run once to preview

3

Re-run without dry-run; already-transcribed stems are skipped (resume-friendly)

4

Import Transcript → upload JSON → optionally attach recordings

5

Name speakers if labels are still placeholders, then run Balanced or Quick

Keep analysis in Docker if you like; still run whispermlx on the Mac host, or mount the Docker socket if you want WhisperX Docker orchestration from the GUI. WhisperX Docker and Whisper-WebUI copyable recipes remain — WhisperX and Whisper-WebUI. Installing the bulk helper: Host STT automation.

What files you can bring

Compatible JSON from WhisperX, Scriberr, AssemblyAI, Deepgram, Otter, Google, Colab, or a manual edit. Subtitle exports (SRT / WebVTT) from Whisper-WebUI, RiverScript, or noScribe are importable, as are aTrain TXT (and JSON if it matches the segment shape).

The analysis image does not embed a transcription engine. The GUI can orchestrate whispermlx, Granite Speech mlx-audio, or WhisperX Docker when those tools are visible to the Streamlit process; otherwise it consumes files you provide (BYO import or Copy command). Where it sits next to STT, meeting, and qualitative-research products: comparison.md.

Naming such as *_transcriptx.json matches project conventions, but naming alone is not enough. Add files through Import Transcript so the library copy, sidecar, and archived original are created. Schema and layout: STORAGE.md. Programmatic import: Host STT automation.

Optional recipes

These stay outside the analysis image. Run in app orchestrates docker run / whispermlx from the Streamlit process when those binaries are visible. Copy command still never executes the snippet.

  • WhisperX — Transcribe Audio → Run in app (WhisperX Docker) or Copy command → WhisperX Docker. Full recipe: docs/recipes/whisperx/.

  • NeMo Parakeet / Canary — Transcribe Audio → Copy command → NeMo presets (Theme K), or Run in app → NeMo Parakeet Docker when configured (parakeet_docker). Convert JSONL with nemo_json_to_whisperx, then Import. Recipe: docs/recipes/parakeet/. CUDA Linux host only; on macOS prefer whispermlx or Granite mlx-audio.

  • Nemotron 3.5 Transcribe — Transcribe Audio → Copy command → Nemotron local vLLM (Theme K), or Run in app → nemotron_vllm when a loopback server is up. Convert with nemotron_json_to_whisperx. Recipe: docs/recipes/nemotron-transcribe/. CUDA host only (BF16 ≈ H100 80 GB); stub TRANSCRIPTX_NEMOTRON_STUB=1. On macOS prefer whispermlx or Granite.

  • Granite Speech — Transcribe Audio → Run in app (granite_mlx) or Copy command → mlx-audio. Convert with granite_json_to_whisperx if you ran the CLI yourself. Recipe: docs/recipes/granite-speech/. Dev stub: TRANSCRIPTX_GRANITE_STUB=1. Mistral Voxtral 3 is not integrated (no open weights).

  • Whisper-WebUI — Gradio UI; hand-off is SRT/VTT → Import Transcript. Full recipe (including Apple Silicon notes): docs/recipes/whisper-webui/README.md. On Apple Silicon the container is expected to use CPU inference; prefer host whispermlx when Metal/MLX speed matters.

When Whisper is noisy or speech overlaps

Situation

Suggested path

Multi-speaker meeting, everyone should appear in the transcript

Re-transcribe with WhisperX and enable diarization (--diarize in Copy command or provider options). Recipe: WhisperX.

One enrolled voice in a loud room (cocktail party, TV in background)

BYO CocktailASR-1 (Apache-2.0, large CUDA SpeechLLM): short reference clip of the target speaker, then mixture audio → one transcript stream (or empty if that voice is absent). Not Run-in-app; not multi-speaker diarized JSON. You still need timed text for import (segment the output or use a WhisperX-shaped adapter). Research: Open source ASR for TranscriptX; product stance: ROADMAP § Next.

Plain captions (YouTube, Whisper without diarize, SRT/VTT)

Import as usual — unlabeled turns become SPEAKER_00 on admit. Content-oriented analysis can run without naming speakers (T0). For a single diarized speaker, check Treat as single speaker on Run Analysis (T1). Multi-speaker interaction charts need names, diarized labels via Allow analysis without named speakers (T2), or re-transcribe with diarization — see settings.md.

Import a whole folder

On Import Transcript, section Import all from folder scans an absolute local directory and imports eligible files (JSON, SRT, VTT, TXT, HTML). Source files are never deleted or modified.

  • Docker: mount the host folder (typically HOST_TRANSCRIPT_INBOX_DIR → /mnt/transcript-inbox). Do not scan /mnt/transcripts or its subdirs.

  • Preview first. Already-imported stems, stem conflicts, and unrepairable files are blocked. Duplicate stems in the folder are all marked conflict.

  • Same-stem audio in approved recordings folders is listed as found or none; it is not copied automatically.

Limits and eligibility rules: Host STT automation.

Language variants

Import an alternate-language version next to an existing transcript using a filename suffix: meeting.json (base) and meeting_fr.json (French). Identify speakers on the base first; import then copies display names into the variant when the IDs match. Details: Host STT automation.

Why engines stay outside the analysis image

Transcription runs on the host (whispermlx binary, WhisperX Docker, or Whisper-WebUI). The GUI either orchestrates those host tools or copies a command.

Where

What runs

Host (terminal or in-app provider)

whispermlx / whispermlx-missing (macOS), Granite mlx-audio (macOS), WhisperX docker run, optional Nemotron local vLLM client, optional Whisper-WebUI Docker, inbox-watch

transcriptx-web (Docker or native)

Import, library, analysis, artifacts; optional STT orchestration only when the provider binary/daemon is visible to that process

The recommended install runs analysis in a Linux container. whispermlx must run on the macOS host (Metal/MLX); it cannot run inside that container. Keeping engines out of the analysis image avoids bloating it. Stacks, shared folders, and when Run in app works: STT stacks.

Theme H: optional in-app / host-orchestrated transcription is shipped for Whisper-class providers (whispermlx, whisperx_docker), optional parakeet_docker (CUDA NeMo Parakeet — configure per recipes/parakeet; dev stub via TRANSCRIPTX_PARAKEET_STUB=1), optional nemotron_vllm (local Nemotron 3.5 Transcribe — recipes/nemotron-transcribe; stub TRANSCRIPTX_NEMOTRON_STUB=1), and optional granite_mlx (Apple Silicon mlx-audio — recipes/granite-speech; stub TRANSCRIPTX_GRANITE_STUB=1) — ROADMAP.md theme H. Theme K Copy commands for NeMo Parakeet/Canary share nemo_json_to_whisperx; Nemotron uses nemotron_json_to_whisperx. YouTube ingest is later. In-app directory watch for audio auto-transcribe is theme G2 + H3 — directory_watcher.md.

Advanced

  • STT stacks — Compose + host whispermlx + optional WhisperX / WebUI

  • Host STT automation — whispermlx-missing, inbox-watch --transcribe, config, Python import API

  • Audio prep — Tools → Preprocessing / Auto-merge before you transcribe

  • Directory watcher — in-app inbox; audio auto_transcribe when an STT provider is available