Video Transcription Agent Skill

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).

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
• MAX_CHUNK_HOURS=4 pi-transcribe ~/Movies — change the long-recording chunk size (default 4.5h)
• 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

• Run pi-transcribe, passing the user's directory/file arguments (if any)
• The bin handles everything: file discovery, audio extraction, API

transcription, idempotency (skips files that already have a sibling .srt)

• Present the bin's summary output to the user (total found, already

transcribed, newly transcribed, failed)

• If there are failures, report which files failed and the error messages

Long recordings (>5h)

Soniox enforces a HARD per-request limit on audio duration (18000 s / 5 h),

independent of file size. Recordings longer than this are automatically split

into MAX_CHUNK_HOURS-sized chunks (default 4.5 h), 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 5 h, so the guard probes duration via ffprobe.

Prerequisites

• ffmpeg (with ffprobe) on PATH — for audio extraction, duration

probing, and chunk splitting. When absent, video files are skipped with a

warning; audio-only files still process.

• SONIOX_API_KEY — resolved from the environment first, then an optional

gitignored .env (current directory, then the skill dir). No secret ships in

the package; the bin fails fast with a clear message if the key is unresolved.

Environment overrides

| Variable | Default | Meaning |

|---|---|---|

| SONIOX_API_KEY | _(required)_ | Soniox API key. |

| MAX_CHUNK_HOURS | 4.5 | Chunk size for recordings over the 5 h duration limit. |

| MAX_AUDIO_MB | 200 | Reserved size guard; 0 disables. |

| TRANSCRIBE_CONCURRENCY | 8 | Files transcribed in parallel. Clamped to 1–100; 1 = serial. |