whisper-video-transcribe-workaround

Data Community

Repo stars 0
Author repo skills-registry

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: When Whisper (CLI or Python) gets stuck on video files during transcription — output dir stays empty, process runs at low CPU/me…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Problem”, “Solution: Extract audio first, then transcribe”, “Step 1 — Extract audio with ffmpeg”, “Step 2 — Transcribe the WAV with faster-whisper”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name whisper-video-transcribe-workaround directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Problem / Solution: Extract audio first, then transcribe / Step 1 — Extract audio with ffmpeg” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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 -y

Flags 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 accuracy
medium — better accuracy but slower
large-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.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Data
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @tomevault-io · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Python
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview whisper-video-transcribe-workaround.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# 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

```bash
ffmpeg -i "video.mp4" -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/audio.wav -y
```

Flags 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

```python
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 accuracy
- `medium` — better accuracy but slower
- `large-v3-turbo` — best accuracy; much heavier

### Step 3 — Save transcript to file

Always write to a JSON file rather than holding in memory:

```python
import json
with open("/tmp/transcript.json", "w", encoding="utf-8") as f:

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Problem → Solution: Extract audio first, then transcribe → Step 1 — Extract audio with ffmpeg → Step 2 — Transcribe the WAV with faster-whisper → Step 3 — Save transcript to file → Verification checklist
terms    -> ffmpeg's audio decoding is battle-tested and handles problematic streams gracefully. · --- > Source: [davidtoby/agent-skills](https://github.com/davidtoby/agent-skills) — distributed by [TomeVault](https://tomevault.io).
files/cmd -> whisper video.mp4 · -vn · -acodec pcms16le · -ar 16000 · -ac 1 · tiny · medium · large-v3-turbo
body sha256 -> 4ffcb6cc94a8