导出
使用OpenChatCut的导出工具进行交付。导出请求应调用 submit_export(或异步使用 submit_render_job),然后在结果未立即返回时使用 track_export 来获取状态并完成最终交付。
默认策略:
- 当用户要求导出/分享/最终确定OpenChatCut时间线时,优先使用
submit_export。 - 在编辑期间默认将原始文件保留在本地。仅在云端导出/预览需要远程资源且用户未禁止上传时,才上传原始文件。
- 不要将沙箱
ffmpeg的工作包装为OpenChatCut工具。仅当用户明确要求在OpenChatCut编辑工作流之外进行独立的本地文件操作时,才使用沙箱ffmpeg进行完整的视频处理。对于OpenChatCut编辑任务,不要生成预编辑或扁平化的本地渲染作为主要的审阅/最终交付物;应使用OpenChatCut导出。
持久化导出
使用 submit_export 执行路径:
{
"format": "video",
"codec": "h264",
"resolution": "1080p",
"fps": 30,
"name": "final-cut"
}
视频编解码器选项为 h264(MP4,默认)和 vp8(WebM)。视频帧率选项与编辑器 UI 匹配:24、25、30、50 或 60;省略 fps 以匹配时间线。音频导出为 MP3:传入 "format":"audio" 并省略 codec / fps,除非你显式传入 "codec":"mp3"。
submit_export 返回一个持久的 renderId。某些导出类型(如字幕文件)可能会立即完成并返回 downloadUrl;视频/音频通常需要 track_export 来等待完成。
获取每个 downloadUrl 后:
- 解析用户的下载文件夹:macOS/Linux 上为
~/Downloads,Windows 上为%USERPROFILE%\Downloads。 - 在触发任何代理/浏览器下载之前,检查下载文件夹中是否有最近几分钟内来自 Chrome 的、与预期的导出名称、扩展名或渲染/下载 URL 基本名称匹配的新鲜下载工件。包括已完成的文件和进行中的
.crdownload文件。 - 如果存在匹配的新鲜
.crdownload文件,不要触发另一个下载。等待 Chrome 移除.crdownload后缀并且最终文件大小不再变化,然后使用该已完成文件。 - 如果已经存在匹配的新鲜已完成文件,直接使用它,而不是再次下载。
- 如果只有较旧的文件存在,将其视为冲突,而非当前导出的结果。
- 不要覆盖现有文件;在需要时选择一个安全的编号文件名,例如
name (1).mp4。 - 始终将完成的导出文件下载到下载文件夹,而不是临时/工作区目录。
- 始终在聊天中内联显示下载的视频。如果有多个导出视频,下载所有视频并展示每个预览,而不仅仅是第一个。
如果项目包含仅本地资源,在渲染之前上传/注册云端可读的替换版本,或当用户希望保持本地时使用本地 CLI 导出路径。
报告返回的 renderId(如果存在)。该作业在编辑器右上角的导出队列中也可见,包括进度和取消。当用户要求将结果保留在“我的素材”中,或当活动工作流显式默认为自动实例化(例如 livestream-to-clips)时,使用 saveToMediaPool:true;否则默认保持为普通的可下载导出。对于长视频,调用 track_export 一次,传入 action:"wait" 和 timeoutSeconds:20。如果返回 waitExpired:true,报告渲染在后台继续并结束此轮对话。稍后使用 action:"status" 检查;重复等待只会保持 Agent 对话轮次打开。在此渲染处于活动状态期间,不要为同一时间线开始另一个导出。
当用户询问导出/渲染状态,或当前对话轮次确实需要等待已提交的视频/音频渲染时,使用 track_export。已完成的连接器导出会返回 downloadUrl;对于每个完成的条目,使用上述冲突安全规则将文件下载到下载文件夹,并在聊天中内联显示:
{
"action": "status",
"renderIds": "abc123"
}
对于最新的项目导出,省略 renderIds 并传入 "latest": true。track_progress 用于生成/转录/上传作业,而非渲染作业。
对于 NLE XML,使用 submit_export 并设置 format:"xml":
{
"format": "xml",
"nleFormat": "fcp_xml_resolve",
"timelineId": "abc123"
}
nleFormat 的值为 Premiere XML 的 fcp_xml(默认)和 DaVinci Resolve XML 的 fcp_xml_resolve。对于非活动时间线,省略 timelineId,或传入一个时间线 ID/前缀。读取并报告警告:字幕、纯色、SVG、不支持的剪辑属性和未渲染的运动图形可能会被 XML 格式丢弃。仅当透明 ProRes MG 导出流程提供了 motionGraphicRenderKeys 时,运动图形才会在 XML 中呈现;否则导出器会报告它们已被丢弃。
对于媒体池源文件下载,对基于文件的后台资源使用 request_asset_download。它返回一个受保护的后台下载 URL/路径,指向原始源媒体。不要使用 pull_asset 进行用户下载;pull_asset 仅限于沙箱使用。
对于字幕文件,使用 submit_export 并设置 format:"subtitles":
{
"format": "subtitles",
"subtitleFormat": "srt"
}
格式为 srt 和 txt。导出会使用字幕项目的实际时间线词定时、源范围、翻译变体、显示文本覆盖以及诸如 wordsPerPage / maxCharactersPerLine 之类的节奏字段,并创建一个持久的可下载导出作业。它适用于可下载的字幕文件。它尚未重用浏览器的 Remotion 字幕页面规划器,因此可视换行/分页虽然定时正确,但在字节级别上仅近似于烧录字幕的分页,而非完全一致。对于非活动时间线,从 manage_timelines 或 read_project 传入 timelineId。
对于一个透明 ProRes 4444 格式的运动图形,使用 export_motion_graphic_prores:
{
"itemId": "abc123",
"filenameMode": "asset"
}
导出特定时间线实例时优先使用 itemId,因为该项目携带了诸如编辑后文本之类的实时 propertyOverrides。对媒体池运动图形使用 assetId;当存在时,后端将使用该资源的第一个时间线实例,与编辑器的媒体池导出行为匹配。对于多个运动图形,在一次调用中传入 itemIds 或 assetIds。每个运动图形仍然会成为一个独立的持久化渲染;使用返回的 renderIds 调用 track_export 来等待,然后通过每个返回的渲染下载路径进行下载。
当准备应引用已渲染运动图形的 XML 时,将 "filenameMode":"xml" 和相同的 timelineId 传递给 export_motion_graphic_prores,然后保留返回的 motionGraphicRenderKey / motionGraphicRenderKeys;在渲染完成后,在 submit_export.motionGraphicRenderKeys 中传递这些键和相同的 timelineId,配合 format:"xml"。
本地渲染(此版本)
所有渲染均在本地完成:submit_export / submit_render_job 驱动本地渲染服务(headless Chrome,使用与编辑器显示相同的时间线状态),直接从磁盘上的 /media/uploads/ 读取媒体。对于基于磁盘的资源,没有 S3 需求,没有 CLI,也没有需要等待的云作业。
submit_export:字幕/XML 同步返回;视频/音频在此版本中也同步在调用内渲染(长时间的时间线可能需要一段时间——警告用户,而不是进行轮询)。submit_render_job+track_export:异步路径——立即返回一个renderId,使用track_export(renderIds/latest/onlyActive)轮询,然后将返回的下载路径交给用户。- 仍然位于
blob:占位符上的资源(上传中)尚不可渲染——在提交之前,等待track_progress的 target=upload 报告就绪。
回退方案
如果渲染因资源的字节缺失(占位符从未重新链接,文件已从磁盘删除)而失败:
- 要求用户在“我的素材”(离线素材横幅)中重新链接该资源,或重新导入文件。
- 对于 URL 源媒体,重新运行
download_media以恢复字节,然后重新提交。
除非进行调试,否则不要告诉用户他们需要理解 HTML-in-Canvas、Remotion 或存储内部原理。在产品层面解释:
- “本地快速导出”
- “素材还在上传,稍等再导”
- “需要先重新链接本地素材”
结果追踪
对于 submit_export,记录:
renderId- 时间线/范围/分辨率/编解码器/帧率
- 用户可以从编辑器渲染作业面板下载
记录上传的资源 ID 以及当云端导出被仅本地资源阻止时尝试的任何回退方案。