kinetograph-render

查看、检查、渲染

命令接收一个入口：项目文件（.tsx、.ts、.jsx、.js）、.json 场景，或 HTML 页面（其 index.html 或包含它的目录）。使用 --comp <id> 选择合成（compositions <entry> 可列出合成），并通过 --props '{"title":"Hi"}' 或 JSON 文件路径传递属性。不使用 -o 时，输出会写入 out/stills/、out/sheets/ 和 out/renders/，并打印路径。

1. 查看

打开 PNG 查看。下方的 Main 是合成 ID。

• kinetograph strip src/index.tsx -n 12：同时显示 12 个带标签的帧，输出到 out/sheets/Main-strip.png。先执行此命令；它会展示整个动画。--range 10..40、--cols N。
• kinetograph still src/index.tsx 45：单帧，输出到 out/stills/Main-f45.png。
• kinetograph onion src/index.tsx 0..60 -n 6：将多个帧叠加混合以显示运动轨迹，输出到 out/sheets/Main-onion.png。

--scale N 会以 N 倍尺寸绘制。范围 a..b 表示从 a 到 b-1；a..=b 则包含 b。

2. 无需像素即可检查

• lint <entry>（--frames 0,45,89；默认抽取 8 个分布较均匀的帧）：检查文本是否溢出其边界框或画布、图层是否超出画布、文本是否重叠、字体和资源是否缺失，以及类型错误；每项都会附上帧和图层 ID。修复所有 lint 错误。它只检查帧中可能显示的内容：透明度为 0 的图层（或位于透明度为 0 的组内的图层），以及被裁剪内容完全遮挡的图层，在该帧会跳过。
• inspect <entry> --frame 45：显示每个图层解析后的坐标、尺寸、bounds、matrix（画布像素）、效果和文本行。用它来查看，而不是对着图片猜测。
• check <entry>：对项目（最近的 tsconfig.json）运行 tsc --noEmit。渲染不会进行类型检查，因此拼错的属性（opactiy={0.5}）会以完全不透明的状态绘制，且不会报错；lint 会将其报告为 type-error。
• audio analyze <entry>：输出 integratedLufs（null 表示静音；在线视频目标值约为 -14）、truePeakDb（保持低于 -1）、clippedSamples（应为 0）和 silences。可使用 --range、--scenes 0..90,90..180。
• snapshot <entry> --update 会批准帧（默认是第一帧、中间帧和最后一帧；可用 --frames 0,30）；之后运行 snapshot <entry> 会与 __snapshots__/ 进行差异比较，并标记移动超过 2 个级别的像素。
• bench <entry> 会为各阶段计时（--frame、--runs、--range）；effects 会列出效果及其字段。

习惯做法：先运行 lint，再运行 strip，最后运行 render。命令失败时会打印原因：更改任何内容之前，先查看 error.message 和 error.code。

3. 诊断

单独运行 doctor 会说明此安装支持的内容：渲染器、插件、CLI 和技能版本。doctor <entry>（可用 --range）会在每一帧运行 JS 阶段，不使用 GPU，并报告引擎无法绘制的内容（兼容模式；支持的内容见 kinetograph-markup）：

• 正常的帧数（cleanFrames、unsupportedFrames、cleanShare）；
• 按元素、属性和原因分组的各项问题，按影响帧数从多到少排列：出现过的 values、元素的 paths（$0.2 <div>，即宿主树中的位置）和首尾帧都包含在内的 ranges。带有 property 的问题指该元素上的 CSS 属性；值为 null 的问题指元素本身。页面脚本自身的 console.error 或未捕获错误也会被视为问题。

移除或替换排名靠前的问题所指的内容，然后再次运行；100% 正常表示没有内容被遗漏。still、strip 和 render 会在标准错误输出中对相同问题发出警告（使用 --json 时为 compat.leftOut）；--strict 会在遇到此类问题的第一帧时以 UNSUPPORTED_CONTENT 失败。对于使用 DOM 元素或 CSS 的项目，在长时间渲染前运行 doctor。

4. 渲染

kinetograph render src/index.tsx 会生成带音频的 out/renders/Main.mp4。常用选项：

• --draft（尺寸减半，与 --scale 0.5 相同）、--range 0..90、--concurrency 4（同时绘制的帧数；文件相同）。
• 从 1080p 生成 4K 可使用 --scale 2，会直接以该尺寸绘制，不会放大。
• --codec h264|h265|prores|vp9|gif（输出扩展名必须匹配：prores 使用 .mov，vp9 使用 .webm，gif 使用 .gif）。
• --crf 20 或 --video-bitrate 8M，不能同时使用；--prores-profile 4444；--pixel-format yuv444p；--audio-codec opus。
• --sequence 会在 -o 文件夹中为每一帧写入一张图像，而非生成视频。

遇到不兼容的选项组合时，程序会提示需要更改的内容。React 会以生产模式运行（速度更快）；--dev-react 会保留 React 的开发构建，以显示警告。所有标志、Alpha、编解码器和编码器规则，以及 --sequence 的详情，均见 references/export.md。

5. 检查渲染结果

• 阅读输出的摘要：尺寸、编解码器、编码器、像素格式、帧数、repeated 和 renderer: 行。Skia GPU (...) 速度较快；Skia CPU (...) 表示速度较慢。
• 对于长片段，先对一段范围执行 strip，或使用 --draft --range 渲染以检查时序。
• 使用 --json 时，查看 output 和 compat 列表，了解哪些内容被排除。
• 使用 audio analyze 检查声音；要检查透明渲染，可将第一帧作为 PNG 打开（--sequence），或在支持显示 Alpha 的播放器中打开。