ffmpeg.wasm でブラウザー内の動画からサムネイルを抽出
ローカル動画を選び、タイムスタンプを秒単位で入力して、動画をアップロードせずに PNG プレビューを表示します。このチュートリアルでは、ffmpeg.wasm と Vite で小さなブラウザーアプリを構築します。ファイル選択、対応する Wasm アセット、エラー表示、実行間のクリーンアップまで扱います。
ブラウザーでサムネイルを抽出する理由は?
ローカルプレビューがあれば、動画をアップロードするかどうか決める前に、適切なフレームを選べます。この例では、ブラウザーがローカルサーバーからアプリケーションコードと FFmpeg コアをダウンロードし、選択した動画と生成画像はブラウザーのメモリ内に保持されます。これはこのアプリの動作の説明であり、ffmpeg.wasm を使うすべてのアプリケーションのプライバシーを保証するものではありません。
ffmpeg.wasm の概要
ffmpeg.wasm ラッパーは、専用のウェブワーカー内で FFmpeg を実行します。仮想ファイルシステムにファイルをコピーし、使い慣れた FFmpeg コマンドを実行して、結果を読み戻します。ここで使うシングルスレッドのコアも、ブラウザーのメインスレッドとは別に実行されます。
まずは、暗号化されていない短い H.264 MP4 を使ってください。この例では、入力を 25 MiB まで、要求するタイムスタンプを六つまでに制限しています。これはデモの制限であり、すべてのデバイスでこのサイズのファイルを処理できるという保証ではありません。2026年11月7日の再検証では、Linux 上で Node.js 24.22.2 と 26.13.0 を使い、それぞれ Corepack 0.34.5、Yarn 4.12.0、Chromium 155.0.8059.84 を組み合わせました。以前の検証環境は、Linux 上の Node.js 24.15.0、Yarn 4.12.0、Chromium 145.0.7632.6 でした。Node はアプリのビルドと配信を担い、ブラウザーがメディア処理を行います。ほかのブラウザーやモバイルデバイスでは、個別のテストが必要です。
インストールと初期化
検証済みの 24.22.2 や 26.13.0 など、最新の Node.js LTS リリースを使ってください。ランタイムにはパッチを適用し続けてください。Node の 2026年10月のセキュリティ勧告には、両系列の更新が記載されています。続行する前に Corepack を用意してください。検証済みのバージョンは 0.34.5 です。Corepack には個別のインストール手順があり、Node.js 26 には同梱されなくなりました。
作業用ディレクトリで、Bash 互換シェルに以下を貼り付けてください。新しい wasm-thumbnails プロジェクトを作成し、既存のディレクトリは上書きしません。サブシェルを使うため、元のシェルのカレントディレクトリとオプションは変わりません。ローカルのロックファイルと TypeScript 設定でプロジェクトの境界を定めます。ローカルの Yarn 設定により、インストールと以降のコマンドで
node-modules リンカーを維持します。ignorePath は、上位ディレクトリの実行ファイル指定によって、固定した Yarn バージョンが置き換わるのを防ぎます。上位ディレクトリのほかの Yarn 設定は、引き続き適用されることがあります。
(
set -eu
mkdir wasm-thumbnails
cd wasm-thumbnails
cat > package.json <<'JSON'
{
"name": "wasm-thumbnails",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"dependencies": {
"@ffmpeg/core": "0.12.10",
"@ffmpeg/ffmpeg": "0.12.15",
"@ffmpeg/util": "0.12.2",
"vite": "8.3.1"
}
}
JSON
printf '{"compilerOptions":{"target":"ES2022"}}\n' > tsconfig.json
printf 'ignorePath: true\nnodeLinker: node-modules\n' > .yarnrc.yml
touch yarn.lock
corepack yarn install
)
依存関係の解決を再現できるよう、生成された yarn.lock を保持してください。以下の三つのファイルを wasm-thumbnails 内に保存します。まず、copy-core.ts はインストール済みパッケージから ESM コアをコピーし、JavaScript ファイルと Wasm ファイルを一致させます。公式の読み込みガイドでは、Vite 用に ESM アセットを指定しています。同一オリジンのアセットは、blob URL ラッパーなしで直接読み込めます。
import { copyFile, mkdir } from 'node:fs/promises'
await mkdir('public/core', { recursive: true })
for (const name of ['ffmpeg-core.js', 'ffmpeg-core.wasm']) {
await copyFile(`node_modules/@ffmpeg/core/dist/esm/${name}`, `public/core/${name}`)
}
次に、index.html を保存します。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Local video thumbnails</title>
<link rel="icon" href="data:," />
<style>
body { font-family: system-ui, sans-serif; max-width: 48rem; margin: 2rem auto; padding: 1rem; }
label { display: block; margin-block: 1rem; }
input { max-width: 100%; }
figure { margin-inline: 0; }
img { max-width: 100%; height: auto; }
</style>
</head>
<body>
<h1>Local video thumbnails</h1>
<form id="picker">
<fieldset id="controls">
<legend>Choose a video and timestamps</legend>
<label>Video <input id="video" type="file" accept="video/*" required /></label>
<label>Seconds, separated by commas
<input id="times" type="text" value="0.5, 1.5" required />
</label>
<button type="submit">Extract thumbnails</button>
</fieldset>
</form>
<p id="status" role="status">Choose a video to begin.</p>
<section id="results" aria-label="Thumbnails"></section>
<script type="module" src="/main.ts"></script>
</body>
</html>
ブラウザー要件への対応
index.html をファイルとして開かず、以下のように localhost でアプリを配信してください。このシングルスレッドの @ffmpeg/core は、SharedArrayBuffer や COOP/COEP ヘッダーなしで動作します。ただし、ラッパーにはモジュールワーカーと WebAssembly が必要です。コアのダウンロードサイズは HTTP 圧縮前で約 31 MiB あるため、初回の抽出は以降の抽出よりもかなり時間がかかることがあります。
@ffmpeg/core-mt への切り替えは、別の組み込み作業です。マルチスレッドの読み込み例には、追加のワーカーアセットと、クロスオリジン分離を含む SharedArrayBuffer のセキュリティ条件が必要です。このシングルスレッドの例に、それらの要件を標準で追加しないでください。本番環境の HTTPS、コンテンツセキュリティポリシー、サブパスでのホスティングには個別の設定が必要です。このチュートリアルではオリジンのルートから配信します。
サムネイルを一つ抽出
以下のプログラム全体を main.ts として保存してください。extractThumbnail() は最初の映像ストリームを選び、指定時刻にシークして、PNG を一つ書き出します。呼び出しごとに一意の仮想ファイル名を使い、終了ステータスと出力バイト列を確認してから、失敗時も含めてファイルを削除します。
import { FFmpeg } from '@ffmpeg/ffmpeg'
import { fetchFile } from '@ffmpeg/util'
const ffmpeg = new FFmpeg()
let extracting = false
async function extractThumbnail(videoFile: File, seconds: number): Promise<Blob> {
if (!Number.isFinite(seconds) || seconds < 0) throw new Error('Invalid timestamp')
if (extracting) throw new Error('A thumbnail operation is already running')
extracting = true
const id = crypto.randomUUID()
const input = `input-${id}.mp4`
const output = `thumb-${id}.png`
try {
if (!ffmpeg.loaded) {
await ffmpeg.load({
coreURL: new URL('/core/ffmpeg-core.js', location.href).href,
wasmURL: new URL('/core/ffmpeg-core.wasm', location.href).href,
})
}
await ffmpeg.writeFile(input, await fetchFile(videoFile))
const code = await ffmpeg.exec([
'-xerror', '-ss', String(seconds), '-i', input,
'-map', '0:v:0', '-frames:v', '1', '-vf', 'scale=320:-1', output,
])
if (code !== 0) throw new Error('FFmpeg could not extract this frame')
// A seek past the end can succeed without producing a usable image.
const data = await ffmpeg.readFile(output)
if (!(data instanceof Uint8Array) || data.length === 0) {
throw new Error('No thumbnail was produced')
}
return new Blob([new Uint8Array(data)], { type: 'image/png' })
} finally {
// A failed command may never have created one or both files.
await Promise.allSettled([ffmpeg.deleteFile(input), ffmpeg.deleteFile(output)])
extracting = false
}
}
function parseTimes(value: string): number[] {
const parts = value.split(',').map((part) => part.trim())
if (parts.length > 6 || parts.some((part) => !/^\d+(\.\d+)?$/.test(part))) {
throw new Error('Enter one to six nonnegative timestamps in seconds.')
}
const times = parts.map(Number)
if (times.some((time) => !Number.isFinite(time))) throw new Error('Invalid timestamp')
return times
}
const form = document.getElementById('picker')
const controls = document.getElementById('controls')
const video = document.getElementById('video')
const times = document.getElementById('times')
const status = document.getElementById('status')
const results = document.getElementById('results')
if (!(form instanceof HTMLFormElement) || !(controls instanceof HTMLFieldSetElement) ||
!(video instanceof HTMLInputElement) || !(times instanceof HTMLInputElement) ||
!status || !results) {
throw new Error('Missing page controls')
}
let running = false
const previewUrls: string[] = []
function clearPreviews(container: HTMLElement): void {
container.replaceChildren()
for (const url of previewUrls) URL.revokeObjectURL(url)
previewUrls.length = 0
}
form.addEventListener('change', () => {
if (running) return
clearPreviews(results)
status.textContent = 'Ready to extract.'
})
form.addEventListener('submit', async (event) => {
event.preventDefault()
if (running) return
const file = video.files?.[0]
if (!file) return
running = true
controls.disabled = true
clearPreviews(results)
status.textContent = 'Loading FFmpeg and extracting…'
const deadline = setTimeout(() => ffmpeg.terminate(), 60_000)
try {
if (file.size === 0 || file.size > 25 * 1024 * 1024) {
throw new Error('Choose a nonempty video of at most 25 MiB.')
}
const marks = parseTimes(times.value)
const figures = []
for (const mark of marks) {
const blob = await extractThumbnail(file, mark)
const url = URL.createObjectURL(blob)
previewUrls.push(url)
const image = new Image()
image.alt = `Video frame at ${mark} seconds`
image.src = url
await image.decode()
const caption = document.createElement('figcaption')
caption.textContent = `${mark} s`
const figure = document.createElement('figure')
figure.append(image, caption)
figures.push(figure)
}
results.replaceChildren(...figures)
status.textContent = `${marks.length} thumbnail(s) ready.`
} catch {
clearPreviews(results)
ffmpeg.terminate()
status.textContent = 'Could not extract thumbnails. Use a small valid video and times within its duration, then retry.'
} finally {
clearTimeout(deadline)
controls.disabled = false
running = false
}
})
-ss オプションはデコード前にシークします。FFmpeg のデフォルトの正確なシークでは、トランスコード時に指定位置より前のフレームを破棄します。動画のフレームは離散的な時刻に存在するため、フレーム間のタイムスタンプを指定しても補間フレームは生成されません。出力の幅は 320 ピクセルです。これはプレビュー抽出ツールであり、ファイル全体の整合性を検査するものではありません。先頭付近のサムネイルを抽出できても、動画の後半のパケットが正常であるとは確認できません。
複数のサムネイルを順次抽出
フォームのループは、一つの FFmpeg インスタンスで各タイムスタンプの処理を待ちます。複雑なバッチ API よりも、小さく自己完結した抽出関数を優先し、フレームごとに入力を再コピーします。要求したすべての画像のデコードが完了してから、結果をまとめて表示します。再送信すると前の結果は消去され、バッチが失敗した場合は一部のプレビューだけが残ることもありません。
wasm-thumbnails があるディレクトリで、以下を実行してください。コアのコピーで上書きするのはプロジェクト内の二つのアセットだけです。Vite はプロジェクトの dist ビルドを置き換えます。各処理は、直前の処理が成功した場合にのみ実行されます。
(
cd wasm-thumbnails &&
node copy-core.ts &&
corepack yarn vite build &&
corepack yarn vite preview --host 127.0.0.1 --port 4173 --strictPort
)
http://127.0.0.1:4173 を開き、2秒より長い動画を選んでください。タイムスタンプは 0.5, 1.5 のままにして、Extract thumbnails を押します。二つの画像が表示され、それぞれの下に指定時刻、上部に
2 thumbnail(s) ready. と表示されるはずです。サムネイルを一つだけ抽出するには、0.5 のように値を一つ指定します。サーバーは Ctrl+C で停止します。ポート 4173 が使用中の場合は、コマンドと URL で別のポートを指定してください。Vite のプレビューサーバーは、ローカルビルドの確認用です。
ウェブワーカーで UI の応答性を維持
ラッパーはすでにワーカーを所有しています。処理中はフォームのファイル選択、タイムスタンプ入力、送信ボタンを無効にし、重複送信を無視します。キャンセル機能はなく、新しい選択で実行中のバッチを追い越すこともできません。読み込みや抽出が停止した場合は、60秒の期限でワーカーを終了します。次の送信時には、新しいコアのインスタンスを読み込みます。
パフォーマンスのヒント
コアは最初の送信時に読み込まれ、バッチが成功した後は再利用されます。一時的な仮想ファイルは、抽出のたびに削除します。プレビュー URL は画像の表示中は有効で、入力が変わるか次の実行が始まると解放されます。ページを再読み込みするか閉じると、セッションは破棄されます。アプリはサムネイルをディスクに保存しません。
仮想ファイルを削除しても、Wasm ランタイムが割り当て済みメモリをすべて即座に OS に返すとは限りません。ワーカーは再利用のためにメモリ容量を保持することがあります。出力画像を小さくしても、高解像度の入力をデコードするコストはなくなりません。デモの制限を引き上げる前に、サポート対象のデバイスで代表的なファイルをテストしてください。
ブラウザー処理とサーバー処理の比較
ブラウザーでの抽出はアップロード前のプレビューに便利ですが、ダウンロード時間、メモリ使用量、処理速度はユーザーのデバイスに依存します。サーバーでの抽出には動画の送信が必要で、処理容量と保持方針の計画も必要です。結果の永続保存や一貫した処理リソースが必要なワークフローに適している場合があります。どちらの方法も、それだけですべてのコーデックへの対応や無制限の容量を実現するものではありません。
よくある問題のトラブルシューティング
- プレビューが表示されない: 動画が空でなく、サイズ制限内に収まり、デコード可能な映像ストリームを含むことを確認してください。
1.25のように秒を小数で入力し、00:00:01.25は使わないでください。終端以降のタイムスタンプではフレームが得られない場合があります。より前の時刻で再試行してください。 - コアの読み込みに失敗する:
/core/ffmpeg-core.jsと/core/ffmpeg-core.wasmの両方がビルドから配信されていることを確認してください。コアのバージョンを変更したら、コピーとビルドのコマンドを再実行してください。JavaScript ラッパーとコアは別々のバージョン番号を持つため、同じバージョン文字列である必要はありません。 - 抽出に失敗する、または期限に達する: より短く、解像度の低い動画を試してください。失敗時のハンドラーはプレビューを破棄してワーカーを終了し、次の送信を初期状態から開始できるようにします。
SharedArrayBufferエラー: 誤ってマルチスレッドのコアに置き換えていないか確認してください。このシングルスレッド構成でアセットが不足している場合、分離用ヘッダーを追加しても解決しません。
ローカルプレビューの先へ
対象デバイスで動画を処理できない場合は、ユーザーの明示的な同意を得たうえでアップロードするワークフローを検討してください。動画サムネイルのドキュメントでは、Transloadit のサーバー側の選択肢を説明しています。ローカルプレビューは単独でも役立つようにしてください。抽出に失敗しても、ほかの作業内容を失わずに別のファイルやタイムスタンプを選べる設計にします。
