lainshao/video-editor

Video Editor · The Video Worker

Composites talking-head voiceover (9:16 / 16:9) with overlay assets (titles / B-roll cutaways / chyrons / subtitles) into short videos. The compositing core is self-contained; live-action stock / news card assets are delegated by this skill as the commander to the footage-finder / news-highlight skills.

When to Trigger

The user says:

• "Edit this video", "Cut the video", "Clip" – most common entry point
• "Make a video", "Produce a full video", "Composite the voiceover and B-roll"
• "New episode of [Overseas / AI Startup / X Series]"
• "Add subtitles / chyron / pop-up text / title card to the voiceover"
• "Add motion / add animation / add visuals"
• "Add Maria-style real article screenshots / real-person reactions / localized images to the voiceover" → reaction_overlay (1080×1920 vertical voiceover; first read recipes/reaction_overlay.md)

Does not trigger but related (delegated to sibling skills, with video-editor as the commander):

• Live-action stock footage / stock footage / B-roll scenes → call footage-finder skill
• News highlight cards (real source screenshots + yellow light emphasis) → call news-highlight skill
• Pure voice-over generation, short raw footage under 30s → do not trigger

Delegation: Shot Cue Type → Which Skill

During the storyboard (Gate 1) phase, each cue is tagged with a type; two types not native to this skill are delegated out:

Cue Type	Who Does It	Deliverable
real_footage	footage-finder skill	Cropped-to-aspect live-action mp4 candidates + review page
news_highlight	news-highlight skill	Real news title yellow-light emphasis card mp4 (Vox-style)
source_progressive_highlight	This skill animator/cutaway/scene_source_progressive_highlight.html	Sentence-by-sentence yellow highlight on real news/article original screenshot, does not redraw the media page
tenure_bullets	This skill animator/cutaway/scene_tenure_bullets.html	Person-framed numbered bullets: current item yellow, old items fade
numbered_pills	This skill animator/cutaway/scene_numbered_pills.html	YC-style 01–04 white capsules + orange rounded edge, grouped overview appearing item by item; same content as listicle, choose one after preview both
company_site	This skill recipes/compose_company_site.py	Real official website scrolling full-screen recording + continuous real-person circular PiP; official website default PIP, segment by segment avoiding subtitles and key areas
cutout_sticker_slidein	This skill animator/cutaway/scene_sticker_slidein.html	Transparent person/object sticker with source, brief stay, slides in from different directions; do not use old white-framed reaction cards
source_quote / source_screenshot	This skill finds original text and captures the real page	Real screenshots with original URL link, corresponding paragraph, and highlighted text; citations cannot be replaced by redrawn cards
real_person_reaction	This skill first searches user materials / original public videos, delegates to footage-finder if necessary	Real person photo or short video with source; do not automatically substitute with Emoji
opener / chyron / cutaway / listicle / spec_review	This skill animator/opener	HTML→mov/mp4
reaction_overlay (person continuously on screen, real material appears locally)	This skill recipes/reaction_overlay.py + existing video compositing	Static image overlay composited with real person clip; cue JSON, source links, and materials can be reused
Subtitles	This skill subtitle	Keyword-highlighted burned-in subtitles

Material Suggestions in Voiceover Script: Read Before Creating Cues

Applies to full videos with visuals, animation cues, reaction_overlay, and 3:4 slidecast. When the user provides a voiceover script (HTML / Markdown / Feishu document), first read the main script body and the separate "Material Suggestions" section; if only audio or video is given, first check the same topic folder for a corresponding voiceover script. Single-point tasks like only subtitles or title cards do not require this step.

• "Material Suggestions" represent editorial intent, not lines to be read aloud; Whisper transcription is only for verifying what was actually said and determining timestamps, do not discard the script's visual suggestions just because a retranscription was done.
• Each suggestion is read as: "anchor original sentence / intended visual / original material or source link / alternative". First, use the anchor to locate the position in the actual transcription; when the voiceover changes wording or reorders sentences, realign semantically, do not mechanically apply the script's estimated timestamps. Do not force-fit material into paragraphs that were not spoken.
• Add a column to the Gate 1 cue table: "Script material suggestion → Adopted / Adjusted / Skipped". When adopted, keep the original link; when adjusted or skipped, write a one-sentence reason and provide an alternative visual. For paragraphs without script suggestions, cues can still be added based on voiceover content, but must be marked as "New".
• When the original link is invalid, facts have changed, or the visual is unsuitable for the current aspect ratio, verify first before replacing; do not use inaccurate screenshots, fake replicas of original webpages, or visuals that are misaligned with the actual voiceover just to execute the script verbatim.
• If a voiceover script exists but the material suggestions section cannot be found, proceed with normal editing without asking the user to rewrite the script. The final cue plan is based on the actual voiceover + user feedback at Gate 1.

When writing new voiceover scripts, see the "Voiceover Material Suggestions" section of the html-report skill for the accompanying format.

Real Pages and Dynamic Visuals: Default Editing Rules

• When mentioning a specific company/product, show its real official website or official product interface. Preserve site branding, company name, and authentic visual identity; prioritize recording page scrolling, mouse positioning, product demos, or local close-ups. Use recipes/capture_company_site.js for capture and recipes/compose_company_site.py for compositing; do not just paste a logo or replace the official site with a self-made fake webpage card. Only use official screenshots with verifiable sources when the official site is inaccessible, and state the reason in the cue table.
• Information that can be revealed as the voiceover progresses should animate item by item. For example, "1, 2, 3, 4" – reveal each direction one by one as mentioned, highlight the current item, and briefly show the full picture at the end; for an 11-item complete list, use grouped/split-screen entry, but ultimately let the audience see all 11 items clearly. Do not display all four items as a static page from the first item, and do not use meaningless floating loops instead of item-by-item presentation.
• Full-screen static materials can overlay a dynamic real-person PiP; real company website displays default to PiP, even when scrolling. For official sites, use recipes/compose_company_site.py: full-screen recording of the real page, continuous talking-head video cropped into a circular small window. Stock B-roll videos default to no PiP. For each cue, first mark the subtitle area and the most important visual key, then choose one of four safe positions: top-left, top-right, mid-left, mid-right; when multiple cues have safe positions, rotate them so that not all company pages are fixed in the same corner. Keep the position fixed within a single cue, do not jump. If no safe position is available, shrink or crop the webpage; if still unsolvable, record the exception and remove the PiP. For static materials, use recipes/compose_static_pip.py. See CONVENTIONS.md section 9.
• For ordered lists, first provide two actual visual options. For the same set of 3-5 items, use scene_numbered_pills.html for full-screen numbered capsules and scene_listicle.html for a person-framed yellow-circle numbered list; display both side-by-side with the same copy in Gate 2. Prefer numbered pills for category/direction overviews, and listicles for continuous explanations of each item; the Hunger-style top bullet is a third, lighter person-framed list. After finalization, reveal items one by one according to the actual voiceover timing, not all at once from the first item.
• Small stickers and suitable introduction visuals can slide in from the edges. Real person/object stickers, memes, photos, and localized screenshots can slide in from top, left, bottom, or right directions, rotating or using a fixed seed for random selection; first check that the path does not cross subtitles, faces, original text, or key data. For full-screen official site recordings and original post videos that require direct recognition, decide based on content whether sliding in is suitable; do not force transitions just for motion. Entry time approximately 0.25–0.35 seconds, leave enough reading time after settling; do not randomly move within the same shot. Use animator/cutaway/scene_sticker_slidein.html for stickers; do not enable the old white-framed emoji reaction cards.
• Visual rhythm threshold: For explanatory voiceover, default continuous pure talking-head footage should not exceed 8 seconds. Time from the exit of the last effective auxiliary visual to the entry of the next; if exceeding 8 seconds, it must be marked in the cue table with an explanation for the blank space. Within the first 5 seconds, present a title or the first piece of evidence. This is this account's editing check line, not a fixed frequency measured from Mariah's videos; do not insert emoji or text cards that repeat the voiceover just to fill seconds. Effective auxiliary visuals should be source pages, product operations, live-action, charts, itemized lists, or new visual states with information; ordinary subtitles, persistent titles, and simple lip movements do not count. Full details and Q&A are in CONVENTIONS.md.

Step Zero · Aspect Ratio + Entry Point (★ video-editor is the single entry point for the entire pipeline)

video-editor is the commander – the user enters video production here, they do not need to go click footage-finder / news-highlight / data-viz on their own. On trigger, the first thing to do is use AskUserQuestion to ask about the aspect ratio:

What aspect ratio is this video?

1. 9:16 Vertical (Douyin / Xiaohongshu / Video Account / Reels) → 1080×1920
2. 16:9 Horizontal (YouTube / Bilibili) → 1920×1080
3. 3:4 Hands-on Tutorial (Screen recording demo / "How I use AI to do X") → 1080×1440 · use slidecast/ sub-module

The aspect ratio follows the content type: Hands-on tutorials / screen recording demos default to 3:4 (slidecast); opinion pieces / vlogs / general culture and other talking-head content use 9:16. Do not cram ordinary talking-head content into the 3:4 screen-recording window format, nor turn hands-on tutorials into 9:16.

Shortcut: If the user has already specified the aspect ratio ("make a 16:9" / "post to YouTube" / "post to Bilibili"), do not ask, just set it directly.

The aspect ratio determines the downstream:

	9:16	16:9
Sub-module canvas	1080×1920	1920×1080
Live-action B-roll	footage-finder --vertical	footage-finder (default horizontal)
News card	news-highlight (vertical version)	news-highlight (Root default 1920×1080)
Data viz	data-viz (1080×1920)	data-viz (1920×1080)
Compose	recipes/compose_dual.sh.template	recipes/compose_16x9.sh.template
Safe zones	CONVENTIONS section 3	CONVENTIONS section 1 16:9 row

All sub-skills already support horizontal; video-editor is responsible for delegation + final compositing, and the user only talks to video-editor throughout. 16:9 also has an additional person-pip capability (clean face voiceover → when there is content, shrink to a small window in the bottom-right; see CONVENTIONS section 9 + compose_16x9 template).

After determining the aspect ratio, proceed to the deliverable routing below.

---

Step One · Routing Inquiry (★ Execute immediately upon trigger)

Do not assume the user wants to follow the full pipeline. First, use AskUserQuestion to ask once. Classify by "what the final deliverable looks like" (deliverable form), not by "what action you want to do" – the user has the final product in mind, not the process.

What are you making this time?

1. A finished video with subtitles: already have a finished video, just add subtitles → subtitle/ sub-module (does not go through the three gates)
2. A title card / intro: 4.5s transparent alpha overlay → opener/ sub-module (does not go through the three gates)
3. A full video with motion effects: add chyron / cutaway / listicle animations → animator/ sub-module (goes through the three gates)
4. Complete from scratch: voiceover → title → motion effects → subtitles all included → opener → animator → subtitle chained in order
5. Voiceover hands-on tutorial (3:4): voiceover → case-step screen recording window slide + subtitles, you overlay screen recording/face → slidecast/ sub-module (goes through the three gates)

Option numbering standard: Use only plain numbers 1 / 2 / 3 / 4 as prefix for AskUserQuestion options; disable ①②③④, ㋐㋑㋒㋓ and other circled/katakana characters – user fonts often do not support them, rendering as garbled characters.

Shortcuts (cases where you can go directly without asking):

User's Original Words	Direct To
"Add subtitles / Burn in subtitles"	1 · subtitle/
"Make an intro / title card / opener"	2 · opener/
"New episode of X series" / "Make a video" / "Produce a full video"	4 · full pipeline
Context already working on a full video, wants to add chyron / cutaway	3 · animator/
"Hands-on tutorial / Screen recording demo / How I use AI to do X" / 100 AI hands-on case series	5 · slidecast/ (3:4)
"Like Maria, add real articles, real-person reactions, and images to vertical voiceover", and the user has already provided the original video	3 · reaction_overlay; first confirm the source video is 1080×1920, read recipes/reaction_overlay.md

Key Principle: 1 and 2 are single-point operations, do not go through the three gates; 3 and 4 must go through the three gates.

★ The Three-Gate Workflow (Options 3, 4 mandatory, no skipping allowed)

⚠ Routing options are not rendering permission – the user selecting 3 or 4 only means "I want to go through the animator process". Once inside animator, you must follow the three gates strictly, STOP at each gate and wait for explicit user confirmation before proceeding to the next step. Even if the user has already told you the title / number of cues / copy, it does not mean they allow you to skip gates.

Gate 1 · Text Plan       ─►   Provide a markdown cue table in chat
                         STOP · Wait for user to express something like "OK / Change X / Cut Y / Lock in"
                         ❌ Do not write any cue HTML
                         ❌ Do not start rendering
                              │
Gate 2 · Spec Review    ─►   Write the HTML for each cue
                         ★ First run `node recipes/lint_layout.js --all <cue directory>`
                           (safe zones / minimum font size / text width / centering, do not proceed until FAIL is fixed)
                         Then generate `_review/spec_review.html`
                         STOP · Tell the user "Open file:///<project>/_review/spec_review.html to view, feedback to me"
                         ❌ Do not render ProRes mov
                         ❌ Do not compose the full video
                              │
Gate 3 · Pre-render Last Call ─►  AskUserQuestion: recap + judgment calls + three output format options
                          STOP · Wait for the user to choose
                          ❌ Do not assume the output format
                              │
Render + compose + subtitles

Until the user says "Lock in / Confirm / Start / Render / OK" or other explicit affirmative expressions, you are still in the previous gate.

❌ Anti-patterns (Do not do this)

Wrong Behavior	Loss
User selects 4 + gives title → you directly extract voiceover + transcribe + write HTML + render	Skipped Gate 1 "change 1-2 words and fix" cheapest checkpoint, saving 5-10 min + 10k tokens
User says "I want this" → you judge "since they want it, just start rendering"	Skipped Gate 2, HTML visual/font errors cost 5x more to re-render (30s render × failure count)
User feedback in Gate 2 "cue 3 change X" → after fix, render directly	Skipped Gate 3 last call, did not let the user choose output form (composite original video / broll transparent track / both), possibly rendering an extra 500MB ProRes
User doesn't say yes → you guess they want to proceed	User review incomplete, rendered result off track requires full redo

✅ Positive Example

"Entering animator. First, transcribe + output cue plan markdown table for you to review. This is Gate 1 – no HTML writing, no rendering, wait for your OK / change / cut."

At the end of each gate, use a similar sentence to explicitly tell the user "Now at Gate X, waiting for your OK" – do not silently proceed.

Detailed process + specific deliverables for each gate + baseline cue count are in animator/README.md.

---

Sub-Module Entry Points

Sub-module	What It Does	Entry Document
opener/	4.5s yellow-serif title card, transparent alpha overlay	opener/README.md
animator/	chyron / cutaway / listicle / spec_review, three-gate workflow	animator/README.md
subtitle/	whisper transcription → keyword highlight PNG overlay → burn subtitles. 9:16 use add_subtitles.py; 16:9 long videos must use make_events_16x9.py + burn_chunked_16x9.py (single-chain burn will freeze, see README)	subtitle/README.md
slidecast/	Voiceover hands-on tutorial (3:4): voiceover → case-step screen recording window slide hard-cut by timestamp + subtitles → preview mp4 + transparent layer mov	slidecast/README.md
reaction_overlay	Talking-head video as base, prioritize real source screenshots and real-person reactions; decide material and duration based on content, do not sprinkle emoji at fixed intervals	recipes/reaction_overlay.md

Common Conventions

• Delivery Specification: 做内容/_运营文档/视频成片流水线-模板.md – one video = two folders with the same name (work / delivery) + Gate 3 default three deliverables (finished video / 3:4 title layer / timeline) placed in ~/Movies/<Series>/<Video Code>/. Full pipeline follows this specification.
• Deliverables Recipe: recipes/deliverables.md (how to render transparent title layer · how to generate timeline from cue plan · delivery folder naming)
• P0 Handoff Gate: For 9:16 full videos, run python3 recipes/preflight.py plan <project>/preflight.json after Gate 1, and before each handoff run python3 recipes/preflight.py final <project>/preflight.json to check for dropped frames, review, and pass again; check 0-second titles, subtitle presets, >8s visual gaps, and PiP/Logo/Credit occlusion. Format in recipes/preflight.example.json and recipes/deliverables.md.
• Visual Convention: CONVENTIONS.md (safe zones, Hana palette, chyron timing, font size hierarchy, climax rules) – must read before writing HTML for any sub-module.
• Layout Lint (★ Must run at Gate 2): node recipes/lint_layout.js <cue.html> – Puppeteer renders and machine-checks safe zones / minimum font size 22px / text width ≤920 / centering offset / font count, three presets auto-detect for 9:16·16:9·3:4, animation cues judged by final settled state. Do not show spec review to user until FAIL is fixed. Add data-lint-ignore for intentional decorative elements that break boundaries.
• Environment Self-Check: bash recipes/doctor.sh – run on new machine / when rendering fails (ffmpeg / whisper / Chrome / puppeteer-core / avconvert / fonts 11 items)
• ffmpeg Dual Output Recipe: recipes/compose_dual.sh.template (mp4 + optional alpha mov)
• Known Pitfalls: recipes/PITFALLS.md (broll_reel flicker / HyperFrames webm no alpha / ffmpeg # escaping / alpha layer turns gray / Chinese path TCC etc. 23 items)
• Historical Case Index: recipes/examples.md (11 cue paradigms from your real videos)

Dual Output Strategy

File	Use	When to Generate	Specification
<Video Name>_整片.mp4	Preview / publish / review	Every iteration	H.264 yuv420p · CRF 20 · includes audio + overlays
<Video Name>_broll层.mov	Overlay in editing software (Premiere / AE / FCP)	Only when user explicitly says "Finalize / Deliver editing layer / Deliver ProRes layer / B-Roll only"	ProRes 4444 yuva444p10le · transparent · silent

During iteration, only output the full mp4 by default. The broll layer takes ~30s to render + ~500MB to write disk, not needed for iteration review.

⚠ The broll layer is always one complete timed track. When the user says "B-Roll only", they want this single complete track, not you splitting N cue clips into separate movs for them to edit themselves.

For non-overlapping cues, the alpha full track must be composited using concat: transparent gap + cue + transparent gap + cue, with gaps calculated using ffprobe's actual cue duration/frame count. Do not overlay translucent cards one by one onto a [email protected] transparent canvas; this will turn off-white cards gray-black when finally composited back onto the voiceover. See recipes/PITFALLS.md item 23 and recipes/compose_dual.sh.template.

Before delivering the broll layer, perform a real background QA: Overlay the final <Video Name>_broll层.mov onto the original voiceover, extract 4-8 key frames / contact sheet, and check color, alpha, face occlusion, and timing. spec_review.html can only review HTML/animation, cannot replace the final ffmpeg composite check.

Title Decision Matrix (How to decide when the user says "add title / add intro / emphasize a word")

User Says	Default =	Key Parameters
"Add title" / "title card" / "intro" / "opener"	opener/yellow.html (yellow-serif large title + white italic subtitle)	Transparent alpha · 0s video start · top-third (padding-top 280px) · 4.5s · ProRes 4444 mov
"Emphasize a word at X time" / "pop-up text"	animator/chyron/chyron.html	Yellow capsule · top 16% (y≈307 center) · 1-2s pop
"1, 2, 3 list" / "three / four points"	animator/cutaway/scene_listicle.html	Numbered list revealed line by line · card top 280px
"Full-screen data card / comparison chart" / "Cut to X data"	animator/cutaway/scene_blank.html	Full-screen white background cutaway · caption top 280px · opaque mp4

Key Principles:

• Video "title" = 0s intro, default is that. Even if the voiceover doesn't mention the phrase until 22s, the title is still at 0s. Follow the account format of yellow main title + white subtitle; keep the white subtitle layer even if the main title is only one line, unless the user explicitly specifies a monochrome version. Custom title scenes must be checked against opener/yellow.html for color and hierarchy at Gate 2.
• Intro title = transparent alpha overlaid on the talking head. Not a solid gold independent shot.
• Data card cutaway = opaque full screen, covering the talking head; other overlays (title / chyron) default to transparent.

Companion Skills

• hyperframes / hyperframes-cli – HyperFrames CLI (render HTML → mov/mp4), rendering dependency for the animation sub-module

Not in This Skill's Scope (Delegated Out)

• Live-action stock footage fetching (Pexels / Pixabay) → footage-finder skill
• News highlight cards → news-highlight skill
• Script generation / TTS voiceover → hyperframes skill's TTS functionality
• Content compliance review → content-audit skill