Most issues withDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/HUANGCHIHHUNGLeo/claude-real-video/llms.txt
Use this file to discover all available pages before exploring further.
claude-real-video trace back to one of three root causes: ffmpeg not being on your PATH, a missing or outdated yt-dlp installation, or the optional Whisper package not being present. The accordions below walk through each common symptom, its cause, and the exact fix.
"ffmpeg not found" or "ffprobe not found"
"ffmpeg not found" or "ffprobe not found"
Symptom:
Then verify it is on your On Windows, if you downloaded a build manually, you must add the
RuntimeError: ffmpeg not found is raised, or the tool runs without error but extraction produces 0 frames.Cause: ffmpeg (and its companion ffprobe) are not pip-installable — they must be installed at the system level and available on your PATH. claude-real-video relies on both for frame extraction and audio handling.Fix: Install ffmpeg for your operating system:| OS | Command |
|---|---|
| macOS | brew install ffmpeg |
| Linux | sudo apt install ffmpeg (or your distro’s package manager) |
| Windows | winget install Gyan.FFmpeg — or download a build from gyan.dev |
PATH:bin\ folder inside the extracted archive to your system PATH before the above command will work."Download failed (private video? try --cookies your_cookies.txt)"
"Download failed (private video? try --cookies your_cookies.txt)"
"yt-dlp not found"
"yt-dlp not found"
Symptom: Or reinstall the whole package to pull in all dependencies:
RuntimeError: yt-dlp not found. Install it: pip install yt-dlpCause: yt-dlp is listed as a Python dependency of claude-real-video, but in some virtual environments it may not end up on PATH (for example if it was installed into a different environment, or if the environment’s bin/Scripts directory is not activated).Fix: Install or upgrade yt-dlp directly:"No transcript — whisper not installed"
"No transcript — whisper not installed"
Symptom: Cause: The Whisper CLI is not installed. Transcription via Whisper is an optional extra — the core Or install Note that Whisper itself also requires
MANIFEST.txt contains the line:claude-real-video package does not install it automatically.Fix: Install the [whisper] extra:openai-whisper directly:ffmpeg to be on your PATH (see the first accordion above)."0 frames extracted"
"0 frames extracted"
Symptom: The CLI reports If
0 frames (deduped from 0 extracted) and the frames/ directory is empty.Causes:ffmpegis not onPATH— extraction silently produces no output.- The video file has no video stream (audio-only file).
- The clip is extremely short and falls below the density floor / scene threshold.
ffmpeg is available:ffmpeg is present but you are processing a very short or low-motion clip, lower the detection thresholds so more frames are captured:--scene 0.1 makes scene-change detection more sensitive; --fps-floor 0.5 guarantees at least one frame every half-second even with no scene changes."Too many frames (hitting --max-frames cap)"
"Too many frames (hitting --max-frames cap)"
Symptom: The reported frame count equals exactly the Use
--max-frames value (default 150), and some of the saved frames look redundant or very similar to each other.Cause: After scene-change detection and deduplication, the number of candidate frames still exceeds the hard cap. The cap then thins the survivors uniformly, which can let near-duplicates through if the dedup threshold was too permissive.Fix: Raise --dedup-threshold to be more aggressive about dropping similar frames (e.g. 15 instead of the default 8), or raise --scene to reduce the number of scene-change candidates in the first place:--report to generate report.html and visually inspect which frames were kept, dropped, or removed by the cap — this makes tuning much easier:"Output directory is overwritten each run"
"Output directory is overwritten each run"
Symptom: After running Alternatively, use
crv a second time, the output from the previous run is gone.Cause: This is by design — each run overwrites the output directory (crv-out by default). The README notes: “Re-running overwrites the output directory.”Fix: Use -o to specify a unique output directory per run:--kb to automatically save a dated markdown note of the analysis to a persistent folder (such as an Obsidian vault) so your findings survive the next run:"Whisper produces wrong language"
"Whisper produces wrong language"
Symptom: The Replace
transcript.txt file contains text in an unexpected language, or Whisper picks the wrong language for a multilingual video.Cause: When --lang is not set, Whisper uses automatic language detection, which samples only the first 30 seconds. If those seconds are ambiguous or contain music, detection can fail.Fix: Pass the expected language code explicitly:en with the appropriate ISO 639-1 code for your language (e.g. zh for Chinese, fr for French, ja for Japanese).If your issue is not covered here, please open a ticket on the GitHub Issues page. Include the exact error message, your OS, Python version, and the command you ran.