Sci-Glow Video Skill (Scientific Glow-Line Explainer Video Full Workflow)
Overview
Stably transforms a hard science topic from a "one-sentence concept" into a complete set of 60-second (or specified duration) glow-line explainer animation deliverables: a pure-text voiceover script, a literature fact-checking table, a precision-cued subtitle script, a 60fps motion-blur master MP4, horizontal and vertical 4K safe-zone covers, and platform-specific promotional copy.
Core philosophy: Hard quality gate with automatic rework (quantified brightness + zero BOM validation + independent read-only sub-agent blind review ≥ 8.5/10). Never force-render a master with P0/P1 defects or overexposed/grey frames.
Dependencies
This Skill orchestrates and builds upon the following upstream capabilities without re-implementing their underlying engines:
Lead-Knowledge-Animation(lead-knowledge-animation): Provides a deterministic Canvas/DOM runtime (motion.js,kit.js) and underlying scaffolding (new_film.mjs,beats.py,timeline.py,fonts.py,sfx.py,mix.py,render.mjs,cover.mjs,verify.mjs,qa_video.py,review_pack.py). FromAzenYes/leaderai-media-toolkit.Lead-Media-Script(lead-media-script): Provides cold-open hook grammar, relatable analogy structures, and platform-specific publishing document templates for Bilibili, Douyin, Kuaishou (Weibo Story), Xiaohongshu, and YouTube. FromAzenYes/leaderai-media-toolkit.uv(uv run): Runs this Skill's companion pure-standard-library CLI scriptscripts/sci_glow_cli.py.- Optional Scientific Literature Retrieval Skills (prioritized if installed in the host):
pubmed-databaseorliterature-search-openalex, used for fact-checking authoritative papers and real numerical data; if unavailable, uses web search to verify primary literature.
Quick Start
# 1. Environment and IBM Plex Sans SC 8-weight self-check (automatically throttled download if fonts missing)
uv run <skill_dir>/scripts/sci_glow_cli.py preflight --auto-fix-fonts --output work/preflight.json
# 2. Analyze the frequency spectrum of any user-provided MP3 to find top-3 drop cue points and pre-sidechain parameters
uv run <skill_dir>/scripts/sci_glow_cli.py analyze-bgm --bgm "<BGM.mp3>" --target-duration 60 --top-k 3 --output work/bgm_analysis.json
# 3. Initialize the project dual-directory structure and write safe default parameters (includes 3:4 1080x1440 and bloom 0.26)
uv run <skill_dir>/scripts/sci_glow_cli.py scaffold-project --workspace "<Project Root>" --date 20261118 --topic Optogenetics --ratio 3x4 --output work/scaffold.json
Utility Scripts
All auxiliary calculations are provided via scripts/sci_glow_cli.py. All output is written as UTF-8 without BOM JSON using the --output flag. Raw terminal logs are forbidden.
| Sub-command | Core Function | Key Required Arguments |
|---|---|---|
preflight | Checks Node 18+, FFmpeg, Chrome, Playwright (with hints for npmmirror + skip browser re-download), upstream dual skills, and IBM Plex 8 weights; adds --auto-fix-fonts to auto-complete missing .otf files. | --output |
scaffold-project | Creates Script Output/<Date Topic Explain>/ and .code/<Date Topic Animation>/ directories, runs new_film.mjs, and patches it to enable 3:4 size and bloom: 0.26. | --workspace, --date, --topic, --ratio, --output |
analyze-bgm | Decodes an 8kHz mono wave via FFmpeg, extracts full-range RMS + <180 Hz low-frequency envelope, searches for Drop 1 (title card cue) → Breakdown → Ultimate Climax Drop, and outputs Top-K --music-start and --music-dips. | --bgm, --target-duration, --top-k, --output |
validate-lines | Validates/removes UTF-8 BOM, checks character count at 1080px width (hook <=12 chars, subtitle <=15 chars), balanced parentheses, no end-of-sentence punctuation, 5s hook upper limit, and auto-calculates to lock total duration tail. | --lines, --target-duration, --ratio, --output (optional --fix-bom, --apply-tail) |
audit-qa | Calls upstream qa_video.py and provides a traffic-light report and parameter prescription based on the gold fingerprint (mean 17-20, p99 >= 130, bright <= 3.5%, zero dead zones, zero flicker frames). Also generates an independent blind review prompt. | --video, --film-dir, --round, --output |
Workflow
When handling multi-question parallel production or a dual-model division of labor, concurrently load multi-agent-batch-playbook.md; visual and layout parameters must strictly adhere to visual-and-layout-guardrails.md.
Step 0: Pre-Work Environment Check and Music Confirmation
- Run
preflight --auto-fix-fonts --output ...; if Playwright is missing, guide the user to execute:$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD="1"; npm i playwright --registry https://registry.npmmirror.com. - Music Gate: If the user specified a track, use only that track. If unspecified and no fitting track is available on this machine, actively ask the user to provide a music file path or switch to pure sound effects (do not silently skip).
Step 1: Zero-Barrier Script Writing and Primary Literature Fact-Checking (Reuses Lead-Media-Script)
- The first 3 seconds must hook the audience with a specific number or counter-intuitive fact, then give a relatable everyday analogy before introducing the scientific term.
- Fact-check against at least 2–3 primary journal sources (
Nature/Science/NEJM/Cell); fabricating data is strictly forbidden. - Generate a plain-text
.txtscript and an execution plan.mdinScript Output/<YYYYMMDD Topic Explain>/.
Step 2: BGM Spectrum Drop Alignment and Precise Subtitle Duration Locking
- Run
analyze-bgm --bgm <path> --target-duration <T> --top-k 3 --output work/bgm.jsonto select the bestmusic_start_sec, and use upstreambeats.pyto outputwork/beats.json. - Write
work/lines.json: lock the title cardT.atto Drop 1, the turning point/crisisatto Breakdown, the breakthrough momentatto Ultimate Climax Drop, and leave room for a callback/concluding image. - Run
validate-lines --lines work/lines.json --target-duration <T> --ratio <ratio> --fix-bom --apply-tail --output work/lines_check.json. Only proceed to run upstreamtimeline.py --beats work/beats.json --music-start <start> --film film/after all checks pass green.
Step 3: Visual System Design and Deterministic Code Implementation (Reuses Lead-Knowledge-Animation)
[!IMPORTANT] Coding and visual parameters must obey visual-and-layout-guardrails.md:
bloom: 0.20–0.28,K.fog: 0.024–0.028,K.hud.cornerdisabled,scenes.jswrapped in IIFE, transition titles usingmode: 'rise', blur: 0and delayed by+0.36s.
- First run
scaffold-projectto create the dual-directory structure. - Design a non-clashing main color palette. Hand-write 3–5 layers of fine glow primitives for the specific scientific metaphor of this film in
film/core.js(repeating generic box cards or stick figures is forbidden). - Write
film/scenes.js,film/index.html, andfilm/cover.html. Then pass upstreamfonts.py film/for subsetting andverify.mjs film/index.html --tol 24for full zero-difference verification.
Step 4: Sidechain Mixing and Dual-Version 4K Cover Safe-Zone Check
- Write
work/cues.jsonas UTF-8 without BOM. Runsfx.py --variants 3andmix.py(provide--music-startand--music-dipsfromanalyze-bgmoutput; target-14.0 LUFS / -1.5 dBFS). - Run
cover.mjs film/cover.html --out out --name <Topic> --guides. Visually inspect the images inwork/Cover Check/to ensure horizontal version key information lies strictly within the central4:3area (x ∈ [240, 1680]).
Step 5: 30fps Draft Quantitative Health Check + Independent Read-Only Sub-Agent Blind Review Loop
See blind-review-protocol.md for details.
- Render a half-resolution draft first:
render.mjs film/index.html --fps 30 --scale 0.5 --out out/draft_r1.mp4(can use--workers 8for a single piece; for multiple concurrent pieces, strictly limit to--workers 4). - Run
audit-qa --video out/draft_r1.mp4 --film-dir film --round 1 --output work/qa_r1.json. If brightness or dead-zone metrics are not met, directly change parameters according to the prescription and re-render the draft. - Run
review_pack.py out/draft_r1.mp4 --film film/ --out out/review_r1. Spawn an independent read-onlyresearchblind review sub-agent (only allowed to readout/review_r1/, forbidden from viewing source code) to perform a 9-dimensional scoring. - If any P0/P1 defects exist or average score
< 8.5, it is strictly forbidden to render the 60fps master. Iterate on fixes, self-check, and re-review until all checks pass green.
Step 6: 60fps Motion-Blur Master Direct Output and Complete Delivery
- After the blind review passes green, render the final version only once:
render.mjs film/index.html --fps 60 --blur 2 --audio work/mix.wav --out out/<Topic>.mp4. - Run
audit-qaandqa_video.py --sheet --ref-sheetagain. Visually inspect the final contact sheet and deleteout/draft*.mp4temporary files. - Following
Lead-Media-Scriptandcopy_template.md, finalizework/Script and Cover.md. Deliver the complete file package to the user, along with a list of audio segments that require human ear listening for re-recording.
Rate Limiting
analyze-bgm,validate-lines,scaffold-project,audit-qaare all run locally with no external network requests.- When
preflight --auto-fix-fontsfetches missing.otffont files from the CDN, it includes a built-in cross-process OS file lock +time.monotonic()rate limiter (1.0 req/s). It implements 3 exponential backoff retries for 5xx errors, and throws aRateLimitErrorto abort the request upon encountering HTTP 429.
Common Mistakes
- PowerShell UTF-8 BOM causes
mix.pyto crash: PowerShell 5.1's defaultSet-Content -Encoding UTF8writes theEF BB BFbyte order mark. All.jsonfiles must be written by Python'sencoding='utf-8', aclitool, or[IO.File]::WriteAllText(without BOM). - Using default
bloom: 0.9andmode: 'center'causes ghosting: A large glow-line subject paired with0.9bloom will definitely breakbright > 3.5%. Acentertitle locked to 14px blur will ruin the light-sweep transition. Must follow visual-and-layout-guardrails.md to lower to0.20–0.28and switch torise(blur: 0). - Chromium Worker overload and "self-reviewing" during multi-piece concurrency: For 3–4 parallel pieces, throttling with
--workers 4is mandatory. Crucially, the same context that wrote the code must never self-approve; sign-off must be exclusively delegated to the read-only blind review sub-agent via the isolatedout/review_rN/directory.