alibabacloud-video-forge

Alibaba Cloud Video Forge

Alibaba Cloud Media Processing Service（MPS）を通じて、カバー画像の生成、複数解像度へのトランスコード、コンテンツモデレーションなど、動画処理をワンストップで実行します。

前提条件

事前確認：Aliyun CLI 3.3.3 以降が必要です aliyun version を実行して、バージョンが 3.3.3 以降であることを確認してください。インストールされていない場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行して更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。

事前確認：Aliyun CLI プラグインの更新が必要です [MUST] aliyun configure set --auto-plugin-install true を実行して、プラグインの自動インストールを有効にしてください。 [MUST] aliyun plugin update を実行して、既存のプラグインを常に最新の状態にしてください。

事前確認：AI-Mode の設定が必要です [MUST] aliyun CLI コマンドを使用する前に、AI-Mode を設定してください。

• aliyun configure ai-mode enable
• aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge"
• aliyun configure ai-mode disable

事前確認：Python 3.10 以降が必要です python3 --version を実行して確認してください。

事前確認：Alibaba Cloud の認証情報が必要です

aliyun configure list を実行して、認証情報の状態を確認してください。有効なプロファイルがない場合は、aliyun configure で設定してください。 認証情報のセキュリティルールについては、references/security-guidelines.md を参照してください。

🚀 クイックスタート

最も簡単な方法 - ワンクリックで動画を処理：

# Method 1: Use end-to-end workflow script (Recommended)
python scripts/video_workflow.py --input /path/to/video.mp4

# Method 2: Check environment first
python scripts/health_check.py

# Method 3: Execute steps manually
python scripts/oss_upload.py --local-file video.mp4 --oss-key input/video.mp4
python scripts/mps_transcode.py --oss-object input/video.mp4 --preset multi
python scripts/mps_audit.py --oss-object input/video.mp4

一般的なシナリオ

シナリオ 1：Bilibili への動画公開

python scripts/video_workflow.py \
  --input my_video.mov \
  --preset 720p \
  --generate-cover \
  --scenes porn terrorism ad

シナリオ 2：UGC コンテンツのモデレーション

python scripts/mps_audit.py --oss-object /input/user_uploaded.mp4

シナリオ 3：複数解像度へのトランスコード

python scripts/mps_transcode.py \
  --oss-object /input/course_video.mp4 \
  --preset multi \
  --output-prefix output/course_2024/

---

シナリオの説明

このスキルは、以下の動画配信シナリオに対応しています。

1. トランスコード — Narrowband HD 圧縮による複数解像度へのトランスコード
2. コンテンツモデレーション — センシティブなコンテンツ（ポルノ、テロリズム、広告）を自動検出
3. スナップショット — カバー画像とスプライトシートを生成
4. 著作権侵害対策 — コンテンツ保護のための暗号化を設定

アーキテクチャ

OSS Bucket + MPS Pipeline + Transcoding Templates + Moderation Service

コンポーネント：

• OSS：動画と出力を保存
• MPS Pipeline：タスクキューを管理
• トランスコードテンプレート：Narrowband HD、Standard のプリセット
• モデレーション：コンテンツの安全性を自動チェック

対象ユーザー：動画プラットフォーム、コンテンツクリエイター、企業研修、教育プラットフォーム

機能の概要

機能ツリーと自動パイプライン管理の詳細については、references/capability-overview.md を参照してください。

環境変数

必須の環境変数：

• ALIBABA_CLOUD_REGION - サービスリージョン（デフォルト：cn-shanghai）
• ALIBABA_CLOUD_OSS_BUCKET - OSS バケット名
• ALIBABA_CLOUD_OSS_ENDPOINT - OSS エンドポイント
• ALIBABA_CLOUD_MPS_PIPELINE_ID - MPS Pipeline ID（任意。未設定の場合は自動選択）

セキュリティに関する注意： 認証情報は Alibaba Cloud のデフォルト認証情報チェーンで管理されます。aliyun configure コマンドを使用して認証情報を設定してください。スクリプトやコマンド内で AK/SK を直接扱わないでください。

🔒 セキュリティガイドライン

セキュリティガイドラインと認証情報管理のベストプラクティスについては、references/security-guidelines.md を参照してください。

SDK のインストール

詳細なインストールガイドとトラブルシューティングについては、references/sdk-installation.md を参照してください。

python3 --version を実行して確認してください。古いバージョンの Python では、一部のスクリプトが失敗する場合があります。

RAM の権限

[MUST] RAM 権限の事前確認： 実行前に、現在のユーザーが以下の RAM 権限を持っていることを確認してください。 権限の一覧と詳細については、references/ram-policies.md を参照してください。

[MUST] 権限エラーへの対応： 実行中にコマンドまたは API 呼び出しが権限エラーで失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL に必要な権限の一覧を確認します
2. ram-permission-diagnose スキルを使用して、必要な権限を申請する手順をユーザーに案内します
3. 必要な権限が付与されたことをユーザーが確認するまで待機します

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（入力動画のパス、出力バケット、テンプレート ID など）を 必ずユーザーに確認してください。明示的な承認なしに、デフォルト値を想定または使用しないでください。

パラメーター	必須／任意	説明	デフォルト
input-url	必須	入力動画の URL またはローカルパス	-
output-bucket	任意	出力 OSS バケット	環境変数の値
output-path	任意	出力パスのプレフィックス	output/
template-id	任意	トランスコーディングテンプレート ID	システムプリセットテンプレート
resolutions	任意	トランスコーディング解像度の一覧	720p,1080p
audit	任意	コンテンツモデレーションを実行するかどうか	true
pipeline-id	任意	MPS パイプライン ID	自動選択

基本的なワークフロー

シナリオ 1：動画の一括標準化

一連のワークフロー：ユーザーが動画を提供 → OSS にアップロード → メディア情報を確認 → カバー画像を生成（スナップショット） → 複数解像度にトランスコード → コンテンツモデレーション → 結果を要約（ダウンロードリンク付き）

ステップ 0：パイプラインの自動選択（任意）

このスキルはパイプラインの自動管理に対応しており、通常はパイプライン ID を手動で設定する必要はありません。スクリプトがタスクの種類に応じて適切なパイプラインを自動選択します。

手動で指定する場合：

# Method 1: Set environment variable (highest priority)
export ALIBABA_CLOUD_MPS_PIPELINE_ID="your-pipeline-id"

# Method 2: Command line parameter
python scripts/mps_transcode.py --oss-object /input/video.mp4 --pipeline-id your-pipeline-id

# Method 3: Use script auto-selection
export ALIBABA_CLOUD_MPS_PIPELINE_ID=$(python scripts/mps_pipeline.py --select)

ステップ 1：動画を OSS にアップロード

source .venv/bin/activate
python scripts/oss_upload.py --local-file /path/to/video.mp4 --oss-key input/video.mp4

ステップ 2：メディア情報の確認

python scripts/mps_mediainfo.py --oss-object /input/video.mp4

ステップ 3：カバー画像の生成（スナップショット）

スナップショット機能を使用して、指定した時刻の動画カバー画像を生成します。

python scripts/mps_snapshot.py --oss-object /input/video.mp4 --mode normal --time 5000

ステップ 4：アダプティブトランスコーディング（最適な解像度とナローバンド HD テンプレートを自動選択）

# Adaptive mode: Auto-detect source video resolution, select best quality, use Narrowband HD template
python scripts/mps_transcode.py --oss-object /input/video.mp4

# Or manually specify multi-stream transcoding
python scripts/mps_transcode.py \
  --oss-object /input/video.mp4 \
  --preset multi

ステップ 5：コンテンツモデレーション

python scripts/mps_audit.py --oss-object /input/video.mp4

ステップ 6：タスクのステータスをポーリング

python scripts/poll_task.py --job-id <job-id-from-step-4> --job-type transcode --region cn-shanghai

完全な例

# 1. Activate virtual environment
source .venv/bin/activate

# 2. Upload video
python scripts/oss_upload.py --local-file ./my_video.mp4 --oss-key input/my_video.mp4

# 3. Get media info
python scripts/mps_mediainfo.py --oss-object /input/my_video.mp4

# 4. Cover generation (snapshot at 5 seconds)
python scripts/mps_snapshot.py --oss-object /input/my_video.mp4 --mode normal --time 5000

# 5. Submit transcoding job (adaptive mode: auto-select best resolution)
python scripts/mps_transcode.py \
  --oss-object /input/my_video.mp4
# Save the returned job-id

# 6. Poll transcoding job status
python scripts/poll_task.py --job-id <job-id> --job-type transcode --region cn-shanghai --interval 10

# 7. Content moderation
python scripts/mps_audit.py --oss-object /input/my_video.mp4

# 8. Download processed video to local
python scripts/oss_download.py --oss-key output/transcode/transcoded.mp4 --local-file ./output_video.mp4

その他のシナリオ

シナリオ 2：トランスコーディングのみ

スナップショットとモデレーションを実行せず、トランスコーディングのみを実行します。

source .venv/bin/activate
python scripts/mps_transcode.py \
  --oss-object /input/video.mp4 \
  --preset 1080p \
  --template-id "your-template-id"

シナリオ 3：コンテンツモデレーション

コンテンツモデレーションのみを実行します。

source .venv/bin/activate
python scripts/mps_audit.py \
  --oss-object /input/video.mp4 \
  --scenes porn terrorism ad

成功の確認

動画の処理後、結果を確認します。

1. スクリプトの終了コードが 0 である
2. 出力に処理済みメディア情報（OSS パス）が含まれている
3. トランスコーディングジョブのステータスが "Success" である
4. コンテンツモデレーションで違反が検出されていない
5. 成果物がローカルにダウンロードされている（oss_download.py を使用）

成果物の取得に関する注意：

• OSS ファイルへのオンラインアクセスには署名が必要です。URL に直接アクセスすると 403 エラーが返されます
• oss_download.py を使用して結果をローカルにダウンロードすることをおすすめします
• オンラインプレビューには、--sign-url パラメーターを使用して一時的な署名付き URL を生成してください

# Verify transcoding success
python scripts/poll_task.py --job-id <job-id> --job-type transcode --region cn-shanghai
# Expected output: Status: Success

# Verify moderation result
python scripts/mps_audit.py --query-job-id <audit-job-id>
# Expected output: Moderation passed, no violations

トラブルシューティング

包括的なトラブルシューティングガイドについては、references/troubleshooting.md を参照してください。

---

クリーンアップ

このスキルの中間ファイルと出力ファイルは OSS に保存されます。削除するには：

# Delete single file
python scripts/oss_delete.py --oss-key output/transcode/video.mp4

# Delete all files under directory (recursive delete)
python scripts/oss_delete.py --prefix output/ --recursive

# Force delete (skip confirmation, for script automation)
python scripts/oss_delete.py --oss-key output/video.mp4 --force

# Preview mode (view files to be deleted without actually deleting)
python scripts/oss_delete.py --prefix output/ --recursive --dry-run

注： 削除操作は取り消せません。実行前に確認してください。まず --dry-run を使用してプレビューしてください。

利用可能なスクリプト

スクリプト	説明
scripts/load_env.py	環境変数ローダー。Alibaba Cloud の認証情報を自動スキャンして読み込みます
scripts/poll_task.py	MPS 非同期タスクのポーラー。タスクのステータスを照会します
scripts/oss_upload.py	ローカルファイルを OSS にアップロードします
scripts/oss_download.py	OSS からローカルにファイルをダウンロードします
scripts/oss_list.py	OSS Bucket 内のファイルを一覧表示します
scripts/oss_delete.py	OSS のファイルまたはディレクトリを削除します（再帰削除に対応）
scripts/mps_mediainfo.py	メディアファイルの情報（解像度、ビットレート、再生時間など）を取得します
scripts/mps_snapshot.py	スナップショットとスプライトシートを生成します（通常モード／スプライトモードに対応）
scripts/mps_transcode.py	動画をトランスコードします（アダプティブ Narrowband HD、複数の解像度プリセット、カスタムパラメーターに対応）
scripts/mps_audit.py	コンテンツの安全性をモデレーションします（複数のモデレーションシナリオに対応）
scripts/mps_pipeline.py	パイプライン一覧の照会と自動選択（パイプライン ID の取得）

ベストプラクティス

1. 最初に必ず環境変数を確認する — 各セッションの開始時に python scripts/load_env.py --check-only を実行します
2. 待機せずにポーリングを使用する — ジョブの送信後、poll_task.py を使ってステータスを自動ポーリングします
3. 解像度を適切に選択する — 対象ユーザーのデバイスに応じて、適切なトランスコード解像度を選択します
4. コンテンツモデレーションを有効にする — UGC コンテンツでは、常に自動モデレーションを有効にします
5. 仮想環境を使用する — 依存関係を分離し、バージョンの競合を避けます
6. パイプラインを自動管理する — パイプライン ID を手動で設定する必要はありません。スクリプトがタスクの種類に応じて適切なパイプラインを自動選択します

参考ドキュメント

ドキュメント	説明
references/ram-policies.md	RAM 権限ポリシーの一覧
references/params.md	スクリプトパラメーターのドキュメント
references/scripts-detail.md	スクリプトの詳しい使用例
references/verification-method.md	成功の確認方法
references/related-commands.md	関連する CLI コマンド
references/cli-installation-guide.md	Aliyun CLI のインストールガイド
references/acceptance-criteria.md	テストの受け入れ基準

AI-Mode の設定

[MUST] Aliyun CLI の AI-Mode セットアップ — aliyun CLI コマンドを使用する前に、適切なトラッキングとプラグイン管理を有効にするため、AI-Mode を設定する必要があります。

AI-Mode を有効にする

機能を強化するために AI-Mode を有効にします：

aliyun configure ai-mode enable

User-Agent を設定する

スキルを適切に識別できるよう、User-Agent を設定します：

aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge"

AI-Mode を無効にする

不要になったら AI-Mode を無効にします：

aliyun configure ai-mode disable

注：適切な機能トラッキングとプラグインの互換性を確保するため、aliyun CLI コマンドを実行する前に AI-Mode を有効にする必要があります。

CLI コマンドの標準

重要：User-Agent は AI-Mode の設定を通じて自動的に適用されます。aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge" を実行すると、その後のすべての aliyun CLI コマンドに正しい User-Agent が自動的に含まれます。各コマンドに --user-agent パラメーターを追加する必要はありません。