talking-head-video-pipeline
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.
Badge for your README
Markdown
[](/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
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)
- ---
- name: talking-head-video-pipeline
- 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.
- ---
- # Talking Head Video Pipeline
- 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.
- ## Beginner Promise
- Assume the user has never edited with Codex.
- - Ask one short question at a time only when an answer cannot be inferred safely.
- - Prefer a working default over presenting many technical choices.
- - Explain the next visible result, not the renderer internals.
- - Introduce rough cutting, transcription providers, or API setup only when raw footage actually needs that branch.
- - Explain paid and local choices plainly, recommend one when useful, and never force it.
- - End every stage with exact output paths and the next phrase the user can say.
- - Resume existing work instead of restarting it.
- ## Non-Negotiable Rules
- 1. **Source is immutable.** Never overwrite or destructively edit the supplied source media.
- 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.
- 3. **Evidence stays readable.** Never cover screenshot body text, product UI, faces, or user-marked safe zones. Do not blur evidence assets.
- 4. **Preview before final.** Build an official preview and wait for approval unless the user explicitly requests direct export.
- 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.
- 6. **Do not interrupt progress.** If a render is advancing, wait and report progress. Change pipelines only after a real error or explicit approval.
- 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.
- 8. **Learn only from explicit feedback.** Do not infer permanent style rules from silence or one unconfirmed draft.
- 9. **Typography is part of correctness.** Declare and verify font family, real weight, caption line policy, baseline alignment, and longest-label fit before approval.
- 10. **Public defaults stay brand-neutral.** Store creator palettes, recurring card systems, and private visual rules only in the local profile.
- 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.
- 12. **Install operations are recoverable.** Back up an existing installation before replacement and archive uninstall targets instead of performing recursive force deletion.
- 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.
- Read [references/quality-gates.md](references/quality-gates.md) before preview or export work.
- ## Route Table
- | User intent or phrase | Route | Typical output |
- |---|---|---|
- | `初始化视频项目`, `第一次用`, `start a video project` | `references/workflows/init.md` | State, edit plan, design profile |
- | `原片还没剪`, `删口误和停顿`, `帮我粗剪`, `raw takes`, `rough cut` | `references/workflows/rough-cut.md` | Approved non-destructive rough cut and timing handoff |
- | `抽字幕轴`, `只做字幕`, `transcribe`, `改字幕` | `references/workflows/captions.md` | SRT, CSV, transcript JSON |
- | `帮我设计`, `换颜色风格`, `规划弹窗`, `design` | `references/workflows/design.md` | DESIGN and complete edit plan |
- | `参考这张截图设计`, `按这张图的视觉语言`, `style reference` | `references/workflows/design.md` reference branch | Project-local STYLE_REFERENCE |
- | `按语义匹配动效`, `GSAP 动效丰富一点`, `semantic motion` | `references/workflows/design.md`, then preview | Validated MOTION_PLAN and preview |
- | `参考 ShotCraft`, `推荐电影感镜头`, `cinematic shot reference` | `references/workflows/design.md` ShotCraft branch | Optional mapped shot references in MOTION_PLAN |
- | `做预览`, `加动效`, `build preview` | `references/workflows/preview.md` | Official preview URL |
- | `出成片`, `导出 4K`, `export final` | `references/workflows/export.md` | Verified final video |
- | `改这个`, `恢复上一版`, `revise` | `references/workflows/revise.md` | Scoped revision and new preview/final |
- | `进度`, `到哪了`, `status` | `references/workflows/status.md` | Current stage and next action |
- | `体检`, `为什么失败`, `doctor` | `references/workflows/doctor.md` | Read-only diagnosis |
- | `以后都这样`, `记住这个风格`, `learn this` | `references/workflows/learn.md` | Confirmed project-local lessons |
- | `复盘成片`, `下次怎么改进`, `retro` | `references/workflows/retro.md` | Structured delivery retrospective |
- | `升级状态`, `迁移`, `migrate` | `references/workflows/migrate.md` | State schema upgrade |
- ## Mode Detection
- Before routing:
- 1. Identify the user's video project directory, not this skill repository.
- 2. Look for `.naive-video-state.json`.
- 3. If absent and the task is more than a one-off caption text edit, load the init workflow.
- 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`.
- 5. Run `python3 tools/video_doctor.py --project <project_dir>` when state and files disagree.
- Use these stages:
- ```text
- initialized -> captions_ready -> design_ready -> preview_ready
- -> approved -> rendering -> final_ready
- ```
- Never mark a later stage until its quality gate passes.
- ## Default Pipeline
- When the user asks for the complete workflow:
- 1. Inspect source media with `ffprobe`.
- 2. Initialize project state and safe output directories.
- 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.
- 4. Produce or validate caption files from `working_video` when present, otherwise `main_video`.
- 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.
- 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.
- 7. Collect or infer a style profile and safe zones. Offer optional screenshot-reference matching to beginners.
- 8. Write an edit plan and semantic motion plan with every requested insert, logic-group link, and time range.
- 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.
- 10. For first-use, new-style, or reasoning-heavy work, render representative static keyframes and resolve composition problems before a full dynamic preview.
- 11. Build a HyperFrames + GSAP preview using a browser-friendly proxy if needed.
- 12. Run preview quality gates and provide the official preview URL.
- 13. Wait for approval unless explicitly told to skip.
- 14. Render overlays or final composition using the approved working video and its audio clock.
- 15. Verify file existence, duration, resolution, frame rate, and audio.
- 16. Record only confirmed feedback as project-local lessons.
- 17. After delivery, run a factual retrospective and promote only explicit, privacy-safe rules.
- ## Project Files
- The init workflow creates this minimal project memory without touching source media:
- ```text
- <project_dir>/
- ├── .naive-video-state.json
- ├── EDIT_PLAN.md
- ├── DESIGN.md
- ├── CONTENT_LOGIC.json # viewer-facing reasoning groups and timed beats
- ├── STYLE_REFERENCE.md # created only when a reference image is used
- ├── MOTION_PLAN.json # created when semantic motion is planned
- ├── VIDEO_LESSONS.md
- ├── VIDEO_RETRO.md
- ├── edit/
- │ ├── rough-cut.mp4 # optional; original media is never overwritten
- │ ├── rough-cut-edl.json # optional decision record
- │ ├── script-aligned.srt
- │ ├── caption-table.csv
- │ └── transcripts/
- ├── preview/
- ├── final/
- └── qa/
- └── KEYFRAME_REVIEW.md # static-composition review before dynamic preview
- ```
- 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).
- ## Style Defaults
- If the user wants speed and gives no reference:
- - Preserve the source aspect ratio.
- - Use a clean, readable card system with one configurable accent color.
- - Use bold captions with restrained keyword emphasis.
- - Use GSAP transforms and opacity for motion.
- - Place cards in verified empty space.
- - Reduce motion density while screenshots or demos are visible.
- - Keep readable text level and baseline-aligned; animate the containing component instead of skewing labels.
- - Choose an explicit caption maximum line count and wrap policy.
- 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).
- 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.
- 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.
- 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.
- 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.
- ## Self-Iteration Contract
- Self-iteration means improving the current user's workflow without leaking it into public defaults.
- Classify feedback into one scope:
- - `project`: applies only to this video.
- - `profile`: applies to this user's future videos; write it only after explicit confirmation.
- - `product`: a privacy-safe, general reliability improvement; propose it to the skill maintainer separately.
- 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).
- 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.
- ## Recovery Rules
- - If preview stops responding, check the process and port before rebuilding.
- - If a browser cannot decode HEVC/Main10 smoothly, make an H.264 proxy for preview only.
- - If a render session is running, poll it; do not terminate it merely because it is slow.
- - If partial frames exist, compare expected and actual frame counts before resuming or restarting.
- - Move damaged partial outputs to a project-local quarantine only after confirming they are not the sole valid result.
- - Keep logs outside command pipes that can terminate long jobs.
- ## Privacy Before Publishing
- Run:
- ```bash
- bash scripts/doctor.sh --privacy-scan .
- python3 tools/validate_skill.py .
- ```
- 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)
- # Naive Video Skill
- 给 Codex 使用的开源口播视频成片导师工作流:原片可以先走可选粗剪,也可以从现成粗剪或字幕轴开始,再完成素材插入、风格选择、可选 ShotCraft 镜头参考、HyperFrames + GSAP 预览和最终成片。
- 它不只是一份提示词。它包含首次初始化、可选 `video-use` 粗剪、阶段路由、项目状态、体检、迁移、质量闸门和显式反馈学习,目标是像导师一样一次问一个问题,让完全没有剪辑基础的人也能一步步拿到可播放成片。
- ## 三步开始
- ### 1. 下载并安装
- ```bash
- git clone https://github.com/naive-kun/naive-video-skill.git
- cd naive-video-skill
- bash install.sh --codex
- ```
- 安装后重启 Codex,或新建一个任务。
- ### WorkBuddy 用户
- 新版本整个仓库只暴露一个 `SKILL.md`,所以 WorkBuddy 新安装时只应出现一个技能:
- ```text
- talking-head-video-pipeline
- ```
- 初始化、粗剪、字幕、设计、预览和导出都是这个技能内部的工作流,不会再显示成十几个独立开关。如果旧版已经出现多个 `naive-video-*` 技能,请在 WorkBuddy 里停用或卸载这些旧条目,只保留 `talking-head-video-pipeline`;更新后的仓库不会再次创建它们。
- ### 2. 在素材目录打开 Codex
- 把原视频放在任意本地目录,然后在该目录打开 Codex。你不需要先创建工程。
- ### 3. 只说这一句
- ```text
- 用 $talking-head-video-pipeline 初始化视频项目,这是我的口播视频:<视频路径>
- ```
- Skill 会检查环境、读取视频参数、询问最少量的风格问题,并告诉你下一句该说什么。你可以什么都不准备直接用默认风格,也可以补一张喜欢的截图,让 Skill 参考它的配色、层级、卡片和构图。
- ## 新手会经历什么
- ```text
- 初始化
- -> 可选粗剪(原片才需要)
- -> 字幕轴
- -> 口播逻辑组与关键词时间
- -> 截图 / 录屏插入方式
- -> 风格与插入时间表
- -> 可选镜头参考
- -> 静态关键帧检查
- -> 官方预览链接
- -> 你确认
- -> 最终成片
- -> 可选复盘与长期规则
- ```
- 默认不改原视频、不改变主音频时钟;只有你明确同意粗剪策略后,才会把新生成的粗剪版作为后续工作时钟。它也不会用低清代理冒充最终成片,或让截图被字幕和卡片盖住。
- ## 原片也能开始:可选 Video Use 粗剪
- 如果你拿来的是多次重拍、带口误和长停顿的原片,Skill 会先问:`这段视频已经粗剪好了吗?`
- - 已经粗剪好:直接进入字幕和设计,不会拿一堆转写选项打断你。
- - 还没粗剪:可选调用独立的 [`video-use`](https://github.com/browser-use/video-use) Skill,先盘点素材、提出保留/删除策略,得到你确认后再生成一个不覆盖原片的粗剪版。
- - 没安装 `video-use`:会告诉你它是可选能力,并在你同意后再教你安装;不会偷偷装依赖。
- 需要靠转写找口误和剪切点时,会说明两条路,但不强制选择:
- - 云端词级转写:精准粗剪的推荐路线,尤其适合口误、重复和多 take;通常需要自己的 API Key,并可能产生费用。
- - 本地词级转写:可离线、可避免云端转写费,但速度、机器要求、口头语保留和时间戳稳定性取决于模型与设备。
- 已有 SRT、CSV 或词级 JSON 会优先复用,不会重复花钱转写。原片始终保留;确认后的粗剪只会作为后续字幕、动效和成片的工作视频。
- ## 截图、录屏和产品图怎么插
- 在设计前,Skill 会问有没有需要展示的截图、录屏、产品图、图表或演示视频,然后让你选择:
- - `semantic`:你只给素材,由 Skill 根据字幕语义决定飞入、停留和飞出时间,适合不熟悉时间轴的新手。
- - `exact`:你指定第几秒,或者指定“说到哪句话时出现”;这种方式更精准。
- - `hybrid`:重要素材由你定,其余交给 Skill。
- 如果你直接说“你帮我定”,就走语义插入;如果你给了秒数或原话,就按精准锚点执行。所有素材都会在 `EDIT_PLAN.md` 里记录原始要求和换算后的时间。
- ## 常用说法
- ```text
- 初始化视频项目,这是主视频:<path>
- 这还是原片,先帮我删掉口误、重复和明显停顿
- 只抽字幕轴,不动视频
- 用现有 SRT 做动效预览
- 这些截图你按字幕语义帮我安排飞入飞出:<paths>
- 说到“这里就是最终效果”时插入 <image-path>,停留 2 秒
- 参考这张截图设计视频风格:<image-path>
- 根据字幕语义自动匹配 GSAP 动效,动效密度 balanced
- 启用 ShotCraft 镜头推荐,最多 3 个;只借镜头语言,截图和演示段禁用
- 进度到哪了
- 体检这个视频项目
- 这个风格以后都这样,记住
- 复盘这条成片,把确认的问题变成下次的检查项
- 预览没问题,出最终成片
- ```
- 公开安装只会出现一个根 Skill。初始化、粗剪、字幕、设计、预览、导出等步骤是它内部按需读取的工作流,不会在 WorkBuddy 里展开成一排独立技能。完整示例见 [examples/prompts.md](examples/prompts.md)。
- ## 安装选项
- ```bash
- bash install.sh --codex # 默认:符号链接,更新仓库后立即生效
- bash install.sh --codex --copy # 冻结复制,更新后需重新安装
- bash install.sh --claude # 安装到 Claude Code
- bash install.sh --all # 两边都安装
- bash install.sh --codex --force # 无交互升级,但仍会先备份旧安装
- ```
- 卸载:
- ```bash
- bash uninstall.sh --codex
- ```
- 安装器不会复制你的素材,也不会写入项目目录,也不会批量清除已有文件:
- - 首次安装只创建一个根 Skill。
- - 升级时,旧安装先移动到 `~/.naive-video-skill/backups/<客户端>/<时间戳>/`。
- - 旧版 `naive-video-*` 多入口会移动到同一备份的 `legacy/` 目录。
- - 安装失败时会恢复先前版本;失败副本会保留在 `~/.naive-video-skill/failed/` 供检查。
- - 卸载不是永久清除,而是移动到 `~/.naive-video-skill/uninstalled/`,可以恢复。
- 这些目录位于 Codex、Claude Code 和 WorkBuddy 的技能发现目录之外,因此备份中的旧 `SKILL.md` 不会再次显示成技能卡片。
- 安装器本身不会创建 `/tmp/naive-video-skill` 或 `_audit_naive_video` 之类的审计副本;这类目录通常来自外部安装器或安全审计。如果用户取消了清理,它们只是额外的仓库副本,可以先保留,不影响 Skill 使用。
- 真正开始任务时,内部初始化工作流才会在你的视频项目中创建状态和输出目录。
- ## 环境体检
- ```bash
- bash scripts/doctor.sh
- ```
- 至少需要:
- - `ffmpeg` / `ffprobe`
- - `python3`
- - `node` / `npm` / `npx`(使用 HyperFrames 时)
- macOS 常用安装:
- ```bash
- brew install ffmpeg node python
- ```
- HyperFrames 可按需运行:
- ```bash
- npx --yes hyperframes --help
- ```
- 转写能力不绑定某一个收费 API。Skill 会优先复用已有 SRT/CSV/词级 JSON。只有原片需要粗剪或确实需要重新转写时,才会说明云端词级转写与本地词级转写的差别:精准粗剪优先推荐云端词级方案并明确费用可能性,本地方案保持可选。都没有时会明确告诉你缺什么,而不是假装已经完成。
- ## 四种风格起点
- - `clean`: 白色轻卡片,适合教程和专业复盘。
- - `dark`: 深色高对比,适合技术和产品演示。
- - `sticker`: 贴纸式动效,适合轻松口播。
- - `minimal`: 只保留字幕和少量重点提示。
- 颜色、字幕、卡片、动效密度和安全区域都写入项目自己的 `DESIGN.md`。公开仓库不包含作者个人品牌规则。
- ## 截图参考风格
- 第一次用时可以直接说:
- ```text
- 参考这张截图设计视频风格:<图片路径>
- 按它的视觉语言做,但不要复制品牌和内容。参考强度 medium。
- ```
- - `low`: 只参考配色和气质。
- - `medium`: 还参考层级、卡片、间距和构图,适合大多数新手。
- - `high`: 尽量贴近视觉语言,但仍不会复制 Logo、水印、人物、原文或完整品牌 UI。
- 提取结果写入当前视频项目的 `STYLE_REFERENCE.md`。静态截图不能证明原视频怎么运动,因此由截图推断的动效会明确标记为 `inferred`,并通过官方预览让你确认。
- ## GSAP 语义动效
- Skill 会把字幕里的数字、列举、对比、警告、流程、因果、任务转移、确认、结果和提问映射到本地 GSAP 配方,而不是给整条视频反复套同一种角落卡片。
- 动效密度可选:
- - `restrained`: 克制,优先证据可读性。
- - `balanced`: 默认,语义节点和留白兼顾。
- - `energetic`: 更丰富,但仍避开人脸、字幕和截图;15 秒展示建议至少 6 个独立语义节点,长视频按时长缓慢增加。
- 详细计划写入项目的 `MOTION_PLAN.json`,预览前由离线检查器验证配方、时间、字幕证据和安全区域。默认只使用项目已有 GSAP;插件缺失时自动走 core fallback,不会让整个预览失败。
- 在动效计划之前,Skill 还会生成 `CONTENT_LOGIC.json`:它不按句号机械切段,而是按“观众正在理解的完整论证”分组。字幕保留说了什么,逻辑组只保留观众要记住什么。输入、关系和结果按口播逐层累积,结论讲完后整组退出,不再听到一个词就弹一张卡、下一句话又全部清空。
- 如果只有 SRT,Skill 会明确标记为 `cue-level`,不会拿整句开始时间冒充词级时间;已有可靠词级数据时,会规范成 `edit/word-timeline.json` 用于精准关键词触发。
- 如果项目使用 npm,推荐安装官方包:
- ```bash
- npm install gsap
- ```
- 如果已经下载了官方浏览器分发包,也可以只把当前项目需要的 `gsap.min.js` 和插件复制到项目自己的 runtime 目录。先检查版本和许可证头:
- ```bash
- python3 tools/gsap_check.py <gsap-directory>
- ```
- 视频常用的可选插件是 SplitText、Flip、ScrambleText、DrawSVG、MorphSVG 和 MotionPath;其中 ScrambleText 只用于很短的系统状态,DrawSVG 不能拿来做廉价手绘箭头。GSDevTools 只用于开发。ScrollTrigger、ScrollSmoother、Observer、Draggable 等网页滚动/交互插件通常不进入固定时间轴视频,视频仍由一个暂停、可 seek 的 GSAP timeline 驱动。
- 本仓库不会直接打包个人下载目录里的 GSAP 文件。GSAP 文件保留自己的版权和标准许可证,MIT 只覆盖本仓库自行编写的内容。
- ## 可选 ShotCraft 镜头参考
- ShotCraft 不是第二套剪辑流程,也不是必装渲染器。它只为少量高价值语义节点提供镜头语言参考;字幕、主音频时钟、安全区、HyperFrames 官方预览和最终导出仍由本 Skill 管理。
- 新项目默认使用第一种,新手也可以随时切换:
- - `automatic`(推荐):根据字幕语义自动选择少量镜头,用本地 HyperFrames + GSAP 重做,不需要安装 ShotCraft 或 Remotion;`balanced` 最多 3 个。
- - `gallery`:你在 ShotCraft 里挑好卡片名,再交给 Skill 适配。
- - `skip`:只使用基础 GSAP 语义配方,不加精选镜头层。
- 即使本机没装 ShotCraft,离线映射仍可给出 `reference-only` 建议,原生动效不会中断:
- ```bash
- python3 tools/shotcraft_catalog.py --semantic list --density balanced --json
- ```
- 初始化后,自动模式会在原生 `MOTION_PLAN.json` 通过基础检查后运行:
- ```bash
- python3 tools/shotcraft_default_plan.py <project-dir>/MOTION_PLAN.json --in-place
- python3 tools/motion_plan_check.py <project-dir>/MOTION_PLAN.json
- ```
- 它只匹配“字幕语义 + 原生 recipe_id”都一致的节点,会避开截图、演示、人脸和字幕安全区;数量上限不是完成指标,找不到合适节点时可以一个都不加。旧项目已有设计不会被升级过程自动改写。
- 只有你明确想浏览或核验上游卡片时,才需要自行安装外部仓库:
- ```bash
- git clone --depth 1 https://github.com/Vincentwei1021/video-shotcraft.git \
- ~/.naive-video/providers/video-shotcraft
- ```
- Skill 不会替你静默执行这条命令。默认把参考改写成 `gsap-adapted` 或 `hyperframes-custom`,预览和导出不依赖上游仓库。
- 复杂 `remotion-subclip` 只有明确同意后才使用。Skill 内置的是安装管理工具,不是打包好的 `node_modules`:
- ```bash
- # 只检查或看计划:不会写文件、不会联网
- python3 tools/remotion_runtime.py --project <project-dir> --check
- python3 tools/remotion_runtime.py --project <project-dir> --plan
- # 用户明确同意下载和许可证后,才执行项目内安装
- python3 tools/remotion_runtime.py --project <project-dir> --install --yes
- ```
- 运行时只写入该视频项目的 `runtime/remotion/`,不会污染全局 Node 环境。Remotion 子片段必须预渲染静音、保留原生 fallback、不能改变主音频时间轴;商业使用前还要单独查看 [Remotion License](https://www.remotion.dev/license)。
- 适配层只包含自行编写的语义映射和上游链接,不复制 ShotCraft 代码、音频、预览或模板。ShotCraft 本身使用 Apache-2.0;本仓库自有内容继续使用 MIT。
- ## 视觉质量与通用组件
- 公开版不会内置作者个人的颜色、字体或固定卡片系统。每个项目必须在 `DESIGN.md` 里明确字体、真实字重、字幕最大行数、换行策略、文本基线、组件类型和最长标签适配,再通过离线检查:
- ```bash
- python3 tools/design_check.py <project-dir>/DESIGN.md
- ```
- 通用组件包括:
- - `structured card`:解释、步骤和对比。
- - `glass notification`:短状态、提醒、确认和 CTA。
- - `focus-frame`:在稳定容器内切换关键词焦点。
- - `seekable-type`:由视频时间轴驱动的短文本输入效果。
- - `split-reveal`:卡片标题、步骤和警告的逐词或克制逐字入场。
- 这些组件只规定信息角色和质量门槛,不规定某个创作者的配色。GSAP 负责运动,字体、间距、对齐、表面和层级仍由设计契约负责。
- 网页组件里的 `setInterval`、随机打字速度、`IntersectionObserver` 和 `ScrollTrigger` 不会直接搬进视频。Skill 会把它们改成暂停、可 seek、任意时间点都能稳定复现的 GSAP timeline。
- 默认拒绝未经要求的手绘感箭头、粗糙框线、细体大字、倾斜正文、错位基线和无规则的单双行字幕切换。
- ## 项目状态与恢复
- 初始化后,项目中会出现:
- ```text
- .naive-video-state.json
- EDIT_PLAN.md
- DESIGN.md
- CONTENT_LOGIC.json # 口播逻辑组、语义节拍与时间精度
- STYLE_REFERENCE.md # 使用参考图时创建
- MOTION_PLAN.json # 使用语义动效时创建
- VIDEO_LESSONS.md
- VIDEO_RETRO.md
- edit/
- rough-cut.mp4 # 需要粗剪时才有
- rough-cut-edl.json # 可选剪切决策记录
- preview/
- final/
- qa/
- KEYFRAME_REVIEW.md # 静态关键帧审查记录
- ```
- 状态文件让新任务知道已经做到字幕、预览还是导出阶段。渲染中断时,Skill 会先检查进度和产物,不会无故推倒重来。
- ## 先关键帧,再动态预览
- 第一次使用、新风格或逻辑关系复杂时,Skill 会先生成一组代表性关键帧:开场、每个主要逻辑组的峰值、信息最密集画面、截图/演示/PiP、主要转场和结尾。关键帧先检查构图、字体、层级和遮挡;通过后才制作完整动态预览。静态通过不代表动效时间已经通过,动态预览仍然需要确认。
- 修改时推荐这样说:
- ```text
- 12.4-14.0 秒:右侧结果卡现在遮住截图正文,请缩小并移到左上安全区。
- 只改这一处,先给我受影响关键帧或前后各 3 秒短片段,其他已确认部分保持不变。
- ```
- Skill 会先修改最小责任层,再局部验证,不会因为一句“整体优化”把已经确认的画面全部重做。
- ## 自我迭代
- 当你明确说“这个风格以后都这样”或“以后不要再这样”,Skill 才会把规则写进项目的 `VIDEO_LESSONS.md`。成片交付后,内部复盘工作流会把成功项、失败根因和预防检查写入 `VIDEO_RETRO.md`,但不会擅自把推测变成长期偏好。
- 需要跨视频复用时,确认后的脱敏规则会保存到本机私有配置:
- ```text
- ~/.naive-video/profiles/default.json
- ```
- 新项目会检测并复用它;你也可以要求某个项目忽略旧风格。
- 长期规则带有稳定 ID、启用状态和确认时间;规则冲突时可以显式替代或停用旧规则。新项目会把当前启用规则导入自己的 `VIDEO_LESSONS.md`,所以“记住”会真正影响下一条视频。
- 反馈分三层:
- - 当前视频专用
- - 当前用户长期风格
- - 可脱敏的通用产品改进
- 个人路径、品牌名、截图、客户信息和素材内容不会自动回流到公开仓库。
- ## 隐私与发布检查
- ```bash
- bash scripts/doctor.sh --privacy-scan .
- python3 tools/validate_skill.py .
- bash tests/smoke.sh
- ```
- CI 会执行同样的无密钥检查。不要提交 `.env`、真实客户素材、转写缓存、渲染文件或本机绝对路径。
- ## 仓库结构
- ```text
- naive-video-skill/
- ├── SKILL.md # 总路由与硬规则
- ├── references/ # 状态、质量、视觉规则、精选镜头包及内部工作流
- ├── templates/ # 项目初始化模板
- ├── migrations/ # 状态 schema 迁移
- ├── tools/ # 无第三方依赖的检查与初始化工具
- ├── scripts/ # 安装、体检入口
- ├── tests/ # 干净环境冒烟测试
- └── agents/openai.yaml
- ```
- 仓库中只能存在根目录这一个 `SKILL.md`。CI 会检查这个约束,避免 WorkBuddy 等递归扫描器把内部工作流误装成多个技能。
- ## English Summary
- 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.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.