Byted Mediakit Voiceover Editing

一、模式与凭据

1.1 三种执行模式

模式	说明	所需环境变量	ASR 方式
------	------	-------------	----------
apig	SkillHub 网关代理，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 文件位置：/.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）

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

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

Output-dir：/output/<素材名>/
脚本启动时会打印路径推导日志，便于调试确认

3.2 素材名推导

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

3.3 从上下文推导 output-dir

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

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

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

3.4 重复处理

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

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

四、脚本清单

> 执行前必须 cd /scripts

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

五、必经步骤

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

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

六、产物对照表

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

七、审核页与数据联动

7.1 模式感知

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

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

7.2 本地模式审核页

本地模式完全支持审核页。Source 字段使用 http://127.0.0.1:/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 子命令之前。一行式调用格式：

> ```

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

> ```

7.4 审核页服务端点

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

八、常见问题

现象	处理
------	------
本地文件走了 DirectUrl 模式	本地文件必须作为第一个位置参数传入；`--directurl` 仅用于 VOD 空间内已有 FileName
step5 写入失败	必须写入 `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