xonika9/agent-skills / skills/x9-video-transcripts
x9-video-transcripts
VerifiedUse 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 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] textline 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
python3 <skill-directory>/scripts/transcripts.py run <file-or-folder>... [--lang ru] [--out DIR] [--force] [--model FILE]
- Pass
--langwhenever 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
--forceonly 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 inno_speechwere transcribed but contain no recognized speech; tell the user which ones.partial(exit 1) — report eachfailedandcollisionsentry with its reason. Rerunning retries the failed files once their cause is fixed.aborted(exit 1) — the samewhisper-clierror hit consecutive files, sonot_attemptedwere left for later. Report the error; it usually means a broken model file or awhisper-clibuild without--vad.setup_required,no_media, or a missing path (exit 2) — nothing was transcribed. See 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
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.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |