course2md README

The project's README from github.com/mizorewww/course2md. As one markdown file: README.md.

course2md

Turn YouTube, Bilibili, or local videos into illustrated Markdown / HTML notes. Add a video in the desktop app, generate notes, then organize and read them in your course library.

English · 中文 · GitHub Wiki

Try 2.0 RC2: 2.0.0-rc.2 release notes and installation. Use the course2md-gui@rc Homebrew cask; the default installation options below provide the stable release.

Features

Install the desktop app (GUI)

Choose one installation method for your system below. The GUI includes its conversion engine; no separate CLI install is needed.

macOS: Apple Silicon, macOS 15 or later

If you have Homebrew: run this in Terminal to install the app and the video tools ffmpeg and yt-dlp:

brew install --cask mizorewww/tap/course2md-gui

After installation, open course2md from Finder → Applications.

Manual installation: download the macOS installer (DMG), open it, and drag course2md.app to Applications. This installs only the app; install video tools separately using the macOS installation guide.

Arch Linux / CachyOS: x86_64

If you have yay, run this to install the desktop app, video tools and required graphics libraries:

yay -S course2md-gui-bin

With paru, run paru -S course2md-gui-bin. Open course2md from your applications menu. Your graphics hardware needs a working Vulkan driver; see the Linux installation guide.

Windows: x64

  1. Download the Windows portable package (ZIP) and extract everything to a permanent folder.

  2. Install video tools in PowerShell:

    winget install --id Gyan.FFmpeg -e
winget install --id yt-dlp.yt-dlp -e

  3. Open course2md-desktop.exe from the extracted folder. Keep course2md.exe beside it: this is the bundled engine. If the app was already open, quit and reopen it after installing tools.

Ubuntu / other Linux distributions: x86_64

Download the Linux desktop package (tar.gz), install video tools and graphics libraries using the Linux installation guide, then extract everything. Enter the extracted folder and run ./course2md-desktop. Keep the course2md engine in the same folder.

The prebuilt package is based on Ubuntu 24.04. Intel Mac and Linux ARM64 do not yet have prebuilt GUIs; use the CLI version. GitHub's Source code archives are developer sources, not app installers.

First use

  1. Open course2md and follow the setup guide to choose a notes folder and speech recognition method.
  2. Check Settings → Runtime environment. ffmpeg (including ffprobe) processes video; yt-dlp handles online videos.
  3. Add a video URL or local file and start conversion. Open the finished notes in your library.

Local recognition downloads models on first use. GPU / CPU recognition also needs llama-server; cloud recognition requires your own API configuration. The app provides setup controls; see the first-launch guide for details.

Install the CLI

The CLI and the desktop app share one configuration file and can be installed side by side.

macOS / Linux (prebuilt binary):

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

This installs course2md into ~/bin (override with COURSE2MD_BIN_DIR) and checks dependencies. Also available: Homebrew brew install mizorewww/tap/course2md; Arch Linux yay -S course2md-bin (x86_64, aarch64); or from source with cargo install --path . (Rust stable).

ffmpeg (including ffprobe) is always required, yt-dlp for online links, and llama-server for GPU/CPU recognition — except on the macOS Apple-Silicon package, whose CoreML backend needs no extra runtime. Run course2md doctor to check everything.

Quick start

course2md ./lecture.mp4                        # local file
course2md https://www.youtube.com/watch?v=…    # or a Bilibili link
course2md ./lecture.mp4 -o ./notes             # choose the output root

The first conversion in a terminal offers interactive setup; scripts should pass options explicitly. Each note is created under the output root as platform/title/ID/, containing course.md, course.html and the screenshots.

Common commands

Command Purpose
course2md <URL or file> Convert a video into notes
course2md --login bilibili / --logout bilibili Scan a QR code to log in to Bilibili / remove the saved login
course2md doctor Check tools, speech backends and settings
course2md config init / config show Create a configuration template / show the config path and settings
course2md models list / models prepare Check downloaded models / pre-download a model
course2md llm setup / llm status / llm disable Configure, inspect or turn off AI proofreading
course2md summarize ./notes Add AI summaries to existing notes
course2md run-task Execute a saved task from stdin JSON (used by the GUI engine)

Use <command> --help for each command's options.

Configuration

The configuration file is ~/.config/course2md/config.toml (%APPDATA%\course2md\config.toml on Windows; XDG_CONFIG_HOME is respected). Precedence: command-line arguments > config.toml > built-in defaults. course2md config init writes a template to get started. AI proofreading is optional and off by default: course2md llm setup saves the endpoint, key and model, and course2md remove clears saved AI service settings.

Frequently asked questions

Conversion fails with a missing ffmpeg. Install ffmpeg (it includes ffprobe) and yt-dlp for online links — for example brew install ffmpeg yt-dlp on macOS — then run course2md doctor to confirm.

A Bilibili video fails or comes back in low quality. Run course2md --login bilibili and scan the QR code; --logout bilibili removes the saved login.

How large are the model downloads? The first local recognition downloads the model automatically: about 1–2.3 GB for macOS CoreML models (cached in ~/Library/Caches/qwen3-speech/) and about 2.4 GB for the llama.cpp GGUF (cached in ~/.cache/course2md/models/). Pre-download with course2md models prepare, or inspect the cache with course2md models inspect.

Documentation and help

All documentation (GitHub Wiki) · CLI installation and usage · Upgrade and uninstall · Troubleshooting · Report a problem

For developers: desktop build guide · development discipline · architecture · benchmarks · packaging and releases · Changelog · MIT license

course2md (mizorewww/course2md)

Searching Database…

427 ·GitHub
Course2md
What is this?course2md turns YouTube, Bilibili, or local course and meeting video recordings into slide-illustrated Markdown and HTML lecture notes, capturing a screenshot whenever the slide changes and placing the transcript underneath it.
Is this a desktop app or a command-line tool?Both. There is a desktop GUI app with its own bundled conversion engine, and a separate CLI; they share one configuration file and can be installed side by side.
How do I get it running?On Apple Silicon Mac, install the Homebrew cask or download the DMG; on Windows, download the portable ZIP and run course2md-desktop.exe; on Arch Linux use yay/paru, or on other Linux use the tar.gz package. The CLI can also be installed via a prebuilt binary script, Homebrew, yay, or 'cargo install --path .'.
Do I need ffmpeg and yt-dlp installed separately?Yes — ffmpeg (including ffprobe) is always required, yt-dlp is needed for online video links, and llama-server is needed for GPU/CPU speech recognition, except on the macOS Apple Silicon package whose CoreML backend needs no extra runtime.
Does it run on Intel Macs or Linux ARM64?Not yet with a prebuilt GUI — those platforms need to use the CLI version instead until a GUI build is available.
Where does my video/audio data go during speech recognition?Local speech recognition (CoreML, Intel NPU, or llama.cpp backends) keeps all data on your machine; nothing leaves your device unless you explicitly configure the cloud API backend.
How does the slide-style note format work?course2md captures a screenshot whenever the video's visual content changes and organizes the transcript into paragraphs under each screenshot, exporting everything as course.md and course.html (optionally JSON with --formats).
Can it log in to Bilibili to fix failed or low-quality downloads?Yes, 'course2md --login bilibili' opens a QR code to scan for login, and '--logout bilibili' removes the saved session; this is the fix for Bilibili videos that fail or come back in low quality.
Is AI proofreading or summarization built in?Optional AI proofreading and summaries work through any OpenAI-compatible endpoint, configured via 'course2md llm setup'; the feature is off by default, so no API key is needed unless you enable it.
What happens if a conversion gets interrupted?Conversions are resumable through speech checkpoints and the --resume flag, and the CLI also supports NDJSON progress output and quiet mode for scripting.
What are similar projects?stemkit, omarchy-meeting-recorder, pickoo-your-favorites, parrot, better-voice, phorminx, pyvideotrans, autoclip
Which topics is it in?linux-app, transcription, speech-to-text, youtube, speech-recognition, note-taking, video-processing, ffmpeg, macos-app, homebrew, windows-app, apple-silicon
Creator
mizorewww
Size
41.7 MB
Stars
427
Updated
CommitOct 15Releasev1.7.0Sep 06
Age
1mo
Commits · 90 Days