HotClip — local AI clipping pipeline

HotClip（AGPL-3.0 开源）把几小时的直播回放/播客/课程切成可直接发布的竖屏短视频,全程本地运行。You drive the same pipeline the desktop app uses, via a headless CLI (or the bundled MCP server). Everything — ASR, highlight detection, cutting, caption burn-in — runs on this machine; the footage is never uploaded.

Setup (once)

1. Repo + deps (skip what already exists):

   git clone https://github.com/xixihhhh/hotclip.git && cd hotclip
   pnpm install   # ffmpeg/ffprobe are bundled npm binaries — nothing else to install
   

2. LLM config for highlight detection, via env vars (any OpenAI-compatible endpoint):

   export HOTCLIP_LLM_BASE_URL=http://localhost:11434/v1   # local Ollama (no key needed)
   export HOTCLIP_LLM_MODEL=qwen3:8b
   # cloud endpoints additionally need: export HOTCLIP_LLM_API_KEY=sk-...
   

   If these are missing, ask the user which LLM endpoint to use — do not guess keys.
3. First transcribe/clip run auto-downloads the ASR model (~1GB, CN mirror first). Warn the user it may take a few minutes once.

Commands (run from the repo root)

pnpm cli transcribe <video>                    # on-device word-level ASR (cached; instant on re-run)
pnpm cli highlights <video> [--max-clips N] [--reference REF] [--json]   # AI highlight candidates — review before cutting
pnpm cli clip <video> [--max-clips N] [--reference REF] [--no-vertical] [--no-captions] [--out DIR] [--json]
                                               # fully managed: transcribe → detect → export + render-QA

--reference <video>: hand in a viral clip to model after — its pacing (duration / speech rate / shot-cut frequency / hook shape) is measured locally and steers candidate selection as a preference (never a hard rule). Use when the user says "切得像这条" / "learn from this clip".

Input: MP4 / MKV / MOV / FLV / TS, or audio-only (podcasts get an auto-generated waveform video). Paths with spaces need quoting.

Recommended workflow

1. Review-first (default for interactive sessions): run highlights --json, show the user the candidates (title / score / hook / recommended), let them pick, then run clip — the pipeline re-detects from cache so this is cheap. For "just do it" requests, run clip directly.
2. Read the output receipt: the export folder contains one mp4 + cover JPG + .post.txt (publish copy) per clip, plus clips.json — per-clip evidence chain (render: what the pipeline did) and qa: render-QA report (status: pass|warn with issues like black frames, long silences, loudness deviation, duration mismatch, mid-word cuts, and platform-risk words in title/copy/captions via a local rule lint — qa.contentHits lists each term and where it appeared).
3. Self-repair is automatic: fixable warnings (leading/trailing silence or black frames → edge-trim; loudness deviation → second normalize pass) are repaired and re-checked in one pass; qa.repair records what was done (actions, applied). A repair is only kept when the re-check strictly improves.
4. Surface QA warnings: if any clip still has qa.status === "warn", tell the user which clip and why; content-lint hits mean the copy/captions may be throttled or rejected by 抖音/小红书/视频号 — suggest rewording before publishing. Never silently ship a warned clip.

Hard rules

• Never guess timestamps. Cut points come from word-aligned transcription (highlights output); do not invent start/end seconds or hand-roll ffmpeg cuts when the pipeline covers it.
• Local-first: do not upload the footage or transcript to any service beyond the user-configured LLM endpoint (which only ever receives transcript text, never media).
• Exports land next to the source video in <name>-hotclip/ unless --out is given; tell the user the absolute path when done.

MCP alternative

The same pipeline is exposed as a local stdio MCP server (pnpm mcp, tools: clip_video / detect_highlights / transcribe_video) — prefer it when the host supports MCP registration; the CLI is equivalent otherwise.