editor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The CLI is self-describing and ships its own API reference. Use

dapi --help

dapi <group> --help

, and

dapi <group> <command> --help

to enumerate every command, argument, and option, and treat live help as authoritative rather than working from memory.

该CLI工具自带说明文档和API参考。使用

dapi --help

、

dapi <group> --help

以及

dapi <group> <command> --help

来查看所有命令、参数和选项，并且应以实时帮助信息为准，而非凭记忆操作。

Footage analysis

素材分析

How to understand source material before editing it. Inspect only the modalities the decision turns on — speech, action, music, graphics, or atmosphere may lead, so there is no fixed priority. Sample the picture against what the audio tells you.

Always probe first.
```
dapi media probe <id|path>
```
reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.
Get the lay of the land. Render a
```
dapi media waveform
```
(audio) and a
```
dapi media filmstrip
```
(video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.
Listen to the audio. Run
```
dapi media listen
```
with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See media-listen.md for prompt patterns.
Transcribe speech. For speech,
```
dapi media transcribe
```
prints the full transcript with word-level start/end times directly — read any segment straight from it.
Sample the video against the audio. Use
```
dapi media grab
```
to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output, e.g.
```
-t '00:32' '00:45' ...
```
. When you need a visual pass without such cues, reach for
```
--auto
```
: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.

如何在编辑前理解原始素材。只需检查影响决策的模态因素——语音、动作、音乐、图形或氛围都可能是关键，因此没有固定的优先级。结合音频信息来采样画面。

始终先探测。
```
dapi media probe <id|path>
```
会报告容器及其轨道，提前告知你文件是否包含视频轨道、音频轨道，或是两者都有。后续所有操作都以此为基础展开。
整体概览。 生成
```
dapi media waveform
```
（音频波形）和
```
dapi media filmstrip
```
（视频胶片条），快速低成本地了解音频的高低音段落分布，以及视觉场景的变化位置。胶片条展示的是大致结构和场景状态，而非裁剪、构图、可读性或精确的剪辑帧。
分析音频内容。 结合上下文（你实际需要了解的信息）编写提示词，运行
```
dapi media listen
```
，并明确要求模型在回答中包含时间戳。提示词模板可参考media-listen.md。
语音转写。 针对语音内容，
```
dapi media transcribe
```
会直接输出包含单词级起止时间的完整转录文本——你可以直接从中读取任意片段。
结合音频采样视频。 使用
```
dapi media grab
```
提取帧。当音频已经指向特定时刻时，直接从转录文本或listen命令的输出中传入这些时间戳，例如
```
-t '00:32' '00:45' ...
```
。当没有此类线索需要视觉遍历素材时，使用
```
--auto
```
参数：它会扫描素材，只保留画面进入新视觉状态的帧，剔除近似重复的帧。

Editing workflow

编辑工作流

Write the brief first. For anything nontrivial, capture the edit as a markdown file: it is the plan every mount works toward and the thing to check the result against.
Lay down the A-roll. Assemble the primary footage as JSX and
```
dapi mount
```
it. Get the spine of the edit right before anything else.
Layer the rest on top. Once the A-roll holds, add B-roll and secondary assets (sound effects, captions, overlays) with further mounts or
```
dapi node insert
```
.

先撰写编辑概要。对于任何非简单任务，将编辑方案记录为Markdown文件：这是所有挂载操作的目标，也是检查最终结果的依据。
搭建主素材轨道（A-roll）。将主要素材组装为JSX并使用
```
dapi mount
```
挂载。先确保编辑的核心框架正确，再进行其他操作。
叠加其余内容。A-roll确定后，通过更多挂载操作或
```
dapi node insert
```
添加副素材轨道（B-roll）和次要资源（音效、字幕、叠加层）。

Compositing

合成

Chrome, scaffolding, and ornament all draw from a visual budget whose default balance is
```
0
```
; prefer not to use them. A cut, hold, or change of size can separate two ideas as clearly as a divider without adding visual clutter. An element earns its place by deepening the story, guiding attention, or expanding imagination, never by filling space.
Video is its own medium, with its own rules; it is not a website, poster, slide, or UI. It is watched, not read.
Let visuals, sound, and voice carry context; let text punctuate rather than explain. Do not add copy, eyebrows, labels, underlines, or brand color highlights unless the brief or explicit video guidance calls for them; examples alone are not instructions.
Choose easing from the intended weight, energy, and continuity of the action.

边框、框架和装饰元素都占用视觉预算，默认平衡值为
```
0
```
；建议尽量避免使用。剪辑、定格或尺寸变化可以像分隔符一样清晰区分两个想法，且不会增加视觉杂乱。元素的存在价值在于深化故事、引导注意力或拓展想象空间，而非填充空白。
视频是独立的媒介，有其自身规则；它不是网站、海报、幻灯片或UI界面。视频是用来观看的，而非阅读。
让视觉、声音和旁白传递背景信息；让文本起到强调作用而非解释说明。除非编辑概要或明确的视频指导要求，否则不要添加文案、眉栏、标签、下划线或品牌色高亮；示例本身不构成指令。
根据动作的预期权重、能量和连贯性选择缓动效果。

Verification

验证

How to confirm a change actually produced what you intended. A clean

mount

insert

does not guarantee a correct-looking composition.

Use
```
dapi node capture
```
to see what the viewer actually gets.
Reconcile captured frames with the brief, and the brief with these guidelines.
Verify after every stage, not only at the end — build the composition incrementally so a problem is caught next to the change that caused it.
Scale verification to the change. A small or incremental tweak the user asked for needs no visual confirmation so the user gets the result back fast and can keep iterating.
Fix the largest viewer-facing problem before polishing details, and recheck related moments after structural changes, since pacing, continuity, emphasis, and meaning are relational.
Use
```
screenshot
```
or
```
logs
```
to debug issues.
DO NOT export/render the scene for visual confirmation —
```
dapi node capture
```
is equivalent to a render but far more efficient. Rendering to a video should be a user-triggered action unless explicitly requested in the prompt.

如何确认修改确实达到了预期效果。顺利完成

mount

或

insert

操作并不保证合成效果正确。

使用
```
dapi node capture
```
查看观众实际看到的内容。
将捕获的帧与编辑概要核对，同时确保编辑概要符合这些准则。
在每个阶段后都进行验证，而非仅在最后——逐步构建合成内容，以便在问题出现时就能定位到导致问题的修改操作。
根据修改规模调整验证方式。对于用户要求的小幅度或增量调整，无需视觉确认，这样用户可以快速获得结果并继续迭代。
在打磨细节前先解决最影响观众体验的问题，结构调整后重新检查相关片段，因为节奏、连贯性、重点和含义都是相互关联的。
使用
```
screenshot
```
或
```
logs
```
命令调试问题。
不要为了视觉确认而导出/渲染场景——
```
dapi node capture
```
与渲染效果等效，但效率高得多。除非提示中明确要求，否则渲染视频应该是用户触发的操作。

Best practices

最佳实践

Wrap entities in
```
<sequence>
```
tags wherever the parent tag supports it — A-roll, B-roll, and other clips belong in sequences so the timeline stays structured rather than a flat, messy pile. (
```
<html>
```
does not support sequences.)
Use the built-in tags for the media a composition is made of (audio, video, images, captions).
For anything 3D, use Three.js drawn into a
```
<surface>
```
tag.
For motion graphics, overlays and UI-heavy graphics, use the
```
<html>
```
tag.
Add auto captions last, after everything else is assembled, so they transcribe the finished audio at its final placement.
Open the application in the background for tasks that don't require an editing UI.
Only render (export) the result when prompted.
Start with a fresh project.

只要父标签支持，就将内容包裹在
```
<sequence>
```
标签中——主素材轨道、副素材轨道和其他剪辑都应放在序列中，这样时间线会保持结构化，而非杂乱无章的扁平堆叠。（
```
<html>
```
标签不支持序列。）
使用合成内容所用媒体对应的内置标签（音频、视频、图像、字幕）。
对于3D内容，使用Three.js绘制到
```
<surface>
```
标签中。
对于动态图形、叠加层和UI密集型图形，使用
```
<html>
```
标签。
在所有内容组装完成后再添加自动字幕，这样字幕会根据最终位置的成品音频进行转写。
对于不需要编辑UI的任务，在后台运行应用程序。
仅在用户提示时才渲染（导出）结果。
从全新项目开始。

Docs

文档

Installation guide, read when dapi is unavailable
An API reference for the JSX syntax

安装指南，当dapi无法使用时阅读
JSX语法的API参考

Examples

示例

Read worked example(s) that match your context.

阅读与你的场景匹配的实践示例。

Video editing

视频编辑

Long-form talking head
Podcast clipping

长镜头访谈
播客剪辑

Prompts

提示词

Writing prompts for
```
dapi media listen
```

为
```
dapi media listen
```
编写提示词

JSX

Basics on how to structure a composition
Driving values from composition time with
```
useTicker
```
Animating with an anime.js timeline
Using an
```
<html>
```
element as the scene root
Embedding an
```
<html>
```
overlay inside a canvas scene
Applying a WGSL shader to a video with shader paint
Rendering a custom WebGPU pass into a
```
<canvas>
```
Rendering a Three.js scene into a
```
<canvas>
```
Generating images and video with
```
generate
```

合成内容的基础结构
使用
```
useTicker
```
根据合成时间驱动数值
使用anime.js时间轴制作动画
使用
```
<html>
```
元素作为场景根节点
在Canvas场景中嵌入
```
<html>
```
叠加层
使用着色器绘制将WGSL着色器应用于视频
将自定义WebGPU通道渲染到
```
<canvas>
```
中
将Three.js场景渲染到
```
<canvas>
```
中
使用
```
generate
```
生成图像和视频