Skip to content
Back to search

watchless

SkillWorks with Claude CodeGitHub

Use when turning a YouTube URL or local presentation, explainer, interview, podcast, or product-demo video into complete screenshot-led notes, faithful light-polished text, HTML, PDF, or a shareable ZIP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chenzixin1--watchless/badge.svg)](/listings/chenzixin1--watchless)

HTML

<a href="/listings/chenzixin1--watchless"><img src="/api/listings/chenzixin1--watchless/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/chenzixin1/watchless.git
cd watchless

python3 -m venv .venv
.venv/bin/pip install -r scripts/requirements.txt
.venv/bin/pip install -r scripts/requirements-dev.txt

系统依赖:

- `ffmpeg` 和 `ffprobe` - `yt-dlp` - Google Chrome,用于 HTML 转 PDF - 本机可访问的 `video-use` Skill,用于转录打包和局部时间线检查

本地 Whisper 只作为显式回退,不会静默替换腾讯云 ASR:

.venv/bin/pip install -r scripts/requirements-whisper.txt

安装为 Codex Skill:

mkdir -p "$HOME/.codex/skills"
ln -sfn "$(pwd)" "$HOME/.codex/skills/watchless"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: watchless
  3. description: Use when turning a YouTube URL or local presentation, explainer, interview, podcast, or product-demo video into complete screenshot-led notes, faithful light-polished text, HTML, PDF, or a shareable ZIP.
  4. ---
  5. # Watchless
  6. > [English](SKILL.md) | [简体中文](SKILL.zh-CN.md)
  7. 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.
  8. ## Hard Requirements
  9. - Run locally. Do not call PodSum, its website, MCP, Cloudflare, APIFY, D1, or R2.
  10. - Keep the source immutable and reuse cached downloads and transcripts.
  11. - Use Tencent Cloud word-level ASR with speaker diarization by default (`--provider tencent`; `auto` also selects Tencent). Never automatically fall back to Volcengine; select other providers explicitly. Do not silently replace it with YouTube automatic captions or local Whisper.
  12. - Keep the output chronological and complete. Light-plus is not a summary: preserve reasoning, examples, figures, caveats, disagreement, questions, answers, and repeated emphasis.
  13. - Show process images during the run: whole-video route overview, boundary evidence where applicable, candidate frames, selected frames, and PDF page overview.
  14. - Use no OpenCV anywhere in this Skill.
  15. - Visual algorithms are route-specific. `slides` uses ffmpeg keyframe recall plus local SSIM refinement. `explainer`, `conversation`, and `demo` do not use SSIM, perceptual hash, histogram scoring, face scoring, or other visual ranking; Codex directly reads their candidate images.
  16. - Resolve speaker identities for every `conversation` video before writing notes. Keep `Speaker N` when evidence remains weak or conflicting.
  17. - Record model token usage and cost in `work/token-usage.json` whenever the runtime exposes real counts. Never invent unavailable usage or silently apply stale prices.
  18. - Do not claim completion until HTML image references, rendered PDF pages, and ZIP contents pass verification.
  19. ## Private-Use Compliance Gate
  20. 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.
  21. - 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.
  22. - 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.
  23. - Never use this Skill to bypass DRM, paywalls, members-only access, private-video access, geographic restrictions, CAPTCHAs, account enforcement, or other access controls.
  24. - 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.
  25. - 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 N` when uncertain and require human review before external use.
  26. - 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.
  27. 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.
  28. ## Route Model
  29. 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.
  30. | Route | Observable pattern | Segmentation | Frame extraction |
  31. | --- | --- | --- | --- |
  32. | `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 |
  33. | `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 |
  34. | `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 |
  35. | `demo` | UI walkthrough, product demonstration, tutorial, or physical procedure | Executable step and observable result | Candidates biased toward before/after and completed states; Codex selects |
  36. Visual strategies are composable:
  37. - `slide-state`: stable, complete slide/build state.
  38. - `speaker`: active speaker or useful group shot.
  39. - `evidence`: chart, quote, interface, object, or source that carries the claim.
  40. - `broll`: relevant external footage in an edited interview or documentary.
  41. - `dense-visual`: increase candidate density for XiaoLin-style edited explainers.
  42. - `document-evidence`: prefer papers, article excerpts, tables, and diagrams.
  43. - `screen-state`: prefer a legible UI result rather than cursor motion or transitions.
  44. For `conversation`, also choose one extraction profile without creating a new main route:
  45. | Profile | Use when | Candidate behavior |
  46. | --- | --- | --- |
  47. | `studio` | Stable studio/remote podcast with little visual evidence | Three representative speaker/group candidates per semantic scene |
  48. | `edited` | Interview with B-roll, locations, documents, or archival footage | Nine distributed candidates plus local evidence-trigger candidates |
  49. | `news` | Broadcast interview with lower thirds, tickers, charts, and product graphics | Eight distributed candidates plus local evidence-trigger candidates |
  50. | `chaptered` | Long interview whose official chapters are useful topic hints | Five candidates; chapters seed review but never force a boundary through an answer |
  51. | `general` | Evidence is insufficient to choose a more specific profile | Backward-compatible five-candidate behavior |
  52. Typical routing examples:
  53. - XiaoLin-style scripted finance/technology video: `explainer + dense-visual + evidence`.
  54. - Best Partners paper/article explanation: `explainer + document-evidence`.
  55. - a16z or YC Lightcone studio podcast: `conversation + speaker`.
  56. - Silicon Valley 101 edited field interview: `conversation + evidence + broll`.
  57. - YC Design Review screen walkthrough: `demo + screen-state + evidence`.
  58. - Low-information entertainment chat: `conversation + speaker`, with fewer, larger topic units.
  59. ## Workflow
  60. Set `SKILL_DIR` to this Skill directory. Run commands from the workspace where `outputs/video-notes/` should be created.
  61. ### 1. Acquire, transcribe, and inspect the whole video
  62. ```bash
  63. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" "$SOURCE" --stage prepare
  64. ```
  65. Read `PROJECT_DIR` from output. Display `verify/mode-overview.jpg`, inspect the transcript and source metadata, and decide the route from observable structure.
  66. ### 2. Confirm route and visual strategies
  67. ```bash
  68. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  69. --stage route --project-dir "$PROJECT_DIR" \
  70. --mode explainer \
  71. --visual-strategy dense-visual \
  72. --visual-strategy evidence \
  73. --mode-reason "scripted host alternates with explanatory charts and B-roll"
  74. ```
  75. 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`.
  76. For a Bloomberg-style news interview:
  77. ```bash
  78. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  79. --stage route --project-dir "$PROJECT_DIR" \
  80. --mode conversation --conversation-profile news \
  81. --visual-strategy speaker --visual-strategy evidence \
  82. --mode-reason "broadcast interview with lower thirds and sparse data graphics"
  83. ```
  84. ### 3A. Slides route
  85. 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.
  86. ```bash
  87. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  88. --stage scenes --project-dir "$PROJECT_DIR" --mode auto \
  89. --slide-rect "0.04,0.08,0.72,0.92"
  90. ```
  91. 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.
  92. Display `verify/selected-keyframes.jpg`. Confirm that frames are complete slides, not black frames, fades, or partial transitions.
  93. ### 3B. Explainer, conversation, and demo routes
  94. Prepare an audio-first semantic review:
  95. ```bash
  96. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  97. --stage timeline --project-dir "$PROJECT_DIR" --mode auto
  98. ```
  99. 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.
  100. 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.
  101. Write `work/timeline/scene-boundaries.json`:
  102. ```json
  103. {"mode":"explainer","scenes":[{"end_sec":42.35,"reason":"hook and first claim complete"},{"end_sec":113.8,"reason":"chart explanation completes"}]}
  104. ```
  105. The final boundary must cover the final transcript phrase. Then build scenes:
  106. ```bash
  107. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  108. --stage scenes --project-dir "$PROJECT_DIR" --mode auto \
  109. --boundaries "$PROJECT_DIR/work/timeline/scene-boundaries.json"
  110. ```
  111. 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.
  112. 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.
  113. ### 4. Confirm selected frames
  114. If default candidates are suitable:
  115. ```bash
  116. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  117. --stage select --project-dir "$PROJECT_DIR"
  118. ```
  119. Otherwise write selections such as `{"1":2,"7":5}` and pass `--selections`. Do not proceed until `keyframe_review.status=complete`.
  120. ### 5. Conversation speaker identity pass
  121. For `conversation`, complete `work/speaker-map.json` before batches. Use evidence in this order:
  122. 1. YouTube metadata and official description: title, credits, chapters, linked show notes.
  123. 2. Self-introductions and reliable subtitles.
  124. 3. Lower thirds, on-screen names, camera handoffs, and visible turn agreement.
  125. 4. Official episode pages.
  126. 5. Earlier episodes from the same channel for recurring-host corroboration.
  127. 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.
  128. ### 6. Write complete scene notes
  129. ```bash
  130. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  131. --stage batches --project-dir "$PROJECT_DIR"
  132. ```
  133. 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.
  134. If the runtime reports actual model usage, append it after each model-heavy phase. Pass current explicit rates only when cost should be calculated:
  135. ```bash
  136. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  137. --stage usage --project-dir "$PROJECT_DIR" \
  138. --usage-stage notes --model-name "$MODEL" \
  139. --input-tokens "$INPUT_TOKENS" --output-tokens "$OUTPUT_TOKENS" \
  140. --cached-input-tokens "$CACHED_INPUT_TOKENS" \
  141. --input-rate-per-million "$INPUT_RATE" \
  142. --cached-input-rate-per-million "$CACHED_RATE" \
  143. --output-rate-per-million "$OUTPUT_RATE"
  144. ```
  145. ### 7. Build and verify outputs
  146. ```bash
  147. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/00_build_video_notes.py" \
  148. --stage finalize --project-dir "$PROJECT_DIR"
  149. ```
  150. 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.
  151. ## Fallbacks
  152. 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.
  153. Stages are idempotent and resumable. `--target-seconds` is an explicit legacy fallback for non-slide modes, never the normal segmentation method.
  154. ## Tencent ASR / 腾讯云通道
  155. See [references/tencent-asr.md](references/tencent-asr.md) for credentials, engine selection, resumable jobs and cross-chunk speaker-label limitations.
README.md · README · 321 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Watchless
  2. > [简体中文](README.md) | [English](README.en.md)
  3. > **Watch less. Understand more.**
  4. ![Watchless:从在线视频到完整可读文档](assets/watchless-hero.png)
  5. 一个在 Codex 本地运行的完整视频理解 Skill:把 YouTube 链接或本地视频,转换成带关键帧、完整文字解说、HTML、PDF 和分享 ZIP 的可读文档。
  6. 项目目标不是生成一段摘要,而是让读者通过“关键图 + 对应文字”的顺序,完整理解原视频的论点、例子、数字、问答和视觉证据。
  7. > **私人内部使用。** 本仓库保留本机 Chrome Cookie 回退,但 Cookie 不会赋予下载、复制或传播权。只处理自己拥有或已经获得授权的内容,输出默认保持私人。详见 [LEGAL.md](LEGAL.md)。
  8. ## 实际效果
  9. 下面四个页面均来自 Watchless 的真实输出。不同内容采用不同的语义切分和关键帧策略,但最终都形成“关键图 + 完整文字”的连续阅读体验。
  10. <table>
  11. <tr>
  12. <td width="50%" valign="top">
  13. <strong>论文与文档解读</strong><br>
  14. <code>explainer + document-evidence</code><br><br>
  15. <img src="assets/examples/explainer.jpg" alt="论文讲解视频图文解读示例"><br>
  16. 围绕完整论点切分,优先保留论文原图、流程图、引文和关键定义。<br>
  17. <a href="https://www.youtube.com/watch?v=z_F0z7wF5XU">查看原视频</a>
  18. </td>
  19. <td width="50%" valign="top">
  20. <strong>棚内多人对谈</strong><br>
  21. <code>conversation + studio + speaker</code><br><br>
  22. <img src="assets/examples/conversation.jpg" alt="多人播客图文解读示例"><br>
  23. 以完整问题和回答为边界,识别说话人,并控制重复人物画面的密度。<br>
  24. <a href="https://www.youtube.com/watch?v=Zyw-YA0k3xo">查看原视频</a>
  25. </td>
  26. </tr>
  27. <tr>
  28. <td width="50%" valign="top">
  29. <strong>新闻访谈与数据证据</strong><br>
  30. <code>conversation + news + speaker + evidence</code><br><br>
  31. <img src="assets/examples/news-interview.jpg" alt="新闻访谈图文解读示例"><br>
  32. 结合采访问答、姓名条、产品图和数据画面,保留可复核的视觉证据。<br>
  33. <a href="https://www.youtube.com/watch?v=HTmE6ZKZ9sU">查看原视频</a>
  34. </td>
  35. <td width="50%" valign="top">
  36. <strong>产品与 UI 演示</strong><br>
  37. <code>demo + screen-state + evidence</code><br><br>
  38. <img src="assets/examples/demo.jpg" alt="产品演示图文解读示例"><br>
  39. 按操作步骤和结果状态切分,优先保留清晰、可理解的完成界面。<br>
  40. <a href="https://www.youtube.com/watch?v=VbqaL_eHhKY">查看原视频</a>
  41. </td>
  42. </tr>
  43. </table>
  44. 案例只展示低分辨率单页节选并链接原视频,不包含可替代原作品的完整输出;第三方画面和名称的权利归各自权利人所有。
  45. ## 项目做什么
  46. Watchless 将一条视频处理成一套可复核、可分享的内容资产:
  47. ![Watchless 项目流程图](assets/watchless-workflow.svg)
  48. 1. 下载视频、字幕和 YouTube 元数据。
  49. 2. 使用腾讯云词级 ASR 和说话人分离生成带时间戳的转录稿。
  50. 3. 查看全片概览,判断视频的内容组织方式。
  51. 4. 按语义边界切分,而不是机械地每 60 或 90 秒切一段。
  52. 5. 从每个语义场景生成候选帧,由 Codex 直接读取图片并选择关键帧。
  53. 6. 对多人视频建立说话人映射,保留可信度和证据。
  54. 7. 生成忠实的 Light-plus 文本和逐场景视觉解说。
  55. 8. 输出 HTML、PDF、ZIP,并运行字幕、图片引用、PDF 和压缩包审计。
  56. ## 内容路径
  57. 项目不把视频简单归为“PPT、科普、播客”三类,而是根据内容如何推进来选择路径:
  58. | 路径 | 适合内容 | 切分单位 | 关键画面 |
  59. | --- | --- | --- | --- |
  60. | `slides` | PPT、课程课件、固定演示区 | 幻灯片或完整构建状态 | 稳定的完整页面 |
  61. | `explainer` | 小 Lin 式科普、论文解读、纪录式解释 | 完整论点、例子或视觉功能 | 图表、文档、动画、地图、B-roll |
  62. | `conversation` | 访谈、播客、圆桌、问答 | 完整问题、回答或主题单元 | 当前说话人、双人镜头、资料画面 |
  63. | `demo` | UI 教程、产品演示、操作流程 | 操作步骤和可观察结果 | 操作前后、完成后的界面状态 |
  64. `conversation` 还会选择一个候选帧子类型:
  65. - `studio`:棚内或远程对谈,视觉变化少,减少重复人物截图。
  66. - `edited`:穿插外景、文档、历史资料或 B-roll,提高证据画面召回。
  67. - `news`:新闻采访,关注姓名条、Ticker、数据图和产品图。
  68. - `chaptered`:长访谈,使用官方章节作为主题提示,但不让章节截断完整回答。
  69. - `general`:证据不足时的兼容行为。
  70. 详细的样本矩阵和模式研究见 [docs/video-pattern-research.zh-CN.md](docs/video-pattern-research.zh-CN.md)。
  71. ## 视觉策略
  72. 视觉策略可以叠加在主路径上:
  73. | 策略 | 作用 |
  74. | --- | --- |
  75. | `slide-state` | 选择稳定、完整的幻灯片或构建状态 |
  76. | `speaker` | 保留当前主讲人或有用的多人镜头 |
  77. | `evidence` | 优先图表、引文、界面、物体和资料 |
  78. | `broll` | 保留编辑型采访中的外景和历史材料 |
  79. | `dense-visual` | 为高视觉密度科普增加候选帧 |
  80. | `document-evidence` | 优先论文、文章摘录、表格和流程图 |
  81. | `screen-state` | 优先清晰的界面结果,而不是鼠标移动或转场 |
  82. 只有 `slides` 路径使用视觉比较:先用 ffmpeg 关键帧召回,再对固定 PPT 区域做局部 SSIM 精修。`explainer`、`conversation` 和 `demo` 不使用 OpenCV、SSIM、感知哈希、直方图、人脸评分或美学评分,而是由 Codex 直接读取候选图片。
  83. ## 安装
  84. ```bash
  85. git clone https://github.com/chenzixin1/watchless.git
  86. cd watchless
  87. python3 -m venv .venv
  88. .venv/bin/pip install -r scripts/requirements.txt
  89. .venv/bin/pip install -r scripts/requirements-dev.txt
  90. ```
  91. 系统依赖:
  92. - `ffmpeg` 和 `ffprobe`
  93. - `yt-dlp`
  94. - Google Chrome,用于 HTML 转 PDF
  95. - 本机可访问的 `video-use` Skill,用于转录打包和局部时间线检查
  96. 本地 Whisper 只作为显式回退,不会静默替换腾讯云 ASR:
  97. ```bash
  98. .venv/bin/pip install -r scripts/requirements-whisper.txt
  99. ```
  100. 安装为 Codex Skill:
  101. ```bash
  102. mkdir -p "$HOME/.codex/skills"
  103. ln -sfn "$(pwd)" "$HOME/.codex/skills/watchless"
  104. ```
  105. ## 配置和安全
  106. 腾讯云词级 ASR 是默认转录路径,默认启用说话人分离。`--provider tencent` 和 `--provider auto` 均使用腾讯云,失败不会自动切换服务商。
  107. 配置环境变量 `TENCENTCLOUD_SECRET_ID` / `TENCENTCLOUD_SECRET_KEY`,或将 `secret_id` / `secret_key` 写入仓库外的 `~/.config/watchless/tencent.json`(文件权限 `0600`)。不要在命令行或 Git 中写入真实密钥。
  108. 支持词级时间戳、长音频分段直传和任务续跑。说话人分离是文字中的匿名标签,不输出独立人声音轨;跨分段标签需要人工核验。完整说明见 [腾讯云通道](references/tencent-asr.md)。
  109. 火山通道保留,仅在显式 `--provider volcengine` 时使用。火山配置可以来自:
  110. - 环境变量 `VOLCENGINE_API_KEY`
  111. - 本地未纳入 Git 的 `scripts/config.py`
  112. - `WATCHLESS_VOLCENGINE_CONFIG` 指向的配置文件
  113. 不要把真实 Key、浏览器 Cookie、下载视频、转录原文或生成产物提交到 Git。项目已经忽略 `outputs/`、虚拟环境、日志和本地缓存;`scripts/config.example.py` 只保留占位符。
  114. ### 私人使用与法律边界
  115. - Chrome Cookie 只允许程序从本机浏览器配置临时读取,不得导出、打印、上传或提交。
  116. - 不得使用本项目绕过 DRM、付费墙、会员限制、私人访问、地区限制、验证码或其他访问控制。
  117. - 默认腾讯云 ASR 会把音频发送给第三方服务;保密或敏感内容必须先确认授权,必要时显式改用本地 Whisper。
  118. - 说话人名称必须有可靠公开证据,无法确认时保留 `说话人N`,不得进行人脸或声纹生物识别。
  119. - 公开发布或商业使用前必须另行核对平台条款、版权、隐私、保密和署名要求。
  120. 免责声明不能把未经授权的使用变成合法。完整风险说明、私人使用规则和官方参考见 [LEGAL.md](LEGAL.md)。
  121. 整个流程在 Codex 本地运行,不依赖 PodSum 网站、MCP、Cloudflare、APIFY、D1 或 R2。
  122. ## 使用流程
  123. ### 1. 下载、转录和全片概览
  124. ```bash
  125. .venv/bin/python scripts/00_build_video_notes.py \
  126. "https://www.youtube.com/watch?v=VIDEO_ID" \
  127. --stage prepare
  128. ```
  129. 命令会打印 `PROJECT_DIR`,并生成:
  130. - `verify/mode-overview.jpg`:全片模式概览。
  131. - `work/transcript/`:带时间戳的转录稿。
  132. - `work/video-use/`:供语义时间线使用的转录材料。
  133. - `work/acquisition.json`:来源、视频、字幕和元数据索引。
  134. 先直接查看概览图和转录稿,再确定路径;不能只根据标题或频道名称判断。
  135. ### 2. 确认路径
  136. 例如,新闻访谈:
  137. ```bash
  138. .venv/bin/python scripts/00_build_video_notes.py \
  139. --stage route \
  140. --project-dir "$PROJECT_DIR" \
  141. --mode conversation \
  142. --conversation-profile news \
  143. --visual-strategy speaker \
  144. --visual-strategy evidence \
  145. --mode-reason "现场新闻采访,包含姓名条和少量数据图"
  146. ```
  147. 常用路由示例:
  148. | 视频样式 | 推荐参数 |
  149. | --- | --- |
  150. | 小 Lin 式科技/财经科普 | `explainer + dense-visual + evidence` |
  151. | 论文或文章讲解 | `explainer + document-evidence` |
  152. | a16z、YC Lightcone 棚内播客 | `conversation + studio + speaker` |
  153. | 硅谷 101 等编辑型采访 | `conversation + edited + evidence + broll` |
  154. | Bloomberg 式新闻采访 | `conversation + news + speaker + evidence` |
  155. | YC Design Review | `demo + screen-state + evidence` |
  156. ### 3. 生成场景和候选帧
  157. PPT 使用混合关键帧路径:
  158. ```bash
  159. .venv/bin/python scripts/00_build_video_notes.py \
  160. --stage scenes \
  161. --project-dir "$PROJECT_DIR" \
  162. --mode auto \
  163. --slide-rect "0.04,0.08,0.72,0.92"
  164. ```
  165. 科普、对谈和演示先生成语义时间线:
  166. ```bash
  167. .venv/bin/python scripts/00_build_video_notes.py \
  168. --stage timeline \
  169. --project-dir "$PROJECT_DIR" \
  170. --mode auto
  171. ```
  172. Codex 读取 `work/video-use/takes_packed.md` 和 `work/timeline/boundary-review.md`,只在语义转折点附近检查 `T-4s` 到 `T+4s`,然后写入 `work/timeline/scene-boundaries.json`:
  173. ```bash
  174. .venv/bin/python scripts/00_build_video_notes.py \
  175. --stage scenes \
  176. --project-dir "$PROJECT_DIR" \
  177. --mode auto \
  178. --boundaries "$PROJECT_DIR/work/timeline/scene-boundaries.json"
  179. ```
  180. 运行过程中应展示全片概览、边界证据、候选接触表和最终关键帧接触表。
  181. ### 4. 选择关键帧、生成解说和打包
  182. ```bash
  183. .venv/bin/python scripts/00_build_video_notes.py --stage select --project-dir "$PROJECT_DIR"
  184. .venv/bin/python scripts/00_build_video_notes.py --stage batches --project-dir "$PROJECT_DIR"
  185. # Codex 逐场景写入 work/codex-notes/scene_NNN.md
  186. .venv/bin/python scripts/00_build_video_notes.py --stage finalize --project-dir "$PROJECT_DIR"
  187. ```
  188. 对谈视频必须在 `batches` 之前完成 `work/speaker-map.json`。说话人证据优先使用 YouTube 官方简介、自我介绍、字幕、姓名条、镜头交接、官方节目页和频道历史;证据不足时保留 `说话人N`,不能强行猜名。
  189. 如果运行时暴露了真实模型 Token 数量,使用 `--stage usage` 写入 `work/token-usage.json`。没有真实用量时保持未知,不估算、不伪造费用。
  190. ## 输出结构
  191. ```text
  192. outputs/video-notes/<title>-<video-id>/
  193. ├── work/
  194. │ ├── source/ # 下载的视频、字幕、YouTube 元数据
  195. │ ├── transcript/ # 可读转录稿
  196. │ ├── video-use/ # 语义时间线输入
  197. │ ├── route-decision.json # 路径和视觉策略
  198. │ ├── timeline/ # 章节提示、边界证据、场景边界
  199. │ ├── candidates/ # 候选帧
  200. │ ├── keyframes/ # Codex 选择的最终关键帧
  201. │ ├── speaker-map.json # 对谈说话人映射
  202. │ ├── codex-batches/ # Codex 批次输入
  203. │ ├── codex-notes/ # 每个场景的完整解说
  204. │ ├── token-usage.json # 仅记录真实用量
  205. │ └── scene-manifest.json
  206. ├── verify/
  207. │ ├── mode-overview.jpg
  208. │ ├── boundary-timelines/
  209. │ ├── candidate-contact-sheets/
  210. │ ├── selected-keyframes.jpg
  211. │ ├── quality-audit.json
  212. │ ├── quality-audit.md
  213. │ └── pdf-pages-contact-sheet.jpg
  214. └── share/
  215. ├── *-light-polished.md
  216. ├── *-visual-explainer.md
  217. ├── *-visual-explainer.html
  218. └── *-visual-explainer.pdf
  219. ```
  220. 最终 ZIP 位于项目目录根部,只包含可分享的 `share/` 内容,不包含视频、凭据、浏览器状态或日志。
  221. ## 质量验证
  222. ```bash
  223. .venv/bin/pytest -q
  224. python3 -m compileall -q scripts tests
  225. git diff --check
  226. ```
  227. Finalize 会生成 `verify/quality-audit.json` 和 `verify/quality-audit.md`,检查:
  228. - 转录是否按原顺序完整覆盖。
  229. - 场景、解说和关键帧数量是否一致。
  230. - 对谈说话人映射是否完成。
  231. - HTML 是否引用了实际存在的图片。
  232. - PDF 是否成功渲染并生成页面概览。
  233. - ZIP 内容是否完整。
  234. - 是否存在字节级重复关键帧。
  235. - 是否记录了真实 Token 用量和显式费率。
  236. ## 贡献和来源
  237. 这是一个面向 Codex 的本地 Skill,不是独立网站或在线 API。修改处理逻辑时,请同步更新:
  238. 1. `SKILL.md` 和 `SKILL.zh-CN.md`。
  239. 2. `README.md` 和必要的模式研究文档。
  240. 3. 对应脚本测试和质量审计。
  241. 4. 项目流程图中的真实处理阶段。
  242. Watchless 使用 `video-use` 完成转录打包和局部时间线检查;第三方说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.