| name | hotclip |
| description | Turn long videos & livestream VODs into viral vertical shorts, 100% locally — on-device transcription, LLM highlight detection, 9:16 reframe with karaoke captions, and a per-clip render-QA report. Use when the user asks to clip / cut / 切片 / 剪 a long video, podcast or stream replay into short clips, find highlights / 爆点 in a video, or transcribe a media file. Footage never leaves the machine. |
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)
- Repo + deps (skip what already exists):
git clone https://github.com/xixihhhh/hotclip.git && cd hotclip
pnpm install
- LLM config for highlight detection, via env vars (any OpenAI-compatible endpoint):
export HOTCLIP_LLM_BASE_URL=http://localhost:11434/v1
export HOTCLIP_LLM_MODEL=qwen3:8b
If these are missing, ask the user which LLM endpoint to use — do not guess keys.
- 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>
pnpm cli highlights <video> [--max-clips N] [--reference REF] [--json]
pnpm cli clip <video> [--max-clips N] [--reference REF] [--no-vertical] [--no-captions] [--out DIR] [--json]
--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
- 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.
- 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).
- 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.
- 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.
