byted-mediakit-voiceover-editing

Files (60)

• LICENSE
• README.md
• SKILL.md
• edl.json · examples/
• step6_speech_cut.json · examples/
• track_witdh_request.json · examples/
• web-sdk.js · examples/
• ASR语义纠错.md · references/内置/
• EDL编辑决策格式.md · references/内置/
• 目标平台配置.md · references/内置/
• 1. 环境检查.md · references/执行步骤/
• 2. 语气词提示与用户行为更新.md · references/执行步骤/
• 3. URL到ASR流水线与候选生成.md · references/执行步骤/
• 4. ASR语义纠错.md · references/执行步骤/
• 5. 口播剪辑.md · references/执行步骤/
• 5.5 审核逻辑确认.md · references/执行步骤/
• 6a. 数据预处理.md · references/执行步骤/
• 6b. 审核与导出.md · references/执行步骤/
• 6c. VOD导出任务提交与查询.md · references/执行步骤/
• 1-核心原则.md · references/用户规则/
• 10-顺句词删除.md · references/用户规则/
• 2-语气词检测.md · references/用户规则/
• 3-静音段处理.md · references/用户规则/
• 4-重复句检测.md · references/用户规则/
• 5-卡顿词.md · references/用户规则/
• 6-句内重复检测.md · references/用户规则/
• 7-连续语气词.md · references/用户规则/
• 8-重说纠正.md · references/用户规则/
• 9-残句检测.md · references/用户规则/
• README.md · references/用户规则/
• 变更记录.md · references/用户规则/
• api_manage.py · scripts/
• apply_review_to_export.py · scripts/
• asr_volc.py · scripts/
• execution_mode.py · scripts/
• export_server.py · scripts/
• ffmpeg_utils.py · scripts/
• local_asr.py · scripts/
• local_av_separation.py · scripts/
• local_denoise.py · scripts/
• local_export.py · scripts/
• local_media_ops.py · scripts/
• local_subtitle.py · scripts/
• merge_asr_words.py · scripts/
• output_dir_resolve.py · scripts/
• pipeline_url_to_asr.py · scripts/
• prepare_export_data.py · scripts/
• project_paths.py · scripts/
• requirements-local.txt · scripts/
• requirements.txt · scripts/
• serve_review_page.py · scripts/
• setup.sh · scripts/
• step2_confirm_config.py · scripts/
• track_cut_realign.py · scripts/
• vod_direct_export.py · scripts/
• vod_local_upload.py · scripts/
• vod_transport.py · scripts/
• volc_request.py · scripts/
• env.md · templates/
• index.html · templates/review-page/

SKILL.md (first lines)

## 一、模式与凭据

### 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/<素材名>/`；若目录已存在则自动递增为 `<素材名>_01`、`<素材名>_02`...
- 脚本启动时会打印路径推导日志，便于调试确认

### 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/step2_confirm_config.py` | Step 2: 语气词/卡顿词确认完成后生成 checkpoint（阻止跳步）  |
| `./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     | 说明                        | 文档                                                                                   |
| -------- | --------------------------- | -------------------------------------------------------------------------------------- |

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples