Pixerate 视频编辑器是做什么的？

项目是纯 JSON 格式：帧尺寸、fps、背景、资产（视频、音频或图像文件，带有 src，对于视频和音频还有 duration）、轨道自上而下排列（视频轨道承载媒体、标题和颜色片段；音频轨道承载声音；较早的视频轨道绘制在较晚的视频轨道之上）以及标记。片段在时间线上具有 start 和 duration；媒体片段还有其资产的 in 点、speed、volume、muted；每个片段可以具有 fadeIn、fadeOut、opacity、fit 和 transform，以及从同一条轨道上在其开始位置结束的片段的 transition。

项目还可以包含嵌套的序列（{ id, name, tracks }，其自己的时间线从 0 开始）。复合片段（type: "sequence"，sequence，in）将其中一个序列的一段作为单一画面和单一声音播放：其不透明度、变换、混合、分级、LUT、淡入淡出、过渡和动画应用于序列的合成画面，其 volume、muted 和淡入淡出应用于序列的混音。复合片段以正常速度播放（没有 speed 或变速），序列内的片段可以被读取（list_video_sequences）但不能被编辑。

所有时间以毫秒为单位在时间线上（或对于 in 是源片段的时长）。ID：轨道看起来像 v1 / a1，片段像 c1，标记像 m1；添加时可以设置自己的 ID。从 get_video_project 读取它们；切勿自行编造。

有关错误、命名空间的工具名称和撤销约定，请参阅 pixerate-agent-tools。

工作流程技能

对于这些任务，请同时加载相应的工作流程技能：它包含方法、步骤之间的检查点和陷阱，并使用以下工具。

pixerate-talking-head-edit：通过转写进行对话清理：填充词、停顿、口吃。
pixerate-bgm-alignment：按节拍剪切、音乐在语音下避让、响度。
pixerate-video-social-cut：垂直重新构图、先放钩子、平台长度、安全区域内的标题。
pixerate-video-colour-grade：校正和匹配镜头、在一个调整片段上应用统一风格、LUT 和肤色。
pixerate-video-montage：按节拍选集、节奏、过渡、音乐和结尾。

工作方法

读取。 get_video_project 获取设置、资产、轨道、片段（包含结束时间和源范围）、每个嵌套序列的摘要、标记和问题。当有复合片段时，list_video_sequences 显示其内容。如果项目是新建的，首先使用 set_video_settings 设置帧尺寸和 fps；稍后更改它们会移动基于帧的限制。
导入媒体。 为每个文件使用 add_video_asset，指定 kind、src 和源文件 duration（没有它无法检查修剪，并且 check_video_project 会警告 unknown-duration）。为视频提供 poster，以便渲染的帧显示画面。
标记结构。 在节拍、段落或审阅笔记处使用 add_video_marker；片段边缘在 UI 中会吸附到标记，标记也使 seek_video 有目标。
一次性组装。 使用 edit_video 进行粗剪：按顺序执行 add_asset、add_track，然后 add_clip 操作，并使用明确的片段 ID，以便后续操作（修剪、过渡）可以引用它们。首先使用 dry_run: true 运行它；错误会指出失败的操作。
细化使用单一工具：trim_video_clip、split_video_clip、move_video_clip、update_video_clip、set_video_transition、delete_video_clips / close_video_gaps；对于镜头之间的时机会使用编辑器会使用的修剪模式：roll_video_edit（移动剪切点）、slip_video_clip（更改镜头显示的内容）、slide_video_clip（在两个相邻镜头之间移动镜头）；对于整个时间段，使用 split_video_at、lift_video_range 或 extract_video_range。使用 set_video_keyframes 为不透明度、音量或位置设置动画。
按文本剪切 当媒体包含语音时：为每个有语音的资产设置 set_video_transcript（或检查 get_video_project 中的 transcriptWords），使用 get_video_transcript 读取编辑成果，然后使用 find_video_fillers、find_video_pauses 或 find_video_transcript_text 找出要移除的范围，并在一次调用中将它们传递给 remove_video_ranges。之后重新读取转写：每次剪切后它都会移动。
检查。 使用 check_video_project 并修复每个错误和警告；使用 find_video_gaps 查找意外的黑场或静音。
查看和聆听。 在剪切点和过渡处使用 get_video_frame 查看图层和音频增益数值；使用带有 times 的 render_video_frame 生成序列的联系表。在批量操作后渲染，而不是每次编辑后。
导出当被要求时：使用 export_video_ffmpeg（一个要运行的命令，不是渲染）或 export_video_edl（单条轨道）以便在其他地方完成。读取返回的注释。如果需要交付响度，让主机先运行 export_video_loudness_measure 并将其输出的内容作为 loudness.measured 传递；单次传递（没有 measured 的 loudness）对于草稿来说是可以的。
当用户应该看到时先计划。 对于任何重大或需要判断的事情（粗剪、清理、按音乐剪辑），建议使用 plan_video_edits（或来自对话和音乐技能的 plan_* 工具）而不是直接应用：项目不会改变，编辑器会显示计划及其长度变化和剪切的片段，一旦用户同意，使用 apply_video_edit_plan 应用该计划（或使用 discard_video_edit_plan 丢弃）。list_video_edit_plans 显示等待中的计划以及项目是否已更改。
效果（仅当主机注册了效果提供商时；否则 search_effects 会显示 available: false）：使用 use 调用 search_effects，然后使用 describe_effect 查看其控件，然后使用 apply_effect（在片段上应用滤镜和叠加层）、set_video_effect_transition 或 add_video_effect_clip（生成器和标题）。使用 update_effect 和 set_video_effect_keyframes 进行调整；使用 get_video_frame（图层列表包含 effects）和 list_applied_effects 进行检查。沿路径的效果（沿边框的射线、轨迹、书写文字）：使用 accepts: ["path"] 调用 search_effects，将其添加为片段或片段效果，然后使用带有帧 points、路径数据 d、片段 mask 轮廓或 text 的 set_video_effect_path。
摄像机运动（具有摄像机运动的提供商，例如 Flair）：一个片段就是一个镜头。使用 role 调用 list_video_camera_moves，然后使用 set_clip_camera_move：transition 从片段的开始处从 from 移动到 framing（滑动、甩镜头、推拉变焦）；hold 在片段的剩余部分以 framing 播放（像静态图片上的 Ken Burns 漂移）。这些运动会烘焙到片段以项目 fps 为单位的 x、y、缩放和旋转关键帧中，在剪切处有两个关键帧，因此预览和导出无需提供商即可播放它们。使用 get_video_frame 检查。
序列模板（具有模板的提供商）：对于现成的开场、揭示或倒计时，使用 list_templates，然后使用 describe_template 查看其插槽，然后使用 values（从其 exampleValues 开始）和 at 调用 fill_template。它会作为一步撤销操作落到新轨道上，位于其他轨道之上：每个镜头的基础层位于承载镜头过渡的基础轨道上，其他层根据角色作为效果、画面和文本片段。未填充的插槽会作为灰色占位符片段（placeholders）返回；使用 add_video_asset 和处于 overwrite 模式的 add_video_clip 将真实画面放在其上。摄像机运动不会被继承：使用 set_clip_camera_move 添加它们。

最佳实践

在动作上剪切。 在动作期间（转身、开门）放置剪切点，这样运动的连续性会掩盖它；在动作处使用 split_video_clip，然后修剪前后两端。
避免跳切。 两个连续镜头如果从几乎相同的构图拍摄同一主体，会显得像故障。改变角度或尺寸，用更高视频轨道上的 B-roll 覆盖剪切点，或者使其成为有意为之的效果。
J 和 L 剪切。 让声音领先或滞后于画面：将媒体的声音放在音频轨道上（相同视频资产的片段），将视频片段静音（muted: true），然后使用 roll_video_edit 将音频剪切点向前移动（J 剪切）或向后移动（L 剪切）。这可以平滑对话和场景变化。
保守使用过渡。 直接剪切是默认设置。使用 crossfade 表示时间流逝或柔和的场景变化，使用 dip（到黑色或某种 color）表示章节分隔，wipe 很少使用。保持简短（300-1000 毫秒）。push 和 slide 更适合图形、蒙太奇和社交编辑，而不是剧情片；iris 是一种风格化的时期或漫画效果。除 dip 外的所有类型都需要手柄：每个片段在剪切点之外有多余媒体的一半时长；dip 不需要。
插入与覆盖。 add_video_clip 和 move_video_clip 接受 mode：refuse（默认；错误会指出下一个空闲位置）、overwrite（替换下面的内容，如同覆盖编辑）或 insert（将后面的素材向后推）。在修剪和删除时使用 ripple: true，并使用 extract_video_range 而不是 lift_video_range，以保持编辑点之后的所有内容同步且无间隙。波纹和插入会移动每个已解锁且同步锁定的轨道，因此对话及其画面保持在一起；对于应该保持不动的音乐背景，请使用 update_video_track 关闭 syncLocked。
使用正确的工具修剪。 要更改剪切发生的时间而不移动其他任何内容，使用 roll_video_edit；要更改镜头显示的时刻，使用 slip_video_clip；要在两个其他镜头之间将镜头 前后移动，使用 slide_video_clip。这三种工具都保持时间线无间隙，并报告它们实际应用的增量（限制在可用媒体范围内）。
谨慎使用关键帧。 使用 set_video_keyframes 进行推近（scale 从 1 到 1.1 覆盖镜头）、对话下的避让（volume）或不在边缘的淡入淡出；使用缓动（ease-in-out）而非线性用于运动。片段边缘的简单淡入淡出使用 fadeIn / fadeOut。
首先通过文本收紧对话。 获取转写后，使用查找工具和一次 remove_video_ranges 移除填充词和停顿；首先检查填充词列表（某些“你知道”可能是有意的）。在单词周围保留 150-300 毫秒（keep）以便呼吸。没有转写时，使用下面提到的声音本身。
通过听觉和数字收紧对话。 在采访或画外音片段上使用 find_video_silences 列出时间线上的停顿；提取较长的停顿（在两侧保留 150-300 毫秒以免语音听起来被截断：在每个 extract_video_range 之前缩小每个范围，并从最后一个停顿倒回提取到第一个，或者重新读取，因为每次提取都会移动后续内容）。使用 get_video_audio_levels 在修剪或分割之前找到台词开始的位置。
速度变速以突出重点。 在重要时刻（跳跃、揭示）之前变速进入慢动作，并在之后退出：使用带有 300-600 毫秒滑行（toSpeed）的 set_video_speed_ramp 而不是硬切换，慢动作大约在 0.25-0.5。定格帧（1-2 秒）适合标题或“这就是我”的时刻；使用 add_video_freeze_frame 添加它。变速声音是阶梯式的，在定帧中为静音，因此将音乐或效果放在变速镜头的下方而不是它们自身的声音上。
关闭间隙。 意外的间隙会播放为背景颜色和静音。使用 find_video_gaps，然后使用 close_video_gaps 或波纹删除。只在需要黑场的地方保留间隙。
在帧上剪切。 将开始、修剪和分割放在帧边界上（1000 / fps 毫秒的整数倍；24 fps 时为 41.667 毫秒，30 fps 时为 33.333 毫秒）。编辑不会自动为你取整。
音频级别。 对话是基准；让音乐低于对话（语音下音量大约 0.2-0.4，台词之间可以更高），避免超过 1 的增益以防止削波。每个片段的 volume 和轨道的 volume 是相乘的关系。为每个在中间开始或结束声音的音频片段设置简短的 fadeIn / fadeOut（10-50 毫秒）以避免咔嚓声；为音乐背景设置 1-3 秒的淡入淡出。使用 fadeInCurve / fadeOutCurve 塑造声音淡入淡出：equal-power 用于两个声音重叠处（它保持响度稳定，而线性曲线会在中间下降；过渡的 audioCurve 已经默认为交叉淡入淡出和擦除使用它），exponential 用于将音乐自然地淡出到静音，s-curve 用于温和的起始和结束。线性是默认值。
交付响度。 标准化最终混音而不是推动片段音量：网络和流媒体为 -14 LUFS，播客为 -16，广播为 -23（EBU R128）或 -24（ATSC），真实峰值不超过 -1 dBTP。两次传递可以保持动态；一次传递则压制电平。
分两遍调色：先校正，后调色。 首先平衡每个镜头以使场景匹配（update_video_clip 的 grade：根据最佳镜头调整曝光和白平衡，然后使用 copy_video_grade 将其复制到场景的其余部分），然后使用 apply_video_grade_preset 以适中的 amount（0.3-0.6）添加调色风格，或者使用用户拥有的 .cube 查找表通过 set_video_lut（通常在 strength 0.5-0.8：胶卷模拟和创意 LUT 在满强度时效果很强）。LUT 在分级设置之后运行，因此首先校正曝光和白平衡；为 log 素材构建的 LUT 期望平坦的画面，在普通视频上看起来会显得压缩。使用 render_video_frame 并排放置几个时间点进行检查。肤色是参考：避免在人物上使用强烈的 hue 或 tint。
跨镜头的调整片段用于应用调色风格。 与其对场景的每个片段单独调色，不如在它们上方的轨道上使用 add_video_adjustment_clip 添加带有风格（grade、带有 amount 的 preset，或使用 apply_effect 在调整片段上应用效果）的调整片段：它会在播放时更改其下方的所有内容，因此修剪和新镜头会自动拾取风格。all 范围包括其上方的标题和轨道；track 范围将其限制在一条轨道上。使用 fadeIn / fadeOut 淡入和淡出以缓和地应用风格，并为其提供蒙版以限制在帧的一部分。
用于局部更改的蒙版。 set_video_clip_mask 将片段裁剪为形状（ellipse 用于人脸或暗角，rectangle 带有 corner_radius 用于画中画，linear 用于分屏或渐变的天空，polygon 用于跟随动作的自定义形状，text 用于给文本形状的片段添加内部字幕或水印）。反转蒙版（inverted: true）以分割帧的外部部分或从除了某个区域外的所有区域遮蔽效果。
代理工作流程（可选，仅当主机配置了代理时）。 对于长片或高分辨率素材，如果主机已设置代理文件夹（proxy_path 和 proxy_extension），import_video_asset 可以通过参数管理代理：设置 create_proxies: true 为每个添加的资产创建代理，并且 switch_to_proxies: true 在导入后立即切换到使用它们。如果源文件移动或父文件夹对它们重命名，reconnect_assets 会重新连接媒体。源剪辑标记（mark_in / mark_out）始终有效并参考源文件。
序列嵌套和复合片段。 对于复杂的项目，使用 add_video_sequence 创建一个嵌套序列，然后使用 add_video_clip 并设置 type: "sequence" 和序列的 ID 将其作为复合片段添加到时间线。复合片段播放其序列的合成视频（处理叠层效果）和混合音频。使用 list_video_sequences 查看序列，使用 list_video_sequence_clips 查看它们的内容。使用 update_video_clip 更改复合片段的长度、位置或时间缩放。
保存和恢复项目状态。 使用 save_video_project_state 手动创建时间点，特别是对于大的、批判性的步骤更是如此。这可以帮助回退到较早的状态而不丢失稍后的更改，并且有助于在没有 undo 时进行策略规划。
最小化 API 调用。 通过使用带有 ops 数组的 edit_video 对轨道设置、资产添加和片段放置进行分组来减少往返次数。对于多个片段更新，使用带有数组参数的 update_video_clip。一次调用 remove_video_ranges 可以同时处理多个选择。使用 build_edit_video_ops 对布局和操作序列进行建模，然后用一次 API 调用执行它们。
检查可空值。 在读取代码以定位或修改属性之前，始终检查资产的 duration 和片段的 in 属性是否为 null。许多 null 值意味着未指定的参数，例如将跟踪新的、未修剪的媒体。

Pixerate 视频编辑器