Transloadit の「output_meta」パラメーターを解説
/upload/handle と
/image/resize の Robot のドキュメントを見たことがあれば、output_meta パラメーターを見かけたかもしれません。具体的に何をするものなのか、不思議に思ったこともあるのではないでしょうか。ほかの多くのパラメーターと違って、名前だけでは用途がすぐにわかりにくいからです :)
そこで、このパラメーターがどう動作するのか、そしてなぜ作られたのかを少し説明します!
output_meta パラメーター
output_meta パラメーターの狙いは、ファイルについて特定のメタデータを収集できるようにすることです。常に有効なら便利そうですが、計算には CPU 負荷がかなりかかります。そのため、Assembly を常に高速に実行できるよう、一部のメタデータの収集はこのパラメーターで制御し、デフォルトでは無効にしました。
Robot の Step に
output_meta パラメーターを定義すると、エンコード結果ごとに追加のメタデータを付けるかどうかを選べます。これにより、きめ細かく制御できるようになりましたが、問題も生じました。アップロードしたファイルでは、どうやってこれを有効にすればよいのでしょうか。ファイルアップロードは 2008 年からサポートしていますが、以前から少し特殊な存在でした。以前は、アップロードされたファイルだけが、Robot の処理結果ではなかったためです。
そこで、output_meta パラメーターによるきめ細かな制御の導入に続き、アップロード処理を専用の Robot にまとめ、新しいパラメーターとともに /upload/handle の
Robot を公開しました。これで例外はなくなり、すべてのファイルについて、各 Step で動作を変更できるようになりました。

どのように動作するのか?
output_meta パラメーターでは、ブール値のプロパティを持つオブジェクト、プロパティ名の配列、またはブール値を使って、任意のメタデータを選択できます。この例では has_transparency を使います。ほかに
dominant_colors や blurhash などのプロパティもサポートしています。has_transparency を true に設定すると、画像を解析し、透明な部分があるかどうかを返します。has_transparency の計算には、一部のファイルでは時間がかかるため、デフォルトでは結果セットから除外しています。このプロパティが不要な場合にまで、余分な実行時間の負担をかけたくないためです。
たとえば、アップロードしたファイルに透明な領域があるかを知りたい場合は、"output_meta": { "has_transparency": true } を
/upload/handle の Robot に設定できます。すると、処理結果のファイルに meta.has_transparency が設定されます。
このパラメーターを使う Assembly の作成方法を見ていきましょう。ぜひ一緒に試してみてください!
Assembly の作成
ここでは、2 種類の Assembly Instructions を作成し、/upload/handle の Robot と /image/resize の Robot のそれぞれで、このパラメーターをどう使うかを確認します。
{
"steps": {
":original": {
"robot": "/upload/handle",
"output_meta": {
"has_transparency": true
}
}
}
}
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"resized": {
"use": [":original"],
"robot": "/image/resize",
"result": true,
"background": "white",
"flatten": false,
"height": 500,
"imagemagick_stack": "v2.0.3",
"resize_strategy": "pad",
"rotation": false,
"strip": true,
"trim_whitespace": true,
"width": 250,
"output_meta": {
"has_transparency": true
}
}
}
}
ここには、2 種類の Assembly Instructions があります。一方は /upload/handle の Robot だけを使い、もう一方は /image/resize の Robot を使います。
/image/resize の Robot を使う
Assembly Instructions では、output_meta プロパティが :original ステップではなく、resized ステップにある点に注目してください。この Assembly Instructions では、アップロード時ではなく、リサイズ時にファイルの透明部分の有無を調べているためです。
結果
上記のいずれかの Assembly Instructions を実行すると、/upload/handle の Robot の JSON 結果から、meta プロパティ(uploads キー内)に
has_transparency というフィールドがあり、true に設定されていることがわかります。このプロパティは、画像に透明な部分がある場合にのみ
true を返します。
同様に、/image/resize の
Robot が返す JSON 結果では、results セクション内の resized キーにある
meta プロパティに、has_transparency というフィールドがあり、true に設定されています。
ご覧のとおり、output_meta パラメーターはかなり便利です!さらに、Assembly を高速化するために、ほかの既存のメタデータキーも取得対象から除外できるようにすることを検討しています。たとえば、現在はすべてのファイルについてデフォルトで MD5 ハッシュを計算していますが、多くのユースケースではそれが不要な場合もあります。このパラメーターで指定できるプロパティが増えたら、必ずお知らせします! 💖
