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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| references/models.md | markdown | 2.0 KB |
| references/onboarding.json | config | 1.4 KB |
| scripts/test_transcripts.py | script | 23.0 KB |
| scripts/transcripts.py | script | 20.8 KB |
scripts/transcripts.py
View on GitHub#!/usr/bin/env python3
"""Local timestamped transcripts for video and audio files (ffmpeg + whisper.cpp).
Subcommands:
check [--download] report dependencies; fetch missing default models
run PATH... [--out DIR] [--lang L] [--force] [--model FILE]
search QUERY PATH... [--max N]
Outputs per source `<stem>.<ext>`: `<stem>.transcript.srt` and `<stem>.transcript.txt`,
next to the source or mirrored under --out. Only stdlib is used.
"""
from __future__ import annotations
import argparse
import json
import os
import re
import shutil
import subprocess
import sys
import tempfile
import time
import urllib.request
from pathlib import Path
# Extensions picked up when scanning folders; files named explicitly are passed to ffmpeg as-is.
MEDIA_EXT = {
".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".ts", ".mpg", ".mpeg",
".wmv", ".flv", ".3gp", ".mp3", ".m4a", ".wav", ".flac", ".ogg", ".oga", ".opus", ".aac",
".wma", ".aif", ".aiff", ".amr",
}
SRT_SUFFIX = ".transcript.srt"
TXT_SUFFIX = ".transcript.txt"
MODELS = {
"whisper": (
"ggml-large-v3-turbo-q8_0.bin",
"https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q8_0.bin",
),
"vad": (
"ggml-silero-v6.2.0.bin",
"https://huggingface.co/ggml-org/whisper-vad/resolve/main/ggml-silero-v6.2.0.bin",
),
}
TIME_RE = re.compile(r"(\d+):(\d{2}):(\d{2})[,.](\d{3})\s*-->\s*(\d+):(\d{2}):(\d{2})[,.](\d{3})")
LANG_RE = re.compile(r"auto-detected language:\s*([a-z]{2,3})")
MIN_TIMEOUT = 900 # seconds per file, raised to 3x the audio length for long recordings
def models_dir() -> Path:
env = os.environ.get("X9_TRANSCRIPTS_MODELS")
return Path(env).expanduser() if env else Path.home() / ".cache" / "x9-video-transcripts" / "models"
def whisper_cli() -> str | None:
# shutil.which also validates an explicit path, so a wrong X9_WHISPER_CLI reads as missing.
return shutil.which(os.environ.get("X9_WHISPER_CLI") or "whisper-cli")
# ---------- pure helpers (unit-tested) ----------
def parse_srt(text: str) -> list[tuple[float, float, str]]:
segs: list[tuple[float, float, str]] = []
for block in re.split(r"\n\s*\n", text.replace("\r\n", "\n")):
lines = [l.strip() for l in block.strip().splitlines()]
for k, line in enumerate(lines):
m = TIME_RE.search(line)
if not m:
continue
g = [int(x) for x in m.groups()]
body = " ".join(l for l in lines[k + 1:] if l).strip()
if body:
segs.append((g[0] * 3600 + g[1] * 60 + g[2] + g[3] / 1000,
g[4] * 3600 + g[5] * 60 + g[6] + g[7] / 1000, body))
break
return segs
def hms(seconds: float) -> str:
s = int(seconds)
return f"{s // 3600:02d}:{s % 3600 // 60:02d}:{s % 60:02d}"
def srt_to_txt(srt_text: str, source: Path, lang: str) -> str:
lines = [f"# source: {source}", f"# language: {lang}"]
lines += [f"[{hms(s)}] {t}" for s, _e, t in parse_srt(srt_text)]
return "\n".join(lines) + "\n"
def _walk(folder: Path):
"""Media files under folder; hidden entries are skipped and folder symlinks are not followed."""
for dirpath, dirnames, filenames in os.walk(folder, followlinks=False):
dirnames[:] = sorted(d for d in dirnames if not d.startswith("."))
for name in sorted(filenames):
f = Path(dirpath) / name
if not name.startswith(".") and f.suffix.lower() in MEDIA_EXT and f.is_file():
yield f
def discover(paths: list[Path]) -> list[tuple[Path, Path]]:
"""Return (source, root) pairs; root is the widest folder argument containing the source."""
args = [Path(os.path.abspath(p.expanduser())) for p in paths]
missing = [str(p) for p in args if not p.exists()]
if missing:
raise FileNotFoundError(", ".join(missing))
folders = sorted((p for p in args if p.is_dir()), key=lambda p: len(p.parts))
sources: list[Path] = []
for p in args:
sources += list(_walk(p)) if p.is_dir() else [p]
found: dict[Path, Path] = {}
for f in sources:
root = next((d for d in folders if f.parent == d or d in f.parents), f.parent)
found.setdefault(f, root)
return list(found.items())
def output_base(source: Path, root: Path, out: Path | None) -> Path:
stem = source.name[: -len(source.suffix)] if source.suffix else source.name
if out is None:
return source.parent / stem
return Path(os.path.abspath(out.expanduser())) / source.parent.relative_to(root) / stem
def output_key(base: Path) -> str:
# macOS and Windows volumes are usually case-insensitive: Clip.MP4 and clip.mov share outputs.
return str(base).casefold()
def recorded_source(txt: Path) -> Path | None:
"""The source path written into a transcript's header, if any."""
try:
with open(txt, encoding="utf-8", errors="replace") as f:
head = [f.readline() for _ in range(3)]
except OSError:
return None
line = next((l for l in head if l.startswith("# source: ")), None)
return Path(line[len("# source: "):].rstrip("\n")) if line else None
def owned_by_other(source: Path, base: Path) -> Path | None:
"""An existing different source that the transcript at base already belongs to."""
rec = recorded_source(Path(str(base) + TXT_SUFFIX))
if rec is None or not rec.exists():
return None # no transcript yet, or its source moved away: treat as this source's
return None if os.path.samefile(rec, source) else rec
def is_current(source: Path, base: Path) -> bool:
srt, txt = Path(str(base) + SRT_SUFFIX), Path(str(base) + TXT_SUFFIX)
if not (srt.exists() and txt.exists()):
return False
src_m = source.stat().st_mtime
return srt.stat().st_mtime >= src_m and txt.stat().st_mtime >= src_m
def normalize(s: str) -> str:
return s.casefold().replace("ё", "е")
def stem(term: str) -> str:
"""Drop a likely inflectional ending so «загородный» also finds «загородном»."""
if len(term) >= 6:
return term[:-2]
if len(term) == 5:
return term[:-1]
return term
def search_lines(lines: list[str], query: str) -> list[int]:
"""Indexes of timestamped lines that contain every query term.
A phrase split across a segment boundary matches at the first of the two lines,
unless the next line alone already contains every term.
"""
terms = [stem(w) for w in normalize(query).split()]
rows = [i for i, l in enumerate(lines) if l.startswith("[")]
hits: list[int] = []
for k, i in enumerate(rows):
cur = normalize(lines[i])
nxt = normalize(lines[rows[k + 1]]) if k + 1 < len(rows) else ""
if all(t in cur for t in terms) or (
all(t in cur + " " + nxt for t in terms) and not all(t in nxt for t in terms)
):
hits.append(i)
return hits
# ---------- side-effecting commands ----------
def check(download: bool) -> int:
report: dict = {"ffmpeg": shutil.which("ffmpeg"), "ffprobe": shutil.which("ffprobe"),
"whisper_cli": whisper_cli(), "models_dir": str(models_dir())}
for key, (name, url) in MODELS.items():
path = models_dir() / name
if not path.exists() and download:
try:
fetch(url, path)
except Exception as e: # report instead of a traceback
report[f"{key}_download_error"] = str(e)
report[f"{key}_model"] = str(path) if path.exists() else None
missing = [k for k in ("ffmpeg", "ffprobe", "whisper_cli", "whisper_model", "vad_model") if report[k] is None]
report["status"] = "ok" if not missing else "missing"
report["missing"] = missing
print(json.dumps(report, ensure_ascii=False, indent=1))
return 0 if not missing else 2
def fetch(url: str, dest: Path) -> None:
dest.parent.mkdir(parents=True, exist_ok=True)
part = dest.with_name(dest.name + ".part")
print(f"downloading {url}", file=sys.stderr)
with urllib.request.urlopen(url, timeout=60) as r, open(part, "wb") as f:
expected = int(r.headers.get("Content-Length") or 0)
shutil.copyfileobj(r, f, length=1 << 20)
if expected and part.stat().st_size != expected:
part.unlink()
raise RuntimeError(f"incomplete download: {url}")
os.replace(part, dest)
def duration(path: Path) -> float:
try:
r = subprocess.run(
["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", str(path)],
capture_output=True, text=True, timeout=120,
)
return float(r.stdout.strip())
except (OSError, ValueError, subprocess.TimeoutExpired):
return 0.0
class WhisperError(RuntimeError):
"""A recognizer failure; the same message on consecutive files aborts the batch."""
def _last_line(text: str, fallback: str) -> str:
return (text.strip().splitlines() or [fallback])[-1]
def transcribe_one(source: Path, base: Path, lang: str, model: Path, vad: Path, cli: str, seconds: float) -> int:
"""Publish each output atomically; an incomplete pair stays stale for a rerun."""
source_state = source.stat()
timeout = max(MIN_TIMEOUT, 3 * seconds)
with tempfile.TemporaryDirectory(prefix="x9-transcripts-") as tmp:
wav = Path(tmp) / "audio.wav"
try:
r = subprocess.run(
["ffmpeg", "-v", "error", "-y", "-i", str(source), "-vn", "-ar", "16000", "-ac", "1",
"-c:a", "pcm_s16le", str(wav)],
capture_output=True, text=True, timeout=timeout,
)
except subprocess.TimeoutExpired:
raise RuntimeError(f"ffmpeg: no result after {timeout:.0f}s")
if r.returncode != 0 or not wav.exists():
raise RuntimeError("ffmpeg: " + _last_line(r.stderr, "no audio stream"))
cmd = [cli, "-m", str(model), "-l", lang, "--vad", "-vm", str(vad), "-f", str(wav),
"-osrt", "-of", str(Path(tmp) / "out")] # stdout/stderr are captured; stderr names the detected language
try:
r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
except subprocess.TimeoutExpired:
raise WhisperError(f"whisper-cli: no result after {timeout:.0f}s")
produced = Path(tmp) / "out.srt"
if r.returncode != 0 or not produced.exists():
raise WhisperError("whisper-cli: " + _last_line(r.stderr, "no output"))
detected = LANG_RE.search(r.stderr or "")
srt_text = produced.read_text(encoding="utf-8", errors="replace")
srt, txt = Path(str(base) + SRT_SUFFIX), Path(str(base) + TXT_SUFFIX)
staged: list[tuple[Path, Path]] = []
try:
for dest, content in ((srt, srt_text),
(txt, srt_to_txt(srt_text, source, detected.group(1) if detected else lang))):
# Keep the exclusive handle: reopening a predictable .part could follow a user-owned link.
# A bounded prefix also keeps valid long destination names publishable.
temporary = tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=dest.parent,
prefix=".x9-transcript-", suffix=".part", delete=False)
part = Path(temporary.name)
staged.append((part, dest))
with temporary:
temporary.write(content)
# Freshness is the completion marker. Make the new SRT stale before it can
# replace an old one; only promote it after TXT is published too. A failed
# second rename or interrupted process therefore cannot make a mixed pair current.
current_state = source.stat()
if any(getattr(current_state, field) != getattr(source_state, field)
for field in ("st_dev", "st_ino", "st_size", "st_mtime_ns")):
raise RuntimeError("source changed during transcription; retry after it stops changing")
source_mtime = source_state.st_mtime
srt_part = staged[0][0]
os.utime(srt_part, (source_mtime - 2, source_mtime - 2))
if srt_part.stat().st_mtime >= source_mtime:
raise RuntimeError("cannot mark incomplete transcript publication as stale")
for part, dest in staged:
os.replace(part, dest)
os.utime(srt, None, follow_symlinks=False)
finally:
for part, _dest in staged:
part.unlink(missing_ok=True)
return len(parse_srt(srt_text))
def run(paths: list[Path], out: Path | None, lang: str, force: bool, model: Path | None) -> int:
cli = whisper_cli()
model = model or models_dir() / MODELS["whisper"][0]
vad = models_dir() / MODELS["vad"][0]
problems = [n for n, ok in (("ffmpeg", shutil.which("ffmpeg")), ("ffprobe", shutil.which("ffprobe")),
("whisper-cli", cli),
(f"model {model}", model.exists()), (f"vad model {vad}", vad.exists())) if not ok]
if problems:
print(json.dumps({"status": "setup_required", "missing": problems}, ensure_ascii=False))
return 2
try:
items = discover(paths)
except FileNotFoundError as e:
print(json.dumps({"status": "failed", "error": f"not found: {e}"}, ensure_ascii=False))
return 2
if not items:
print(json.dumps({"status": "no_media", "error": "no audio or video files found"}, ensure_ascii=False))
return 2
source_paths = {output_key(source.resolve()): source for source, _root in items}
source_inodes: dict[tuple[int, int], Path] = {}
for source, _root in items:
source_stat = source.stat()
source_inodes[(source_stat.st_dev, source_stat.st_ino)] = source
planned: dict[str, Path] = {}
summary: dict = {"files": len(items), "done": 0, "skipped": 0, "failed": [], "collisions": [],
"no_speech": [], "audio_seconds": 0.0}
started = time.time()
last_whisper_error = None
for n, (source, root) in enumerate(items, 1):
previous_whisper_error, last_whisper_error = last_whisper_error, None
base = output_base(source, root, out)
label = f"[{n}/{len(items)}] {source}"
key = output_key(base)
destinations = [Path(str(base) + suffix + tail)
for suffix in (SRT_SUFFIX, TXT_SUFFIX) for tail in ("", ".part")]
overwritten_source = None
try:
for dest in destinations:
overwritten_source = source_paths.get(output_key(dest.resolve()))
if overwritten_source is None:
try:
dest_stat = dest.stat()
except FileNotFoundError:
continue
overwritten_source = source_inodes.get((dest_stat.st_dev, dest_stat.st_ino))
if overwritten_source is not None:
break
except (OSError, RuntimeError) as e:
summary["failed"].append({"file": str(source), "error": f"cannot check output safety: {e}"})
print(f"{label}: FAILED cannot check output safety", file=sys.stderr)
continue
if overwritten_source is not None:
summary["collisions"].append({"file": str(source), "same_output_as": str(overwritten_source),
"error": "output would overwrite an input source"})
print(f"{label}: output would overwrite source {overwritten_source}", file=sys.stderr)
continue
if key in planned:
summary["collisions"].append({"file": str(source), "same_output_as": str(planned[key])})
print(f"{label}: output name collides with {planned[key]}", file=sys.stderr)
continue
planned[key] = source
owner = owned_by_other(source, base)
if owner:
summary["collisions"].append({"file": str(source), "same_output_as": str(owner)})
print(f"{label}: existing transcript belongs to {owner}", file=sys.stderr)
continue
if not force and is_current(source, base):
summary["skipped"] += 1
print(f"{label}: up to date", file=sys.stderr)
continue
try:
base.parent.mkdir(parents=True, exist_ok=True)
except OSError as e:
summary["failed"].append({"file": str(source), "error": f"cannot create output folder: {e}"})
print(f"{label}: FAILED cannot create output folder", file=sys.stderr)
continue
if not os.access(base.parent, os.W_OK):
summary["failed"].append({"file": str(source), "error": f"output folder is not writable: {base.parent}"})
print(f"{label}: FAILED output folder is not writable", file=sys.stderr)
continue
secs = duration(source)
print(f"{label}: transcribing {hms(secs)} of audio", file=sys.stderr)
t0 = time.time()
try:
segments = transcribe_one(source, base, lang, model, vad, cli, secs) # type: ignore[arg-type]
except WhisperError as e:
summary["failed"].append({"file": str(source), "error": str(e)})
print(f"{label}: FAILED {e}", file=sys.stderr)
if str(e) == previous_whisper_error:
summary["status"] = "aborted"
summary["not_attempted"] = [str(s) for s, _r in items[n:]]
summary["error"] = "the same whisper-cli error repeated on consecutive files"
break
last_whisper_error = str(e)
continue
except Exception as e: # report and continue with the batch
summary["failed"].append({"file": str(source), "error": str(e)})
print(f"{label}: FAILED {e}", file=sys.stderr)
continue
last_whisper_error = None
summary["done"] += 1
summary["audio_seconds"] += secs
if segments == 0:
summary["no_speech"].append(str(source))
print(f"{label}: done ({hms(secs)} audio in {time.time() - t0:.0f}s, {segments} segments)", file=sys.stderr)
summary["elapsed_seconds"] = round(time.time() - started, 1)
summary["audio_seconds"] = round(summary["audio_seconds"], 1)
if "status" not in summary:
summary["status"] = "ok" if not (summary["failed"] or summary["collisions"]) else "partial"
print(json.dumps(summary, ensure_ascii=False, indent=1))
return 0 if summary["status"] == "ok" else 1
def search(query: str, paths: list[Path], limit: int) -> int:
files: list[Path] = []
for p in paths:
p = p.expanduser()
if not p.exists():
print(f"not found: {p}")
return 2
if p.is_dir():
files += sorted(p.rglob("*" + TXT_SUFFIX))
continue
txt = p if p.name.endswith(TXT_SUFFIX) else Path(str(output_base(p, p.parent, None)) + TXT_SUFFIX)
if not txt.exists():
print(f"no transcript for {p}; pass its {TXT_SUFFIX} file or the folder holding it")
return 2
files.append(txt)
if not files:
print("no transcripts found; run the run command first")
return 2
shown = 0
for f in files:
lines = f.read_text(encoding="utf-8", errors="replace").splitlines()
rec = recorded_source(f)
src = str(rec) if rec and rec.exists() else str(f) # a moved source is reported by its transcript
for i in search_lines(lines, query):
if shown >= limit:
print("... more matches; raise --max to see them")
return 0
print(f"{src}\t{lines[i]}")
shown += 1
if not shown:
print(f"no matches in {len(files)} transcripts")
return 0
def main(argv: list[str] | None = None) -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
sub = ap.add_subparsers(dest="cmd", required=True)
c = sub.add_parser("check")
c.add_argument("--download", action="store_true", help="download missing default models")
r = sub.add_parser("run")
r.add_argument("paths", nargs="+", type=Path)
r.add_argument("--out", type=Path, help="mirror outputs under this directory instead of next to sources")
r.add_argument("--lang", default="auto", help="spoken language code, e.g. ru; default auto-detect")
r.add_argument("--force", action="store_true", help="re-transcribe even when outputs are current")
r.add_argument("--model", type=Path, help="path to another ggml Whisper model")
s = sub.add_parser("search")
s.add_argument("query")
s.add_argument("paths", nargs="+", type=Path)
s.add_argument("--max", type=int, default=50)
a = ap.parse_args(argv)
if a.cmd == "check":
return check(a.download)
if a.cmd == "run":
return run(a.paths, a.out, a.lang, a.force, a.model)
return search(a.query, a.paths, a.max)
if __name__ == "__main__":
sys.exit(main())
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 |