vmake-dynamic-caption

动态字幕

功能与准备

使用 subtitle 添加动态字幕或更改其样式，同时保留原视频并生成新视频。需要 vmake-labs-cli，目标版本为 0.1.11，兼容范围为 >=0.1.11 <0.2.0。

首次调用前，请阅读 CLI setup，确定可执行文件的位置，并通过 subtitle --help 检查其版本和文件参数。对于不明确的 JSON 字段或媒体限制，请查询 vmake contracts 中的 subtitle 条目。有关输出、交互和错误，请阅读 runtime and recovery。

• 字幕内容必须来自可识别的语音或可用的字幕时间轴。如果两者都没有，请获取合适的输入。
• 仅当样式 ID 已实际配置且有效时，才使用 --subtitle-material-id。否则，请说明将使用随机样式，并省略此选项。样式 ID 和会话媒体 ID 要分开处理。
• 如需编辑文本、翻译、突出显示词语或调整位置，请检查当前命令的支持情况和可用样式。仅当符合用户目标时，才使用视频字幕移除功能去除现有的烧录字幕。
• 对于明确的字幕请求，直接执行。只有在“改善表达”之类的模糊目标导致操作意图不清楚时才提问。仅在请求需要时，才添加蒙太奇或移除现有字幕。

收集输入

1. 使用用户提供的实际视频文件或 URL。不要重复询问用户已回答的问题；如果有多个候选项且无法确定，请让用户选择。
2. 使用可读取的本地视频。按照 CLI setup 下载所有远程原始文件，然后提交本地文件。如果下载失败，请向用户索取原始本地文件，并在收到后继续已确定的字幕请求。
3. 继续任务时添加 -r '<session_id>'；新任务则省略。仅按当前帮助的支持情况传递可选参数 --lang、--detach 和 --subtitle-material-id。默认值和登录要求遵循 CLI setup。
4. 继续处理蒙太奇时，保留其会话，并获取完整且当前有效的 Artifact 或 Message Part 视频 URL。先下载该视频，再让 CLI 将其上传到 CDN。如果 URL 缺失、已过期或仅以媒体 ID 表示，请查询 Task/历史记录。保留来源与文件的对应关系。不要先使用 create-room、add-media 或 --item-id。

上传并提交

使用已确定的可执行文件和准备好的本地视频：

vmake subtitle --video-file '<local-video-path>'

CLI 会验证视频，将其上传以获取 CDN URL，然后提交字幕任务并监控进度。参数文件和单独验证均为可选。保留原视频和会话，以便恢复；参数处理和临时文件清理遵循 CLI setup。

跟进并交付

• 保留实际的 session_id、room_url、所有 Task ID、artifact viva.short_id 以及完整 URL。分别读取 stdout 和 stderr，且不要启动第二个监控程序。
• 仅当任务达到 TASK_STATE_COMPLETED，且此任务返回了可用的视频 URL 后才交付。HTTP 200、流关闭、退出代码 0、Session 空闲以及 end.reason=result 本身都不能证明任务已完成；未知状态不算成功。
• 优先提供可播放的视频或带完整查询参数的可点击链接。如果返回了实际会话 URL，也请一并提供。封面图或输入视频都不是已添加字幕的结果。
• 遇到断连、超时或是否已受理不确定时，请查询原任务。只有在确认失败已修复并获得授权后才重试。如果字幕失败但蒙太奇已成功，请交付蒙太奇并说明字幕未能添加。下载失败时，应恢复下载，不要重复已成功的生成任务。详情请参阅 runtime and recovery。