DOCS

指令全表

Reel Scout — Command & Integration Reference

Concise reference for the CLI, MCP tools, LLM/VLM backends, and config flags. For the design rationale see roadmap.md; for the signal model see ../prompts/signal-reliability-cheatsheet.md.

CLI

Command	What it does
`browse <profile_url>`	List a channel/profile’s videos (metadata only). `--json` / `--urls-only`.
`crawl <url…>`	Download videos. `--channel <url> --limit N`, `--playlist <url>`, `--file -` (stdin).
`analyze <url\|path…>`	Full pipeline: download/register → transcribe → keyframes+VLM → shot/audio metrics (§4E) → on-screen text (§4F) → merge → optional score. Accepts a local file path (platform-outage insurance). `--score`.
`transcribe <path>` / `vision <path>`	Individual stages against a local file.
`list` / `show <id>`	List analyzed videos / show one analysis.
`export --format json\|csv\|html\|bundle\|skeleton\|storyboard`	Export analyses. `html` = one self-contained file; `bundle` = one self-contained file per reel + an index (the course take-home).
`view`	Local web server for the library: a table with star / group / note per row. The analysis stays read-only; only your own annotations and analysis requests write back.
`note <ref>`	Annotate a clip. `--text`, `--group <name>` (`--new-group`), `--no-group`, `--star` / `--unstar`, `--json`.
`group {list,add,rename,rm}`	Manage the annotation groups (also doable from the list page toolbar). `rm` clears the filing and keeps every note and star.
`pending [--run] [--all] [--no-score]`	Analysis requests queued from the viewer (“queue analysis” on a Threads carousel’s other videos). Lists them; `--run` analyzes each as `<post url>?media=N` and marks it done only if the DB shows that row `analyzed`. See threads.md.
`inspect <id>`	Interactive single-clip viewer (transcript↔keyframe time-sync).
`score <id>`	Craft score (hook / visual / pacing (evidence-based, §4E) / structure).
`ingest {vision,analysis,score} <id> --from-json <path\|->`	Write agent-produced frame descriptions / structured analysis / craft scores back into the DB, for machines with no local model. `--model` required; stored as `agent:<model>`. Analysis enums are validated.
`compare <id…>`	Side-by-side comparison table.
`stats [--channel] [--csv]`	Corpus tag distributions + score aggregates.
`coverage [--channel] [--limit N] [--json]`	Per-clip transcript + keyframe coverage with the max gap (longest stretch with no subtitle segment / no sampled frame, head and tail included), worst first.
`patterns --channel <c>`	Per-channel patterns: length, hook/CTA/structure mix, high-vs-low contrast, cadence.
`inspire --based-on <ref> [--angle] [--name-retries N] [--zh-convert s2twp\|s2tw\|off] [--zh-hotwords FILE]`	Generate a fresh variant (titles/hook/structure/length) from a high scorer. Real names in the analysis are checked against the answer; a miss is re-asked up to N times (default 2). Without `--angle` the check is `strict` (a dropped real name or an invented one fails); with `--angle` it is `angle` mode (only an invented name fails; dropped source names are listed under `name_check.dropped`). `name_check.mode` says which ran; `name_check.status` is `passed` or `failed`; failed exits 3 with a stderr warning.
`track --my-video <ref> --views --likes [--comments --notes]`	Record real performance + structural iteration hints vs the top corpus.
`research --niche <n> --channels <url…> [--depth --out --no-analyze]`	Competitor research report.
`batch --stdin` / `--file <path>` / `--doc <url>`	Analyze every reel in a list, one bundle each. `--dry-run`, `--limit`, `--out`, `--mode`. Prefer `--stdin`/`--file` for someone’s own list — it stays on their machine. `--doc` rewrites Google `/edit` links to no-auth export endpoints, which needs sharing set to “anyone with the link”, i.e. it makes that document public to anyone holding the URL.
`skill {install,path}`	Copy the agent-facing assets (SKILL.md, `/scout`, prompt pack, setup preflight) to `~/.claude/skills/reel-scout`. `--dest`, `--force`. `pip install` alone does not give an agent anything to load.
`mcp install` / `mcp path`	Register the MCP server with Claude Desktop / Claude Code so they can launch it, pinning an absolute `REEL_SCOUT_DATA`. `--client`, `--data`, `--path`, `--force`, `--dry-run`. `mcp path` diagnoses what is configured versus what this directory resolves to.
`db {stats,reset,migrate,normalize-paths,backfill-text,health,backfill-shots,check-invalid,check-llm-residue}` / `config {show,check}`	DB / config utilities. `check-invalid` lists videos whose media never really processed (0 keyframes alongside a non-empty transcript) and would otherwise average into `stats` as a genuine 0.0; it reports by default and marks `status=invalid` only with `--apply`. It never deletes. `check-llm-residue` lists rows written before v1.5’s merge/scorer fix: analyses stored from an unparseable merge reply, scores with a NULL column, and scores with all four dimensions exactly 0.0 (a suspect, not proof). It opens the database read-only and has no `--apply`.

Refs (<ref>, <id>) accept a full 16-hex video id or a unique prefix; track --my-video also accepts a URL already in the DB.

MCP tools (`reel-scout-mcp`, stdio)

19 tools: analyze, annotate, batch_cancel, batch_start, batch_status, crawl, export, ingest_analysis, ingest_score, ingest_vision, inspect, inspire, keyframes, list_annotations, list_videos, mark, patterns, research, show_video. LLM/network tools (analyze, inspire, research) route stdout to stderr so they don’t corrupt the JSON-RPC stream. research reads the existing DB by default; pass analyze: true to crawl+analyze first (slow).

Backends

VLM (VLM_BACKEND): omlx (default) / ollama. Model via VLM_MODEL (default qwen2.5vl:7b), fallback VLM_FALLBACK_MODEL.
LLM (merger/scorer/inspire/research, LLM_BACKEND): omlx / ollama / openclaw (proxy to a subscription, no local GPU).
Whisper (WHISPER_BACKEND): auto (default: mlx when it can run here, else faster-whisper) / faster-whisper / whisper.cpp / mlx (mlx-whisper on Metal, Apple Silicon, mlx extra; WHISPER_MODEL large-v3 / large-v3-turbo or an HF repo id; no beam search, falls back to faster-whisper with a notice when unavailable); subtitle-first when a native subtitle is present (uploaded track in the spoken language > its auto -orig ASR > Whisper; among Chinese tracks zh-Hant > zh-TW > zh-HK > zh > Simplified). WHISPER_MULTILINGUAL=1 for code-switching interviews.

All inference defaults to localhost — no cloud API keys required.

`batch` picks nothing for you

batch probes the configured backends before it runs. A reachable VLM means --mode full is unambiguous and it just goes. Without one it stops and makes you choose, because the alternative — quietly producing transcript-only bundles — drops the craft score without anyone noticing:

full        local VLM does the visual layer and the score
agent       skip the VLM; an agent reads the keyframes and writes its own
            findings back via `ingest` (see below and SKILL.md Step 2b)
transcript  transcript and structure only, stated plainly

In agent mode the run ends by listing the videos still missing a visual layer, with the exact ingest command for each.

No local model at all

Keyframe extraction is ffmpeg, not a model, so the frames exist on disk before the VLM stage runs. An agent that can see images can supply the visual layer and the craft score itself, and ingest writes that back so it shows up in show / view / inspect / export like any other analysis:

reel-scout analyze "<url>" --skip-vision        # download + transcript + structure
# agent reads data/keyframes/<id>/*.jpg, then:
reel-scout ingest vision   <id> --from-json - --model <name>
reel-scout ingest analysis <id> --from-json - --model <name>   # merge needs an LLM too
reel-scout ingest score    <id> --from-json - --model <name>

This is the only path that needs no oMLX/ollama/API key. The thing to know:

Rows are stamped agent:<model>, because craft scores are model-dependent (the same clip: 7.43 under qwen3-vl:8b, 5.5 under qwen2.5vl:7b).
stats therefore groups score aggregates by model_used. A corpus mixing agent-scored and locally-scored videos gets one block per source, and the pooled block is labelled as pooled (mixed_score_sources: true in --json, flag,score_source,mixed,1 in --csv) so it is not read as a single scale. Per-video reads are unaffected either way.

Transcription still wants a local Whisper; set WHISPER_MODEL=small to keep the download modest, or rely on subtitle-first when the source has native subtitles.

Notable config flags

Flag	Default	Effect
`REEL_SCOUT_DATA`	`./data`	Data dir (DB, videos, keyframes).
`KEYFRAME_STRATEGY` / `KEYFRAME_MAX` / `KEYFRAME_RESOLUTION`	`scene` / `8` / `0`	Keyframe extraction.
`KEYFRAME_SHOT_CAP`	`30`	Short clips (≤ `KEYFRAME_LONG_SEC`) with more cuts than `KEYFRAME_MAX` get one frame per shot up to this many; `0` keeps the flat cap. `scene`/`hybrid` only.
`SHOT_METRICS_ENABLED` / `SHOT_SCENE_THRESHOLD`	`true` / `0.3`	§4E measured pacing (cuts/min + energy/BPM).
`PACING_SLOW_BELOW_CPM` / `PACING_FAST_FROM_CPM`	`8` / `25`	Cuts/min bands that set `style.pacing` for measured clips.
`MICRO_SHOT_SEC` / `MICRO_RUN_MIN`	`0.2` / `3`	Flash runs (strobe / stop-motion): counted once in `segment_count` and in keyframe-cap growth.
`OCR_ENABLED` / `OCR_ENGINE`	`true` / `vlm`	§4F on-screen text; `tesseract` opt-in (needs the `ocr` extra).
`IG_COOKIES_FILE`	—	Instagram cookies for gated content.
`LLM_BACKEND` / `VLM_BACKEND` / `WHISPER_BACKEND`	`omlx`/`omlx`/`auto`	Inference backends.
`REEL_SCOUT_ZH_CONVERT` / `REEL_SCOUT_ZH_HOTWORDS`	`s2twp` / —	Source Simplified→Traditional conversion (`s2twp`/`s2tw`/`off`, needs the `zh` extra) for inspire’s analysis copy and for Simplified transcripts / subtitles as they are saved (original kept in `transcripts.text_full_original`), plus a YAML/JSON hotword table applied after OpenCC.
`INSPIRE_NAME_RETRIES`	`2`	inspire re-asks on a real-name miss at most this many times (0 = check only).

reel-scout config show prints the resolved config; config check probes backend reachability.

Optional extras (`pip install reel-scout[<extra>]`)

whisper, audio (onnxruntime+numpy — PANNs events + BPM), diarize, instagram (instaloader browse fallback), ocr (pytesseract+Pillow), vector, zh (OpenCC — Simplified→Traditional at the source: inspire’s analysis copy, and Simplified transcripts / subtitles on save, original kept).

Take-home bundle

reel-scout export --format bundle -o ./course-reels \
  --cjk-font /path/to/NotoSansTC.ttf   # optional: embeds Chinese glyphs

Each reel becomes ONE html file with the video, keyframes, waveform peaks, fonts and a per-file CJK subset inlined — no server, no sibling files, nothing to lose when it is moved or emailed. Sized for short-form: reels land around 2–25 MB, and anything over --max-mb (default 25) is skipped with a reason rather than producing a file nobody can open. Without --cjk-font, Chinese falls back to the reader’s system face; Latin always uses the bundled brand faces.