alibabacloud-video-translation

動画翻訳スキル

Alibaba Cloud IMS を活用したワンクリック動画翻訳です。字幕レベルと音声レベルの翻訳に対応しています。

---

入力形式の要件

重要：API によってアドレス形式が異なります！

API アドレス形式のリファレンス

API	アドレス形式	例
SubmitIProductionJob（字幕抽出）	oss:// 形式	oss://my-bucket/videos/test.mp4
SubmitVideoTranslationJob（動画翻訳）	HTTP URL 形式	https://my-bucket.oss-cn-shanghai.aliyuncs.com/videos/test.mp4

重要：字幕抽出では oss:// を使用し、動画翻訳では HTTP URL を使用します！

ユーザー入力の処理

ユーザー入力の種類	処理方法
HTTP URL 形式	動画翻訳にはそのまま使用します。字幕抽出が必要な場合は oss:// に変換します
oss:// 形式	字幕抽出にはそのまま使用します。動画翻訳には HTTP URL に変換します
ローカル動画	OSS へのアップロード先を必ず確認し、アップロード後に両方の形式を保存します

形式変換ルール

oss:// format ⇄ HTTP URL format

oss://my-bucket/videos/test.mp4
    ⇄
https://my-bucket.oss-cn-shanghai.aliyuncs.com/videos/test.mp4

変換式：

• oss://<bucket>/<path> → https://<bucket>.oss-<region>.aliyuncs.com/<path>
• HTTP URL は署名不要です。Bucket ドメイン形式をそのまま使用します

ローカル動画の処理フロー

User provides local video path
    │
    ├─ AskUserQuestion: "Please provide OSS upload path (format: oss://<bucket>/<path>/<filename>.mp4)"
    │
    ├─ User specifies upload path
    │   ├─ Check if Bucket exists
    │   ├─ Upload file: aliyun oss cp <local_path> <oss_path>
    │   ├─ Save oss:// format → for subtitle extraction
    │   └─ Save HTTP URL format → for video translation
    │
    └─ User does not specify path → STOP, user MUST provide upload path

アップロードコマンド：

aliyun oss cp <local_path> oss://<bucket>/<path>/<filename>.mp4

アップロード後に両方の形式を保存します：

Local: /Users/demo/videos/test.mp4
Uploaded to: oss://my-bucket/videos/test.mp4
    ├─ oss:// format: oss://my-bucket/videos/test.mp4 (for subtitle extraction)
    └─ HTTP URL: https://my-bucket.oss-cn-shanghai.aliyuncs.com/videos/test.mp4 (for video translation)

---

実行ゲートのチェックリスト

厳守事項：エージェントはフェーズ順に実行する必要があります。現在のフェーズに合格するまでは、次に進めません！

フェーズ 0：環境と認証情報の確認（ハードゲート）

確認項目	コマンド	合格条件	失敗時の対応
CLI バージョン	aliyun version	>= 3.3.1	停止し、cli-installation-guide.md を参照
認証情報の状態	aliyun configure list	有効な状態	停止し、設定方法を案内
プラグインのインストール	aliyun configure set --auto-plugin-install true	設定済み	自動設定

ハードゲート：合格するまで、後続の操作には進めません！

---

フェーズ 1：翻訳モードの確認（ブロッキング）

AskUserQuestion: "Do you need subtitle translation (translate subtitles only) or speech translation (translate subtitles + replace voiceover)?"

┌─ Subtitle translation → NeedSpeechTranslate: false
└─ Speech translation → NeedSpeechTranslate: true

⚠️ No reply received → STOP, cannot proceed!

入力の種類から翻訳モードを推測しないでください！

---

フェーズ 2：字幕処理の確認（ブロッキング）

AskUserQuestion: "Do you need to erase original subtitles from the video? Do you need to burn-in translated subtitles?"

⚠️ No reply received → STOP, cannot proceed!

パラメーターの対応関係：

機能	パラメーター	値
元の字幕を消去	DetextArea	"Auto"／座標／未設定（消去なし）
新しい字幕を焼き込む	SubtitleConfig	設定オブジェクト／未設定（焼き込みなし）

---

フェーズ 3：出力先の確認（ノンブロッキング）

条件	処理方法
ユーザーが明示的に指定	ユーザー指定のパスを使用
ユーザーが指定しない	デフォルトのパスを使用し、ユーザーに通知

デフォルトの出力ルール：

• バケット：入力動画と同じバケット
• ディレクトリ：入力動画と同じディレクトリ
• ファイル名：{source}_translated_{random8}.mp4
• 例：oss://bucket/videos/demo.mp4 → oss://bucket/videos/demo_translated_a1b2c3d4.mp4

シェル変数は使用せず、Python を使用してください：python3 -c "import random; print(''.join(random.choices('abcdefghijkmnpqrstuvwxyz23456789', k=8)))"

---

フェーズ 4：字幕レビューの確認（条件付きブロッキング）

トリガー条件	処理方法
ユーザーが字幕レビューを選択	ブロッキング。レビュー結果の確認をユーザーに求め、必ず待機します
ユーザーがレビューを不要とする	ノンブロッキングで続行

重要：字幕抽出後は、内容を変更せずそのまま出力して、ユーザーに確認してもらう必要があります！

---

シナリオ選択

重要なポイント：

1. ユーザーがローカル動画を入力した場合、必ず最初に OSS にアップロードし、HTTP URL を取得します
2. ユーザーが字幕を提供しない場合、字幕の抽出と確認が必要かどうか、必ず質問します

User inputs video
    │
    ├─ Local video?
    │   └─ Yes → AskUserQuestion: "Please provide OSS upload path"
    │       ├─ User provides path → Upload to OSS → Convert to HTTP URL → Continue
    │       └─ User does not provide → STOP
    │
    ├─ oss:// format?
    │   └─ Yes → Inform user to convert to HTTP URL format
    │
    └─ HTTP URL format? → Continue
        │
        ├─ User provides SRT file?
        │   ├─ Yes → Input type = with_subtitle
        │   │   ├─ Translation mode = speech → 【Scenario 4】 ⚠️ MUST ask CustomSrtType
        │   │   └─ Translation mode = subtitle → 【Scenario 3】
        │   │
        │   └─ No → Input type = only_video ⚠️ MUST ask if review needed
        │       │
        │       ├─ AskUserQuestion: "Do you need to extract subtitles for review first, or translate directly?"
        │       │
        │       ├─ Need review → 【Scenario 2】 ⚠️ Phase 4 blocking
        │       │
        │       └─ Direct translation → 【Scenario 1】 (TextSource=OCR_ASR)

シナリオ	名前	ブロッキングポイント	TextSource	フロー
0	ローカル動画のアップロード	OSS アップロード先の確認	-	アップロード→HTTP URL→後続のシナリオ
1	直接翻訳	フェーズ 1、2	OCR_ASR	翻訳を直接送信
2	字幕の確認	フェーズ 1、2、字幕確認の問い合わせ、フェーズ 4	SubtitleFile	字幕を抽出→確認→翻訳
3	字幕翻訳＋ユーザー提供字幕	フェーズ 1、2	SubtitleFile	ユーザー提供の SRT を使って直接翻訳
4	音声翻訳＋ユーザー提供字幕	フェーズ 1、2＋CustomSrtType の確認	SubtitleFile	字幕の言語を確認してから翻訳

シナリオ 0（ローカル動画）の詳細なフロー：

1. AskUserQuestion：「OSS のアップロード先を指定してください（形式：oss:////.mp4）」
2. ユーザーがパスを指定したら、aliyun oss cp <local_path> <oss_path> を実行します
3. HTTP URL に変換します：https://<bucket>.oss-<region>.aliyuncs.com/<path>/<filename>.mp4
4. 後続のシナリオのフローに進みます

シナリオ 2 の詳細なフロー：

1. 字幕検出領域（roi パラメーター）を尋ねます
2. CaptionExtraction を呼び出して字幕を抽出します。入力と出力には oss:// 形式を使用します
3. 字幕の内容をそのまま出力し、ユーザーに確認してもらいます
4. ユーザーの確認後、確認済みの SRT を使って翻訳を送信します

---

パラメーター決定表

決定ルール：各パラメーターの処理方法を明確に定め、恣意的に推測しないでください！

パラメーター	トリガー条件	処理方法	デフォルト値	禁止事項
NeedSpeechTranslate	常に	必ず質問する	なし	入力から推測しないでください
NeedFaceTranslate	常に	固定値	false	true に設定しないでください
DetextArea	ユーザーが消去を選択	必ず質問する	なし	恣意的に Auto に設定しないでください
SubtitleConfig	ユーザーが焼き込みを選択	デフォルトを使用できます	標準スタイル	確認を省略しないでください
TextSource	シナリオによって決定	シナリオのルールに従う	シナリオの対応表を参照	恣意的に選択しないでください
CustomSrtType	シナリオ 4	必ず質問する	なし	恣意的に推測しないでください
OutputConfig.MediaURL	出力先	デフォルトを使用できます	デフォルトのルール	シェル変数を使用しないでください
JobParams.roi	字幕抽出	必ず質問する	[[0.5,1],[0,1]]	恣意的にデフォルト値を設定しないでください
SourceLanguage	ユーザーが指定、または推測可能	デフォルトを使用できます	自動検出	中国語の場合のみ zh を使用
TargetLanguage	ユーザーが指定	デフォルトを使用できます	en	それ以外の言語の場合は質問する

TextSource のシナリオ対応表：

シナリオ	値	説明
1	OCR_ASR	字幕を自動検出
2	SubtitleFile	確認済みの SRT
3、4	SubtitleFile	ユーザー提供の SRT

CustomSrtType のトリガールール：

条件	値
CaptionExtraction で抽出	SourceSrt
ユーザーが字幕を提供（シナリオ 4）	必ず質問する：SourceSrt / TargetSrt

---

失敗時の保護メカニズム

HARD-GATE：音声翻訳に失敗した後、字幕翻訳に自動で切り替えないでください！

API エラーの処理

ErrorCode	対応
Forbidden.SubscriptionRequired	ram-policies.md を参照
InvalidParameter	api-parameters.md を参照
InputConfig.Subtitle is invalid	troubleshooting.md を参照
JobFailed	JobId を記録し、再試行が必要かユーザーに尋ねます

SRT 形式の修復フロー

Detect empty subtitle entries → Delete empty entries → Renumber → Upload repaired file → Inform user

詳細は troubleshooting.md を参照してください。

---

CLI コマンドテンプレート

重要: API を送信する前に、api-parameters.md を参照して、パラメーター形式を必ず確認してください！

詳細については、cli-commands.md を参照してください。

主要なコマンド:

# Register media asset
aliyun ice register-media-info --input-url "oss://<bucket>/<object>" --media-type video --user-agent AlibabaCloud-Agent-Skills

# Submit subtitle extraction (use OSS path)
aliyun ice submit-iproduction-job \
  --function-name CaptionExtraction \
  --input "Media=oss://<bucket>/<object> Type=OSS" \
  --biz-output "Media=oss://<bucket>/<output>.srt Type=OSS" \
  --job-params '{"lang":"ch","roi":[[0.5,1],[0,1]]}' \
  --force \
  --user-agent AlibabaCloud-Agent-Skills

# Submit video translation
aliyun ice submit-video-translation-job \
  --user-agent AlibabaCloud-Agent-Skills

CLI 形式の重要なポイント:

• 字幕抽出では、コマンド名 submit-iproduction-job（小文字、区切り文字は -）を使用します
• --input と --biz-output の形式は、スペース区切りの文字列 "Media=... Type=OSS" です。JSON ではありません
• --job-params の形式は JSON 文字列です
• プラグインのパラメーター検証をスキップするには、--force を必ず追加してください
• すべての ICE コマンドに --user-agent AlibabaCloud-Agent-Skills を必ず追加してください

---

ドキュメントの参照先

ドキュメント	内容
workflow-details.md	4 つのシナリオの詳細な実行フロー
cli-commands.md	CLI コマンドテンプレートライブラリ
troubleshooting.md	エラー処理の詳細
api-parameters.md	API パラメーターの完全なドキュメント
ram-policies.md	RAM 権限の要件
cli-installation-guide.md	CLI のインストールガイド

---

主な制約

• API を送信する前に、api-parameters.md を参照して、パラメーター形式を必ず確認してください
• すべての ICE CLI コマンドに --user-agent AlibabaCloud-Agent-Skills を必ず追加してください
• 字幕抽出（SubmitIProductionJob）では oss:// 形式を使用します
• 動画翻訳（SubmitVideoTranslationJob）では HTTP URL 形式を使用します。署名は不要です
• ローカル動画は必ず先に OSS にアップロードしてください。ユーザーはアップロード先のパスを指定する必要があります
• NeedFaceTranslate は false にする必要があります
• SpeechTranslate と SubtitleTranslate は同時に指定できません
• InputConfig.Subtitle は HTTPS 形式を使用する必要があります。oss:// は使用しないでください
• 音声翻訳と SRT 入力を組み合わせる場合は、SpeechTranslate.CustomSrtType が必要です
• 入力タイプから翻訳モードを推測しないでください

---

タスクのポーリング

必須: タスクの状態を完了（State=Finished）または失敗（State=Failed）になるまで継続してポーリングしてください。途中で終了しないでください！

タスクの種類	照会コマンド	間隔	タイムアウト
字幕抽出	QueryIProductionJob	30 秒	5 分
動画翻訳	get-smart-handle-job	30 秒	30 分

ポーリングのロジック:

Loop polling until:
  - State == "Finished" → Return result
  - State == "Failed" → Report error
  - Exceeds 30 minutes → Report TimeoutError

Prohibited: Return after single query / Skip polling and return JobId directly

所要時間の目安（3 分の動画）:

• 字幕レベルの翻訳：3～5 分
• 音声レベルの翻訳：10～20 分

---

結果の取得

# Get media asset info
aliyun ice get-media-info --media-id "<MediaId>"

# Generate signed URL (for private Bucket)
aliyun oss sign oss://<bucket>/<object> --timeout 3600

---

ドキュメントの末尾