course2md: turn YouTube, Bilibili and local lecture videos into slide-illustrated Markdown notes

The problem course2md solves, and who it is aimed at

Lecture recordings are bad study material. A two-hour video has slides you need to see and speech you need to read, and neither is searchable on its own. course2md takes a YouTube link, a Bilibili link or a local file and produces a directory of screenshots interleaved with transcript paragraphs, exported as course.md and course.html. The README describes the output as "screenshots are captured when the picture changes, the transcript is organized into paragraphs under each screenshot".

The audience is narrow but real: students working through recorded courses, and anyone who has to turn meeting recordings into a written record. The README frames it around a "course library" with folders, search, an outline reader and version history, which is a study workflow rather than a transcription service. If you only need a text transcript, the screenshot pipeline is overhead you are paying for.

How the screenshot and transcript pipeline fits together

The core mechanism is change detection on video frames. Cargo.toml lists the image-compare crate alongside image with jpeg and png features, which matches the README's claim that frames are captured when the picture changes rather than on a fixed interval. That is the right choice for slides: a fixed interval produces near-duplicate screenshots and bloats the notes folder.

Transcripts have two sources. Platform subtitles are preferred, and speech recognition runs when none exist. The flag --transcript-source subtitle|asr forces either side, which matters because platform subtitles are often wrong for technical terms while ASR on a clean recording can be better. Recognition is local by default: the README lists Apple Silicon CoreML, Intel NPU, llama.cpp GPU/CPU, and a cloud API, and states that "recognition data stays on your machine unless you choose the cloud backend".

Long conversions are resumable through speech checkpoints and --resume, and scripted use is served by NDJSON progress behind --json plus a quiet mode. The desktop app is a separate front end over the same engine; the README notes the GUI bundles its conversion engine, and the CLI and GUI share one configuration file.

Installing the course2md CLI and converting a first video

The CLI is the smaller commitment. On macOS or Linux the README gives a prebuilt binary installer that places course2md in ~/bin, overridable with COURSE2MD_BIN_DIR, and checks dependencies:

curl -fsSL https://raw.githubusercontent.com/mizorewww/course2md/main/install.sh | bash

Homebrew users can run `brew install mizorewww/tap/course2md` instead, and Arch users `yay -S course2md-bin`. From source it is `cargo install --path .` on Rust stable. The external dependencies are not optional: ffmpeg including ffprobe is always required, yt-dlp for online links, and llama-server for GPU or CPU recognition. The macOS Apple Silicon package is the exception because its CoreML backend needs no extra runtime.

Before converting anything, check the environment. The README presents doctor as the tool check:

course2md doctor

Expect it to report on tools, speech backends and settings. If ffmpeg or yt-dlp is missing, fix that first; the conversion will not get far without them.

Then convert a local file and choose where notes land:

course2md ./lecture.mp4 -o ./notes

Each note is created under the output root as platform/title/ID/ and contains course.md, course.html and the screenshots. The README notes that the first conversion in a terminal offers interactive setup and that scripts should pass options explicitly, so for anything automated add flags rather than relying on the prompt. JSON output is available through --formats, and the README also documents `course2md config init` and `course2md config show` for creating a template and locating the configuration file.

Where course2md breaks down

The most concrete limitation is platform coverage in the GUI. The README states that Intel Mac and Linux ARM64 do not yet have prebuilt GUIs, and directs those users to the CLI. It also warns that GitHub's Source code archives are developer sources, not app installers, which is a trap for anyone who downloads the first ZIP on a release page.

The GUI is also picky about graphics. The Arch package pulls in required graphics libraries and the README says your graphics hardware needs a working Vulkan driver, so a headless server or an old integrated GPU is the wrong host for the desktop app. On Windows the portable package must be extracted to a permanent folder with course2md.exe kept beside the desktop executable, because that file is the bundled engine; moving the exe alone breaks the app. The README adds that if the app was already open, you must quit and reopen it after installing ffmpeg and yt-dlp.

Local recognition has a first-use cost. Models are downloaded on first use, and GPU or CPU recognition needs llama-server running, with cloud recognition requiring your own API configuration. There is no documented offline path that avoids both a model download and an external runtime. Finally, the version line matters: the README points at 2.0.0-rc.4 while the default installation options provide the stable release, so two different behaviours are in circulation under one project name.

course2md versus a general transcription tool

A general transcription service takes audio and returns text with timestamps. course2md takes video and returns text plus the frames where the picture changed, laid out so each paragraph sits under the slide it came from. That is the actual difference in approach, and it decides the use case: for a podcast, the screenshot pass is wasted work, while for a slide-heavy lecture it is the reason to use the tool at all.

The second difference is where recognition runs. The README offers CoreML on Apple Silicon with no extra runtime, Intel NPU, llama.cpp on GPU or CPU, or a cloud API, and states that recognition data stays on your machine unless you pick the cloud backend. Services that only expose an upload endpoint give you no such choice. The trade is that you own the runtime: ffmpeg, yt-dlp and possibly llama-server, plus model downloads, are now your problem rather than a vendor's.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-09-15, the same day as the v2.0.0-rc.4 release. Releases are coming quickly: rc.2 and rc.3 both landed on 2026-09-10, and rc.4 followed on 2026-09-15. That pace is normal for a release candidate but it means the interface is still moving, and anything you script against the CLI should pin a version rather than track main.

Upgrade cost depends on how you installed it. A Homebrew cask or an Arch package is a package-manager upgrade; the curl installer writes into ~/bin and is re-run the same way; a cargo install from source means rebuilding. The GUI and CLI share one configuration file, so upgrading one without the other can leave a version mismatch between the front end and the engine, which is why the README insists the engine binary stay beside the desktop executable.

The project is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is the plain reading of the licence text; it is not legal advice, and if you redistribute a modified build you should read the LICENSE file in the repository rather than this summary.

Editorial conclusion

Adopt course2md if you already have ffmpeg and yt-dlp, want notes you can read in any editor, and are willing to run a release candidate: 2.0.0-rc.4 is the version the README points at. Skip it if you need a stable tagged release, if you are on an Intel Mac or Linux ARM64 where the README says there is no prebuilt GUI, or if you cannot run a local speech model and do not want the cloud backend. Before committing, run course2md doctor and check that it finds ffmpeg, ffprobe and your chosen speech backend, then convert one short local file with --transcript-source subtitle to see the output layout under platform/title/ID/ before you point it at a full course.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mizorewww/course2md on GitHub
4. README
5. Releases