プレビュー用サムネイルの生成
🤖/file/preview はアップロードされた任意のファイルに対して、内容をプレビューするためのサムネイルを生成します。デスクトップのファイルマネージャーに表示されるサムネイルと同様のものです。

この Robot は、あらゆるファイルに対して、その内容が伝わるサムネイルをプレビュー画像として生成することを目的としています。元のメディアを損失なく縮小して表示することが目的ではありません。見た目のよさと他のプレビューとの一貫性を保ちながら、メディアの内容をひと目で認識しやすくすることを目指しています。生成処理はファイルの種類によって異なります。たとえば、この Robot は、メディアファイルからのカバーアートの抽出、動画からのフレームの抽出、音声ファイルの波形生成、ドキュメントや画像の内容のプレビューに対応しています。strategy パラメーターには、利用できる戦略の一覧があり、フォールバックの順序を制御できます。
デフォルトの戦略設定では、ファイル固有のサムネイルを生成できない場合、汎用アイコンにフォールバックします。デフォルトの with-text アイコンスタイルにはファイル拡張子が含まれ、icon_style と icon_text_content で外観を制御します。
デフォルトのパラメーターでは、アプリケーションの UI に組み込めるよう、設定された寸法と形式で静止画プレビューを生成します。オプションの clip 戦略では、clip_format を使用してアニメーションプレビューを生成します。プレビュー画像はデフォルトで最適化され、見た目の品質を維持しながらファイルサイズを削減します。
使用例
アップロードされた任意のファイルのプレビュー用サムネイルを生成する例:
{
"steps": {
"previewed": {
"format": "png",
"height": 400,
"robot": "/file/preview",
"use": ":original",
"width": 300
}
}
}パラメーター
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 には任意の名前を付けられます。ただし、
formatavif | gif | jpeg | jpg | png | webp(デフォルト:"png")生成するサムネイル画像の出力形式です。
clip戦略を使用して短い動画クリップを生成する場合、その形式はclip_formatで定義されます。qualitystring | number静止画プレビューの圧縮品質を 1 から 100 の範囲で指定します。指定すると、最終的な画像のリサイズ時に、この品質で指定形式に直接エンコードし、埋め込みメタデータを削除します。デフォルトのエンコード動作を維持するには、このパラメーターを省略してください。アニメーションクリップでは独自のエンコード設定を使用します。
optimizeが有効な場合、このエンコードの後に最適化を実行します。widthnumber(デフォルト:300)サムネイルの幅をピクセル単位で指定します。
heightnumber(デフォルト:200)サムネイルの高さをピクセル単位で指定します。
resize_strategycrop | fit | fillcrop | min_fit | pad | stretch(デフォルト:"pad")プレビューサムネイルを指定のサイズにするために、Robot が生成画像をリサイズする必要がある場合があります。たとえば、動画から抽出したフレームのサイズが、選択した
widthパラメーターとheightパラメーターの値に一致しない場合です。詳細は、利用可能なリサイズストラテジーの一覧を参照してください。
backgroundstring(デフォルト:"#ffffffff")背景の塗りつぶしに使用する色の16進数コードです(pad リサイズ戦略でのみ使用されます)。形式は
#rrggbb[aa](赤、緑、青、アルファ)です。余白を透明にするには#00000000を使用してください。zoomboolean(デフォルト:true)falseに設定すると、小さい画像を指定のwidthとheightに合わせて拡大しません。元の画像の寸法を維持し、出力の最大サイズだけを制限したい場合に便利です。選択したリサイズストラテジーでの拡大の影響については、利用可能なリサイズストラテジーの一覧をご覧ください。このパラメーターは、静止画を生成するストラテジーにのみ影響します。
clipストラテジーで生成されるアニメーションクリップには影響しません。strategyobjectファイルカテゴリーごとのサムネイル生成処理の定義です。各キーでファイルカテゴリーを選択し、その値にはストラテジーを順番に並べた配列を指定します。
ファイルカテゴリー 利用可能なストラテジー audioartwork,waveform,iconvideoartwork,frame,clip,iconimageimage,embedded-preview,icondocumentpage,iconarchiveiconwebpagerender,iconunknowniconartworkは埋め込みカバーアートを抽出し、waveformは音声波形を描画し、frameは動画フレームを抽出し、clipはアニメーション付きの動画プレビューを作成します。画像の場合、imageは元の画像をリサイズし、embedded-previewは埋め込みプレビューがあれば抽出します。pageはドキュメントの最初のページを描画し、renderはウェブページをキャプチャし、iconはファイル形式を示すアイコンを生成します。各ファイルについて、Robot は最初のストラテジーでサムネイルの生成を試みます。この処理に失敗した場合(たとえば、動画ファイルにカバーアートがない場合)は、次のストラテジーを試します。サムネイルが生成されるか、一覧のすべてのストラテジーを試し終わるまで、この処理を繰り返します。最後の項目に
iconストラテジーを選択すると、適切なストラテジーを常に利用できるようにするフォールバックとして機能します。このパラメーターのデフォルトの定義は次のとおりです。
{ "archive": [ "icon" ], "audio": [ "artwork", "waveform", "icon" ], "document": [ "page", "icon" ], "image": [ "image", "embedded-preview", "icon" ], "unknown": [ "icon" ], "video": [ "artwork", "frame", "icon" ], "webpage": [ "render", "icon" ] }artwork_outer_colorstringカバーアートのグラデーションの外側に使用する色です。
artwork_center_colorstringカバーアートのグラデーションの中心に使用する色です。
waveform_center_colorstring(デフォルト:"#000000ff")波形のグラデーションの中央で使用する色です。形式は
#rrggbb[aa](赤、緑、青、アルファ)です。音声ファイルにwaveformストラテジーを適用した場合にのみ使用します。waveform_outer_colorstring(デフォルト:"#000000ff")波形のグラデーションの外側で使用する色です。形式は
#rrggbb[aa](赤、緑、青、アルファ)です。音声ファイルにwaveformストラテジーを適用した場合にのみ使用します。waveform_heightstring | number(デフォルト:100)波形の高さをピクセル単位で指定します。音声ファイルに
waveformストラテジーを適用した場合にのみ使用します。波形がプレビューサムネイルの一部の領域だけを占めるように調整できます。waveform_widthstring | number(デフォルト:300)波形の幅をピクセル単位で指定します。音声ファイルに
waveformストラテジーを適用した場合にのみ使用します。波形がプレビューサムネイルの一部の領域だけを占めるように調整できます。icon_stylesquare | with-text(デフォルト:"with-text")iconストラテジーを適用した場合に生成されるアイコンのスタイルです。デフォルトのwith-textスタイルには、ファイルの種類を示すアイコンと、その下にテキストボックスが含まれます。テキストボックスの内容はicon_text_contentパラメーターで指定でき、デフォルトではファイルの拡張子(MP4、JPEG など)が表示されます。squareスタイルには、ファイルの種類を示す正方形のアイコンのみが含まれます。以下は、それぞれのスタイルでテキストファイルから生成したプレビューの例です。
with-textスタイル:
squareスタイル:

icon_text_colorstring(デフォルト:"#a2a2a2")アイコン内のテキストの色です。形式は
#rrggbb[aa]です。iconストラテジーを適用した場合にのみ使用されます。icon_text_fontstring(デフォルト:"Roboto")アイコン内のテキストのフォントファミリーです。
iconストラテジーを適用した場合にのみ使用されます。対応するすべてのフォントはこちらの一覧で確認できます。icon_text_contentextension | none(デフォルト:"extension")生成されるアイコンのテキストボックスの内容です。
icon_styleパラメーターがwith-textに設定されている場合にのみ使用します。デフォルト値のextensionでは、ファイルの拡張子(例:MP4、JPEG)をアイコンに追加します。noneを指定すると、テキストボックスは空になりますが、独自のテキストを重ねて表示するための領域は確保されます。たとえば、アプリケーション内で HTML を使用してテキストを重ねられます。optimizeboolean(デフォルト:true)生成されるプレビュー画像を、見た目の品質を維持しながらファイルサイズを削減するように最適化するかどうかを指定します。有効にすると、🤖/image/optimize を使用して画像を最適化します。
optimize_prioritycompression-ratio | conversion-speed(デフォルト:"conversion-speed")画像の最適化で、変換速度と圧縮率のどちらを優先するかを指定します。
optimizeが有効な場合にのみ使用します。詳細は 🤖/image/optimize のドキュメントをご覧ください。optimize_progressiveboolean(デフォルト:false)画像をインターレース化するかどうかを指定します。インターレース化すると、ブラウザーで結果の画像が段階的に読み込まれます。
optimizeが有効な場合にのみ使用します。詳細は 🤖/image/optimize のドキュメントをご覧ください。clip_formatapng | avif | gif | webp(デフォルト:"webp")生成する動画クリップのアニメーション画像形式です。動画ファイルに
clip戦略を適用する場合にのみ使用されます。画像形式とその特性についての詳細は、MDN Web Docs を参照してください。GIF は多くのソフトウェアでサポートされていますが、使用できるカラーパレットは限られています。APNG はさまざまな色深度に対応していますが、可逆圧縮のため、動画では画像サイズが大きくなります。AVIF は効率的に圧縮できますが、アニメーションへの対応はブラウザーによって異なります。WebP はファイルサイズの小ささと見た目の品質のバランスがよく、デフォルトのクリップ形式です。
clip_offsetstring | number(デフォルト:1)クリップを切り出す開始位置を秒単位で指定します。動画ファイルに
clip戦略を適用する場合にのみ使用されます。大きな動画では、処理を高速化するためにファイルの一部のみをインポートすることがあります。オフセットが利用可能なメディアデータの範囲外にあると、クリップを生成できない場合があります。clip_durationstring | number(デフォルト:5)生成する動画クリップの長さを秒単位で指定します。動画ファイルに
clip戦略を適用する場合にのみ使用されます。クリップを長くするとファイルサイズも大きくなり、プレビューには適さない場合があるため、ご注意ください。clip_frameratestring | number(デフォルト:5)生成する動画クリップのフレームレートです。動画ファイルに
clip戦略を適用する場合にのみ使用されます。フレームレートを高くすると動きが滑らかになりますが、ファイルサイズも大きくなり、プレビューには適さない場合があるため、ご注意ください。clip_loopboolean(デフォルト:true)生成するアニメーション画像を無限にループ再生するか(
true)、一度再生したら停止するか(false)を指定します。動画ファイルにclip戦略を適用する場合にのみ使用されます。