⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
hand-drawn-explainer-video-nikola
制作、修改和验收中文手绘知识讲解视频,交付配音、字幕、时间轴、可编辑工程和真实 MP4。支持两条不可混淆的制作路线:同一画布持续落墨的逐笔故事动画,以及用 SVG/HTML/GSAP 编排流程卡片、关系图和知识图形的程序动画。逐笔路线可选择自然肤色 Q 版人物、小黑风格或其他手绘风格,并可采用单场景、多幕故事、左右双语义岛等画面结构。用户说“边讲边画”“一笔一笔画出来”“白板手绘”“先画左边再画右边”“知识讲解动画”或希望把文稿、SRT、人物故事做成手绘视频时使用。也支持只输出生图/图生视频提示词。不用于写实数字人或假装已经完成无法验证的成片。
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Hand-drawn Explainer Video Nikola
作者 Nikola|联系与交流:X / Twitter @Nikola314159
一个面向中文知识讲解的 Codex Skill:把主题、文稿或 SRT 制作成“讲一部分、画一部分”的手绘视频,并交付真实 MP4、字幕、时间轴和可编辑素材。
这应该是目前手绘漫画效果最好的skills仓库了,我参考了许多大佬的方法,尝试了多次完成,TOKEN都要给我整完了。希望各位朋友喜欢,有问题直接推特留言或者提pr吧,未来也会持续维护这个仓库,并更新更多的功能。
过程示例:

它能做什么
本 Skill 只有两条制作路线。画面结构与视觉风格是逐笔路线中的可组合选项,不是额外路线:
制作路线
├─ 逐笔故事动画
│ ├─ 画面结构:单场景 / 多幕故事 / 左右双语义岛
│ └─ 视觉风格:Q版人物 / 小黑风格 / 其他手绘风格
└─ 程序动画
├─ HTML / SVG / GSAP
└─ 流程卡片 / 关系图 / 精确文字 / 知识图形
“左右双语义岛”是逐笔故事动画的一种画面组织方法:先画左边、讲完一部分,再画右边,并保留前面的内容。也可以使用单场景或多幕连续故事。Q 版人物与小黑风格是视觉风格:前者适合乔布斯传记、历史人物等,后者适合抽象观点、方法论和隐喻;两者都能使用双语义岛,也都能使用其他画面结构。
除此之外,本 Skill 也能只输出 Flow、Nano Banana 或其他图像/视频模型的自包含提示词;这是交付范围,不是第三条制作路线。
这个仓库不把“手绘风静图平移”冒充逐笔绘制。逐笔路线使用内置的 MIT 后端,并在最终交付前检查真实视频、音轨、字幕、场景边界和末帧。
路线怎么选
| 你说的话 | 默认路线 |
|---|---|
| “边讲边画”“一笔一笔画出来”“笔尖跟着线走” | 逐笔故事 |
| “先画左边,再画右边,过程中写关键词” | 逐笔故事 + 左右双语义岛画面结构 |
| “小黑、怪诞、白底、少量彩色批注” | 逐笔故事 + 小黑视觉风格 |
| “流程卡片、关系图、精确标签、独立元素运动” | 程序动画 |
| “只给我生图/图生视频提示词” | 提示词模式 |
完整风格说明见 docs/STYLES.md。
案例
《约法三章》:16:9 多幕逐笔故事动画


这是最终采用的优秀版本:七幅连续故事画面,每幕从空白纸张开始逐笔落墨,每幅只承载一个完整事件。旧的 9:16 单画布样片存在人物、道具和环境线条互相干扰的问题,因此不作为仓库推荐案例。
乔布斯的一生:自然肤色 Q 版人物 + 双语义岛


“什么是 Skill”:程序动画

这个案例展示流程卡片、人物动作、字幕和真实旁白时间轴。出于第三方许可考虑,GSAP 浏览器文件不直接提交,由 npm install 获取。
《商用Skills_完整手绘视频》是程序化知识图形路线的完整生产案例:44 个场景中的人物、卡片、箭头、放大镜、字幕条等均作为独立 HTML/SVG 元素编排,再由 GSAP/HyperFrames 按真实旁白时间轴驱动。仓库中的 36 秒工程是便于下载和学习的精简公开示例,不包含那条 7 分 29 秒完整成片。
它与“边说边画”不是同一种实现:
| 对比项 | 程序化知识图形 | 逐笔“边说边画” |
|---|---|---|
| 画面如何出现 | 独立卡片、人物、箭头和文字按时间移动、缩放、切换或描边 | 同一画布按语义区域持续落墨,先线稿后补色,已画内容保留 |
| 核心技术 | HTML/SVG + GSAP + HyperFrames | 位图线稿提取 + skeleton/stream 连续笔迹 + 分区遮罩 |
| 最适合 | 流程、规则、关系、对比、精确文字 | 人物故事、历史叙事、白板讲解、一幅画逐步完成 |
| 不可混称 | 手绘风元素动画不等于真实逐笔绘制 | 不能用整图淡入、卡片飞入或 SVG 运动冒充落墨 |
配音默认
成片默认使用火山引擎语音合成的刘飞音色 zh_male_liufei_uranus_bigtts,资源模型为 seed-tts-2.0。用户明确指定时,可以改用火山引擎中的其他已授权音色;已有与文稿一致、质量合格的旁白则优先复用。
在火山引擎控制台进入“开通管理”,开通豆包语音的“语音合成 2.0”服务:

不建议把电脑系统朗读、edge-tts 或其他低质量本地文本转语音自动当作成片替代方案,它们与已验证的刘飞听感差异明显。若当前环境没有火山引擎授权或用户提供的合格音轨,应保留已完成的画面、字幕与时间轴并说明配音缺口,不应静默换成系统声音后宣称完成。详见 配音与声音对齐。
安装
最简单的方式是让 Codex 安装此仓库,或手动克隆:
git clone https://github.com/hi-nikola/hand-drawn-explainer-video-nikola.git "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola"
python "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola/scripts/setup_check.py"
提示词模式到这里即可使用。运行脚本需要 Python 3.10+;Windows 若默认 python 较旧,请改用 py -3.12 或已确认的新版本解释器。逐笔视频首次使用还需:
cd "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola"
python vendor/srt-whiteboard-animation/scripts/prepare_env.py
python scripts/stroke_story_preflight.py --report preflight-stroke-story.json
完整 MP4 需要 FFmpeg/FFprobe;程序动画需要 Node.js、浏览器和 HyperFrames。详见 安装、配置 和 排错。
逐笔核心渲染不需要下载本地神经网络小模型或模型权重,也不要求 GPU;已有合格源图/线稿和旁白时,可以使用本地传统图像算法完成。首次安装 Python/npm 依赖需要联网,从文稿生成新插画或新合成刘飞配音则需要相应外部服务。
直接可用的触发提示词
使用 $hand-drawn-explainer-video-nikola,把下面内容做成 45 秒中文手绘讲解视频。讲一部分画一部分,先画左边再画右边,重要结论用准确关键词后期写出;使用自然肤色 Q 版人物,先做代表镜头验证,再交付真实 MP4、SRT、时间轴和可编辑素材。
使用 $hand-drawn-explainer-video-nikola,用小黑风格解释这个方法:纯白背景、稀疏黑线、少量红橙蓝批注。要真实逐笔落墨,不要只做静图缩放;字幕和关键词必须准确。
使用 $hand-drawn-explainer-video-nikola,把这段内容做成手绘风流程卡片动画。使用可编辑 SVG/HTML,所有标题、数字和箭头关系必须确定性生成,并验证最终 MP4。
目录
SKILL.md:触发说明与总工作流;references/:逐笔、双语义岛、程序动画、声音和质量规范;scripts/:预检、配音辅助、最终合成和验证;vendor/srt-whiteboard-animation/:带来源说明的 MIT 逐笔运行时,不含第二个 Skill;examples/:公开样片、源图和可编辑工程;docs/:安装、配置、架构、风格和排错。
安全与费用
仓库不含 API Key、Token、Cookie、个人绝对路径或私有模型。云配音、生图和视频服务都是可选能力,可能收费;请先 Dry Run、复用内容匹配的缓存,并避免在结果未知时盲目重试。漏洞和凭据泄露报告见 SECURITY.md。
许可
Skill、原创脚本与文档使用 Apache License 2.0。vendor/srt-whiteboard-animation/ 保留上游 MIT 许可。示例媒体按 CC BY 4.0 媒体说明 提供(仅限作者有权许可的部分)。第三方软件、人物姓名、产品名和商标不因此获得再许可,详见 THIRD_PARTY_NOTICES.md。
欢迎阅读 CONTRIBUTING.md 后提交新的风格预设、回归用例或渲染改进。
致谢
感谢以下开源项目及其作者分享思路、代码和可复用经验;本仓库只在各自许可与说明范围内借鉴或使用,具体代码来源边界见 第三方说明。
- kaomei/hand-drawn-video-prompts:中文口播分镜、Q 版蜡笔视觉规范与提示词工作流;
- geeklee/srt-whiteboard-animation:SRT 语义分区、持续画布与 stream 连续笔迹;
- gnipbao/story-to-handdrawn-video:故事到手绘漫画、线稿/彩图配合与风格组织;
- ChenShuo2004/cs-board:完整白板视频工作台、骨架笔迹与生产流程方面的实践;
- heygen-com/hyperframes-launches:HyperFrames 程序动画的镜头与合成范例;
- Vincentwei1021/video-shotcraft:可复用镜头结构与程序化视频编排思路。
- helloianneo/ian-xiaohei-illustrations:感谢 Ian 开源“小黑”视觉 IP 与配图 Skill;本仓库的小黑风格借鉴了其黑色实心小角色、白点眼、纯白手绘、大量留白和少量红橙蓝批注的视觉语言。
向每一位愿意公开工具、案例和踩坑经验的创作者表示感谢。
// HOW IT'S BUILT
// FILES
74 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
SKILL.md7.6 KBce9e99ad50adupstream ↗
--- name: hand-drawn-explainer-video-nikola description: 制作、修改和验收中文手绘知识讲解视频,交付配音、字幕、时间轴、可编辑工程和真实 MP4。支持两条不可混淆的制作路线:同一画布持续落墨的逐笔故事动画,以及用 SVG/HTML/GSAP 编排流程卡片、关系图和知识图形的程序动画。逐笔路线可选择自然肤色 Q 版人物、小黑风格或其他手绘风格,并可采用单场景、多幕故事、左右双语义岛等画面结构。用户说“边讲边画”“一笔一笔画出来”“白板手绘”“先画左边再画右边”“知识讲解动画”或希望把文稿、SRT、人物故事做成手绘视频时使用。也支持只输出生图/图生视频提示词。不用于写实数字人或假装已经完成无法验证的成片。 --- # Nikola 手绘讲解视频 把中文主题、文稿或 SRT 变成真正可播放、可检查、可继续编辑的手绘讲解视频。先识别用户要的是“画面被逐笔画出来”,还是“手绘风独立元素运动”;不能为了方便把一种效果冒充另一种效果。 提示词模式无本地依赖;逐笔渲染器已随仓库打包,首次使用需创建隔离 Python 环境;程序动画模式需 Node.js、HyperFrames、浏览器和 FFmpeg。成片配音默认使用火山引擎刘飞音色,需用户自己的已授权账号或复用已有音轨;图像生成和视频模型为可选能力,可能产生费用。 ## 先选择交付范围 - **只要提示词**:读 [prompt-workflow.md](references/prompt-workflow.md),输出自包含提示词,不调用收费接口。 - **样片**:制作用户指定片段;未指定时用 10–15 秒代表镜头验证人物、笔迹、字幕和节奏。 - **完整视频**:先读 [安装与预检](references/preflight-and-recovery.md) 和 [完整流程](references/automation-workflow.md)。先内部验证代表镜头,再继续全片;只有用户要求逐步确认或存在关键选择时才暂停。 - **修改已有视频**:保留未被要求修改的音轨、时间轴和素材,只重做受影响阶段。 ## 先选两条制作路线之一 | 用户真正想要的效果 | 制作路线 | 必读 | |---|---|---| | “画面被画出来”“边讲边画”“逐笔落墨”“笔尖跟着线走” | 逐笔故事动画 | [stroke-story-workflow.md](references/stroke-story-workflow.md) | | 流程卡片、概念关系、独立元素组合、确定性文字 | 程序动画 | HyperFrames + SVG/HTML + GSAP,读 [automation-workflow.md](references/automation-workflow.md) | 逐笔故事动画选定后,再分别选择画面结构与视觉风格: - **画面结构**:单场景、多幕连续故事,或“先左后右并保留前文”的左右双语义岛。双语义岛只是逐笔故事的一种画面组织方法,参考 [semantic-island-storytelling.md](references/semantic-island-storytelling.md)。 - **视觉风格**:自然肤色 Q 版人物、小黑风格,或用户指定的其他手绘风格。Q 版适合人物传记与历史;小黑适合抽象观点、方法论和隐喻。两种风格都能采用双语义岛,也都能采用其他画面结构。 场景视频与“只输出 Flow/Nano Banana 提示词”是可选交付方式,不是本 Skill 的第三条手绘制作路线。自然连续人物动作或复杂运镜需要先核实视频模型、成本和一致性限制;只要提示词时读 [prompt-workflow.md](references/prompt-workflow.md)。 逐笔路线使用 `vendor/srt-whiteboard-animation/` 中随仓库发布的 MIT 后端快照。它不包含第二份 `SKILL.md`,不会单独触发或要求重复确认;主 Skill 统一负责路由、配音、字幕、渲染和验收。运行环境不可用时保存已完成资产并报告缺口;除非用户明确同意,不以 SVG 动画冒充真实逐笔绘制。 ## 可选视觉风格 - **Q 版人物故事**:自然肤色、人物身体、年龄和服装锚点清楚,适合传记、历史和人物观点。参考 [q-human-story-style.md](references/q-human-story-style.md) 与 [乔布斯案例](examples/stroke-story/steve-jobs/README.md)。 - **小黑风格**:纯白、稀疏黑线、少量红橙蓝、留白和冷幽默动作主体,适合方法、系统、状态和隐喻。它是本仓库内置、可直接点选的公开预设;使用时必须读取 [完整视觉 DNA、来源说明与提示词骨架](references/xiaohei-style.md)。该风格借鉴 Ian 的开源项目,应始终称为“小黑风格”。 程序化知识图形是制作路线,不是视觉风格。参考 [“什么是 Skill”程序动画案例](examples/program-animation/skill-demo/README.md)。逐笔案例见 [《约法三章》](examples/stroke-story/yuefa-sanzhang/README.md) 与 [《乔布斯的一生》](examples/stroke-story/steve-jobs/README.md)。 参考图只影响当前项目,除非用户明确要求保存为新预设。人物、画风、动效和声音分别记录,不把换画风等同于换音色或重做旁白。 ## 公开默认与本地配置 仓库中的 [preferences.json](preferences.json) 只含无密钥默认值。用户指令和项目 `DESIGN.md` 优先。成片默认使用火山引擎 `seed-tts-2.0` 的刘飞音色 `zh_male_liufei_uranus_bigtts`;用户明确要求时可选择火山引擎其他已授权音色,已有与文稿一致的合格音轨优先复用。不要自动改用电脑系统朗读、edge-tts 或其他低质量本地 TTS;缺少授权音轨时可以继续提示词、画面和无配音阶段,但必须把配音列为未完成项。 首次使用先读 [安装说明](docs/INSTALL.md) 和 [配置说明](docs/CONFIGURATION.md),再运行: ```text python scripts/setup_check.py ``` 完整视频在首次配音或长渲染前还要运行路线对应的预检。预检失败只阻止依赖该能力的阶段,不重做已经通过的音频、插画或字幕。 ## 核心制作规则 1. **保留内容**:分别保存原稿、合成读音稿和字幕;未经授权不删观点、数字和限定词。 2. **声音先行**:优先复用内容一致的完整音轨;新音轨尽量整段或按自然章节合成。 3. **时间来自真实音频**:使用有效时间戳、强制对齐或复核后的句级停顿;不能把平均分配说成逐字对齐。 4. **动画服务于解释**:逐笔路线按语义区域持续落墨;程序路线拆成可控元素。整图平移、缩放或淡入淡出只能辅助。 5. **控制可画性**:真实笔迹速度取决于区域时间和源图复杂度;`hand-follow` 只平滑手部,不能让线条真正减速。 6. **精确文字后期生成**:日期、专名、Logo、长中文和关键数字使用字幕或确定性文字层,不交给图片模型猜写。 7. **先验证代表镜头**:检查人物一致性、抬笔、补色、遮挡、关键词和字幕,再批量渲染。 8. **成片必须真实验收**:完整解码 MP4,检查全部场景、语义边界、切点、音轨和最后 0.3–0.5 秒。 ## 安全、费用和准确性 - 不把 API Key、Token、Cookie、请求头、本机绝对路径或私有模型目录写入仓库、命令参数、报告或工程 ZIP。 - 账号型配音、生图和视频服务可能收费;先复用缓存,不盲目重试状态不明的请求。 - 真实人物、公司、Logo、日期和数字需要可靠来源或确定性资产。风格参考不能保证实体准确。 - 用户要求完整视频时,最少交付真实 MP4;工具支持时同时保留 SRT、旁白、时间轴、源图、标注和可编辑工程。 质量与交付细节见 [quality-and-delivery.md](references/quality-and-delivery.md)。仓库结构、贡献和许可见 [README](README.md)。examples/program-animation/skill-demo/README.md1.1 KBd9c2d4887444upstream ↗
# “什么是 Skill”:程序动画示例 36 秒可编辑 HTML/SVG/HyperFrames 工程,展示八个镜头、整段旁白、时间轴和确定性文字。它适合流程、关系和独立元素运动,不是逐笔故事路线。  [观看 14 秒 MP4 样片](what-is-skill-sample.mp4)。样片中的人物、气泡、流程节点、箭头和文字都是独立 SVG/HTML 元素,由 GSAP/HyperFrames 按真实旁白时间轴驱动;它没有假装成“同一幅画被逐笔画出来”。 ```powershell npm install npm run check npm run dev npm run render ``` `npm install` 安装固定版本的 GSAP;生命周期脚本从 npm 包复制浏览器文件到 `assets/gsap.min.js`。该生成文件不提交到仓库,许可遵循 GSAP 自身条款。HyperFrames 由命令按固定版本调用。 旁白只作案例资产。新项目优先复用用户提供的合格音轨;需要新合成时默认使用火山引擎刘飞 `zh_male_liufei_uranus_bigtts`,用户明确指定时可改用其他火山音色。不要把案例文件本身或电脑系统朗读当成所有项目的正式旁白。examples/stroke-story/steve-jobs/README.md981 B1780a8011052upstream ↗
# 乔布斯的一生:逐笔双语义岛案例 这是风格和工程结构示例,不是对人物或品牌的官方呈现,也不暗示 Steve Jobs、Apple、Pixar 或其权利人认可本项目。 文件: - `source.png`:自然肤色 Q 版人物、低线条密度、无长文字的批准源图; - `annotation.json`:左右语义区、顺序和绘制窗口; - `regions-preview.png`:区域框和叙事顺序预览; - `semantic-island-sample.mp4`:约 8.9 秒代表镜头; - `steve-jobs-biography.mp4`:约 57 秒完整样片; - `transition-contact.jpg`:边界联系表,用于检查前一区保留与后一区起笔。 人物必须是自然肤色、完整人形并随年龄改变;“小黑风格”只影响线条、留白和批注语言,不能把真实人物画成黑脸小怪物。专名和关键词使用后期确定性文字层。 公开包只保留代表性的源图和视频,没有包含云服务凭据、原始请求记录或本机路径。examples/stroke-story/yuefa-sanzhang/README.md2.3 KB8dfbdd31b441upstream ↗
# 《约法三章》:16:9 多幕逐笔故事动画案例 这是最终采用的 38.5 秒横屏版本,1920×1080、30fps。它把完整口播拆成七幅连续历史故事画面,每幕从空白纸张开始,以 `skeleton` 连续落墨并完成彩色补全,完成后短暂停留,再自然切换到下一幕。   - [观看 38.5 秒手速平滑版 MP4](yuefa-sanzhang-16x9-stroke-story.mp4) - [下载可编辑工程包](editable-project.zip):包含七张彩色源图、逐幕标注、刘飞旁白、字幕、确定性文字层、时间轴和渲染文件; - `timeline.json`:七幕真实旁白时间轴; - `verification.json`:视频解码、音频、字幕和逐幕运动检查; - `seven-scenes-final-frames.jpg`:七幕最终画面检查; - `hand-speed-contact-sheet.jpg`:落墨过程与手部移动检查。 七幕依次为:刘邦攻入咸阳、百姓忧惧、召集关中父老、宣布三条约法、废除秦朝苛法、秦人慰劳汉军、赢得关中民心。音轨复用已确认的火山引擎刘飞配音 `zh_male_liufei_uranus_bigtts`。成片实际解码 1155 帧,自动检查无错误、无警告。 ## 为什么不用旧竖屏样片 旧的 9:16 单幅画布把复杂历史群像、人物、道具和环境压在同一画面,容易出现画面元素互相干扰与跨区域串线。最终版不再强制四宫格或贴纸式语义岛,而采用“多幕连续故事”:每幅只承担一个完整事件,人物和环境可以在本幕自然接触,并从幕与幕的边界消除干扰。 这说明“逐笔故事动画”不等于必须使用左右双语义岛。复杂历史故事在用户未限定竖屏时,应优先考虑 16:9 多幕结构。手速平滑版使用 `--hand-follow 0.35` 缓动手部追随,但不改变旁白、笔迹或场景时长。 这里的“逐笔”指程序化骨架追踪与轮廓感知上色,并非声称逐笔复刻真人的自然笔顺。它与 SVG 卡片移动、整图淡入或镜头缩放不同。 工程包用于复现案例,不代表新项目必须复制同一故事、时长或人物。解压后先按仓库安装文档创建逐笔隔离环境;其中路径应按本机位置重新选择,不要沿用其他电脑的绝对路径。README.md11 KB3fe88aec3fe4upstream ↗
# Hand-drawn Explainer Video Nikola 作者 Nikola|联系与交流:[X / Twitter @Nikola314159](https://x.com/Nikola314159) 一个面向中文知识讲解的 Codex Skill:把主题、文稿或 SRT 制作成“讲一部分、画一部分”的手绘视频,并交付真实 MP4、字幕、时间轴和可编辑素材。 这应该是目前手绘漫画效果最好的skills仓库了,我参考了许多大佬的方法,尝试了多次完成,TOKEN都要给我整完了。希望各位朋友喜欢,有问题直接推特留言或者提pr吧,未来也会持续维护这个仓库,并更新更多的功能。 过程示例:  ## 它能做什么 本 Skill 只有两条制作路线。画面结构与视觉风格是逐笔路线中的可组合选项,不是额外路线: ```text 制作路线 ├─ 逐笔故事动画 │ ├─ 画面结构:单场景 / 多幕故事 / 左右双语义岛 │ └─ 视觉风格:Q版人物 / 小黑风格 / 其他手绘风格 └─ 程序动画 ├─ HTML / SVG / GSAP └─ 流程卡片 / 关系图 / 精确文字 / 知识图形 ``` “左右双语义岛”是逐笔故事动画的一种画面组织方法:先画左边、讲完一部分,再画右边,并保留前面的内容。也可以使用单场景或多幕连续故事。Q 版人物与小黑风格是视觉风格:前者适合乔布斯传记、历史人物等,后者适合抽象观点、方法论和隐喻;两者都能使用双语义岛,也都能使用其他画面结构。 除此之外,本 Skill 也能只输出 Flow、Nano Banana 或其他图像/视频模型的自包含提示词;这是交付范围,不是第三条制作路线。 这个仓库不把“手绘风静图平移”冒充逐笔绘制。逐笔路线使用内置的 MIT 后端,并在最终交付前检查真实视频、音轨、字幕、场景边界和末帧。 ## 路线怎么选 | 你说的话 | 默认路线 | |---|---| | “边讲边画”“一笔一笔画出来”“笔尖跟着线走” | 逐笔故事 | | “先画左边,再画右边,过程中写关键词” | 逐笔故事 + 左右双语义岛画面结构 | | “小黑、怪诞、白底、少量彩色批注” | 逐笔故事 + 小黑视觉风格 | | “流程卡片、关系图、精确标签、独立元素运动” | 程序动画 | | “只给我生图/图生视频提示词” | 提示词模式 | 完整风格说明见 [docs/STYLES.md](docs/STYLES.md)。 ## 案例 ### 《约法三章》:16:9 多幕逐笔故事动画   - [38.5 秒 16:9 手速平滑版 MP4](examples/stroke-story/yuefa-sanzhang/yuefa-sanzhang-16x9-stroke-story.mp4) - [可编辑工程包](examples/stroke-story/yuefa-sanzhang/editable-project.zip) - [七幕结构、时间轴与验证说明](examples/stroke-story/yuefa-sanzhang/README.md) 这是最终采用的优秀版本:七幅连续故事画面,每幕从空白纸张开始逐笔落墨,每幅只承载一个完整事件。旧的 9:16 单画布样片存在人物、道具和环境线条互相干扰的问题,因此不作为仓库推荐案例。 ### 乔布斯的一生:自然肤色 Q 版人物 + 双语义岛   - [完整 57 秒样片](examples/stroke-story/steve-jobs/steve-jobs-biography.mp4) - [8.9 秒双岛代表镜头](examples/stroke-story/steve-jobs/semantic-island-sample.mp4) - [源图、区域与时间说明](examples/stroke-story/steve-jobs/README.md) ### “什么是 Skill”:程序动画  - [14 秒真实 MP4 样片](examples/program-animation/skill-demo/what-is-skill-sample.mp4) - [可编辑 HTML/SVG/HyperFrames 工程与说明](examples/program-animation/skill-demo/README.md) 这个案例展示流程卡片、人物动作、字幕和真实旁白时间轴。出于第三方许可考虑,GSAP 浏览器文件不直接提交,由 `npm install` 获取。 《商用Skills_完整手绘视频》是程序化知识图形路线的完整生产案例:44 个场景中的人物、卡片、箭头、放大镜、字幕条等均作为独立 HTML/SVG 元素编排,再由 GSAP/HyperFrames 按真实旁白时间轴驱动。仓库中的 36 秒工程是便于下载和学习的精简公开示例,不包含那条 7 分 29 秒完整成片。 它与“边说边画”不是同一种实现: | 对比项 | 程序化知识图形 | 逐笔“边说边画” | |---|---|---| | 画面如何出现 | 独立卡片、人物、箭头和文字按时间移动、缩放、切换或描边 | 同一画布按语义区域持续落墨,先线稿后补色,已画内容保留 | | 核心技术 | HTML/SVG + GSAP + HyperFrames | 位图线稿提取 + skeleton/stream 连续笔迹 + 分区遮罩 | | 最适合 | 流程、规则、关系、对比、精确文字 | 人物故事、历史叙事、白板讲解、一幅画逐步完成 | | 不可混称 | 手绘风元素动画不等于真实逐笔绘制 | 不能用整图淡入、卡片飞入或 SVG 运动冒充落墨 | ## 配音默认 成片默认使用火山引擎语音合成的刘飞音色 `zh_male_liufei_uranus_bigtts`,资源模型为 `seed-tts-2.0`。用户明确指定时,可以改用火山引擎中的其他已授权音色;已有与文稿一致、质量合格的旁白则优先复用。 在火山引擎控制台进入“开通管理”,开通豆包语音的“语音合成 2.0”服务:  不建议把电脑系统朗读、edge-tts 或其他低质量本地文本转语音自动当作成片替代方案,它们与已验证的刘飞听感差异明显。若当前环境没有火山引擎授权或用户提供的合格音轨,应保留已完成的画面、字幕与时间轴并说明配音缺口,不应静默换成系统声音后宣称完成。详见 [配音与声音对齐](references/voiceover.md)。 ## 安装 最简单的方式是让 Codex 安装此仓库,或手动克隆: ```powershell git clone https://github.com/hi-nikola/hand-drawn-explainer-video-nikola.git "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola" python "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola/scripts/setup_check.py" ``` 提示词模式到这里即可使用。运行脚本需要 Python 3.10+;Windows 若默认 `python` 较旧,请改用 `py -3.12` 或已确认的新版本解释器。逐笔视频首次使用还需: ```powershell cd "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola" python vendor/srt-whiteboard-animation/scripts/prepare_env.py python scripts/stroke_story_preflight.py --report preflight-stroke-story.json ``` 完整 MP4 需要 FFmpeg/FFprobe;程序动画需要 Node.js、浏览器和 HyperFrames。详见 [安装](docs/INSTALL.md)、[配置](docs/CONFIGURATION.md) 和 [排错](docs/TROUBLESHOOTING.md)。 逐笔核心渲染不需要下载本地神经网络小模型或模型权重,也不要求 GPU;已有合格源图/线稿和旁白时,可以使用本地传统图像算法完成。首次安装 Python/npm 依赖需要联网,从文稿生成新插画或新合成刘飞配音则需要相应外部服务。 ## 直接可用的触发提示词 ```text 使用 $hand-drawn-explainer-video-nikola,把下面内容做成 45 秒中文手绘讲解视频。讲一部分画一部分,先画左边再画右边,重要结论用准确关键词后期写出;使用自然肤色 Q 版人物,先做代表镜头验证,再交付真实 MP4、SRT、时间轴和可编辑素材。 ``` ```text 使用 $hand-drawn-explainer-video-nikola,用小黑风格解释这个方法:纯白背景、稀疏黑线、少量红橙蓝批注。要真实逐笔落墨,不要只做静图缩放;字幕和关键词必须准确。 ``` ```text 使用 $hand-drawn-explainer-video-nikola,把这段内容做成手绘风流程卡片动画。使用可编辑 SVG/HTML,所有标题、数字和箭头关系必须确定性生成,并验证最终 MP4。 ``` ## 目录 - `SKILL.md`:触发说明与总工作流; - `references/`:逐笔、双语义岛、程序动画、声音和质量规范; - `scripts/`:预检、配音辅助、最终合成和验证; - `vendor/srt-whiteboard-animation/`:带来源说明的 MIT 逐笔运行时,不含第二个 Skill; - `examples/`:公开样片、源图和可编辑工程; - `docs/`:安装、配置、架构、风格和排错。 ## 安全与费用 仓库不含 API Key、Token、Cookie、个人绝对路径或私有模型。云配音、生图和视频服务都是可选能力,可能收费;请先 Dry Run、复用内容匹配的缓存,并避免在结果未知时盲目重试。漏洞和凭据泄露报告见 [SECURITY.md](SECURITY.md)。 ## 许可 Skill、原创脚本与文档使用 [Apache License 2.0](LICENSE)。`vendor/srt-whiteboard-animation/` 保留上游 MIT 许可。示例媒体按 [CC BY 4.0 媒体说明](LICENSE-MEDIA.md) 提供(仅限作者有权许可的部分)。第三方软件、人物姓名、产品名和商标不因此获得再许可,详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 欢迎阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 后提交新的风格预设、回归用例或渲染改进。 ## 致谢 感谢以下开源项目及其作者分享思路、代码和可复用经验;本仓库只在各自许可与说明范围内借鉴或使用,具体代码来源边界见 [第三方说明](THIRD_PARTY_NOTICES.md)。 - [kaomei/hand-drawn-video-prompts](https://github.com/kaomei/hand-drawn-video-prompts):中文口播分镜、Q 版蜡笔视觉规范与提示词工作流; - [geeklee/srt-whiteboard-animation](https://github.com/geeklee/srt-whiteboard-animation):SRT 语义分区、持续画布与 stream 连续笔迹; - [gnipbao/story-to-handdrawn-video](https://github.com/gnipbao/story-to-handdrawn-video):故事到手绘漫画、线稿/彩图配合与风格组织; - [ChenShuo2004/cs-board](https://github.com/ChenShuo2004/cs-board):完整白板视频工作台、骨架笔迹与生产流程方面的实践; - [heygen-com/hyperframes-launches](https://github.com/heygen-com/hyperframes-launches):HyperFrames 程序动画的镜头与合成范例; - [Vincentwei1021/video-shotcraft](https://github.com/Vincentwei1021/video-shotcraft):可复用镜头结构与程序化视频编排思路。 - [helloianneo/ian-xiaohei-illustrations](https://github.com/helloianneo/ian-xiaohei-illustrations):感谢 Ian 开源“小黑”视觉 IP 与配图 Skill;本仓库的小黑风格借鉴了其黑色实心小角色、白点眼、纯白手绘、大量留白和少量红橙蓝批注的视觉语言。 向每一位愿意公开工具、案例和踩坑经验的创作者表示感谢。scripts/animation-map.mjs20 KBfb31e635eef0upstream ↗
#!/usr/bin/env node // animation-map.mjs — HyperFrames animation map for agents // // Reads every GSAP timeline registered in window.__timelines, enumerates // tweens, samples bboxes at N points per tween, computes flags and // human-readable summaries. Outputs a single animation-map.json. // // Usage: // node scripts/animation-map.mjs <composition-dir> --cli <entry.mjs> --browser <chrome> \ // [--frames N] [--out <dir>] [--min-duration S] [--width W] [--height H] [--fps N] import { mkdir, writeFile } from "node:fs/promises"; import { resolve, join } from "node:path"; // Compatibility wrapper for inline HTML/SVG/GSAP projects only. // The inspection logic below is from the installed HyperFrames Skill helper. import {createRequire} from 'node:module'; import {pathToFileURL} from 'node:url'; import {readFile,access} from 'node:fs/promises'; async function createFileServer({projectDir}) { if(!args.cli||!args.browser)throw Error('Supply --cli <JS entrypoint> and --browser <executable>.'); await access(resolve(args.cli));await access(resolve(args.browser)); const file=join(projectDir,'index.html');const source=await readFile(file,'utf8'); if(/data-composition-src|<video[\s>]/i.test(source))throw Error('Inline adapter does not support sub-compositions/video; use official CLI inspection.'); return {url:pathToFileURL(file).href,close(){}}; } async function createCaptureSession(url,out,config) { const req=createRequire(resolve(args.cli)); const {default:puppeteer}=await import(pathToFileURL(req.resolve('puppeteer-core')).href); const browser=await puppeteer.launch({executablePath:resolve(args.browser),headless:true,args:['--disable-gpu']}); const page=await browser.newPage();await page.setViewport({width:config.width,height:config.height}); return {browser,page,url}; } async function initializeSession(s){await s.page.goto(s.url);await s.page.evaluate(()=>document.fonts.ready);} async function closeCaptureSession(s){await s.browser.close();} async function getCompositionDuration(s){return s.page.evaluate(()=>Number(document.querySelector('[data-composition-id]').dataset.duration));} // ─── CLI ───────────────────────────────────────────────────────────────────── const args = parseArgs(process.argv.slice(2)); if (!args.composition) die("missing <composition-dir>"); const FRAMES = Number(args.frames ?? 6); const OUT_DIR = resolve(args.out ?? ".hyperframes/anim-map"); const MIN_DUR = Number(args["min-duration"] ?? 0.15); const WIDTH = Number(args.width ?? 1080); const HEIGHT = Number(args.height ?? 1920); const FPS = Number(args.fps ?? 30); const COMP_DIR = resolve(args.composition); await mkdir(OUT_DIR, { recursive: true }); // ─── Main ──────────────────────────────────────────────────────────────────── const server = await createFileServer({ projectDir: COMP_DIR, port: 0 }); const session = await createCaptureSession( server.url, OUT_DIR, { width: WIDTH, height: HEIGHT, fps: FPS, format: "png" }, null, ); try { await initializeSession(session); const duration = await getCompositionDuration(session); const tweens = await enumerateTweens(session); if (!Number.isFinite(duration) || duration <= 0 || !tweens.length) { throw Error('Missing duration or registered GSAP tweens; use official CLI inspection.'); } const kept = tweens.filter((tw) => tw.end - tw.start >= MIN_DUR); const report = { composition: COMP_DIR, duration, totalTweens: tweens.length, mappedTweens: kept.length, skippedMicroTweens: tweens.length - kept.length, tweens: [], }; for (let i = 0; i < kept.length; i++) { const tw = kept[i]; const times = Array.from( { length: FRAMES }, (_, k) => +(tw.start + ((k + 0.5) / FRAMES) * (tw.end - tw.start)).toFixed(3), ); const bboxes = []; for (const t of times) { await seekTo(session, t); const bbox = await measureTarget(session, tw.selectorHint); bboxes.push({ t, ...bbox }); } const animProps = tw.props.filter( (p) => !["parent", "overwrite", "immediateRender", "startAt", "runBackwards"].includes(p), ); const flags = computeFlags(tw, bboxes, { width: WIDTH, height: HEIGHT }); const summary = describeTween(tw, animProps, bboxes, flags); report.tweens.push({ index: i + 1, selector: tw.selectorHint, targets: tw.targetCount, props: animProps, start: +tw.start.toFixed(3), end: +tw.end.toFixed(3), duration: +(tw.end - tw.start).toFixed(3), ease: tw.ease, bboxes, flags, summary, }); } markCollisions(report.tweens); for (const tw of report.tweens) { if (tw.flags.includes("collision") && !tw.summary.includes("collision")) { tw.summary += " Overlaps another animated element."; } } // ── Composition-level analysis ── report.choreography = buildTimeline(report.tweens, duration); report.density = computeDensity(report.tweens, duration); report.staggers = detectStaggers(report.tweens); report.elements = buildElementLifecycles(report.tweens); report.deadZones = findDeadZones(report.density, duration); report.snapshots = await captureSnapshots(session, report.tweens, duration); await writeFile(join(OUT_DIR, "animation-map.json"), JSON.stringify(report, null, 2)); printSummary(report); } finally { await closeCaptureSession(session).catch(() => {}); server.close(); } // ─── Seek helper ──────────────────────────────────────────────────────────── async function seekTo(session, t) { await session.page.evaluate((time) => { if (window.__hf && typeof window.__hf.seek === "function") { window.__hf.seek(time); return; } const tls = window.__timelines; if (tls) { for (const tl of Object.values(tls)) { if (typeof tl.seek === "function") tl.seek(time); } } }, t); await new Promise((r) => setTimeout(r, 100)); } // ─── Timeline introspection ────────────────────────────────────────────────── async function enumerateTweens(session) { return await session.page.evaluate(() => { const results = []; const registry = window.__timelines || {}; const selectorOf = (el) => { if (!el || !(el instanceof Element)) return null; if (el.id) return `#${el.id}`; const cls = [...el.classList].slice(0, 2).join("."); return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase(); }; const walk = (node, parentOffset = 0) => { if (!node) return; if (typeof node.getChildren === "function") { const offset = parentOffset + (node.startTime?.() ?? 0); for (const child of node.getChildren(true, true, true)) { walk(child, offset); } return; } const targets = (node.targets?.() ?? []).filter((t) => t instanceof Element); if (!targets.length) return; const vars = node.vars ?? {}; const props = Object.keys(vars).filter( (k) => ![ "duration", "ease", "delay", "repeat", "yoyo", "onStart", "onUpdate", "onComplete", "stagger", ].includes(k), ); const start = parentOffset + (node.startTime?.() ?? 0); const end = start + (node.duration?.() ?? 0); results.push({ selectorHint: selectorOf(targets[0]) ?? "(unknown)", targetCount: targets.length, props, start, end, ease: typeof vars.ease === "string" ? vars.ease : (vars.ease?.toString?.() ?? "none"), }); }; for (const tl of Object.values(registry)) walk(tl, 0); results.sort((a, b) => a.start - b.start); return results; }); } async function measureTarget(session, selector) { return await session.page.evaluate((sel) => { const el = document.querySelector(sel); if (!el) return { x: 0, y: 0, w: 0, h: 0, missing: true }; const r = el.getBoundingClientRect(); const cs = getComputedStyle(el); return { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height), opacity: parseFloat(cs.opacity), visible: cs.visibility !== "hidden" && cs.display !== "none", }; }, selector); } // ─── Tween description (the key output for agents) ────────────────────────── function describeTween(tw, props, bboxes, flags) { const dur = (tw.end - tw.start).toFixed(2); const parts = []; parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`); // Movement const first = bboxes[0]; const last = bboxes[bboxes.length - 1]; if (first && last) { const dx = last.x - first.x; const dy = last.y - first.y; if (Math.abs(dx) > 3 || Math.abs(dy) > 3) { const dirs = []; if (Math.abs(dy) > 3) dirs.push(dy < 0 ? `${Math.abs(dy)}px up` : `${Math.abs(dy)}px down`); if (Math.abs(dx) > 3) dirs.push(dx < 0 ? `${Math.abs(dx)}px left` : `${Math.abs(dx)}px right`); parts.push(`moves ${dirs.join(" and ")}`); } } // Opacity if (first && last && first.opacity !== undefined && last.opacity !== undefined) { const o1 = first.opacity; const o2 = last.opacity; if (Math.abs(o2 - o1) > 0.1) { if (o1 < 0.1 && o2 > 0.5) parts.push("fades in"); else if (o1 > 0.5 && o2 < 0.1) parts.push("fades out"); else parts.push(`opacity ${o1.toFixed(1)}→${o2.toFixed(1)}`); } } // Scale (from props) if (props.includes("scale") || props.includes("scaleX") || props.includes("scaleY")) { parts.push("scales"); } // Size changes if (first && last) { const dw = last.w - first.w; const dh = last.h - first.h; if (Math.abs(dw) > 5) parts.push(`width ${first.w}→${last.w}px`); if (Math.abs(dh) > 5) parts.push(`height ${first.h}→${last.h}px`); } // Visibility if (first && last && first.visible !== last.visible) { parts.push(last.visible ? "becomes visible" : "becomes hidden"); } // Final position if (last && !last.missing) { parts.push(`ends at (${last.x}, ${last.y}) ${last.w}×${last.h}px`); } // Flags if (flags.length > 0) { parts.push(`FLAGS: ${flags.join(", ")}`); } return parts.join(". ") + "."; } // ─── Flag computation ─────────────────────────────────────────────────────── function computeFlags(tw, bboxes, { width, height }) { const flags = []; const dur = tw.end - tw.start; if (bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate"); const anyOffscreen = bboxes.some( (b) => b.x + b.w <= 0 || b.y + b.h <= 0 || b.x >= width || b.y >= height || b.x < -b.w * 0.5 || b.y < -b.h * 0.5 || b.x + b.w > width + b.w * 0.5 || b.y + b.h > height + b.h * 0.5, ); if (anyOffscreen) flags.push("offscreen"); if (bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)) { flags.push("invisible"); } if (dur < 0.2 && tw.props.some((p) => ["y", "x", "opacity", "scale"].includes(p))) { flags.push("paced-fast"); } if (dur > 2.0) flags.push("paced-slow"); return flags; } function markCollisions(tweens) { for (let i = 0; i < tweens.length; i++) { for (let j = i + 1; j < tweens.length; j++) { const a = tweens[i]; const b = tweens[j]; if (a.end <= b.start || b.end <= a.start) continue; for (const ba of a.bboxes) { const bb = b.bboxes.find((x) => Math.abs(x.t - ba.t) < 0.05); if (!bb) continue; const overlap = rectOverlapArea(ba, bb); const aArea = ba.w * ba.h; if (aArea > 0 && overlap / aArea > 0.3) { if (!a.flags.includes("collision")) a.flags.push("collision"); if (!b.flags.includes("collision")) b.flags.push("collision"); break; } } } } } function rectOverlapArea(a, b) { const x1 = Math.max(a.x, b.x); const y1 = Math.max(a.y, b.y); const x2 = Math.min(a.x + a.w, b.x + b.w); const y2 = Math.min(a.y + a.h, b.y + b.h); return Math.max(0, x2 - x1) * Math.max(0, y2 - y1); } // ─── Composition-level analysis ───────────────────────────────────────────── function buildTimeline(tweens, duration) { const cols = 60; const lines = []; const secPerCol = duration / cols; lines.push("Timeline (" + duration.toFixed(1) + "s, each char ≈ " + secPerCol.toFixed(2) + "s):"); lines.push(" " + "0s" + " ".repeat(cols - 8) + duration.toFixed(0) + "s"); lines.push(" " + "┼" + "─".repeat(cols - 1) + "┤"); for (const tw of tweens) { const startCol = Math.floor(tw.start / secPerCol); const endCol = Math.min(cols, Math.ceil(tw.end / secPerCol)); const bar = " ".repeat(startCol) + "█".repeat(Math.max(1, endCol - startCol)) + " ".repeat(Math.max(0, cols - endCol)); const label = tw.selector + " " + tw.props.join("+"); lines.push(" " + bar + " " + label); } return lines.join("\n"); } function computeDensity(tweens, duration) { const buckets = []; for (let t = 0; t < duration; t += 0.5) { const active = tweens.filter((tw) => tw.start <= t + 0.5 && tw.end >= t); buckets.push({ t: +t.toFixed(1), activeTweens: active.length }); } return buckets; } function findDeadZones(density, duration) { const zones = []; let zoneStart = null; for (const d of density) { if (d.activeTweens === 0) { if (zoneStart === null) zoneStart = d.t; } else { if (zoneStart !== null) { const zoneEnd = d.t; if (zoneEnd - zoneStart >= 1.0) { zones.push({ start: zoneStart, end: zoneEnd, duration: +(zoneEnd - zoneStart).toFixed(1), note: "No animation for " + (zoneEnd - zoneStart).toFixed(1) + "s. Intentional hold or missing entrance?", }); } zoneStart = null; } } } if (zoneStart !== null && duration - zoneStart >= 1.0) { zones.push({ start: zoneStart, end: +duration.toFixed(1), duration: +(duration - zoneStart).toFixed(1), note: "No animation for " + (duration - zoneStart).toFixed(1) + "s at end. Final hold or missing outro?", }); } return zones; } function detectStaggers(tweens) { const groups = []; const used = new Set(); for (let i = 0; i < tweens.length; i++) { if (used.has(i)) continue; const tw = tweens[i]; const group = [tw]; used.add(i); for (let j = i + 1; j < tweens.length; j++) { if (used.has(j)) continue; const other = tweens[j]; const sameProps = tw.props.join(",") === other.props.join(","); const sameDuration = Math.abs(tw.duration - other.duration) < 0.05; const closeInTime = other.start - tw.start < tw.duration * 4; if (sameProps && sameDuration && closeInTime) { group.push(other); used.add(j); } } if (group.length >= 3) { const intervals = []; for (let k = 1; k < group.length; k++) { intervals.push(+(group[k].start - group[k - 1].start).toFixed(3)); } const avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length; const maxDrift = Math.max(...intervals.map((iv) => Math.abs(iv - avgInterval))); const consistent = maxDrift < avgInterval * 0.3; groups.push({ elements: group.map((g) => g.selector), props: tw.props, count: group.length, intervals, avgInterval: +avgInterval.toFixed(3), consistent, note: consistent ? group.length + " elements stagger at " + (avgInterval * 1000).toFixed(0) + "ms intervals" : group.length + " elements stagger with uneven intervals (" + intervals.map((iv) => (iv * 1000).toFixed(0) + "ms").join(", ") + ")", }); } } return groups; } function buildElementLifecycles(tweens) { const elements = {}; for (const tw of tweens) { const sel = tw.selector; if (!elements[sel]) { elements[sel] = { firstTween: tw.start, lastTween: tw.end, tweenCount: 0, props: new Set() }; } elements[sel].firstTween = Math.min(elements[sel].firstTween, tw.start); elements[sel].lastTween = Math.max(elements[sel].lastTween, tw.end); elements[sel].tweenCount++; tw.props.forEach((p) => elements[sel].props.add(p)); } const result = {}; for (const [sel, data] of Object.entries(elements)) { const lastBbox = findLastBbox(tweens, sel); result[sel] = { firstAppears: +data.firstTween.toFixed(3), lastAnimates: +data.lastTween.toFixed(3), tweenCount: data.tweenCount, props: [...data.props], endsVisible: lastBbox ? lastBbox.opacity > 0.1 && lastBbox.visible : null, finalPosition: lastBbox ? { x: lastBbox.x, y: lastBbox.y, w: lastBbox.w, h: lastBbox.h } : null, }; } return result; } function findLastBbox(tweens, selector) { for (let i = tweens.length - 1; i >= 0; i--) { if (tweens[i].selector === selector && tweens[i].bboxes?.length > 0) { return tweens[i].bboxes[tweens[i].bboxes.length - 1]; } } return null; } async function captureSnapshots(session, tweens, duration) { const times = [0, duration * 0.25, duration * 0.5, duration * 0.75, duration - 0.1]; const snapshots = []; for (const t of times) { await seekTo(session, t); const visible = await session.page.evaluate(() => { const out = []; const els = document.querySelectorAll("[id]"); for (const el of els) { const cs = getComputedStyle(el); if (cs.display === "none") continue; const opacity = parseFloat(cs.opacity); if (opacity < 0.01) continue; const rect = el.getBoundingClientRect(); if (rect.width < 1 || rect.height < 1) continue; out.push({ id: el.id, x: Math.round(rect.x), y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height), opacity: +opacity.toFixed(2), }); } return out; }); const activeTweens = tweens .filter((tw) => tw.start <= t && tw.end >= t) .map((tw) => tw.selector); snapshots.push({ t: +t.toFixed(2), visibleElements: visible.length, animatingNow: activeTweens, elements: visible, }); } return snapshots; } // ─── Output ───────────────────────────────────────────────────────────────── function printSummary(report) { console.log( `\nAnimation map: ${report.mappedTweens}/${report.totalTweens} tweens (skipped ${report.skippedMicroTweens} micro-tweens)`, ); const flagCounts = {}; for (const tw of report.tweens) { for (const f of tw.flags) flagCounts[f] = (flagCounts[f] ?? 0) + 1; } if (Object.keys(flagCounts).length > 0) { for (const [f, n] of Object.entries(flagCounts)) console.log(` ${f}: ${n}`); } if (report.staggers?.length > 0) { console.log(` staggers: ${report.staggers.map((s) => s.note).join("; ")}`); } if (report.deadZones?.length > 0) { console.log( ` dead zones: ${report.deadZones.map((z) => z.start + "-" + z.end + "s").join(", ")}`, ); } console.log(report.choreography); } function parseArgs(argv) { const out = {}; let positional = 0; for (let i = 0; i < argv.length; i++) { const a = argv[i]; if (a.startsWith("--")) { const k = a.slice(2); const v = argv[i + 1]?.startsWith("--") ? true : argv[++i]; out[k] = v; } else if (positional === 0) { out.composition = a; positional++; } } return out; } function die(msg) { console.error(`animation-map: ${msg}`); process.exit(2); }scripts/asr-requirements-tested.txt418 B40b9223eee9dupstream ↗
anyio==4.14.2 av==18.1.0 certifi==2026.7.22 click==8.5.0 colorama==0.4.6 ctranslate2==4.8.1 faster-whisper==1.2.1 filelock==3.32.4 flatbuffers==25.12.19 fsspec==2026.7.0 h11==0.16.0 hf-xet==1.6.0 httpcore==1.0.9 httpx==0.28.1 huggingface_hub==1.29.0 idna==3.19 numpy==2.5.2 onnxruntime==1.29.0 packaging==26.3 protobuf==7.36.0 PyYAML==6.0.3 setuptools==84.0.0 tokenizers==0.23.1 tqdm==4.70.0 typing_extensions==4.16.0scripts/boundary_contact_sheet.py3.5 KB62a474c21a41upstream ↗
#!/usr/bin/env python3 """Extract exact semantic-boundary frames into a labeled contact sheet. The input JSON is intentionally project-agnostic: { "checks": [ {"label": "scene-01-left-end", "timeMs": 3200}, {"label": "scene-01-right-start", "timeMs": 3500} ] } """ from __future__ import annotations import argparse import json import math from pathlib import Path import av from PIL import Image, ImageDraw, ImageFont def frame_at(container: av.container.InputContainer, stream: av.video.stream.VideoStream, time_ms: int) -> Image.Image: target_seconds = max(0, time_ms) / 1000 container.seek(int(target_seconds * 1_000_000), any_frame=False, backward=True) candidate = None for frame in container.decode(stream): candidate = frame if frame.time is not None and frame.time >= target_seconds: break if candidate is None: raise RuntimeError(f"无法读取 {time_ms}ms 附近的视频帧") return candidate.to_image().convert("RGB") def main() -> int: parser = argparse.ArgumentParser(description="按语义边界时间抽帧并生成联系表") parser.add_argument("--video", required=True) parser.add_argument("--checks", required=True, help="包含 checks[{label,timeMs}] 的 JSON") parser.add_argument("--output", required=True) parser.add_argument("--columns", type=int, default=2) parser.add_argument("--thumb-width", type=int, default=720) args = parser.parse_args() video = Path(args.video).resolve() checks_path = Path(args.checks).resolve() output = Path(args.output).resolve() data = json.loads(checks_path.read_text(encoding="utf-8")) checks = data.get("checks", []) if not checks: raise SystemExit("checks 不能为空") frames: list[tuple[str, int, Image.Image]] = [] with av.open(str(video)) as container: stream = container.streams.video[0] for item in checks: label = str(item.get("label", "check")) time_ms = int(item["timeMs"]) if time_ms < 0: raise ValueError(f"检查点不能为负数:{label}={time_ms}ms") frames.append((label, time_ms, frame_at(container, stream, time_ms))) columns = max(1, args.columns) margin = 20 label_height = 44 sample = frames[0][2] thumb_width = max(240, args.thumb_width) thumb_height = round(sample.height * thumb_width / sample.width) rows = math.ceil(len(frames) / columns) sheet = Image.new( "RGB", (columns * thumb_width + (columns + 1) * margin, rows * (thumb_height + label_height) + (rows + 1) * margin), "white", ) draw = ImageDraw.Draw(sheet) font = ImageFont.load_default() for index, (label, time_ms, frame) in enumerate(frames): row, column = divmod(index, columns) x = margin + column * (thumb_width + margin) y = margin + row * (thumb_height + label_height + margin) thumb = frame.resize((thumb_width, thumb_height), Image.Resampling.LANCZOS) sheet.paste(thumb, (x, y + label_height)) safe_label = label.encode("ascii", "replace").decode("ascii") draw.text((x, y + 8), f"{safe_label} {time_ms / 1000:.3f}s", fill="black", font=font) output.parent.mkdir(parents=True, exist_ok=True) sheet.save(output, quality=92) print(json.dumps({ "output": str(output), "checks": len(frames), }, ensure_ascii=False)) return 0 if __name__ == "__main__": raise SystemExit(main())scripts/check_drawable_regions.py5.2 KB47aa61a97845upstream ↗
#!/usr/bin/env python3 """检查逐笔故事源图的语义区域是否适合独立落墨。""" from __future__ import annotations import argparse import json import math from pathlib import Path import cv2 import numpy as np def rect(element: dict) -> tuple[int, int, int, int]: region = element["region"] return int(region["x"]), int(region["y"]), int(region["width"]), int(region["height"]) def intersection(a: tuple[int, int, int, int], b: tuple[int, int, int, int]) -> int: ax, ay, aw, ah = a bx, by, bw, bh = b return max(0, min(ax + aw, bx + bw) - max(ax, bx)) * max(0, min(ay + ah, by + bh) - max(ay, by)) def gap(a: tuple[int, int, int, int], b: tuple[int, int, int, int]) -> float: ax, ay, aw, ah = a bx, by, bw, bh = b dx = max(bx - (ax + aw), ax - (bx + bw), 0) dy = max(by - (ay + ah), ay - (by + bh), 0) return math.hypot(dx, dy) def main() -> int: parser = argparse.ArgumentParser(description="检查逐笔源图的区域重叠、留白和跨区连通线") parser.add_argument("image") parser.add_argument("annotation") parser.add_argument("--report", required=True) parser.add_argument("--min-gutter-ratio", type=float, default=0.035, help="区域矩形最小间距占画面宽度的比例,默认 3.5%%") parser.add_argument("--bridge-min-pixels", type=int, default=80, help="同时进入多个区域的连通前景最小像素数") args = parser.parse_args() image = cv2.imread(args.image, cv2.IMREAD_COLOR) if image is None: raise SystemExit(f"无法读取图片:{args.image}") annotation = json.loads(Path(args.annotation).read_text(encoding="utf-8")) height, width = image.shape[:2] expected = annotation.get("canvas", {}) errors: list[dict] = [] warnings: list[dict] = [] elements = sorted(annotation.get("elements", []), key=lambda item: item.get("sequence", 0)) regions = [(item.get("id", str(index)), rect(item)) for index, item in enumerate(elements)] if expected.get("width") != width or expected.get("height") != height: errors.append({"type": "canvas_mismatch", "image": [width, height], "annotation": expected}) for region_id, (x, y, region_width, region_height) in regions: if min(x, y, region_width, region_height) < 0 or x + region_width > width or y + region_height > height or region_width == 0 or region_height == 0: errors.append({"type": "region_out_of_bounds", "region": region_id, "rect": [x, y, region_width, region_height]}) min_gutter = round(width * args.min_gutter_ratio) pair_metrics = [] for index, (a_id, a) in enumerate(regions): for b_id, b in regions[index + 1:]: overlap = intersection(a, b) distance = gap(a, b) pair_metrics.append({"a": a_id, "b": b_id, "overlapPixels": overlap, "gutterPixels": round(distance, 1)}) if overlap: errors.append({"type": "region_overlap", "a": a_id, "b": b_id, "pixels": overlap}) elif distance < min_gutter: warnings.append({"type": "gutter_too_small", "a": a_id, "b": b_id, "pixels": round(distance, 1), "recommendedMinimum": min_gutter}) # 清晰墨线和高饱和色块进入前景;亮、低饱和的轻微纸纹通常被排除。 hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV) gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) foreground = ((gray < 150) | ((hsv[:, :, 1] > 70) & (hsv[:, :, 2] < 235))).astype(np.uint8) foreground = cv2.morphologyEx(foreground, cv2.MORPH_CLOSE, np.ones((3, 3), np.uint8)) component_count, labels, stats, _ = cv2.connectedComponentsWithStats(foreground, 8) region_masks = [] for _, (x, y, region_width, region_height) in regions: mask = np.zeros((height, width), np.uint8) mask[y:y + region_height, x:x + region_width] = 1 region_masks.append(mask) bridges = [] for label in range(1, component_count): area = int(stats[label, cv2.CC_STAT_AREA]) if area < args.bridge_min_pixels: continue component = labels == label touched = [regions[index][0] for index, mask in enumerate(region_masks) if np.count_nonzero(component & (mask > 0)) >= 12] if len(touched) > 1: bridges.append({"regions": touched, "pixels": area}) if bridges: errors.append({"type": "foreground_bridges_regions", "components": bridges}) report = { "passed": not errors, "image": str(Path(args.image).resolve()), "annotation": str(Path(args.annotation).resolve()), "canvas": [width, height], "minGutterPixels": min_gutter, "pairs": pair_metrics, "errors": errors, "warnings": warnings, "note": "自动检查用于拦截明显重叠和跨区连线,仍需人工逐区播放确认。", } Path(args.report).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8") print(json.dumps(report, ensure_ascii=False, indent=2)) return 1 if errors else 0 if __name__ == "__main__": raise SystemExit(main())scripts/finalize_stroke_video.py5.8 KBd6233596c3eaupstream ↗
"""Finalize multi-scene stroke-story videos deterministically. The helper always normalizes scene size, frame rate and timestamps. Approved source images are overlaid only when the caller explicitly requests it after a visual end-frame comparison; unconditional overlays can create a late crop/zoom flash even when the stroke render is already complete. """ from __future__ import annotations import argparse import json import subprocess import tempfile from pathlib import Path def run(command: list[str]) -> None: completed = subprocess.run(command, text=True, capture_output=True, encoding="utf-8", errors="replace") if completed.returncode: detail = completed.stderr.strip() or completed.stdout.strip() raise RuntimeError(f"命令失败({completed.returncode}):{detail[-3000:]}") def ass_filter(path: Path) -> str: value = path.resolve().as_posix().replace(":", r"\:").replace("'", r"\'") return f"ass='{value}'" def main() -> int: parser = argparse.ArgumentParser(description="统一时间基准并合成逐笔故事视频;源图补全须显式启用") parser.add_argument("--manifest", required=True, help="项目清单 JSON") parser.add_argument("--ffmpeg", required=True, help="可运行的 FFmpeg 绝对路径") parser.add_argument("--output", required=True, help="最终 MP4") parser.add_argument("--fade-ms", type=int, default=650, help="每幕末尾源图淡入时长,默认650ms") parser.add_argument("--lead-ms", type=int, default=900, help="淡入开始距幕尾的时间,默认900ms") parser.add_argument( "--source-overlay", choices=("never", "always"), default="never", help="是否在每幕末尾淡入批准源图;默认 never,只有末帧对照确认漏色后才用 always", ) args = parser.parse_args() manifest_path = Path(args.manifest).resolve() root = manifest_path.parent data = json.loads(manifest_path.read_text(encoding="utf-8")) ffmpeg = str(Path(args.ffmpeg).resolve()) output = Path(args.output).resolve() output.parent.mkdir(parents=True, exist_ok=True) width = int(data.get("width", 1920)) height = int(data.get("height", 1080)) fps = int(data.get("fps", 30)) scenes = data.get("scenes", []) if not scenes: raise SystemExit("manifest.scenes 不能为空") with tempfile.TemporaryDirectory(prefix="stroke-finalize-") as tmp_name: tmp = Path(tmp_name) finalized: list[Path] = [] total_ms = 0 for index, scene in enumerate(scenes, start=1): video = (root / scene["video"]).resolve() duration_ms = int(scene["durationMs"]) if not video.is_file(): raise FileNotFoundError(f"第{index}幕视频缺失:{video}") total_ms += duration_ms scene_out = tmp / f"scene-{index:03d}.mp4" if args.source_overlay == "always": image_value = scene.get("image") if not image_value: raise KeyError(f"第{index}幕启用源图补全但未提供 image") image = (root / image_value).resolve() if not image.is_file(): raise FileNotFoundError(f"第{index}幕源图缺失:{image}") fade_ms = min(args.fade_ms, max(1, duration_ms // 3)) fade_start = max(0, duration_ms - args.lead_ms) / 1000 overlay = ( f"[1:v]scale={width}:{height},format=rgba," f"fade=t=in:st={fade_start:.3f}:d={fade_ms / 1000:.3f}:alpha=1[full];" "[0:v][full]overlay=0:0:shortest=1,format=yuv420p" ) run([ ffmpeg, "-loglevel", "error", "-y", "-i", str(video), "-loop", "1", "-i", str(image), "-filter_complex", overlay, "-t", f"{duration_ms / 1000:.3f}", "-r", str(fps), "-c:v", "libx264", "-preset", "fast", "-crf", "18", "-an", str(scene_out), ]) else: run([ ffmpeg, "-loglevel", "error", "-y", "-i", str(video), "-vf", f"fps={fps},scale={width}:{height}:flags=lanczos,format=yuv420p", "-t", f"{duration_ms / 1000:.3f}", "-r", str(fps), "-c:v", "libx264", "-preset", "fast", "-crf", "18", "-an", str(scene_out), ]) finalized.append(scene_out) concat_file = tmp / "concat.txt" concat_file.write_text("".join(f"file '{path.as_posix()}'\n" for path in finalized), encoding="utf-8") merged = tmp / "visual.mp4" run([ ffmpeg, "-loglevel", "error", "-y", "-f", "concat", "-safe", "0", "-i", str(concat_file), "-vf", f"fps={fps},scale={width}:{height}:flags=lanczos,format=yuv420p", "-c:v", "libx264", "-preset", "fast", "-crf", "18", "-an", str(merged), ]) narration = data.get("narration") ass = data.get("ass") if narration: command = [ffmpeg, "-loglevel", "error", "-y", "-i", str(merged), "-i", str((root / narration).resolve())] if ass: command += ["-vf", ass_filter(root / ass)] command += [ "-af", "apad=pad_dur=1", "-t", f"{total_ms / 1000:.3f}", "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", str(output), ] run(command) else: output.write_bytes(merged.read_bytes()) print(json.dumps({ "output": str(output), "durationMs": total_ms, "scenes": len(scenes), "sourceOverlay": args.source_overlay, }, ensure_ascii=False)) return 0 if __name__ == "__main__": raise SystemExit(main())scripts/install.ps1919 B09a7ec27b14fupstream ↗
[CmdletBinding()] param( [string]$Destination, [switch]$Force ) $ErrorActionPreference = 'Stop' $source = Split-Path -Parent $PSScriptRoot if (-not $Destination) { $codexBase = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' } $Destination = Join-Path $codexBase 'skills/hand-drawn-explainer-video-nikola' } $target = [System.IO.Path]::GetFullPath($Destination) if (Test-Path -LiteralPath $target) { if (-not $Force) { throw "Destination already exists: $target. Use -Force only after backing it up." } throw "For safety this installer never deletes an existing Skill. Rename or remove it manually, then run again." } New-Item -ItemType Directory -Path (Split-Path -Parent $target) -Force | Out-Null Copy-Item -LiteralPath $source -Destination $target -Recurse Write-Host "Installed to $target" Write-Host "Next: python `"$target/scripts/setup_check.py`""scripts/media_check.py12 KBce767d91d633upstream ↗
"""Validate encoded media and scene coverage. Does not perform ASR or visual acceptance.""" import argparse import json import math from pathlib import Path import re import sys def positive(value): return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) and value > 0 def check_timeline(data, report): errors = report['errors'] duration = data.get('duration') scenes = data.get('scenes') if not positive(duration) or not isinstance(scenes, list) or not scenes: raise ValueError('Timeline needs positive duration and a nonempty scenes array.') previous = 0.0 captions = [] for i, scene in enumerate(scenes): start, end = scene.get('start'), scene.get('end') if not isinstance(start, (int, float)) or not math.isfinite(start) or not positive(end) or not 0 <= start < end <= duration + .001: raise ValueError(f'Invalid time range in scene {i+1}.') if abs(start - previous) > .05: errors.append(f'Scene {i+1}: gap or overlap in semantic timeline (use separate transition intervals).') if not isinstance(scene.get('caption'), str) or not scene['caption'].strip(): errors.append(f'Scene {i+1}: missing caption.') captions.append(scene.get('caption', '')) previous = end if abs(previous-duration) > .05: errors.append('Scenes do not cover timeline ending.') source = data.get('narration_text') if isinstance(source, str) and source.strip(): # Whitespace only: punctuation, numbers and words must remain unchanged. normalize = lambda value: re.sub(r'\s+', '', value) report['caption_text_checked'] = True if normalize(source) != normalize(''.join(captions)): errors.append('Caption text differs from narration_text (whitespace ignored only).') else: report['caption_text_checked'] = False report['warnings'].append('No narration_text: content completeness was NOT checked.') if not data.get('alignment'): errors.append('Missing alignment method; do not imply word-level synchronization.') if data.get('audio_duration') is not None: if not positive(data['audio_duration']) or data['audio_duration'] > duration + .1: errors.append('Invalid source narration duration or narration longer than video timeline.') return scenes def check_media(args, data, scenes, report): import av import numpy as np samples = {} targets = [(i, s['start'] + (s['end']-s['start'])*.65) for i,s in enumerate(scenes)] motion = [[] for _ in scenes] count = 0 previous = None previous_scene = None scene_index = 0 previous_time = -1 with av.open(str(args.video)) as container: if not container.streams.video or not container.streams.audio: raise ValueError('MP4 must contain both video and audio streams.') stream = container.streams.video[0] width, height = stream.width, stream.height fps = float(stream.average_rate or 0) if fps <= 0: raise ValueError('No usable video frame rate.') step = max(1, round(fps / 5)) for frame in container.decode(video=0): if frame.time is None: raise ValueError('Video frame is missing its timestamp.') t = float(frame.time) if t <= previous_time: raise ValueError('Video timestamps are not increasing.') previous_time = t count += 1 while targets and t >= targets[0][1]: index, target = targets.pop(0) samples[index] = (t, frame.to_image()) if args.contact_sheet else (t, None) while scene_index < len(scenes)-1 and t >= scenes[scene_index]['end']: scene_index += 1 if count % step == 0: # Configurable normalized ROI excludes title/caption/progress by default. arr = frame.reformat(width=180, height=320, format='rgb24').to_ndarray() x0,y0,x1,y1 = args.motion_roi crop = arr[int(y0*320):int(y1*320),int(x0*180):int(x1*180)].astype('float32') # Exclude transitions and samples across scenes from the motion estimate. scene = scenes[scene_index] inside = scene['start']+.5 < t < scene['end']-.4 if previous is not None and previous_scene == scene_index and inside: motion[scene_index].append(float(np.abs(crop-previous).mean())) previous, previous_scene = crop, scene_index if not count: raise ValueError('No decoded video frames.') video_end = previous_time + 1/fps report.update(size=[width,height], fps=fps, frames_decoded=count, video_duration=video_end, scene_samples=[{'scene':i+1,'time':v[0]} for i,v in samples.items()],motion_roi=args.motion_roi) tolerance = max(.1, 2/fps) if abs(video_end-data['duration']) > tolerance: report['errors'].append('Encoded video duration differs from timeline.') if abs(count/fps-video_end) > tolerance: report['errors'].append('Frame count/timestamps inconsistent with constant frame rate.') for attr, actual in [('width',width),('height',height),('fps',fps)]: expected = getattr(args, attr) if expected is not None and abs(actual-expected) > .05: report['errors'].append(f'Unexpected {attr}: {actual}; expected {expected}.') if targets: report['errors'].append('Not every scene could be sampled from the actual MP4.') peak, total, clipped, audible_start, audible_end = 0., 0, 0, None, None first_pts, last_pts, prior_end = None, None, None timestamp_gaps = 0 with av.open(str(args.video)) as container: resampler = av.AudioResampler(format='fltp', layout='mono', rate=24000) def consume(frame): nonlocal peak,total,clipped,audible_start,audible_end array = frame.to_ndarray().ravel() if not np.isfinite(array).all(): raise ValueError('Audio contains non-finite samples.') if len(array): peak = max(peak,float(np.abs(array).max())) clipped += int((np.abs(array) >= .999).sum()) audible = np.flatnonzero(np.abs(array) > .015) if len(audible): if audible_start is None: audible_start = (total+int(audible[0]))/24000 audible_end = (total+int(audible[-1]))/24000 total += len(array) for frame in container.decode(audio=0): if frame.time is None: raise ValueError('Audio frame is missing its timestamp.') now = float(frame.time) if first_pts is None: first_pts = now if prior_end is not None and abs(now-prior_end) > .1: timestamp_gaps += 1 last_pts = now+frame.samples/frame.sample_rate prior_end = last_pts for converted in resampler.resample(frame): consume(converted) for converted in resampler.resample(None): consume(converted) if not total or audible_start is None: report['errors'].append('No audible narration detected.') if first_pts is not None and (abs(first_pts) > tolerance or abs(last_pts-video_end) > tolerance or timestamp_gaps): report['errors'].append('Audio timestamps do not cover video or have gaps.') if abs(total/24000-video_end) > tolerance: report['errors'].append('Decoded audio length differs from video; mux silence for intentional tail hold.') if peak >= 1.0: report['errors'].append('Audio reaches/exceeds full scale; review clipping.') if clipped: report['warnings'].append('Near-full-scale samples detected; listen for clipping.') report.update(audio_duration=total/24000,audio_peak=peak,near_full_scale_samples=clipped, audible_span=[audible_start,audible_end],audio_timestamp_start=first_pts,audio_timestamp_end=last_pts) report['art_motion'] = [{'scene':i+1,'max_mean_change':max(values,default=0)} for i,values in enumerate(motion)] for item in report['art_motion']: if item['max_mean_change'] < .1: report['warnings'].append(f"Scene {item['scene']}: little ROI motion detected; review content and ROI manually.") if args.contact_sheet and samples: from PIL import Image, ImageDraw columns = min(4,len(samples)) thumb_w = 216 thumb_h = round(thumb_w*height/width) cell_h = thumb_h+28 sheet = Image.new('RGB',(columns*thumb_w, math.ceil(len(samples)/columns)*cell_h),'#F8F6EF') draw = ImageDraw.Draw(sheet) for i,(timestamp,frame_image) in samples.items(): x,y = (i%columns)*thumb_w,(i//columns)*cell_h sheet.paste(frame_image.resize((thumb_w,thumb_h)),(x,y)) draw.text((x+6,y+thumb_h+5),f'Scene {i+1} / {timestamp:.2f}s',fill='black') args.contact_sheet.parent.mkdir(parents=True,exist_ok=True) sheet.save(args.contact_sheet) def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--timeline',type=Path,required=True) parser.add_argument('--video',type=Path) parser.add_argument('--report',type=Path,required=True) parser.add_argument('--contact-sheet',type=Path) parser.add_argument('--timeline-only',action='store_true') parser.add_argument('--width',type=int) parser.add_argument('--height',type=int) parser.add_argument('--fps',type=float) parser.add_argument('--motion-roi',type=float,nargs=4,default=[0,.23,1,.74],metavar=('X0','Y0','X1','Y1')) args = parser.parse_args() report = {'errors':[],'warnings':[], 'checks_scope':'Timeline only' if args.timeline_only else 'Decoded media and timeline', 'human_review_required':True,'limitations':'No ASR, pronunciation, semantic synchronization or visual quality acceptance. Motion statistics do not prove independent element animation.'} try: if not args.timeline_only and not args.video: raise ValueError('--video is required unless --timeline-only.') x0,y0,x1,y1 = args.motion_roi if not (0<=x0<x1<=1 and 0<=y0<y1<=1 and (x1-x0)*180>=1 and (y1-y0)*320>=1): raise ValueError('Motion ROI must have nonempty normalized bounds.') sources = [args.timeline] + ([args.video] if args.video else []) destinations = [args.report] + ([args.contact_sheet] if args.contact_sheet else []) if len({p.resolve() for p in destinations}) != len(destinations) or any(p.resolve()==s.resolve() for p in destinations for s in sources): raise ValueError('Report/contact sheet paths must differ from each other and input files.') data = json.loads(args.timeline.read_text(encoding='utf-8-sig')) scenes = check_timeline(data,report) report['alignment'] = data.get('alignment') if not args.timeline_only and not report['errors']: check_media(args,data,scenes,report) except Exception as exc: report['errors'].append(f'{type(exc).__name__}: {exc}') report['automated_checks_passed'] = not report['errors'] # Refuse to overwrite a source even when argument validation failed. if args.report.resolve() not in {p.resolve() for p in [args.timeline,args.video] if p}: args.report.parent.mkdir(parents=True,exist_ok=True) args.report.write_text(json.dumps(report,ensure_ascii=False,indent=2),encoding='utf-8') print(json.dumps({k:report[k] for k in ['automated_checks_passed','errors','warnings']},ensure_ascii=False)) return 0 if report['automated_checks_passed'] else 1 if __name__ == '__main__': sys.exit(main())scripts/preflight.py5.9 KB352421d7645eupstream ↗
"""Local capability checks. Never calls a paid API or installs dependencies.""" import argparse import json import os from pathlib import Path import subprocess import sys import tempfile def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--config', type=Path, required=True) parser.add_argument('--report', type=Path, required=True) parser.add_argument('--mode', choices=['render', 'asr', 'all'], default='render') parser.add_argument('--audio', type=Path, help='Authorized local audio; only its first five seconds are transcribed') args = parser.parse_args() cfg = json.loads(args.config.read_text(encoding='utf-8-sig')) checks = [] env = dict(os.environ, PYTHONUTF8='1', PYTHONIOENCODING='utf-8', HF_HUB_OFFLINE='1', HF_HUB_DISABLE_TELEMETRY='1') def record(name, passed, detail): checks.append(dict(check=name, passed=bool(passed), detail=detail)) def path(key): value = cfg.get(key) if not value or not Path(value).is_file(): record(key, False, 'Missing file; configure an existing executable or CLI entrypoint.') return None return str(Path(value).resolve()) def run(name, command, timeout=45): try: result = subprocess.run(command, capture_output=True, text=True, encoding='utf-8', errors='replace', env=env, timeout=timeout) # Do not echo arbitrary subprocess logs, user text or environment values. ok = result.returncode == 0 record(name, ok, 'Executed successfully.' if ok else 'Subprocess failed, exit=' + str(result.returncode) + '; do not retry unchanged runtime.') return result if ok else None except subprocess.TimeoutExpired: record(name, False, 'Timed out; do not repeat unchanged command.') except OSError as exc: record(name, False, 'Could not start process: ' + type(exc).__name__) return None if args.mode in ['render', 'all']: ffmpeg, ffprobe, node, cli, chrome = [path(k) for k in ['ffmpeg', 'ffprobe', 'node', 'hyperframes_cli', 'chrome']] if ffmpeg and ffprobe: with tempfile.TemporaryDirectory(prefix='handdrawn-preflight-') as tmp: video = str(Path(tmp) / 'encoder-check.mp4') if run('h264_actual_encode', [ffmpeg, '-v', 'error', '-f', 'lavfi', '-i', 'color=c=white:s=64x64:r=30', '-frames:v', '3', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-y', video]): r = run('ffprobe_actual_media', [ffprobe, '-v', 'error', '-show_entries', 'stream=codec_name,width,height', '-of', 'json', video]) if r: streams = json.loads(r.stdout).get('streams', []) record('h264_probe_matches', any(s.get('codec_name') == 'h264' and s.get('width') == 64 and s.get('height') == 64 for s in streams), 'Expected H.264, 64x64.') if node and cli: run('hyperframes_cli', [node, cli, '--help']) if node and cli and chrome: code = """const {createRequire}=require('node:module'); const req=createRequire(process.argv[1]); (async()=>{const p=req('puppeteer-core');const b=await p.launch({executablePath:process.argv[2],headless:true,args:['--disable-gpu']}); try{const page=await b.newPage();await page.setViewport({width:64,height:64});await page.setContent('<svg width="64" height="64"><rect width="64" height="64" fill="blue"/></svg>');const png=await page.screenshot();if(png.length<100)throw Error('empty screenshot');}finally{await b.close();}})().catch(()=>process.exit(1));""" run('chrome_actual_capture_and_puppeteer_dependency', [node, '-e', code, cli, chrome]) media_python = path('media_python') if media_python: run('media_qa_imports', [media_python, '-c', 'import av,numpy; from PIL import Image; print("ok")']) if args.mode in ['asr', 'all']: asr_python = path('asr_python') model = Path(cfg['asr_model']) if cfg.get('asr_model') else None required = ['model.bin', 'config.json', 'tokenizer.json'] ready = model is not None and all((model / f).is_file() and (model / f).stat().st_size > 0 for f in required) record('asr_model_files', ready, 'Require nonempty model.bin, config.json, tokenizer.json; a cache directory alone is insufficient.') if ready and asr_python: audio = args.audio.resolve() if args.audio else None if audio and not audio.is_file(): record('asr_audio_sample', False, 'Specified local audio does not exist.') else: code = """import sys import numpy as np from faster_whisper import WhisperModel from faster_whisper.audio import decode_audio m=WhisperModel(sys.argv[1],device='cpu',compute_type='int8',cpu_threads=2,local_files_only=True) sample=decode_audio(sys.argv[2],sampling_rate=16000)[:80000] if len(sys.argv)>2 else np.zeros(16000,dtype=np.float32) segs,_=m.transcribe(sample,language='zh',beam_size=1,vad_filter=False,condition_on_previous_text=False) count=sum(1 for _ in segs) if len(sys.argv)>2 and count==0:raise RuntimeError('No speech segments from supplied sample') print('smoke_completed') """ cmd = [asr_python, '-c', code, str(model.resolve())] + ([str(audio)] if audio else []) run('asr_model_load_and_inference', cmd, timeout=120) report = dict(passed=bool(checks) and all(c['passed'] for c in checks), mode=args.mode, paid_requests=0, model_downloads=0, checks=checks, scope='Local execution checks only; not speech naturalness, full scene layout or service availability. Required checks depend on the chosen route.') args.report.parent.mkdir(parents=True, exist_ok=True) args.report.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding='utf-8') print(json.dumps(report, ensure_ascii=False)) return 0 if report['passed'] else 1 if __name__ == '__main__': sys.exit(main())scripts/quick_validate.py4.0 KBbdb20bb3fc6cupstream ↗
"""Static regression checks for hand-drawn-explainer-video-nikola.""" from __future__ import annotations import json from pathlib import Path ROOT = Path(__file__).resolve().parents[1] def text(path: str) -> str: return (ROOT / path).read_text(encoding="utf-8") def main() -> int: skill = text("SKILL.md") zh = text("SKILL.zh-CN.md") workflow = text("references/stroke-story-workflow.md") islands = text("references/semantic-island-storytelling.md") quality = text("references/quality-and-delivery.md") prefs = json.loads(text("preferences.json")) checks = { "frontmatter_name": "name: hand-drawn-explainer-video-nikola" in skill, "trigger_routes": all(x in skill for x in ( "两条制作路线", "边讲边画", "双语义岛只是逐笔故事的一种画面组织方法", "程序动画")), "bundled_backend": "vendor/srt-whiteboard-animation" in skill and "不包含第二份 `SKILL.md`" in skill, "no_silent_svg_fallback": "不以 SVG 动画冒充真实逐笔绘制" in skill, "liufei_voice_default": prefs.get("speaker") == "zh_male_liufei_uranus_bigtts" and prefs.get("voice_resource") == "seed-tts-2.0" and prefs.get("voice_provider") == "volcengine_openspeech", "credential_policy": "Never store credentials" in prefs.get("credentials", ""), "chinese_entry": "经过解码和画面抽检的 MP4" in zh, "backend_runtime_files": all((ROOT / p).is_file() for p in ( "vendor/srt-whiteboard-animation/scripts/render_stream_whiteboard.py", "vendor/srt-whiteboard-animation/scripts/annotation_schema.py", "vendor/srt-whiteboard-animation/assets/drawing-hand.png", "vendor/srt-whiteboard-animation/LICENSE", "vendor/srt-whiteboard-animation/UPSTREAM.md", )), "backend_not_triggerable": not (ROOT / "vendor/srt-whiteboard-animation/SKILL.md").exists(), "skeleton_default": prefs.get("stroke_story_ink_path") == "skeleton", "preflight_documented": "stroke_story_preflight.py" in workflow and "prepare_env.py" in workflow, "audio_complexity_budget": "区域可用时长 ÷ 线条与色块复杂度" in islands, "deterministic_keywords": "确定性 ASS/HTML 文字层" in islands, "hand_speed_boundary": "hand-follow" in workflow and "不改变旁白、笔迹" in workflow, "final_overlay_opt_in": "--source-overlay never" in workflow, "tail_frame_qa": "最后 0.3–0.5 秒" in quality, "style_docs": all((ROOT / p).is_file() for p in ( "references/xiaohei-style.md", "references/q-human-story-style.md", "docs/STYLES.md")), "public_docs": all((ROOT / p).is_file() for p in ( "README.md", "docs/INSTALL.md", "docs/CONFIGURATION.md", "SECURITY.md", "CONTRIBUTING.md")), "license_files": all((ROOT / p).is_file() for p in ( "LICENSE", "LICENSE-MEDIA.md", "THIRD_PARTY_NOTICES.md", "references/hand-drawn-video-prompts-LICENSE.txt")), "readme_contact_and_routes": all(x in text("README.md") for x in ( "https://x.com/Nikola314159", "商用Skills_完整手绘视频", "逐笔“边说边画”", "## 致谢")), "no_low_quality_tts_fallback": all(x in text("references/voiceover.md") for x in ( "zh_male_liufei_uranus_bigtts", "电脑系统朗读", "edge-tts", "配音缺口")), "examples": all((ROOT / p).is_file() for p in ( "examples/stroke-story/steve-jobs/steve-jobs-biography.mp4", "examples/stroke-story/yuefa-sanzhang/yuefa-sanzhang-16x9-stroke-story.mp4", "examples/stroke-story/yuefa-sanzhang/editable-project.zip", "examples/program-animation/skill-demo/index.html", "examples/program-animation/skill-demo/what-is-skill-sample.mp4", )), } print(json.dumps(checks, ensure_ascii=False, indent=2)) return 0 if all(checks.values()) else 1 if __name__ == "__main__": raise SystemExit(main())scripts/setup_check.py3.6 KBe49f6e1ec043upstream ↗
"""Read-only environment check for hand-drawn-explainer-video-nikola.""" from __future__ import annotations import json import os from pathlib import Path import platform import shutil import subprocess import sys from typing import Optional ROOT = Path(__file__).resolve().parents[1] BACKEND = ROOT / "vendor" / "srt-whiteboard-animation" def command(name: str) -> Optional[str]: return shutil.which(name) def browser_path() -> Optional[str]: """Find a browser on PATH or in common Windows install locations.""" for name in ("chrome", "msedge", "chromium", "chromium-browser"): found = command(name) if found: return found if platform.system() != "Windows": return None roots = [ os.environ.get("PROGRAMFILES"), os.environ.get("PROGRAMFILES(X86)"), os.environ.get("LOCALAPPDATA"), ] relative_paths = ( Path("Google/Chrome/Application/chrome.exe"), Path("Microsoft/Edge/Application/msedge.exe"), Path("Chromium/Application/chrome.exe"), ) for root in roots: if not root: continue for relative in relative_paths: candidate = Path(root) / relative if candidate.is_file(): return str(candidate) return None def main() -> int: venv_python = BACKEND / ".venv" / ("Scripts/python.exe" if platform.system() == "Windows" else "bin/python") required_files = [ ROOT / "SKILL.md", BACKEND / "scripts/render_stream_whiteboard.py", BACKEND / "scripts/annotation_schema.py", BACKEND / "assets/drawing-hand.png", BACKEND / "LICENSE", ] browser = browser_path() checks: dict[str, object] = { "python": {"ok": sys.version_info >= (3, 10), "version": platform.python_version()}, "skill_files": {"ok": all(p.is_file() for p in required_files)}, "ffmpeg": {"ok": bool(command("ffmpeg")), "path": command("ffmpeg")}, "ffprobe": {"ok": bool(command("ffprobe")), "path": command("ffprobe")}, "node": {"ok": bool(command("node")), "path": command("node")}, "browser": {"ok": bool(browser), "path": browser}, "powershell": {"ok": bool(command("pwsh") or command("powershell"))}, "stroke_venv": {"ok": venv_python.is_file(), "path": str(venv_python)}, "tts_key_configured": {"ok": bool(__import__("os").environ.get("VOLCENGINE_TTS_API_KEY")), "value_exposed": False}, } if venv_python.is_file(): probe = subprocess.run( [str(venv_python), "-c", "import av,cv2,numpy; from PIL import Image; print('ok')"], capture_output=True, text=True, timeout=30, ) checks["stroke_dependencies"] = {"ok": probe.returncode == 0} else: checks["stroke_dependencies"] = {"ok": False, "reason": "run vendor/srt-whiteboard-animation/scripts/prepare_env.py"} capabilities = { "prompt_only": bool(checks["skill_files"]["ok"]), "stroke_story": bool(checks["stroke_venv"]["ok"] and checks["stroke_dependencies"]["ok"]), "final_mp4": bool(checks["ffmpeg"]["ok"] and checks["ffprobe"]["ok"]), "program_animation": bool(checks["node"]["ok"] and checks["browser"]["ok"] and checks["ffmpeg"]["ok"] and checks["ffprobe"]["ok"]), "optional_volcengine_tts": bool(checks["powershell"]["ok"] and checks["tts_key_configured"]["ok"]), } result = {"root": str(ROOT), "checks": checks, "capabilities": capabilities} print(json.dumps(result, ensure_ascii=False, indent=2)) return 0 if capabilities["prompt_only"] else 1 if __name__ == "__main__": raise SystemExit(main())scripts/stroke_story_preflight.py6.1 KB4124eca3d9baupstream ↗
"""Validate the bundled stroke-story backend with a local smoke render. This script never installs dependencies or calls a paid API. """ from __future__ import annotations import argparse import json from pathlib import Path import subprocess import tempfile ROOT = Path(__file__).resolve().parents[1] BUNDLED_BACKEND = ROOT / "vendor" / "srt-whiteboard-animation" def default_backend_python(backend: Path) -> Path: windows = backend / ".venv" / "Scripts" / "python.exe" posix = backend / ".venv" / "bin" / "python" return windows if windows.exists() or not posix.exists() else posix def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--backend", type=Path, default=BUNDLED_BACKEND) parser.add_argument("--backend-python", type=Path) parser.add_argument("--report", type=Path, required=True) args = parser.parse_args() backend = args.backend.resolve() python = (args.backend_python or default_backend_python(backend)).resolve() checks: list[dict[str, object]] = [] def record(name: str, passed: bool, detail: str) -> None: checks.append({"check": name, "passed": bool(passed), "detail": detail}) required = [ backend / "scripts" / "render_stream_whiteboard.py", backend / "scripts" / "stream_render.py", backend / "scripts" / "annotation_schema.py", backend / "assets" / "drawing-hand.png", ] record("backend_files", all(path.is_file() for path in required), "Require bundled renderer, schema, core and hand asset.") record("backend_python", python.is_file(), "Require an existing isolated Python executable.") if all(path.is_file() for path in required) and python.is_file(): env_check = subprocess.run( [str(python), "-c", "import av,cv2,numpy; from PIL import Image; print('ok')"], capture_output=True, text=True, timeout=30, ) record("python_dependencies", env_check.returncode == 0, "Require PyAV, OpenCV, NumPy and Pillow.") help_check = subprocess.run( [str(python), str(required[0]), "--help"], capture_output=True, text=True, timeout=30, ) help_text = help_check.stdout + help_check.stderr record( "renderer_options", help_check.returncode == 0 and "skeleton" in help_text and "contour-wipe" in help_text, "Renderer must expose skeleton ink and contour-wipe color modes.", ) if env_check.returncode == 0 and help_check.returncode == 0: with tempfile.TemporaryDirectory(prefix="stroke-story-preflight-") as tmp: tmp_path = Path(tmp) image = tmp_path / "smoke.png" annotation = tmp_path / "smoke.annotation.json" output = tmp_path / "smoke.mp4" make_assets = ( "from PIL import Image,ImageDraw; import json,sys; " "im=Image.new('RGB',(360,640),(245,235,215)); d=ImageDraw.Draw(im); " "d.ellipse((80,130,280,330),outline=(35,35,35),width=12); " "d.line((110,410,250,520),fill=(35,35,35),width=12); im.save(sys.argv[1]); " "a={'sceneId':'smoke','canvas':{'width':360,'height':640},'sceneDurationMs':1200,'elements':[" "{'id':'main','label':'smoke','sequence':1,'narrativeRole':'smoke','subtitle':'smoke','type':'character'," "'region':{'x':40,'y':80,'width':280,'height':500},'reveal':{'direction':'top_to_bottom','startMs':100,'durationMs':900,'maskPaddingPx':10,'protectedRegions':[]}," "'handPath':{'start':[180,100],'end':[180,560],'easing':'easeInOut'}}]}; " "open(sys.argv[2],'w',encoding='utf-8').write(json.dumps(a,ensure_ascii=False))" ) asset_result = subprocess.run( [str(python), "-c", make_assets, str(image), str(annotation)], capture_output=True, text=True, timeout=30, ) render_result = subprocess.run( [ str(python), str(required[0]), str(image), str(annotation), str(output), str(required[3]), "--ink-path", "skeleton", "--color-fill", "contour-wipe", "--cap-long-edge", "320", ], capture_output=True, text=True, timeout=90, ) if asset_result.returncode == 0 else None record( "skeleton_smoke_render", bool(render_result and render_result.returncode == 0 and output.is_file() and output.stat().st_size > 1000), "Render a small local MP4 without network or paid requests.", ) if output.is_file(): decode = subprocess.run( [str(python), "-c", "import av,sys; c=av.open(sys.argv[1]); print(sum(1 for _ in c.decode(video=0)))", str(output)], capture_output=True, text=True, timeout=30, ) try: frame_count = int(decode.stdout.strip()) except ValueError: frame_count = 0 record("smoke_video_decode", decode.returncode == 0 and frame_count > 1, "Smoke MP4 must decode more than one frame.") report = { "passed": bool(checks) and all(bool(item["passed"]) for item in checks), "paid_requests": 0, "installs": 0, "backend": str(backend), "backend_provenance": "bundled vendor/srt-whiteboard-animation (MIT)", "checks": checks, } args.report.parent.mkdir(parents=True, exist_ok=True) args.report.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8") print(json.dumps(report, ensure_ascii=False)) return 0 if report["passed"] else 1 if __name__ == "__main__": raise SystemExit(main())scripts/volcengine_tts.ps16.3 KB97fa499bfdceupstream ↗
param( [Parameter(Mandatory=$true)][string]$TextFile, [Parameter(Mandatory=$true)][string]$OutputFile, [string]$Speaker, [switch]$DryRun ) $ErrorActionPreference = 'Stop' function Get-TextHash([string]$Value) { $sha = [Security.Cryptography.SHA256]::Create() try { return ([BitConverter]::ToString($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($Value)))).Replace('-','').ToLowerInvariant() } finally { $sha.Dispose() } } function Get-AudioHash([string]$Path) { $sha = [Security.Cryptography.SHA256]::Create() $inputStream = [IO.File]::OpenRead($Path) try { return ([BitConverter]::ToString($sha.ComputeHash($inputStream))).Replace('-','').ToLowerInvariant() } finally { $inputStream.Dispose(); $sha.Dispose() } } try { $prefs = Get-Content -LiteralPath (Join-Path $PSScriptRoot '../preferences.json') -Raw -Encoding UTF8 | ConvertFrom-Json if (-not $Speaker) { $Speaker = $prefs.speaker } if ([string]::IsNullOrWhiteSpace($Speaker)) { throw 'Missing speaker preference.' } $text = (Get-Content -LiteralPath $TextFile -Raw -Encoding UTF8).Trim() if (-not $text) { throw 'Narration is empty.' } if ($text.Length -gt 1500) { throw 'Local safety limit: 1500 characters. Split at natural paragraph boundaries.' } $OutputFile = [IO.Path]::GetFullPath($OutputFile) if ([IO.Path]::GetExtension($OutputFile) -ne '.mp3') { throw 'Output must have an .mp3 extension.' } $textHash = Get-TextHash $text $resource = 'seed-tts-2.0' $requestHash = Get-TextHash ($textHash + '|' + $Speaker + '|' + $resource + '|mp3|24000') $metaPath = $OutputFile + '.json' if (Test-Path -LiteralPath $OutputFile) { if (-not (Test-Path -LiteralPath $metaPath)) { throw 'Output exists without cache metadata; choose a new output path.' } $old = Get-Content -LiteralPath $metaPath -Raw -Encoding UTF8 | ConvertFrom-Json $audioHash = Get-AudioHash $OutputFile if ($old.complete -ne $true -or $old.request_sha256 -ne $requestHash -or $old.audio_sha256 -ne $audioHash) { throw 'Existing audio does not match the input, voice or checksum. Refusing to overwrite.' } Write-Output "Cache verified; no API request: $OutputFile" exit 0 } if (Test-Path -LiteralPath $metaPath) { throw 'Orphan metadata exists; choose a new output path.' } if ($DryRun) { @{dry_run=$true;network_request=$false;characters=$text.Length;speaker=$Speaker;resource=$resource;text_sha256=$textHash;output=$OutputFile} | ConvertTo-Json exit 0 } $plain = $env:VOLCENGINE_TTS_API_KEY if (-not $plain) { $secretPath = Join-Path $env:LOCALAPPDATA 'CodexVoice/volcengine-key.dpapi' if (-not (Test-Path -LiteralPath $secretPath)) { throw 'No authorized local TTS credential found.' } $secure = Get-Content -LiteralPath $secretPath | ConvertTo-SecureString $plain = [Net.NetworkCredential]::new('', $secure).Password } $requestId = [guid]::NewGuid().ToString() $headers = @{'X-Api-Key'=$plain;'X-Api-Request-Id'=$requestId;'X-Api-Resource-Id'=$resource} $payload = @{user=@{uid='local-video'};req_params=@{text=$text;speaker=$Speaker;audio_params=@{format='mp3';sample_rate=24000}}} $body = [Text.Encoding]::UTF8.GetBytes(($payload | ConvertTo-Json -Depth 8 -Compress)) Write-Output "One paid TTS request, speaker=$Speaker, characters=$($text.Length), request_id=$requestId. No automatic retries." try { $response = Invoke-WebRequest -UseBasicParsing -Uri 'https://openspeech.bytedance.com/api/v3/tts/unidirectional' -Method Post -Headers $headers -ContentType 'application/json' -Body $body -TimeoutSec 180 -MaximumRedirection 0 } catch { # Never echo raw transport errors: some clients embed headers or request bodies. throw "TTS transport failed or timed out. Billing may already have occurred. Check service logs using request_id=$requestId before retrying." } $content = $response.Content if ($content -is [byte[]]) { $content = [Text.Encoding]::UTF8.GetString($content) } $stream = New-Object IO.MemoryStream $complete = $false foreach ($line in ($content -split "`n")) { if (-not $line.Trim()) { continue } if ($complete) { throw 'Unexpected data after completion; refusing ambiguous response.' } try { $entry = $line | ConvertFrom-Json } catch { throw 'Malformed TTS response; not saving partial audio.' } if ($null -eq $entry.code -or $entry.code -notin @(0,20000000)) { # Service message is untrusted and may contain submitted text. Return only numeric codes. $safeCode = if ([string]$entry.code -match '^\d+$') { [string]$entry.code } else { 'unknown' } throw "TTS service rejected the request (code=$safeCode); no retry performed." } if ($entry.data) { try { $part = [Convert]::FromBase64String($entry.data) } catch { throw 'Invalid audio encoding in response.' } $stream.Write($part,0,$part.Length) } if ($entry.code -eq 20000000) { $complete = $true } } if (-not $complete -or $stream.Length -eq 0) { throw 'Incomplete or empty audio response; not saving and not retrying.' } New-Item -ItemType Directory -Path (Split-Path -Parent $OutputFile) -Force | Out-Null # CreateNew also protects against a second process producing the same output while this request runs. $file = [IO.File]::Open($OutputFile,[IO.FileMode]::CreateNew,[IO.FileAccess]::Write) try { $stream.Position=0; $stream.CopyTo($file) } finally { $file.Dispose() } $metadata = @{complete=$true;created_at=(Get-Date -Format o);request_id=$requestId;resource=$resource;speaker=$Speaker;sample_rate=24000;format='mp3';characters=$text.Length;text_sha256=$textHash;request_sha256=$requestHash;audio_sha256=(Get-AudioHash $OutputFile);needs_listening_review=$true} $metadata | ConvertTo-Json | Set-Content -LiteralPath $metaPath -Encoding UTF8 Write-Output "Saved: $OutputFile. Decode and listen for pronunciation, missing words and the ending before aligning captions." } catch { $message = $_.Exception.Message if ($plain) { $message = $message.Replace($plain,'[REDACTED]') } Write-Output ('TTS failed: ' + $message) exit 1 } finally { $plain=$null; $headers=$null; $content=$null; $response=$null if ($stream) { $stream.Dispose() } }references/automation-workflow.md6.0 KB1531e860d34bupstream ↗
# 完整成片流程 ## 1. 确定输入与复用资产 检查现有原稿、完整配音、样片意见、角色/配色参考、输出目录和工具。先按 [preflight-and-recovery.md](preflight-and-recovery.md) 实测所选路线:渲染必需能力与可选独立语音复核分别检查,复用本地已验证配置。已有批准就是继续工作的依据;不要每个镜头都问确认。原稿变更与读音调整留痕。 项目保存:`script.txt`(原稿)、`narration.txt`(合成输入,可有明确读音处理)、`assets/`、`DESIGN.md`、`timeline.json`、`index.html`、渲染日志和检查报告。项目按当前指令放置。 使用简短的项目状态文件记录稿件摘要、配音资产与来源、样片批准范围、每镜头素材/动画/检查状态、最近成功渲染路径。修改时从受影响阶段继续:仅改字重或配色不动配音;改口播后重新合成或剪辑相应音轨,并重新对齐受影响字幕和后续镜头。失败日志不保存密钥或原始请求头。 ## 2. 先配音,再定时长 遵循 [voiceover.md](voiceover.md)。时长由实际音频决定;镜头常为 4–6 秒但不是硬约束。用户有时长上限时,通过经授权的稿件调整或适度语速调整解决,不截断最后一句。 时间轴至少保存以下字段,单位为秒: ```json { "duration": 36.0, "audio_duration": 34.848, "narration_text": "完整原稿,必须与下面各段拼接一致", "alignment": "sentence_pause_estimate", "scenes": [ {"n": 1, "start": 0.0, "end": 4.0, "caption": "对应原文"} ] } ``` 上面是字段说明,不是可直接通过检查的完整数据。实用值必须替换为真实全稿与所有镜头。字幕与合成读音文本不同时记录差异原因,不能静默把 ASR 错字覆盖原稿。 ## 3. 做视觉编排表 每镜头记录:起止时间、旁白原文、类型(人物情景/知识图形/实际素材)、最终构图、第一/第二/第三次变化、转场、素材来源、待验证项。不为凑数强加三次变化。画面应在对应概念被讲到时出现。 人物负责引入疑惑、体验和提醒;流程、关系和对比优先用知识图形。屏幕操作与事实截图用真实素材。只按“每句换一张图”安排视频不能保证解释质量。 先按主 Skill 的路线表确认视觉意图。用户要求画面被逐笔画出时,改读 [stroke-story-workflow.md](stroke-story-workflow.md),视觉编排表以“共享画布 + 语义区域 + 开始时间”为主,不再按 SVG 独立场景设计。只有流程卡片、关系图和独立元素动画继续使用本页后续的 HyperFrames 规则。 ## 4. 制作可控素材与动画 程序动画模式默认使用已安装的 HyperFrames 技能;制作前读它的作者规范、CLI 和相关动画参考。工具缺失先报告可行安装/替代,不把技能文件存在当作运行环境正常。 可复制 `examples/program-animation/skill-demo/` 到新工作目录参考:人物独立手臂、气泡依次出现、卡片收拢到书、分步流程、材料归集、复用箭头、闭合权限锁、放大镜检查。先运行 `npm install` 获取固定版本依赖;换主题时重做文稿与语义关系,不能只改标题。 工程细节: - 使用本地素材与本地 GSAP;字体声明明确,系统中文字体可使用 `@font-face` 的 `local()`,可移植交付时注明依赖或嵌入有授权字体。 - SVG 外层固定构图坐标,内层命名组做动画,避免父子坐标混淆导致手臂飞走。 - 未来场景的初始隐藏状态写在明确 CSS ID 规则中;不要只依靠暂停时间轴 t=0 的 `set()`。 - 动态手臂替代原手臂,不能保留两份形成多手人物。放大镜、卡片、气泡不得误挡角色或字幕。 - 同一属性不同时被多个动画控制;用有限重复、确定性的时间轴和框架规定的同步注册。 - 把最长标题、字幕和最终同时可见元素排好,再加进入动作。合法的短暂转场交叠需实际查看,不能批量忽略所有碰撞。 - 结尾留适量阅读停顿,结束后不突然跳回首帧或留黑画面。 复杂自然动作才使用视频模型。此前生成的图片不一定可直接拆成透明图层;需要拆层/重新生成或改为 SVG 时,说明质感变化。用户已批准的简化手绘方式无需再次确认。 ## 5. 环境和渲染 先检查 Node、可工作的完整 FFmpeg/FFprobe 和渲染浏览器。先运行版本检查、音频探测和 H.264 编码器检查,再长时间渲染。 已验证 HyperFrames 0.8.20;新项目按当前工具帮助选择并固定版本,不机械升级旧工程或批量改全局设置。用官方 CLI 初始化可用项目,保留它的项目指令;初始化的远程技能下载失败不等于本地已有插件失效,分别核实。 本次实测坑:某些剪辑软件内置 FFmpeg 能解码但无 `libx264`/`crf` 支持;复制共享版 exe 会因缺 DLL 无法启动。不要反复拿同一不完整组件重试。使用完整发行版,或当前可用的 `imageio_ffmpeg.get_ffmpeg_exe()`;后者不保证附带 FFprobe,需要单独查找有效 FFprobe。 可在进程范围指定 `HYPERFRAMES_FFMPEG_PATH` / `HYPERFRAMES_FFPROBE_PATH`,不要改系统 PATH;本机缓存的浏览器路径也不是可移植配置。 先检查代表场景、最长字幕和转场,再运行当前 CLI 的 `check`(或对应版本的 lint/validate/inspect)。修复完成后验证 3–5 秒内部样段,再导出完整 MP4;不在排版检查尚未完成时启动全片。初次一般 2 个渲染 worker,按机器资源调节。长命令保存日志并反馈实质进展。编码失败只修环境/重新渲染,不重新请求 TTS 或所有图片。 ## 6. 检查和交付 执行 [quality-and-delivery.md](quality-and-delivery.md)。先样片的请求只交样片;样片已批准且要求全片时一直做到全片完成。完整成片应带可编辑工程及音频,不能让用户自己从代码导出才能观看。references/hand-drawn-video-prompts-LICENSE.txt1.0 KBa8fc602a6029upstream ↗
MIT License Copyright (c) 2026 kaomei Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.references/output-example.md8.4 KBd5e5e0181fd8upstream ↗
# 输出示例:AI CapEx 七镜头 这是 1.0 的格式示例,严格使用当前 AI CapEx 文案的 7 个镜头,不加入无关人物或额外风格测试镜头。完整测试输出见项目 `outputs/q-doodle-flow-skill-v1-ai-capex-test.md`。 ## 镜头索引 | 镜头 | 对应口播 | 时长 | 视觉隐喻 | 后期关键词 | |---|---|---:|---|---| | 01 模型榜失宠 | “谁发了最强模型”已经没人看了。 | 6 秒 | 分析师把冠军奖杯推开,用放大镜盯电表 | 模型榜失宠 | | 02 开始算账 | 现在华尔街死盯着大厂的电费单和折旧表。 | 6 秒 | 电费单与折旧账本压在天平两端 | 开始算账 | | 03 财报试金石 | 四大巨头的财报将是 AI 赛道真正的试金石。 | 6 秒 | 四位 Q 版商业人物参加财报考试 | 财报试金石 | | 04 算力豪赌 | 大厂合计要砸下约 7000 亿美元买算力。 | 6 秒 | 四辆 GPU 手推车推向会吞硬件的机器 | 约7000亿美元 | | 05 三张压力单 | 自由现金流、云毛利、能源成本都承压。 | 6 秒 | 三张卡片分别漏水、被压扁、被电表拖拽 | 成本反噬 | | 06 收入与成本赛跑 | AI 商业化赚的钱跑输了资本开支和电费。 | 6 秒 | 黄色收入硬币被三头成本怪物追赶 | 收入跑得赢吗 | | 07 革命还是吞金兽 | 你觉得 AI 是生产力革命还是吞金兽? | 6 秒 | AI 机器站在生产力与吞金岔路口 | 你站哪边 | ## 完整镜头示例:01 ```text 镜头 01 对应口播:“谁发了最强模型”已经没人看了。 建议时长:6 秒 视觉隐喻:模型冠军奖杯被推到一旁,分析师用放大镜改盯电表。 后期关键词:模型榜失宠 【Flow 生图提示词】 Create a vertical 9:16 modern Q-version hand-drawn crayon illustration on clean warm-white sketchbook paper. A natural Q-version market analyst in the center pushes a golden blank champion trophy toward the left while raising an oversized cobalt-blue magnifying glass toward a simplified gray electricity meter on the right. Use thick imperfect black hand-drawn outlines, sunflower yellow, cobalt blue and tomato red, 3–5 large visual groups, a central subject group occupying about 65% of the width, and generous blank space above and below. Keep all faces illustrated and restrained. No readable text, model names, numbers, logos, watermark, photorealism, 3D, cyber HUD, vintage newspaper style or extra decorations. 【Flow 图生视频提示词】 Create a 6-second vertical 9:16 tactile 10–12 fps paper stop-motion assembly. Start from the supplied completely blank warm-white paper frame and end on the supplied final illustration. Use a locked flat frontal camera. The golden blank trophy slides in from the left, the Q-version analyst pops into the center and pushes it aside, then raises the cobalt-blue magnifying glass. The gray electricity meter slides in from the right; the glass swings once and locks over its dial. Preserve the exact final character, paper texture, thick black crayon linework and sunflower-yellow/cobalt-blue/tomato-red palette. Hold the exact end frame for the final 0.8 seconds. No camera drift, zoom, parallax, lip sync, face morphing, new characters, text, logos, watermark or audio. ``` ## 完整镜头示例:04 ```text 镜头 04 对应口播:2026 年这些大厂合计要砸下约 7000 亿美元买算力。 建议时长:6 秒 视觉隐喻:四位 Q 版商业人物推着 GPU 手推车,集体把硬件送进一台贪吃的红色算力机器。 后期关键词:约7000亿美元 【Flow 生图提示词】 Create a vertical 9:16 modern Q-version hand-drawn crayon illustration on clean warm-white sketchbook paper. Four restrained Q-version business leaders push four cobalt-blue carts filled with blank sunflower-yellow GPU chips toward one giant tomato-red compute machine with a playful open mouth. Keep the people natural rather than distorted; let the carts and machine carry the exaggeration. Arrange the leaders and carts on the left and the machine on the right, centered in the middle 65%–70% with clean upper and lower breathing space. Use thick imperfect black hand-drawn outlines and bold crayon blocks. No readable text, currency figures, logos, watermark, photorealism, 3D, factory background or cyber HUD. 【Flow 图生视频提示词】 Create a 6-second vertical 9:16 tactile 10–12 fps paper stop-motion assembly from the supplied completely blank warm-white paper frame to the supplied final illustration. Lock the flat frontal camera. The tomato-red compute machine slides in from the right, then four cobalt-blue carts roll in from the left, followed by the four Q-version leaders pushing together. Blank yellow hardware bounces gently in the carts; the machine mouth opens once. Preserve exact faces, proportions, crayon texture and color palette. Settle into the supplied end frame and hold for the final 0.8 seconds. No camera drift, zoom, parallax, walking cycle, face morphing, new people, text, numbers, logos, watermark or audio. ``` ## 完整镜头示例:05 ```text 镜头 05 对应口播:亚马逊自由现金流逼近归零,微软云毛利承压,谷歌能源成本飙升。 建议时长:6 秒 视觉隐喻:三张空白压力卡片分别漏水、被重物压扁、被红色电表拖住。 后期关键词:成本反噬 【Flow 生图提示词】 Create a vertical 9:16 modern Q-version hand-drawn crayon illustration on clean warm-white sketchbook paper. Show three large blank finance cards side by side: a blue cash tank with one yellow drop remaining on the left, a blue cloud squeezed by a yellow weight in the center, and a small data-center block pulled by a tomato-red electricity meter and cable on the right. Add three imperfect red grading circles around the problem objects. Use thick black hand-drawn crayon lines, sunflower yellow, cobalt blue and tomato red, with the three-card group occupying about 88% of the width and clean margins. No words, letters, numerals, tables, logos, watermark, 3D, realistic machinery or UI. 【Flow 图生视频提示词】 Create a 6-second vertical 9:16 tactile paper stop-motion infographic. Start from the supplied completely blank warm-white paper frame and end on the supplied final three-card illustration. Lock the flat frontal camera. Slide in the three blank cards from left to right. Pop in the cash tank and let one yellow drop fall, drop the yellow weight onto the blue cloud once, then slide in the data-center block and red meter so the cable pulls taut. Draw the three red grading circles one after another. Preserve rigid flat paper pieces, exact layout, crayon texture and final palette; hold the end frame for 0.8 seconds. No zoom, UI animation, numbers, words, logos, extra cards, morphing, watermark or audio. ``` ## 完整镜头示例:07 ```text 镜头 07 对应口播:你觉得 AI 是生产力革命还是吞金兽? 建议时长:6 秒 视觉隐喻:AI 机器站在生产力符号与吞金嘴的岔路口,等待观众按下选择开关。 后期关键词:你站哪边 【Flow 生图提示词】 Create a vertical 9:16 minimal modern Q-version hand-drawn crayon illustration on clean warm-white sketchbook paper. Place one friendly white AI machine at a fork in the center. On the left, a cobalt-blue gear, sunflower-yellow rocket and tomato-red upward arrow form one productivity group. On the right, the machine opens a playful red mouth toward a short stack of yellow coins. A human hand reaches from the bottom toward a small muted-green switch. Use thick imperfect black hand-drawn outlines, bold crayon blocks, 3–5 large groups and generous blank space. No words, letters, numbers, logos, watermark, photoreal robot, glossy 3D, cyberpunk, UI panels or background room. 【Flow 图生视频提示词】 Create a 6-second vertical 9:16 tactile 10–12 fps paper stop-motion assembly. Start from the supplied completely blank warm-white paper frame and end on the supplied final illustration. Lock the flat frontal camera. Draw the two forked path lines upward, drop in the rigid white AI machine, then pop out the blue gear, yellow rocket and red arrow on the productivity side. Open the red mouth once and slide the yellow coin stack toward it. A hand rises from the bottom and presses the green switch once. Preserve exact shapes, crayon linework, paper texture and palette, then hold the exact end frame for the final 0.8 seconds. No camera movement, zoom, parallax, smooth 3D motion, morphing, new symbols, text, logos, watermark or audio. ```references/preflight-and-recovery.md5.4 KBe355427cf87aupstream ↗
# 运行预检与故障恢复 完整制作第一次进入配音或长渲染前读取本页;同项目仅改文案/颜色且环境未变时复用已有检查。提示词模式不执行环境检查。 ## 用执行结果选环境 不按默认 `python`、包可被搜索到、文件夹存在来判断能力。先选已验证的独立环境;运行库升级、模型路径变动或环境被清理后重新实测。机器路径放在本地配置(Windows 可放 `%LOCALAPPDATA%/CodexVideo/runtime.json`),不要写进可分发技能或工程 ZIP。配置不是成功证明。 `scripts/preflight.py` 只做本地检查,不读密钥、不调用配音、不安装依赖。配置字段:`node`、`hyperframes_cli`(CLI 的 JS 入口绝对路径)、`chrome`、`ffmpeg`、`ffprobe`、`media_python`;独立语音复核另加 `asr_python`、`asr_model`(实际模型快照目录)。按当前机器发现文件并填入,不复制别人的路径。 逐笔故事模式另外运行 `scripts/stroke_story_preflight.py`。它检查仓库内置的 `vendor/srt-whiteboard-animation`、隔离 Python、`skeleton`/`contour-wipe` 参数,并在临时目录完成一个无网络的小型 MP4 渲染与解码。它不会安装依赖或调用收费接口;具体命令见 [stroke-story-workflow.md](stroke-story-workflow.md)。 ```text python <skill>/scripts/preflight.py --config <local-runtime.json> --mode render --report <project>/preflight-render.json python <skill>/scripts/preflight.py --config <local-runtime.json> --mode asr --audio <existing-local-audio> --report <project>/preflight-asr.json ``` 渲染检查会真实编码三帧 H.264、探测生成文件、通过当前 CLI 依赖启动 Chrome 并截图。ASR 检查会先核实非空模型权重、配置和词表,再在独立子进程中实际加载模型并推理;提供已有音频时只用前五秒。不能把导入成功或空模型缓存当成可运行。 本机本次验证通过的是 Python 3.12 独立环境、faster-whisper 1.2.1 / CTranslate2 4.8.1;完整依赖组合见 `scripts/asr-requirements-tested.txt`。这是可复现组合,不是所有机器都必须升级到该版本。建立独立环境时依照安装技能,不改系统 PATH 或其他项目环境。先用已有音频测试,不为预检重新收费配音。 ## 选择当前发行版支持的检查工具 优先运行当前 HyperFrames CLI 的 `check` / `inspect` / `snapshot`。部分技能附带的动画映射脚本直接依赖开发包 `@hyperframes/producer`,CLI 发行版不一定提供这个独立包;不能把“CLI 能运行”推导成“所有附带脚本依赖齐全”。 需要细粒度动画映射且工程是单页、内联 SVG/HTML/GSAP 时,可使用本技能的兼容入口(参数均取本地配置): ```text node <skill>/scripts/animation-map.mjs <project> --cli <hyperframes-cli-entry> --browser <chrome-executable> --width 1080 --height 1920 --frames 2 --out <project>/animation-map ``` 它沿用原映射逻辑,通过 CLI 所在依赖树发现 Puppeteer,不要求单独安装开发包,也不硬编码 npm 缓存目录。此入口不模拟 HyperFrames 嵌套合成/视频同步,遇到外部子合成或视频会明确拒绝;改用官方 CLI 检查与实际 MP4 验证,不把缩减版映射冒充完整引擎检查。 ## 按失败类型恢复 - DLL 初始化失败、访问违规:记录解释器和依赖版本,将该组合标记为本次不可用。切换经预检的隔离环境;无任何变化不再重跑同一命令。仅凭另一个环境成功,不能断言具体哪个 DLL 或单个版本就是根因。 - 模型只有目录、权重缺失:不启动加载。选择已完整可用的模型;确需下载时先核实体积、磁盘和网络,不为了可选加强检查自动下载数 GB。 - 检查脚本缺开发依赖:使用上述兼容入口或当前 CLI 的公开能力;不临时修改全局插件文件。 - 浏览器检查超时:保存阶段和日志,先查看进程是否仍有进展;确认停滞后终止本次子进程,允许切换 `--no-browser-gpu` 后做短片/截图测试。软件模式不是普遍更快,不强制套用。 - UTF-8 中文文件被系统 GBK 解码:文件读写显式指定 UTF-8,必要时对子进程设置 `PYTHONUTF8=1`,不修改系统区域设置。 - 布局错误:修画面,保留已通过的音轨。固定眉题、角标尽量放在场景外共享层;转场标题叠化与正常场景文本冲突分别判断,禁止批量忽略碰撞。 预检失败只阻止依赖该能力的阶段。原生有效词时间戳可用于字幕对齐;独立 ASR 是额外复核,失败不等于配音失败,但必须披露复核缺口,不能改用静音分析后宣称已逐词验收。没有工具可以证明语气自然或英文读音完全正确时,保留待试听状态。 ## 长渲染之前与之后 顺序为:确定最终静态构图 → 代表场景、长字幕和转场检查 → 完整工程检查通过 → 长渲染。不要一边仍改布局、一边先启动全片渲染。用 3–5 秒内部样段覆盖人物动作与至少一次转场,确认有画、有声后继续全片;不重复向用户索要已确认风格。 最终仍需实际 MP4 全解码、逐场景/转场抽检与结尾核对。修复工具、代码返回 0、HTML 通过检查,都不等于成片已经验收。保存实际工具路径、版本、预检结果和已成功阶段,下一次从记录继续,但在环境改变后重新验证。references/prompt-workflow.md1.8 KB2e0d81a10b6bupstream ↗
# 原仓库提示词模式 仅在用户要求提示词、或明确选择 Flow/Nano Banana 外部生成时使用。本模式不调用 API、不购买额度、不渲染视频。 未指定其他画风时,读 [style-guide.md](style-guide.md) 获取原 Q 版蜡笔画风与 Flow 首尾帧语法;用户提供参考图时读 [style-selection-and-updates.md](style-selection-and-updates.md),替换不一致的配色、笔触、比例与背景描述。下面的 Q 版蜡笔示例不是所有风格的固定要求。[output-example.md](output-example.md) 是题材示例,其事实不是新任务的事实来源。 按语义拆分,常见每镜头 4–6 秒但以稿件与用户要求为准。每镜头一个核心视觉隐喻,每条提示词自包含,不使用“同上”。 ```text 镜头 01 对应口播: 建议时长: 视觉隐喻: 画面中文关键词: 【生图提示词】 完整英文描述:9:16、#F8F6EF、自然克制 Q 版人物、粗黑手绘线、黄/蓝/红色板、具体位置关系、主体与字幕安全区。 【图生视频提示词】 完成插画作 Last Frame、空白暖白纸作 First Frame;locked camera、rigid paper cutouts、tactile paper stop-motion;明确哪个物件先出现、人物何时动作、怎样落到尾帧。no lip sync、no added characters/logos、no audio。 【实体准确性提醒】 哪些文字、旗帜、Logo、日期、金额应使用原始资产或确定性后期图层。 ``` 仅单张参考图时改为原位微动作,不要求不存在的首帧控制。不要保证生成模型像素级保持背景、中文或国旗准确。短关键词可提供直接生成版,同时给无字安全版;长文字与精确数字默认后期。 只写提示词时不引入配音配置、工程打包或样片批准流程。references/q-human-story-style.md1.5 KBb79cd024d422upstream ↗
# 自然肤色 Q 版人物故事 用于人物传记、历史事件和真实人物观点。小黑风格适合抽象观点与隐喻,不应把它套在真实人物身上,更不能把人物的脸和身体画成黑色。 ## 人物锚点 - 自然肤色、完整人的身体,约 3–4 头身;五官清爽、轮廓帅气但不过度美化。 - 为青年、中年、晚年分别记录发型、胡须、脸型、服装和代表道具。 - 同一年龄阶段保持脸型、眼镜、服装色和身材比例稳定。 - 用姿态和道具表达事件,不依赖浮动标签或大段文字。 ## 画面规则 - 纯白或浅暖纸面,深色干净轮廓、有限平涂、低纹理和充足留白。 - 一个场景聚焦一个事件;多事件优先拆幕,只有天然并列关系才使用双语义岛。 - 源图不生成 Logo、日期、产品名或长中文;在后期准确叠加。 - 字幕安全区默认保留底部约 18%,主体脸部和关键道具避开该区域。 ## 人物传记提示词补充 ```text Create a handsome, natural-skin chibi human portrait with a complete human body, about 3.5 heads tall, in a clean hand-drawn editorial storybook style. Preserve these age anchors: [发型/胡须/服装/道具]. Sparse dark outlines, limited flat color, low texture, generous negative space. No black face or black body, no mascot replacement, no pseudo-text, no logo. ``` 乔布斯示例采用青年长发、创业期黑发、中年短发与晚年灰胡须/圆眼镜等阶段锚点;这些只是案例人物特征,不是所有人物的通用模板。references/quality-and-delivery.md4.6 KB18272d0f90a0upstream ↗
# 验收与交付 执行前先按 [预检与恢复](preflight-and-recovery.md) 确认所需能力实际可运行;动画映射脚本与 CLI 的依赖须分别核实。固定共享文字避免在转场中重复叠加,正常文本碰撞修复后再长渲染。 ## 不同层级分别验证 1. **文本**:原稿逐段与字幕比较,限定词/数字不得少;同音替换与读音稿另存。英文旁白与展示文本之间可以有已解释差异。 2. **工程**:按当前 HyperFrames 版本运行完整检查,修复脚本、字体、隐藏场景、出框和动画冲突。转场信息提示逐一查看,不用忽略属性掩盖正常场景问题。 3. **实际成片**:完整解码 MP4 的视频与音频,检查时长、帧率、尺寸、峰值与结尾。每个场景至少抽看一帧,并加看人物动作峰值、转场与最后一帧;抽图不能替代必要的动态观看/试听。 4. **内容动作**:验证手/物件分别移动、阅读顺序跟随讲解、锁仍闭合、没有多手/缺肢、错误遮挡或中文变形。画面中只存在进度条运动不能证明主体动画有效。 逐笔故事模式额外检查:首帧无提前露线;笔尖贴近当前新增墨线;手部转向和跨笔画时速度自然且不抢画面;未开始区域和保护区不泄漏;已完成区域持续保留;逐幕最后 0.3–0.5 秒与批准源图对照,不能残留浅色衣物或纸纹造成的漏色白斑。两个以上语义区域时,必须加看前一区域完成前约 0.2 秒和后一区域开始后约 0.2 秒。关键词层要检查显现中段、完成帧及与人物/字幕的碰撞。`contour-wipe` 只能称为轮廓感知上色,不能描述成恢复了真人上色笔顺。 多幕逐笔视频还要检查每个切点前后至少 3 帧以及最终视频最后 0.3–0.5 秒,确认没有短黑帧、重复帧、时间戳回退或突然叠入的裁切/放大源图。无损 concat 或 PyAV 合并失败时不要反复重试相同命令;改用 `finalize_stroke_video.py` 在统一帧率、尺寸和时间基准下重新编码。脚本默认 `--source-overlay never`;源图补全只在末帧对照确认漏色后显式启用,不得覆盖已经完整的逐笔过程。 某些版本的工程截图检查一次只覆盖少数时间点,传入全部镜头时间不代表全部截图都生成。核对实际图片数量与镜头数;必要时分批检查。自动生成的联系表只取每镜头一个时点,需另外查看进出场、动作峰值和末帧。 ## 可复用检查器 ```text python <skill>/scripts/media_check.py --video final.mp4 --timeline timeline.json --report verification.json --contact-sheet contact.jpg --width 1080 --height 1920 --fps 30 ``` 依赖 PyAV、NumPy;导出联系表另需 Pillow。先使用可用隔离环境,不随意更改其他项目依赖。`timeline.json` 采用自动成片参考里的 schema,可将 `narration_text` 写入后校验所有 caption 拼接;没有原稿时报告“未校验内容”而不是默认通过。 该工具检查真实文件、帧数、音频数值、音轨/时间轴覆盖,并报告主体区域的运动统计。画幅和帧率按实际要求传入;默认运动区域排除顶部 23% 和底部 26%,不同布局用 `--motion-roi X0 Y0 X1 Y1` 指定归一化边界。统计不能区分整图平移与独立人物运动,低运动量标为待复核提醒。`alignment` 必须如实记录,检查器不执行语音识别、不证明语义同步、不评判人物美感,自动成功不能代替看片。退出码 0 仅表示本次自动检查无错误,报告中的警告与人工检查仍须处理。 自动检查同样无法判断语义岛是否提前泄漏、关键词是否压脸,以及片尾是否发生内容正确但比例错误的源图覆盖;这些项目必须查看真实边界帧。 可用 `--timeline-only` 对时间轴及正文一致性作离线校验,不渲染、不调用任何付费接口。 ## 交付物 最终 MP4;字幕 SRT;完整原稿;独立配音;封面(需要时);时间轴 JSON;可编辑工程 ZIP;简短制作说明与验证报告。样片任务不必交全部工程。可编辑指保留源工程,不等于普通播放器能修改。 ZIP 必须包含实际运行需要的资源,使用相对引用,无密钥/绝对用户目录/临时文件;声明外部字体及运行依赖。原稿与配音重用时不重复扣费,调用记录与实际账单分清。 最后在对话中展示/链接真实 MP4,用当前任务要求的绝对输出路径。报告实际时长、分辨率、已完成范围及已知限制;不能把缺少后半段的样片称为完整片。references/semantic-island-storytelling.md5.6 KBf6c3bfe7a110upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/stroke-story-workflow.md13 KB196963ef6bf9upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/style-guide.md6.7 KBa01876611c02upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/style-selection-and-updates.md4.9 KB67a1d06e70b7upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/upstream-whiteboard-review.md2.1 KBc6ae5a5a53c4upstream ↗
# srt-whiteboard-animation 上游借鉴记录 复核来源:<https://github.com/geeklee/srt-whiteboard-animation>,以及该仓库尚未合并的 PR #4。上游代码遵循 MIT License;复制代码时保留原许可证和署名。本记录用于后续维护时避免重复调研,也避免把实验性改动直接当成稳定默认值。 ## 已吸收 - 字幕语义驱动的 `sequence` / `startMs` / `protectedRegions` 编排; - 持久画布和区域内 stream 连续笔迹,采用 `ink → color`; - 渲染前标注预检:画布、坐标、保护区、时序窗口和凝视时间; - 空允许掩码仍写满原时间窗,避免后续画面提前; - `--hand-height` 与 `--hand-follow` 分开控制,分别解决遮挡和移动观感; - 不同尺寸、帧率和时间基准的片段统一重编码后合并。主 Skill 通过 `finalize_stroke_video.py` 实现这一点。 ## 已用自己的方案覆盖 - 上游按单条 SRT 合成 edge-tts;本 Skill 保持用户选择的整段配音和真实音频时间轴,不因画面窗口过短强制加速语音; - 上游主流程偏 25–35 秒单幅白板;本 Skill 对多事件故事优先拆为 4–8 秒连续横屏场景,以保持人物尺度和故事性; - 上游基础合并器负责静音画面;本 Skill 的最终收尾同时处理批准源图补全、旁白、ASS 字幕和统一时间基准。 ## 不设为默认 - 小黑风格、极简线稿:可作为用户指定画风,不覆盖已确认的自然肤色 Q 版人物; - 每幕强制标题和 2–4 个手写要点:知识讲解可选,历史故事默认由画面和字幕表达; - 默认封面:只有发布需要时增加; - 橡皮擦幕间过渡:先做样片。它可能引入第二只大手并打断故事连续性; - 自动把语音压进字幕窗口:默认延长画面或调整分镜,不牺牲已确认配音的故事感。 ## 后续更新判断 查看上游更新时先区分 `main` 与未合并 PR。只吸收能够用真实样片验证、且不改变已确认画风和配音的机制。任何新默认项至少通过:标注错误用例、空掩码用例、复杂群像样片、多幕合并和最终音画检查。references/voiceover.md4.4 KBea690812b6e1upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/xiaohei-style.md2.4 KB9fe3b7461505upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
.env.example101 Bdb734de0e12aupstream ↗
# Optional provider credential. Leave empty unless you choose this provider. VOLCENGINE_TTS_API_KEY=.gitattributes177 B69acb38576c0upstream ↗
* text=auto *.ps1 text eol=crlf *.py text eol=lf *.md text eol=lf *.json text eol=lf *.png binary *.jpg binary *.jpeg binary *.wav binary *.mp3 binary *.mp4 binary *.zip binary.gitignore296 B5b41a41517c6upstream ↗
__pycache__/ *.py[cod] .venv/ venv/ .env .env.* !.env.example preferences.local.json runtime.local.json *.dpapi *.key *.pem *.p12 *.pfx *.log .DS_Store Thumbs.db node_modules/ examples/program-animation/skill-demo/assets/gsap.min.js dist/ output/ outputs/ render/ tmp/ temp/ models/ model-cache/agents/openai.yaml446 Bfcacbcad1695upstream ↗
interface: display_name: "Nikola 手绘讲解视频" short_description: "制作逐笔故事或程序图形的中文手绘视频" default_prompt: "使用 $hand-drawn-explainer-video-nikola 把我的中文内容制作成手绘讲解视频;先选择逐笔故事或程序动画,逐笔路线再选择画面结构与 Q 版人物、小黑风格等视觉风格,成片默认沿用火山引擎刘飞配音,并在交付前验证真实 MP4。"config/runtime.example.json380 Bbda14058d7acupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
CONTRIBUTING.md887 Bac47ab0b93b1upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
docs/ARCHITECTURE.md833 B092f7bd35d58upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
docs/assets/volcengine-seed-tts-2-setup.png476 KB1dafbd8ddeaeupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
docs/CONFIGURATION.md1.5 KB6e0b9bcd1555upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
docs/INSTALL.md4.2 KB5c11462f1fb0upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
docs/STYLES.md2.5 KB02c29ca75187upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
docs/TROUBLESHOOTING.md2.5 KB5ce45bdca713upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
evals/evals.json4.5 KBf11c5a01b768upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/assets/narration.wav1.6 MB444cbb44b370upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/DESIGN.md1.2 KBd51839ca0520upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/hyperframes.json318 Bdc9ec2eb28c6upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/index.html37 KB25dbc8b9ec39upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/package-lock.json557 B6b1d2394bd4cupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/package.json513 Bc594e9d4267fupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/preview.png476 KB4730ac20f567upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/script.txt567 Bd7063ae2e4ceupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/timeline.json2.1 KBd6974dfb64c8upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/what-is-skill-sample.mp43.5 MBa406e11adf10upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/program-animation/skill-demo/使用说明.txt834 B1e5c31d7a0bdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/steve-jobs/annotation.json1.3 KBdc4493dc0eecupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/steve-jobs/regions-preview.png1.2 MBe500b288687eupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/steve-jobs/semantic-island-sample.mp41.2 MB133243da9519upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/steve-jobs/source.png1.3 MBa24abe2318faupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/steve-jobs/steve-jobs-biography.mp412.9 MBc59493459e55upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/steve-jobs/transition-contact.jpg192 KBd70143a76f70upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/yuefa-sanzhang/editable-project.zip19.1 MB09fc82796de5upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/yuefa-sanzhang/hand-speed-contact-sheet.jpg1.4 MB60f8d0514762upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/yuefa-sanzhang/seven-scenes-final-frames.jpg1.0 MBf15d03803341upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/yuefa-sanzhang/timeline.json2.0 KB0349580b2200upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/yuefa-sanzhang/verification.json1.8 KB1bba104bcfcdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
examples/stroke-story/yuefa-sanzhang/yuefa-sanzhang-16x9-stroke-story.mp427.9 MB7fbcb5842387upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
LICENSE11 KB261eeb9e9f8bupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
LICENSE-MEDIA.md728 Bd5a68926bb75upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
preferences.json744 B77c0e915f569upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
requirements-media.txt70 B76c8893c9b9cupstream ↗
av>=14,<19 numpy>=2,<3 opencv-python-headless>=4.10,<6 Pillow>=11,<13SECURITY.md589 B61032b687caaupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
SKILL.zh-CN.md1.4 KBc4db4d546d1cupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
THIRD_PARTY_NOTICES.md2.9 KB08e151304959upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/hi-nikola-hand-drawn-explainer-video-nikola.md