Skip to content
Back to search

talking-head-video-pipeline

SkillWorks with Claude CodeGitHub

End-to-end, stateful talking-head video production for complete beginners and experienced editors. Use when a user wants optional rough-cut guidance, transcription or caption revision, viewer-facing content logic groups, screenshot and demo placement, visual design, staged keyframe plus HyperFrames/GSAP preview, a synchronized final export, interrupted-work recovery, diagnosis, scoped revision, or reusable style learning from explicit feedback. Routes through internal workflow modules, optionally integrates video-use for raw footage, and preserves originals, evidence readability, privacy, and preview approval.

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/naive-kun--naive-video-skill/badge.svg)](/listings/naive-kun--naive-video-skill)

HTML

<a href="/listings/naive-kun--naive-video-skill"><img src="/api/listings/naive-kun--naive-video-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 184 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: talking-head-video-pipeline
  3. description: End-to-end, stateful talking-head video production for complete beginners and experienced editors. Use when a user wants optional rough-cut guidance, transcription or caption revision, viewer-facing content logic groups, screenshot and demo placement, visual design, staged keyframe plus HyperFrames/GSAP preview, a synchronized final export, interrupted-work recovery, diagnosis, scoped revision, or reusable style learning from explicit feedback. Routes through internal workflow modules, optionally integrates video-use for raw footage, and preserves originals, evidence readability, privacy, and preview approval.
  4. ---
  5. # Talking Head Video Pipeline
  6. Turn raw or rough-cut talking-head footage into an approved working cut, editable captions, a motion-packaged preview, and a verified final export. Treat this file as the router and shared contract. Read only the routed internal workflow and references needed for the current stage.
  7. ## Beginner Promise
  8. Assume the user has never edited with Codex.
  9. - Ask one short question at a time only when an answer cannot be inferred safely.
  10. - Prefer a working default over presenting many technical choices.
  11. - Explain the next visible result, not the renderer internals.
  12. - Introduce rough cutting, transcription providers, or API setup only when raw footage actually needs that branch.
  13. - Explain paid and local choices plainly, recommend one when useful, and never force it.
  14. - End every stage with exact output paths and the next phrase the user can say.
  15. - Resume existing work instead of restarting it.
  16. ## Non-Negotiable Rules
  17. 1. **Source is immutable.** Never overwrite or destructively edit the supplied source media.
  18. 2. **Main audio is the clock.** Do not retime, reorder, resample, or replace it unless the user explicitly approves a rough-cut strategy. After approval, the derived `working_video` becomes the downstream clock while the original remains immutable.
  19. 3. **Evidence stays readable.** Never cover screenshot body text, product UI, faces, or user-marked safe zones. Do not blur evidence assets.
  20. 4. **Preview before final.** Build an official preview and wait for approval unless the user explicitly requests direct export.
  21. 5. **Original-quality final.** Do not present an upscaled low-resolution preview as a true high-resolution final. Use the original source as the final base whenever possible.
  22. 6. **Do not interrupt progress.** If a render is advancing, wait and report progress. Change pipelines only after a real error or explicit approval.
  23. 7. **No private data in the skill.** Project-local paths, media names, brand rules, screenshots, customer details, and API keys stay in the user's project.
  24. 8. **Learn only from explicit feedback.** Do not infer permanent style rules from silence or one unconfirmed draft.
  25. 9. **Typography is part of correctness.** Declare and verify font family, real weight, caption line policy, baseline alignment, and longest-label fit before approval.
  26. 10. **Public defaults stay brand-neutral.** Store creator palettes, recurring card systems, and private visual rules only in the local profile.
  27. 11. **Public install exposes one Skill.** Keep stage modules under `references/workflows/`; do not add nested `SKILL.md` files that package managers may register separately.
  28. 12. **Install operations are recoverable.** Back up an existing installation before replacement and archive uninstall targets instead of performing recursive force deletion.
  29. 13. **Optional providers stay optional.** The curated default shot pack is native HyperFrames + GSAP. Never clone, install, update, or require ShotCraft, Remotion, or another provider without explicit user consent. Native recipes must remain a complete fallback.
  30. Read [references/quality-gates.md](references/quality-gates.md) before preview or export work.
  31. ## Route Table
  32. | User intent or phrase | Route | Typical output |
  33. |---|---|---|
  34. | `初始化视频项目`, `第一次用`, `start a video project` | `references/workflows/init.md` | State, edit plan, design profile |
  35. | `原片还没剪`, `删口误和停顿`, `帮我粗剪`, `raw takes`, `rough cut` | `references/workflows/rough-cut.md` | Approved non-destructive rough cut and timing handoff |
  36. | `抽字幕轴`, `只做字幕`, `transcribe`, `改字幕` | `references/workflows/captions.md` | SRT, CSV, transcript JSON |
  37. | `帮我设计`, `换颜色风格`, `规划弹窗`, `design` | `references/workflows/design.md` | DESIGN and complete edit plan |
  38. | `参考这张截图设计`, `按这张图的视觉语言`, `style reference` | `references/workflows/design.md` reference branch | Project-local STYLE_REFERENCE |
  39. | `按语义匹配动效`, `GSAP 动效丰富一点`, `semantic motion` | `references/workflows/design.md`, then preview | Validated MOTION_PLAN and preview |
  40. | `参考 ShotCraft`, `推荐电影感镜头`, `cinematic shot reference` | `references/workflows/design.md` ShotCraft branch | Optional mapped shot references in MOTION_PLAN |
  41. | `做预览`, `加动效`, `build preview` | `references/workflows/preview.md` | Official preview URL |
  42. | `出成片`, `导出 4K`, `export final` | `references/workflows/export.md` | Verified final video |
  43. | `改这个`, `恢复上一版`, `revise` | `references/workflows/revise.md` | Scoped revision and new preview/final |
  44. | `进度`, `到哪了`, `status` | `references/workflows/status.md` | Current stage and next action |
  45. | `体检`, `为什么失败`, `doctor` | `references/workflows/doctor.md` | Read-only diagnosis |
  46. | `以后都这样`, `记住这个风格`, `learn this` | `references/workflows/learn.md` | Confirmed project-local lessons |
  47. | `复盘成片`, `下次怎么改进`, `retro` | `references/workflows/retro.md` | Structured delivery retrospective |
  48. | `升级状态`, `迁移`, `migrate` | `references/workflows/migrate.md` | State schema upgrade |
  49. ## Mode Detection
  50. Before routing:
  51. 1. Identify the user's video project directory, not this skill repository.
  52. 2. Look for `.naive-video-state.json`.
  53. 3. If absent and the task is more than a one-off caption text edit, load the init workflow.
  54. 4. If present, read it plus `EDIT_PLAN.md`, `DESIGN.md`, and `VIDEO_LESSONS.md` only when relevant. Use `working_video` when present; otherwise use `main_video`.
  55. 5. Run `python3 tools/video_doctor.py --project <project_dir>` when state and files disagree.
  56. Use these stages:
  57. ```text
  58. initialized -> captions_ready -> design_ready -> preview_ready
  59. -> approved -> rendering -> final_ready
  60. ```
  61. Never mark a later stage until its quality gate passes.
  62. ## Default Pipeline
  63. When the user asks for the complete workflow:
  64. 1. Inspect source media with `ffprobe`.
  65. 2. Initialize project state and safe output directories.
  66. 3. Ask whether the footage is already rough-cut only when that status is unclear. If it is raw, load the optional rough-cut workflow and require strategy approval.
  67. 4. Produce or validate caption files from `working_video` when present, otherwise `main_video`.
  68. 5. Ask whether screenshots, recordings, product images, charts, or demos must appear. Let the user choose semantic placement, exact seconds/spoken-sentence anchors, or a hybrid; explain that exact anchors are more precise.
  69. 6. Normalize word-level timing when available and split the speech into viewer-facing logic groups. Do not fake word precision from whole-caption starts.
  70. 7. Collect or infer a style profile and safe zones. Offer optional screenshot-reference matching to beginners.
  71. 8. Write an edit plan and semantic motion plan with every requested insert, logic-group link, and time range.
  72. 9. For new projects, automatically map a few safe semantic nodes to the curated ShotCraft-inspired native pack unless the user chooses `skip`. Preserve existing approved projects, the native recipe, and offline fallback.
  73. 10. For first-use, new-style, or reasoning-heavy work, render representative static keyframes and resolve composition problems before a full dynamic preview.
  74. 11. Build a HyperFrames + GSAP preview using a browser-friendly proxy if needed.
  75. 12. Run preview quality gates and provide the official preview URL.
  76. 13. Wait for approval unless explicitly told to skip.
  77. 14. Render overlays or final composition using the approved working video and its audio clock.
  78. 15. Verify file existence, duration, resolution, frame rate, and audio.
  79. 16. Record only confirmed feedback as project-local lessons.
  80. 17. After delivery, run a factual retrospective and promote only explicit, privacy-safe rules.
  81. ## Project Files
  82. The init workflow creates this minimal project memory without touching source media:
  83. ```text
  84. <project_dir>/
  85. ├── .naive-video-state.json
  86. ├── EDIT_PLAN.md
  87. ├── DESIGN.md
  88. ├── CONTENT_LOGIC.json # viewer-facing reasoning groups and timed beats
  89. ├── STYLE_REFERENCE.md # created only when a reference image is used
  90. ├── MOTION_PLAN.json # created when semantic motion is planned
  91. ├── VIDEO_LESSONS.md
  92. ├── VIDEO_RETRO.md
  93. ├── edit/
  94. │ ├── rough-cut.mp4 # optional; original media is never overwritten
  95. │ ├── rough-cut-edl.json # optional decision record
  96. │ ├── script-aligned.srt
  97. │ ├── caption-table.csv
  98. │ └── transcripts/
  99. ├── preview/
  100. ├── final/
  101. └── qa/
  102. └── KEYFRAME_REVIEW.md # static-composition review before dynamic preview
  103. ```
  104. State is operational metadata, not a media database. Keep it small and never store transcript bodies, private screenshots, or secrets in it. See [references/state-management.md](references/state-management.md).
  105. ## Style Defaults
  106. If the user wants speed and gives no reference:
  107. - Preserve the source aspect ratio.
  108. - Use a clean, readable card system with one configurable accent color.
  109. - Use bold captions with restrained keyword emphasis.
  110. - Use GSAP transforms and opacity for motion.
  111. - Place cards in verified empty space.
  112. - Reduce motion density while screenshots or demos are visible.
  113. - Keep readable text level and baseline-aligned; animate the containing component instead of skewing labels.
  114. - Choose an explicit caption maximum line count and wrap policy.
  115. Ask for an accent color only if brand consistency matters. Otherwise use the neutral preset and make it easy to change later. Beginners may optionally provide a screenshot and choose `low`, `medium`, or `high` reference strength; explain that the skill copies visual language, never the source brand or content. Motion density is `restrained`, `balanced`, or `energetic`. See [references/style-onboarding.md](references/style-onboarding.md).
  116. Detailed GSAP recipes and semantic mappings live in [references/motion-recipes.md](references/motion-recipes.md). Runtime and plugin selection live in [references/gsap-runtime.md](references/gsap-runtime.md). Screenshot extraction and anti-copy rules live in [references/style-reference-workflow.md](references/style-reference-workflow.md). Asset timing choices live in [references/asset-onboarding.md](references/asset-onboarding.md). Load them only for the matching design branch.
  117. ShotCraft discovery and adaptation rules live in [references/shotcraft-integration.md](references/shotcraft-integration.md); the native beginner pack lives in [references/shotcraft-default-pack.md](references/shotcraft-default-pack.md). Load them for new automatic projects, named cards, or cinematic shot requests. Never install a provider silently.
  118. Word-level timing, viewer-facing logic groups, and accumulation/exit behavior live in [references/content-logic-workflow.md](references/content-logic-workflow.md). Load it after captions and before semantic design.
  119. Typography, component geometry, glass notifications, and seek-safe focus/type/split adaptation live in [references/visual-quality-rules.md](references/visual-quality-rules.md). Load it for every design or preview task.
  120. ## Self-Iteration Contract
  121. Self-iteration means improving the current user's workflow without leaking it into public defaults.
  122. Classify feedback into one scope:
  123. - `project`: applies only to this video.
  124. - `profile`: applies to this user's future videos; write it only after explicit confirmation.
  125. - `product`: a privacy-safe, general reliability improvement; propose it to the skill maintainer separately.
  126. Record profile feedback in `VIDEO_LESSONS.md` with the user's words, the confirmed rule, and the affected stage. Never copy media paths or private evidence into this repository. See [references/self-iteration.md](references/self-iteration.md).
  127. Use the retro workflow after delivery to separate failures, environment issues, and taste feedback before promoting any rule. New projects import active private-profile rules into `VIDEO_LESSONS.md` so the editor can actually apply them.
  128. ## Recovery Rules
  129. - If preview stops responding, check the process and port before rebuilding.
  130. - If a browser cannot decode HEVC/Main10 smoothly, make an H.264 proxy for preview only.
  131. - If a render session is running, poll it; do not terminate it merely because it is slow.
  132. - If partial frames exist, compare expected and actual frame counts before resuming or restarting.
  133. - Move damaged partial outputs to a project-local quarantine only after confirming they are not the sole valid result.
  134. - Keep logs outside command pipes that can terminate long jobs.
  135. ## Privacy Before Publishing
  136. Run:
  137. ```bash
  138. bash scripts/doctor.sh --privacy-scan .
  139. python3 tools/validate_skill.py .
  140. ```
  141. Block publication if either command reports personal absolute paths, secrets, private media names, invalid frontmatter, multiple skill manifests, missing internal workflows, unsafe install commands, or broken templates.
README.md · README · 380 lines

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

  1. # Naive Video Skill
  2. 给 Codex 使用的开源口播视频成片导师工作流:原片可以先走可选粗剪,也可以从现成粗剪或字幕轴开始,再完成素材插入、风格选择、可选 ShotCraft 镜头参考、HyperFrames + GSAP 预览和最终成片。
  3. 它不只是一份提示词。它包含首次初始化、可选 `video-use` 粗剪、阶段路由、项目状态、体检、迁移、质量闸门和显式反馈学习,目标是像导师一样一次问一个问题,让完全没有剪辑基础的人也能一步步拿到可播放成片。
  4. ## 三步开始
  5. ### 1. 下载并安装
  6. ```bash
  7. git clone https://github.com/naive-kun/naive-video-skill.git
  8. cd naive-video-skill
  9. bash install.sh --codex
  10. ```
  11. 安装后重启 Codex,或新建一个任务。
  12. ### WorkBuddy 用户
  13. 新版本整个仓库只暴露一个 `SKILL.md`,所以 WorkBuddy 新安装时只应出现一个技能:
  14. ```text
  15. talking-head-video-pipeline
  16. ```
  17. 初始化、粗剪、字幕、设计、预览和导出都是这个技能内部的工作流,不会再显示成十几个独立开关。如果旧版已经出现多个 `naive-video-*` 技能,请在 WorkBuddy 里停用或卸载这些旧条目,只保留 `talking-head-video-pipeline`;更新后的仓库不会再次创建它们。
  18. ### 2. 在素材目录打开 Codex
  19. 把原视频放在任意本地目录,然后在该目录打开 Codex。你不需要先创建工程。
  20. ### 3. 只说这一句
  21. ```text
  22. 用 $talking-head-video-pipeline 初始化视频项目,这是我的口播视频:<视频路径>
  23. ```
  24. Skill 会检查环境、读取视频参数、询问最少量的风格问题,并告诉你下一句该说什么。你可以什么都不准备直接用默认风格,也可以补一张喜欢的截图,让 Skill 参考它的配色、层级、卡片和构图。
  25. ## 新手会经历什么
  26. ```text
  27. 初始化
  28. -> 可选粗剪(原片才需要)
  29. -> 字幕轴
  30. -> 口播逻辑组与关键词时间
  31. -> 截图 / 录屏插入方式
  32. -> 风格与插入时间表
  33. -> 可选镜头参考
  34. -> 静态关键帧检查
  35. -> 官方预览链接
  36. -> 你确认
  37. -> 最终成片
  38. -> 可选复盘与长期规则
  39. ```
  40. 默认不改原视频、不改变主音频时钟;只有你明确同意粗剪策略后,才会把新生成的粗剪版作为后续工作时钟。它也不会用低清代理冒充最终成片,或让截图被字幕和卡片盖住。
  41. ## 原片也能开始:可选 Video Use 粗剪
  42. 如果你拿来的是多次重拍、带口误和长停顿的原片,Skill 会先问:`这段视频已经粗剪好了吗?`
  43. - 已经粗剪好:直接进入字幕和设计,不会拿一堆转写选项打断你。
  44. - 还没粗剪:可选调用独立的 [`video-use`](https://github.com/browser-use/video-use) Skill,先盘点素材、提出保留/删除策略,得到你确认后再生成一个不覆盖原片的粗剪版。
  45. - 没安装 `video-use`:会告诉你它是可选能力,并在你同意后再教你安装;不会偷偷装依赖。
  46. 需要靠转写找口误和剪切点时,会说明两条路,但不强制选择:
  47. - 云端词级转写:精准粗剪的推荐路线,尤其适合口误、重复和多 take;通常需要自己的 API Key,并可能产生费用。
  48. - 本地词级转写:可离线、可避免云端转写费,但速度、机器要求、口头语保留和时间戳稳定性取决于模型与设备。
  49. 已有 SRT、CSV 或词级 JSON 会优先复用,不会重复花钱转写。原片始终保留;确认后的粗剪只会作为后续字幕、动效和成片的工作视频。
  50. ## 截图、录屏和产品图怎么插
  51. 在设计前,Skill 会问有没有需要展示的截图、录屏、产品图、图表或演示视频,然后让你选择:
  52. - `semantic`:你只给素材,由 Skill 根据字幕语义决定飞入、停留和飞出时间,适合不熟悉时间轴的新手。
  53. - `exact`:你指定第几秒,或者指定“说到哪句话时出现”;这种方式更精准。
  54. - `hybrid`:重要素材由你定,其余交给 Skill。
  55. 如果你直接说“你帮我定”,就走语义插入;如果你给了秒数或原话,就按精准锚点执行。所有素材都会在 `EDIT_PLAN.md` 里记录原始要求和换算后的时间。
  56. ## 常用说法
  57. ```text
  58. 初始化视频项目,这是主视频:<path>
  59. 这还是原片,先帮我删掉口误、重复和明显停顿
  60. 只抽字幕轴,不动视频
  61. 用现有 SRT 做动效预览
  62. 这些截图你按字幕语义帮我安排飞入飞出:<paths>
  63. 说到“这里就是最终效果”时插入 <image-path>,停留 2 秒
  64. 参考这张截图设计视频风格:<image-path>
  65. 根据字幕语义自动匹配 GSAP 动效,动效密度 balanced
  66. 启用 ShotCraft 镜头推荐,最多 3 个;只借镜头语言,截图和演示段禁用
  67. 进度到哪了
  68. 体检这个视频项目
  69. 这个风格以后都这样,记住
  70. 复盘这条成片,把确认的问题变成下次的检查项
  71. 预览没问题,出最终成片
  72. ```
  73. 公开安装只会出现一个根 Skill。初始化、粗剪、字幕、设计、预览、导出等步骤是它内部按需读取的工作流,不会在 WorkBuddy 里展开成一排独立技能。完整示例见 [examples/prompts.md](examples/prompts.md)。
  74. ## 安装选项
  75. ```bash
  76. bash install.sh --codex # 默认:符号链接,更新仓库后立即生效
  77. bash install.sh --codex --copy # 冻结复制,更新后需重新安装
  78. bash install.sh --claude # 安装到 Claude Code
  79. bash install.sh --all # 两边都安装
  80. bash install.sh --codex --force # 无交互升级,但仍会先备份旧安装
  81. ```
  82. 卸载:
  83. ```bash
  84. bash uninstall.sh --codex
  85. ```
  86. 安装器不会复制你的素材,也不会写入项目目录,也不会批量清除已有文件:
  87. - 首次安装只创建一个根 Skill。
  88. - 升级时,旧安装先移动到 `~/.naive-video-skill/backups/<客户端>/<时间戳>/`。
  89. - 旧版 `naive-video-*` 多入口会移动到同一备份的 `legacy/` 目录。
  90. - 安装失败时会恢复先前版本;失败副本会保留在 `~/.naive-video-skill/failed/` 供检查。
  91. - 卸载不是永久清除,而是移动到 `~/.naive-video-skill/uninstalled/`,可以恢复。
  92. 这些目录位于 Codex、Claude Code 和 WorkBuddy 的技能发现目录之外,因此备份中的旧 `SKILL.md` 不会再次显示成技能卡片。
  93. 安装器本身不会创建 `/tmp/naive-video-skill` 或 `_audit_naive_video` 之类的审计副本;这类目录通常来自外部安装器或安全审计。如果用户取消了清理,它们只是额外的仓库副本,可以先保留,不影响 Skill 使用。
  94. 真正开始任务时,内部初始化工作流才会在你的视频项目中创建状态和输出目录。
  95. ## 环境体检
  96. ```bash
  97. bash scripts/doctor.sh
  98. ```
  99. 至少需要:
  100. - `ffmpeg` / `ffprobe`
  101. - `python3`
  102. - `node` / `npm` / `npx`(使用 HyperFrames 时)
  103. macOS 常用安装:
  104. ```bash
  105. brew install ffmpeg node python
  106. ```
  107. HyperFrames 可按需运行:
  108. ```bash
  109. npx --yes hyperframes --help
  110. ```
  111. 转写能力不绑定某一个收费 API。Skill 会优先复用已有 SRT/CSV/词级 JSON。只有原片需要粗剪或确实需要重新转写时,才会说明云端词级转写与本地词级转写的差别:精准粗剪优先推荐云端词级方案并明确费用可能性,本地方案保持可选。都没有时会明确告诉你缺什么,而不是假装已经完成。
  112. ## 四种风格起点
  113. - `clean`: 白色轻卡片,适合教程和专业复盘。
  114. - `dark`: 深色高对比,适合技术和产品演示。
  115. - `sticker`: 贴纸式动效,适合轻松口播。
  116. - `minimal`: 只保留字幕和少量重点提示。
  117. 颜色、字幕、卡片、动效密度和安全区域都写入项目自己的 `DESIGN.md`。公开仓库不包含作者个人品牌规则。
  118. ## 截图参考风格
  119. 第一次用时可以直接说:
  120. ```text
  121. 参考这张截图设计视频风格:<图片路径>
  122. 按它的视觉语言做,但不要复制品牌和内容。参考强度 medium。
  123. ```
  124. - `low`: 只参考配色和气质。
  125. - `medium`: 还参考层级、卡片、间距和构图,适合大多数新手。
  126. - `high`: 尽量贴近视觉语言,但仍不会复制 Logo、水印、人物、原文或完整品牌 UI。
  127. 提取结果写入当前视频项目的 `STYLE_REFERENCE.md`。静态截图不能证明原视频怎么运动,因此由截图推断的动效会明确标记为 `inferred`,并通过官方预览让你确认。
  128. ## GSAP 语义动效
  129. Skill 会把字幕里的数字、列举、对比、警告、流程、因果、任务转移、确认、结果和提问映射到本地 GSAP 配方,而不是给整条视频反复套同一种角落卡片。
  130. 动效密度可选:
  131. - `restrained`: 克制,优先证据可读性。
  132. - `balanced`: 默认,语义节点和留白兼顾。
  133. - `energetic`: 更丰富,但仍避开人脸、字幕和截图;15 秒展示建议至少 6 个独立语义节点,长视频按时长缓慢增加。
  134. 详细计划写入项目的 `MOTION_PLAN.json`,预览前由离线检查器验证配方、时间、字幕证据和安全区域。默认只使用项目已有 GSAP;插件缺失时自动走 core fallback,不会让整个预览失败。
  135. 在动效计划之前,Skill 还会生成 `CONTENT_LOGIC.json`:它不按句号机械切段,而是按“观众正在理解的完整论证”分组。字幕保留说了什么,逻辑组只保留观众要记住什么。输入、关系和结果按口播逐层累积,结论讲完后整组退出,不再听到一个词就弹一张卡、下一句话又全部清空。
  136. 如果只有 SRT,Skill 会明确标记为 `cue-level`,不会拿整句开始时间冒充词级时间;已有可靠词级数据时,会规范成 `edit/word-timeline.json` 用于精准关键词触发。
  137. 如果项目使用 npm,推荐安装官方包:
  138. ```bash
  139. npm install gsap
  140. ```
  141. 如果已经下载了官方浏览器分发包,也可以只把当前项目需要的 `gsap.min.js` 和插件复制到项目自己的 runtime 目录。先检查版本和许可证头:
  142. ```bash
  143. python3 tools/gsap_check.py <gsap-directory>
  144. ```
  145. 视频常用的可选插件是 SplitText、Flip、ScrambleText、DrawSVG、MorphSVG 和 MotionPath;其中 ScrambleText 只用于很短的系统状态,DrawSVG 不能拿来做廉价手绘箭头。GSDevTools 只用于开发。ScrollTrigger、ScrollSmoother、Observer、Draggable 等网页滚动/交互插件通常不进入固定时间轴视频,视频仍由一个暂停、可 seek 的 GSAP timeline 驱动。
  146. 本仓库不会直接打包个人下载目录里的 GSAP 文件。GSAP 文件保留自己的版权和标准许可证,MIT 只覆盖本仓库自行编写的内容。
  147. ## 可选 ShotCraft 镜头参考
  148. ShotCraft 不是第二套剪辑流程,也不是必装渲染器。它只为少量高价值语义节点提供镜头语言参考;字幕、主音频时钟、安全区、HyperFrames 官方预览和最终导出仍由本 Skill 管理。
  149. 新项目默认使用第一种,新手也可以随时切换:
  150. - `automatic`(推荐):根据字幕语义自动选择少量镜头,用本地 HyperFrames + GSAP 重做,不需要安装 ShotCraft 或 Remotion;`balanced` 最多 3 个。
  151. - `gallery`:你在 ShotCraft 里挑好卡片名,再交给 Skill 适配。
  152. - `skip`:只使用基础 GSAP 语义配方,不加精选镜头层。
  153. 即使本机没装 ShotCraft,离线映射仍可给出 `reference-only` 建议,原生动效不会中断:
  154. ```bash
  155. python3 tools/shotcraft_catalog.py --semantic list --density balanced --json
  156. ```
  157. 初始化后,自动模式会在原生 `MOTION_PLAN.json` 通过基础检查后运行:
  158. ```bash
  159. python3 tools/shotcraft_default_plan.py <project-dir>/MOTION_PLAN.json --in-place
  160. python3 tools/motion_plan_check.py <project-dir>/MOTION_PLAN.json
  161. ```
  162. 它只匹配“字幕语义 + 原生 recipe_id”都一致的节点,会避开截图、演示、人脸和字幕安全区;数量上限不是完成指标,找不到合适节点时可以一个都不加。旧项目已有设计不会被升级过程自动改写。
  163. 只有你明确想浏览或核验上游卡片时,才需要自行安装外部仓库:
  164. ```bash
  165. git clone --depth 1 https://github.com/Vincentwei1021/video-shotcraft.git \
  166. ~/.naive-video/providers/video-shotcraft
  167. ```
  168. Skill 不会替你静默执行这条命令。默认把参考改写成 `gsap-adapted` 或 `hyperframes-custom`,预览和导出不依赖上游仓库。
  169. 复杂 `remotion-subclip` 只有明确同意后才使用。Skill 内置的是安装管理工具,不是打包好的 `node_modules`:
  170. ```bash
  171. # 只检查或看计划:不会写文件、不会联网
  172. python3 tools/remotion_runtime.py --project <project-dir> --check
  173. python3 tools/remotion_runtime.py --project <project-dir> --plan
  174. # 用户明确同意下载和许可证后,才执行项目内安装
  175. python3 tools/remotion_runtime.py --project <project-dir> --install --yes
  176. ```
  177. 运行时只写入该视频项目的 `runtime/remotion/`,不会污染全局 Node 环境。Remotion 子片段必须预渲染静音、保留原生 fallback、不能改变主音频时间轴;商业使用前还要单独查看 [Remotion License](https://www.remotion.dev/license)。
  178. 适配层只包含自行编写的语义映射和上游链接,不复制 ShotCraft 代码、音频、预览或模板。ShotCraft 本身使用 Apache-2.0;本仓库自有内容继续使用 MIT。
  179. ## 视觉质量与通用组件
  180. 公开版不会内置作者个人的颜色、字体或固定卡片系统。每个项目必须在 `DESIGN.md` 里明确字体、真实字重、字幕最大行数、换行策略、文本基线、组件类型和最长标签适配,再通过离线检查:
  181. ```bash
  182. python3 tools/design_check.py <project-dir>/DESIGN.md
  183. ```
  184. 通用组件包括:
  185. - `structured card`:解释、步骤和对比。
  186. - `glass notification`:短状态、提醒、确认和 CTA。
  187. - `focus-frame`:在稳定容器内切换关键词焦点。
  188. - `seekable-type`:由视频时间轴驱动的短文本输入效果。
  189. - `split-reveal`:卡片标题、步骤和警告的逐词或克制逐字入场。
  190. 这些组件只规定信息角色和质量门槛,不规定某个创作者的配色。GSAP 负责运动,字体、间距、对齐、表面和层级仍由设计契约负责。
  191. 网页组件里的 `setInterval`、随机打字速度、`IntersectionObserver` 和 `ScrollTrigger` 不会直接搬进视频。Skill 会把它们改成暂停、可 seek、任意时间点都能稳定复现的 GSAP timeline。
  192. 默认拒绝未经要求的手绘感箭头、粗糙框线、细体大字、倾斜正文、错位基线和无规则的单双行字幕切换。
  193. ## 项目状态与恢复
  194. 初始化后,项目中会出现:
  195. ```text
  196. .naive-video-state.json
  197. EDIT_PLAN.md
  198. DESIGN.md
  199. CONTENT_LOGIC.json # 口播逻辑组、语义节拍与时间精度
  200. STYLE_REFERENCE.md # 使用参考图时创建
  201. MOTION_PLAN.json # 使用语义动效时创建
  202. VIDEO_LESSONS.md
  203. VIDEO_RETRO.md
  204. edit/
  205. rough-cut.mp4 # 需要粗剪时才有
  206. rough-cut-edl.json # 可选剪切决策记录
  207. preview/
  208. final/
  209. qa/
  210. KEYFRAME_REVIEW.md # 静态关键帧审查记录
  211. ```
  212. 状态文件让新任务知道已经做到字幕、预览还是导出阶段。渲染中断时,Skill 会先检查进度和产物,不会无故推倒重来。
  213. ## 先关键帧,再动态预览
  214. 第一次使用、新风格或逻辑关系复杂时,Skill 会先生成一组代表性关键帧:开场、每个主要逻辑组的峰值、信息最密集画面、截图/演示/PiP、主要转场和结尾。关键帧先检查构图、字体、层级和遮挡;通过后才制作完整动态预览。静态通过不代表动效时间已经通过,动态预览仍然需要确认。
  215. 修改时推荐这样说:
  216. ```text
  217. 12.4-14.0 秒:右侧结果卡现在遮住截图正文,请缩小并移到左上安全区。
  218. 只改这一处,先给我受影响关键帧或前后各 3 秒短片段,其他已确认部分保持不变。
  219. ```
  220. Skill 会先修改最小责任层,再局部验证,不会因为一句“整体优化”把已经确认的画面全部重做。
  221. ## 自我迭代
  222. 当你明确说“这个风格以后都这样”或“以后不要再这样”,Skill 才会把规则写进项目的 `VIDEO_LESSONS.md`。成片交付后,内部复盘工作流会把成功项、失败根因和预防检查写入 `VIDEO_RETRO.md`,但不会擅自把推测变成长期偏好。
  223. 需要跨视频复用时,确认后的脱敏规则会保存到本机私有配置:
  224. ```text
  225. ~/.naive-video/profiles/default.json
  226. ```
  227. 新项目会检测并复用它;你也可以要求某个项目忽略旧风格。
  228. 长期规则带有稳定 ID、启用状态和确认时间;规则冲突时可以显式替代或停用旧规则。新项目会把当前启用规则导入自己的 `VIDEO_LESSONS.md`,所以“记住”会真正影响下一条视频。
  229. 反馈分三层:
  230. - 当前视频专用
  231. - 当前用户长期风格
  232. - 可脱敏的通用产品改进
  233. 个人路径、品牌名、截图、客户信息和素材内容不会自动回流到公开仓库。
  234. ## 隐私与发布检查
  235. ```bash
  236. bash scripts/doctor.sh --privacy-scan .
  237. python3 tools/validate_skill.py .
  238. bash tests/smoke.sh
  239. ```
  240. CI 会执行同样的无密钥检查。不要提交 `.env`、真实客户素材、转写缓存、渲染文件或本机绝对路径。
  241. ## 仓库结构
  242. ```text
  243. naive-video-skill/
  244. ├── SKILL.md # 总路由与硬规则
  245. ├── references/ # 状态、质量、视觉规则、精选镜头包及内部工作流
  246. ├── templates/ # 项目初始化模板
  247. ├── migrations/ # 状态 schema 迁移
  248. ├── tools/ # 无第三方依赖的检查与初始化工具
  249. ├── scripts/ # 安装、体检入口
  250. ├── tests/ # 干净环境冒烟测试
  251. └── agents/openai.yaml
  252. ```
  253. 仓库中只能存在根目录这一个 `SKILL.md`。CI 会检查这个约束,避免 WorkBuddy 等递归扫描器把内部工作流误装成多个技能。
  254. ## English Summary
  255. Naive Video Skill is a beginner-first, stateful Codex workflow for talking-head video production. It routes optional non-destructive rough cutting, captions, asset placement, semantic motion, optional ShotCraft shot references, preview, export, revision, diagnosis, explicit-feedback learning, and state migration while preserving originals, evidence readability, and privacy.
  256. ## License
  257. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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