byted-mediakit-voiceover-editing

一、モードと認証情報

1.1 3 種類の実行モード

モード	説明	必要な環境変数	ASR 方式
apig	SkillHub ゲートウェイプロキシ、Bearer Token 認証	ARK_SKILL_API_BASE + ARK_SKILL_API_KEY（コンテナから注入）+ VOLC_SPACE_NAME + ASR_API_KEY + ASR_BASE_URL	豆包音声大規模モデル
cloud	Volcano Engine 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 を渡す
「クラウドを使って」／「Volcano Engine を使って」／「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	说明	文档
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:<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