howoneai/xiaolin-explainer-packaging

Xiao Lin Shuo Explainer Packaging

Packages a set of on-camera talking-head clips (A-roll) and dialogue into a Xiao Lin Shuo-style explainer video. The on-camera footage is generated or shot by other tools. This skill is responsible for retrieving the reference materials needed for packaging, as well as the explainer visuals, subtitles, transitions, and audio.

If the environment contains design-aesthetic-standard, visual and audio creative decisions should also follow it. If it contains video-generation, see it for generating and editing the on-camera clips.

Reference Documents (Read as Needed)

• references/style-bible.md: Her visual language, 6 hard rules, color palette, fonts, picture-in-picture, transition statistics, and audio levels. Must read before planning scenes.
• references/research.md: What data to look up for each layout, source grading, where to find it, and image rights. Read when planning scenes.
• references/layouts.md: Parameters, example calls, and gotchas for each layout component. Read when writing storyboards.
• references/storyboard-api.md: Formats for timeline.json and project.json, storyboard API, keyword timing, review and rendering commands. Read when first setting up the project.

Environment

• Node ≥ 18, ffmpeg, python3 (with numpy and Pillow). npm install and the first render require an internet connection (Remotion downloads Chrome).
• Only tested on macOS (Apple Silicon). Other systems default to software rendering (swangle); you can change this with the environment variable REMOTION_GL.
• Fonts: The template includes 6 SIL OFL fonts; see their licenses in templates/engine/public/fonts/LICENSES.txt. The font "优设标题黑" (YouShe.ttf) may not be included. The new_project.sh script looks for it in $YOUSHE_TTF and common font directories; if not found, it prompts the user to download it from https://www.uisdc.com/uisdc-first-free-font and save it as public/fonts/YouShe.ttf. When this font is missing, titles and subtitles fall back to the boldest weight (900) of Source Han Sans (思源黑体), without slant, significantly weakening the style.
• Remotion License: Individuals, companies with 3 or fewer people, and non-profits can use it for free, including commercial use. Companies with 4 or more people must purchase a company license (https://www.remotion.pro/license).

Workflow

1. Prepare Input

• On-camera clips: One 1920×1080 mp4 per sentence, placed in public/clips/<id>.mp4.
• Dialogue: Each sentence has spoken text say (in Chinese characters) and subtitle text sub.
• Facts file: Copied from templates/facts_template.md. Fill in existing facts and sources; look up missing ones in Step 4.
• Optional: Real shots or AI-generated images (public/broll/), photos (public/photos/), music (public/music/), new icons (public/icons/).

2. Set Up Project

<skill>/scripts/new_project.sh <project_dir>          # Adding --demo generates 4 fake on-camera clips and example storyboards for a smoke test

Then write timeline.json. Transcribe each on-camera video clip, determine tin/tout, and trim leading/trailing silence; write any mid-clip speech errors into cuts. Edit brand and music in project.json.

3. Plan Scenes (First Write a Table, Then Write Code)

After reading style-bible.md and research.md, create a table: Scene Name | Which Sentences It Covers | Layout | Dark or White Background | Picture-in-Picture Method | Required Data. Check the following 5 points:

• A scene spans 2–8 sentences; do not have one page per sentence.
• Each scene can indicate "subject is cropped" or "subject occupies >60% of the frame" (R1).
• Every 2–3 dark scenes are followed by 1 white scene (R2).
• Where citing the original text, use docpage, and the original text is a true verbatim quote.
• Leave full-screen on-camera segments for the opening hook, key point sentences, turning points, and the ending; do not cover them entirely with explainer visuals.

4. Retrieve Reference Materials

Search item by item according to the "Required Data" column of the scene table, as described in research.md. Write each result into the facts file with its number, original text, source link, and date. Use the script scripts/commons_photo.py to search for and download photos.

After retrieving, revise the scene table: If a verbatim original text cannot be found, do not use docpage. If data with consistent metrics cannot be gathered, do not use paper. If numbers in the dialogue don't match the facts file, first edit the dialogue, then generate or re-cut the on-camera clips.

5. Write Storyboard

Follow the writing style from templates/scenes_example.py. For each scene:

• Align element entrances with keywords: S.k('keyword', -0.15).
• Highlight the current item and dim the rest (focus / hl / lit). Move the camera to the current item (sc.cam / look).
• Register at least 1 review frame using KF.append((label, timecode)).

Run python3 story_core.py timeline.json scenes.py and confirm gaps/overlaps [].

6. Keyframe Review (At Least 2 Rounds)

python3 -c "import json;print(' '.join(str(f) for _,f in json.load(open('keyframes.json'))))" | xargs node render.mjs stills stills/k1
python3 <skill>/scripts/sheet.py stills/k1 keyframes.json 6

Inspect each composite image one by one, make changes according to the review checklist below, and re-render the modified frames. When you have the original creator's video, capture original frames of similar layouts and compare them side by side.

7. Full Render, Mix, Finalize, Audit

<skill>/scripts/render_chunks.sh video.mp4
python3 <skill>/scripts/mix_audio.py timeline.json mix_raw.wav
<skill>/scripts/finalize.sh video.mp4 mix_raw.wav final.mp4
python3 <skill>/scripts/audit.py video.mp4 72        # Compare video frames and static frames frame by frame; flagged must be 0

Mobile version: ffmpeg -i final.mp4 -c:v libx264 -crf 23 -preset medium -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart final_phone.mp4.

Review Checklist

For each keyframe, check:

1. The subject is large enough or cropped by the edge. No large empty spaces around.
2. The currently discussed item is the brightest, and the camera is near it.
3. At most 2 labels per frame.
4. Nothing is obstructed by subtitles (screen y 905–960), picture-in-picture, station logos, or AI annotations.
5. No missing glyphs (box characters), no words broken into vertical lines, no text overflowing the card.
6. Numbers, units, and original text match the facts file; the source line exists; CC BY photos are credited.
7. White and dark scenes alternate.

Known Gotchas

• When a keyword is at the beginning of a sentence, S.k(word, -0.3) may start before the clip. Use max(S.t0, …) to clamp it.
• For formula6, the column width equals iw. iw must be ≥ number of characters × fs.
• Screen x = (world x − camera x) × s + 960. piprect occupies screen x 110–560; place the subject at ≥ 600. When you change the camera position, the subject's position on screen also changes.
• The default unit for ui results is "元/月"; use u= to change it.
• The bottom edge of paper cards on screen must have screen y ≤ 900.
• For ent6, only the flags cl cn de fr jp us are available.
• If an image path does not exist, rendering fails (FAIL ... Error loading image). First confirm with ls public/<path>.
• A static frame looking correct does not mean the video is correct. After full render, you must run audit.py.
• Gradient 3D text exceeding 600px may cause Chrome to hang. Do not remove the layer count and blur limit on GText.

Usage Boundaries

• This is a style replication tool. The final video must retain the brand.label annotation of "AI Generated · Not the Person"; do not remove it.
• brand.logo is empty by default. Fill in the user's own logo; do not fill in a logo of "小Lin说" or any other real creator and publish publicly.
• Do not generate on-camera footage using the likeness or voice of a real creator and publish it publicly.
• Do not present the final video as the creator's own work, nor use it to mislead viewers.
• All data, original text, and policy provisions shown on screen must be traceable to their sources.