byted-tos-video-process

Volcengine TOS Video Process

Volcengine TOS に保存された動画を調査し、フレームを抽出して、動画クリップを連結します。メタデータの参照、単一スナップショットの取得、複数フレームのキャプチャ、動画の連結、TOS から TOS への保存に対応しています。

セットアップ（環境ごとに1回）

初回使用時に依存関係をインストールします。

cd {baseDir}
pip install -r {baseDir}/requirements.txt

その後、Python 3.7 以降でスクリプトを実行します。

python3 {baseDir}/scripts/<script>.py <args>

tos の ModuleNotFoundError が表示された場合は、依存関係を再インストールしてください。

環境変数

このスキルでは、metadata ブロックで宣言された TOS ID を使用します。一般的な実行時変数は次のとおりです。

環境変数	必須	説明
TOS_ACCESS_KEY	はい	TOS アクセスキー ID
TOS_SECRET_KEY	はい	TOS シークレットアクセスキー
TOS_ENDPOINT	はい	TOS エンドポイント URL
TOS_REGION	はい	TOS リージョン
TOS_BUCKET	はい	動画を保存するソースバケット
TOS_OBJECT_KEY	いいえ	動画のソースオブジェクトキー。一部のスクリプトでは代替値を指定できますが、video_info.py と video_snapshot.py はこの値を環境変数から読み取ります
TOS_SECURITY_TOKEN	いいえ	一時的な認証情報を使用する場合の STS セッショントークン
TOS_SAVEAS_BUCKET	いいえ	スナップショットの保存先となるデフォルトのバケット
TOS_SAVEAS_OBJECT_PREFIX	いいえ	スナップショットの保存先となるデフォルトのキーのプレフィックス

クイックスタート（よく使うタスク）

# Read video metadata (resolution, duration, codec)
TOS_OBJECT_KEY=demo.mp4 python3 {baseDir}/scripts/video_info.py

# Capture a single frame at 5 seconds
TOS_OBJECT_KEY=demo.mp4 python3 {baseDir}/scripts/video_snapshot.py --time 5000 --output frame_5s.jpg

# Capture multiple frames and save locally
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 --timestamps 1000 3000 5000

# Capture multiple frames by interval
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 \
  --interval-ms 5000 --duration-ms 60000 --output-dir snapshots

# Capture multiple frames and save to TOS
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 --timestamps 1000 3000 5000 --save-to-tos

# Concatenate multiple video clips
python3 {baseDir}/scripts/video_concat.py --key clip1.mp4 --fragments "clip2.mp4,clip3.mp4" --output-key merged.mp4 --wait

利用可能なスクリプト

スクリプト	用途
scripts/video_info.py	動画のメタデータ（形式、再生時間、解像度、コーデック、フレームレート）を読み取ります。
scripts/video_snapshot.py	指定したタイムスタンプで単一フレームをキャプチャします。ローカルへの保存、または TOS から TOS への保存に対応しています。
scripts/video_snapshots.py	タイムライン上の複数のフレームを一括でキャプチャします。明示的なタイムスタンプ、間隔モード、並行実行、TOS から TOS への保存に対応しています。
scripts/video_concat.py	複数の動画クリップを1つに連結します。TOS ゲートウェイの media_jobs 非同期 API を job_type=Concat で使用します。完了までポーリングする --wait に対応しています。

video_snapshots.py と video_concat.py では、--key 形式でオブジェクトを選択できます。video_info.py と video_snapshot.py は、現在 TOS_OBJECT_KEY を環境変数から読み取ります。video_snapshots.py では、複数バケットのテスト用に --bucket による上書きにも対応しています。詳しい使い方は、各スクリプトを -h 付きで実行してください。

対象外

• 動画の完全なトランスコードパイプライン（このスキルの対象は、メタデータの参照、フレーム抽出、連結のみです）。
• 画像のみ、またはドキュメントのみのワークフロー（byted-tos-image-process または byted-tos-doc-process を使用してください）。
• TOS 以外のストレージプロバイダー。

ルール

• 認証：認証には、上記の metadata ブロックで宣言された TOS ID を使用します。スクリプトごとに --key でオブジェクトの選択を上書きできます。
• タイムスタンプの単位：すべてのタイムスタンプパラメーターの単位はミリ秒です（例：5000 = 5秒）。
• タイムスタンプの検証：スナップショットのタイムスタンプが動画の再生時間を超えないようにしてください。必要に応じて、まず video_info.py で再生時間を確認してください。
• TOS への保存：--save-to-tos と TOS_SAVEAS_BUCKET／TOS_SAVEAS_OBJECT_PREFIX を使用すると、ローカルにダウンロードせずにスナップショットを TOS に保存できます。
• パラメーターの正式な参照元：video/snapshot のパラメーター全体については、Volcengine TOS の公式ドキュメントが正式な参照元です。不明な場合は、REFERENCE.md を確認してください。
• 言語：ユーザーの希望する言語で返信してください。

関連資料

• セットアップと環境：README.md
• パラメーターのリファレンス：REFERENCE.md
• エンドツーエンドのワークフロー：WORKFLOWS.md