動画を HLS、MPEG-Dash、CMAF に変換
🤖/video/adaptive は、動画を HTTP Live Streaming(HLS)、MPEG-Dash、CMAF に対応した形式にエンコードし、必要なマニフェストファイルとプレイリストファイルを生成します。

この Robot は、あらゆる種類の動画ファイルと音声ファイルを受け付けます。複数の入力ファイルをまとめて処理するには、use パラメーターで
Step のバンドルを忘れずに使用してください。これにより、この Robot が複数の入力ファイルを一度に処理します。
この Robot は通常、🤖/video/encode と組み合わせて使用します。MPEG-Dash と HTTP Live Streaming に対応する専用の動画・音声エンコードプリセットを用意しています。これらのプリセットには、"dash/" または "hls/"
というプレフィックスが付きます。HTTP Live Streaming の動作デモはこちら (English)。
HLS の字幕
"technique": "hls" では、各入力の最初の埋め込み字幕トラックが分割された WebVTT に変換され、マスタープレイリストからリンクされます。同じ入力内の残りの字幕トラックは破棄されます。いずれかの入力に複数の字幕トラックが含まれている場合、Assembly に警告が追加されます。
パッケージ化の前にトラックを追加するには、🤖/video/subtitle で "subtitles_type": "external"、"preset": "empty"、および "eng" などの
language を使用します。その後、"hls/" プリセットでエンコードし、エンコード済みの動画をこの Robot に渡します。デフォルトでは、プレイリストの字幕の
NAME には「English」など、その言語の英語名が使われ、LANGUAGE には入力の言語タグが保持されます。認識されない言語コードは、そのまま名前として使われます。言語が指定されていない場合、または "und" の場合、名前は「Unknown」になります。カスタムの ffmpeg.var_stream_map マッピングでは、字幕ラベルはそのマッピングで決まります。
カスタムの ffmpeg.var_stream_map で字幕名を明示的に設定するには、"ffmpeg_stack": "v8.0.0" を選択し、その sname オプションを使用します。
WebVTT キューと MPEG-TS 動画は、同じタイムスタンプのタイムラインを使用します。AAC のプライミングや動画フレームの並べ替えにより、両方の開始時刻がゼロより後になる場合があります。そのため、最初のキューのタイムスタンプがゼロよりわずかに大きいだけでは、字幕が遅れているとは限りません。字幕と動画の同期を維持するため、生成されたタイムスタンプを保持してください。HLS Step へのいずれかの入力に字幕がある場合、ffmpeg.muxdelay のデフォルト値は、字幕のないレンディションも含めた Step 全体で 0 になります。この値や他のタイムスタンプオプションを上書きすると、同期が変わる場合があります。
以下の説明に従って ${file.meta.relative_path} を保持し、WebVTT セグメントと字幕プレイリストを他のすべての結果とともに保存してください。
CMAF のアスペクト比
CMAF は、最大のレンディションとの差が 1% 以内である、ほぼ等しいアスペクト比のレンディションを、再エンコードやピクセル寸法の変更なしで揃えます。これにより、"hls/480p" や "hls/720p" などのプリセットを組み合わせてビットレートを切り替えられます。
4:3 と 16:9 のようにアスペクト比が大きく異なるレンディションは、別々の動画グループでそれぞれの形状を維持します。DASH プレーヤーはこれらのグループ間でビットレートを切り替えられないため、Assembly に警告が表示されます。HLS では引き続きすべてのビットレートバリアントが一覧に含まれます。カスタムの FFmpeg オプションで動画の形状やレイアウトを変更する場合は、レンディションのアスペクト比を揃えてください。
セグメント境界の整列
HLS と CMAF の動画セグメントは既存のキーフレームで分割されるため、実際の長さが segment_duration を超える場合があります。レンディションを 4 秒のセグメントに揃えるには、先行する各
🤖/video/encode Step で
"ffmpeg": { "force_key_frames": "expr:gte(t,n_forced*4)" } を設定します。4 を選択したセグメント長に置き換え、すべてのレンディションで同じ値を使用してください。キーフレーム間隔はエンコード時に設定してください。パッケージ化では、コピーされたストリームにキーフレームを追加できません。
MPEG-Dash と HTTP Live Streaming に必要な CORS 設定
MPEG-Dash マニフェストや HLS プレイリストファイルを再生するには、サーバー側で適切な CORS 設定が必要です。ファイルを配信するサーバーでは、レスポンスに次のヘッダーフィールドを追加するように設定してください。
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: *
ファイルを Amazon S3 バケットに保存している場合は、次の CORS 定義 を使用して、CORS ヘッダーフィールドを正しく設定できます。
[
{
"AllowedHeaders": ["*"],
"AllowedMethods": ["GET"],
"AllowedOrigins": ["*"],
"ExposeHeaders": []
}
]
S3 バケットの CORS を設定する手順は次のとおりです。
- https://s3.console.aws.amazon.com/s3/buckets/ にアクセスします
- 対象のバケットをクリックします
- 「Permissions」をクリックします
- 「Cross-origin resource sharing (CORS)」を編集します
セグメントとプレイリストファイルの保存
この Robot は、結果ファイル(セグメント、初期化セグメント、MPD マニフェストファイル、M3U8 プレイリストファイル)に適切なメタデータプロパティ relative_path を設定します。そのため、ストレージ用の Robot のいずれかを使って簡単に保存できます。
使用するストレージ用の
Robot の path パラメーターで、Assembly Variable として
${file.meta.relative_path} を使用してください。これにより、プレイリストファイルが機能する適切なパスにファイルを保存できます。
使用例
HTTP Live Streaming の実装例です。アップロードされた動画を三つのバージョンにエンコードし、それぞれを複数のセグメントに分割して、すべてのセグメントを含むプレイリストファイルを生成します:
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"encoded_1080p": {
"ffmpeg_stack": "v7",
"preset": "hls/1080p",
"robot": "/video/encode",
"use": ":original"
},
"encoded_480p": {
"ffmpeg_stack": "v7",
"preset": "hls/480p",
"robot": "/video/encode",
"use": ":original"
},
"encoded_720p": {
"ffmpeg_stack": "v7",
"preset": "hls/720p",
"robot": "/video/encode",
"use": ":original"
},
"hls_bundled": {
"playlist_name": "my_playlist.m3u8",
"robot": "/video/adaptive",
"technique": "hls",
"use": {
"bundle_steps": true,
"steps": [
"encoded_480p",
"encoded_720p",
"encoded_1080p"
]
}
}
}
}パラメーター
interpolateboolean | Record<string, boolean>処理設定の各フィールドで Assembly Variables を展開するかどうかを制御します。
デフォルトでは、Robot の処理設定のほとんどのフィールドで Assembly Variables が展開されます。すべての設定フィールドをリテラルテキストとして扱うには、このパラメーターを
falseに設定してください。特定のフィールドだけをリテラルテキストとして扱うには、そのフィールドのパスをfalseに設定してください。デフォルトでリテラルとして扱われる Robot 固有のフィールドで展開を有効にするには、このパラメーターをtrueに設定するか、そのフィールドのパスをtrueに設定してください。pathのようなフィールド名を使用してください。ネストされたオブジェクトには、ffmpeg.vfのようなドット区切りのパスを使用してください。output_metaRecord<string, boolean> | boolean | Array<string>算出に多くの CPU リソースを要するメタデータを指定できます。Assembly の処理速度を維持するため、これらはデフォルトで無効になっています。
画像の場合、このオブジェクトに
"has_transparency": trueを追加すると、画像に透明な部分が含まれるかどうかを抽出できます。"dominant_colors": trueを追加すると、画像から 16 進数のカラーコードの配列を抽出できます。画像の場合、
"blurhash": trueを追加すると、画像のプレースホルダーをコンパクトに表す BlurHash 文字列も抽出できます。画像全体の読み込み中に、ぼかしたプレビューを表示するのに役立ちます。画像の場合、代わりに
"thumbhash": trueを使用すると、base64 エンコードされた ThumbHash をmeta.thumbhashに抽出し、meta.has_alpha(完全に不透明な場合も含め、アルファチャンネルが存在するかどうか)も抽出します。ThumbHash は EXIF の向きを反映したピクセルを表し、アニメーション画像では最初のフレームを使用します。抽出はベストエフォートです。40 メガピクセルを超える画像、非対応の形式、デコードの失敗やデコード処理の上限への到達があった場合、プレースホルダーは生成されません。抽出に成功すると、そのファイルのバイト数の 20% に相当するメタデータ料金が加算されます。無効な場合やハッシュが生成されない場合、ThumbHash の追加料金は発生しません。このオプションは画像を生成する Step に設定してください。たとえば、アップロードされた元画像では
/upload/handle、処理済みの出力では/image/resizeに設定します。/transloadit/storeにのみ設定しても、抽出は要求されません。ストレージは生成元のメタデータを保持します。Transloadit Storage は生成されたハッシュをその不変のバージョンとともに永続化し、保存済みの結果やネイティブのアセット読み取り時に返します。S3 への直接アップロードではプレースホルダーは生成されません。プレースホルダーには画像情報が含まれるため、画像全体と同じアクセス制御で保護してください。動画の場合、
"colorspace": trueパラメーターを追加すると、出力動画の色空間を抽出できます。動画の場合、
"interlaced": trueを追加すると、インターレース動画かどうかも検出できます。これは、低コストの ffprobe のfield_orderフラグと、ソースの先頭フレームに対する処理範囲を制限したidetサンプリング処理を組み合わせ、file.metaの下にinterlaced、field_order、診断用のinterlace_detectionオブジェクトを出力します。この処理は計算コストが高く、それに応じて課金されます。音声の場合、
"mean_volume": trueを追加すると、音声ファイルの平均音量を表す単一の値を取得できます。また、
falseに設定すると、メタデータの抽出をスキップしてトランスコードを高速化できます。user_metaRecord<string, any>(デフォルト:{})出力される各ファイルに、ファイルの内容を変更せずにカスタム JSON メタデータを追加します。ネストしたオブジェクトと配列に対応しています。
継承の動作は Robot によって異なります。値は出力ファイルの既存の
user_metaとマージされ、一致するトップレベルのキーは現在の Step によって置き換えられます。Robot が新しい出力を作成する場合は、必要なキーを明示的に割り当ててください。処理 Step では、
${file.*}は最初の入力を、${result.*}は出力されるファイルを参照します。値は Robot の実行後、後続のメタデータ抽出と一時保存の前に、出力ごとに評価されます。:originalでは、メタデータ抽出の前にアップロードごとに値が評価されます。後続の Step は
${file.user_meta.key}を読み取ります。完全な例と継承ルールについては、カスタムメタデータ を参照してください。resultboolean(デフォルト:false)この Step の結果を Assembly Status JSON に含めるかどうか
queuebatchqueue を 'batch' に設定すると、このステップのジョブの優先度を手動で下げ、キューの待ち時間がゼロである必要のないジョブが優先ジョブスロットを消費しないようにします。
force_acceptboolean(デフォルト:false)通常は無視するファイルタイプを Robot に強制的に受け入れさせます。
デフォルトでは、Robot は認識できないファイルを無視します。たとえば、🤖/video/encodeは入力画像を無視します。
force_acceptパラメーターをtrueに設定すると、Robot に渡されたすべてのファイルを強制的に受け入れさせることができます。通常、この設定はエラーにつながるため、デバッグやエッジケースへの対処にのみ使用してください。ignore_errorsboolean | Array<meta | execute>(デフォルト:[])処理の特定のフェーズでエラーを無視します。
このパラメーターを
["meta"]に設定すると、Robot はメタデータ抽出中のエラーを無視します。このパラメーターを
["execute"]に設定すると、Robot はメイン実行フェーズ中のエラーを無視します。このパラメーターを
trueに設定すると、["meta", "execute"]と同じ動作になり、両方のフェーズでエラーを無視します。usestring | Array<string> | Array<object> | object入力として使用する Step を指定します。
- Step には任意の名前を付けられます。ただし、
":original"は Transloadit が処理するユーザーアップロード用に予約されています。 - 配列を使用して、複数の Step を入力として指定できます。
{ "use": [ ":original", "encoded", "resized" ] } - 入力 Step に
asでタグを付けて、意味上の用途を Robot に伝えることもできます。{ "use": [ { "name": ":original", "as": "image" }, { "name": ":original", "as": "mask" } ] }
ヒントuseについては、通常ここまでの内容で十分ですが、高度な使用例 も参照できます。- Step には任意の名前を付けられます。ただし、
ffmpegobject"hls"方式と"cmaf"方式では、カスタム FFmpeg オプションを使用できます。デフォルトの方式である"dash"では、空でないカスタムオプションは拒否されます。これらのオプションはパッケージングコマンドに適用されます。このコマンドは、デフォルトで入力ストリームをコピーします。キーフレーム間隔などのエンコードオプションは、先行する 🤖/video/encode の Step で設定してください。
ffmpeg_stackv6 | v7 | v8 | string(デフォルト:"v7.0.0")パッケージングに使用する FFmpeg スタックを選択します。デフォルトは
"v7.0.0"です。この Robot は常に"v7.0.0"以上を使用し、それより古いスタックを選択した場合は自動的にアップグレードされます。widthstring | number | nullこのパラメーターは、この Robot では効果がありません。レンディションの幅は、先行する 🤖/video/encode の Step で設定してください。
heightstring | number | nullこのパラメーターは、この Robot では効果がありません。レンディションの高さは、先行する 🤖/video/encode の Step で設定してください。
presetandroid | android-high | android-low | android_high | android_low | dash-1080p-video | dash-1080p_video |このパラメーターは、この Robot では効果がありません。エンコードプリセットは、先行する 🤖/video/encode の Step で設定してください。
techniquedash | hls | cmaf(デフォルト:"dash")使用するストリーミング方式を指定します。MPEG-Dash には
"dash"、HTTP Live Streaming には"hls"を使用できます。"cmaf"では、FFmpeg ベースの CMAF 出力を生成し、同じ fMP4 セグメントを参照する MPEG-Dash と HLS の両方のマニフェストを出力します。playlist_namestring生成されるマニフェスト/プレイリストファイルのファイル名です。デフォルトは、
techniqueが"dash"の場合は"playlist.mpd"、techniqueが"hls"の場合は"playlist.m3u8"です。"cmaf"の場合、この値は MPEG-Dash マニフェストの名前を指定し、デフォルトは"playlist.mpd"です。hls_playlist_namestringtechniqueが"cmaf"の場合にのみ使用されます。生成される HLS マスタープレイリストのファイル名を指定します。デフォルトは"playlist.m3u8"です。segment_durationstring | number各セグメントの長さを秒単位で指定します。省略した場合、MPEG-Dash と CMAF では 4 秒、HLS では 10 秒になります。
closed_captionsboolean(デフォルト:true)"hls"方式を使用する際に、クローズドキャプションのサポートを有効にするかどうかを指定します。audio_groupboolean(デフォルト:false)trueに設定し、"hls"方式を使用すると、音声のみの入力ファイルは独立したストリームのビットレート別バリアントではなく、切り替え用の音声レンディションとして扱われます。これにより、プレーヤーで音声トラックを選択できます(複数言語の切り替えなど)。音声のみのファイルはマルチバリアントプレイリストに#EXT-X-MEDIA:TYPE=AUDIOエントリーとして記載され、動画バリアントからAUDIO属性で参照されます。有効にすると、動画入力からは映像ストリームのみが出力セグメントに含まれます(多重化された音声はすべて除外されます)。音声は、音声のみの入力ファイルとして別途指定してください。
各レンディションの
LANGUAGEには、対応する音声のみの入力ファイルにある最初の音声ストリームのlanguageタグが使用されます。タグがない場合は"und"になります。たとえば、🤖/audio/encode で"ffmpeg": {"metadata:s:a:0": "language=deu"}を使用してタグを設定できます。use.steps順で最初の音声のみの入力にはDEFAULT=YESが設定され、その他のレンディションにはDEFAULT=NOが設定されます。すべての音声レンディションにAUTOSELECT=YESが設定されます。各レンディションのNAMEには、音声ストリームにtitleタグがあればその値が使用され、なければ言語の英語名が使用されます(たとえば、"eng"は「English」、"deu"は「German」になります)。タグのない音声の名前は「Unknown」になり、認識されない言語コードはそのまま名前として使用されます。名前が重複する場合は、末尾に数字が追加されます。このオプションで切り替え用の音声レンディションを有効にできるのは
"hls"方式のみで、"dash"または"cmaf"のパッケージングは変わりません。CMAF では、すべての音声が一つのアダプテーションセットにまとめられ、最初の音声の言語がラベルとして付けられます。CMAF でaudio_group: trueを設定した場合、または既知の音声言語を複数含む CMAF 入力を指定した場合(単一の動画に多重化されたトラックを含む)、Assembly に警告が追加されますが、既存の CMAF 出力でパッケージングが続行されます。多言語音声には、technique: "hls"とaudio_group: trueを使用してください。