意味のあるファイルプレビューの生成
新しい /file/preview Robot をご紹介します。これは、対応するファイル形式に対して自動でプレビューを作成し、生成できない場合はアイコンにフォールバックするよう設計された Transloadit の機能です。動画のサムネイル、音声のアルバムアートや波形、ドキュメントのページプレビュー、Web サイトのスクリーンショット、アーカイブのアイコンなど、この Robot を使えば、人がファイルをすばやく見分けられるプレビューを提供できます。複雑な各種ファイルタイプの扱いは私たちが引き受けるので、アプリの構築に集中できます。
この Robot は数行の JSON で導入でき、内部ではファイルごとの戦略を使い分けます。プレビュー生成をシンプルにし、アプリ内でのファイル認識を支援できます。

何ができるか?
🤖/file/previewは、ユーザーがファイル内容をすばやく識別できるように、意味のあるプレビューを生成するために設計されています。対応内容は次のとおりです。
画像:RAW 形式を含む、対応画像向けに最適化されたサムネイル
動画:フレーム抽出または短いクリップ
(コンテンツプレビューを生成できない場合はフォールバックアイコンを使用します。
)
音声:埋め込みアートワーク(利用できない場合は波形を可視化します。
)
ドキュメント:先頭ページのプレビュー
Web ページ:ページのスクリーンショット
アーカイブ:種類別アイコン
利用できるプレビューは、ファイル形式、コーデック、メディアデータによって異なります。すべてのファイルでコンテンツプレビューを生成できるわけではありません。
デフォルト戦略では、上のアーカイブ例のように、より情報量の多いプレビューを利用できない場合、Robot は種類別アイコンにフォールバックします。対応する戦略とフォールバック順は、strategy ドキュメントを参照してください。
この Robot は、実用的で見た目にも優れたデフォルトをすぐに使えるよう設計されていますが、動作は完全にカスタマイズできます。詳しくは後述します。
なぜ Transloadit か?
幅広いファイルのプレビュー生成は、画像形式、動画コーデック、ドキュメント形式の種類が非常に多いため複雑です。特に、RAW 画像形式を扱う写真家や、さまざまな Microsoft Office ドキュメントを扱うユーザーなど、ニッチな顧客ではこの複雑さがより顕著になります。画像形式と動画形式は絶えず進化するため、最新形式への追従と対応を継続するには、継続的な投資が必要です。利用できる変換については、対応形式と Robot リファレンスを参照してください。
ファイルプレビュー生成のために独自の内製ソリューションを構築すると、多数あるファイルタイプの一部をカバーするだけでも相応のエンジニアリングリソースが必要になり、さらに新しい形式への対応のために継続的な保守と更新が必要なため、そのリソースは長期にわたって拘束されます。さらに、ユーザーがアップロードしたファイルの処理は慎重さが求められ、さまざまなファイル処理ツールの中でインフラが脆弱性にさらされるおそれもあります。そこで、ファイルプレビュー生成を Transloadit に任せることで、その処理をアプリケーションサーバーから切り離し、エンジニアリングチームは顧客に最高のサービスを提供することに集中できます。複雑なプレビュー処理は Transloadit が担当します。
🤖/file/previewは、他の Robotと組み合わせて、ビジネスに固有のワークフローを作成できます。そうしたワークフローは、ファイルパイプラインのあらゆる部分の変換に活用できます。Transloadit は、エンドユーザーのアップロードを直接処理することも、大規模なメディアライブラリをインポートすることも、オンデマンドでファイルを変換し、最適化された結果を Smart CDNでブラウザーへ直接ストリーミングすることもできます。
実装オプション
🤖/file/preview を導入する方法はいくつかありますが、最初の方法として最適なのは、この Robot を参照するTemplateを作成することです。Template は、ファイルに対して Transloadit が何を行うかを記述する、アカウント内の JSON レシピです。Template はアカウントの Template Editor で作成することも、Terraform Provider Plugin経由で作成することもできます。
事前処理
事前処理では、プレビューを生成してストレージに保存します。通常は、エンドユーザーがプレビューを要求するより十分前、ユーザーが初めてファイルをアップロードした時点で実行します。このような事前処理は、オンデマンドよりもエンコードコストと保存コストが高くなり、統合も複雑になる代わりに、初回リクエスト時のレイテンシーを抑えられます。
Transloadit は元ファイルのアップロードを受け付け、プレビューを生成して、その後ストレージに保存できます。Transloadit にアップロード処理を任せるには、Templateで 🤖/upload/handleを次のように参照します。
{
"allow_steps_override": false,
"steps": {
":original": {
"robot": "/upload/handle"
},
"previewed": {
"robot": "/file/preview",
"use": ":original",
"width": 300,
"height": 200
},
"stored": {
"use": ["previewed", ":original"],
"robot": "/s3/store",
"credentials": "YOUR_AWS_CREDENTIALS",
"acl": "bucket-default",
"path": "my_target_folder/${unique_prefix}/${file.url_name}"
}
}
}
YOUR_AWS_CREDENTIALS は、保存済みの
Template 認証情報の名前に置き換えてください。一意のプレフィックスにより、元ファイルと各プレビューにそれぞれ固有のオブジェクトパスが割り当てられます。acl: "bucket-default" は生成される ACL ヘッダーを省略します。バケットのアクセス制御ポリシーは別途設定してください。この Template を使用する前に、S3 のセットアップと権限ガイドに従ってください。
アップロード元は通常ブラウザー(たとえば Uppy 経由)ですが、バックエンド SDK からファイルをアップロードすることもできます。
まずはブラウザーでのユースケースを見ていきます。
フロントエンドアップロード
Transloadit は、Web ブラウザー向けのオープンソースファイルアップローダーである
Uppyを使って、エンドユーザーがブラウザーから行うアップロードを処理できます。ファイルを受け付けると、Transloadit は Template の処理設定に従って処理するため、プレビューを生成して S3 バケットに保存します。元ファイルも保存されます。"stored" Step で "use": ["previewed", ":original"] を指定していたためです。
ブラウザーコードを実行する前に、独自アプリケーション側で保護された
POST /api/transloadit/assembly-options ハンドラーを実装してください。ここでは、ユーザーの認証、アップロードの認可、リクエストのオリジンまたはアプリの CSRF トークンの確認、アップロード制限の適用を行う必要があります。このハンドラーは、上記のアップロード用
Template の固定 ID に結び付けてください。ブラウザーが渡す任意の Template や処理設定に署名してはいけません。Workspace で
Signature Authenticationを有効にし、保存済み Template では
allow_steps_override: false を保持してください。
そのバックエンドでは、署名生成の例を使って、短時間だけ有効な auth.expires を含む
{ params, signature } を返します。シリアライズ済みの
params 文字列は変更せずに返し、Auth Secret はサーバー側に保持してください。このエンドポイントは自分のアプリのものであり、Transloadit の
API エンドポイントではありません。
ブラウザープロジェクトで Yarn を使って @uppy/core、@uppy/dashboard、@uppy/transloadit をインストールし、ページに id="uppy-dashboard" を持つ要素を追加します。次のコードをバンドラー経由で読み込んでください。
import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'
import '@uppy/core/dist/style.min.css'
import '@uppy/dashboard/dist/style.min.css'
const uppy = new Uppy()
.use(Dashboard, {
inline: true,
// This is the element where the dashboard will be rendered:
target: '#uppy-dashboard',
})
.use(Transloadit, {
waitForEncoding: true,
assemblyOptions: async () => {
const response = await fetch('/api/transloadit/assembly-options', {
method: 'POST',
credentials: 'same-origin',
})
if (!response.ok) {
throw new Error(`Could not authorize the upload (HTTP ${response.status})`)
}
return response.json()
},
})
uppy.on('transloadit:complete', (assembly) => {
const preview = assembly.results?.previewed?.[0]
if (preview) {
console.log('Preview object URL:', preview.ssl_url)
} else {
console.log('No previews were generated.')
}
})
S3 エクスポートは、生成元の Step である previewed の下に結果を更新します。返される ssl_url は、非公開 S3 オブジェクトへのアクセスを付与するものでも、恒久的なダウンロード URL を保証するものでもありません。ダウンロードはアプリケーション側で認可してください。たとえば、バックエンドで生成した短時間有効な S3 ダウンロード URL を使えます。
Uppy は Transloadit が開発したものです。この投稿では紹介しきれないほど多くの機能があるため、詳しくは Uppy Web サイトを参照してください。
ネイティブモバイルアプリと統合したい場合は、Android用と iOS用の SDK もあります。
バックエンドアップロード
バックエンドからでも同様に Transloadit へアップロードできます。Node.js では次のようになります。
yarn add @transloadit/node で @transloadit/node をインストールしてください。サンプルは upload.mjs として保存し、node upload.mjs で実行します。まずサーバー環境で、TRANSLOADIT_KEY に API キー、TRANSLOADIT_SECRET に Auth Secret、TRANSLOADIT_TEMPLATE_ID に上記のアップロード用 Template の ID を設定してください。また、./file.mp4 は読み取り可能なローカルファイルに置き換えてください。Auth Secret はブラウザーコードやソース管理に含めないでください。
import { Transloadit } from '@transloadit/node'
const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}
const transloadit = new Transloadit({
authKey: TRANSLOADIT_KEY,
authSecret: TRANSLOADIT_SECRET,
})
const assembly = await transloadit.createAssembly({
params: { template_id: TRANSLOADIT_TEMPLATE_ID },
files: { file: './file.mp4' },
waitForCompletion: true,
})
const preview = assembly.results?.previewed?.[0]
if (preview) {
console.log('Preview object URL:', preview.ssl_url)
} else {
console.log('No previews were generated.')
}
統合しやすいように、多くのバックエンド言語向けの SDK も用意されていますが、REST API を直接利用することもできます。
インポート
Transloadit にアップロード処理を任せる代わりに、Transloadit は S3 などのクラウドソースからファイルをインポートし、プレビューを生成して、S3 や他のストレージプロバイダーへ再度エクスポートできます。これは 1 つのファイルに対して行うことも、多数の TB のファイルを含むバケット全体に対して行うこともできます。
一例として、以下の Template には 🤖/file/filter も追加します。これにより、ファイルタイプでフィルタリングし、この例では音声ファイルだけのプレビューを生成する方法を示します。これはファイルサイズ、ビットレート、メディアタイプなど、ほかの条件でのフィルタリングにも応用できます。以下は、アカウントの Template Editor で作成する完全なTemplateです。
{
"steps": {
"imported": {
"robot": "/s3/import",
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "my_source_folder/"
},
"audio_filtered": {
"use": "imported",
"robot": "/file/filter",
"accepts": [["${file.type}", "==", "audio"]],
"error_on_decline": false
},
"previewed": {
"robot": "/file/preview",
"use": "audio_filtered",
"width": 300,
"height": 200,
"format": "png"
},
"stored": {
"use": "previewed",
"robot": "/s3/store",
"credentials": "YOUR_AWS_CREDENTIALS",
"acl": "bucket-default",
"path": "my_target_folder/${unique_prefix}/${file.url_name}"
}
}
}
この Template は、どの SDK からでも参照して実行できます。Node.js では、上と同じパッケージとサーバー環境設定を使いますが、TRANSLOADIT_TEMPLATE_ID にはこのインポート用 Template の ID を設定してください。以下を import.mjs として保存し、node import.mjs を実行します。ローカルアップロードは不要です。フィルターに一致する音声ファイルがなければ、読み取るプレビューは生成されません。
import { Transloadit } from '@transloadit/node'
const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}
const transloadit = new Transloadit({
authKey: TRANSLOADIT_KEY,
authSecret: TRANSLOADIT_SECRET,
})
const assembly = await transloadit.createAssembly({
params: { template_id: TRANSLOADIT_TEMPLATE_ID },
waitForCompletion: true,
})
const preview = assembly.results?.previewed?.[0]
if (preview) {
console.log('Preview object URL:', preview.ssl_url)
} else {
console.log('No previews were generated.')
}
オンデマンド
最後に、Smart CDN を使ってオンデマンドでプレビューを生成することもできます。これは、ユーザーがプレビューを要求するまで Transloadit が何も処理しないことを意味します。その後、Transloadit がストレージから元ファイルをインポートし、プレビューを生成して、エンドユーザーへ直接配信します。結果はエンドユーザーの近くにキャッシュされます。
これには次の利点があります。
- プレビューはユーザーから要求されたときにだけ作成されるため、実際には要求されないメディアファイルのコストを抑えられます。
- キャッシュ済みの結果は、利用可能でキャッシュ可能な間は、追加のエンコード料金なしで配信できます。キャッシュ配信にも帯域幅料金は発生します。期限切れまたは追い出し済みの結果は再処理が必要になることがあり、その場合は新たな処理料金が発生します。
- 統合がシンプルです。プレビューを自分で処理(保存、参照の格納など)する必要はありません。代わりに Template を作成し、そのアセット用の Smart CDN URL を Web ページやアプリに追加するだけで済みます。
- エンドユーザーのデバイス、解像度、帯域幅などに合わせてプレビューを調整できます。そのため、ユーザー体験の向上につながらない配信バイトを無駄にせずに済みます。これにより、帯域幅、バッテリー、時間を節約できます。
オンデマンドプレビュー、署名付き URL、配信計測についてさらに詳しく知りたい場合は、次の投稿を参照してください。Smart CDN によるオンデマンドメディアプレビュー
以下は、S3 からメディアファイルをインポートし、プレビューを生成して、Smart CDN で配信するよう Transloadit に指示する Template の例です。
{
"steps": {
"imported": {
"robot": "/s3/import",
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "${fields.input}"
},
"previewed": {
"use": "imported",
"robot": "/file/preview",
"width": "${fields.w}"
},
"served": {
"use": "previewed",
"robot": "/file/serve"
}
}
}
この Template の URL 構造は次のとおりです。
https://my-workspace.tlcdn.com/my-template/file.mp4?w=300
YOUR_AWS_CREDENTIALS には、保存済みの Template 認証情報の名前を使用し、ソースファイルはその S3 バケット内の file.mp4 に配置してください。ここで、my-template は Template 名、${fields.input} は URL から file.mp4 を受け取り、${fields.w} は URL から 300 を受け取ります。Workspace と Template のプレースホルダーは自分の値に置き換えてください。これは URL 構造を示すものです。保護された配信を行う場合は、ブラウザーに送る前にバックエンドで要求されたファイルと寸法を認可し、有効期限付きの署名済み URL を生成してください。Smart CDN の署名ガイドに従ってください。require_signature_auth は、Template API を使って
1 に設定してください。これは、上記の処理設定 JSON の外側にある Template 設定です。任意のパスや変換を受け付ける汎用署名エンドポイントは公開しないでください。
プレビューのカスタマイズ
🤖/file/preview には、すぐに使える実用的で見た目のよいデフォルトがありますが、いくつかのパラメーターを使って、アプリの見た目や使い勝手に合わせて出力を制御できます。
format:サムネイルの出力形式widthとheight:ピクセル単位の寸法resize_strategy:指定寸法にプレビューを収める方法background:余白を埋める背景色(16 進形式、#rrggbb[aa])strategy:ファイルタイプごと(音声、動画、画像など)のプレビュー生成のカスタマイズ
音声の波形では次を指定できます。
waveform_center_colorとwaveform_outer_color:16 進形式のグラデーション色waveform_heightとwaveform_width:波形の寸法
アイコンでは次を指定できます。
icon_style:フォールバックアイコンの見た目icon_text_color:16 進形式のテキスト色icon_text_font:フォントファミリーicon_text_content:アイコン上に表示するテキスト
動画クリップでは次を指定できます。
clip_format:アニメーション形式clip_offset:開始位置(秒)clip_duration:長さ(秒)clip_framerate:フレーム/秒clip_loop:アニメーションをループするかどうか
画像最適化では次を指定できます。
optimize:ファイルサイズ最適化を有効にするかどうかoptimize_priority:変換速度と圧縮率のバランスoptimize_progressive:プログレッシブ読み込みを有効にするかどうか
取り得る値、デフォルト値、制限、戦略固有の動作については、🤖/file/preview ドキュメントを参照してください。
セキュリティに関する考慮事項
ファイルを保護し、プレビュー機能へのアクセスを制御するために、フロントエンド統合(Uppy、Smart CDN、モバイル)ではリクエスト署名の実装を推奨します。特に Smart CDN 配信では、Smart CDN URL に署名する前に、要求されたファイルと変換へのアクセスを認可してください。署名は URL を保護するものであり、それを取得した人は、有効である間は利用できます。
多くのプログラミング言語での例を含む詳しい情報は、Smart CDN の署名付き URL に関するドキュメントを参照してください。
次の点を忘れないでください。
- 署名付き URL は常にバックエンドで生成する
- Auth Secret をクライアントサイドコードに公開しない
- 署名付き URL には有効期限を設定する
有効期限を短くすると、リプレイ可能な時間枠を狭められます。有効期限を長くすると、URL をより長く利用可能にできますが、キャッシュ保持、キャッシュヒット、または処理コストの低下を保証するものではありません。キャッシュ配信には引き続き課金され、期限切れまたは追い出し済みの結果は再度処理が必要になることがあります。
高度なユースケース
この投稿では 🤖/file/preview を使う基本的な方法を紹介しましたが、より複雑なパイプラインに統合する方法はほかにも多数あります。
- 自動バッチ生成:ストレージバケット全体に対するプレビュー生成をスケジュールして、常に最新のプレビューを大規模に維持します。
- イベント駆動の統合:新しいファイルが届くたびに自動でプレビュー処理を開始し、必要なときに常にプレビューを利用できるようにします。
- ハイブリッドワークフローの構成:🤖/file/previewを他の Transloadit Robot、たとえば 🤖/image/facedetect や 🤖/video/encodeと組み合わせることで、単一のワークフロー内で複数段階の変換を構築できます。
- 拡張されたストレージオプション:AWS S3 だけでなく、主要なクラウドストレージプロバイダーすべてに加え、独自インフラ(S3 互換ストレージや SFTP)にもシームレスに統合できます。
- カスタマイズ可能なキャッシュ:🤖/file/previewを Smart CDN 設定と組み合わせて、性能要件と信頼性要件に合う構成にできます。
- 独自 CDN の利用:大規模導入では、既存の契約やインフラを活用するために、顧客自身の CDN と私たちのエンコードプラットフォームを組み合わせることができます。
料金と提供状況
現在のプラン、料金、プラン制限については 料金ページと、Robot の料金ドキュメントを確認してください。
参考情報
次の情報も役立ちます。
- デモ (English)では、ほかの機能や組み合わせ方のイメージを確認できます。
- Smart CDNでは、ファイル、プレビュー、その他の変換をオンデマンドで配信する方法を詳しく確認できます。
- Smart CDN によるオンデマンドメディアプレビューでは、デモ、配信計測、サーバーサイド署名の例を確認できます。
次のステップ
開始するには、次の手順に従ってください。
- サインアップして Transloadit アカウントを作成します。
- 🤖/file/preview を使って最初の Template を作成します。
- Template Editor を使って、さまざまなプレビューと統合オプションを試します。
- アプリケーションにプレビューを統合します。
導入でお困りですか。私たちは Robot を作っていますが、お手伝いが好きな本物の人間です。お気軽に次からご連絡ください。support@transloadit.com。
それでは、よい transloading を 🙂
