メタデータ
多くのファイルには、その内容に関する有用な情報が含まれています。これは「メタデータ」と呼ばれます。Transloadit は、アップロード、インポート、処理されたすべてのファイルから、このメタデータを自動的に抽出します。
少なくとも、各ファイルには次のような情報が含まれます。
{
"id": "ae52b7f8c1b3426e8c29ea0a9daf8306",
"name": "straw-apple.jpg",
"basename": "straw-apple",
"ext": "jpg",
"size": 92230,
"mime": "image/jpeg",
"type": "image",
"field": "test_file",
"url": "http://tmp.maynard.transloadit.com/upload/1324a798a99fce7f5f8289a95a74f02b.jpg",
"original_id": "4af24fb2595f44809f3adc2f77bc9bfa",
"meta": {
// …
}
}
抽出できる情報は、メディアファイルやその種類だけでなく、何によって作成されたかにも依存します。iPhone で作成されたファイルであれば、おそらく位置情報を示す latitude が含まれています。より一般的なキーには、height や duration があります。
処理対象のファイルからどのような情報を抽出できるかを確認するには、デモ (English)のいずれかでファイルをアップロードし、そのレスポンスを調べてみてください。
id-
Transloadit が内部でファイルを追跡するために使用する、ランダムで一意の ID です。
name-
ファイル名です。ファイルが処理によって別の形式に変換される場合、Transloadit はこのフィールドで使用される拡張子を変更します。
basename-
拡張子を除いたファイル名です。
ext-
ファイルの拡張子です。拡張子が判定されていない場合は
null、拡張子のない名前の場合は空文字列になることがあります。 size-
ファイルサイズです。単位はバイトです。
mime-
このファイルについて判定された MIME タイプです。
type-
ファイルを表す抽象的なカテゴリです。既知の値は
"audio"、"document"、"image"、"office"、"pdf"、"swf"、"video"、"xls"で、カテゴリが検出されなかった場合はnullです。利用側は、将来追加されるカテゴリとの互換性を保つため、これら以外の文字列も受け入れる必要があります。 field-
このファイルの送信に使用されたフォームフィールドの名前です。
url-
ファイルをダウンロードできる URL です。配信用 URL がない場合は
nullです。当社のサーバー上の一時 URL は数時間で有効期限が切れます。後で使用するには、ファイルをストレージにエクスポートしてください。/transloadit/storeはurl/ssl_urlに署名付き Smart CDN URL を設定します。キーがない場合はnullを設定します。アクセスと保持に関する条件に従って長期的に参照できるよう、返された Workspace、asset_id、version_idを保持してください。/transloadit/importは、asset_idと省略可能なversion_id、または変更可能なpathを受け入れます。一時 URL も、処理対象ファイルのidも、長期的に利用できるストレージ参照ではありません。 original_id-
このファイルの生成元となった、元のアップロードファイルの一意の ID です。これは、複数ファイルのアップロードで、複数の Steps による処理を経た後、どのファイルから特定のファイルが生成されたかを特定するのに役立ちます。
meta-
以下に示すように、ファイルから抽出された追加のメタデータを含むオブジェクトです。同じ日付タグが複数ある場合、元の値のリストとして返されることがあります。単一のタイムスタンプとして使用する前に、値の型を確認してください。
画像のメタデータ
対象のファイルによって異なりますが、type が image のファイルでは、通常、meta プロパティに次のようなデータが含まれることがあります。
width-
メディアの幅です。単位はピクセルです。表示比率がピクセル比率と異なる動画の場合、意図された表示幅を表します。
height-
メディアの高さです。単位はピクセルです。
aspect_ratio-
画像のアスペクト比です。幅を高さで割った値です。何らかの理由で画像の高さが 0 の場合は 0 になります。
date_recorded-
メディアが記録された日時です。単一の有効な文字列のタイムスタンプは、
YYYY/MM/DD HH:MM:SSに正規化されます。タイムゾーンが含まれている場合は UTC/GMT に変換され、末尾がGMTになります。解析できない文字列のタイムスタンプはnullになります。数値のタイムスタンプと、同じ日付タグが複数ある場合のリストは、元の値が保持されます。 date_file_created-
メディアのメタデータによって報告される作成日時のタイムスタンプです。利用可能な場合に含まれます。
date_file_modified-
ファイルシステムまたは埋め込まれたメディアのメタデータによって報告される更新日時のタイムスタンプです。
title-
この画像のタイトルです。例:
"Tree"。 keywords-
ファイルのメタデータから抽出されたキーワードです。文字列、有限の数値、または文字列、有限の数値、真偽値を要素に持つ配列です。例:
["tree", "nature"]。このフィールドは存在しない場合やnullの場合があります。反復処理する前に型を確認してください。配列の要素が必ずしも文字列とは限りません。 description-
この画像の説明です。例:
"This tree is very old."。 location-
この画像が撮影された場所です。通常は通りの住所で、たとえば
"Zingster Str. 32"です。文字列および数値のメタデータ値は保持されます。文字列メソッドを使用する前に型を確認してください。 creator-
ファイルから抽出された作成者のメタデータです。元のスカラー値、およびそれらの値のリストが保持されます。文字列メソッドを使用する前に型を確認してください。
author-
画像を撮影した作成者です。一部のカメラは、
creatorではなくこのフィールドに値を設定します。 copyright-
著作権のメタデータフィールドです。
copyright_notice-
ファイルから抽出された著作権表示のメタデータです。元のスカラー値が保持されます。文字列メソッドを使用する前に型を確認してください。
city-
この画像が撮影された市です。例:
"Berlin"。文字列および数値のメタデータ値は保持されます。文字列メソッドを使用する前に型を確認してください。 state-
この画像が撮影された州です。例:
"Berlin"。 country-
この画像が撮影された国です。例:
"Germany"。 country_code-
画像のメタデータに記録された国コードです。例:
"de"または528。文字列および数値の値は保持されます。文字列メソッドを使用する前に型を確認してください。 aperture-
この画像の絞り設定です。例:
5.7。 exposure_compensation-
この画像の露出補正です。例:
"+4/3"。 exposure_mode-
この画像の露出モードです。例:
"Auto"。文字列および数値のメタデータ値は保持されます。文字列メソッドを使用する前に型を確認してください。 exposure_time-
この画像の露出時間です。例:
"1/30"。 flash-
この画像のフラッシュ設定です。例:
"Off, Did not fire"。 focal_length-
この画像の焦点距離です。例:
"55.0 mm"。 f_number-
この画像の F 値です。例:
5.6。 iso-
この画像の ISO 値です。例:
800。 light_value-
この画像のライトバリューです。例:
6.9。 metering_mode-
この画像の測光モードです。例:
"Multi-segment"。 shutter_speed-
この画像のシャッタースピードです。例:
"1/32"。 white_balance-
この画像のホワイトバランス設定です。例:
"Manual"。文字列および数値のメタデータ値は保持されます。文字列メソッドを使用する前に型を確認してください。 device_name-
メディアを記録したデバイスの名前です。例:
"iPhone 3GS"。 device_vendor-
メディアを記録したデバイスの製造元です。例:
"Apple"。文字列および数値のメタデータ値は保持されます。文字列メソッドを使用する前に型を確認してください。 device_software-
メディアを記録したデバイスのソフトウェアバージョンです。例:
"3.1.2"。 latitude-
メディアが記録された場所の緯度です。例:
52.5374。 longitude-
メディアが記録された場所の経度です。例:
13.4034。 thumb_index-
現在のサムネイルのインデックスです。0 から始まります。このキーは 🤖/video/thumbs の結果にのみ存在します。
thumb_offset-
現在のサムネイルのオフセットです。単位は秒です。このキーは 🤖/video/thumbs の結果にのみ存在します。
frame_count-
アニメーション GIF ファイルのフレーム数です。それ以外のすべての画像形式では、デフォルトで
1です。 colorspace-
検出されたメディアの色空間です。例:
"sRGB"または"Gray"。動画の色空間は、メタデータ抽出が有効な状態で検出された場合に利用できます。output_meta.colorspace: trueは必要ありません。output_meta: falseを設定すると、メタデータ抽出が無効になります。 has_clipping_path-
画像にクリッピングパスが含まれている場合は
true、それ以外の場合はfalseです。 average_color-
最も出現頻度の高い単一のピクセル色を数えるドミナントカラーとは異なります。ドミナントカラーの用途は限られています。平均色は、まず入力画像を 1 ピクセルに縮小してから算出されます。
has_transparency-
画像に透明な領域があるかどうかを示します。透明度の検査を要求するには、
output_meta.has_transparencyをtrueに設定してください。JPEG 画像のfalseのように、偽であることが既知の値は、このオプションが省略されている場合やfalseの場合でも返されることがあります。output_meta自体をfalseに設定すると、追加のメタデータ抽出はスキップされます。ただし、基本的なファイル形式とサイズのチェックは引き続き実行されることがあります。 dominant_colors-
画像のドミナントカラーを 16 進数値の配列として、最大 10 色まで返します。この抽出をスキップするには、
output_meta.dominant_colorsを省略してください。値がfalseの場合も含め、このプロパティを指定すると抽出が要求され、色が返された場合は追加の使用料金が発生することがあります。output_meta自体をfalseに設定すると、追加のメタデータ抽出は無効になります。ただし、基本的なファイル形式とサイズのチェックは引き続き実行されることがあります。
動画のメタデータ
対象のファイルによって異なりますが、type が video のファイルでは、通常、meta プロパティに次のようなデータが含まれることがあります。
width-
メディアの幅です。単位はピクセルです。表示比率がピクセル比率と異なる動画の場合、意図された表示幅を表します。
height-
メディアの高さです。単位はピクセルです。
framerate-
動画のフレームレートです。例:
29.5。 video_bitrate-
動画の映像ビットレートです。例:
500000。 video_codec-
動画の映像コーデックです。例:
"ffh264"。 audio_bitrate-
全チャンネルを合計した音声ビットレートです。単位はビット毎秒です。例:
128000。 audio_samplerate-
音声のサンプルレートです。単位はヘルツです。例:
44100。 audio_channels-
音声チャンネル数です。ステレオでは通常
2です。 audio_codec-
音声コーデックです。例:
"faad"。サポートされている音声コーデックを参照してください。 seekable-
動画の形式がシークに対応しているかどうかを示します。例:
true。 interlaced-
動画がインターレース走査を使用していると見られるかどうかを示します。インターレース動画では
true、プログレッシブ動画ではfalseです。検出を要求するには、output_meta.interlacedをtrueに設定してください。検出が要求されなかった場合や、要求された検出で確定的な結果が得られなかった場合、このキーは値がnullの状態で存在することがあります。フィールドが存在するだけでは、検出が実行されたことを示しません。 field_order-
FFprobe が報告するフィールド順序です。例:
"tt"、"bb"、"tb"、"bt"、"progressive"。この診断用フィールドに値を設定する検出を要求するには、output_meta.interlacedをtrueに設定してください。検出が要求されなかった場合や、フィールド順序が取得できなかった場合、このキーは値がnullの状態で存在することがあります。インターレースとプログレッシブを単純に分岐させるには、interlacedを使用してください。 interlace_detection-
Transloadit のインターレース検出機能による診断の詳細です。このオブジェクトには、
sampled_frames、tff、bff、progressive、undetermined、confidence、method、ffprobe_field_orderが含まれることがあります。検出を要求するには、output_meta.interlacedをtrueに設定してください。検出が要求されなかった場合、このキーは値がnullの状態で存在することがあります。プロパティを読み取る前に、null ではないオブジェクトであることを確認してください。 colorspace-
検出されたメディアの色空間です。例:
"sRGB"または"Gray"。動画の色空間は、メタデータ抽出が有効な状態で検出された場合に利用できます。output_meta.colorspace: trueは必要ありません。output_meta: falseを設定すると、メタデータ抽出が無効になります。 date_recorded-
メディアが記録された日時です。単一の有効な文字列のタイムスタンプは、
YYYY/MM/DD HH:MM:SSに正規化されます。タイムゾーンが含まれている場合は UTC/GMT に変換され、末尾がGMTになります。解析できない文字列のタイムスタンプはnullになります。数値のタイムスタンプと、同じ日付タグが複数ある場合のリストは、元の値が保持されます。 date_file_created-
メディアのメタデータによって報告される作成日時のタイムスタンプです。利用可能な場合に含まれます。
date_file_modified-
ファイルシステムまたは埋め込まれたメディアのメタデータによって報告される更新日時のタイムスタンプです。
device_name-
メディアを記録したデバイスの名前です。例:
"iPhone 3GS"。 device_vendor-
メディアを記録したデバイスの製造元です。例:
"Apple"。文字列および数値のメタデータ値は保持されます。文字列メソッドを使用する前に型を確認してください。 device_software-
メディアを記録したデバイスのソフトウェアバージョンです。例:
"3.1.2"。 latitude-
メディアが記録された場所の緯度です。例:
52.5374。 longitude-
メディアが記録された場所の経度です。例:
13.4034。
たとえば、インポートまたはアップロードの Step でインターレース動画を検出し、該当するファイルだけを後続の Step に渡すことができます。
{
"steps": {
":original": {
"robot": "/upload/handle",
"output_meta": {
"interlaced": true
}
},
"only_interlaced": {
"use": ":original",
"robot": "/file/filter",
"accepts": [["${file.meta.interlaced}", "==", "true"]]
}
}
}
音声のメタデータ
対象のファイルによって異なりますが、type が audio のファイルでは、通常、meta プロパティに次のようなデータが含まれることがあります。
duration-
音声ファイルの長さです。単位は秒です。
audio_bitrate-
全チャンネルを合計した音声ビットレートです。単位はビット毎秒です。例:
128000。 audio_samplerate-
音声のサンプルレートです。単位はヘルツです。例:
44100。 audio_channels-
音声チャンネル数です。ステレオでは通常
2です。 audio_codec-
音声コーデックです。例:
"faad"。サポートされている音声コーデックを参照してください。 artist-
メディアのメタデータに記録されたアーティスト情報です。同じタグが複数ある場合はリストとして返されます。数値のように見える名前や、
trueおよびfalseという語は、リスト内も含め、JSON の数値または真偽値として届くことがあります。文字列メソッドを使用したり、リストを反復処理したりする前に、型を確認してください。 mean_volume-
音声ファイルの平均音量です。測定を要求するには、
output_meta.mean_volumeをtrueに設定してください。測定が要求されなかった場合や、値が取得できなかった場合、このキーは値がnullの状態で存在することがあります。フィールドが存在するだけでは、測定が実行されたことを示しません。
Office 文書のメタデータ
type が office のファイルでは、ファイルに保存されたプロパティに存在する場合、meta に次のフィールドが含まれることがあります。これらの件数は、文書の作成アプリケーションによって報告されるものです。Transloadit は文書の内容から再計算しないため、値が存在しない場合や、古い場合があります。
page_count-
ページ数です。Office 文書の場合、ファイルに保存されたプロパティから取得されます。
word_count-
Office 文書のプロパティに保存された単語数です。
character_count-
Office 文書のプロパティに保存された文字数です。