skill-technical-remotion

name

skill-technical-remotion

description

Use when a finalized narration script must become a stable-layout Remotion or HTML/PPT-style explainer video and the user requires a strict pause-unit narration JSON, BlueMagpie-TTS reference cloning with minimum-plus-editorial pacing, Qwen word-level synchronization, accurate subtitles, official technical preview assets, one visible semantic animation per narration unit, or a 9:16 vertical technical Short.

Skill Technical Remotion

Overview

Build source-independent explainer videos from one approved script, one strict minimal narration JSON, and one canonical final narration WAV. Generate and select audio first, derive captions and canonical semantic cues from Qwen timestamps, derive a separate speech-anticipating visual-cue layer, then render and verify the Remotion composition.

Keep article writing outside this skill

• Accept an approved script, transcript, or structured narration as the production input. Do not silently rewrite approved wording.
• When the request is a concise Traditional Chinese Short introduction for an AI model, software feature, developer tool, or other technology and no approved script exists, REQUIRED CONDITIONAL SUB-SKILL: use skill-writing-technical-shorts for the article. Resume this skill only after that script is complete.
• For other article formats, use the writing skill selected for that format. Do not copy writing formulas into this skill.
• Keep research citations outside spoken narration. Preserve the display script and minimal narration separately from TTS-only pronunciation aliases and provider-specific control text.

Required production skills

• REQUIRED AUDIO SUB-SKILL: use tts-skill for the strict narration schema, PCM pause assembly, mastering, and final-audio clock rules. Do not inherit its global Fish Audio provider in this workflow: skill-technical-remotion requires its own BlueMagpie-TTS take-05 profile unless the user explicitly overrides it.
• REQUIRED SHORT SUB-SKILL: use remotion-video-creation for Remotion implementation rules whenever the output is a Short. A Short defaults to 1080×1920 (9:16); do not let a landscape template or sub-skill override that format.
• REQUIRED LANDSCAPE SUB-SKILL: use plan-geometric-explainer-video only for non-Short landscape explainers that need its 16:9 geometric grammar. Do not route a Short through its 16:9 output contract.
• REQUIRED COMPLETION SKILL: use verification-before-completion before declaring the video finished.

Read this skill's own references/bluemagpie-default-voice.json before generating narration. Preserve the exact-byte bundled 28.32-second source selected by the user, but synthesize only with its declared 4.222125–12.196063-second lossless derivative because the full source failed content checks and exceeds BlueMagpie's recommended reference duration. Verify both hashes, formats, durations, derivation bounds, embedded source provenance, model, loader node, and TTS node. Resolve the derivative to an absolute reference_audio_path; do not create another trim, denoise, substitute it, or replace it with the global Fish Audio default.

Do not reopen historical motion-reference videos merely to imitate another creator's style. Current official product or research assets requested for technical evidence are allowed only through the provenance workflow below; otherwise work from the current script, final audio, timing artifacts, brand rules, and supplied production assets.

Production workflow

1. Lock the display script and build the minimal narration. Run scripts/prepare_minimal_narration.py build, then validate, before any TTS call. narration.json must be a non-empty array whose objects contain exactly text then pause_after_ms; no IDs, page fields, captions, tts_text, paths, seeds, or hashes are allowed. Make every deliberate audible pause one text item, retain the boundary punctuation, and allow no deliberate pause inside an item. For Traditional Chinese, split at ，；：。！？; keep the enumeration mark 、 inside the item unless the editor explicitly wants physical silence there. Concatenating all text values must reproduce the approved script exactly after removing layout-only line breaks.
2. Separate production metadata. Store scene/page ranges and labels in scenes.json; store pronunciation-only wording in pronunciation-overrides.json. Run scripts/materialize_narration_manifest.py to derive disposable stable IDs, page metadata, and TTS aliases for legacy consumers. Never edit the derived manifest or copy its fields back into narration.json.
3. Generate pause-unit candidates. Run this skill's scripts/generate_bluemagpie_tts.py to render one lossless BlueMagpie output for every minimal narration item with the canonical reference_audio_path. For a quality-selected run, generate three independent candidates per pause unit with the approved voice recipe. When the live schema exposes seed, vary accepted seeds; otherwise use the profile-approved CFG values 1.8, 2.0, and 2.2 so ComfyUI does not return one cached candidate three times. Record prompt/node IDs, CFG, output hashes, generation info, and a seed only when the live schema exposes one; never invent a seed. Keep Traditional Chinese TTS input unless the user explicitly approves another pronunciation strategy.
4. Select by pronunciation, then confidence. Run unprompted Qwen/Qwen3-ASR-1.7B; do not use Whisper. First reject any candidate whose normalized pronunciation differs from its approved pause unit. For Chinese, compare normalized Pinyin syllable sequences while preserving canonical Latin/product-name tokens. Among pronunciation-equivalent candidates, select the highest Qwen mean token log-probability. Record every candidate, transcript, pronunciation result, score, seed, and winner in candidate_selection_manifest.json.

Read references/production-contract.md before scaffolding the project or defining deliverables.

Hard gates

• Never generate final timestamps before the final WAV is locked.
• Any audio change invalidates Qwen timing, captions, cues, render, and sync validation.
• Require the exact two-field narration.json schema and exact approved-script reconstruction before TTS. Any missing pause boundary, extra key, rewritten word, or stale metadata mapping fails.
• Require physical PCM silence in the final WAV: every narration item's pause_after_ms is a lower bound. Any added silence must come from pacing-overrides.json, be non-negative and reasoned, and be recorded as required + extra = effective. A pause tag, hidden reduction, inferred default, or duplicated global gap does not pass.
• Require Qwen3 ASR rather than Whisper for BlueMagpie candidate selection and listen checks. A candidate must pass pronunciation equivalence before confidence ranking.
• Never overwrite canonical Qwen cue timestamps to make animation feel synchronized. Derive a separate visual timestamp and require a 0.30–0.60-second semantic lead.
• Treat visual-only timing changes as renderer changes: do not regenerate audio or rerun ASR; prove the WAV and SRT hashes are unchanged. Treat any editorial-pause change as an audio change and realign everything.
• For Short output, require a true 1080×1920 9:16 composition unless the user explicitly requests another orientation. A letterboxed or scaled-down landscape canvas does not pass.
• Require exactly one sentence-animation mapping for every minimal narration item and at least one visible semantic change per mapping. Captions, global progress, ambient loops, and page transitions do not satisfy this gate by themselves.
• Require every narration unit to pass visual-semantic-qc.json. Trigger-only QC, an unreviewed before/after pair, inverted meaning, unrelated content, or an empty shell does not pass.
• Fail recurring beat motion that alternates entrance directions, relocates a stable panel, uses low-damping bounce, shakes or scale-pulses by default, or makes the viewer reacquire the same information region every sentence.
• Require a 1× continuous-motion review and motion-stability-qc.json; before/after stills cannot prove temporal stability.
• Require final stills-manifest.json evidence to be decoded from the candidate delivery MP4, and require its video SHA-256 to match that MP4. Independently rendered browser stills are iteration aids, not final evidence.
• Require contiguous per-scene filmstrips sampled at no less than 2 fps and recorded in filmstrip-manifest.json.
• Fail any unintended FFmpeg blackdetect=d=0.5 interval, especially a transition gap created by compounded non-overlapping fades.

Quick reference

Input or stage	Canonical artifact	Consumers
Approved wording	approved script + two-field narration.json	TTS, captions
Editorial pacing	pacing-overrides.json	PCM assembly, page holds, timing QC
Scene mapping	scenes.json	derived manifest, storyboard, timing
Pronunciation aliases	pronunciation-overrides.json	TTS only
Derived production metadata	generated narration manifest	legacy TTS/timing consumers
Locked voice	final-narration.wav	Qwen, Remotion, delivery
Qwen alignment	raw word timestamps	captions, scenes, named cues
Canonical timing	timing JSON + SRT + animation-cues.json	captions, provenance
Visual timing	visual-animation-cues.json	Remotion animation triggers
Sentence motion coverage	sentence-animation-map.json + sentence-animation-qc.json	Remotion, still review, delivery QC
Visual semantic audit	visual-semantic-qc.json	per-unit meaning and asset-relevance delivery gate
Final-MP4 frame evidence	stills-manifest.json	exact per-unit before/after and cue-boundary review
Decoded motion review	filmstrip-manifest.json	contiguous per-scene temporal inspection
Official previews	official-assets.json + local derivatives	fixed preview viewport, provenance QC
Motion stability	motion-stability-qc.json	continuous-playback delivery gate
Render	MP4	sync, stream, decode, loudness QC

Common mistakes

• Animating before audio is locked: discard the timing and realign.
• Using ASR spelling as subtitles: retain the display script and use ASR timestamps only.
• Fixing pronunciation inside narration.json: add the alias to pronunciation-overrides.json instead.
• Triggering effects at guessed seconds: bind each effect to a named aligned cue.
• Starting visuals exactly when the word is heard: derive a 0.30–0.60-second anticipatory visual cue while preserving the canonical cue.
• Slowing page changes by moving narration: keep audio fixed and reallocate the physical page gap to hold, transition, and pre-roll.
• Treating one full sentence as one unit: split every deliberate ，；：。！？ pause into its own minimal narration item.
• Copying IDs, page labels, captions, aliases, or paths into narration.json: keep them in separate inputs or generated manifests.
• Trusting TTS punctuation or control text for pacing: assemble pause-unit WAVs with the exact per-item PCM silence and retain pause-timing.json.
• Treating pause_after_ms as both minimum and final duration: keep it as the lower bound and record selective additions separately with reasons.
• Reusing a 16:9 scene inside a portrait wrapper: rebuild the hierarchy for 9:16 instead of letterboxing or shrinking the landscape canvas.
• Letting several narration units share one unchanged diagram: assign every unit its own visible semantic reveal, highlight, connector, transformation, or state change and validate 100% coverage.
• Treating trigger coverage as semantic approval: inspect every unit's actual before/after state and record what changed.
• Showing a positive MOTION or AUDIO card for narration that says motion cannot be seen or audio cannot be heard: visualize the absence, mute, or blocked state.
• Forcing an image or clip into the video because it was downloaded or comes from an official source: use it only when the narration explicitly explains it.
• Leaving an empty shell while waiting for the next phase: use a meaningful current state or remove the container until its content is introduced.
• Making every unit animate by flying a replacement card from alternating sides: keep the information region fixed and animate the diagram state inside it.
• Inspecting only stills: watch the contiguous rendered motion at 1× to catch bounce, jitter, repeated reacquisition, and non-seamless loops.
• Trusting independently rendered stills as delivery evidence: decode the exact frames from the candidate final MP4 and bind their hashes to its SHA-256.
• Fading one scene out and the next scene in without overlap: this creates a near-black dead zone; use a hard cut, a real overlap, or persistent chrome.