Node.js で FFmpeg 出力をストリーミング
Node.js から FFmpeg を起動し、エンコード済みのバイト列を一時ファイルへストリーミングして、エンコードと書き込みの両方が完了したときにのみ結果を公開します。この手順では、動画を H.264 に変換し、音声があれば AAC に変換するローカルコマンドを作成します。既存の出力の上書きを拒否し、失敗時やキャンセル時には処理途中のデータを削除します。
ストリーミング対象の選択
入力には、完全なローカルファイルを使います。FFmpeg が直接開くためシークでき、メタデータが末尾にある MP4/MOV ファイルも処理できます。出力は stdout を通じて Node.js の書き込み可能ストリームへ送られます。元の入力と完成した単一の出力ファイルが残り、アップロードサーバーは介在しません。
パイプではシークできません。MP4 出力には +frag_keyframe+empty_moov を使い、最初のヘッダーと後続のフラグメントを書き込みます。+faststart を使う通常の MP4 には、シーク可能な出力ファイルが必要です。FFmpeg の MP4 マルチプレクサーのドキュメントでは、フラグメント化と互換性のトレードオフを説明しています。一部のプレーヤーや編集ソフトは、フラグメント化 MP4 を受け付けません。この出力形式を選ぶ前に、利用先で確認してください。
ここでのストリーミングとは、バイト列の転送方法を指します。エンコードはマシンの性能が許す限り高速に実行され、最終的なファイル名は完了後にのみ現れます。これはバッチ変換であり、リアルタイムのエンコード速度、ライブ再生、アダプティブストリーミングを保証するものではありません。
ローカルでのサンプル準備
Linux、Node.js 24 または 26、libx264 と aac のエンコーダーを備えた FFmpeg ビルド、および ffprobe を用意してください。このサンプルは Node の組み込み TypeScript サポートを使うため、npm パッケージは不要です。不足しているツールは、Node.js のダウンロードと
FFmpeg のダウンロードの各ページからインストールしてください。以下のコマンドでは Bash と、ハードリンクをサポートするローカルファイルシステムを使います。信頼できる動画で始めてください。このコマンドはアップロード用のサンドボックスではありません。
ツールを確認します。
node --version &&
ffmpeg -version &&
ffprobe -version &&
ffmpeg -hide_banner -encoders
エンコーダーの一覧に libx264 と aac が含まれていることを確認してください。テスト済みの組み合わせは、Linux 上の Node.js 26.8.1 と FFmpeg 9.0.1、および Ubuntu 24.04 上の Node.js 24.13.0、26.5.0 と FFmpeg 6.1.1 です。
新しいディレクトリと、映像とトーン音声を含む三秒のサンプルを作成します。&& による連結は維持してください。ディレクトリがすでに存在する場合や移動に失敗した場合は、その中に何も書き込まれません。-n フラグもサンプルの置き換えを拒否します。
mkdir node-ffmpeg-demo &&
cd node-ffmpeg-demo &&
printf '{"type":"module"}\n' > package.json &&
ffmpeg -nostdin -n -v error \
-f lavfi -i testsrc2=size=320x180:rate=24 \
-f lavfi -i sine=frequency=440:sample_rate=48000 \
-t 3 -c:v libx264 -threads 2 -pix_fmt yuv420p -c:a aac input.mp4
以降のコマンドも、このディレクトリで実行してください。サンプルでは意図的に通常の MP4 ファイルを使っています。ファイル名を FFmpeg に渡すことで、pipe:0 経由で入力する場合のシーク制限を回避します。
FFmpeg と書き込み可能ストリームの接続
以下のスクリプト全体を transcode.ts として保存してください。出力ディレクトリは必要に応じて作成されます。エンコード中に別のプロセスが出力先を作成した場合でも、既存の出力先は保持されます。
import { spawn } from 'node:child_process'
import { createWriteStream } from 'node:fs'
import { link, mkdir, mkdtemp, rm, stat } from 'node:fs/promises'
import { dirname, join, resolve } from 'node:path'
import { pipeline } from 'node:stream/promises'
import { parseArgs } from 'node:util'
function diagnosticCode(error: unknown): string {
if (typeof error === 'object' && error !== null && 'code' in error) {
const code = error.code
if (
typeof code === 'string' &&
['ENOENT', 'EACCES', 'EEXIST', 'ENOSPC', 'ABORT_ERR'].includes(code)
) return code
}
return 'PROCESSING_FAILED'
}
function logCleanupFailure(error: unknown): void {
console.error('Temporary file cleanup failed', { code: diagnosticCode(error) })
}
async function withOutputFile(
outputPath: string,
signal: AbortSignal,
produce: (temporary: string) => Promise<void>,
): Promise<string> {
signal.throwIfAborted()
const destination = resolve(outputPath)
await mkdir(dirname(destination), { recursive: true })
const directory = await mkdtemp(join(dirname(destination), '.ffmpeg-'))
const temporary = join(directory, 'output.mp4')
try {
signal.throwIfAborted()
await produce(temporary)
const info = await stat(temporary)
if (info.size === 0) throw new Error('FFmpeg produced an empty file')
signal.throwIfAborted()
// An exclusive hard link publishes on the same filesystem without copying or replacing data.
await link(temporary, destination)
return destination
} finally {
// A cleanup warning must not replace the original processing error or undo a published file.
await rm(directory, { recursive: true, force: true }).catch(logCleanupFailure)
}
}
async function streamTranscode(
inputPath: string,
outputPath: string,
signal: AbortSignal,
executable: string,
): Promise<string> {
return withOutputFile(outputPath, signal, async (temporary) => {
signal.throwIfAborted()
const child = spawn(executable, [
'-nostdin', '-v', 'error', '-xerror',
'-threads', '2', '-i', resolve(inputPath),
'-map', '0:v:0', '-map', '0:a:0?',
'-filter_threads', '1', '-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2',
'-c:v', 'libx264', '-threads', '2', '-preset', 'medium', '-crf', '23',
'-pix_fmt', 'yuv420p', '-c:a', 'aac', '-b:a', '128k',
'-movflags', '+frag_keyframe+empty_moov', '-f', 'mp4', 'pipe:1',
], { stdio: ['ignore', 'pipe', 'pipe'] })
let diagnostics = ''
let processError: Error | undefined
child.stderr.setEncoding('utf8')
child.stderr.on('data', (chunk: string) => {
diagnostics = (diagnostics + chunk).slice(-8000)
})
const closed = new Promise<void>((resolveClosed, reject) => {
child.once('error', (error) => {
processError = error
})
child.once('close', (code, killedBy) => {
if (processError) reject(processError)
else if (code === 0) resolveClosed()
else reject(new Error(`FFmpeg failed (${killedBy ?? code}): ${diagnostics}`))
})
})
const io = new AbortController()
const written = pipeline(
child.stdout,
createWriteStream(temporary, { flags: 'wx' }),
{ signal: io.signal },
)
const stop = (): void => {
io.abort()
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL')
}
signal.addEventListener('abort', stop, { once: true })
if (signal.aborted) stop()
try {
// Neither a clean stdout EOF nor FFmpeg exiting alone proves that the job succeeded.
await Promise.all([closed, written])
signal.throwIfAborted()
} catch (error) {
stop()
await Promise.allSettled([closed, written])
signal.throwIfAborted()
throw error
} finally {
signal.removeEventListener('abort', stop)
}
})
}
let verbose = false
async function main(): Promise<void> {
const { values, positionals } = parseArgs({
allowPositionals: true,
options: {
ffmpeg: { type: 'string', default: 'ffmpeg' },
timeout: { type: 'string', default: '120' },
verbose: { type: 'boolean', default: false },
},
})
verbose = values.verbose
const [input, output] = positionals
const seconds = Number(values.timeout)
if (
!input || !output || positionals.length !== 2 ||
!Number.isFinite(seconds) || seconds <= 0 || seconds > 86400
) {
throw new Error('Usage: node transcode.ts [--timeout seconds] [--verbose] -- input output.mp4')
}
const controller = new AbortController()
const stop = (): void => controller.abort(
Object.assign(new Error('Transcoding cancelled or timed out'), { code: 'ABORT_ERR' }),
)
process.once('SIGINT', stop)
process.once('SIGTERM', stop)
const timer = setTimeout(stop, seconds * 1000)
try {
const outputFile = await streamTranscode(input, output, controller.signal, values.ffmpeg)
console.log(`Transcoding completed: ${outputFile}`)
} finally {
clearTimeout(timer)
process.off('SIGINT', stop)
process.off('SIGTERM', stop)
}
}
main().catch((error: unknown) => {
console.error('Transcoding failed', { code: diagnosticCode(error) })
// Detailed diagnostics are opt-in because FFmpeg messages can include local paths and metadata.
if (verbose && error instanceof Error) console.error(error.message)
process.exitCode = 1
})
spawn() は引数の配列を受け取り、シェルを実行しません。pipeline() はバックプレッシャーを適用します。書き込み可能ストリームの処理が追いつかなくなると、Node は FFmpeg 出力の読み取りを停止し、最終的にパイプが FFmpeg を待機させます。ストリームのエラーも伝播します。Node のストリームパイプラインのドキュメントを参照してください。
最初の映像ストリームは必須です。? は 0:a:0? 内で、最初の音声ストリームを任意にします。これは
FFmpeg のストリームマッピング規則に従います。H.264 の yuv420p 出力の縦横が偶数になるよう、必要に応じてパディングで行または列を追加します。字幕、追加の音声トラック、その他の映像ストリームは含めません。
成功するには、子プロセスの
close イベントが終了コードゼロで発生し、かつ書き込みパイプラインが完了する必要があります。書き込みに失敗すると FFmpeg を停止し、FFmpeg プロセスが失敗すると書き込みを中止します。コードは両方の処理が終了するのを待ってから、一時データを削除します。その後、排他的なハードリンクによって、ファイル全体を再コピーせずに完成ファイルを公開します。この方法にはハードリンクのサポートが必要であり、電源喪失時の耐久性は保証しません。
変換の実行と確認
サンプルを実行し、実際のストリームを確認します。
node transcode.ts -- input.mp4 output.mp4 &&
ffprobe -v error -show_entries stream=codec_name,codec_type,width,height \
-show_entries format=duration -of json output.mp4
出力の絶対パスを含む完了メッセージが表示されるはずです。プローブ結果では、320 × 180 の H.264 映像、AAC 音声、約三秒の長さを確認してください。音声のない動画では、映像ストリームだけが生成されます。独自の入力を使う場合は、パスを引用符で囲み、新しい出力名を指定してください。例:node transcode.ts -- "my clip.mov" "my clip encoded.mp4"。
同じコマンドをもう一度実行して、上書きポリシーを確認してください。終了コード 1 で終了し、EEXIST が報告されます。元の出力は変更されません。拒否されるのは公開時なので、二回目の実行でもエンコードに時間がかかります。別の結果を保存するには、異なるファイル名を選んでください。
編集ソフトで開ける通常の MP4 にするには、完成した出力を別の新しいファイルにリマックスします。
ffmpeg -nostdin -n -v error -i output.mp4 -map 0 -c copy -movflags +faststart compatible.mp4
これは再エンコードせずに、エンコード済みストリームをコピーします。compatible.mp4 に直接書き込むため、リマックスが中断されると、そこに不完全なファイルが残ることがあります。-n は既存の出力先を拒否します。再試行する前に、不完全なファイルを自分で確認するか削除してください。FFmpeg のバージョンによっては、上書きを拒否してもステータスゼロを返すため、ステータスだけに頼らず、診断メッセージとファイルを確認してください。この追加ファイルの分もディスク容量が必要です。
失敗とリソース制限への対処
Ctrl+C、SIGTERM、またはデフォルトの 120 秒の制限時間により、処理を中止して一時出力を削除します。大きな信頼できる入力には、--timeout 600 で制限時間を延長してください。公開が始まった後は、完成した出力先が残る場合があります。キャンセルによって削除されることはありません。SIGKILL、マシンのクラッシュ、または権限不足によるクリーンアップの失敗で、.ffmpeg-* ディレクトリが残り、手動確認が必要になることがあります。
デフォルトのエラー行には、検証済みのコードだけが含まれます。ローカルでのデバッグには --verbose を追加してください。FFmpeg のエラーには、診断情報の末尾から最大 8,000 文字が含まれます。この詳細出力を HTTP クライアントに転送しないでください。
| 結果 | 確認事項 |
|---|---|
ENOENT | FFmpeg 実行ファイルが見つかりません。必要に応じて --ffmpeg /absolute/path/to/ffmpeg を使ってください。 |
PROCESSING_FAILED | --verbose を使い、入力が無効または存在しない、エンコーダーが利用できない、メディアがサポートされていないといった問題を調べてください。 |
EEXIST | 新しい出力ファイル名を選んでください。 |
EACCES または ENOSPC | ディレクトリの権限とディスクの空き容量を確認してください。 |
ABORT_ERR | 処理がキャンセルされたか、制限時間を超えました。 |
-xerror は、エラーが報告されると FFmpeg を停止させますが、変換の成功は入力元の完全性や安全性の証明にはなりません。途中で切れたコンテナーでも、デコード可能なフレームが残っているものがあります。アプリケーション側で想定する長さやチェックサムがわかっている場合は、別途検証してください。
このコマンドは一回の変換を実行し、要求するコーデックスレッド数と保持する診断情報の量を制限し、Node 内で動画全体をバッファリングしないようにしています。それでも FFmpeg には、デコーダーとエンコーダー用のメモリが必要です。バックプレッシャーはメモリや CPU の使用量制限ではありません。出力サイズにも上限はありません。アップロード API では、まず入力を一時保存し、アップロードとディスクの制限を適用したうえで、OS のリソース制限下で上限付きのキューを通して処理を実行してください。このローカルストリームパイプラインは処理工程であり、完全な公開サービスではありません。
