2598588975/koubo-explainer-video

Vlog-Style Explainer Video

One video = one voiceover + a collection of real footage + a set of animated overlays that follow the voiceover. Fully code-rendered (Lemo page), outputting mp4 + srt.

Visual structure (reference from sample videos; visual style is determined per project):

• Approximately 50% is the "explainer box": the foreground is an explainer animation that matches the project style, with a blurred real footage clip playing behind it. Black background with yellow/white is just one option.
• The remaining portion is real footage: full-screen, overlapping cards, quad-split, three cards.
• Sections discussing "poor results, errors" use negative samples (user-specified low-quality footage) with a red "Negative Example" label.
• Bottom subtitles are always present; keywords use the project's unified accent color; for the black/yellow scheme, yellow is used.
• Audio: voice + icon/physical sound effects. No background music by default, and no paper rustling (users have explicitly disliked the "scratchy" sound).

Model Collaboration & Execution Entry

This skill is a production specification and local rendering toolset; it does not include its own cross-model API scheduler for Claude / DeepSeek / GPT. Placing it in Cherry Studio does not imply automatic collaboration between the three models.

• Claude: Overall planning, aesthetics, and primary production responsibility. Unifies the argument structure, storyboard rhythm, typography, and color palette; creates and modifies storyboard images for user confirmation; after user approval, handles rendering implementation, compositing, and final video QA. Claude's self-review does not replace user approval.
• DeepSeek: Script processing and structured organization. Handles colloquial phrasing, removes redundant sentences, splits long sentences, extracts keywords, performs logic checks, and creates script.json drafts. Factual verification must include sources; agreement between models is not evidence.
• GPT: Reference image analysis and image generation. Based on actual tool capabilities, reviews reference videos or time-coded frames, extracts storyboard elements, and generates needed illustrations/visual assets. Image generation must use real image-generation tools; do not substitute model suggestions for generated images.
• Codex: Auxiliary support. Handles skill maintenance, file/document organization, tool checks, or technical troubleshooting as specified by the user; does not take over Claude's storyboard creation, review communication, or rendering.
• User: Final storyboard approval. Claude submits complete storyboard images and necessary sample frames; revises based on user feedback; proceeds with formal rendering only after the user explicitly confirms the current version.

This is the user-specified priority division of labor, not a model capability ranking, and does not require every minor change to be cycled through all models. Only invoke models that are currently available and authorized; if Claude is unavailable, explain the missing items and prepare handover materials; do not automatically have Codex/GPT take over its primary responsibilities unless the user specifies otherwise. Do not impersonate other models as having reviewed content. For specific handover and Cherry/Codex usage, see Model Collaboration.

Visual Baseline (Must Read Before Each Project)

First read Visual Style, then create the storyboard and rendering page:

• Each project first defines its visual direction, then unifies it across the entire video. Black background with yellow/white is an optional scheme; other schemes like light editorial style, cool minimalist, cinematic, etc., are possible. Claude proposes options based on the topic and references, submitting them with the storyboard/samples for user approval. Once selected for the current project, do not arbitrarily mix colors, fonts, or switch styles.
• The black/yellow scheme does not include jarring blue text; other schemes may deliberately use coordinated primary/accent colors like blue. Do not extrapolate issues from a specific sample video into a blanket ban on blue for all styles. Red is reserved for errors, prohibitions, risks, or negative examples.
• The entire video uses a fixed font combination and size hierarchy. Body text prioritizes clear sans-serif fonts; headings may use one serif font to match the style. Achieve a premium look through whitespace, alignment, font weight, and minimal emphasis.
• Horizontal video designed for mobile viewing: in the final 1920×1080 output, body text and subtitles default to 64–72 px; auxiliary labels may be slightly smaller, typically 36–48 px, but small labels should not carry critical explanations. Font sizes are based on actual scaled dimensions; when text becomes cramped, split sentences or shots.
• Glitch and flash effects are disabled by default: do not actively add RGB misalignment, tearing, three-frame cuts, white flashes, black/white flashes, shutter effects, or full-screen shaking. Negative samples play normally, relying on red markers and localized explanations of issues.
• examples/codex-jiangzhi/ is a historical structural reference, containing non-unified color schemes, small critical text, white flashes, and glitch designs; it is not a qualified current aesthetic template. New projects must be migrated to the selected style before producing samples. In case of conflict between old examples and this section, this section takes precedence.

Before Starting

1. Environment: Requires the Lemo-Opuscar library (LIB, default C:/Users/codex/lemo-opuscar) containing the renderer, core/audio/sfx.py, Python in .venv, as well as Node.js, FFmpeg, and a usable shell. First verify paths and dependencies; if missing, specify the exact missing items and follow available installation instructions; do not assume another skill has installed them. The working directory is a new project folder under the user's material directory (e.g., D:/zgc personal/Works Old Island/codex-skill-koubo), not the skill directory.
2. Request four items from the user: voiceover mp3, script (one sentence per line + words to highlight), good footage (real clips, as specific as possible: film name + approximate timecode), and negative footage (poor-quality clips, e.g., from minimax/kling). If anything is missing, ask; do not find substitute footage yourself.
3. Claude first creates storyboard images and visual samples, then proceeds only after user confirmation. Samples should at least cover the title, the most information-dense explainer box, and any negative examples, accompanied by a mobile-size preview. After submission, pause at "Awaiting user confirmation"; do not treat Claude's self-review, tool validation, user silence, or a generic "make a video" request as confirmation of the current storyboard. If the user has already explicitly confirmed the same version, do not ask again; if there are substantial changes to shot content, sequence, duration, or visual style, re-submit the affected parts for confirmation. Rendering time depends on the actual environment.

Workflow

Project structure (reuses the data structure of examples/codex-jiangzhi/, with appearance redone according to the current visual specifications):

<project>/
  assets/voice.mp3        voiceover
  script.json             script: {"cues":[{"id","sec","text","hl":["highlight words"]}]}; sec only marks the sentence that starts the segment
  storyboard/shots.json   storyboard (script-generated)
  layers.json             frame extraction table: material path + timecode interval for each layer
  tools/                  align.py prep_layers.py storyboard.py mix.py build.sh qa.sh (copied from skill scripts/)
  index.html              rendering page (copied from examples/codex-jiangzhi/index.html and modified)
  frames/(frames per layer) frames.json timeline.json cues.json events.json mix.wav

First mkdir -p <project>/tools, copy scripts/*.py scripts/*.sh scripts/align.py into tools/.

1. Align Voiceover (a few minutes)

After writing the script and sec in script.json:

cd <project> && "$LIB/.venv/Scripts/python.exe" tools/align.py assets/voice.mp3 --model small --offset 0.8

Whisper word-level timestamps + exact script text are aligned to produce timeline.json (with t0/t1 per sentence) and cues.json. Video timing must come from here – if the voiceover is later changed, rerun this step and the visuals will automatically adjust. If the printed match rate is below ~85%, the script and voiceover differ too much; go back and check.

2. Claude Creates Storyboard, User Confirms Before Proceeding

1. Using the structure template from references/storyboard-guide.md, decompose the voiceover into shots and write storyboard/shots.json.
2. For each shot, select the material and start timecode, writing into layers.json.
3. Generate images (storyboard images confirm shot content; actual font sizes must be verified on the rendering page sample, not just from storyboard thumbnails):

   "$LIB/.venv/Scripts/python.exe" tools/storyboard.py      # → storyboard/board_1..N.png
   

   The storyboard images include the full video color band, a thumbnail of each shot (actual material frame capture), original voiceover sentences, visuals, on-screen text, transitions, sound effects, and a header with statistics on explainer box/negative sample ratio. First review with an available image viewer, identify shots where visuals don't match the dialogue, replace footage, and regenerate.
4. Claude submits the board images and representative visual samples to the user; user confirmation is the go/no-go point (duration, footage, script, color scheme, font sizes). Only implement necessary samples for this review following step 4; do not pre-produce the full video. Clearly mark the current storyboard version and wait for user feedback; if there are modifications, update and resubmit; only proceed to formal production after explicit user confirmation.

3. Frame Extraction

"$LIB/.venv/Scripts/python.exe" tools/prep_layers.py     # → frames/<layer>/f0001.jpg… + frames.json

Each layer = the visuals of one shot: muted, cropped 16:9, scaled by speed, 24 fps. Frame i corresponds to timecode t0 + i/24 seconds, with an extra 0.5 seconds at the tail for transitions. Four sizes: full 1920×1080 / card 960×540 / bg 480×270 (blurred first, softer when scaled up in the page) / inset 640×360. Thousands of jpgs are loaded on-demand by the page; do not load all at once.

4. Claude Implements index.html

Copy the engineering skeleton from examples/codex-jiangzhi/index.html, then migrate the old template according to references/render-engine.md and references/visual-style.md:

• Retain: drawing basics, cover, subtitles, on-demand frame loading, async render skeleton, and voiceover time mapping. Adjust labels, progress bars, cards, and title styles per new specs.
• Disable old effect calls: rgbSplit, slices, dynamic pixel, wflash, shutter, full-screen shake, and 2-frame black inserts; also remove sound effects specifically configured for these effects. Negative sections retain the normal time order of original footage.
• Rewrite: segment beat objects, explainer animation scenes, BAD[n]/OVER[n], HITS, transition timecodes, material keys → label names.
• All timecodes use T('cue id'), do not hardcode seconds.
• Sound effects are recorded in scenes using E(t, 'hit'|'whoosh'|'tick'|'stamp'|'ding'|'pop'|'clack'|'zap'|'boom', {...}).

After modifications, extract a few static frames to confirm no errors:

cd "$LIB" && node core/render/still.mjs "<project absolute path>" 0.5 11.2 20.5 47.7 93.3 --out "<project>/stills/chk"
"$LIB/.venv/Scripts/python.exe" "$LIB/core/render/sheet.py" <project>/stills/chk/sheet.jpg <project>/stills/chk/*.png --cols 4 --w 480

Open the overview image with an available image viewer to check visuals, subtitles, labels, explainer box proportions, and also inspect individual full frames at 640×360 and approximately 390×219; do not enlarge before judging readability. The most information-dense shot must be inspected; if wrong, reduce text, split the shot, or enlarge the subject and re-extract. After static frame approval, preview transitions and negative sections dynamically to confirm no flashes, shakes, or subtitle flickering.

5. User Confirmation, Then Claude Renders and Composites

First verify that the user has explicitly confirmed the current storyboard version; without this confirmation, stop at the storyboard review stage. Claude's aesthetic self-review and program checks do not replace this step.

sh tools/build.sh <output name>            # one-stop: events → mix → video → mux → srt → QA

The step-by-step breakdown is:

cd "$LIB" && node core/render/events.mjs "<project>"                                  # video sound effect events → events.json
"$LIB/.venv/Scripts/python.exe" tools/mix.py --out mix.wav                        # voice + sound effects (add --bgm for background music)
cd "$LIB" && node core/render/video.mjs "<project>" --fps 24 --workers 5 --out "<project>/video_<name>.mp4"
sh "$LIB/core/render/mux.sh" video_<name>.mp4 mix.wav <name>.mp4 24 0                  # −14 LUFS, no grain added to vector visuals
"$LIB/.venv/Scripts/python.exe" "$LIB/core/render/srt.py" cues.json <name>.srt

Rendering time depends on the actual machine. Use a different --out filename each time (the renderer locks files, same name will block).

6. Claude QA, Then Deliver

sh tools/qa.sh <name>.mp4 prints codec/duration, black frame list, loudness, and generates a frame summary qa/sheet.jpg. Check each item:

• Black frames: only allow designed opening/closing fades, etc.; do not treat 2-frame black inserts, shutter, or black flashes as default transitions. Unexpected black frames require checking material loading and element entry timing.
• Loudness: approximately −14 LUFS, peak ≤ −1 dB.
• Frame summary: review from start to finish; ensure subtitles and visuals match, stickers do not obstruct faces.
• Visual and mobile readability: verify the color palette, red semantics, unified fonts, actual font sizes, subtitle safe area, and mobile-size full frames per references/visual-style.md.
• Dynamic comfort: play all transitions and negative sections; sparse frame extraction and blackdetect cannot prove no white flashes or glitch flickering. Finally, deliver the mp4 / srt / poster using available attachment/link methods in the current environment, and specify which footage was used for which sentence and which checks were actually performed; do not assume the existence of a report_artifacts tool.

Hard Constraints

• If the same error occurs twice consecutively, stop and report; do not repeatedly retry. For network anomalies, do not resubmit paid tasks.
• All sample videos must be muted; do not use clips with original audio without user consent.
• Microsoft YaHei does not include ✗ ⇢ ↘ glyphs; they will render as boxes – use × → ↓ instead.
• The storyboard requires final user confirmation; do not proceed with formal rendering and production without it. If the user changes the script, rerun align.py; do not manually edit timeline.json. If changes affect an already confirmed storyboard, resubmit the affected parts for confirmation.
• Use an actual available viewer to inspect images before drawing conclusions. If you haven't watched the video, note that the review is based on frame extractions at specific timecodes; do not present a static frame check as a full dynamic video check.

References

• Visual Style — Must read every time: typography, color palette, mobile readability, low-stimulation motion, and acceptance criteria
• Model Collaboration — Claude / DeepSeek / GPT division of labor, handover, Cherry and Codex execution boundaries
• references/render-engine.md — index.html layer structure, implementation of each shot type, on-demand frame loading, pitfalls
• references/storyboard-guide.md — Structure template, shot selection rules, negative sample usage, transition and sound effect recipes, shots.json syntax
• examples/codex-jiangzhi/ — "Is Codex Really Getting Dumber?" historical v2: reference only for engineering structure and narrative; old colors, small text, glitches, and flashes are not to be reused directly
• scripts/ — align.py (voiceover alignment), prep_layers.py (frame extraction), storyboard.py (storyboard images), mix.py (audio mixing), build.sh (one-stop), qa.sh (QA)