動画への字幕追加
🤖/video/subtitle は、動画に字幕とクローズドキャプションを追加します。

この Robot は、SRT、VTT、ASS、および /speech/transcribe で "format": "json" を使用した場合のタイムスタンプ付き JSON 出力に対応しています。use パラメーターで、動画を "video" として、文字起こしを "subtitles" として渡してください。JSON 内の単語はキャプションにまとめられ、焼き込み字幕で単語をハイライトする場合は ASS に、外部字幕ストリームの場合は通常の SRT キューに変換されます。JSON から生成した外部字幕のキューでは、大文字・小文字と句読点が保持されます。プロバイダーのセグメントはキャプションの区切りを制御しません。SRT と VTT のタイミングは保持されます。
preset またはカスタムの ffmpeg オプションを指定しない場合、従来の "flash" プリセットは FLV を出力します。このデフォルト設定では、焼き込み字幕には MP3 オーディオを使用し、外部字幕では入力オーディオをコピーします。MP4 入力に対して MP4 を使用するなど、入力コンテナを保持するには、"preset": "empty" を設定してください。
HLG または PQ HDR 動画に字幕を焼き込む場合、キャプションの描画前に動画を SDR BT.709 にトーンマッピングします。キャプションの色は意図した RGB 値を保持し、出力には SDR のタグが付けられます。外部字幕では、ソース動画の HDR カラーが保持されます。SDR 入力の既存の処理は変わりません。ffmpeg.pre:filter:v で独自のトーンマッピングを指定した場合は、そのフィルターが色変換を制御します。
使用例
アップロードされた動画を単語ごとのタイムスタンプ付きで文字起こしし、発話中の単語を強調表示する大文字のソーシャルメディア向け字幕を焼き込みます。字幕は通常、最大三単語で構成され、文末や 0.4 秒を超える間で区切られます。ソーシャルメディア向けのフレーズ分割では、短いフレーズをまとめるため、または文末の単語が一つだけ孤立するのを避けるため、さらに一単語を含めることができます:
{
"steps": {
"captioned": {
"ffmpeg_stack": "v7",
"preset": "empty",
"robot": "/video/subtitle",
"style": "social",
"subtitles_type": "burned",
"use": {
"steps": [
{
"as": "video",
"name": ":original"
},
{
"as": "subtitles",
"name": "transcript"
}
]
}
},
"transcript": {
"format": "json",
"provider": "aws",
"robot": "/speech/transcribe",
"source_language": "en-US",
"use": ":original"
}
}
}パラメーター
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 には任意の名前を付けられます。ただし、
ffmpegobjectFFmpeg に渡すパラメーターオブジェクトです。プリセットを使用する場合、ここで指定したオプションがプリセットのオプションに上書きマージされます。利用可能なオプションは、FFmpeg ドキュメントを参照してください。ここで指定したオプションは、プリセットのオプションよりも優先されます。
ffmpeg_stackv6 | v7 | v8 | string(デフォルト:"v6.0.0")エンコードに使用する FFmpeg スタックのバージョンを選択します。現在は「v7」の使用を推奨しています。「v6.0.0」、「v7.0.0」、「v8.0.0」という正確なバージョン指定は、後方互換性のために引き続き受け付けられるレガシー値です。非推奨の「v5.x」の値も受け付けられます。
widthstring | number | null新しい動画の幅(ピクセル単位)です。
値が指定されておらず、
presetパラメーターが利用できる場合は、presetで指定されている幅 が適用されます。heightstring | number | null新しい動画の高さ(ピクセル単位)です。
値が指定されておらず、
presetパラメーターが利用できる場合は、presetで指定されている高さ が適用されます。presetandroid | android-high | android-low | android_high | android_low | dash-1080p-video | dash-1080p_video |事前設定済みの設定 に従って動画を変換します。
Robot を使用して独自の FFmpeg パラメーターを指定する場合や、Transloadit にエンコード設定を一切行わせたくない場合は、ここで
'empty'を使用できます。subtitles_typeburned | external | burn(デフォルト:"external")字幕を別のストリームとして動画に追加し、動画プレーヤーで表示と非表示を切り替えられるようにするか(値
"external")、動画に直接焼き込んで動画ストリームの一部にするか(値"burned"または"burn")を指定します。stylesocial焼き込み字幕に、太い Poppins の文字、太い縁取り、柔らかい黒の影を組み合わせた既成の外観を適用します。JSON 字幕は画面下部の三分の一の領域に大文字で表示されます。デフォルトでは、動画の短辺を基準に JSON 字幕のフォントサイズを決め、各字幕を安全な表示幅内に収めます。一行を優先し、最大でも二行に収めます。単語の途中では分割しません。各字幕は 120 ミリ秒かけて 85% から本来のサイズまで拡大し、その後は単語の位置を固定したままハイライトの色が変わります。文字起こしファイルは保持されます。既存のスタイル設定パラメーターはプリセットより優先されます。
font_sizeを明示的に指定すると、自動サイズ調整が無効になります。ASS ファイルは独自のスタイルを保持します。/speech/transcribeからのタイムスタンプ付き JSON では、現在の単語が次の単語または字幕の開始まで強調表示され、ほかの単語にはfont_colorが使用されます。ソーシャル向け JSON 字幕では末尾のコンマとピリオドを省略し、疑問符と感嘆符は保持します。単語の強調表示とグループ化には JSON 入力が必要です。highlight_colorstring | string(デフォルト:"FFD60A")JSON 字幕で現在の単語に使用するアクセントカラーです。焼き込みの JSON 字幕にのみ適用されます。
"style": "social"を使用する場合、短い空白区間では、次の単語またはキャプションが始まるまで直前の単語のハイライトが維持されます。ソーシャルスタイルを使用しない場合、空白区間ではキャプション全体にfont_colorを使用します。"rgb"、"rrggbb"、または"aarrggbb"形式を使用してください。先頭に#を付けることもできます。三桁の色は六桁に展開されます。アルファ値のない色は完全に不透明です。八桁の色では、先頭の二桁で透明度を指定します("00"は完全に不透明、"ff"は完全に透明です)。speaker_colorsArray<string | string>/speech/transcribeからspeaker_labelsを使用して生成する焼き込み JSON 字幕の、話者ごとのアクセントカラーです。最初の色はspeaker_1、二番目の色はspeaker_2を強調表示し、以降も同様に割り当てます。話者数が色の数を超えると、先頭の色から繰り返します。話者が指定されていない単語にはhighlight_colorを使用します。話者が変わると、必ず字幕を区切ります。max_words_per_captionstring | number(デフォルト:3)一つのキャプションに表示するタイムスタンプ付き JSON 単語数の上限の目安です。文末の句読点または 0.4 秒を超える間がある場合は、上限に達する前にキャプションを区切ります。
"style": "social"を使用する場合、末尾にある「by」「to」「the」などの英語の機能語を、可能であれば次のキャプションに移します。「line of code」などの短い句はまとめて保持でき、文末の単独の単語は前のキャプションに結合できます。これらの調整では、文末や長い間をまたぐことなく、キャプションごとに最大一語の追加を許容します。上限が 1 の場合は、一語のキャプションを保持します。間が 0.4 秒以下の場合、キャプションは次のキャプションが始まるまで表示され、それより長い間がある場合は、最後の単語の終了時点で消えます。SRT、VTT、ASS のキューは変更しません。border_stylebox | outline | shadow(デフォルト:"outline")字幕のスタイルを指定します。縁取りの色は
border_colorパラメーターで指定してください。border_colorstring | string(デフォルト:"000000")字幕の縁取りの色です。デフォルトは不透明な黒です。焼き込み字幕にのみ適用されます。
"rgb"、"rrggbb"、または"aarrggbb"形式を使用してください。先頭に#を付けることもできます。三桁の色は六桁に展開されます。アルファ値のない色は完全に不透明です。八桁の色では、先頭の二桁で透明度を指定します("00"は完全に不透明、"ff"は完全に透明です)。fontstring使用するフォントファミリーです。フォントの太さとスタイルも含まれます。デフォルトは Arial です。
"style": "social"を使用する場合、デフォルトは Poppins で、JSON キャプションには ExtraBold ウェイトを使用します。フォントを明示的に指定すると、スタイルより優先されます。対応するすべてのフォントはこちらの一覧を参照してください。
font_colorstring | string(デフォルト:"FFFFFF")字幕テキストの色です。焼き込み字幕にのみ適用されます。
"rgb"、"rrggbb"、または"aarrggbb"形式を使用してください。先頭に#を付けることもできます。三桁の色は六桁に展開されます。アルファ値のない色は完全に不透明です。八桁の色では、先頭の二桁で透明度を指定します("00"は完全に不透明、"ff"は完全に透明です)。font_sizestring | number動画の高さに合わせてスケーリングされる、288 ピクセルの字幕座標空間でのテキストサイズを指定します。デフォルトは 16 です。
"style": "social"を使用する場合、デフォルトは 54 です。ソーシャルスタイルの JSON キャプションでは、値を省略すると、このデフォルト値を動画の短辺に合わせてスケーリングし、縦長動画では 18% 拡大し、最大二行に収まるよう必要に応じてキャプションを縮小します。収まるように調整する前の Poppins の大文字の高さは短辺の約 7.5% で、縦長動画では約 9% です。値を明示的に指定すると、高さに対する相対サイズが維持され、自動調整は無効になります。boldboolean字幕テキストを太字にするかどうかを指定します。焼き込み字幕にのみ適用されます。デフォルトは
falseです。"style": "social"を使用する場合、デフォルトはtrueです。falseを明示的に指定すると、スタイルより優先されます。italicboolean(デフォルト:false)字幕テキストを斜体にするかどうかを指定します。焼き込み字幕にのみ適用されます。
outline_widthstring | number | null動画の高さに合わせて拡大縮小される、288 ピクセルの字幕座標空間での文字の縁取り幅を指定します。
"4"のような数値文字列も受け付けます。境界線スタイルが"outline"または"box"の焼き込み字幕にのみ適用されます。省略した場合、またはnullの場合は、デフォルトの幅が使用されます("style": "social"では 2、ソーシャル向け JSON 字幕では最終的に調整されたフォントサイズに比例する幅)。positionbottom | bottom-left | bottom-right | center | left | right | top |(デフォルト:"bottom")字幕の位置を指定します。
"style": "social"では、デフォルトの下部位置で JSON 字幕を画面下部の三分の一の領域に配置し、縦向き動画では下端の余白を広く取ります。値を明示的に指定すると、スタイルの設定より優先されます。languagestring | null字幕ストリームの言語を三文字の言語コード(例:
"eng"、"deu"、"spa")で指定します。外部字幕の場合にのみ使用します。複数の字幕ストリームを追加する場合は、動画プレーヤーで言語を選択できるよう、ストリームごとに異なる言語を設定してください。namestring | null字幕トラックのわかりやすい名前(例:
"English"、"Deutsch"、"Español")を指定します。外部字幕の場合にのみ使用されます。この名前は、動画プレーヤーの字幕メニューで言語とともに表示されます。keep_subtitlesboolean(デフォルト:false)入力ファイル内の既存の字幕を保持するか、新しい字幕に置き換えるかを指定します。外部字幕の場合にのみ使用します。同じ動画に複数の字幕ストリーム(異なる言語など)を追加するために、
/video/subtitleを使用する複数の Step を連結する場合は、この値をtrueに設定してください。