動画のトランスコード・リサイズ・透かし追加
🤖/video/encode は、動画やアニメーション GIF のエンコード、リサイズ、透かしの追加を行います。

Robot /video/encode は、トランスコード、リサイズ、透かしの追加に対応する汎用性の高い動画処理ツールです。HEVC(H.265)などの最新規格を含むさまざまな形式に対応し、一般的なデバイス向けのプリセット、上級ユーザー向けのカスタム FFmpeg パラメーター、透かしの位置指定などの機能を備えています。
iPhone の空間オーディオ
iPhone の空間オーディオで録画した動画には、ステレオ AAC トラックと Apple Positional Audio Codec(APAC)トラックが含まれる場合があります。未対応の音声が含まれている場合、この Robot はデフォルトで対応している音声トラックを一つ保持します。空間オーディオは保持も変換もされません。
未対応の音声のみを含むファイルは、引き続き処理に失敗します。個別の音声トラック選択やストリームコピーを指定した場合は、選択したトラックを保持します。出力形式は、コピーするトラックに対応している必要があります。
HLG または PQ HDR 動画に透かしを追加したり、drawtext などのシンプルな FFmpeg 動画フィルターで描画したりする場合、描画前に動画を SDR BT.709 にトーンマッピングします。これにより、オーバーレイの色は意図した RGB 値を保持します。SDR 入力の処理は従来どおりです。トーンマッピングを指定するカスタム ffmpeg.pre:filter:v は、独自に色変換を制御します。複数の入力を扱うカスタム filter_complex グラフでは、各入力の色空間を明示的に処理する必要があります。
FFmpeg によるテキストオーバーレイの追加
この Robot の ffmpeg パラメーターで FFmpeg の drawtext フィルターを使用すると、動画にテキストオーバーレイを追加できます。以下に、デフォルトのフォントを使う例と、カスタムのフォントファミリー名を指定する例の二つを示します。
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"text_overlay_default": {
"use": ":original",
"robot": "/video/encode",
"preset": "empty",
"ffmpeg_stack": "v7",
"ffmpeg": {
"codec:a": "copy",
"vf": "drawtext=text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
},
"result": true
},
"text_overlay_custom": {
"use": ":original",
"robot": "/video/encode",
"preset": "empty",
"ffmpeg_stack": "v7",
"ffmpeg": {
"codec:a": "copy",
"vf": "drawtext=font='Times New Roman':text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
},
"result": true
}
}
}
注意事項:
- FFmpeg の
drawtextでフォントをファミリー名で参照するには、font属性を使用してください。 - FFmpeg のフォントファミリー名には通常ハイフンが含まれません(例:
Times New Roman)。一方、ImageMagick ではハイフンを含む名前を使用します(例:Times-New-Roman)。 textfileやfontfileなど、ファイルを読み込むdrawtextオプションには対応していません。代わりに、インラインのtextとフォントファミリー名を使用してください。- 元の音声を保持するには、
"codec:a": "copy"を設定してください。 - テキストの位置は
xとyの式で指定してください。上記の例ではテキストを中央に配置しています。
テキストオーバーレイの実行可能なデモ (English)をご覧ください。
使用例
アップロードされた動画を HEVC(H.265)にトランスコードします:
{
"steps": {
"hevc_encoded": {
"preset": "hevc",
"robot": "/video/encode",
"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'を使用できます。resize_strategycrop | fit | fillcrop | min_fit | pad | stretch(デフォルト:"pad")利用可能なリサイズ方式をご覧ください。
zoomboolean(デフォルト:true)falseに設定すると、小さい動画を指定の幅と高さに引き伸ばしません。選択したリサイズ方式での拡大の影響については、利用可能なリサイズ方式の一覧を参照してください。cropobject | string元の動画から切り抜く矩形の左上と右下の座標を含むオブジェクトを指定してください。値には、絶対ピクセル値を表す整数、または割合を表す文字列を使用できます。
例:
{ "x1": 80, "y1": 100, "x2": "60%", "y2": "80%" }この例では、1000×1000 ピクセルの動画から、
(80, 100)から(600, 800)までの領域を切り抜きます。この矩形の幅は 520px、高さは 700px です。cropが設定されている場合、幅と高さのパラメーターは無視され、resize_strategyは自動的にcropに設定されます。同様に、座標を含むオブジェクトを JSON 文字列として指定することもできます。
"{\"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer>}"backgroundstring(デフォルト:"#00000000")"pad"のリサイズ方式を使用する場合の、出力動画の背景色です。"rrggbbaa"形式(赤、緑、青、アルファ)で指定します。デフォルトの色は黒です。rotate0 | 90 | 180 | 270 | 360 | false整数で指定した角度だけ動画を強制的に回転します。現在は
90の倍数のみ対応しています。カメラから向きの情報が提供されている多くの動画では、向きを自動補正します。このオプションは、カメラが向きを検出しなかったために回転が必要な動画にのみ有用です。rotateをfalseに設定すると、メタデータに回転の指示が含まれていても回転しません。hintboolean(デフォルト:false)RTP/RTSP ストリーミング用に、mp4 ファイルのヒンティングを有効にします。
turboboolean(デフォルト:false)動画を複数のチャンクに分割し、各チャンクを並列にエンコードしてから、すべてを結合して出力動画を作成します。ただし、追加の Priority Job Slots を消費するため、非常に小さい動画ファイルではかえって効率が下がる場合があります。各動画は最大 30 個のチャンクに分割されるため、長い動画ほどチャンクも長くなります。
VP8 出力と未解決の動画コーデック式では、
turboがtrueでも通常のエンコードを使用します。chunk_durationstring | numberturboがtrueに設定されている場合に、各チャンクの長さを指定できます。これにより、使用する Priority Job Slots を減らしながら、その機能を利用できます。たとえば、各チャンクを長くするほど、必要な Encoding Jobs は少なくなります。指定した長さが 5 秒未満の場合は、5 秒として扱われます。長い動画では、各動画の分割数が最大 30 個になるようにチャンクが長くなります。
watermark_url"" | string(デフォルト:"")この画像の上に重ねる PNG 画像の URL です。別の Assembly Step から透かしを渡すこともできます。
watermark_positionbottom | bottom-left | bottom-right | center | left | right | top | | Array<bottom | bottom-left | bottom-right | center | left | right | top | >(デフォルト:"center")透かしを配置する位置です。
[ "center", "left", "bottom-left", "bottom-right" ]のように候補の値を配列で指定することもできます。その場合、いずれかの値がランダムに選択されます。この設定では、指定した隅にウォーターマークを配置します。ウォーターマークの位置を特定のピクセル数だけずらすには、画像自体にパディングを追加する必要があります。
watermark_x_offsetstring | number(デフォルト:0)watermark_positionで決まる配置位置を基準に、ウォーターマークを x 方向にずらすピクセル数です。正の値と負の値を指定でき、結果は
watermark_positionパラメーターによって異なります。正の値では透かしが画像の中心に近づき、負の値では中心から遠ざかります。watermark_y_offsetstring | number(デフォルト:0)watermark_positionで決まる位置を基準に、透かしを配置する y 方向のオフセットをピクセル数で指定します。正の値と負の値を指定でき、結果は
watermark_positionパラメーターによって異なります。正の値では透かしが画像の中心に近づき、負の値では中心から遠ざかります。watermark_sizestring"50%"のように、透かしのサイズを割合で指定します。透かしのリサイズ方法はwatermark_resize_strategyに大きく依存します。watermark_resize_strategyarea | fit | stretch(デフォルト:"fit")リサイズ方式の動作を説明するため、出力動画のサイズを 800×800 ピクセル、透かし画像のサイズを 400×300 ピクセルとします。また、
watermark_sizeパラメーターは"25%"に設定されているとします。"fit"リサイズ方式では、透かしの長辺が、動画の対応する辺の 25% を占めるように拡大縮小します。もう一方の辺は、透かし画像のアスペクト比に従って拡大縮小します。この例では透かしの幅が長辺で、動画サイズの 25% は 200px になります。したがって、透かしは 200×150 ピクセルにリサイズされます。watermark_sizeが"50%"に設定されている場合は、400×300 ピクセルになります(つまり、元のサイズのままです)。"stretch"リサイズ方式では、透かし画像の両辺がそれぞれ動画の対応する辺の 25% を占めるように引き伸ばします(アスペクト比を維持せずにリサイズします)。この例では動画が 800×800 ピクセルなので、透かしのサイズが 25% の場合、透かしは 200×200 ピクセルにリサイズされます。アスペクト比を維持する場合は 200×150 ピクセルになるため、高さ方向に引き伸ばされたように見えます。"area"リサイズ方式では、動画の面積の"xx%"を覆うように、アスペクト比を維持して透かしをリサイズします。面積の割合にはwatermark_sizeの値を使用します。watermark_start_timestring | number(デフォルト:0)動画の開始から透かしが表示されるまでの遅延時間(秒)です。デフォルトでは、透かしをすぐに表示します。
watermark_durationstring | number(デフォルト:-1)透かしを表示する時間(秒)です。
watermark_start_timeと組み合わせると、効果的な演出ができます。デフォルト値は-1.0で、動画の全編にわたって透かしを表示します。watermark_opacitystring | number(デフォルト:1)透かしの不透明度です。有効な値の範囲は
0(非表示)から1.0(完全に表示)までです。segmentboolean(デフォルト:false)Apple の HTTP Live Streamingで使用するために、ファイルを複数の部分に分割します。
segment_durationstring | number(デフォルト:10)各 HTTP セグメントの長さを指定します。指定は任意で、デフォルト値は Apple が推奨する
10です。明確な理由がない限り、この値は変更しないでください。segment_prefixstring(デフォルト:"")命名に使用する接頭辞です。たとえば、接頭辞を
"segment_"にすると、"segment_0.ts"、"segment_1.ts"などの名前でファイルが生成されます。指定は任意で、デフォルトは入力ファイルのベース名です。関連するsegment_nameパラメーターもご覧ください。segment_namestring(デフォルト:"")最終セグメントに使用する名前です。使用できる変数は
${segment_prefix}、${segment_number}、${segment_id}(ハイフンなしの UUIDv4)です。segment_time_deltastring | numberセグメントの長さに適用する差分です。指定は任意で、セグメントの境界を微調整できます。
デモ
- Service to generate a slideshow from AI-filtered images (English)
- Overlay videos with dynamic artwork generated with HTML & JS (English)
- Add text overlay to videos (English)
- Service to convert a GIF to a video (English)
- Service to frame video files using a watermark (English)
- Overlay a video on top of another video (English)
- Remove a green screen from a video (English)
- Service to automatically rotate a video (English)
- Video watermarking service (English)
関連ブログ記事
- iPhone 動画アップロードの自動回転機能をリリース
- リアルタイムエンコード - 150 倍以上の高速化
- Transloadit、透かし挿入に対応した WebM サポートを発表
- 音声エンコード Robot の正式リリースと注目の更新情報
- スケーリング強化による安定性とパフォーマンスの向上
- エンコーディング性能を高める FFmpeg の改良
- アダプティブストリーミング向け MPEG-DASH 対応のご紹介
- 今後の Transloadit のお客様向け新料金モデル
- Transloadit、動画エンコードを高速化する Turbo Mode を公開
- Transloaditで動画に透かしを入れる方法
- Transloadit でストリーミング用動画をエンコードするガイド
- FFmpeg と Node.js で音声波形動画を作成する
- Let's Build: 回転するレコードの GIF ジェネレーター
- Build a Reddit video subtitling bot with Transloadit (English)
- Transloadit で魅力的な音声ビジュアライゼーションを作成
- 高度な圧縮による動画品質の最適化
- FFmpeg でグリーンスクリーンを除去:動画のクロマキー処理
- MKV と MP4:どちらの動画形式が優れている?
- Three.js で 360° 動画プレーヤーを作成
- オンデマンド動画エンコーディングでコスト削減
- 動画機能の新情報:トランジション、チャプター、CMAF など