FFmpeg.wasm と WebCodecs によるウェブカメラフィルターの実験
ブラウザーで FFmpeg のグレースケールフィルターを実行する、ローカルのウェブカメラプレビューを作成します。カメラのプレビューとフィルター適用後のキャンバスを表示し、操作ボタンで処理を停止、再開できます。小さなフレームごとに PNG を FFmpeg.wasm に渡して結果を受け取るため、CPU 負荷が高く、フレームレートが低い実験になります。
フィルターを通るフレームの流れ
処理経路は、カメラ映像 → VideoFrame → PNG → FFmpeg のメモリー内ファイルシステム → グレースケール PNG → キャンバスです。FFmpeg の hue=s=0 フィルターで彩度を取り除きます。アプリは各処理の完了を待ってから次のフレームを要求し、カメラの全フレームを処理キューに入れることはありません。結果を受け取るたびに FFmpeg ワーカーを終了するため、次のフレームではコアを再読み込みします。このループで、同じバージョン固定のコアに対して exec() を繰り返し呼び出すと、WebAssembly のメモリーエラーが発生する場合があります。ワーカーごとに実行を一度に限定すると、このエラーを回避できますが、起動処理の負荷が増えます。
WebAssembly によって FFmpeg のフィルターをローカルで再利用できますが、このパイプラインがネイティブの FFmpeg と同じ速度になるわけではありません。ffmpeg.wasm の FAQでも、この性能差を明示的に注意喚起しています。PNG のエンコード、デコード、コピーも処理負荷を増やします。
ここでは、WebCodecs から映像の VideoFrame スナップショットを取得します。ピクセルを描画した後で、このスナップショットを閉じます。VideoEncoder や VideoDecoder は使用せず、この例でハードウェアアクセラレーションが利用されるとは主張しません。出力はキャンバスのプレビューであり、録画データや、ビデオ通話向けのフィルター適用済み MediaStream は生成しません。
ブラウザー対応
この手順は、Linux 上の Chromium 145.0.7632.6 で、合成カメラを使用してテストしました。物理ウェブカメラや、ほかのブラウザーではテストしていません。コードでは、カメラを開く前に VideoFrame、OffscreenCanvas、requestVideoFrameCallback() を確認します。
このバージョンでは、MediaStreamTrackProcessor や MediaStreamTrackGenerator を使わず、再生中の動画からスナップショットを取得します。これらの挿入可能なストリームの API は、ブラウザー間で window とワーカーへの公開状況が異なります。この逐次処理のプレビューには、フレームコールバックで十分です。
セキュリティ要件
localhost 経由でページを開いてください。カメラへのアクセスにはセキュアコンテキストとユーザーの許可が必要です。通常のリモートオリジンから配信する場合は HTTPS が必要です。index.html を直接開かないでください。
シングルスレッド版の @ffmpeg/core を、ページと同じローカルサーバーから配信します。SharedArrayBuffer やクロスオリジン分離ヘッダーは不要です。別途提供される @ffmpeg/core-mt ビルドには、共有メモリー、クロスオリジン分離、追加のワーカーアセットが必要です。このビルドへの切り替えは、この手順では扱いません。シングルスレッドという説明は FFmpeg コアについてのもので、ラッパーはコアを Web Worker 内で実行します。
ローカルプロジェクトの作成
Bash 互換のターミナル、Node.js 22.12 以降、Yarn の実行に使える Corepack が必要です。テスト環境では Node.js 26.8.1、Yarn 4.12.0、Vite 8.3.0 を使用しました。Vite がモジュールとワーカーを処理します。HTML エントリーポイントについては、手動インストールガイドで説明されています。
webcam-filter が存在しない親ディレクトリから、次のコマンドを実行してください。&& で連結した処理は途中で失敗すると停止し、mkdir は既存プロジェクトの上書きを拒否します。ブロック全体が成功した場合にのみ、先へ進んでください。コアファイルはバージョンを固定したパッケージからコピーするため、ブラウザーがサードパーティの CDN からエンジンを取得することはありません。
mkdir webcam-filter &&
cd webcam-filter &&
printf '{"private":true,"type":"module","packageManager":"yarn@4.12.0"}\n' > package.json &&
printf 'nodeLinker: node-modules\n' > .yarnrc.yml &&
touch yarn.lock &&
corepack yarn add --exact @ffmpeg/ffmpeg@0.12.15 @ffmpeg/core@0.12.10 &&
corepack yarn add --dev --exact vite@8.3.0 &&
mkdir -p public/ffmpeg &&
cp node_modules/@ffmpeg/core/dist/esm/ffmpeg-core.{js,wasm} public/ffmpeg/
webcam-filter に vite.config.ts を作成してください。FFmpeg ラッパーを依存関係の事前バンドルから除外することで、モジュールワーカーの URL とパッケージの関連付けを維持します。
import { defineConfig } from 'vite'
export default defineConfig({
optimizeDeps: { exclude: ['@ffmpeg/ffmpeg'] },
})
同じディレクトリに index.html を作成してください。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="icon" href="data:," />
<title>FFmpeg webcam experiment</title>
</head>
<body>
<h1>FFmpeg webcam experiment</h1>
<button id="start" type="button">Start camera</button>
<button id="stop" type="button" disabled>Stop</button>
<p id="status" role="status">Ready.</p>
<figure>
<figcaption>Camera</figcaption>
<video id="camera" aria-label="Camera preview" width="320" height="240" muted playsinline></video>
</figure>
<figure>
<figcaption>FFmpeg grayscale</figcaption>
<canvas id="output" aria-label="Grayscale preview" width="320" height="240"></canvas>
</figure>
<script type="module" src="/main.ts"></script>
</body>
</html>
フレームを一つずつ処理
main.ts を作成してください。開始するたびに、そのセッション専用の FFmpeg ラッパーとカメラストリームを作成します。停止すると現在のセッションは即座に解除されます。後から完了する Promise は、そのセッションがまだ有効な場合にのみプレビューを更新できます。これは、停止後に許可の取得、エンジンの読み込み、PNG のデコードが完了した場合に重要です。
import { FFmpeg } from '@ffmpeg/ffmpeg'
const startButton = document.querySelector('#start')
const stopButton = document.querySelector('#stop')
const status = document.querySelector('#status')
const camera = document.querySelector('#camera')
const output = document.querySelector('#output')
if (
!(startButton instanceof HTMLButtonElement) ||
!(stopButton instanceof HTMLButtonElement) ||
!(status instanceof HTMLElement) ||
!(camera instanceof HTMLVideoElement) ||
!(output instanceof HTMLCanvasElement)
) {
throw new Error('Missing demo elements')
}
const outputContext = output.getContext('2d')
if (!outputContext) throw new Error('Canvas 2D is unavailable')
interface Session {
ffmpeg: FFmpeg
canvas: OffscreenCanvas
stream?: MediaStream
callbackId?: number
}
let current: Session | undefined
const loadFFmpeg = async (session: Session): Promise<void> => {
if (session.ffmpeg.loaded) return
await session.ffmpeg.load({
coreURL: new URL('/ffmpeg/ffmpeg-core.js', location.href).href,
wasmURL: new URL('/ffmpeg/ffmpeg-core.wasm', location.href).href,
})
}
const stop = (message = 'Stopped.'): void => {
const session = current
if (!session) return
current = undefined
if (session.callbackId !== undefined) {
camera.cancelVideoFrameCallback(session.callbackId)
}
session.ffmpeg.terminate()
for (const track of session.stream?.getTracks() ?? []) track.stop()
camera.pause()
camera.srcObject = null
outputContext.clearRect(0, 0, output.width, output.height)
status.textContent = message
startButton.disabled = false
stopButton.disabled = true
}
const schedule = (session: Session): void => {
if (current !== session) return
session.callbackId = camera.requestVideoFrameCallback((_now, metadata) => {
session.callbackId = undefined
void filterFrame(session, metadata.mediaTime)
})
}
const filterFrame = async (session: Session, mediaTime: number): Promise<void> => {
try {
if (current !== session) return
const context = session.canvas.getContext('2d')
if (!context) throw new Error('Canvas 2D is unavailable')
const frame = new VideoFrame(camera, { timestamp: Math.round(mediaTime * 1_000_000) })
try {
context.drawImage(frame, 0, 0, 320, 240)
} finally {
frame.close()
}
const blob = await session.canvas.convertToBlob({ type: 'image/png' })
const bytes = new Uint8Array(await blob.arrayBuffer())
if (current !== session) return
await loadFFmpeg(session)
if (current !== session) return
await session.ffmpeg.writeFile('in.png', bytes)
const code = await session.ffmpeg.exec([
'-y', '-i', 'in.png', '-vf', 'hue=s=0', '-frames:v', '1', '-update', '1', 'out.png',
])
if (code !== 0) throw new Error('FFmpeg failed')
const data = await session.ffmpeg.readFile('out.png')
if (!(data instanceof Uint8Array) || data.length === 0) {
throw new Error('FFmpeg produced no image')
}
const bitmap = await createImageBitmap(
new Blob([new Uint8Array(data)], { type: 'image/png' }),
)
try {
if (current !== session) return
outputContext.drawImage(bitmap, 0, 0)
status.textContent = 'Filtering…'
} finally {
bitmap.close()
}
// This per-frame experiment uses one exec() per worker.
session.ffmpeg.terminate()
schedule(session)
} catch {
if (current === session) stop('Filter failed. Start again to retry.')
}
}
startButton.onclick = async () => {
if (current) return
if (
!navigator.mediaDevices?.getUserMedia ||
typeof VideoFrame !== 'function' ||
typeof OffscreenCanvas !== 'function' ||
typeof createImageBitmap !== 'function' ||
typeof camera.requestVideoFrameCallback !== 'function' ||
typeof Worker !== 'function' ||
typeof WebAssembly !== 'object'
) {
status.textContent = 'Required browser APIs are unavailable. Use a supported browser on localhost.'
return
}
const session: Session = { ffmpeg: new FFmpeg(), canvas: new OffscreenCanvas(320, 240) }
current = session
startButton.disabled = true
stopButton.disabled = false
status.textContent = 'Loading FFmpeg…'
let failureMessage = 'Could not load FFmpeg. Check the local server and engine files, then retry.'
try {
await loadFFmpeg(session)
if (current !== session) return
status.textContent = 'Requesting camera…'
failureMessage = 'Could not open camera. Check camera permission and availability, then retry.'
const stream = await navigator.mediaDevices.getUserMedia({
audio: false,
video: { width: { ideal: 320 }, height: { ideal: 240 }, frameRate: { ideal: 5 } },
})
// getUserMedia has no abort signal; release a stream granted after Stop.
if (current !== session) {
for (const track of stream.getTracks()) track.stop()
return
}
session.stream = stream
const track = stream.getVideoTracks()[0]
if (!track) throw new Error('No video track')
track.addEventListener('ended', () => {
if (current === session) stop('Camera ended. Start again to retry.')
}, { once: true })
camera.srcObject = stream
await camera.play()
if (current !== session) return
status.textContent = 'Waiting for a frame…'
schedule(session)
} catch {
if (current === session) stop(failureMessage)
}
}
stopButton.onclick = () => stop()
window.addEventListener('pagehide', () => stop())
カメラの解像度とフレームレートは希望値であり、保証値ではありません。固定サイズのキャンバスに描画するため、カメラがより大きな映像や異なるアスペクト比の映像を返しても、すべての入力を 320 × 240 に拡大縮小します。-update 1 オプションは出力画像を一つ書き出し、-y はその一時ファイル名での上書きを許可します。各フレームの処理後、または停止時や失敗時にワーカーを終了すると、ワーカーのメモリー内ファイルシステムが解放されます。アプリは画像をディスクに保存しません。VideoFrame.close() と
ImageBitmap.close() で、作成した画像リソースを解放します。
プレビューの実行と停止
webcam-filter から、サーバーをフォアグラウンドで起動してください。
corepack yarn vite --host 127.0.0.1
Vite が表示したローカル URL を開いてください。Start camera をクリックし、カメラへのアクセスを許可します。Loading FFmpeg…、Requesting camera… の後、最初のグレースケールフレームが表示されると、ステータスが Filtering… に変わります。色の付いた物をカメラに映して、二つのプレビューを比較してください。フレームはブラウザー内にとどまり、このアプリがアップロードや録画を行うことはありません。
Stop をクリックすると、このアプリのカメラトラックを停止し、FFmpeg ワーカーを終了して、プレビューを消去します。初期化中に停止した場合も、Start camera が再び使えるようになります。ブラウザーには、応答待ちのカメラ許可プロンプトを閉じる API がありません。停止後に許可した場合は、ページを更新せずに、遅れて取得したストリームを停止します。別のページに移動する際もクリーンアップを実行します。終了したら、Ctrl+C でターミナルのサーバーを停止してください。
許可が拒否された場合は、カメラの許可と利用可否を確認するよう促すエラーが表示されます。ブラウザーのサイト設定でアクセスを許可し、Start camera をもう一度クリックしてください。エンジンファイルがない場合は、カメラへのアクセスを要求する前に読み込みエラーが発生します。public/ffmpeg 配下に両方のファイルがあることを確認してください。処理エラーが発生すると、セッションが停止し、Filter failed. Start again to retry. が表示されます。カメラが終了した場合のメッセージは
Camera ended. Start again to retry. です。
プレビューに FFmpeg を使うべきかの判断
このループでは、FFmpeg が処理中の間、カメラのフレームをスキップします。要求するフレームレートを下げると負荷を減らせますが、毎秒五フレームを要求しても、フィルター適用済みフレームが毎秒五フレーム得られるとは限りません。解像度を上げたりフィルターを追加したりする前に、対象のハードウェアで PNG の受け渡しを含む処理全体を計測してください。マルチスレッド版コアでも、画像変換やデータコピーはなくなりません。
グレースケールのカメラプレビューには、Canvas 2D フィルターや WebGL シェーダーを適用すれば、PNG とファイルシステムを経由する処理を避けられます。この FFmpeg.wasm 版は、ファイルベースの API を学んだり、小さなスナップショットで FFmpeg フィルターを試したりする用途に使ってください。録画、音声、WebRTC 向けのフィルター適用済みストリームには、別の出力経路が必要です。
