trend-explainer-video

trend-explainer-video: Ranking Voiceover Explainer Video Pipeline

Using C:/Users/<your username>/.workbuddy/skills/video-talkcraft (TalkCraft skill) as the rendering engine, this skill provides the project skeleton, end-to-end scripts, visual branding, and practical troubleshooting for ranking-themed videos. For video theory/general gates, see the TalkCraft base skill; they are not repeated here.

Pipeline Steps (commands and pitfalls in references/pipeline.md)

1. Capture Snapshot: Fetch the ranking page in one go (curl with user agent), save to data/snapshot.md/.json as the sole source of truth—rankings, star counts, descriptions, languages must only come from this single fetch; fabrication is prohibited.
2. Voiceover Script script.json: 35-sentence fixed structure = 1 opening + 10 projects × (ranking sentence + detail/total stars sentence + how-to-use sentence + total stars sentence) + 3 closing paragraphs (wrap-up / catchphrase / CTA). Hard rule: numbers in full Chinese; each project must start with 'First place… / Second place…'; each project includes a 'how to use' narration (verb-starting, explaining its use case / how to use / what it solves). Opening should directly state: 'Today’s GitHub weekly trending list—I’ll cover the top 10 in one go.'
3. Narration: synth_voice.py (VOICE/RATE at top, edge-tts requires HTTP_PROXY) → assemble_voice.py (full.wav + timestamps.json) → cp audio/full.wav remotion/public/narration.wav.
4. Timeline Reconstruction: make_timing.py → gen_beats.py (includes anchors.json generation) → gen_cues.py. All three anchor tables must be in sync: gen_beats's REPO_ANCHORS, gen_cues's REPO_CFG, all.tsx's REPO_CFG, plus scenes/index.ts's sceneFor (closing chart/quote/cta shot numbers shift due to inserted sentences). Any change in narration parameters = full chain rebuild, never just replace the audio track.
5. Project Implementation: Copy skeleton from assets/remotion-template/; modify src/data.ts (snapshot data), src/scenes/all.tsx's five tables REPO_CFG/USES/STEPS/ICONS/DETAILS + RANK_LIST rank shot table. Reuse all other scene code as-is. Run npx tsc --noEmit for verification.
6. Rendering: node <video-talkcraft>/scripts/render_shots.mjs --all --concat out/assembled.mp4 --audio out/full-mix.wav --mux out/v?.mp4 (full-mix auto-renders based on timing fingerprint).
7. Machine Gates (deliver only if all green): beat_lint → motion_check (still + shake) → sfx_check solo+mix → workbench_contract_lint. Thresholds and FAIL prescriptions in pipeline.md.
8. Delivery: loudnorm two passes (measure → linear normalize) → delivery.mp4 → rerun sfx_check --mix → present_files.
9. Cover: gen_cover.py generates a 1080×1920 vertical universal cover (no specific projects, long-term reuse), producing cover_vertical.png/.jpg.

Differentiated Visuals of This Pipeline (v16 final, see references/style-guide.md)

• Independent Rank Page RankPage: The shot for the rank word is rendered full-screen as an independent '[n]th place' page (gold 240px large text + RANK #N + repo name + star count + 10-segment progress bar), not co-located with project content.
• Three-Part Content Mirror: IllBg full-screen illustration background (blur30+darkening) + OgiCard dynamic illustration card (EFFECT PREVIEW + Ken Burns + light spots + light sweep) + DemoPanel terminal/grid demo, paired with USES 3 items (emoji) + DetailBlock detailed carousel.
• How-to-Use Three-Step Illustration Mirror HowScene: Three steps each with a StepIcon icon illustration card (gradient background + large emoji + STEP badge), driven by two tables STEPS/ICONS.
• Ambient Full-Screen Environment Animation: Three light bands sweep across in staggered phases, curing motion_check static segments (small cards/text scenes must include this).
• Dark Visual Theme: Color palette in style-guide.md; star count gold #FFC94D, weekly growth green #63E6A4.

Frequent Pitfalls (see references/pipeline.md for details)

• ImageGen image generation may suffer persistent 429 rate limits → use emoji icon cards (StepIcon) for illustration images, PIL programmatic generation (gen_cover.py) for covers, zero-cost, stable, and appropriate; switch to AI images when service recovers.
• motion_check static segments (freezedetect noise=0.003): small cards/static text/blurred background scenes—slow sin animation cannot fix → Ambient three light bands staggered sweep (≥3 bands; 2 bands leave gaps).
• <Video> server-side rendering will always crash → use OffthreadVideo + muted.
• Asset fps ≠ output fps → motion_check flags 'duplicate frames'; use optical flow interpolation minterpolate=mi_mode=blend.
• Windows: symlinks all rejected → copy directories; ffmpeg 7+ lacks -vsync → use -fps_mode passthrough.
• edge-tts requires proxy: HTTP_PROXY/HTTPS_PROXY=http://<your proxy>.
• Modifying all.tsx: use Python atomic rewrite (Windows EBUSY race condition can cause Edit to appear successful but fail); bash heredoc with backticks in Python gets truncated → write a .py file and execute.

Environment Quick Reference

• bash PATH at each session: add PortableGit usr/bin + ffmpeg-bin; python use venv: C:/Users/<your username>/.workbuddy/binaries/python/envs/default/Scripts/python.exe; node use managed version directly; tsc run node_modules/typescript/lib/tsc.js (bin/tsc hijacked by fnm shim).