Skip to content

xonika9/agent-skills / skills/x9-video-transcripts

x9-video-transcripts

Verified

Use when the user wants offline, timestamped transcripts of their own local video or audio files, from one file to a whole folder, or wants to find where something was said in recordings already transcribed this way — «расшифруй ролики», «сделай субтитры к видео», «где в роликах я говорил про…», "transcribe these videos with timestamps". Do not use for online video links, a quick summary of what a video is about, live dictation, or translation.

FileKindSize
SKILL.mdskill md5.5 KB
references/models.mdmarkdown2.0 KB
references/onboarding.jsonconfig1.4 KB
scripts/test_transcripts.pyscript23.0 KB
scripts/transcripts.pyscript20.8 KB
---
name: x9-video-transcripts
description: Use when the user wants offline, timestamped transcripts of their own local video or audio files, from one file to a whole folder, or wants to find where something was said in recordings already transcribed this way — «расшифруй ролики», «сделай субтитры к видео», «где в роликах я говорил про…», "transcribe these videos with timestamps". Do not use for online video links, a quick summary of what a video is about, live dictation, or translation.
---

# Video transcripts

Turn local recordings into timestamped transcripts with whisper.cpp on the user's machine, and find moments in them later. A script does the recognition, so a batch costs the agent progress lines and a JSON summary, never the transcript text.

The [onboarding declaration](references/onboarding.json) is the machine-readable onboarding contract.

## Storage

Each source `<name>.<ext>` gets two files beside it:

- `<name>.transcript.srt` — standard subtitles for players and video editors;
- `<name>.transcript.txt` — `# source:` and `# language:` headers, then one `[hh:mm:ss] text` line per segment; search reads this file.

The `.transcript` suffix leaves the user's own `<name>.srt` untouched. Nothing central is created: a folder of 50 videos gains 100 small files next to them. `--out DIR` mirrors the same names under `DIR`; use it when the source location is read-only, short on synced space, or the user wants a separate library. After an interrupted run, repeat the same command.

A source listed under `collisions` is left untranscribed. Only renaming that source or giving it a different `--out` folder resolves the collision; a rerun or `--force` does not.

## Transcribe

```bash
python3 <skill-directory>/scripts/transcripts.py run <file-or-folder>... [--lang ru] [--out DIR] [--force] [--model FILE]
```

- Pass `--lang` whenever the spoken language is known; auto-detection misfires on short or music-heavy recordings.
- Folders are scanned recursively for common audio and video extensions, skipping hidden entries and without following folder symlinks; a file named explicitly is passed to ffmpeg whatever its extension.
- Runtime grows with audio length. For long recordings or more than a few files, run the command in the background and wait for it to exit instead of polling; progress goes to stderr, the summary to stdout. If the runtime stops the command before it exits, run the same command again: finished files are skipped. If a rerun stops again while the same file is `transcribing`, stop retrying and report that file's audio length and the runtime's command time limit.
- Use `--force` only when the user asks to redo existing transcripts, for example with another model or language.

Read the summary's `status`:

- `ok` (exit 0) — nothing failed. Files in `no_speech` were transcribed but contain no recognized speech; tell the user which ones.
- `partial` (exit 1) — report each `failed` and `collisions` entry with its reason. Rerunning retries the failed files once their cause is fixed.
- `aborted` (exit 1) — the same `whisper-cli` error hit consecutive files, so `not_attempted` were left for later. Report the error; it usually means a broken model file or a `whisper-cli` build without `--vad`.
- `setup_required`, `no_media`, or a missing path (exit 2) — nothing was transcribed. See [Setup](#setup) or correct the paths.

Never delete, move, or re-encode source media.

## Setup

`transcripts.py check` reports `ffmpeg`, `ffprobe`, `whisper-cli`, and the two model files; `check --download` fetches missing default models, about 875 MB, into `$X9_TRANSCRIPTS_MODELS` or `~/.cache/x9-video-transcripts/models`. A transcription request authorizes that download; state its size when starting it. Installing `ffmpeg` or whisper.cpp changes the system, so give the install command (with Homebrew: `brew install ffmpeg whisper-cpp`) and wait for the user's go-ahead. Set `X9_WHISPER_CLI` when `whisper-cli` is not on `PATH`.

## Find a moment

```bash
python3 <skill-directory>/scripts/transcripts.py search "<words>" <folder-or-file>... [--max 50]
```

Matching ignores case, treats ё as е, and drops the last letters of longer words so inflected forms match; every word must occur in one segment or across two adjacent ones. A file argument is a `.transcript.txt` or a source with its transcript beside it. Each hit prints the source path, or the transcript path when the recorded source has moved, and the timestamp. Exit 2 means a path is missing or has no transcript, which is not evidence that the words were never said. Answer from the hits, and read transcript lines into context only to quote, summarize, or check a hit's surroundings.

Recognition misspells rare names and terms, so when a name finds nothing, search for a distinctive ordinary word from the same passage or a likely alternative spelling.

## Quality limits

- Proper names, brand and game terms, and anglicisms carry most errors.
- Speech over loud music can be dropped, and the surrounding segment stretched, so timestamps near such passages may be off by many seconds.
- For a different accuracy or speed trade-off, read [references/models.md](references/models.md).

## Done

After `run`, every entry in the last summary's `failed`, `collisions`, `no_speech`, and `not_attempted` lists has been reported to the user with its reason. After `search`, the answer cites each relevant hit's file and timestamp, or states how many transcripts were searched without a match.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall