alibabacloud-video-editor

動画編集スキル

クラウド（Alibaba Cloud ICE）で動画を編集します。ローカルでの ffmpeg は不要です。3 つのモードがあります。

• タイムライン編集（SubmitMediaProducingJob）— 複数のクリップを組み立てます。Timeline JSON を作成し、スクリプトがプロデュースジョブを送信して完了までポーリングし、出力動画の URL を返します。
• 通常のテンプレート（AddTemplate、Type=Timeline）— パラメーター化された Timeline Config を保存し、その ClipsParam の仕様を確認して、置き換え用のテキスト／メディアを使って繰り返しレンダリングします → references/22-normal-templates.md。
• インテリジェント制作（SubmitIProductionJob）— 1 つのメディアファイルに対して 1 つのアルゴリズムを実行します（スマートカバー、ロゴ／字幕の消去、字幕抽出、マッティング、美顔、横から縦への変換、音声のノイズ除去／ミキシング／分離／分析）。Timeline は使用しません → §7.1 および references/13-intelligent-production.md。

このスキルは一連の工程の最終段階です。 何がどこで起きるか、誰が話すか、どの場面が重要かといったコンテンツの理解は、他の機能によって上流で生成され、このスキルにはデータとして渡されます（§2.4）。ここでは、そのデータと素材を使って、レンダリング済みの検証済み動画を作成します。

厳守事項

好みの問題では済まされない、逸脱不可の6つのルールです。このドキュメントに記載されたそれ以外のすべての内容――フォントサイズ、色、長さ、プリセット、長さの比率――は、実際に公開された案件に基づく実例であり、必須要件ではありません。何が可能かを知るための参考にしたうえで、素材とユーザーの依頼に応じて判断してください。

1. ユーザーのローカルストレージには何も保存しません。 メディアをダウンロードすることはありません。所定の場所で読み込みます（ffmpeg -i "<https URL>" はHTTP経由でストリーミングします。スナップショットジョブは署名付きフレームURLを返します）。中間生成物はOSSに保存します。アルゴリズムの出力、吹き替え音声、プロキシ、変換済み入力などはすべて、ICEジョブが書き込んだOSSオブジェクトであり、ユーザーのディスク上のファイルではありません。納品物はダウンロードファイルではなく、再生URL（§8）として引き渡します。ローカルファイルを作成するのは、ユーザーが明示的に依頼した場合に限ります。読み取りのためにローカルツールで書き込む必要がある少数のファイル（波形PNG、silencedetectのトランスクリプト、確認するフレーム、edl.json、project.md）は、ユーザーのプロジェクト外にある1つのスクラッチディレクトリ――${TMPDIR:-/tmp}/video-editor/<session>――に保存し、使い捨てとして扱います。ユーザーのワークスペースには決して作成しないでください。ユーザーから受け取ったローカルファイルは、操作する前にOSSへアップロードします（§4）。
2. すべての生成処理にはICEを使用し、ffmpegは音声の分析にのみ使います。 カット、結合、トリミング、オーバーレイ、トランジション、字幕の焼き込み、ミキシング、速度変更、合成音声／吹き替え、フォーマット変換は、ICEジョブでレンダリングします（TimelineにはSubmitMediaProducingJob、単一メディアのアルゴリズムにはSubmitIProductionJob、Normal Timelineにはテンプレートレンダリングを使用します）。ffmpegの用途は音声信号の読み取り――波形（showwavespic）、無音／発話部分の末尾（silencedetect）、ラウドネス（volumedetect）、長さ（ffprobe）――だけで、書き込むのは分析結果の数値に限ります（§1.4）。メディアの生成や変換には決して使いません。concat、メディアファイルに対する-filter_complex、-c copy、再エンコード、atempo、トランスコードは禁止です。フレームはffmpegではなく、SubmitSnapshotJobで取得します。唯一の例外はメディアではなくチャートです。timeline_view.pyは、クラウド上のスナップショットスプライトからタイルを切り出し、波形の上に並べます。これらを返すICE APIがないためです（§1.4）。Pythonのメディアライブラリも、別のクラウド製品も使いません。ユーザーの要件をICEジョブで実現できない場合は、その旨を伝えて停止してください。ローカルでレンダリングした納品物は誤った回答であり、代替手段ではありません。
3. レンダリングの前にリージョンを確認し、次に出力バケットを確認します（§2.1）。Template Configの生成とAddTemplateにバケットは不要ですが、レンダリングには必要です。デフォルトリージョンはありません。cn-shanghaiも例外ではありません。
4. 何かを送信する前に、平易な言葉でプランを確認します（§2.2）。生成ジョブには費用と時間がかかりますが、説明の段落にはどちらもかかりません。
5. 報告する前に、すべての納品物を検証します（§9）。Successが意味するのは、ファイルが書き込まれたということだけです。それ以上の意味はありません。未検証の出力を検証済みとして報告しないでください。
6. 複数クリップのTimelineは必ずコンパイルし、直接書き込まないでください。 ユーザーがtimeline.jsonのみを求め、クラウドへの呼び出しを禁止している場合でも、まずedl.jsonを書き込み、その後python "$SKILL_DIR/scripts/video_editor.py" compile --edl edl.json --output timeline.jsonを実行します。compileはオフラインで動作し、クラウドへの呼び出しはありません（§2.1、18-edl-and-compile.md）。生成されたファイルが納品物です。チェックリストのうち、処理を妨げる違反はすべて修正してください。compileとsubmitはいずれも同じチェックリストを適用します（§5）。 役割分担：references/＝必要に応じて読むナレッジベース、scripts/video_editor.py＝純粋な実行ツール（送信／ポーリング／URL取得、およびiproduction／iproduction-status）、scripts/frame_qa.py＝クラウド素材のモデルレビュー用（動画全体は--mode full、署名付きスナップショットフレームは--frames。ローカルでのサンプリングは行いません）（§9）。編集ロジックはすべて、生成するTimelineに記述します。

1. セットアップ

以下の $SKILL_DIR は、この SKILL.md を含むディレクトリを指します。スクリプトは必ず絶対パスで実行してください（python "$SKILL_DIR/scripts/video_editor.py" ...）。通常、作業ディレクトリはスキルのディレクトリではなく、ユーザーのプロジェクトです。

pip install -r "$SKILL_DIR/scripts/requirements.txt"

AK/SK（§1.1）と OSS 出力バケット（§1.2）は必須です。これらがない場合は作業を中止し、ユーザーを案内してください。DASHSCOPE_API_KEY（§1.3）と ffmpeg（§1.4）は任意です。これらがない場合は、代わりに自分の視覚能力でクラウドのスナップショットフレームを読み取って検証し（§9）、検証を省略しないでください。

1.1 Alibaba Cloud の認証情報（必須）

スクリプトは Alibaba Cloud のデフォルト認証情報チェーンを使用します。環境変数、次に aliyun CLI プロファイル（~/.aliyun/config.json に保存され、current で指定されたプロファイル。ALIBABA_CLOUD_PROFILE で上書き可能）、次に ~/.alibabacloud/credentials.ini、最後に ECS RAM ロールの順に確認します。CLI プロファイルプロバイダーは alibabacloud-credentials>=1.0.2 でのみ利用可能です。そのため、scripts/requirements.txt ではこのバージョン以上を指定しています。古いリリースでは、正しく設定された aliyun configure プロファイルが無視され、バージョンの問題ではなく認証情報の不足のように見えるエラーが発生します。

ユーザーの希望に応じて、以下のいずれかの設定方法を案内してください。

# Option A — aliyun CLI (writes a reusable profile; recommended). Install if `aliyun` is missing:
brew install aliyun-cli   # macOS; or fetch a binary and `tar xzf` it + `sudo mv aliyun /usr/local/bin/`
# Binaries: https://aliyuncli.alicdn.com/aliyun-cli-darwin-arm64-latest.tgz (macOS), https://aliyuncli.alicdn.com/aliyun-cli-linux-amd64-latest.tgz (swap amd64→arm64), https://aliyuncli.alicdn.com/aliyun-cli-windows-amd64-latest.zip (put aliyun.exe on PATH)
aliyun version            # verify the install — aliyun CLI >= 3.3.3 required (upgrade: brew upgrade aliyun-cli, or re-download the binary)
aliyun configure          # prompts for AccessKey ID / Secret / region
# RAM role assumption or STS token: pick the matching authentication mode in the prompts

# Option B — environment variables in ~/.zshenv (all zsh sessions, incl. IDE terminals)
echo 'export ALIBABA_CLOUD_ACCESS_KEY_ID=<id>' >> ~/.zshenv
echo 'export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<secret>' >> ~/.zshenv

キーは AccessKey コンソール で取得してください。SDK がキーを解決できることを確認します。aliyun sts get-caller-identity で確認できるのは CLI が独自の設定を読み取れることだけであり、Python の認証情報チェーンがキーを取得できたことの確認にはなりません。

python3 -c "from alibabacloud_credentials.client import Client; print(Client().get_credential().provider_name)"
# cli_profile/static_ak → Option A live; env → Option B live; CredentialException → nothing configured

1.2 OSS 出力バケット（必須）

アップロード先およびジョブの出力先として使用します。

export OSS_BUCKET=your_bucket_name
export OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com

バケットはステップ 0 の確認（§2.1）で選択します。aliyun ossutil ls を実行し、ユーザーが確認したリージョン内のバケットのみを表示して、ユーザーに選んでもらいます。黙って選択してはいけません。OSS では同じ認証情報チェーンを使用します。出力バケットは、生成ジョブと同じリージョンに配置する必要があります。

出力バケットは通常、非公開です。完成したオブジェクトを検証済みの再生リンクにする方法については、§8 を参照してください。

1.3 Model Studio API キー（任意、検証用）

scripts/frame_qa.py で完成した動画をマルチモーダルモデルに確認させるには、DASHSCOPE_API_KEY を設定します。これは AK/SK とは別の認証情報です。AK/SK ではモデル推論を呼び出せません。Model Studio コンソール → API-KEY でキーを作成し、echo 'export DASHSCOPE_API_KEY=sk-xxxxxxxx' >> ~/.zshenv で保存してから、新しいシェルを開いてください（IDE のターミナルを含む、すべての zsh セッションで有効になります）。対話型ターミナルでのみ必要な場合は、代わりに ~/.zshrc を使用してください。両方に設定してはいけません。

ユーザーが設定を辞退した場合、またはまだ設定していない場合でも、検証は行います。代わりに、自分の視覚能力でクラウドのスナップショットフレームを読み取ってください（§9）。キーについては一度だけ説明してから作業を続け、未検証の動画を検証済みとして報告してはいけません。

1.4 ffmpeg（任意 — 音声分析のみ）

編集や合成に ffmpeg は不要です。このスキルの目的はそこにあります。ここでの ffmpeg の役割はひとつだけです。理解および検証フェーズで、モデルが推論できるように、音声信号をテキストまたはグラフに変換します。メディアの生成、変換、抽出は行わず（ハードルール 2）、メディアファイルをダウンロードすることもありません（ハードルール 1）。https URL を渡すと必要なデータをストリーミングし、書き込むファイルはスクラッチディレクトリ内の分析成果物だけです（ハードルール 1）。

ICE API からは得られない音声情報の分析に使用します。RMS 波形（showwavespic）、無音や発話の末尾の検出（silencedetect — ASR のギャップで文の境界はわかりますが、環境音の末尾はわかりません。17-snapshot-and-asr.md §1.5）、ラウドネス（volumedetect）、長さ（ffprobe）です。クラウドのフィルムストリップと波形を同じ軸に重ねるのは timeline_view.py です。タイルはスナップショットジョブから取得し、ffmpeg が波形を描画して 2 行を 1 つの PNG に貼り合わせます。これはメディアではなくグラフです（ハードルール 2）。映像関連はすべてクラウドジョブで行い、ffmpeg は使いません。フレーム、フィルムストリップ、コンタクトシートは SubmitSnapshotJob（17-snapshot-and-asr.md §2）から取得し、カットポイントは上流のシーンラベル、omni_segment.py、または確認するフィルムストリップ（§2.4）から取得します。

macOS へのインストール：brew install ffmpeg。ffmpeg がない場合でも、クラウドスナップショットで必要なすべてのフレームを確認できます（17-snapshot-and-asr.md）。一方、波形、音声の末尾、ラウドネスの数値は得られません。--mode full（§9）で検証し、実行できなかったチェックを明記してください。黙って機能を落としてはいけません。

1.5 可観測性 — User-Agent

UA テンプレート： AlibabaCloud-Agent-Skills/{skill-name}/{session-id} skill-version/{skill-version}

セッション ID のルール： 利用可能な場合はホストの AGENT_SESSION_ID を使用してください。それ以外の場合は、プロセスごとに 32 文字の小文字の 16 進数 ID を 1 つ生成してください。同じ実行内のすべての Alibaba Cloud 呼び出しでは、同一のセッション ID を使用する必要があります。ここでの {skill-name} は alibabacloud-video-editor、{skill-version} は references/manifest.json から取得します。スクリプトは、クラウドクライアントの作成前、インポート時にこの値を読み込みます。scripts/video_editor.py は値を一度構築してすべてのクライアントに適用します。新しいクライアントでも config.user_agent = USER_AGENT を設定する必要があります。

---

2. ワークフロー

ステップ	アクション	詳細
0	何よりも先に、リージョンを確認してから出力バケットを確認	→ §2.1
1	リクエストを分類する	→ §3 ルーティングテーブル
2	該当するリファレンスドキュメントを読む	→ §3
3	素材の URL を収集する	→ §4
4	素材を確認する — 未解決の疑問ごとにシグナルを1つ（以下を参照）。まず上流の結果（§2.4）を確認し、その後、まだ判断が必要な内容に答える asr ／ snapshot ／ pack_material.py の処理だけを実行する	→ 17-snapshot-and-asr.md §0、§2.4、19-editor-brief.md
5	EDL（カットの判断）を作成し、compile で Timeline に変換する	→ 18-edl-and-compile.md。§5 のチェックリストは機械的に実行される
6	計画を平易な言葉で提案し、確認を待つ	→ §2.2
7	ジョブを送信する	→ §7
8	ポーリングして署名付き URL を取得する	→ §8
9	検証し、自分で修正して（最大3ラウンド）、結果を報告する	→ §9

単一メディアのアルゴリズムリクエストはショートカットできます。タスク全体が1つのファイルに対する1つのアルゴリズム（スマートカバー、ロゴ／字幕の消去、キャプション抽出、マッティング、美肌処理、H→V、音声ノイズ除去、音声ミキシング／分離、ビート／サビ／品質の検出）の場合、ステップ4〜5を省略し、§2.1 から §7.1 に進みます。Timeline はなく、§5 のチェックリストも適用されません。ただし、ステップ0、3、6、9（リージョン／バケット、素材の URL、計画の確認、検証）は引き続き実施します。アルゴリズムの出力を他の素材と組み合わせる必要がある場合は、まずアルゴリズムのジョブを実行し、その出力をタイムラインのパイプラインに渡します（13-intelligent-production.md §6）。

通常テンプレートの作成もショートカットできます。リージョンを確認し、パラメーター化された Config を設計してレビューした後、確認を得てから AddTemplate を呼び出します。出力バケットが必要になるのは、テンプレートをレンダリングするときです。references/22-normal-templates.md をお読みください。

ステップ4はシグナルごとに実施し、すべてをまとめて実行する必要はありません。 まだ答える必要がある疑問を明確にし、それに答えるシグナルだけを取得します。インデックスは 17-snapshot-and-asr.md §0 です。ファイル全体の連結には未解決の疑問がないため、ステップ4は実施せず、ステップ3からステップ5に進みます。ユーザーが指定した時刻と位置の字幕に関する疑問は、視覚的なものが1つだけです。フレームをサンプリングして確認してください（11-output-verification.md §3）。ASR は誰も尋ねていない疑問に答えることになります。asr と snapshot は課金対象のジョブです。「数秒で返る」ことは「無料」を意味しません。また、誤った処理を実行した場合も、正しい処理を実行した場合と同じ料金がかかります。

2.1 まず環境を確認する

リージョンを決めつけてはいけません。cn-shanghai でさえ、aliyun CLI のプロファイルや認証情報ファイルにすでにリージョンが記載されている場合でさえ同様です。レンダリングタスクでは、次の順序で確認してください。

1. どのリージョンでジョブを送信するかをユーザーに確認します。有効な ICE リージョン（cn-shanghai、cn-beijing、cn-hangzhou、cn-shenzhen、cn-zhangjiakou、ap-southeast-1）を列挙し、制約を伝えます。AI 機能を使うには cn-shanghai／cn-beijing／cn-hangzhou が必要です。つまり、すべての AI_* クリップとエフェクト、そして 14 個すべての SubmitIProductionJob 関数（§7.1）が対象です。また、MediaId 入力はアセットと同じリージョンで送信する必要があります。タスクがまだ決まっていない場合、ユーザーは回答を保留できます。ただし、その場合は Timeline を構築する前にこの手順に戻ってください。
2. どの出力バケットを使うかを確認します。確認済みのリージョンで絞り込みます。aliyun ossutil ls はすべてのバケットをリージョンとともに一覧表示するため、選択したリージョンにあるものだけをユーザーに提示し、選んでもらいます。出力バケットはジョブと同じリージョンにある必要があります。オフラインの Config 生成や AddTemplate ではこの手順を省略し、最初のテンプレートレンダリングの前に確認してください。
3. 両方を確認してから、どのような動画を作りたいかを尋ねます（§3 以降）。タスクに別のリージョンが必要だと判明した場合（例：AI 非対応リージョンでの AI 機能の利用や、別のリージョンにある MediaId の利用）は、手順 1 に戻り、ユーザーに再確認します。

利用できないリージョンは質問の対象であり、代替として勝手に選ぶものではありません。 ユーザーが指定したリージョンでリクエストに対応できない場合は、その旨を伝えて停止します。制約を明示し、対応可能なリージョンを列挙したうえで、リージョンと同じリージョンにあるバケットを尋ねてください。このドキュメントに明記された内容を確かめるためだけに一度送信してはいけません。iproduction は API リクエストを送る前にローカルで呼び出しを拒否します。また、サービスからの 400 応答では、何も得られないまま往復の時間がかかります。代わりのリージョンを自分で選ぶことも禁止です。失敗後にリージョン、バケット、製品を独断で切り替えるのは、ユーザーがしていない決定を勝手に下すことであり、ユーザーが希望していない場所に成果物を保存することになります。「直接送信して」／「そのまま送信して」は、計画の確認を省略するものです（§2.2）。この確認を省略するものではありません。

複数クリップの編集には EDL を使います。 タスクが「素材の範囲を N 個つなぎ合わせる」もの（ハイライト、プロモーション、エピソードの連結、モンタージュ）であれば、edl.json を作成してください。残す範囲ごとに source／in／out／beat／quote／reason を 1 つずつ記載し、compile を実行します（18-edl-and-compile.md）。これにより Timeline が出力され、§5 のチェックリストが機械的に実行されます。そのため、修正時には Timeline 全体を再生成するのではなく、数値を 1 つ変更するだけで済みます。装飾を加えても、このルールの対象外にはなりません。ミュート、背景のぼかし、フィルター、トランジションは範囲ごとの effects、アンビエントオーバーレイはトップレベルの EffectTracks、BGM は audio エントリーで指定します。いずれも EDL のフィールドです（18-edl-and-compile.md §1）。ミュート、ぼかし、トランジション、音楽の追加を伴う連続したつなぎ合わせも、やはりつなぎ合わせなので、引き続きコンパイルが必要です。最初から範囲のリストが存在しない場合に限り、Timeline を手書きしてください。対象は、単一クリップのジョブ、アバターのナレーション、スライドショーテンプレートです。

Timeline を直接生成する場合は、次の順に検討してください。出力タイプは何か → どのトラックを使うか → 各トラックにどのクリップを配置するか → クリップに In／Out／TimelineIn／TimelineOut が必要か（単純に連続してつなぐだけなら不要）→ どのエフェクト、トランジション、音量を使うか → JSON を出力する。

視覚的な結果を左右する情報が足りない場合は、構成を始める前に確認してください。 特に重要なのは背景です。背景の指定がないナレーション／アバター動画は黒背景でレンダリングされます。ユーザーが求めていない見た目を黙って選んではいけません。

2.2 送信前にプランを確認する

素材を読み、EDLを作成したら、平易な言葉で4～8文のプランを説明し、そこで止めてください。カットの構成、残す場面と削る場面、推定実行時間と素材全体の長さとの比較、映像の見た目（トランジション／カラーグレーディング／ウォーターマークの有無。何もない場合はその旨）、字幕と音声の処理、出力仕様を説明します。その後、返事を待ちます。

決まったチェックリストではなく、素材から浮かび上がる質問をしてください。適切な質問はその都度異なります。ただし、ほぼ毎回確認する価値がある質問が2つあります。目標の長さとウォーターマークを入れるかどうかです（デフォルトではオフです。compile はEDLに指定されていないものを勝手に追加しません。18-edl-and-compile.md §2）。

確認したとみなされるもの。 ユーザーが読める返信内の文章です。内部のタスクリストやTODO項目ではありません。コンパイル済みEDLでも、--yes を付けた submit コマンドでもありません。このフラグは、出力パスと上書きリスクについての スクリプトの stdin プロンプトを抑止するもので、このステップとは関係ありません（§7）。compile から submit へ一気に進むと、ユーザーは請求が届くまでカットの内容を知ることがありません。そのため、プランの説明と送信の両方を1つのタスク項目に含めないでください。「プランを伝えてから送信する」という項目1つでは、プランが存在しないまま、1回のツール呼び出しで両方が完了扱いになる可能性があります。プランを独立したステップにし、完成させて送信し、その後で初めて submit に進んでください。スクリプト実行や非対話型実行などで回答できる人がいない場合も、コマンドを実行する前にプランを書き出してください。人が不在でも、なくなるのは返事だけであり、ステップ自体は省略されません。

このステップは、ローカルエディターでの場合よりもここでは重要です。制作ジョブには費用と時間がかかり、納品物が却下されると一連の作業をすべてやり直すことになります。実際に、79秒の素材を66秒にカットしたところ「長すぎる。ハイライトではない」と却下され、30秒に作り直す必要がありました（19-editor-brief.md §4）。最初に段落を1つ書いておけば防げたはずです。

フィードバックを受けたら、EDLを修正して再コンパイルしてください。タイムラインを手作業で修正してはいけません（18-edl-and-compile.md §5）。

2.3 セッションの記録 — project.md

複数のセッションにまたがるプロジェクトでは、EDLと同じスクラッチディレクトリ内に project.md を保持してください（ハードルール1）。ユーザーのプロジェクトツリーには絶対に置かないでください。セッションごとに ## Session N — YYYY-MM-DD セクションを1つ追加し、環境（リージョン、出力バケット、使用中の MediaId）、戦略（1段落）、決定事項（カット、長さ、見た目、その理由、およびユーザーが却下した内容）、成果物（JobId、出力オブジェクトのパス、再利用する価値のある分析ジョブID）、保留中（延期した項目）を記録します。ユーザーが記録を残したい場合は、チャットに貼るか、指定された場所に書き込んでください。それはユーザーのファイルであり、中間ファイルではありません。

このスキルで特に役立つ理由は2つあります。§2.1に従えば、同じ質問を繰り返さずに済みます。前回のセッションを読み、「前回は cn-beijing／my-bucket でした。続けますか？」と確認すればよく、改めて質問する必要はありません。また、分析結果を再購入せずに済みます。変更されていない素材に対してASRやスナップショットのジョブをすでに実行している場合、再送信せずに結果を参照してください。却下された内容も記録してください。ユーザーがすでに断った戦略をもう一度探るのが、最もコストのかかる作業です。

起動時に project.md が存在する場合は、何かを提案する前に、前回のセッションを1文で要約してください。

2.4 上流の分析結果 — このスキルが利用するもの

チェーンの前段階は、ほかの機能に属します。データを受け取ったら、それを信頼できるものとして扱い、再導出しないでください。

上流の結果	適用先
カット候補／ハイライト区間（from／to + 理由）	EDL の ranges[] — 指定されたとおりに in／out を設定し、根拠を reason に記入します（18-edl-and-compile.md §1）
タイムスタンプ付きの文字起こし／会話タイムライン	ステップ 4 の asr パスを置き換えるか、照合します
字幕ファイル（SRT／WebVTT）	EDL の subtitles[]、または展開済み Timeline に対する decompile --inline-srt（21-timeline-export.md）
ラベル／タグ／人物の登場	どの区間を残すかを決定します。フレーム単位で正確なつなぎ目は、引き続き ASR の句読点 + 無音区間から取得します（17-snapshot-and-asr.md §1.5）
話者の帰属	どの VoiceId がどの行を担当するか、および用語集の名前（17-snapshot-and-asr.md §1.7）
クローン済み VoiceId（トレーニング済み — このスキルでは音声をトレーニングしません）	AI_TTS クリップの customizedVoice（07-smart-media-features.md、09-voice-and-avatar-catalog.md）

ルールは 2 つあります。

• 上流のタイムスタンプは候補レベルのものであり、フレーム単位で正確ではありません。 コンパイルする前に、各区間を実際のつなぎ目 — 句読点 + 0.3 秒以上の無音区間、上流ラベル／omni_segment.py／スナップショットのフィルムストリップによるショット境界（§1.4）、silencedetect による音声の末尾 — に合わせてください。粗い区間をそのままコピーすると、会話が途中で切れてしまいます（18-edl-and-compile.md §1.5）。
• 分析結果がない場合は、推測せずに質問してください。 必要なコンテンツの知識（重要な場面、話者など）が不足している場合は、ユーザーに上流の機能を実行してもらい、その結果を渡してもらってください。区間を捏造したり、全編カットに黙って切り替えたりしないでください。

---

3. 要件 → リファレンスの振り分け

リクエストに必要な機能に該当する行を見つけて読み、その後 Timeline を構築します。

各行が示すのはシナリオではなく機能です。「ハイライト動画」のドキュメントも「動画翻訳」のドキュメントもありません。シナリオとは機能を組み合わせたものであり、以下の行 — 通常は 2、3 行と 18-edl-and-compile.md — を組み合わせて実現します。リクエストに一致する行が 1 つもない場合でも、それはよくあることであり、失敗ではありません。

ユーザーの要望	参照先	主な型／フィールド
あらゆる内容（トラックとクリップの基本、長さの制御、位置合わせ）	01-timeline-basics.md	VideoTracks／AudioTracks／SubtitleTracks／EffectTracks、In／Out／TimelineIn／TimelineOut、MainTrack、MaxDuration、ClipId／ReferenceClipId、FECanvas
ボイスオーバー、ナレーション、BGM、ミキシング、ミュート、音量、音声のループ、ノイズ除去、ラウドネスの正規化、音声の抽出	02-multi-track-audio.md	複数のAudioTracks、Volume（Gain）、AFade、LoopMode、ADenoise、ALoudNorm、AEqualize
タイトル、字幕、エンドクレジット、スクロールテキスト、スタイル付き／吹き出しテキスト、字幕の背景、字幕アニメーション、常時表示するコーナータイトル、焼き付け字幕を消去した帯に重ねるテキスト、書き換えや翻訳後にトラック全体のタイミングを再調整（行幅と表示時間の再計算、用語集、吹き替えのカバー）	03-subtitles-and-titles.md（§1 位置、§11 タイミングの再調整）	Type: "Text"／"Subtitle"、Content、Alignment＋X／Y、FontSize、SubtitleEffects、AaiMotion*、Scroll*、AdaptMode、subtitle_localize.py
トランジション、フィルター、カラーグレーディング、VFX、マスク、ケン・バーンズ効果、ズーム、ぼかし／単色の背景、ウォーターマーク／ロゴ、ピクチャーインピクチャー、分割画面	04-effects-and-transitions.md	Transition／DLTransition、Filter、VFX、Flip、KenBurns、Zoom、Background、GlobalImage、EffectTracks
写真から動画を作成、画像カルーセル、スライドショー、フォトアルバム、オープニング／エンディングのタイトルカード（静止画をN秒間表示）	05-slideshow-template.md	Type: "Image"＋Duration、Transition、KenBurns、BGM
N個の範囲をカットにまとめる（ハイライト、プロモーション、エピソードの連結、モンタージュ）；各カットを作成した理由の記録；送信前のタイムラインの検証	18-edl-and-compile.md	compile サブコマンド、edl.json（sources／ranges／audio／subtitles）、BLOCK と WARN のチェックリスト
複数のクリップの連結、複数エピソードの結合、素材のクロップ、異なる種類の素材の混在（静止画＋動画）、横長から縦長への変換、ステッカー／GIF のオーバーレイ、再生速度の変更、反転／回転／クロップ／フリーズ、バッチでのリミックスバリエーション作成	06-multi-clip-editing.md	In／Out／MaxOut、Speed、Flip、Rotate、Crop、FreezeFrame、Clip＋RandomClip、AdaptMode
テキスト読み上げ、音声認識による字幕、カラオケ風のハイライト、既存のショット内のセリフの吹き替え／再録音、書き換えたセリフをショットの長さに合わせること、読み上げに合わせたナレーション、デジタルアバター／ニュース番組、グリーンスクリーンまたは実写背景の除去、SSML	07-smart-media-features.md	AI_TTS、AI_ASR（＋AlignmentText、NeedHighlighting）、AI_Avatar、AI_Matting、AI_RealMatting、Harmonization、SpeechRate、customizedVoice、行ごとのマイクロレンダー
出力解像度／ビットレート／コーデック／フォーマット、VOD または S3 への出力、カバー画像、完了コールバック	08-output-and-job-config.md	OutputMediaConfig、EditingProduceConfig、MediaMetadata、UserData.NotifyAddress
音声またはアバター画像の選択、提供されたクローン済みVoiceIdの使用	09-voice-and-avatar-catalog.md（接続方法は07-smart-media-features.mdも参照）	Voiceの値（複数の感情／CosyVoice／方言／多言語）、customizedVoice、AvatarIdの値
TTS／アバターのナレーション用スクリプトがない	10-narration-script-examples.md	Contentのスクリプトスタイル（ストーリー解説／ライブコマース）
完成動画の確認、フレームのサンプリング、品質に関する問題（「出力がおかしく見える」）、ある瞬間の確認（この継ぎ目は自然か、あのセリフは最後まで再生されたか、この場面の映像はどうなっているか）、複数範囲のカット後の継ぎ目の検証	11-output-verification.md（§6 継ぎ目、§7 再録音した出力）	frame_qa.pyによる動画全体のレビュー、スナップショットのサンプリング（ミリ秒単位の--time、瞬間を指定する--count 1）、フレームQAの盲点、timeline_view.py（フィルムストリップ＋波形、共通の時間軸、--seams edl.json）
編集前の動画の読み取り：タイムスタンプ付きの会話タイムライン、動画全体のフィルムストリップ／コンタクトシート、指定した時点のフレーム、分析結果を位置合わせするための時間↔ピクセルの対応表、別の見解としてのショット／会話の分割	17-snapshot-and-asr.md（§1.6 グラウンドトゥルース — 音声を1回、クラウド処理を2回 — ＋omni_segment.py、§1.7 話者の割り当て、§1.8 トランスクリプトは下書き）	asr／snapshot サブコマンド、EditingConfig.SentenceMaxLength、FrameType: normal、Sprite／WebVtt、--cover、--start-time／--duration
すべての分析結果を一画面で読みやすく表示；カット位置の候補を判断	17-snapshot-and-asr.md §1.5	pack_material.py → material_packed.md（ギャップ＋句読点＋無音を1つの時間軸に表示）
範囲の選択を委任；カットの構成（ハイライト／連結／デモ／解説／インタビュー／モンタージュ）の選択	19-editor-brief.md	サブエージェント向けブリーフのテンプレート、構成の類型、長さの厳守
1つのファイルに対する1つのアルゴリズム：スマートカバー、動画の要約、ロゴ／局ロゴ／ウォーターマークの削除、焼き付け字幕の消去、字幕のSRTへの抽出、グリーンスクリーンの背景除去、顔の美肌処理、横長から縦長へのリフレーム、サビ／ビートの検出、音声品質の確認、音声のノイズ除去、音声のミキシング、ボーカル／伴奏の分離	13-intelligent-production.md	iproduction／iproduction-status、FunctionName、Input／Output、JobParams、出力プレースホルダー
このスキルでは算出できないコンテンツ知識が必要なリクエスト：動画のラベル、アクションイベント、人物の登場、キーワードのタイムライン、ハイライト候補、話者の割り当て	§2.4 — 上流の処理結果を求め、決して推測しない	EDLのranges[]（in／out／reason）、SRTからのsubtitles[]、17-snapshot-and-asr.md §1.5による継ぎ目のスナップ
エンジンが実際に計算したタイムライン（AI_ASR／AI_TTS／AI_Avatar／VideoDetextの実行後）；完成したAI処理結果の微調整；AIの実行後に再実行せず構成を反復調整；カットをPremiereに渡す	21-timeline-export.md	export-timeline／export-timeline-status／decompile（＋--inline-srt）、ExportType、ProjectIdとTimelineの違い、SRT字幕トラック
再利用可能な標準テンプレートの作成、生成、確認、レンダリング；TemplateId／ClipsParam；可変メディアスロット；イントロ／アウトロまたはデフォルトのウォーターマークテンプレート	22-normal-templates.md	template_editor.py generate/create/get/expand/submit、AddTemplate、スカラーの$Param、ArrayItems／Array
実案件での注意事項：送信前のIMSバケット登録、MediaIdのみを使うASR入力、STSと長期AKによる署名付きURL配信、切り詰めを防ぐための連結ルール、動きのない外観プリセット、入力可能なテンプレート／ClipsParamの設計	23-production-pitfalls.md	aliyun ice get-storage-list、ASR入力形式、連結マージン、ClipsParamスロット
権限エラー、RAMの設定	ram-policies.md	ice:*、oss:* アクション
AI 機能（AI_*）は一部のリージョンでのみ実行されます。cn-shanghai、cn-beijing、または cn-hangzhou で送信してください。

---

4. 素材 URL

• ローカルファイル → oss-upload スキルを使ってアップロードし、返された OSS URL を使用します。
• すでに URL の場合 → そのまま使用します。URL だけではメタデータがありません。EDL で数値の out が必要な場合（18-edl-and-compile.md）は、ffprobe "<url>" で測定してください。HTTP 経由でストリーミングされ、何も書き込みません（ハードルール 1～2）。ffprobe がインストールされていない場合は、その旨を伝えて確認を求めてください。代わりに MP4/moov パーサーを自作してはいけません。再生時間を推測するのはさらに悪い方法です。
• すべての URL をそのままコピーしてください。 MediaURL／FileURL は、ユーザーの入力または以前のツール出力と一字一句同じでなければなりません。オブジェクトキーを「正規化」してはいけません。_ を - に打ち直したり、大文字と小文字を変えたり、末尾の数字を削ったりすると、InvalidMaterial.NotFound: The specified clips url not found が発生します。
• URL ではなく MediaId（32 文字の 16 進数アセット ID）の場合 → まず media-info（§8）を実行して、ファイル名、種類、リージョン、再生時間を確認してください（GetMediaInfo は FileInfoList[0].FileBasicInfo.Duration に返すため、ffprobe での確認は不要です）。アセットのリージョン（またはそのリージョンに AI 機能がない場合は AI 対応リージョン）でジョブを送信し、同じリージョンにある出力バケットを優先してください。

---

5. 送信前チェックリスト

以下のルールはすべて、実際に失敗したジョブから得られたものです。送信前にこのリストを確認してください。違反すると、生成ジョブが失敗するか、気付かないまま誤った結果が生成されます。

このリストの大部分は、現在、機械的にチェックされます。 compile と submit の両方で実行されます。失敗が記録されたルールはブロックされ、それ以外は警告されます（18-edl-and-compile.md §3）。ICE にはサーバー側のドライランエンドポイントがありません。Timeline チェッカーと通常テンプレート用の expand コマンドはローカルでの再実装であるため、新しいエンジンルールを見落とす可能性があります。それでも、チェックできない事項（意図、素材の選択、§5-E のパラメーター運用）については、リストを確認してください。

A. 正しいクリップタイプと配置

ルール	正しい例	誤った例（失敗）
AI 機能には AI_ を付ける	AI_ASR、AI_TTS、AI_Matting、AI_RealMatting、AI_Avatar	ASR／TTS／Matting のみ
AI_Avatar は VideoTrackClips のクリップタイプです	{"Type":"AI_Avatar","AvatarId":...,"Voice":...,"Content":...}	別のクリップの Effects に入れる → InvalidTimelineFormat: ... MediaId is empty
マッティングはクリップの Effects に指定するエフェクトです	{"Type":"AI_RealMatting"}	マッティングのクリップタイプ、または SubType: "Matting"
グリーンスクリーンのマッティングパラメーター	{"Type":"AI_Matting","Color":"green"}	ColorType／"GreenScreen"
実写シーン（グリーンスクリーンなし）のマッティング	AI_RealMatting	AI_Matting（輪郭が粗くなります）
ミラー／反転には専用エフェクトを使う	{"Type":"Flip","Direction":"horizontal"}	hflip／vflip を指定した VFX → InvalidTimelineFormat: Invalid vfx subType
字幕テキストのフィールド	Content	Text

AI_ASR には有効な配置が 2 通りあります。目的に応じて選択してください。

• VideoTracks／AudioTracks のクリップの Effects 内：{"Type":"AI_ASR","AlignmentText":"...", <style fields>} — 字幕はそのクリップ自身の音声を元に生成され、同じジョブでレンダリングされます。ナレーション／アバター動画に推奨されるワンステップ方式であり、NeedHighlighting／HighlightingStyle が機能する唯一の配置です。
• SubtitleTracks 内のクリップとして指定し、MediaURL で元動画を参照：既存の動画音声を通常どおり認識します。

音声から字幕を生成する場合は、必ず組み込みの AI_ASR を使用してください。音声を自分で文字起こししたり、合成音声に合わせて Type: "Text" クリップのタイミングを手動で設定したりしてはいけません。

1 つのスクリプトにつき AI_Avatar クリップは 1 つです。 ナレーション全体を 1 つのクリップの Content に入れてください。文ごとに分割すると、アバターが文ごとに冒頭のジェスチャーを繰り返します。

B. 音声

• ミュート／音量には Gain を使用します：{"Type":"Volume","Gain":0}（0 = ミュート、1 = 元の音量、1 より大きい値 = 増幅、最大 10、3 以下を推奨）。Volume エフェクト内の {"Volume": 0} はジョブの失敗につながります。
• LoopMode は音声クリップ専用です：AudioTrackClips のクリップを 1 つ使用し、LoopMode: true と In／Out、TimelineIn／TimelineOut を設定します。動画を繰り返すには、コピーを隣接させる（またはテンプレートの ArrayItems 展開を使用する）とともに、最後のコピーを目標の長さにトリミングします。
• 同じトラック上の音声クリップは時間的に重ねてはいけません。音声を重ねるには、別々のトラックを使用します。

C. 映像とエフェクト

• 1 つの EffectTrack につきエフェクトの種類は 1 つだけです：EffectTracks の各エントリーの EffectTrackItems に含められるエフェクトの種類は 1 つだけです。フィルターと VFX は別々の EffectTrack エントリーに配置してください。混在させるとジョブが失敗します（同じ種類のアイテムを複数含めるのは問題ありません）。
• タイムラインに実際の動画が含まれない場合、GlobalImage には明示的な Duration が必要です。設定しないと、最初のフレームにしか表示されません。実際の動画が含まれる場合は、出力全体に自動的に表示されます。
• 背景は、指示がある場合は画面全体を覆う必要があります：背景クリップに（キャンバス相対の）"Width": 1, "Height": 1 を設定します。AdaptMode だけでは、黒帯が残る場合があります。
• 通常の Transition は、その Duration の分だけ出力を短くします（クリップが重なります）。合計の長さを変えずに保つには、DLTransition を使用します。

D. タイムライン構成

• 動画または音声のクリップが少なくとも 1 つ必要です：VideoTracks と AudioTracks の両方を空にすることはできません。字幕のみのタイムラインは TimelineFormatError: Both video tracks and audio tracks are empty. で失敗します。字幕は何かの上に表示されるため、テキストのみの成果物は作成できません。何を追加するかはユーザーが決めることであり、あなたが決めることではありません（§2.1）。背景について何も言及されていない場合は、どれを使うか尋ねてください。画像、動画、音声を明示的にすべて禁止されている場合は、指定された条件のままでは依頼を実行できないと伝え、どの制約を緩和するか尋ねてください。このチェックを通すためにアセットを生成またはアップロードしてはいけません。黒い PNG や無音の WAV は、明示的な指示を無視することになり、ユーザーのバケットに誰も求めていないオブジェクトを残してしまいます。
• インデックス番号の大きい動画トラックほど、インデックス番号の小さいトラックの上に表示されます。
• TimelineIn／TimelineOut を省略すると、クリップは配列の順序どおりに隙間なく連結されます。

E. パラメーターの扱い

• ユーザーが指定したパラメーターだけを設定してください。 任意のスタイル／エフェクトパラメーターの値を勝手に作らないでください。誤ったデフォルト値によって、意図した結果が気付かないうちに損なわれることがあります。

  • マスクの outer_alpha=1.0 は、マスクが何もしていないように見えます。blur_intensity=1.0 は、内側全体をぼかします。
  • マット処理した人物のオーバーレイに Width／Height を設定すると、人物のサイズが変わり、「同じ人物、異なる背景」という要件が崩れます。
  • Gain の値を推測すると、ミックスの音量が意図せず変わります。

  これらのフィールドは省略してエンジンのデフォルトを適用するか、リファレンスドキュメントにある実証済みの組み合わせをコピーしてください。

• URL は原文のまま使用します（§4）。

---

6. 最小限のタイムライン例

完全版、簡略版、長さを指定した例は references/01-timeline-basics.md にあります。Timeline を手書きできるのは、クリップ 1 つの Timeline、またはエクスポート済みの Timeline の場合に限られます（§7.2）。 クリップが 2 つ以上ある場合は、EDL を作成してから compile -e edl.json -O timeline.json を実行してください（§2 手順 5、18-edl-and-compile.md）。EDL は通常数行で済み、コンパイルもオフラインのコマンド 1 つで実行できます。また、§5 のチェックリストを機械的に実行する唯一の方法でもあります。自作スクリプトで validate_timeline／lint_timeline をインポートしても、このチェックは実行されません。

---

7. ジョブを送信する

停止してください。§2.2 の計画は、すでに返信に含まれていますか？ ユーザーに送った最後の内容がカットの説明文ではなくコマンドだった場合は、これを実行しないでください。compile と submit を1回のツール呼び出しバッチで実行することを防ぐために、このセクションがあります。

# Submit and wait for completion (--yes skips the script's stdin prompt, not §2.2)
python "$SKILL_DIR/scripts/video_editor.py" submit \
  --timeline timeline.json \
  --output-config output.json \
  --region <region confirmed in §2.1> \
  --wait --yes

--region は必須で、デフォルト値はありません。ポーリングせずに送信するには --wait を省略します。--client-token を指定すると、再試行が冪等になります。すべてのフラグについては、video_editor.py submit --help を参照してください。

確認は2種類あり、--yes が対応するのはそのうち1つだけです。 --yes を指定しない場合、スクリプトは標準入力で Do you want to proceed? [y/N] と尋ね、非対話型のシェルでは中断するため、エージェントは基本的に常にこのフラグを指定します。このフラグが省略するのは、出力パス、解像度、リージョン、上書きのリスクに関するスクリプト独自の確認だけです。これは§2.2 の計画確認ではありません。§2.2 はこのコマンドが存在する前に会話内で行うものなので、それを代わりに行えるフラグはありません。計画をすでに返信でユーザーに見せている場合に限り、submit に進んでください。

OutputMediaConfig：

{
  "MediaURL": "https://{your-bucket}.oss-cn-shanghai.aliyuncs.com/{your-target-video-path}",
  "Width": 1080,
  "Height": 1920
}

ユーザーが解像度を指定していない場合は、1080×1920（縦向き）または1920×1080（横向き）を使用します。ビットレート、コーデック、VOD/S3 出力、コールバックなど、その他のフィールドについては 08-output-and-job-config.md を参照してください。

送信すると JobId が返されます。

7.0 通常のタイムラインテンプレート

再利用可能な編集構成については、references/22-normal-templates.md を読んでください。Config をローカルで生成し、その固定アセットと置換スロットをユーザーに提示してから、確認を得たうえで永続テンプレートを作成します。見慣れないテンプレートをレンダリングする前に、その ClipsParam を get し、ローカルで expand してください。コンソールで生成された数値のスロット ID を推測してはなりません。また、VideoDuration という名前のスロットは、そのスロットが置き換えるフィールドだけを示すことを忘れないでください（references/22 §Parameter Rules）。

python "$SKILL_DIR/scripts/template_editor.py" generate --preset video-concat -o template_config.json

ここで停止し、Config をユーザーに提示してください。固定アセット、置換スロット、およびそれらのスロットが意味する ClipsParam の仕様を示します。AddTemplate はクラウド上に永続リソースを作成するため、これは§7 の注記にあるとおり、--yes では代替できない確認です。

python "$SKILL_DIR/scripts/template_editor.py" create --name "Video Concatenation Template" \
  --config template_config.json --region <confirmed region> --yes

テンプレートのレンダリングは通常の生成ジョブなので、§2.2 の確認、同じリージョンの出力バケット、ポーリング、§9 の検証、最大3回の自己修正ラウンドがすべて適用されます（references/22-normal-templates.md §Workflow）。

7.1 インテリジェント制作ジョブ（単一メディアのアルゴリズム）

アルゴリズムは1つ、入力ファイルは1つ、Timeline は使用しません。送信する前に references/13-intelligent-production.md を読んでください。 14個の関数名、それぞれの JobParams、必須の出力プレースホルダー、結果の形式は推測できません。

# Smart cover images from a media asset into OSS
python "$SKILL_DIR/scripts/video_editor.py" iproduction \
  --function Cover --input <mediaId-or-oss://bucket/object> \
  --output 'oss://<bucket>/covers/{source}-{sequenceId}.png' \
  --job-params '{"Model":""}' \
  --region <region confirmed in §2.1> --wait --yes

# Poll / re-read a job
python "$SKILL_DIR/scripts/video_editor.py" iproduction-status --job-id <job_id> --region <region>

• SubmitIProductionJob には ClientToken がありません。何も確認せずに再試行すると、2つ目のジョブの料金が発生します。再送信する前にクエリしてください。
• 入力バケット、出力バケット、メディアアセット、ジョブは、すべて同じリージョンに存在する必要があります。
• 14個すべての関数が AI 機能です。利用できるのは cn-shanghai / cn-beijing / cn-hangzhou のみです。その他のリージョン（cn-shenzhen、cn-zhangjiakou、ap-southeast-1）では、API に到達する前に iproduction がローカルで ValidationError を返して失敗します。サービスに到達した場合も、InvalidParameter.FunctionNotSupported が返るだけです。このリクエストでは、ここが行き止まりです。§2.1 に戻り、ユーザーにリージョンと同一リージョンのバケットを尋ねてください。代わりのものを指定してはなりません。
• タイムラインジョブと同じように、§9 に従って結果を検証してください。消去または美顔ジョブは、何も変更していなくても Success を返します。

7.2 プロジェクトのエクスポート — AI によって展開されたタイムライン

送信するタイムラインには、AI の宣言（AI_ASR、AI_TTS、AI_Avatar、VideoDetext）が含まれます。実際のアドレスとタイミングは、エンジンの実行後にのみ存在します。ユーザーが計算済みのタイムラインを必要とする場合は、エクスポートしてください。コマンドとフラグについては references/21-timeline-export.md を参照してください。

python "$SKILL_DIR/scripts/video_editor.py" export-timeline \
  --project-id <ProjectId from GetMediaProducingJob> \
  --bucket <scratch bucket, same region> --prefix export/ep01 \
  --region <region confirmed in §2.1> --output timeline_expanded.json --wait --yes

Timeline ではなく ProjectId を渡してください。ProjectId はすでに実行済みのレンダーを展開しますが、未レンダリングの Timeline を渡すと、エクスポートによって AI タスクが実行され、課金されます。この Timeline は EDL が存在しないため、手動編集しても構いません（§11 の例外）。ただし、decompile して EDL に戻すほうが望ましいです。ほかのすべてと同じループでオフラインに処理でき、AI が再実行されることもありません。

---

8. ポーリングとレポート

# Query once (region = the region the job was submitted in)
python "$SKILL_DIR/scripts/video_editor.py" status --job-id <job_id> --region <region>

# Wait for completion
python "$SKILL_DIR/scripts/video_editor.py" status --job-id <job_id> --region <region> --wait
# Add --details to print the submitted ClipsParam and Timeline when diagnosing a template render.

# Resolve a MediaId to a signed (authenticated) URL and media details (region = the asset's region)
python "$SKILL_DIR/scripts/video_editor.py" media-info --media-id <media_id> --region <region>

# Verified V4 signed URL for private-bucket hand-off (supports AK and STS)
zsh "$SKILL_DIR/scripts/oss_sign_clean.sh" oss://<bucket>/<object> [ttl-seconds] [region-or-endpoint]

ステータスの値：Init、Queuing、Processing ＝ 実行中、Success ＝ 完了、Failed ＝ 原因を確認するため、メッセージを調べてください。

Success の場合、status はジョブの MediaId、MediaURL、再生時間を出力します。その MediaId を指定して media-info を実行すると、署名付き URL を取得できます。出力バケットは通常プライベートであるため、通常の OSS URL は表示できません。

URL は 2 種類、用途も 2 つです。 media-info の URL は、今この場でのあなた向けです。有効期限はおよそ 1 時間で、STS 署名付きのものには取得できないものもあります。これから行う §9 の確認には問題ありませんが、後でユーザーが開く必要のあるものには使えません。ユーザーに渡す URL は oss_sign_clean.sh で生成します。V4 署名で、STS トークンを含み、リージョンが限定され、出力前に curl で検証されます。検証に失敗したものは納品物ではありません（23-production-pitfalls.md §3）。署名処理自体に失敗した場合は、その旨を明確に伝え、有効期限が短く未検証であることを明記した media-info の URL と、再署名コマンドを渡してください。通常の URL を、検証済み URL のように装って渡してはいけません。

この URL が納品物です。ただし、まだ回答ではありません。 ユーザーに届けるのは §9 の後です。media-info が返す再生時間や解像度はメタデータであり、検証ではありません。BGM がミュートされているのか、ミックスされているのかは判断できません。再生リンクとして、有効期限と再署名用のワンライナーを添えて報告してください。完成した動画をユーザーのマシンにダウンロードしてはいけません（ハードルール 1）。ローカルコピーの取得は、ユーザーから明示的に依頼された場合に限ります。

---

9. 出力を検証する

Success はファイルが書き込まれたことを意味するだけです。素材の誤り、黒いフレーム、字幕の欠け、音声の無音があっても Success と表示されます。すべての納品物を報告前に検証してください。 詳細なガイダンスは references/11-output-verification.md を参照してください。

最初に利用できる方法を選んでください。

順序	方法	コマンド	必要なもの
1	クラウドのスナップショットフレームをあなたが確認する（推奨）	video_editor.py snapshot --mode normal -i <output MediaId or oss:// object> -r <region> --time <ms> --count 12 --interval 5 -O "oss://<bucket>/qa/f-{Count}.jpg" --wait を実行し、その後 snapshot-urls で署名付きリンクを取得	AK/SK + 出力バケット
2	動画全体 + モデル	frame_qa.py --video "<signed URL>" --mode full	DASHSCOPE_API_KEY
3	出力全体のクラウドフィルムストリップ	video_editor.py snapshot --mode webvtt --cover <duration> → スプライトのタイルを確認（§9 の継ぎ目チェックを参照）	AK/SK + 出力バケット

まずフレームを確認してください。動画の長さに関係なくコストは一定です（89 MB / 78 s の動画 → JPEG 約 500 KB、約 3～5k トークン）。一方、動画全体を確認すると 1 秒ごとにトークンが消費されます。短いトランジションでは、5 秒間隔よりも密にサンプリングする必要があります。--interval は秒単位で、1 つのジョブ内のフレーム間隔のみを指定します。一方、--time はミリ秒単位なので、任意の瞬間を確認するには個別のジョブが必要です（--time <ms> --count 1）。疑わしい継ぎ目の前後 ±0.1 s と ±0.2 s を確認する場合は、1 フレームのジョブを 4 回実行します（11-output-verification.md §6）。frame_qa.py はクラウド上の素材のみを確認し（--video <signed URL>、または --frames による署名付きフレーム URL）、何もダウンロードしません（ハードルール 1～2）。 DASHSCOPE_API_KEY がありませんか？ 検証を省略したり、キーが用意されるまで待ったりしないでください。パス 1 と 3 にはキーはまったく不要です。URL に対応したビジョン／ブラウザーのツールで、署名付きフレーム URL を確認してください。ローカルの絶対パスが必要なファイルリーダーに HTTP URL を渡してはいけません。必要であれば、curl でフレームをスクラッチディレクトリに保存して、そのファイルを確認してください。あなたはマルチモーダルモデルである可能性が非常に高いため、自分自身のビジョンをレビュアーとして活用してください。§1.3 を一度だけユーザーに案内し、そのまま続行してください。ビジョンによるキー不要の方法は、画像に関する質問に限られます。音声が主役の成果物にはフレームではなく、以下の ffmpeg によるリスニングパスを使ってください。自分で画像を読み取れませんか？ その場合、キーは必須です。同じ署名付きフレーム URL をモデルに渡し（frame_qa.py --frames "<url>" …）、自分自身によるレビューではなく、モデルによるレビューとして結果を報告してください。ビジョンもキーも使えない場合に限り、出力を未検証として報告し、その理由を伝えてください。

ユーザーが検証を免除した場合（「别检查了」／「just send the URL」）は？ その希望に従ってください。これはユーザーの判断であり、パス 1 はジョブと、ユーザーがかけたくないかもしれない 1 分を要します。ただし、免除されるのは検査の実行であって、報告ではありません。URL に未検証と明記して渡し、Success が証明するのはバイトが書き込まれたことだけであると率直に説明してください。また、ユーザーの希望により省略した項目（フレーム、音声の末尾、意図した長さとのレンダリング時間の比較）を挙げ、気が変わったときに 10 秒で実行できるコマンドを 1 つ提示してください（上記のパス 1 の snapshot）。返信を、検証済みの成果物であるかのように受け取られる内容にしてはいけません（ハードルール 5）。

成果物の価値が音声や動きにある場合は、--mode full に切り替えてください（TTS ナレーション、AI_Avatar のリップシンク、BGM ミキシング、KenBurns／Scroll* アニメーションなど）。フレームのサンプリングでは音声を聴いたり、同期ずれやカクつきを確認したりできません。ナレーションが主役の出力では、レンダリング時間と意図したナレーション時間を比較してください。レンダリングが短ければナレーションが途中で切れています。理由なく長ければ、末尾に黒画面や無音が残る可能性があります。ジョブが Success でも、どちらかが当てはまれば成果物は不合格です。検査間隔より短いトランジションも確認できます。その箇所を狙って 1 フレームのジョブを実行してください。ただし、1 時点ごとにジョブが 1 つ必要になるため、まず全体をスキャンし、問題がありそうな箇所だけを絞り込んでください。

--mode full にはキーが必要です。音声が主役の成果物には、キー不要の方法がもう 1 つあります。ffmpeg に署名付き出力 URL を渡し、映像ではなく信号を読み取ってください。 これは分析であり、ローカルでのミキシングやレンダリングを禁じるハードルール 2 には抵触しません。ストリーミング処理を行い、書き込まれるファイルはスクラッチ内の分析用ファイルだけです（§1.4）。出力に対して volumedetect または astats を実行すれば、ミックスのベッド音量が指定どおりか、元の音声が保持されているか、末尾が早く無音になっていないかを確認できます。キーも ffmpeg も使えない場合は、音声は未検証と報告し、どちらが使えないのかを明記してください。フレームの確認は代わりになりません。BGM が 20% でもミュートでも、フレームは同じように見えるからです。

複数範囲のカットでは、さらに継ぎ目に焦点を当てた検証が必要です（すべてのカットで台詞が途切れていないこと。透かしを指定した場合は、配置され、カットで途切れていないこと）。詳しくは 11-output-verification.md §6 を参照してください。モデルによる QA では、台詞の途中で切れていることを見逃す場合が多くあります。その確認には timeline_view.py --seams edl.json を使います。各継ぎ目につき 1 枚の画像が作られ、両側の映像がフィルムストリップと音声波形として共通の時間軸上に表示されます。この組み合わせで見つけられる主な問題は、音声が映像のカットを越えて続く台詞です。カット時点のフレームには顔しか映っていないため、フレームだけでは確認できません。 単純にファイル全体をつなぎ合わせる場合、ソースフレームは不要です。 素材の同一性はすでに二重に確認されています。URL はそのままコピーされ（§4）、ICE は素材を解決できない場合、InvalidMaterial.NotFound を明示的に返して失敗します。出力の先頭、継ぎ目、末尾をスナップショットし、レンダリング時間をソースの長さの合計と比較してください。これで、ファイルの欠落、順序の入れ替わり、黒い継ぎ目を検出できます。出力フレームをソースのスナップショットとピクセル単位で照合しても、Timeline ですでに確認できていることに答えるため、アンカーごとに課金対象のジョブが増えるだけです。素材にクロップ、マット、消去、速度変更などの変換を加え、変換前の状態を確認する必要がある場合に限り、ソースフレームを取得してください。

動画以外の IProduction 成果物（§7.1）には frame_qa.py は適していません。抽出した SRT を読み込み、タイミングとテキストをソースと照合してください。検出 JSON／Result を読み込み、範囲がメディアの長さに対して妥当か確認してください。音声出力には --mode full を使用し、実際に聴いてください。動画出力（消去、ビューティー、H→V、マッティング）には、上記の通常の手順を使用してください。変更されるはずの領域からフレームをサンプリングします。

9.1 自己修正ループ — 最大3ラウンド

検証は、引き渡すレポートではありません。まず完了させるループです。

1. 検証します。すべて合格したら、成果物を提示します。
2. 失敗があれば、正となるソース、つまりEDL、または通常テンプレートのレンダリングではテンプレートの Config／ClipsParam を修正し、再コンパイル／展開して再送信し、再検証します。パラメーターの型だけでなく、仮説を変更してください。
3. 3ラウンドで停止します。 問題が残っている場合は、結果に未納品と明記し、未解決の不具合を挙げ、証拠を添えてください。説明のつかない不一致を「テンプレートの仕様」や完了済みの結果として扱ってはいけません。

失敗した箇所は、それを検出した検査よりも高解像度で再検証してください。たとえば、1 fps で検出された継ぎ目は、もう一度 1 fps で走査するのではなく、字幕帯のストリップを 4～8 fps で確認します（11-output-verification.md §6）。以前失敗した検査に合格して初めて、不具合が修正されたと判断してください。

検証していないプレビューをユーザーに見せないでください。納品しないものは提示しないでください。

その後、実際に送信した Timeline（複数段階のパイプラインは要約します。結果がトラックのマウント方法に依存する場合は、字幕トラックを抽出した SRT から作成したか、吹き替え音声トラックか、ウォーターマーク／エフェクトレイヤーかを明記します。たとえば JobId だけでなく、マウントそのもの、SubtitleTracks[].FileURL → SRT オブジェクトを記載します）、出力情報（バケット／オブジェクトパス／リージョン／MediaId／長さ／解像度／JobId）、署名付き視聴 URL（有効期限があることを明記）、使用した検証手順、その結果、検証できなかった事項、自己修正に要したラウンド数を報告してください。

---

10. エラー → 修正

references/25-error-index.md でメッセージを確認してください。各行に原因、最短の修正方法、その説明があるセクションが記載されています。Success と報告されるのに成果物を損なう失敗については、§11 を参照してください。

---

11. アンチパターン

references/25-error-index.md には、明示的に失敗する事例が記載されています。ここでは、Success を返しながら不適切な成果物を生成するものや、往復処理を無駄にするものを取り上げます。どれも一度は代償を払って学んだ事例です。

プロセス

• プランの確認前に編集する。 レンダリングには費用がかかりますが、文章にはかかりません（§2.2）。よくあるのは、同じターン内で compile からそのまま submit --yes を実行し、内部のタスクリストをユーザーが確認したプランだと思い込むことです（§2.2「確認とみなされるもの」）。
• 確認していない出力を、確認したかのように報告する。 Success が意味するのは、バイト列が書き込まれたことだけです（§9）。よくあるのは、status → media-info →「出力を確認しました」という流れです。再生時間と解像度はメタデータであり、音声の成果物ではミックスについて何もわかりません（§8、§9）。ユーザーが確認を省略することを認めた場合は、その旨を伝え、成果物を未確認と明記してください。省略の許可によって認められるのは確認を省くことであり、問題がないとの保証ではありません（§9）。
• 同じ不具合に3回を超えて取り組み続ける。 不具合を明示して、引き継いでください（§9.1）。
• 検証に失敗した後、Timelineを手作業で修正する。 それでは、Timelineを作成した判断から逸脱し、次のラウンドで検討する材料がなくなります。EDLを修正してください（18-edl-and-compile.md §5）。唯一の例外はエクスポート済みのTimelineです（§7.2）。AIによる展開には対応するEDLがないため、結果を微調整するには直接編集するしかありません。
• 計算されたタイムラインではなく、提出したタイムラインを微調整する。 AI_* エントリはプレースホルダーであり、アライナーの文境界と実際の再生時間は含まれていません。まずエクスポートしてください（§7.2）。
• 変更されていないソースを再分析する。 ASRとスナップショットの出力は、不変の入力に対する不変の関数です。キャッシュしてください（§2.3）。
• メディアをダウンロードして確認する、または作業ファイルをユーザーのプロジェクトに書き込む。 ストリーミングし、スナップショットを取得し、スクラッチファイルはスクラッチ領域に置いてください（厳守事項1）。完成した動画も同様です。成果物は再生URLであり（§8）、ユーザーのディスク上のファイルではありません。
• project.md に地域やバケットがすでに記録されているのに、ユーザーに再度尋ねる（§2.3）。
• このドキュメントに記載された制約を調べるために地域を試し、その後、自分でジョブを別の地域に移す。 cn-shenzhen での InvalidParameter.FunctionNotSupported の呼び出しを3回行っても、§7.1 にすでに記載された以上のことはわかりません。その後、cn-shanghai と別のバケットに切り替えると、ユーザーが依頼していない2つの判断を下すことになります。最初に拒否された時点で停止し、ユーザーに確認してください（§2.1）。

素材の確認

• スナップショットジョブで FrameType: intra を使用する。 フレームの3分の1しか出力されないまま、Success が報告されます（17-snapshot-and-asr.md §2.2）。
• レスポンスの例に現れたという理由で、文書化されていないAPIフィールドを信頼する。 SubmitASRJob はエラーを出さずにこれらを受け入れて無視します（17-snapshot-and-asr.md §1.3）。
• リクエストパラメーターからフィルムストリップのタイル座標を計算する。 サーバーが座標を書き換えるため、VTTを確認してください（17-snapshot-and-asr.md §2.3）。
• 上流が持つべきコンテンツの知識をでっち上げる。 ハイライト候補、ラベル、話者の割り当てはデータとして届きます（§2.4）。推測した範囲を使うのは、コイントスでレンダリング費用を払うようなものです。上流の結果を依頼し、会話のタイムラインには SubmitASRJob を使用してください。
• タイムスタンプの取得に qwen-omni-turbo を使う。 40秒のクリップでも、量子化による誤りや幻覚が発生します（17-snapshot-and-asr.md §1.6）。

カット

• 無音の長さだけで文の境界を判断する。 実測では、無音区間の条件を満たした候補16件のうち2件は文の途中でした。文末の句読点と、0.3秒以上の無音区間の両方を条件にしてください（17-snapshot-and-asr.md §1.5）。
• 映像のシーンが切り替わる位置で Out をカットする。 会話の音声はカットをまたいで続くことがよくあります。音声の末尾に合わせてください（18-edl-and-compile.md §1.5）。
• 目標の長さに合わせるため、会話ブロックの途中をトリミングする。 代わりにブロック全体を削除してください（18-edl-and-compile.md §1.5）。
• ソースの大部分を残す「ハイライト」。 79秒から66秒への短縮は却下され、30秒は承認されました。デフォルトは30～40％にしてください（19-editor-brief.md §4）。
• 長さの選択肢として「できるだけ長く」を提示する。 最長の選択肢は、ソースの半分を上限にしてください。

構成

• 往復処理を省くためにローカルで ffmpeg レンダリングすること — パーツを concat で連結し、-filter_complex でオーバーレイし、字幕を焼き込み、吹き替え音声に atempo を適用します。ICE が生成したことのない納品物が作られるため、後続の工程では再現も再編集もできず、明確に禁止されています（ハードルール 2）。EDL またはタイムラインを修正して再提出してください。ICE ジョブで編集を表現できない場合は、その旨を報告してください。
• ユーザーが求めていないオプションのパラメーターを勝手に設定すること。 誤ったデフォルト値は、意図した結果を気づかれないまま損ないます。outer_alpha=1.0 ではマスクが何も作用していないように見えます。マット処理された人物に Width／Height を指定すると、人物が拡大縮小されます（§5-E）。
• Text クリップで X／Y を指定すること。 動作が不安定なため、Alignment のみを使い、フレームを確認してください（03-subtitles-and-titles.md）。
• 誰も求めていないウォーターマークを入れること。 デフォルトでは無効です（§2.2）。
• 複数範囲をカットした部分にトランジションを付けること。 フレームがぼやけ、行末が欠けるため、求められていない限りハードカットにしてください（18-edl-and-compile.md §1.5）。
• AI_Avatar のスクリプトを複数のクリップに分割すること。 アバターは文ごとに冒頭のジェスチャーを繰り返します（§5-A）。
• 合成音声に合わせて Text クリップのタイミングを手動調整すること。 AlignmentText を指定した AI_ASR を使い、エンジンに位置合わせさせてください（§5-A）。
• HighlightingStyle.FontColor に RGB の 16 進数を指定すること。 バイト順の BGR で、# プレフィックスは付けません。同じクリップの通常の FontColor／OutlineColour フィールド（#RRGGBB）とは逆です。"00FFFF" は黄色に、"FFFF00" はシアンにレンダリングされます。"#FFFF00" は黒になります（解析エラー）。必ずサンプルフレームで色を確認してください（07-smart-media-features.md）。
• 翻訳トラックに元の字幕タイミングをそのまま使うこと。 スペイン語やドイツ語の音声は英語より 10～30 % 長くなります。元の字幕キューの表示時間のままでは、翻訳文がフレームからはみ出したり、読めない速さで表示されたりします。言語ごとに改行と表示時間を再計算し、各キューを吹き替え音声の全体をカバーする長さにしてください（03-subtitles-and-titles.md §11）。
• 長すぎるセリフへの最初の対処として、吹き替え音声を速くすること。 対処の順序は、**翻訳を書き直す → SpeechRate を上げる → ICE で再レンダリングする際にオーディオクリップの Speed を上げる（上限は約 1.5）**です。ローカルで atempo を使うことは決してしないでください（ハードルール 2）。34 文字のセリフを 21 文字に書き直したところ、自然な速度で 2 秒のショットに収まりました。速度を上げたバージョンは、早口すぎるとして却下されました（07-smart-media-features.md）。また、音声に合わせるために映像の再生速度を変えてはいけません。
• 長さを確認していない吹き替え音声の ASR 結果を信頼すること。 認識結果は、途中で切れたテイクに対して、完結した文を幻覚として補い、短い区間では単語を捏造することがあります。確認対象の不具合そのものが隠れてしまいます。まず音声の長さを測り、それから内容を確認してください（11-output-verification.md §7）。
• 渡された VoiceId を別の話者のセリフに割り当てたり、自分で学習させようとしたりすること。 話者の判定は声質の推測ではなく、画面上で口を動かしている人物に基づいて行われます（17-snapshot-and-asr.md §1.7）。また、クローン音声はユーザーから入力として受け取るものであり（§2.4）、このスキルから送信するジョブではありません（07-smart-media-features.md）。

12. ファイル一覧

パス	用途
scripts/requirements.txt	Python の依存関係
related_apis.yaml	依存する Alibaba Cloud API
references/manifest.json	スキル名＋バージョン — UA の skill-version/ ソースです。クラウドへの初回呼び出し前に読み込みます（§1.5）
scripts/video_editor.py	実行ツール：compile（オフラインの EDL → Timeline ＋チェックリスト）／submit／status／media-info／asr／asr-status／snapshot／snapshot-urls／iproduction／iproduction-status／export-timeline／export-timeline-status／decompile（オフラインの展開済み Timeline → EDL）
scripts/template_editor.py	通常テンプレートの実行ツール：オフラインの共通 Config プリセット、およびローカルでの expand／AddTemplate／GetTemplate／TemplateId ＋ ClipsParam によるジョブ生成
scripts/frame_qa.py	クラウド上の素材のみをモデルでレビューします。動画全体（--video、§9）または署名付きスナップショットフレーム URL（--frames）に対応し、ローカルでのサンプリングは行いません（ハードルール 1–2）
scripts/pack_material.py	ASR ＋ WebVTT ＋ silencedetect を material_packed.md に統合します。単一の時間軸、カットマーカー、キャッシュに対応します
scripts/timeline_view.py	共通の時間軸にフィルムストリップと音声波形を表示します。継ぎ目ごとの検証には --seams edl.json を使用します
scripts/omni_segment.py	qwen3.5-omni-plus によるショット／ダイアログのセグメンテーションです。ASR 文字起こしのセカンドオピニオンを得られます（17-snapshot-and-asr.md §1.6）
scripts/oss_sign_clean.sh	プライベートバケットからの受け渡しに使用する、検証済みの OSS V4 署名付き URL です。AK と STS に対応します（§8）
scripts/subtitle_localize.py	ローカライズ用字幕キューの生成ツールです。折り返し、表示時間の再計算、用語集の検証、SRT に対応し、sub_end が実測された吹き替え音声を包含するようにします（03-subtitles-and-titles.md §11）
references/	機能ナレッジベース（§3 ルーティング）、25-error-index.md、ram-policies.md
evals/scenarios/	評価シナリオ