Remotion 代码讲解器(remotion-code-explainer)
概述
将任何源代码文件转换为沉浸式、帧同步的 1920×1080 30fps MP4 Remotion 讲解视频,采用 单画面 Log2Base2 Studio 格式。
绝不将屏幕分割成并排的侧面板或拥挤的多卡片墙。每段视频只使用 一个统一的可视化舞台(<SinglePaneStage>),让观众的注意力完全集中在代码的执行过程上:
- 极简顶栏(
44px,内置于SinglePaneStage):- 左侧显示课程标题和当前活动章节标签;右侧显示微妙的步骤计数器和细进度条。
- 单个统一的 Log2Base2 舞台(
SinglePaneStage— 100% 宽度):- 聚焦的单行代码聚光灯标题:仅显示 当前步骤标题 和 单行活动代码(清晰的等宽字体,使用
borderBottom: "2px solid #FACC15"高亮当前朗读中的令牌原位,绝不添加水平内边距)以及 一个 紧凑的活动标注标签(令牌→通俗易懂的解释),该标签在triggerFrame时刻弹入。 - 全宽沉浸式 SVG 画布(
viewBox="0 0 1600 680"):宽敞、连续的动态图形,将 Log2Base2 内存/执行可视化(带标签的内存盒0x1004、可变变量、动态strokeDashoffset指针箭头、栈帧推入/弹出、数组/树交换)与实时 UI/stdout/张量预览直接结合在 同一 开放画布上。
- 聚焦的单行代码聚光灯标题:仅显示 当前步骤标题 和 单行活动代码(清晰的等宽字体,使用
- 极简底部字幕栏(
VoiceoverCaptionBar—68px):- 干净居中的逐词高亮字幕,由精确的 TTS
WordBoundary毫秒级时间戳(startMs、endMs)驱动。
- 干净居中的逐词高亮字幕,由精确的 TTS
依赖项
remotion-best-practices(~/.gemini/skills/remotion/SKILL.md):必须遵循所有 Remotion 动画规则(useCurrentFrame()、interpolate()、spring()、<Sequence premountFor>、<Audio>、@remotion/google-fonts,以及零 CSS 过渡)。uv(~/.gemini/config/plugins/science/skills/uv/SKILL.md):需要使用uv run --with edge-tts执行神经语音合成和WordBoundary时间戳提取。
快速开始
# 1. 搭建 Remotion 讲解项目脚手架
uv run python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
scaffold \
--project-dir "/path/to/project" \
--source-file "/path/to/source.ext" \
--output "/path/to/project/scaffold-status.json"
# 2. 合成自然神经语音 + 精确的 WordBoundary 和令牌时间戳
uv run --with edge-tts python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
synthesize-voiceover \
--project-dir "/path/to/project" \
--beats-json "/path/to/project/beats.json" \
--voice "en-US-AndrewNeural" \
--rate "+2%" \
--pause-sec 0.40 \
--output "/path/to/project/public/voiceover/manifest.json"
# 3. 通过快速的 8 线程关键帧去重渲染器渲染最终 1080p 30fps MP4
uv run python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
render-mp4 \
--project-dir "/path/to/project" \
--composition-id "CodeExplainer" \
--out-name "Explainer.mp4" \
--concurrency 8 \
--output "/path/to/project/render-report.json"
沉浸式叙事与工作流程
- 设计生动的节拍(
beats.json):- 编写清晰、对话式的解说词,立即抓住观众对代码行为背后原因的探究兴趣。
- 保持
codeSnippet集中(1–4行),以便传递给<SinglePaneStage>的活动行中逐字包含活动token。 - 在涉及数据包移动、指针跳跃、数组交换或实时张量/UI 动画的节拍上,设置
"motionStepFrames": 2。
- 搭建项目并合成语音:
- 通过
scripts/code_explainer_cli.py运行scaffold(复制SinglePaneStage.tsx、VoiceoverCaptionBar.tsx和render_full_mp4.mjs)和synthesize-voiceover。
- 通过
- 创作全画幅动态图形(
viewBox="0 0 1600 680"):- 将您动画化的 Log2Base2 × KodeKloud SVG 故事板作为
children传递给<SinglePaneStage>。 - 展示,而非讲述:用物理运动替代静态的代码墙和文本框——值从寄存器/变量飞入内存槽、指针平滑重路由、数据包跨越组件传输,以及实时状态/UI 输出在同一开放画布上更新。
- 将动态网格或滚动轨迹包裹在
<clipPath>中,以避免运动溢出其区域。
- 将您动画化的 Log2Base2 × KodeKloud SVG 故事板作为
- 验证静态帧并渲染最终 MP4:
- 运行
npm run lint并使用read_file检查代表性静态帧(npx remotion still),以验证无重叠或裁剪。 - 运行
render-mp4(scripts/render_full_mp4.mjs),确保最终的.mp4保存到out/目录、项目根目录和工作区根目录。
- 运行
速率限制与常见错误
scripts/code_explainer_cli.py强制执行/tmp/remotion_edge_tts.lock(0.35s间隔,3 次重试,退避时间为1s/2s/4s)。- 切勿 使用双区域分屏仪表板或倾倒 40 行滚动代码墙;保持屏幕只有一个
<SinglePaneStage>面板。 - 切勿 为高亮的内联令牌添加水平
padding(仅使用borderBottom: "2px solid #FACC15"和backgroundColor)。 - 切勿 在 SVG 舞台内使用静态文本卡片,而应利用动画的内存/指针/数据包运动来直观演示概念。