Watchless
Turn one video into a complete visual article. The transcript is the factual source; screenshots preserve the visual evidence. The reader should not need to watch the original video.
Hard Requirements
- Run locally. Do not call PodSum, its website, MCP, Cloudflare, APIFY, D1, or R2.
- Keep the source immutable and reuse cached downloads and transcripts.
- Use Tencent Cloud word-level ASR with speaker diarization by default (
--provider tencent;autoalso selects Tencent). Never automatically fall back to Volcengine; select other providers explicitly. Do not silently replace it with YouTube automatic captions or local Whisper. - Keep the output chronological and complete. Light-plus is not a summary: preserve reasoning, examples, figures, caveats, disagreement, questions, answers, and repeated emphasis.
- Show process images during the run: whole-video route overview, boundary evidence where applicable, candidate frames, selected frames, and PDF page overview.
- Use no OpenCV anywhere in this Skill.
- Visual algorithms are route-specific.
slidesuses ffmpeg keyframe recall plus local SSIM refinement.explainer,conversation, anddemodo not use SSIM, perceptual hash, histogram scoring, face scoring, or other visual ranking; Codex directly reads their candidate images. - Resolve speaker identities for every
conversationvideo before writing notes. KeepSpeaker Nwhen evidence remains weak or conflicting. - Record model token usage and cost in
work/token-usage.jsonwhenever the runtime exposes real counts. Never invent unavailable usage or silently apply stale prices. - Do not claim completion until HTML image references, rendered PDF pages, and ZIP contents pass verification.
Private-Use Compliance Gate
Before acquiring a remote source, confirm that the user owns the content, has permission to process it, or has independently established another lawful basis. If authorization is unclear, stop and request an authorized local file instead of downloading.
- This repository and its outputs are private by default. Do not publish or distribute generated notes without a separate rights, privacy, confidentiality, and attribution review.
- Chrome browser cookies may be read only from the user's local browser profile. Never export, print, copy, upload, log, or commit cookie values. Cookie access does not establish a right to download or reuse content.
- Never use this Skill to bypass DRM, paywalls, members-only access, private-video access, geographic restrictions, CAPTCHAs, account enforcement, or other access controls.
- Before sending non-public or sensitive audio to the selected cloud ASR provider, confirm that the user is authorized to make that third-party transfer. Use explicitly requested local Whisper or stop when authorization is unavailable.
- Resolve speaker names only from explicit public metadata, self-introduction, lower thirds, or similarly reliable evidence. Do not perform face or voice biometric identification. Keep
Speaker Nwhen uncertain and require human review before external use. - Use the minimum screenshots and quotations needed for any approved external use. Do not publish a complete transcript or visual reconstruction that substitutes for the source without a separate legal review.
Read LEGAL.en.md before running this Skill on third-party, confidential, commercial, or sensitive material. These controls reduce risk but do not constitute legal advice.
Route Model
Choose one content route after directly inspecting verify/mode-overview.jpg and the transcript. Then add visual strategies. Do not route from the title or channel alone.
| Route | Observable pattern | Segmentation | Frame extraction |
|---|---|---|---|
slides | Stable PPT, slide deck, document pages, or a fixed presentation region | Every meaningful slide/build state | Hybrid H.264 keyframe recall, local SSIM refinement, accurate scan fallback |
explainer | Scripted visual argument: presenter, charts, animation, maps, documents, B-roll | Complete argument/example/visual function | Dense time-distributed candidates inside each semantic scene; Codex selects |
conversation | Interview, panel, podcast, or question-and-answer exchange | Complete Q&A or topic unit, not every speaker turn | Active speaker/two-shot candidates; evidence or B-roll can override faces |
demo | UI walkthrough, product demonstration, tutorial, or physical procedure | Executable step and observable result | Candidates biased toward before/after and completed states; Codex selects |
Visual strategies are composable:
slide-state: stable, complete slide/build state.speaker: active speaker or useful group shot.evidence: chart, quote, interface, object, or source that carries the claim.broll: relevant external footage in an edited interview or documentary.dense-visual: increase candidate density for XiaoLin-style edited explainers.document-evidence: prefer papers, article excerpts, tables, and diagrams.screen-state: prefer a legible UI result rather than cursor motion or transitions.
For conversation, also choose one extraction profile without creating a new main route:
| Profile | Use when | Candidate behavior |
|---|---|---|
studio | Stable studio/remote podcast with little visual evidence | Three representative speaker/group candidates per semantic scene |
edited | Interview with B-roll, locations, documents, or archival footage | Nine distributed candidates plus local evidence-trigger candidates |
news | Broadcast interview with lower thirds, tickers, charts, and product graphics | Eight distributed candidates plus local evidence-trigger candidates |
chaptered | Long interview whose official chapters are useful topic hints | Five candidates; chapters seed review but never force a boundary through an answer |
general | Evidence is insufficient to choose a more specific profile | Backward-compatible five-candidate behavior |
Typical routing examples:
- XiaoLin-style scripted finance/technology video:
explainer + dense-visual + evidence. - Best Partners paper/article explanation:
explainer + document-evidence. - a16z or YC Lightcone studio podcast:
conversation + speaker. - Silicon Valley 101 edited field interview:
conversation + evidence + broll. - YC Design Review screen walkthrough:
demo + screen-state + evidence. - Low-information entertainment chat:
conversation + speaker, with fewer, larger topic units.
Workflow
Set SKILL_DIR to this Skill directory. Run commands from the workspace where outputs/video-notes/ should be created.
1. Acquire, transcribe, and inspect the whole video
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" "$SOURCE" --stage prepare
Read PROJECT_DIR from output. Display verify/mode-overview.jpg, inspect the transcript and source metadata, and decide the route from observable structure.
2. Confirm route and visual strategies
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage route --project-dir "$PROJECT_DIR" \ --mode explainer \ --visual-strategy dense-visual \ --visual-strategy evidence \ --mode-reason "scripted host alternates with explanatory charts and B-roll"
Later stages may use --mode auto; they read the confirmed work/route-decision.json. An explicit --mode remains a manual override. Compatibility aliases: presentation -> slides, editorial -> explainer.
For a Bloomberg-style news interview:
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage route --project-dir "$PROJECT_DIR" \ --mode conversation --conversation-profile news \ --visual-strategy speaker --visual-strategy evidence \ --mode-reason "broadcast interview with lower thirds and sparse data graphics"
3A. Slides route
Slides do not use semantic timeline boundaries. If the slide occupies only part of the frame, directly inspect the overview and pass a relative crop rectangle.
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage scenes --project-dir "$PROJECT_DIR" --mode auto \ --slide-rect "0.04,0.08,0.72,0.92"
The default backend is hybrid-keyframe: scan H.264 keyframes at low resolution, compare the fixed slide region with SSIM, locally refine clustered changes on a 2-second grid, and fall back to accurate full scanning when keyframe recall is unavailable. Use --slide-backend accurate, --slide-interval, or --slide-threshold only when the default misses or over-splits states.
Display verify/selected-keyframes.jpg. Confirm that frames are complete slides, not black frames, fades, or partial transitions.
3B. Explainer, conversation, and demo routes
Prepare an audio-first semantic review:
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage timeline --project-dir "$PROJECT_DIR" --mode auto
Read work/video-use/takes_packed.md and work/timeline/boundary-review.md. Propose boundaries only at complete phrases and semantic transitions. For each real decision point T, inspect approximately T-4s to T+4s with video-use/helpers/timeline_view.py; do not scan the full video at fixed intervals.
When official chapters exist, the timeline stage writes work/timeline/chapter-hints.json. Treat chapters only as coarse topic proposals: merge or split them to preserve complete questions, answers, examples, and qualifications.
Write work/timeline/scene-boundaries.json:
json{"mode":"explainer","scenes":[{"end_sec":42.35,"reason":"hook and first claim complete"},{"end_sec":113.8,"reason":"chart explanation completes"}]}
The final boundary must cover the final transcript phrase. Then build scenes:
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage scenes --project-dir "$PROJECT_DIR" --mode auto \ --boundaries "$PROJECT_DIR/work/timeline/scene-boundaries.json"
Display candidate contact sheets and verify/selected-keyframes.jpg. Select frames by direct inspection. For explainers, prefer visual evidence over a face; for conversations, prefer the active speaker unless evidence/B-roll adds information; for demos, prefer the completed UI or physical result.
For edited and news conversations, the scene builder also looks for spoken references such as charts, data, reports, papers, products, chips, and screens. It adds nearby candidates labeled evidence to the contact sheet. These are recall hints, not automatic visual scores; Codex must still inspect and choose the frame.
4. Confirm selected frames
If default candidates are suitable:
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage select --project-dir "$PROJECT_DIR"
Otherwise write selections such as {"1":2,"7":5} and pass --selections. Do not proceed until keyframe_review.status=complete.
5. Conversation speaker identity pass
For conversation, complete work/speaker-map.json before batches. Use evidence in this order:
- YouTube metadata and official description: title, credits, chapters, linked show notes.
- Self-introductions and reliable subtitles.
- Lower thirds, on-screen names, camera handoffs, and visible turn agreement.
- Official episode pages.
- Earlier episodes from the same channel for recurring-host corroboration.
Record display_name, role, confidence, and evidence. high requires explicit naming plus turn agreement; medium is a documented inference; low remains Speaker N. Use timestamped turn_overrides when ASR merges people or changes labels for one person. Set status=complete only after checking handoffs throughout the video.
6. Write complete scene notes
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage batches --project-dir "$PROJECT_DIR"
Inspect every referenced image and transcript. Write each requested work/codex-notes/scene_NNN.md. Preserve the original order and voice; do not turn dialogue into third-person editorial narration. Visual descriptions must remain factual and useful.
If the runtime reports actual model usage, append it after each model-heavy phase. Pass current explicit rates only when cost should be calculated:
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage usage --project-dir "$PROJECT_DIR" \ --usage-stage notes --model-name "$MODEL" \ --input-tokens "$INPUT_TOKENS" --output-tokens "$OUTPUT_TOKENS" \ --cached-input-tokens "$CACHED_INPUT_TOKENS" \ --input-rate-per-million "$INPUT_RATE" \ --cached-input-rate-per-million "$CACHED_RATE" \ --output-rate-per-million "$OUTPUT_RATE"
7. Build and verify outputs
bash"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \ --stage finalize --project-dir "$PROJECT_DIR"
Finalize automatically writes verify/quality-audit.json and verify/quality-audit.md. Display verify/pdf-pages-contact-sheet.jpg, read the audit, and resolve warnings about transcript coverage, note/frame counts, speaker identity, duplicate exact frames, or missing usage records. Report Markdown, HTML, PDF, ZIP, scene count, image count, page count, recorded tokens, and known cost. Unknown usage remains unknown.
Fallbacks
After the compliance gate is satisfied, try anonymous yt-dlp, then local Chrome browser cookies without exporting them. Do not use the cookie fallback to defeat access controls. Volcengine credentials may be discovered from the environment, scripts/config.py, or WATCHLESS_VOLCENGINE_CONFIG; never print or copy credential values. Use source/manual subtitles only with --use-source-subtitles. Use local Whisper only when explicitly requested with --provider whisper. If acquisition still fails, report the classified error and request an authorized local video.
Stages are idempotent and resumable. --target-seconds is an explicit legacy fallback for non-slide modes, never the normal segmentation method.
Tencent ASR / 腾讯云通道
See references/tencent-asr.md for credentials, engine selection, resumable jobs and cross-chunk speaker-label limitations.
