WebAssembly でブラウザー内の音声を MP3 にエンコード
短い音声ファイルをアップロードせずに MP3 に変換します。このチュートリアルでは、FFmpeg.wasm、ローカル静的サーバー、キャンセルボタン、ダウンロードリンクを備えた小さなブラウザーアプリケーションを作成します。
ブラウザー内でエンコードすると、選択した音声はユーザーのデバイス内に留まります。ブラウザーはエンコーダーのアセットをダウンロードし、選択したファイルをメモリに読み込み、Web Worker で FFmpeg を実行します。エンコードには CPU とメモリを使うため、この例では入力を 25 MiB に制限し、一度に一つのファイルを処理します。
FFmpeg のパッケージ構成の選択
FFmpeg.wasm は FFmpeg を WebAssembly としてパッケージ化したものです。ここでは、シングルスレッド版の @ffmpeg/core@0.12.10 と
@ffmpeg/ffmpeg@0.12.15 を使います。ラッパーとコアのバージョン番号は別々です。両方に同じ番号を指定してインストールしても、有効なパッケージの組み合わせにはなりません。
- ローカル処理: アプリケーションには音声アップロード用のエンドポイントがありません。
- 応答性: ワーカーがメイン UI スレッドの外でエンコーダーを実行します。
- 形式のサポート: ここで使うデコーダーと MP3 エンコーダーは FFmpeg が提供します。
WebAssembly はネイティブと同等のエンコード速度を保証するものではありません。FFmpeg.wasm FAQ では、性能とメモリの制約を説明しています。サポート対象のデバイスで、代表的なファイルを使ってテストしてください。
ローカルプロジェクトのセットアップ
前提条件
Node.js は 24.x 系の 24.15 以降、または 26.x 系の 26.5 以降を使ってください。Bash と、WebAssembly およびモジュールワーカーに対応したブラウザーも必要です。この手順は Linux 上で Node.js 24.15.0、26.5.0、26.8.1、Yarn 4.12.0、Chromium 145 を使ってテストしています。これらはテスト済みのサーバーランタイムであり、ブラウザーのエンコーダーの要件ではありません。Node はネイティブの TypeScript サポート を使って
server.ts を直接実行するため、コンパイラーやバンドラーは不要です。
ファイルを作成する前に、node と
corepack に PATH が通っていることを確認してください。Node のディストリビューションに Corepack が含まれていない場合は、別途インストールしてください。以下のセットアップでは、Corepack に Yarn 4.12.0 を明示的に指定します。
最初は、破損していない短いモノラルまたはステレオの WAV を使ってください。サンプルレートは 44.1 kHz または 48 kHz とします。ほかの音声コンテナーは、固定したバージョンの FFmpeg コアに対応するデコーダーが含まれている場合に限り動作します。未対応のサンプルレートやチャンネル構成は、MP3 用にリサンプリングまたはダウンミックスされる場合があります。ファイル選択の accept
属性は利便性のためのもので、検証ではありません。ほかのブラウザーやモバイルデバイスでは、別途テストが必要です。
プロジェクトのセットアップ
プロジェクトを作成する親ディレクトリで、以下のブロックを Bash に貼り付けてください。webassembly-audio-encoder ディレクトリがすでに存在する場合は処理を拒否します。インストールに失敗した場合も含め、シェルの作業ディレクトリは元のままです。子ディレクトリのロックファイルで独立した Yarn プロジェクトを作成し、独自の設定ファイル名を使うことで、親プロジェクトの通常の
.yarnrc.yml 設定を継承しないようにします。
(
command -v node >/dev/null &&
command -v corepack >/dev/null &&
mkdir webassembly-audio-encoder &&
cd webassembly-audio-encoder &&
printf '%s\n' \
'{"private":true,"type":"module","packageManager":"yarn@4.12.0",' \
'"dependencies":{"@ffmpeg/ffmpeg":"0.12.15","@ffmpeg/core":"0.12.10","express":"5.1.0"}}' \
> package.json &&
printf '\n' > yarn.lock &&
printf '%s\n' 'nodeLinker: node-modules' 'enableGlobalCache: false' \
> .audio-yarnrc.yml &&
YARN_RC_FILENAME=.audio-yarnrc.yml corepack yarn@4.12.0 install &&
mkdir -p public/vendor/ffmpeg public/vendor/core &&
cp -R node_modules/@ffmpeg/ffmpeg/dist/esm/. public/vendor/ffmpeg/ &&
cp -R node_modules/@ffmpeg/core/dist/esm/. public/vendor/core/
)
ffmpeg ディレクトリは全体を保持してください。その JavaScript モジュールには、ラッパーのワーカーと相対インポート先が含まれます。両方の vendor ディレクトリには、このインストール済みパッケージ構成のファイルを使う必要があります。実行時に CDN への依存はなく、これらのブラウザー向け相対インポートにバンドラーも不要です。
設定ファイルの書き込み後にインストールやコピーが失敗した場合は、ディレクトリを保持したまま、報告されたエラーを解消し、同じ親ディレクトリから残りの手順を再試行してください。
(
cd webassembly-audio-encoder &&
YARN_RC_FILENAME=.audio-yarnrc.yml corepack yarn@4.12.0 install &&
mkdir -p public/vendor/ffmpeg public/vendor/core &&
cp -R node_modules/@ffmpeg/ffmpeg/dist/esm/. public/vendor/ffmpeg/ &&
cp -R node_modules/@ffmpeg/core/dist/esm/. public/vendor/core/
)
再試行では、アプリケーションのファイルを保持し、vendor 内のパッケージファイルを置き換えます。このプロジェクトで後から Yarn コマンドを実行する際も、同じ
YARN_RC_FILENAME セレクターを使ってください。
開発サーバーのセットアップ
以下を webassembly-audio-encoder/server.ts として保存してください。配信対象は public/ のみで、プロジェクトファイルは公開されません。ポート 3000 が空いている必要があります。Express 5 はバインドの失敗を listen コールバックに渡すため、このコードはエラーを出力し、ゼロ以外のステータスで終了します。
import { fileURLToPath } from 'node:url'
import express from 'express'
const app = express()
app.use(express.static(fileURLToPath(new URL('./public/', import.meta.url))))
app.listen(3000, '127.0.0.1', (error) => {
if (error) {
console.error(`Cannot start the audio server: ${error.message}`)
process.exitCode = 1
return
}
console.log('Open http://127.0.0.1:3000')
})
後述のファイルを作成したら、親ディレクトリからサーバーを起動してください。
(cd webassembly-audio-encoder && node server.ts)
http://127.0.0.1:3000 を開いてください。終了したら Ctrl+C でサーバーを停止します。シェルの作業ディレクトリは親ディレクトリのままです。このループバックサーバーは、ローカルでこの手順を試すためのものです。
エンコーダーの操作 UI の追加
以下を webassembly-audio-encoder/public/index.html として保存してください。
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Browser audio encoder</title>
</head>
<body>
<h1>Encode audio to MP3</h1>
<label for="uploader">Audio file, up to 25 MiB</label>
<input type="file" id="uploader" accept="audio/*" />
<button id="encodeButton" type="button">Encode audio</button>
<button id="cancelButton" type="button" disabled>Cancel</button>
<p id="status" role="status">Choose an audio file.</p>
<a id="download" download="output.mp3" hidden>Download MP3</a>
<script type="module" src="./index.js"></script>
</body>
</html>
以下を webassembly-audio-encoder/public/index.js として保存してください。試行ごとに専用のワーカーと仮想ファイルシステムを作成します。ワーカーを終了すると、変換に失敗した場合も含め、仮想ファイルとエンコーダーの状態が破棄されます。ダウンロード用に完成した Blob は、その URL が無効化されるまで利用できます。
import { FFmpeg } from './vendor/ffmpeg/index.js'
const uploader = document.getElementById('uploader')
const encodeButton = document.getElementById('encodeButton')
const cancelButton = document.getElementById('cancelButton')
const status = document.getElementById('status')
const download = document.getElementById('download')
let active = null
let downloadURL = null
function clearDownload() {
download.hidden = true
download.removeAttribute('href')
if (downloadURL !== null) URL.revokeObjectURL(downloadURL)
downloadURL = null
}
function cancelEncoding() {
if (active === null) return
active.canceled = true
active.ffmpeg.terminate()
}
async function encodeFile() {
if (active !== null) return
clearDownload()
const file = uploader.files?.[0]
if (!file || file.size === 0 || file.size > 25 * 1024 * 1024) {
status.textContent = 'Choose a nonempty audio file of at most 25 MiB.'
return
}
const job = { ffmpeg: new FFmpeg(), canceled: false }
active = job
uploader.disabled = true
encodeButton.disabled = true
cancelButton.disabled = false
status.textContent = 'Loading the encoder…'
// Also bound loading and worker failures that may never reply to the wrapper.
const deadline = setTimeout(() => {
job.ffmpeg.terminate()
}, 120_000)
try {
await job.ffmpeg.load({
coreURL: new URL('./vendor/core/ffmpeg-core.js', location.href).href,
wasmURL: new URL('./vendor/core/ffmpeg-core.wasm', location.href).href,
})
const input = new Uint8Array(await file.arrayBuffer())
if (job.canceled) return
await job.ffmpeg.writeFile('input.audio', input)
status.textContent = 'Encoding…'
const exitCode = await job.ffmpeg.exec(
['-i', 'input.audio', '-map', '0:a:0', '-vn', '-c:a', 'libmp3lame', '-b:a', '192k', 'output.mp3'],
60_000,
)
if (exitCode !== 0) throw new Error('Encoder failed or timed out')
const output = await job.ffmpeg.readFile('output.mp3')
if (!(output instanceof Uint8Array) || output.byteLength === 0) {
throw new Error('Encoder returned no audio')
}
downloadURL = URL.createObjectURL(new Blob([output], { type: 'audio/mpeg' }))
download.href = downloadURL
download.hidden = false
status.textContent = 'Done. Your MP3 is ready to download.'
} catch {
status.textContent = job.canceled
? 'Encoding canceled.'
: 'Encoding failed. Try a shorter supported audio file and check the encoder assets.'
} finally {
clearTimeout(deadline)
job.ffmpeg.terminate()
active = null
uploader.disabled = false
encodeButton.disabled = false
cancelButton.disabled = true
if (job.canceled) status.textContent = 'Encoding canceled.'
}
}
encodeButton.addEventListener('click', encodeFile)
cancelButton.addEventListener('click', cancelEncoding)
window.addEventListener('pagehide', () => {
cancelEncoding()
clearDownload()
})
window.addEventListener('pageshow', (event) => {
if (event.persisted && active === null) {
status.textContent = 'Choose an audio file to encode again.'
}
})
仮想ファイル名を固定することで、選択したファイル名が FFmpeg のオプションやパスとして扱われるのを防ぎます。明示的な音声マッピングで最初の音声ストリームを選択し、終了コードがゼロ以外の場合は、不完全な出力を正常なダウンロードとして提供しません。MP3 リンクは、次のエンコードを試行するか、ページが非表示になるまで有効です。このコマンドでは、-b:a 192k で MP3 の固定ビットレートを選択します。libmp3lame のオプションでは、ビットレートと可変ビットレートの品質設定を区別しています。
対応するローカルアセットの読み込み
FFmpeg ラッパーは、コピーした
vendor/ffmpeg/worker.js からモジュールワーカーを起動します。そのワーカーが同一オリジンから ESM コアをインポートし、Wasm ファイルを読み込みます。このシングルスレッドのコアには、別途 ffmpeg-core.worker.js や
SharedArrayBuffer を用意する必要はありません。@ffmpeg/core-mt に置き換える場合は、追加のワーカーとクロスオリジン分離の要件も実装する必要があります。
変換ごとのクリーンアップ
JavaScript 層はファイル選択とダウンロード URL を管理し、FFmpeg はデコードとエンコードを処理します。このファイル変換に AudioContext や AudioWorklet は不要です。
FFmpeg API リファレンスには、Promise ベースのファイル操作、実行タイムアウト、terminate() が記載されています。処理ごとに新しいワーカーを作ると初期化に時間がかかりますが、キャンセルと仮想ファイルのクリーンアップが簡単になります。
録音の変換と確認
冒頭と末尾の両方に聞き分けられる音がある短い WAV を選択し、Encode audio を押してください。エンコードが完了すると、ステータスに
Done. Your MP3 is ready to download.
と表示されます。Download MP3 を開いてください。保存した output.mp3 を音声プレーヤーで開き、最後まで聴いてください。長さ、チャンネル、内容が、選択した録音と一致していることを確認します。
次に別の録音を試し、変換に成功した後で、空のファイルや未対応のファイルを試してください。Encode audio を押すと、前のダウンロードリンクが消えるはずです。読み込み中とエンコード中にそれぞれ Cancel を押してください。その後、Encode audio が再び使えるはずです。別のページに移動してから戻ってください。古いダウンロードリンクが非表示のまま、再び変換できることを確認します。
エンコーダーが正常終了しても、破損した入力が完全だったことの証明にはなりません。FFmpeg は、途中で切れたファイルから音声を復元し、ゼロを返す場合があります。破損していない入力を使い、ダウンロードした録音を利用する前に全体を確認してください。
25 MiB の入力制限はこのデモの方針であり、ピークメモリ使用量を保証するものではありません。デコード後の音声とエンコーダーは、圧縮された入力よりはるかに多くのメモリを使う場合があります。コマンドには 60 秒のエンコードタイムアウトがあり、外側の 120 秒の期限で、停止した読み込みやワーカー呼び出しを終了します。大きなファイルでは、測定せずに制限を引き上げるのではなく、サーバー側での処理を検討してください。
vendor ファイルとアプリケーションコードは一緒に保持し、固定したパッケージを更新する際は変換の確認を繰り返してください。この例にはアップロードや保存用のエンドポイントはなく、ダウンロードはブラウザーによって保存されます。
アップロードとサーバー側の処理が必要なワークフローには、Transloadit の音声エンコーディングサービスをご覧ください。
