whisper-video-transcribe-workaround
- Repo stars 0
- Author updated Live
- Author repo skills-registry
- Domain
- Data
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools，默认拥有全部工具权限。
---
name: whisper-video-transcribe-workaround
description: When Whisper (CLI or Python) gets stuck on video files during transcription — output dir stays e…
category: data
runtime: Python
---
# whisper-video-transcribe-workaround output preview
## PART A: Task fit
- Use case: When Whisper (CLI or Python) gets stuck on video files during transcription — output dir stays empty, process runs at low CPU/memory with no progress — the workaround is to extract audio first with ffmpeg, then transcribe the WAV. Use this when Whisper hangs or times out on a video file. Use when this capability is needed..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Problem / Solution: Extract audio first, then transcribe / Step 1 — Extract audio with ffmpeg” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “When Whisper (CLI or Python) gets stuck on video files during transcription — output dir stays empty, process runs at low CPU/memory with no progress — the workaround is to extract audio first with ffmpeg, then transcribe the WAV. Use this when Whisper hangs or times out on a video file. Use when this capability is needed.”.
- **02** When the source has headings, the agent prioritizes “Problem / Solution: Extract audio first, then transcribe / Step 1 — Extract audio with ffmpeg” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options.The source mentions slash commands such as `/tmp`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “Problem / Solution: Extract audio first, then transcribe / Step 1 — Extract audio with ffmpeg”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: whisper-video-transcribe-workaround
description: When Whisper (CLI or Python) gets stuck on video files during transcription — output dir stays e…
category: data
source: tomevault-io/skills-registry
---
# whisper-video-transcribe-workaround
## When to use
- When Whisper (CLI or Python) gets stuck on video files during transcription — output dir stays empty, process runs at…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Problem / Solution: Extract audio first, then transcribe / Step 1 — Extract audio with ffmpeg” and keep inference separate from source facts.
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies.The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "whisper-video-transcribe-workaround" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Problem / Solution: Extract audio first, then transcribe / Step 1 — Extract audio with ffmpeg
rules -> SKILL.md triggers / order / output contract
runtime -> Python | read files, write/modify files | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
}Whisper Video Transcription Workaround
Problem
When running whisper video.mp4 directly, the process may:
- Appear to run (PID exists, CPU may be active)
- But output dir stays empty even after many minutes
- Eventually time out or get stuck at ~33-43% "downloading/decoding"
This happens because the Whisper CLI tries to decode the video container internally, and certain video streams (especially DASH/m3u8 segmented video from YouTube downloads) cause the decoder to stall.
Solution: Extract audio first, then transcribe
Step 1 — Extract audio with ffmpeg
ffmpeg -i "video.mp4" -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/audio.wav -yFlags explained:
-vn— no video stream-acodec pcm_s16le— 16-bit PCM audio (Whisper prefers)-ar 16000— 16kHz sample rate (Whisper's native rate)-ac 1— mono (better for speech recognition)-y— overwrite without asking
Step 2 — Transcribe the WAV with faster-whisper
from faster_whisper import WhisperModel
model = WhisperModel("tiny", device="cpu", compute_type="int8")
segments, info = model.transcribe(
"/tmp/audio.wav",
language="zh",
vad_filter=True,
vad_parameters=dict(min_silence_duration_ms=800)
)
results = [{"start": round(s.start, 2), "end": round(s.end, 2), "text": s.text.strip()} for s in segments]Model size guide for Chinese:
tiny— fastest, ~3x realtime on CPU; acceptable accuracymedium— better accuracy but slowerlarge-v3-turbo— best accuracy; much heavier
Step 3 — Save transcript to file
Always write to a JSON file rather than holding in memory:
import json
with open("/tmp/transcript.json", "w", encoding="utf-8") as f:
json.dump({"segments": results, "language": info.language}, f, ensure_ascii=False, indent=2)Verification checklist
- Audio WAV was created (
ls -lh /tmp/audio.wav) - faster-whisper started logging segment output
- JSON file written with non-empty segments array
- Transcript language matches expected language
- Total duration of last segment ≈ video duration
Why this works
ffmpeg's audio decoding is battle-tested and handles problematic streams gracefully. Whisper's audio decoder (even faster-whisper) can get confused by AV1 video streams in MP4 containers downloaded via yt-dlp (DASH format). Extracting to clean PCM WAV sidesteps the issue entirely.
Known limitations
- The tiny model makes more transcription errors than medium/large — review before publishing
- Very long audio (>1hr) may still be slow on CPU; consider splitting with
ffmpeg -ss 0 -t 3600 -i audio.wav part1.wav
Source: davidtoby/agent-skills — distributed by TomeVault.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review