Video Transcription

Transcribe video and audio files in-place to SRT subtitle format with speaker
diarization. Backed by the pi-transcribe CLI (a TypeScript port of the
original standalone skill — no Python).

Two backends. Soniox is the default and writes <name>.srt. AssemblyAI is
opt-in via TRANSCRIBE_BACKEND=assemblyai, uses the EU endpoint, and writes
<name>.diarize.srt — a different suffix, so both can transcribe the same file
and you can compare diarization side by side.

TRANSCRIBE_BACKEND=both runs them in one pass: audio is extracted once and
fed to both APIs, producing <name>.srt and <name>.diarize.srt together. Use
this when the user asks to compare diarization or wants both transcripts.

Usage

Run the pi-transcribe bin, optionally passing a directory or file paths.
Output .mp3 (extracted audio) and .srt (subtitles) files are placed
alongside the source files.

pi-transcribe [directory | file ...]

• No argument: scans ~/Movies (default)
• Single directory: scans the specified directory (e.g. a Google Recorder
  .m4a export folder)
• One or more file paths: transcribes exactly those files

Examples:

• /transcribe — transcribe all untranscribed files in ~/Movies
• /transcribe /path/to/recordings — transcribe files in a specific directory
• pi-transcribe "~/Movies/May 28 at 4-04 PM.m4a" "~/Movies/Feb 2 at 5-05 PM.m4a" — transcribe specific files
• TRANSCRIBE_BACKEND=assemblyai pi-transcribe ~/Movies — use AssemblyAI instead of Soniox (writes .diarize.srt, needs ASSEMBLY_AI_KEY)
• TRANSCRIBE_BACKEND=both pi-transcribe ~/Movies — run BOTH backends in one pass (writes .srt + .diarize.srt; needs both keys)
• TRANSCRIBE_BACKEND=assemblyai TRANSCRIBE_LANGUAGE=hu pi-transcribe file.m4a — pin Hungarian instead of auto-detecting
• MAX_CHUNK_HOURS=4 pi-transcribe ~/Movies — change the long-recording chunk size (default 4.5h Soniox / 9h AssemblyAI)
• TRANSCRIBE_CONCURRENCY=4 pi-transcribe ~/Movies — change how many files transcribe in parallel (default 8)

Parallel processing

Files transcribe through a bounded worker pool: up to TRANSCRIBE_CONCURRENCY
files (default 8) are in flight at once, overlapping the Soniox wait that
dominates each file's wall-clock time. Files are dispatched oldest-first but may
complete in any order. Set TRANSCRIBE_CONCURRENCY=1 for serial, deterministic
behavior. The value is clamped to 1–100 (100 = the Soniox pending-job cap).

Execution

1. Run pi-transcribe, passing the user's directory/file arguments (if any)
2. The bin handles everything: file discovery, audio extraction, API
   transcription, idempotency (skips files that already have a sibling .srt)
3. Present the bin's summary output to the user (total found, already
   transcribed, newly transcribed, failed)
4. If there are failures, report which files failed and the error messages

Long recordings

Each provider enforces a HARD per-request limit on audio duration,
independent of file size: Soniox 18000 s / 5 h, AssemblyAI 10 h. Recordings
longer than the limit are automatically split into MAX_CHUNK_HOURS-sized
chunks (default 4.5 h on Soniox, 9 h on AssemblyAI), transcribed separately, and
merged into a single SRT with correct absolute timestamps — full coverage, no
truncation. Override the chunk size with the MAX_CHUNK_HOURS env var.

Note: the limit is on duration, not megabytes — a long low-bitrate recording can
be small in size yet still exceed the cap, so the guard probes duration via
ffprobe.

Prerequisites

• ffmpeg (with ffprobe) — declared in this package's pi.tools
  manifest and resolved through the dashboard tool registry (PATH or
  the static npm packages: ffmpeg-static for ffmpeg,
  @ffprobe-installer/ffprobe for ffprobe — both optionalDependencies
  here). When absent, video files are skipped with a warning; audio-only
  files still process. pi-dashboard-ensure <package-root>/package.json
  reports both.
• The selected backend's API key — SONIOX_API_KEY or ASSEMBLY_AI_KEY,
  both declared as env probes in pi.tools. Same resolver: environment
  first, then an optional gitignored .env (current directory, then the skill
  dir). Only the active backend's key is required. No secret ships in the
  package; the bin fails fast with a clear message if the key is unresolved.

Environment overrides

Variable	Default	Meaning
TRANSCRIBE_BACKEND	soniox	soniox, assemblyai, both/all, or a comma list. Unknown values fall back to soniox.
SONIOX_API_KEY	(required for soniox)	Soniox API key.
ASSEMBLY_AI_KEY	(required for assemblyai)	AssemblyAI API key.
MAX_CHUNK_HOURS	4.5 / 9	Chunk size for long recordings; default follows the backend's duration cap.
MAX_AUDIO_MB	200	Reserved size guard; 0 disables.
TRANSCRIBE_CONCURRENCY	8	Files transcribed in parallel. Clamped to 1–100; 1 = serial.
TRANSCRIBE_SRT_SUFFIX	per backend	Override the sibling subtitle suffix (.srt / .diarize.srt).
TRANSCRIBE_LANGUAGE	(unset)	AssemblyAI only: pin a language (e.g. hu) instead of auto-detecting.
TRANSCRIBE_MAX_SPEAKERS	(unset)	AssemblyAI only: hard cap on speaker labels.

AssemblyAI backend notes

EU endpoint (api.eu.assemblyai.com) for data residency. Runs
speech_models: ["universal-3-5-pro", "universal-2"] with speaker_labels and
language_detection on: universal-3-5-pro natively covers 18 languages and
anything outside that set (Hungarian included) automatically falls back to
universal-2 (99 languages). Speaker letters A/B/C are normalised to
Speaker 1/Speaker 2/Speaker 3, so the SRT format is identical to Soniox's.