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` 文件位置**：`<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_720p` | | DirectUrl | 取 FileName 去扩展名 | `test.mp4` → `test` | | Vid | 取 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.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](references/执行步骤/1.%20环境检查.md) | | Step 2 | 语气词/卡顿词确认与规则更新 | [2. 语气词提示与用户行为更新.md](references/执行步骤/2.%20语气词提示与用户行为更新.md) | | Step 3 | URL → ASR 流水线与候选生成 | [3. URL到ASR流水线与候选生成.md](references/执行步骤/3.%20URL到ASR流水线与候选生成.md) | | Step 4 | ASR 语义纠错（Agent 执行） | [4. ASR语义纠错.md](references/执行步骤/4.%20ASR语义纠错.md) | | Step 5 | 口播剪辑（Agent 执行） | [5. 口播剪辑.md](references/执行步骤/5.%20口播剪辑.md) | | Step 5.5 | 审核逻辑确认 | [5.5 审核逻辑确认.md](references/执行步骤/5.5%20审核逻辑确认.md) | | Step 6a | 数据预处理 | [6a. 数据预处理.md](references/执行步骤/6a.%20数据预处理.md) | | Step 6b | 审核与导出 | [6b. 审核与导出.md](references/执行步骤/6b.%20审核与导出.md) | | Step 6c | VOD 导出任务提交与查询 | [6c. VOD导出任务提交与查询.md](references/执行步骤/6c.%20VOD导出任务提交与查询.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:<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` 子命令**之前**。一行式调用格式： > ``` > 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/<path>` | 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