cURL でリモートメディアを FFmpeg にストリーミング
cURL による HTTP ダウンロードをパイプで FFmpeg に渡すと、入力動画のコピーをローカルに保存せずにサムネイルと音声を抽出できます。MP4 は逐次読み取りに対応している必要があります。このチュートリアルでは、内容が既知のテスト用クリップを作成して HTTP で配信し、そのレスポンスから JPEG と WAV ファイルを生成します。
概要
Linux 上の Bash、cURL、Python 3、および libx264 と AAC のエンコーダーを備えた FFmpeg ビルドを使用します。以下のコマンドは FFmpeg 6.1.1 と 9.0.1 でテスト済みです。Python はローカル HTTP サーバー用のため、適切なリモート URL がすでにあれば不要です。
この例では、moov メタデータをメディアデータより前に置いた「faststart」MP4 を作成します。この配置については、FFmpeg の
MP4 ドキュメントで説明されています。パイプでは前の位置にシークできないため、末尾にメタデータがある通常の MP4 は、cURL がファイル全体を送信した後でも処理に失敗することがあります。配置が不明な場合は、後述の先にダウンロードする例を使用してください。-f mp4 を追加しても形式を指定するだけで、入力をシークできるようにはなりません。
各ブロックは、Bash で同じ親ディレクトリから実行してください。丸括弧内でのシェルオプションの変更はサブシェル内に限定されます。各処理ブロックには新しい出力ディレクトリが必要で、既存のディレクトリへの再実行は拒否されます。失敗すると、その新しいディレクトリに不完全なファイルが残ることがあります。使用前に内容を確認し、再試行には別の新しいディレクトリを選んでください。
パイプラインの設定
クリップと HTTP 配信元の準備
6.4 秒のクリップを作成します。最初の二秒は赤、次の二秒はライム色、最後は青です。音声は最後の 0.2 秒に短い 880 Hz のトーンが鳴るまで無音なので、音声の抽出が不完全であれば耳で確認できます。
(
set -euo pipefail
mkdir curl-media-demo
ffmpeg -nostdin -n -hide_banner -loglevel warning -filter_threads 1 \
-f lavfi -i "color=c=red:s=160x90:r=10:d=6.4" \
-f lavfi -i "aevalsrc='if(gte(t,6.2),0.25*sin(2*PI*880*t),0)':s=48000:d=6.4" \
-vf "drawbox=c=lime:t=fill:enable='gte(t,2)',drawbox=c=blue:t=fill:enable='gte(t,4)'" \
-map 0:v:0 -map 1:a:0 -c:v libx264 -pix_fmt yuv420p -threads 1 \
-c:a aac -movflags +faststart curl-media-demo/input.mp4
)
このターミナルで、ループバックアドレスを使い、テストデータ用ディレクトリだけを配信します。
(
set -eu
test -f curl-media-demo/input.mp4
python3 -m http.server 8765 --bind 127.0.0.1 --directory curl-media-demo
)
サーバーを起動したまま、以降のブロックは別のターミナルで実行してください。ポート 8765 が使用中なら、空いているポートを選び、サーバーのコマンドと URL の両方を変更します。終了したら Ctrl+C でサーバーを停止してください。
一度のダウンロードからサムネイルと音声を抽出
別のターミナルで同じ親ディレクトリに戻り、次を実行します。
(
set -euo pipefail
mkdir outputs
curl -fsSL "http://127.0.0.1:8765/input.mp4" | \
ffmpeg -nostdin -n -hide_banner -loglevel warning -filter_threads 1 -i pipe:0 \
-map 0:v:0 -vf "fps=1" -c:v mjpeg -q:v 2 -threads 1 -frame_pts 1 \
outputs/thumbnail_%03d.jpg \
-map 0:a:0 -c:a pcm_s16le outputs/audio.wav
)
このテストデータでは、thumbnail_000.jpg から thumbnail_005.jpg までの
160×90 の JPEG が六枚生成される想定です。最初の二枚は赤、次の二枚はライム色、最後の二枚は青です。outputs/audio.wav を再生してください。6.4 秒の録音の終わり近くでトーンが鳴るまでは無音になるはずです。AAC のデコードにより、WAV の末尾に少量のパディングが加わることがあります。
仕組み
pipe:0 は標準入力を読み取ります。-map オプションで最初の映像ストリームと音声ストリームを明示的に選択し、それぞれを個別に出力します。音声のない動画では、必須の音声マッピングが失敗するため、WAV が黙って省略されることはありません。新規ディレクトリの確認は、以前の実行で作成された画像シーケンスを保護します。FFmpeg の -n は MP4 と WAV のファイル名を保護しますが、image2 シーケンスでは個々の JPEG が上書きされることがあります。ディレクトリの保護処理を残し、これらの例は順番に実行してください。
fps フィルターはフレームを間引くか複製して、毎秒一フレームを生成します。デフォルトの丸め処理では、このテストデータから六フレームが得られるため、最後の一秒未満の部分に個別のサムネイルは生成されません。-frame_pts 1 は、出力タイムベースでの出力表示タイムスタンプをファイル名の番号に使用します。ここではタイムベースが一秒なので、番号は出力時刻の 0–5 秒を表します。元のフレーム番号ではなく、選ばれるソースフレームの正確な位置を保証するものでもありません。image2 のオプションを参照してください。
cURL の -f は、404 などの HTTP エラーで転送を失敗させます。一方、-sS は進捗表示を非表示にし、エラーメッセージは残します。Bash の pipefail は、FFmpeg が正常終了してもダウンロードの失敗を伝播します。どちらのオプションも、サーバーが破損のないメディアを送信した証明にはなりません。
応用例
シーンの変化を選択して時刻を記録
一定間隔ではなく色の変化をサンプリングするには、別途ダウンロードし、新しいディレクトリに出力します。
(
set -euo pipefail
mkdir scenes
curl -fsSL "http://127.0.0.1:8765/input.mp4" | \
ffmpeg -nostdin -n -hide_banner -loglevel warning -filter_threads 1 -i pipe:0 \
-map 0:v:0 \
-vf "select='gt(scene,0.3)',metadata=print:key=lavfi.scene_score:file=scenes/time.txt" \
-fps_mode vfr -c:v mjpeg -q:v 2 -threads 1 scenes/scene_%03d.jpg
)
このクリップでは、scene_001.jpg はライム色、scene_002.jpg は青になる想定です。対応する pts_time の値は、scenes/time.txt 内で 2 秒と 4 秒です。これらは FFmpeg の入力タイムライン上で選択されたフレームのタイムスタンプで、このテストデータではゼロから始まります。実際の時計に基づく撮影時刻ではなく、JPEG の連番もタイムスタンプではありません。
select フィルターはシーンスコアをしきい値と比較します。0.3 を超えるスコアは視覚的な変化を検出するための経験則であり、意味上のシーン境界ではありません。クリップによっては、フレームが一枚も選択されないことがあります。-fps_mode vfr は、選択されたフレーム間の隙間が複製フレームで埋まるのを防ぎます。
トラブルシューティング
パイプで不完全なファイルが報告されるか、使用可能なパケットが見つからない場合は、MP4 の読み取りにシークが必要なのかもしれません。新しいディレクトリにダウンロードし、実際にダウンロードしたファイルを処理してください。これにより、ネットワークの失敗とデコードの失敗も切り分けられます。
(
set -euo pipefail
mkdir download
curl -fsSL --retry 3 "http://127.0.0.1:8765/input.mp4" -o download/input.mp4
ffmpeg -nostdin -n -hide_banner -loglevel warning -filter_threads 1 -i download/input.mp4 \
-map 0:v:0 -vf "fps=1" -c:v mjpeg -q:v 2 -threads 1 -frame_pts 1 \
download/thumbnail_%03d.jpg \
-map 0:a:0 -c:a pcm_s16le download/audio.wav
)
テスト用 URL では、パイプの場合と同じサムネイルと音声が生成されます。-o でファイルにダウンロードする場合に cURL の再試行を使用し、デコーダーへのパイプでは使用しないでください。cURL は再試行の前に、パイプへ書き込み済みのバイトをリセットできません。この違いは再試行のドキュメントで説明されています。このブロックは、ダウンロードが失敗するとデコード前に停止します。
HTTP 200 レスポンスと終了ステータスのゼロだけでも、メディアが完全であるとは確認できません。FFmpeg はデコード時の破損を報告してもゼロを返すことがあり、破損したフレームやサンプルを復旧することもあります。警告を読み、想定されるサムネイルの枚数と色を比較し、音声の長さと最後のトーンを確認してください。独自のメディアでは、既知の長さや想定される内容、または信頼できる配信元のチェックサムを使用します。これらの例では整合性チェックを実行しません。先にダウンロードすればシークの問題は解決しますが、破損は解決しません。
パフォーマンスに関する考慮事項
パイプを使うと入力 MP4 の保存は不要ですが、JPEG と非圧縮 WAV はディスク容量を消費します。FFmpeg はデータの到着に合わせて処理するため、ネットワーク速度とデコード速度が処理速度を決めます。これは HTTP によるファイルのダウンロードであり、リアルタイム処理やライブストリーミングの動作を保証するものではありません。サムネイルの生成頻度を下げると保存画像の枚数は減りますが、シーン検出では引き続きデコード済みフレームを調べます。
別の入力コンテナを使う場合は、FFmpeg の pipe プロトコルのドキュメントと、デマルチプレクサーがそのコンテナを逐次読み取りできるかを確認してください。MP4 の配置を制御できない場合に備え、先にダウンロードする方法も使えるようにしておきます。
