Troubleshooting

Troubleshooting

Wiki · GUI · CLI · 中文

Troubleshooting

Desktop app

Open Settings → Runtime environment to check video tools and your recognition method. Install missing tools using the app's help, then restart the app. You do not need to install the CLI for this. Open task details to read conversion errors.

• Missing ffmpeg / yt-dlp: the Homebrew Cask and AUR GUI package install these tools. For manual downloads, follow the GUI installation guide.
• Conversion engine not found: extract the entire Windows/Linux archive and keep the bundled engine beside the desktop app. Do not mix versions.
• Linux window will not open: check the Vulkan driver and the launch error; confirm your distribution meets the prebuilt package's requirements.
• Model download failed: check the network and available storage, or configure a cloud API in recognition settings.

CLI

Run the environment check:

course2md doctor

It reports ffmpeg / ffprobe / yt-dlp / llama-server / uv availability, platform backends (CoreML / NPU), config-file validity (including permission warnings), and the local model cache state.

Reporting a problem

Include your system, app version and steps to reproduce. GUI users can attach the task error and the output directory's run.json. CLI users can also attach:

1. The full output of course2md doctor
2. The run.json file from the output directory (records provider, model, transcript source, and stats — no credentials)
3. The command line you used (redact URLs if needed)

Common fixes:

Symptom	Fix
Download fails on restricted networks	export HF_ENDPOINT=https://hf-mirror.com (honored by both GGUF and CoreML downloads; download errors print this hint too)
Transcripts look mixed/inconsistent after switching models	Pre-1.0 checkpoints are discarded automatically; rerun with --no-resume to force a clean pass
--no-download deleted my video	Fixed in 1.0 — files not downloaded by the current run are never removed
English course transcribed as Chinese on NPU	Fixed in 1.0 — language is auto-detected; force nothing
Prefer platform subtitles over local ASR	Default behavior in 1.0 (--transcript-source auto); force with --transcript-source subtitle