Mux から Transloadit への移行
Mux は、動画を取り込み、エンコードし、HLS 再生向けにパッケージ化します。Transloadit は、より広範なメディア処理プラットフォームです。ファイルのアップロードやインポート、複数レンディションの生成、HLS や MPEG-DASH 出力の作成、サムネイルの生成、字幕の追加、音声の文字起こし、結果の自社ストレージへの保存を行えます。
このガイドでは、オンデマンド動画カタログを対象に、取り込み、エンコード、サムネイル、自社ストレージへのエクスポート、およびそれに伴うアプリケーション変更を扱います。メタデータ、アップロード、Webhook、セキュリティに関する判断事項を整理します。Player SDK の実装、再生分析、ライブストリーミング、DRM、多言語トラックのパッケージ化、AI ワークフローの再構築は、この具体例の対象外です。
ストレージと DAM の対象範囲以下のフローは、利用中の S3 バケットと CDN にエクスポートします。ホスト型 DAM の移行、フォルダーとメタデータのインポート、tlcdn.com の配信切り替え、移行のドライラン/マニフェスト、Media Library のロール、ウィジェット、CMS/エディター連携には、別途移行計画が必要です。このガイドには、ホスト型 DAM インポーターは含まれません。
移行マップ
| Mux の概念 | 移行時の判断 |
|---|---|
| 直接アップロード | SDK または Uppy 経由で 🤖/upload/handle Robot を使用します。あわせて、サーバー側のアップロード認可フローを変更します。 |
| アセット作成 | 処理ワークフローは Assembly が実行します。永続的なメディア ID 用に、アプリケーション側でカタログレコードを保持します。 |
| 動画品質レベル | 🤖/video/encode Robot のプリセットとレンディションラダーを選択します。Mux の品質レベル名は Transloadit のプリセット名ではありません。 |
| アダプティブ再生 | 🤖/video/adaptive Robot でレンディションをパッケージ化するか、🤖/video/ondemand Robot を別途評価します。 |
| ポスター画像 | 🤖/video/thumbs Robot でファイルを生成し、画像 URL を置き換えます。 |
| キャプション/字幕 | 既存のテキストトラックは別途保持します。🤖/speech/transcribe Robot で新しい SRT または WebVTT ファイルを生成できます。プレーヤーにどのように渡すかを決めてください。 |
| アセット準備完了 Webhook | Assembly Notifications では、ペイロードと署名方式が異なります。 |
| Playback ID と URL | ストレージ/CDN から配信するエクスポート済み HLS マニフェスト、または Smart CDN の URL を使用します。既存 ID はルックアップテーブルに保持します。 |
Assembly は、Mux のアセット、その playback ID、アクセス制御ポリシー、分析履歴を再作成するものではありません。メディア本体を移行する前に、それぞれの責務をどのアプリケーションが担うかを決めてください。
事前エンコードかオンデマンドエンコードかを選ぶ
プリセットと URL の移行
Mux は現在、品質レベルを basic、plus、premium として命名しています。plus は per-title encoding を使用します。以下の固定 3 レンディションラダーでは、その挙動は再現されません。独自のプリセットを選ぶ前に、代表的な動画で、画質、ファイルサイズ、アスペクト比、フレームレート、必要な最大解像度を比較してください。詳しくは、Mux の品質レベルガイド を参照してください。サムネイル URL オプション についても、フレーム時刻、寸法、フィットモードなどを洗い出し、対応する出力を意図的に生成してください。それらのクエリー文字列をエクスポート画像の URL に引き継いでも、変換は適用されません。
予測しやすいカタログでは、/video/encode と /video/adaptive で事前にバリアントをエンコードします。視聴される動画が一部に限られる大規模カタログでは、視聴者のリクエスト時に HLS アセットを生成するために、Smart CDN と組み合わせた
/video/ondemand を評価してください。この Robot には、レスポンス分岐の末尾が
/file/serve になる、別の互換性のある Smart CDN Template が必要です。エンコード予算の悪用を防ぐため、URL はバックエンドで署名してください。以下のアップロードとエクスポート用 Template は、Smart CDN 用ではなく事前エンコード用です。
アダプティブ動画 Template の例
この Template は、動画を受け取り、3 つのレンディションをエンコードし、セグメント化して、ビットレート別バリアントプレイリストとマルチバリアントプレイリストを書き出し、サムネイルを生成して、パッケージを S3 に保存します。この例では Assembly ごとに 1 つのソース動画を使い、その解像度に適したレンディションを選んでください。3 つのプリセットは、低解像度ソースに不足している細部を追加するものではありません。
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"encoded_480p": {
"use": ":original",
"robot": "/video/encode",
"preset": "hls/480p",
"ffmpeg_stack": "v7"
},
"encoded_720p": {
"use": ":original",
"robot": "/video/encode",
"preset": "hls/720p",
"ffmpeg_stack": "v7"
},
"encoded_1080p": {
"use": ":original",
"robot": "/video/encode",
"preset": "hls/1080p",
"ffmpeg_stack": "v7"
},
"hls": {
"use": {
"steps": ["encoded_480p", "encoded_720p", "encoded_1080p"],
"bundle_steps": true
},
"robot": "/video/adaptive",
"technique": "hls",
"playlist_name": "playlist.m3u8",
"result": true
},
"poster": {
"use": ":original",
"robot": "/video/thumbs",
"count": 1,
"result": true
},
"exported_hls": {
"use": "hls",
"robot": "/s3/store",
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "videos/${assembly.id}/${file.meta.relative_path}/${file.name}",
"url_prefix": "https://cdn.example.com/",
"acl": "bucket-default"
},
"exported_poster": {
"use": "poster",
"robot": "/s3/store",
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "videos/${assembly.id}/posters/${file.url_name}",
"url_prefix": "https://cdn.example.com/",
"acl": "bucket-default"
}
}
}
/video/adaptive は、その出力に relative_path を設定します。プレイリスト参照を解決できるよう、エクスポートパスでもこれを保持してください。サードパーティ認証情報 と、バケットルートを読み取れる CDN を設定してください。url_prefix は配信を設定したり、アクセス権を付与したりはしません。acl: "bucket-default" はオブジェクト ACL を送信しないため、アクセス制御はバケットポリシーと CDN オリジンアクセスで設定してください。
署名付き Assembly リクエストでは notify_url を設定し、通知署名を検証し、ASSEMBLY_COMPLETED を必須にしてください。エクスポートでは、生成元の Step 配下にある URL が更新されます。results.hls にはセグメントとプレイリストが並ぶため、meta.relative_path が空で、名前が playlist.m3u8 のエントリーを選択してください。サムネイルは results.poster から読み取り、その URL を永続化する前に
is_temp_url: false を確認してください。一時的な Transloadit URL は 24 時間後に失効し、再生には使えません。詳しくは、結果ファイルの保存 を参照してください。トラフィック切り替え前に、エクスポート済みマニフェスト、ビットレート別バリアントプレイリスト、セグメントを、想定する HLS プレーヤー経由で CDN 上からテストしてください。
既存の Mux ソースファイルをインポートする
Mux からのエクスポート
各環境のアセットを一覧取得し、ページネーションをたどってください。各アセットの playback ID、ポリシー、トラック、メタデータ、処理設定は、移行マニフェストに保持します。元のバイト列が必要な場合は、保持しているオリジナルファイルを優先してください。Mux にしかコピーがない場合は、master_access: "temporary" で一時的な master access を有効化し、master.status: "ready" または video.asset.master.ready を待ってから、返された
master.url をインポートに使用します。この URL の有効期間は 24 時間です。期限切れのインポートを再試行する前に、再度アクセスを要求してください。Mux は master について、元のバイト列を保証するのではなく、max_resolution_tier により解像度が制御される、入力と同等品質のものと説明しています。MP4 には映像と主要音声トラックが含まれます。代替音声は保持し、テキストトラックは別途ダウンロードしてください。詳しくは、Mux の master download ガイド を参照してください。
Static MP4 renditions は、アセットの品質レベルでエンコードされた配信用ファイルです。バックフィルで Mux の master が必要な場合は master access を使用してください。static rendition は、独自の画質および解像度制約を持つ別の選択肢です。
ソース動画ファイルが S3 に残っている場合は、🤖/s3/import Robot を使用します。アプリケーションが一時的な HTTPS ソース URL を保持している場合は、🤖/http/import Robot を使用します。Template のバックフィル用バリアントを保存してください。:original のアップロード Step を、imported という名前のインポート Step に置き換え、use: ":original" への 4 つの参照(3 つのエンコードとポスター)をすべて
use: "imported" に変更します。このインポート Step には、Assembly ごとに 1 つの認可済みソース URL または S3 キーを設定してください。/s3/import では、独自のソース credentials と path を設定します。/http/import では、url を設定します。たとえば、HTTPS インポート Step では、署名付き Assembly リクエストの fields.source_url から、バックエンドが選択したソース URL を読み取れます。
{
"steps": {
"imported": {
"robot": "/http/import",
"url": "${fields.source_url}"
}
}
}
これは入力 Step の置き換え例であり、完全な処理 Template ではありません。アクセス権があるソース URL のみを使用してください。一時的なソース URL は、インポート完了まで有効である必要があります。期限切れになった URL は再試行前に更新してください。エクスポートと再生確認が成功したら、照合のために元のアセット ID を保持したまま、新しい playback URL をデータベースに書き込みます。
メタデータ、構成、バージョン使用している場合は、Mux の
meta.title、meta.creator_id、meta.external_id に加えて、passthrough もカタログにコピーしてください。アプリケーション内のタグ、フォルダーパス、コレクション所属、改訂履歴も同じマニフェストに保持します。インポート Step が転送するのはメディアであり、こうしたカタログ上の関係ではありません。各改訂には新しいオブジェクトキーを割り当て、旧アセット ID と playback ID から、新しいマニフェスト、ポスター、テキストトラック URL への対応表を保持してください。サンプルでは Assembly ID を出力プレフィックスに使っているため、再試行時も置き換え改訂を公開する前に照合が必要です。
チェックリスト
アップロードウィジェット Mux Uploader は Mux Direct Upload URL を使用します。この UI とエンドポイントフローは、Uppy とその Transloadit プラグインに置き換えてください。置き換えの手順はフレームワーク別ガイド に従ってください。短期間有効な署名付き Assembly オプションを返す前に、ユーザーを認可し、許可された Template をサーバー側で選択します。アップロード進行状況と処理完了は区別し、playback URL を公開するのはエクスポート成功後のみにしてください。
Webhook と自動化
Mux の video.asset.ready イベント は、再生準備完了を通知しますが、別個の master download や static rendition の準備完了までは通知しません。Mux は、Webhook を mux-signature ヘッダーで署名し、その 配信には重複や再試行が含まれる場合があります。Transloadit の通知検証は、Transloadit 自身のドキュメントに従って実装してください。Mux のイベントハンドラーを置き換える前に、ソース改訂と Assembly ID でカタログ更新を重複排除し、失敗を処理し、再試行台帳を保持します。Assembly Notifications に Mux の署名検証ロジックを再利用してはいけません。
セキュリティ Mux の 署名付き再生では、サーバー側で生成した JWT を使用します。それらのトークンは、置き換え先の CDN を認可するものではありません。視聴者認可は、移行先 CDN の仕組みで再構築し、HLS マニフェスト、プレイリスト、セグメント、ポスター、キャプションを保護したうえで、許可されるリクエストと拒否されるリクエストの両方をテストしてください。Assembly リクエスト署名 は処理を認可しますが、エクスポート済みファイルへのアクセスを付与したり制限したりはしません。S3 のアクセスポリシーと CDN オリジン権限は、各アセットの公開範囲に合わせて整合させてください。アップロードポリシーでマルウェアスキャンが必要な場合は、🤖/file/virusscan Robot を追加します。上記の例には、スキャンや隔離のフローは含まれていません。コンテンツモデレーションとマルウェアスキャンには、それぞれ別個の受け入れルールが必要です。
Mux Robots と AI ワークフロー Mux Robots は、キャプション、要約、チャプター、モデレーションを含むホスト型 AI ワークフローを提供します。Directives は、ワークフローの順序付けや、アセット準備完了時のトリガーに使用できます。アプリケーションで使っているジョブ、依存関係、出力、モデレーション判断を棚卸ししてください。上記のエンコード Template は、それらのワークフローの置き換えにはなりません。各置き換え候補について、言語、スキーマ、精度、しきい値、コストをテストするまでは、既存の出力と自動化を維持してください。Transloadit Template では処理 Step を検査可能にできますが、AI 予測が決定論的になるわけではありません。Template の改訂、Assembly ID、失敗、エクスポートパスを追跡し、パイロットで費用を測定し、それに応じてバックフィルバッチに上限を設けてください。切り替え前に、処理リージョン、保存リージョン、コンプライアンス要件をチームで確認してください。
工数の目安計画上の目安として、公開向けオンデマンド動画連携では 2 ~ 5 エンジニアリング日を見込んでください。前提は、開発者がオリジナルファイル、S3/CDN 配信、互換性のある HLS プレーヤーをすでに用意していることです。これには、Template、アップロード/署名フロー、通知ハンドラー、パイロットカタログの切り替えが含まれますが、大量転送時間は含みません。Mux のみが保持する master、非公開再生、CMS 変更、キャプション、代替音声、AI ワークフローには追加作業が必要です。代表的なファイルでインポート、エンコード、エクスポートのスループットを測定し、バックフィル全体に必要な期間を見積もってください。
- 動画を事前エンコードするか、オンデマンドエンコードにするかを決める
- ソースファイル、asset/playback ID、公開範囲、トラック、メタデータ、URL オプション、自動化を棚卸しする
- 必要なレンディション、サムネイル、エクスポートに対応する Template を作成してテストする。テキストトラックのパッケージ化は別途計画する
- ストレージ認証情報、CDN アクセス、HLS 再生向け CORS、必要に応じた非公開配信制御を設定する
- パイロット向けにアップローダーと Webhook 連携を置き換え、ロールバック用に旧配信マッピングを保持する
- 範囲を限定したバッチでバックフィルし、各マッピングを公開する前に、動画の再生時間、解像度、再生、ポスター、権限、カタログ件数を比較する
- アプリケーションと CMS のレコードを、エクスポート済みマニフェストまたは Smart CDN URL に更新する。管理下のドメイン上の URL については、そこでリダイレクトを設定してテストし、アプリケーション内の Mux ホスト URL 参照も更新する
- 埋め込みプレーヤー、ブックマーク、キャプション、CDN セグメントリクエストを確認してから展開範囲を広げる。ロールバック可能期間とキャッシュ寿命が過ぎるまでは旧アセットを利用可能な状態に保つ