Back to Details

compose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Compose

视频合成

This atom owns the full video assembly pipeline. You receive raw outputs from the capture stage and produce a single polished artifact. Follow the pipeline below step by step.
该模块负责完整的视频组装流程。你将接收捕获阶段的原始输出，并生成单个打磨完成的成品。请逐步遵循以下工作流程。

Inputs

输入参数

The command or capture stage should have provided a handoff with two sections:
命令或捕获阶段应提供包含两部分的交接内容：

Mechanical (structured)

结构化参数

  • clips: paths to raw recordings (.cast, .mp4, .webm, .png)
  • driver: tuistory | true-input | agent-browser
  • layout: 
    single
    | 
    side-by-side
  • labels: text for each clip (e.g., "BEFORE (dev)", "AFTER (PR)")
  • speed: multiplier (default 3x)
  • fidelity: 
    auto
    | 
    compact
    | 
    standard
    | 
    inspect
    (optional; auto => side-by-side=inspect, single=standard)
  • title: text for the title card
  • subtitle: one-sentence summary
  • sections: text banners for chapters 
    [{t, title}]
    (optional)
  • keys: keystroke events 
    [{t, label, dur?}]
    (if overlay requested)
  • showcase: preset name -- 
    macos
    , 
    minimal
    , 
    hero
    , 
    presentation
    , 
    factory
    , 
    factory-hero
  • effects tier: 
    utilitarian
    | 
    full
    | 
    none
    (see "Choosing effects at compose time" below)
  • output: desired output path
  • clips：原始录制文件路径（.cast、.mp4、.webm、.png格式）
  • driver：tuistory | true-input | agent-browser
  • layout：
    single
    （单面板）| 
    side-by-side
    （双面板并排）
  • labels：每个剪辑的文本标签（例如："BEFORE (dev)"、"AFTER (PR)"）
  • speed：速度倍数（默认3倍）
  • fidelity：
    auto
    （自动）| 
    compact
    （紧凑）| 
    standard
    （标准）| 
    inspect
    （精细）（可选；自动模式下，双面板布局=精细，单面板=标准）
  • title：标题卡文本
  • subtitle：一句话摘要
  • sections：章节文本横幅 
    [{t, title}]
    （可选）
  • keys：按键事件 
    [{t, label, dur?}]
    （若需要叠加显示）
  • showcase：预设名称 -- 
    macos
    , 
    minimal
    , 
    hero
    , 
    presentation
    , 
    factory
    , 
    factory-hero
  • effects tier：
    utilitarian
    （实用型）| 
    full
    （全效型）| 
    none
    （无特效）（详见下方“合成阶段选择特效”）
  • output：期望的输出路径

Creative (natural language)

自然语言创意指导

Free-text guidance on what to emphasize: which moments to hold, what the title card should convey, whether phase cards are warranted, how to trim dead time. Use this -- along with the effects tier -- for editorial decisions, including choosing specific effects to apply.
关于重点内容的自由文本指引：哪些时刻需要停留、标题卡应传达的信息、是否需要阶段卡片、如何修剪无效时长。结合特效等级，用于编辑决策，包括选择具体应用的特效。

Pipeline

工作流程

1. Build props   →  construct the Showcase JSON props
2. Render        →  render-showcase.sh (converts .cast, stages clips, renders, cleans up)
3. Finalize      →  verify and output
Remotion handles all compositing in a single pass — title cards, transitions, window chrome, backgrounds, keystroke overlays, spotlights, particles, noise, and color grading are all automatic. You construct the props JSON; the engine does the rest.
1. 构建Props   →  生成Showcase JSON配置参数
2. 渲染        →  执行render-showcase.sh（转换.cast文件、处理剪辑、渲染、清理）
3. 最终校验    →  验证并输出成品
Remotion会一次性处理所有合成工作——标题卡、转场、窗口边框、背景、按键叠加、聚光灯、粒子效果、噪点和色彩分级均为自动完成。你只需构建Props JSON，其余工作由引擎完成。

Remotion project & helper script

Remotion项目与辅助脚本

bash
REMOTION_DIR=${DROID_PLUGIN_ROOT}/remotion
RENDER=${DROID_PLUGIN_ROOT}/scripts/render-showcase.sh
bash
REMOTION_DIR=${DROID_PLUGIN_ROOT}/remotion
RENDER=${DROID_PLUGIN_ROOT}/scripts/render-showcase.sh

Showcase mode vs Demo mode

展示模式 vs 演示模式

Both use the same Remotion pipeline but target different visual registers.
ShowcaseDemo
GoalCinematic, high-polish marketing materialClear, utilitarian demonstration — single or comparison, whichever the story calls for
Preset
factory
, 
factory-hero
, or 
hero
macos
, 
minimal
, or 
presentation
Effects tierFull -- spotlight, zoom, callout, keystroke overlay. Go all out.Utilitarian -- zoom for readability, keystroke overlay for user actions
AudienceExternal — landing pages, social, marketingInternal — PR reviews, docs, QA
Decision rule: If the video will be seen outside the eng team, use Showcase mode. If it's for a PR description, internal demo, or documentation embed, use Demo mode. The visual polish layers (warm glow, particles, color grade, motion blur) are always present but their intensity is palette-driven — Factory presets produce rich cinematic warmth while Catppuccin presets stay subtle and cool.
两者使用相同的Remotion工作流，但面向不同的视觉风格。
展示模式演示模式
目标电影质感、高打磨度的营销素材清晰、实用的演示——单面板或对比面板，根据需求选择
预设
factory
, 
factory-hero
, 或 
hero
macos
, 
minimal
, 或 
presentation
特效等级全效型 -- 聚光灯、缩放、标注、按键叠加。全力启用所有特效。实用型 -- 为可读性缩放、为用户操作叠加按键显示
受众外部用户——着陆页、社交平台、营销场景内部团队——PR评审、文档、QA测试
决策规则：如果视频将面向工程团队以外的用户，使用展示模式。如果用于PR描述、内部演示或文档嵌入，使用演示模式。视觉打磨层（暖光、粒子效果、色彩分级、运动模糊）始终存在，但强度由预设决定——Factory预设呈现丰富的电影质感暖色调，而Catppuccin预设保持柔和冷色调。

Choosing effects at compose time

合成阶段选择特效

The command stage committed an effects tier (utilitarian, full, or none). Now that you have actual recordings, choose specific effects:
  • Utilitarian: Add zoom effects for any small or hard-to-read text. Add keystroke overlay if user actions were captured. Skip spotlight and callout unless something is genuinely hard to find on screen.
  • Full: Use the full palette. Spotlight the key proof points. Zoom into details. Add callout annotations where the UI isn't self-explanatory. Layer keystroke overlay throughout. Aim for cinematic -- the viewer should feel guided, not left to scan.
  • None: Pass 
    "effects": []
    in props. Keystroke overlay is still allowed if committed separately.
命令阶段已确定特效等级（实用型、全效型或无特效）。现在你已有实际录制文件，可选择具体特效：
  • 实用型：为小字体或难以阅读的文本添加缩放特效。如果捕获了用户操作，添加按键叠加。除非屏幕内容确实难以定位，否则跳过聚光灯和标注。
  • 全效型：使用全部特效库。聚焦关键证明点。放大细节。在UI不易理解的位置添加标注注释。全程叠加按键显示。追求电影质感——引导观众视线，而非让观众自行扫描。
  • 无特效：在Props中传入 
    "effects": []
    。如果单独指定，仍可保留按键叠加。

Step 1: Choose fidelity and pacing

步骤1：选择画质与节奏

render-showcase.sh
auto-selects 
inspect
for side-by-side and 
standard
for single-clip layouts when 
fidelity
is omitted or set to 
auto
.
FidelityDefault output sizeRemotion encodePolish overlaysBest for
compact
1920x1080H.264 CRF 21, JPEG framesfull grain + gradeSmall embeds
standard
1920x1080H.264 CRF 18, JPEG framesreduced grain + gradeSingle-panel demos
inspect
2560x1440H.264 CRF 14, PNG framesminimal grain + gradeSide-by-side comparisons / tiny text
当
fidelity
省略或设为
auto
时，
render-showcase.sh
会自动为双面板布局选择
inspect
，为单面板布局选择
standard
。
画质等级默认输出尺寸Remotion编码打磨叠加层适用场景
compact
1920x1080H.264 CRF 21，JPEG帧完整噪点+色彩分级小型嵌入场景
standard
1920x1080H.264 CRF 18，JPEG帧减少噪点+色彩分级单面板演示
inspect
2560x1440H.264 CRF 14，PNG帧最低噪点+色彩分级双面板对比 / 小字体内容

.cast conversion behavior

.cast文件转换规则

render-showcase.sh
converts 
.cast
inputs through 
agg -> gif -> ffmpeg -> mp4
before Remotion render, using the asciicast's own cols/rows and fixed font metrics so element positions remain stable across fidelity profiles.
CRITICAL: 
agg
replaces ALL 16 ANSI colors with its theme palette. The render script uses a custom Droid CLI theme. If you manually run 
agg
, never omit 
--theme
and never use built-in themes like 
monokai
or 
dracula
.
The 
--theme
flag accepts a comma-separated hex string (no 
#
prefix): 
bg,fg,color0..color7
(10 values) or 
bg,fg,color0..color7,color8..color15
(18 values for bright variants).
Note: 
tuistory
recordings of the Droid CLI typically emit NO color escape codes -- the CLI uses Ink's direct rendering which doesn't produce standard ANSI SGR sequences in the cast output. The theme's 
bg
(first value: 
181818
) and 
fg
(second value: 
e0d0c0
, warm white) are the only colors that will affect the output. The warm-white fg avoids the cold blue-grey look of default themes.
For other terminals that DO emit ANSI color codes, build the full theme string from the terminal's actual color settings.
Pacing: Target the final video duration, not a speed factor. A blind multiplier either makes text illegible or leaves dead air.
Demo typeTarget durationWhy
Single feature, 3-5 steps30-45sViewer watches the whole thing in one breath
Before/after comparison, side-by-side45-75sEach panel needs time to land; frozen-vs-active contrasts need a beat
Multi-phase or complex flow60-120sPhase cards give the viewer reset points; rushing defeats the purpose
Set the 
speed
prop to hit the target: if the raw recording is 3 minutes and the target is 60s, use 
"speed": 3
. If it's already 40s raw, use 
"speed": 1
or trim dead time instead. Trim first, speed second -- cut LLM thinking pauses, build waits, and network delays from the 
.cast
with 
asciinema cut
or by splitting segments, then apply a gentle speed-up only if still over target.
Keystroke timing adjustment: If a keystroke list was emitted during capture, its timestamps are in raw recording time. When you apply a speed multiplier, you must divide every timestamp by the speed factor before passing it to the Remotion props. A keystroke at raw 
t=6.0s
in a 3x video should appear at 
t=2.0s
.
render-showcase.sh
通过
agg -> gif -> ffmpeg -> mp4
流程转换
.cast
输入文件，使用asciicast自身的列/行和固定字体参数，确保元素位置在不同画质配置下保持稳定。
**重要提示：
agg
会将所有16种ANSI颜色替换为其主题调色板。**渲染脚本使用自定义Droid CLI主题。如果手动运行
agg
，切勿省略
--theme
参数，也不要使用
monokai
或
dracula
等内置主题。
--theme
参数接受逗号分隔的十六进制字符串（不带
#
前缀）：
bg,fg,color0..color7
（10个值）或
bg,fg,color0..color7,color8..color15
（18个值，包含亮色变体）。
注意：Droid CLI的
tuistory
录制通常不会输出颜色转义码——CLI使用Ink直接渲染，不会在cast输出中生成标准ANSI SGR序列。主题的
bg
（第一个值：
181818
）和
fg
（第二个值：
e0d0c0
，暖白色）是仅有的会影响输出的颜色。暖白色前景可避免默认主题的冷蓝灰色调。
对于其他会输出ANSI颜色码的终端，请根据终端实际颜色设置构建完整的主题字符串。

Non-.cast clips

节奏控制：以最终视频时长为目标，而非速度倍数

.mp4
, 
.webm
, and 
.png
clips are passed through to Remotion unchanged except for staging into 
public/
. Re-encode non-
.cast
clips manually only if their pixel format or dimensions are invalid.
盲目设置速度倍数要么导致文本难以辨认，要么留下无效空白时长。
演示类型目标时长原因
单一功能，3-5步操作30-45秒观众可一口气看完整个演示
前后对比，双面板布局45-75秒每个面板都需要时间展示；静态与动态的对比需要停顿
多阶段或复杂流程60-120秒阶段卡片为观众提供重置节点；仓促演示会失去意义
设置
speed
参数以达到目标时长：如果原始录制时长为3分钟，目标时长为60秒，则使用
"speed": 3
。如果原始时长已为40秒，则使用
"speed": 1
或修剪无效时长。先修剪，再调速——使用
asciinema cut
或分割片段，从
.cast
文件中移除LLM思考停顿、构建等待和网络延迟，仅在仍超出目标时长时再适度提速。

Clip aspect ratio (mandatory check for browser captures)

按键时间调整

At the default 1920×1080 output with factory preset margins, panels come out roughly:
LayoutPanel aspect
single
~1760×920 (≈16:9 landscape)
side-by-side
~872×920 per panel (≈8:9, near-square / slight portrait)
.cast
conversions target panel aspect automatically. Pre-recorded 
.mp4
/ 
.webm
clips do not — if the clip aspect doesn't match the panel aspect, the clip will letterbox (with the default 
objectFit: "contain"
) or crop (with 
"cover"
).
Common pitfall: browser captures are typically 16:9 landscape (e.g. 1280×720). Dropped into a 
side-by-side
layout they render as a thin band with giant black bars above and below.
Two fixes, in priority order:
  1. Re-capture at a panel-friendly viewport — go back to the capture stage and set viewport to ~960×1000 for 
    side-by-side
    , ~1280×720 for 
    single
    .
  2. Pass 
    "objectFit": "cover"
    in props     — crops the clip edges to fill the panel. Acceptable when the relevant UI is centered and edges are expendable. Not acceptable if cropped content matters (e.g. sidebar UI cut off).
.cast
clips rarely need this since their rendered aspect is derived from cols/rows; it's almost always a browser-capture concern.
如果捕获阶段输出了按键列表，其时间戳为原始录制时间。当你应用速度倍数时，必须将每个时间戳除以速度倍数后再传入Remotion Props。例如，原始录制中
t=6.0s
的按键，在3倍速视频中应显示在
t=2.0s
。

Duration checkpoint (mandatory, before proceeding)

非.cast格式剪辑

Check whether the planned speed factor produces a final duration within the pacing table's target range:
final_duration = clip_duration / speed_factor
If final_duration is...Action
Within the target rangeProceed
Below the minimumReduce the speed factor until the target is met. If even at 1x the clip is below the minimum, the recording is too short — return to capture and add more interaction steps.
Above the maximumTrim dead time first (
asciinema cut
), then increase the 
speed
prop
This checkpoint is not optional. A video that lands outside the target range fails verification.
.mp4
、
.webm
和
.png
剪辑会直接传入Remotion，仅会被暂存到
public/
目录。仅当像素格式或尺寸无效时，才需要手动重新编码非
.cast
格式的剪辑。

Step 2: Build props

剪辑宽高比（浏览器捕获必须检查）

Choose layout

—
Default: 
single
. One clip of the target/final state. New features, bug-fix proofs, walkthroughs, and README heroes all belong here.
Use 
side-by-side
only when the story is fundamentally a comparison: regression (broken vs fixed), behavior-preserving refactor, or an explicit user request. Never fabricate a "before" clip to justify the side-by-side shape.
Save the 
showcaseSchema
JSON to a temp file:
bash
DEMO_TMP="$(mktemp -d /tmp/droid-demo-XXXXXX)"
PROPS="${DEMO_TMP}/showcase-props.json"

cat > "$PROPS" << 'EOF'
{
  "clips": ["demo.cast"],
  "layout": "single",
  "fidelity": "auto",
  "labels": [],
  "speed": 3,
  "title": "PR #11621 — Prevent session freezes",
  "subtitle": "Bash Mode blocks interactive commands and supports ESC cancellation",
  "preset": "factory",
  "keys": [
    {"t": 2.0, "label": "vim"},
    {"t": 5.5, "label": "sleep 100"},
    {"t": 8.0, "label": "Esc"}
  ],
  "sections": [],
  "effects": [],
  "speedNote": "3x speed",
  "windowTitle": "droid demo"
}
EOF
For a comparison flow, swap 
"clips"
to two paths, 
"layout"
to 
"side-by-side"
, and populate 
"labels"
(e.g., 
["BEFORE (main)", "AFTER (PR #11621)"]
).
Use a run-scoped props path like 
$PROPS
; do not reuse a global 
/tmp/showcase-props.json
across rerenders or concurrent demos.
CRITICAL: 
clipDuration
handling. The render script auto-detects clip duration via ffprobe when 
clipDuration
is omitted from the props. If you set it manually, it must match the actual clip duration or you get blank frames (too long) or truncation (too short). When in doubt, omit it and let the script auto-detect.
在默认1920×1080输出和factory预设边距下，面板尺寸大致如下：
布局面板宽高比
single
~1760×920（≈16:9横屏）
side-by-side
每个面板~872×920（≈8:9，接近方形/轻微竖屏）
.cast
文件转换会自动适配面板宽高比。预录制的
.mp4
/
.webm
剪辑不会自动适配——如果剪辑宽高比与面板不匹配，剪辑会出现黑边（默认
objectFit: "contain"
）或被裁剪（
"cover"
）。
常见问题：浏览器捕获通常为16:9横屏（例如1280×720）。放入
side-by-side
布局时，会呈现为一条细带，上下有巨大黑边。
两种修复方案，优先级如下：
  1. 重新捕获为适配面板的视口——返回捕获阶段，将视口设置为960×1000（用于
    side-by-side
    ）或    1280×720（用于
    single
    ）。
  2. 在Props中传入
    "objectFit": "cover"
    ——裁剪剪辑边缘以填充面板。当相关UI居中且边缘可舍弃时适用。如果裁剪内容重要（例如侧边栏UI被截断），则不适用。
.cast
剪辑几乎不需要此操作，因为其渲染宽高比由列/行决定；这通常是浏览器捕获的问题。

Props reference

时长检查点（必须执行，否则无法继续）

PropTypeRequiredDescription
clips
string[]
yesFilenames (basenames only — the render script handles staging)
layout
"single" | "side-by-side"
yesComposition layout
labels
string[]
yesLabels for each clip (visible in side-by-side; pass 
[]
for single)
fidelity
"compact" | "standard" | "inspect"
noOutput quality/compression profile. Omit for auto-selection by layout.
speed
number
noPlayback speed for 
.cast -> agg
conversion.
title
string
yesTitle card heading
subtitle
string
yesTitle card subheading
preset
preset nameyesVisual preset — see table below
keys
Keystroke[]
yesKeystroke overlay events (pass 
[]
for none)
sections
Section[]
noSection banners to mark chapters (pass 
[]
for none)
effects
Effect[]
yesEffect timeline (pass 
[]
for none)
clipDuration
number
noClip duration in seconds. Auto-detected by render script if omitted.
speedNote
string
noShown on title card (e.g., 
"3x speed"
)
windowTitle
string
noText in the window title bar
width
number
noOutput width (default: 2560 for inspect, else 1920)
height
number
noOutput height (default: 1440 for inspect, else 1080)
objectFit
"contain" | "cover" | "fill"
noHow each clip fits its panel. Default 
"contain"
(letterbox to preserve aspect). Use 
"cover"
when clip aspect doesn't match panel aspect and you'd rather crop than see black bars. See "Clip aspect ratio" below.
codeAnnotations
CodeAnnotation[]
noTimed syntax-highlighted code overlays shown during the main content sequence. See "Code annotations" below.
transitionStyle
"motion-blur" | "flash" | "whip-pan" | "light-leak" | "glitch-lite"
noPresentation used for title→content and content→outro transitions. Default 
"motion-blur"
preserves existing aesthetic. See "Transition styles" below.
检查计划的速度倍数是否能使最终时长符合节奏表的目标范围：
final_duration = clip_duration / speed_factor
如果final_duration...操作
在目标范围内继续执行
低于最小值降低速度倍数直到达到目标。即使1倍速仍低于最小值，说明录制时长过短——返回捕获阶段添加更多交互步骤。
高于最大值先修剪无效时长（
asciinema cut
），再提高
speed
参数
此检查点为必填项。超出目标范围的视频无法通过验证。

Preset quick reference

步骤2：构建Props

—

选择布局

PresetLookPaletteBest for
factory
Warm black bg, traffic lights, 12px radius, 80px marginFactory (warm)Official Factory content
factory-hero
Same as factory + gradient bgFactory (warm)Factory landing pages, social
hero
Gradient bg, generous margins, prominent shadowCatppuccin (cool)Non-Factory marketing
macos
Dark bg, traffic lights, clean frameCatppuccin (cool)General-purpose demos
presentation
Black bg, generous marginsCatppuccin (cool)Slide decks, talks
minimal
No window bar, tiny radius, tight marginsCatppuccin (cool)Docs embeds, inline clips
默认：
single
。展示目标/最终状态的单个剪辑。新功能、修复证明、操作指南和README主视觉均适用此布局。
仅当内容本质为对比时使用
side-by-side
：回归测试（损坏vs修复）、行为保留重构或明确的用户需求。切勿为了使用双面板布局而伪造“之前”的剪辑。
将
showcaseSchema
JSON保存到临时文件：
bash
DEMO_TMP="$(mktemp -d /tmp/droid-demo-XXXXXX)"
PROPS="${DEMO_TMP}/showcase-props.json"

cat > "$PROPS" << 'EOF'
{
  "clips": ["demo.cast"],
  "layout": "single",
  "fidelity": "auto",
  "labels": [],
  "speed": 3,
  "title": "PR #11621 — 防止会话冻结",
  "subtitle": "Bash模式阻止交互命令并支持ESC取消",
  "preset": "factory",
  "keys": [
    {"t": 2.0, "label": "vim"},
    {"t": 5.5, "label": "sleep 100"},
    {"t": 8.0, "label": "Esc"}
  ],
  "sections": [],
  "effects": [],
  "speedNote": "3x speed",
  "windowTitle": "droid demo"
}
EOF
对于对比流程，将
"clips"
改为两个路径，
"layout"
改为
"side-by-side"
，并填充
"labels"
（例如：
["BEFORE (main)", "AFTER (PR #11621)"]
）。
使用作用域内的Props路径（如
$PROPS
）；不要在重新渲染或并发演示中重用全局的
/tmp/showcase-props.json
。
重要提示：
clipDuration
处理。如果Props中省略
clipDuration
，渲染脚本会通过ffprobe自动检测剪辑时长。如果手动设置，必须与实际剪辑时长匹配，否则会出现空白帧（时长过长）或截断（时长过短）。不确定时，省略该参数让脚本自动检测。

Keystroke schema

Props参考

{ t: number, label: string, dur?: number }
  • t
    : Time in seconds relative to clip start (not title card). Adjust for speed factor.
  • label
    : Display text (e.g., 
    "Ctrl+C"
    , 
    "vim main.rs"
    )
  • dur
    : Display duration in seconds (default: 1.2s). Auto-cut when next keystroke starts.
参数类型必填描述
clips
string[]
是文件名（仅基础名——渲染脚本处理暂存）
layout
"single" | "side-by-side"
是合成布局
labels
string[]
是每个剪辑的标签（双面板布局可见；单面板传入
[]
）
fidelity
"compact" | "standard" | "inspect"
否输出质量/压缩配置。省略时根据布局自动选择。
speed
number
否
.cast -> agg
转换的播放速度。
title
string
是标题卡主标题
subtitle
string
是标题卡副标题
preset
预设名称是视觉预设——见下方表格
keys
Keystroke[]
是按键叠加事件（无则传入
[]
）
sections
Section[]
否标记章节的横幅（无则传入
[]
）
effects
Effect[]
是特效时间线（无则传入
[]
）
clipDuration
number
否剪辑时长（秒）。省略时由渲染脚本自动检测。
speedNote
string
否显示在标题卡上（例如：
"3x speed"
）
windowTitle
string
否窗口标题栏文本
width
number
否输出宽度（默认：inspect画质为2560，其他为1920）
height
number
否输出高度（默认：inspect画质为1440，其他为1080）
objectFit
"contain" | "cover" | "fill"
否剪辑适配面板的方式。默认
"contain"
（添加黑边以保留宽高比）。当剪辑宽高比与面板不匹配且宁愿裁剪也不愿显示黑边时，使用
"cover"
。详见“剪辑宽高比”部分。
codeAnnotations
CodeAnnotation[]
否主内容序列中显示的定时语法高亮代码叠加层。用于PR演示，可将关键源码变更与运行时效果并列展示。
transitionStyle
"motion-blur" | "flash" | "whip-pan" | "light-leak" | "glitch-lite"
否标题→内容和内容→结尾转场的呈现方式。一次渲染中的两个转场使用相同风格。
flash
和
light-leak
的色调取自预设调色板。默认
motion-blur
始终适用；预设级别的指引见
showcase/SKILL.md
。

Section schema

预设速查

json
{ "t": 2.0, "title": "Testing basic echo" }
  • t
    : Time in seconds relative to clip start (not title card). Adjust for speed factor.
  • title
    : Display text for the section header. Remains visible until the next section starts.
预设视觉风格调色板适用场景
factory
暖黑色背景、交通灯样式、12px圆角、80px边距Factory（暖色调）官方Factory内容
factory-hero
与factory相同 + 渐变背景Factory（暖色调）Factory着陆页、社交平台
hero
渐变背景、宽边距、突出阴影Catppuccin（冷色调）非Factory营销内容
macos
深色背景、交通灯样式、简洁边框Catppuccin（冷色调）通用演示
presentation
黑色背景、宽边距Catppuccin（冷色调）幻灯片、演讲
minimal
无窗口栏、小圆角、窄边距Catppuccin（冷色调）文档嵌入、内联剪辑

Effect types

按键事件格式

EffectPropsDescription
fade-in
t
, 
dur
Fade from black
fade-out
t
, 
dur
Fade to black
zoom
t
, 
dur
, 
to: {x,y,w,h}
Directed zoom to a target region (30% in, 40% hold, 30% out)
spotlight
t
, 
dur
, 
on: {x,y,w,h}
, 
dim?
Dim everything except a region (
dim
: 0–1, default 0.6)
callout
t
, 
dur
, 
text
, 
at: {x,y}
Text overlay anchored to a point
Regions use percentage strings (e.g., 
"25%"
) relative to the video dimensions.
{ t: number, label: string, dur?: number }
  • t
    ：相对于剪辑开始的时间（秒）。需根据速度倍数调整。
  • label
    ：显示文本（例如：
    "Ctrl+C"
    、
    "vim main.rs"
    ）
  • dur
    ：显示时长（秒，默认1.2秒）。下一个按键开始时自动结束显示。

When to use effects

章节格式

EffectUse when…Don't use when…
spotlight
Drawing attention to a specific region (error, status change)The whole frame is relevant
zoom
Small text or detail that's hard to read at full scaleContent is already legible
callout
Annotating something the viewer might not recognizeThe UI is self-explanatory
Keystroke overlayShowing user actions (typing, key presses)No user interaction in the clip
Less is more. One well-timed spotlight has more impact than five overlapping effects.
json
{ "t": 2.0, "title": "测试基础echo命令" }
  • t
    ：相对于剪辑开始的时间（秒）。需根据速度倍数调整。
  • title
    ：章节标题显示文本。持续显示到下一章节开始。

Code annotations

特效类型

Timed syntax-highlighted code card laid over the captured video. Use for PR demos where the decisive source change needs to sit next to the runtime proof.
FieldTypeRequiredDescription
t
number
yesStart time in seconds, relative to clip start. Adjust for 
speed
factor (same rule as 
keys[].t
).
dur
number
yesHow long the card stays visible, in seconds.
code
string
yesSource text; 
\n
for multiline; no trailing newline.
language
string
noPrism language id (
tsx
, 
ts
, 
py
, 
rust
, 
bash
, ...). Default 
tsx
.
title
string
noSmall caption above the code (usually a file path).
highlight
[{start,end}]
no1-based inclusive line ranges with accent background + left border.
focus
[{start,end}]
no1-based inclusive line ranges kept at full opacity; others are dimmed/blurred.
position
"top-right" | "center" | "bottom-left"
noDefault 
"top-right"
. Move to 
"bottom-left"
if the captured top-right is load-bearing.
Keep it short — aim for ≤ 15 lines per card, hold for 3–6 seconds.
特效参数描述
fade-in
t
, 
dur
从黑色淡入
fade-out
t
, 
dur
淡出到黑色
zoom
t
, 
dur
, 
to: {x,y,w,h}
定向缩放到目标区域（30%进入、40%停留、30%退出）
spotlight
t
, 
dur
, 
on: {x,y,w,h}
, 
dim?
调暗除目标区域外的所有内容（
dim
：0–1，默认0.6）
callout
t
, 
dur
, 
text
, 
at: {x,y}
锚定到指定点的文本叠加层
区域使用百分比字符串（例如：
"25%"
），相对于视频尺寸。

Transition styles

特效使用场景

transitionStyle
selects the title→content and content→outro crossfade presentation. Both transitions in one render share the same style. 
flash
and 
light-leak
derive their tint from the preset palette. Default 
motion-blur
is always safe; preset-tier guidance lives in 
showcase/SKILL.md
.
StyleFeelUse when…
motion-blur
Subtle dolly, blur + opacity crossfadeDefault for PR demos, Factory content, most showcase work
flash
Quick palette-tinted flash at midpointBug-fix proofs where the "after" state should feel sudden
whip-pan
Horizontal pan + motion blurEnergetic showcase / marketing when pacing is fast
light-leak
Warm gradient sweepFactory-branded landing/social clips
glitch-lite
RGB channel offset + horizontal bandSecurity/vulnerability proof, terminal aesthetic; never default, never twice
特效适用场景…不适用场景…
spotlight
吸引注意力到特定区域（错误、状态变化）整个画面内容都相关
zoom
小字体或细节在全屏下难以阅读内容已清晰可辨
callout
注释观众可能不熟悉的内容UI本身易于理解
按键叠加展示用户操作（打字、按键）剪辑中无用户交互
少即是多。一次时机恰当的聚光灯效果比五个重叠特效更有冲击力。

Step 3: Render

代码注释

Use the render script — it handles clip staging, duration detection, rendering, and cleanup:
bash
RENDER=${DROID_PLUGIN_ROOT}/scripts/render-showcase.sh
定时语法高亮代码卡片，叠加在捕获的视频上。用于PR演示，可将关键源码变更与运行时效果并列展示。
字段类型必填描述
t
number
是开始时间（秒），相对于剪辑开始。需根据
speed
倍数调整（与
keys[].t
规则相同）。
dur
number
是卡片显示时长（秒）。
code
string
是源码文本；用
\n
换行；无 trailing newline。
language
string
否Prism语言ID（
tsx
, 
ts
, 
py
, 
rust
, 
bash
等）。默认
tsx
。
title
string
否代码上方的小标题（通常为文件路径）。
highlight
[{start,end}]
否1-based包含性行范围，带高亮背景+左侧边框。
focus
[{start,end}]
否1-based包含性行范围保持完全不透明；其他行变暗/模糊。
position
"top-right" | "center" | "bottom-left"
否默认
"top-right"
。如果捕获的右上角内容重要，可移至
"bottom-left"
。
保持简洁——每张卡片最多15行，显示3–6秒。

Basic render

转场风格

$RENDER --props "$PROPS" --output /tmp/demo.mp4
/tmp/before.cast /tmp/after.cast
transitionStyle
选择标题→内容和内容→结尾的交叉淡入呈现方式。一次渲染中的两个转场使用相同风格。
flash
和
light-leak
的色调取自预设调色板。默认
motion-blur
始终安全；预设级别的指引见
showcase/SKILL.md
。
风格感受适用场景…
motion-blur
微妙的推拉、模糊+透明度交叉淡入PR演示、Factory内容、大多数展示工作的默认选择
flash
转场中点的快速调色板色调闪烁修复演示，其中“之后”的状态应显得突然
whip-pan
水平平移+运动模糊充满活力的展示/营销场景，节奏较快
light-leak
暖色调渐变扫过Factory品牌的着陆页/社交剪辑
glitch-lite
RGB通道偏移+水平条纹安全/漏洞演示、终端风格；切勿默认使用，切勿重复使用

Or with inline props (useful for simple cases)

步骤3：渲染

$RENDER --props-inline '{"clips":["clip.mp4"],"layout":"single","labels":[],"title":"Demo","subtitle":"Test","preset":"macos","keys":[],"effects":[]}'
--output /tmp/demo.mp4 /tmp/clip.mp4

The script:
1. Converts `.cast` inputs to `.mp4` using the selected fidelity profile
2. Copies clip files into `${REMOTION_DIR}/public/`
3. Auto-detects `clipDuration` via ffprobe if missing from props
4. Runs `npx remotion render Showcase` with profile-specific encode flags
5. Cleans up staged and generated clips

**Quick frame check** (sanity-check layout before full render):

```bash
cd ${REMOTION_DIR}
npx remotion still Showcase --props="$(cat "$PROPS")" --frame=30 --scale=0.5 /tmp/check.png
Render time: Expect ~1-3 minutes for a 30-60s video at 1920x1080. Set worker timeouts accordingly (5 minutes is safe).
使用渲染脚本——它会处理剪辑暂存、时长检测、渲染和清理：
bash
RENDER=${DROID_PLUGIN_ROOT}/scripts/render-showcase.sh

Step 4: Finalize

基础渲染

Check the result:
bash
ffprobe -v quiet -print_format json -show_format -show_streams /tmp/demo.mp4
Confirm:
  • Resolution is 1920x1080 (or matches the expected output)
  • Duration is reasonable (not 0s, not hours)
  • File size is manageable (under 5 MB for GitHub embeds, 25 MB hard limit)
  • Pixel format is yuv420p (universal playback)
$RENDER --props "$PROPS" --output /tmp/demo.mp4
/tmp/before.cast /tmp/after.cast

Outputs

或使用内联Props（适用于简单场景）

Hand to the verify stage:
undefined
$RENDER --props-inline '{"clips":["clip.mp4"],"layout":"single","labels":[],"title":"Demo","subtitle":"Test","preset":"macos","keys":[],"effects":[]}'
--output /tmp/demo.mp4 /tmp/clip.mp4

脚本执行以下操作：
1. 使用选定的画质配置将`.cast`输入转换为`.mp4`
2. 将剪辑文件复制到`${REMOTION_DIR}/public/`
3. 如果Props中缺少`clipDuration`，通过ffprobe自动检测
4. 使用配置特定的编码标志运行`npx remotion render Showcase`
5. 清理暂存和生成的剪辑

**快速帧检查**（完整渲染前验证布局）：

```bash
cd ${REMOTION_DIR}
npx remotion still Showcase --props="$(cat "$PROPS")" --frame=30 --scale=0.5 /tmp/check.png
渲染时间：1920x1080分辨率下，30-60秒的视频预计需要1-3分钟。相应设置工作超时（5分钟较为安全）。

Compose outputs

步骤4：最终校验

  • video: /tmp/demo-pr-11621.mp4
  • resolution: 1920x1080
  • duration: 42s
  • size: 3.2 MB
  • preset: factory
  • keystrokes: 3 events overlaid
  • effects: 1 spotlight
  • engine: remotion
undefined
检查结果：
bash
ffprobe -v quiet -print_format json -show_format -show_streams /tmp/demo.mp4
确认：
  • 分辨率为1920x1080（或符合预期输出）
  • 时长合理（不是0秒，也不是数小时）
  • 文件大小可控（GitHub嵌入建议小于5MB，硬限制25MB）
  • 像素格式为yuv420p（通用播放格式）

Screenshot-only artifacts (proofs, QA)

输出

Not every deliverable is a video. For proof and QA workflows, compose may just organize screenshots and snapshots:
交付给验证阶段：
undefined

Annotated screenshot set

合成输出

bash
ffmpeg -y -i before.png -i after.png \
  -filter_complex "
    [0:v]scale=960:-1[left];
    [1:v]scale=960:-1[right];
    [left][right]hstack=inputs=2[out]" \
  -map "[out]" comparison.png
  • video: /tmp/demo-pr-11621.mp4
  • resolution: 1920x1080
  • duration: 42s
  • size: 3.2 MB
  • preset: factory
  • keystrokes: 3 events overlaid
  • effects: 1 spotlight
  • engine: remotion
undefined

Markdown report with embedded evidence

仅截图成品（验证、QA）

For text-based deliverables, organize the evidence into a structured report rather than a video. The verify stage handles this.
并非所有交付物都是视频。对于验证和QA工作流，合成阶段可能只需整理截图和快照：
—

带注释的截图集

—
bash
ffmpeg -y -i before.png -i after.png \
  -filter_complex "
    [0:v]scale=960:-1[left];
    [1:v]scale=960:-1[right];
    [left][right]hstack=inputs=2[out]" \
  -map "[out]" comparison.png
—

包含嵌入证据的Markdown报告

—
对于文本类交付物，将证据整理为结构化报告而非视频。验证阶段负责处理此工作。