Completed Talking-Head Video
Official Source
This Skill is authored and maintained by chengfeng / AI产品自由.
https://github.com/Agentchengfeng/chengfeng-videocut-skills
Official Accounts: GitHub @Agentchengfeng; X @chengfeng240928; Xiaohongshu / WeChat Official Account / Bilibili / Douyin / WeChat Channels AI产品自由.
Core Workflow
This Skill solves one thing: turning a talking-head video into a complete finished video; the output aspect ratio and animation style are determined by user configuration.
+-----------------------------+
| Input |
| Video + Subtitles + Optional Assets |
+--------------+--------------+
|
v
+-----------------------------+
| 1. Storyboard |
| Semantic segmentation + task type + visual source |
+--------------+--------------+
|
v
+-----------------------------+
| 2. Timeline Preview |
| Align original video/screenshots/HTML with speech |
+--------------+--------------+
|
v
+-----------------------------+
| 3. Synthesis |
| Export final MP4 according to user config ratio |
+--------------+--------------+
|
v
+-----------------------------+
| Validation |
| ffprobe + keyframe inspection |
+-----------------------------+
Do not present cue tables, HTML modules, review player, final player, or export scripts as separate user workflows. They are implementation details within "Timeline Preview" and "Synthesis."
User Configuration
Every time this Skill is executed, first read:
用户配置/default.json
The configuration only defines the user's current selection:
{
"aspectRatio": "3:4",
"animationStyle": "xiaohei"
}
Supported values:
3:4: Default vertical HD; logical canvas1080x1440; exports at DPR1.5for1620x2160.16:9: Horizontal; logical and export canvas1920x1080.4:3: Horizontal; logical and export canvas1440x1080.animationStyle: Defaultxiaohei; options from动画/styles.json.
Command-line arguments override user configuration; when no explicit parameters are given, the export script reads aspectRatio and the animation script reads animationStyle. Temporary ratio overrides with:
--config /path/to/config.json
--ratio 16:9
--aspect-ratio 16:9
--width 1920 --height 1080
--dpr 1.5
Do not include visual preferences, templates, encoding quality, output directories, subtitle margins, or other various settings in 用户配置/default.json. User configuration only holds the current selection; the animation directory only holds the options registry and specific style implementations.
Animation Style
The currently selected animation style is placed in 用户配置/default.json:
animationStyle
The animation directory only registers options:
动画/styles.json
xiaohei maps to:
动画/ian-xiaohei-svg-motion/
When a storyboard or HTML module needs explanatory animations, flow animations, or hand-drawn-style highlights, default to the xiaohei comic-style SVG motion effects. Do not invent new animation styles on the fly unless the user explicitly specifies otherwise.
Input
First locate these files:
- Main video:
source_cut.mp4,*_cut.mp4, or a user-specified edited video. - Subtitles:
subtitles.srt,video.srt, orsubtitles_with_time.json. - Optional script: article, voiceover script, body draft; only used to understand intent.
- Optional assets: screenshots, product pages, comment images, result pages, proof pages in
assets/. - Project rules: if the current project has
AGENTS.mdorREADME.md, read it first.
Truth source priority:
Actual audio / subtitles > Edited video visuals > Asset files > Script draft
If the script and actual subtitles differ, defer to the subtitles and audio.
Step 1: Storyboard
Default to creating an HTML storyboard review page first; do not start with a Markdown table.
The pre-storyboard workflow must follow this order:
- Segment by speech semantics: combine one, two, or three sentences that discuss the same concept, action, or evidence into one segment; do not mechanically split by subtitle number.
- Determine the visual task for each segment: is it a workflow demonstration, original image explanation, result proof, conceptual organization, or pure text expression.
- Decide the visual source: for segments that can use real screen recordings, original screenshots, or original images for proof, prioritize the original material; only design HTML / xiaohei animations for conceptual explanations where the current screen is mainly text, white space, or weakly related visuals.
- Only then proceed to specific visual design: for each HTML / xiaohei animation segment, first write down its independent metaphor and action, then implement the module.
Common path:
review/storyboard-audit-vN.html
Default template:
templates/storyboard-audit.html
The storyboard should answer the user's question:
When this sentence is spoken, what should the audience see?
At minimum, clearly specify for each segment:
- Time range
- Subtitle number
- Full spoken text
- Semantic segmentation rationale
- Visual task
- Visual type:
Original Video,Operation Screen Recording,Original Screenshot,Original Image,Infographic Focus,HTML Animation,Text + Animation - Asset source
- Camera action
Visual selection rules:
- Operation demonstrations: use the original video / original screen recording; do not convert to abstract animations.
- When explaining image content, chart content, error screenshots, product screenshots: use the original image or original screenshot directly; animations only for circling, annotating, and local focus.
- Real operations, proof pages, result pages, segments requiring credibility: retain original video or original screenshot.
- Screen recordings / original video segments default to full original display; only if segmentation explicitly needs to avoid subsequent unified subtitles, mark that segment as a screen-recording small window and leave subtitle-safe space at the bottom. Do not batch-apply the small-window rule to all screen recording segments.
- Conceptual organization, mechanism relationships, system division, opinion summarization where the current screen is mainly text, white space, or weakly related visuals: create HTML / xiaohei animations.
- Abstract segments that can be understood with brief text: use text + animation; text handles naming, animations handle relationships and actions.
- Existing screenshots or infographics: reuse them first; do not redraw.
- When the same image appears multiple times, each occurrence must serve a different purpose: overview, local focus, comparison, result re-examination.
- Do not make all animations use the same dynamics. Each animation segment must first design its action metaphor independently, then implement.
Hard storyboard standards:
- One page presents only one concept, one action, or one case. If the same speech segment contains two independent cases, it must be split into two pages; do not cram two cases into the same table or same animation to save pages.
- For each HTML / xiaohei animation segment, first write down "When this sentence is spoken, what changes on screen," then implement. Actions must be bound to specific spoken sentences or subtitles; do not apply the same entrance/flash/zoom effect uniformly to all segments.
- When explaining original images, screenshots, or result pages, the main visual must be the original asset. HTML is only responsible for cropping, zooming, circling, annotating, and focus switching; do not replace the original image with screen recording frames or redrawn graphics.
- For long images and web result pages, default to cropping out blank non-informative areas, prioritizing exposure of the region the audience is hearing about; when the speech mentions a corresponding object, you may zoom into that image or part, pushing the rest to the background.
- Do not include asset paths, internal notes, action explanations, or workbench text like "original image asset · img/xxx.png" in the video frame. Storyboards may include sources; the final video only retains content the audience needs to see.
- Do not add titles unless necessary. Result pages, table pages, and original image comparison pages should let the main visual speak for itself; only keep short labels, model names, metric names, or necessary annotations.
- Data comparison pages should prioritize clear tables, column alignment, short labels, and minimal highlighting. Font size must serve readability; do not cram text into tiny boxes. If a simple table explains it clearly, do not build complex card stacks.
- In vertical short videos, tables should not be reduced to a narrow horizontal strip in the middle. During data phases, make the table the main visual, occupying the primary safe zone; task descriptions, case labels, and summary phrases appear only during the corresponding speech phase and must disappear or recede to non-space-consuming positions during the final data comparison phase.
- Evaluation terms should only include positive/neutral results explicitly stated in the speech or required by editing emphasis. Comparison columns can be left blank or show only data; do not add negative words like "slow and expensive" unless the original speech reaches that conclusion.
- Icons must be found from the animation library index. Existing icons for ChatGPT, Claude, Flash lightning, Step, DeepSeek, Qwen, etc., must not be replaced with abstract shapes; when a user provides a new SVG, first store it in the animation library and update the index.
Do not proceed to timeline preview before storyboard direction is confirmed.
Step 2: Timeline Preview
After storyboard direction is confirmed, proceed to timeline preview.
Common path:
review/timeline-preview.html
Default template:
templates/timeline-preview.html
Timeline preview checks:
- Whether visual transitions align with speech sentences.
- Whether the original video has been mistakenly replaced with HTML.
- Whether segments marked as screen-recording small windows avoid the bottom subtitle safe zone; unmarked recording segments must not be automatically windowed.
- Whether screenshots, pages, and proof assets are used correctly.
- Image assets default to retaining left/right margins; do not fill the current screen entirely; only scale down when emphasizing a full screenshot is needed.
- Whether the frame blocks text, crops improperly, or has black bars.
- Whether HTML modules look fine alone but are still valid when placed in the full timeline.
When the preview page includes source video, it must be served via an HTTP Range-enabled service; otherwise, the browser cannot randomly seek, and the progress bar will reset to the beginning. Do not use plain python -m http.server to preview MP4 timelines. Default to:
node ~/.Codex/skills/chengfeng-videocut-skills/口播成片/scripts/serve_range_preview.cjs \
--project-dir /absolute/path/to/project \
--port 8767
Generate if necessary:
docs/08-动画cue表-vN.md
html-modules/module-*.html
html-modules/xiaohei-*.html
If a new explanatory animation is needed, first read animationStyle from 用户配置/default.json, then find the corresponding animation sub-skill in 动画/styles.json.
Each animation action must be bound to a specific spoken sentence; do not evenly distribute time. Multi-stage HTML animations must explicitly manage visibility states: when the next stage appears, information cards, labels, and annotations from the previous stage that no longer serve a purpose must be hidden; do not let the previous stage continue occupying main visual space, especially for vertical-screen data tables, screenshot focus areas, and result pages.
Step 3: Synthesis
Only proceed to synthesis after the user has confirmed the timeline preview.
Before synthesis, create or confirm:
final-player.html
Before writing a new final-player.html or HTML module, read:
references/artifact-contracts.md
If the project has HTML modules, first inject the render mode:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/write_render_mode.cjs \
--project-dir /absolute/path/to/project
Timeline preview and final export must use the same HTML rendering context. HTML modules in both the preview page and final-player.html must include ?timeline=1&render=1; the preview page only scales the final canvas proportionally inside the window; modules must not re-layout responsively based on the preview window.
High-definition delivery must not simply scale the CSS logical canvas. Default 3:4 must maintain the 1080x1440 logical canvas, then use screenshot DPR 1.5 to output 1620x2160; otherwise, tables, CSS cards, and screenshot annotations will appear relatively smaller in the export compared to the preview.
If preview and export sizes differ, first check the HTML module's internal CSS, render-mode.js, and export DPR to confirm the preview page and final-player have the same logical canvas; do not re-export the entire video first. Common causes are that the preview iframe is smaller and looks fine, but the final HD canvas triggers constraints like .photo-frame { max-width: ... }, .stage { width: min(...) }, .wrap { max-height: ... }, clamp(...), causing the export to become a "small image." Fix order:
- Regenerate
html-modules/render-mode.jswithwrite_render_mode.cjs. - Confirm in the timeline preview that the HTML module URL has become
?timeline=1&render=1. - Confirm that
viewportinexport_final_video.cjsis the logical canvas size, anddpris the HD multiplier. - Use final-player to capture a keyframe of that module under the actual export viewport; if necessary, use
getBoundingClientRect()to compare the main visual container size.
When handling horizontal xiaohei SVG / 16:9 SVG modules in a vertical screen, do not use overall scaling like .wrap { transform: scale(...) } to solve "small horizontal bar" problems. Overall scaling in a 3:4 canvas will crop the left and right edges, especially model cards, arrows, and explanatory labels distributed left-to-right. Either rearrange into a vertical composition or maintain a complete safe zone; after changes, must capture the left and right boundary frames of that module, not just the center keyframe.
Export the final video:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03
Default to HD delivery: lossless PNG intermediate frames, H.264 crf=14, preset=slow. This avoids the scenario where the browser preview is clear but the export has soft small text and thin lines:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03 \
--frame-format png \
--crf 14 \
--preset slow
Only when temporarily reviewing rhythm or needing a fast draft, explicitly downgrade:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03 \
--frame-format jpeg \
--quality 92 \
--crf 18 \
--preset medium
Ratio reading rules are under "User Configuration." When the project differs from user configuration, pass:
--config
--ratio
--aspect-ratio
--fps
--player
--stage
--frames-dir
--width
--height
--frame-format png|jpeg
--quality 100
--crf 14
--dpr 1.5
--device-scale-factor 1.5
Validation
A successful export does not mean the final video is correct. Two steps are mandatory:
- Use
ffprobeto check resolution, frame rate, duration, and audio. - Extract 3+ keyframes and manually verify the visuals are correct.
- For each HTML module, extract at least 1 frame from
final-playerat the corresponding speech timepoint and compare with the timeline preview at the same timepoint; size, position, cropping, and visibility must be consistent; do not rely solely onffprobeas the completion criterion.
Check resolution according to the current ratio; other expectations come from script defaults and actual project input. Current default configuration:
1620x2160
Logical canvas 1080x1440, DPR 1.5
3:4
30fps
Duration matches edited source video
Has audio
No HUD, buttons, review timeline, or browser UI
Boundaries
Suitable for:
- Chinese language talking-head videos
- Tutorials, product demos, result showcases, knowledge explanations
- Existing edited video and subtitles; assets can be added later
- Mixed output using original video + screenshots + HTML explanation visuals
Not prioritized:
- Generating a finished video from a script alone without any video input
- Complex multi-camera live-action editing
- Fine color grading and multi-track mixing requiring NLE project files
- User requesting final publishing without reviewing storyboard and timeline preview
Project Hygiene
If adding or modifying files in the user's working directory, must synchronously update the project README index.
Local activity logs are placed uniformly at:
log/
log/ only records local experiments, user preferences, temporary conclusions, and unpublished work-in-progress; it must not be uploaded to GitHub. This directory is ignored by .claude/skills/.gitignore.
Do not add a new README in this Skill's directory. The core files of this Skill only retain:
SKILL.md
templates/
references/
scripts/
用户配置/
动画/
动画/ is used to accumulate reusable HTML/SVG/GSAP animation sub-skills, templates, and rules for talking-head video production; optional styles are in 动画/styles.json, current selection is in 用户配置/default.json.