Byted Mediakit Voiceover Editing

一、模式与凭据#

1.1 三种执行模式#

模式说明所需环境变量ASR 方式apigSkillHub 网关代理，Bearer Token 认证ARK_SKILL_API_BASE + ARK_SKILL_API_KEY（容器注入）+ VOLC_SPACE_NAME + ASR_API_KEY + ASR_BASE_URL豆包语音大模型cloud直连火山引擎 OpenAPI，HMAC 签算VOLC_ACCESS_KEY_ID + VOLC_ACCESS_KEY_SECRET + VOLC_SPACE_NAME + ASR_API_KEY + ASR_BASE_URL豆包语音大模型local完全本地执行，无需云端服务无（可选 EXECUTION_MODE=local）Qwen3-ASR 本地推理

优先级： apig > cloud > local。自动检测按此顺序依次检查环境变量，缺参时打印 .env 路径与缺失变量列表并自动降级。

1.2 凭据配置#

• .env 文件位置： <SKILL_DIR>/.env
• 脚本先读 进程环境变量，再用 .env 补全未设置的项（不覆盖容器注入）
• ARK_SKILL_* 通常由部署容器注入， 不必 手写到 .env
• 缺参不阻塞：不使用终端 input() 交互，缺参时打印提示信息并自动降级到可用模式
• Agent 推荐用户通过 编辑 .env 文件 或 Agent 文件写入工具 来配置变量，避免终端粘贴问题
• 安全：控制台创建 仅含所需权限 的密钥；测试请用 独立点播空间； .env 勿提交仓库

1.3 模式意图识别（Agent 必读）#

当用户在对话中表达模式切换意图时，Agent 应识别并执行：

用户表达识别为操作"用本地模式" / "不走云端" / "离线处理"EXECUTION_MODE=local写入 .env 或传 --mode local"用云端" / "用火山引擎" / "走 AK/SK"EXECUTION_MODE=cloud写入 .env 或传 --mode cloud"走网关" / "用 apig" / "用 SkillHub"EXECUTION_MODE=apig写入 .env 或传 --mode apig

隔离要求：各任务的模式选择相互独立。一个任务中切换到 local 不应影响另一个任务的模式。Agent 应在每次任务开始时重新检测或遵循用户当次指定。

---

二、执行约束（STRICT — NO EXCEPTIONS）#

1. 仅使用以下脚本，禁止创建新脚本
2. 按顺序执行所有步骤，跳步即任务失败
3. 执行任何脚本前必须先 cd <SKILL_DIR>/scripts
4. 每个 CHECKPOINT 必须验证产物后再继续
5. 任何步骤失败必须 立即停止并报告，不得继续
6. Step 4/5/6 输出 禁止 简化版、占位符、示例或省略内容
7. 最终输出必须保持原样，不能做任何修改
8. 审核页是否自动打开由 TALKING_VIDEO_AUTO_EDIT_REVIEW_AUTO_OPEN 决定（ 强制）：Agent 不得额外执行 open/ start/ xdg-open 等命令
9. 超时设置：音视频处理时长较长，宿主超时时间应设置为 60 分钟

职责分工#

组件职责不做**脚本（规则引擎）ASR 优化、候选生成（标记位置+规则置信度+删除建议）不做最终删除/保留决策宿主 Agent（你）**语义断句、口癖识别确认、候选复核、最终删除/保留决策不修改脚本

核心原则：脚本提供候选（含 deleted_parts + cleaned_text），Agent 做最终决策。

---

三、路径规则#

3.1 SKILL_DIR 与 Output-dir#

• SKILL_DIR： byted-mediakit-voiceover-editing 目录路径

• PROJECT_ROOT：由 scripts/project_paths.py 推导：

  1. 环境变量 VOICEOVER_EDITING_PROJECT_ROOT 若设置则用之
  2. 否则为 <SKILL_DIR> 的 parents[2]（沿父链上移 3 级，不依赖中间目录命名）

• Output-dir： <PROJECT_ROOT>/output/<素材名>/

• 脚本启动时会打印路径推导日志，便于调试确认

3.2 素材名推导#

来源推导规则示例URL取最后一段去扩展名https://x.com/video.mp4 → video本地文件取文件名去扩展名/path/Test_Video_720p.mp4 → Test_Video_720pDirectUrl取 FileName 去扩展名test.mp4 → testVid取 Vid 值v0xxx → v0xxx

3.3 从上下文推导 output-dir#

• 推导优先级（按顺序尝试）：

  1. 对话历史/命令参数中已显式传入 --output-dir output/<子目录> → 直接沿用
  2. 无法从对话历史获得 → 询问用户指定

• Agent 不得 扫描仓库来推断 output-dir

3.4 重复处理#

写入任何输出文件/目录前，若目标已存在， 必须提示用户：

• 目录已存在：「是否删除原目录？[删除/保留并新建(01)]」
• 文件已存在：「是否删除/覆盖/保留？」
• 超时 20 秒默认「保留并新建(01)」

---

四、脚本清单#

执行前必须 cd <SKILL_DIR>/scripts

脚本用途./scripts/setup.sh环境检查与依赖安装./scripts/pipeline_url_to_asr.pyStep 3: URL → ASR 流水线（支持 --mode local/cloud/apig）./scripts/merge_asr_words.pyStep 4 产出缺 words 时，从 raw 合并./scripts/prepare_export_data.pyStep 6a: 数据预处理（ --width --height --write-step6）./scripts/serve_review_page.pyStep 6b: 审核页静态服务 + 数据保存 + 导出代理./scripts/export_server.py导出服务（独立进程，接收审核页 POST）./scripts/vod_direct_export.pyStep 6c: VOD 导出任务提交与查询

---

五、必经步骤#

各 Step 完整检查单见 references/执行步骤/ 下分步文档。

Step说明文档Step 1环境检查与依赖安装1. 环境检查.mdStep 2语气词/卡顿词确认与规则更新2. 语气词提示与用户行为更新.mdStep 3URL → ASR 流水线与候选生成3. URL到ASR流水线与候选生成.mdStep 4ASR 语义纠错（Agent 执行）4. ASR语义纠错.mdStep 5口播剪辑（Agent 执行）5. 口播剪辑.mdStep 5.5审核逻辑确认5.5 审核逻辑确认.mdStep 6a数据预处理6a. 数据预处理.mdStep 6b审核与导出6b. 审核与导出.mdStep 6cVOD 导出任务提交与查询6c. VOD导出任务提交与查询.md

---

六、产物对照表#

产物文件生成步骤说明step1_preuploaded.jsonStep 3素材上传/注册结果（含 _execution_mode）step3_voice_separation_result.jsonStep 3人声分离结果step5_asr_raw_*.jsonStep 3ASR 原始转写step5_asr_optimized.jsonStep 4语义纠错后 ASRstep6_speech_cut.jsonStep 5口播剪辑决策review_import_data.jsonStep 6a审核页数据（含 _execution_mode、 track、 sentences）export_request.jsonStep 6a / 审核保存导出请求（审核页"保存"后会同步更新此文件）export_submit_*.jsonStep 6b/6c最终提交的导出数据

---

七、审核页与数据联动#

7.1 模式感知#

审核页通过 review_import_data.json 中的 _execution_mode 字段自动识别当前模式，并在界面上：

• 显示 模式徽标（APIG 蓝/云端绿/本地橙）
• 调整 导出按钮文案（本地模式显示"本地导出视频"）
• 调整 导出成功信息（本地模式显示输出文件路径，云端显示 OutputVid + PlayURL）

7.2 本地模式审核页#

本地模式 完全支持审核页。Source 字段使用 http://127.0.0.1:<port>/local-media/<绝对路径> 格式，由 serve_review_page.py 的 /local-media/ 路由代理访问本地文件。

7.3 数据联动（审核修改 ↔ 直接导出同步）#

审核页提供两个操作按钮：

按钮功能数据流💾 保存审核将修改持久化到磁盘POST /api/save-review → 更新 review_import_data.json + 重新生成 export_request.json导出直接触发视频导出POST /export → apply_review_to_export → export_submit_*.json → ffmpeg/VOD

关键：用户在审核页做了修改后，点击"💾 保存审核"即可将修改同步到磁盘。此后即使关闭审核页，Agent 通过 vod_direct_export.py --output-dir <输出目录> submit --wait 直接导出时也会读取更新后的 export_request.json，确保数据一致。

⚠️ 关键约束：调用 vod_direct_export.py 时， --output-dir 必须写在 submit/ query 子命令 之前。一行式调用格式：

text

cd SKILL_DIR/scripts && source .venv/bin/activate && python vod_direct_export.py --output-dir <绝对路径> submit --wait

7.4 审核页服务端点#

端点方法说明/GET审核页 HTML/api/review-dataGET返回 review_import_data.json``/api/modeGET返回当前执行模式/api/save-reviewPOST保存审核修改（回写 review_import_data + 重生成 export_request）/exportPOST触发导出（local: ffmpeg；cloud/apig: vod_direct_export）/local-media/<path>GET本地模式媒体文件代理

---

八、常见问题#

现象处理本地文件走了 DirectUrl 模式本地文件必须作为 第一个位置参数 传入； --directurl 仅用于 VOD 空间内已有 FileNamestep5 写入失败必须写入 output/<文件名>/step5_asr_optimized.json，禁止写 output 根目录concat 规则要删但音频还在播actionTime 必须从 step5 words 查出 仅保留 部分的 ms重复文件未提示写入前必须检查目标是否存在，按 3.4 规则处理step6 修正未生效确保 step6 顶层为 optimized_segments 或 sentences；运行 --write-step6 写回segment 起止时间不准Step 6a 会依 step5 words 校正delete 未在 deleted_parts每个 action: delete 段 必须 在 deleted_parts 中有对应项审核页修改关闭后丢失关闭前点击"💾 保存审核"持久化到磁盘审核页本地资源 404确认 Source 字段为 /local-media/ URL 格式；检查 serve_review_page.py 是否正常运行缺参提示后阻塞不再使用 input()，缺参时自动降级并打印 .env 路径提示

---

九、字幕可见性（Alpha）#

• 字段： textElement.Extra[transform].Alpha（0～1）
• 含义： 0 隐藏（不渲染到画布）， 1 展示
• 删除态：Alpha 设为 0； 恢复：Alpha 设为 1