cURL と FFmpeg による動画サムネイルの抽出
リモート動画からサムネイルを抽出するには、大きなファイルのダウンロードが必要になる場合があります。メタデータと要求したフレームがファイルの先頭付近にあれば、バイト範囲リクエストでダウンロード量を減らせます。このガイドでは、まず先頭部分を試し、失敗したらシーク可能なファイル全体のダウンロードに切り替える Bash ヘルパーを紹介します。ローカルで動きのある動画を用意し、要求したフレームが JPEG に含まれているか確認します。
検証用 HTTP 動画の準備
Linux 環境で Bash、GNU coreutils、cURL 8.5 以降、ffprobe と libx264
エンコーダーを備えた FFmpeg、および Node.js を使用します。Ubuntu 24.04 では、シェルとメディアツールを bash、coreutils、curl、ffmpeg パッケージで提供しています。ローカルのオリジンサーバーと検証ツールには、Node.js 24 系の 24.15 以降、または 26 系を使用します。以下の .mts ファイルは Node のネイティブ TypeScript サポートで実行でき、組み込みモジュールのみを使用します。プロジェクトのインストールは不要です。Node.js 26 の公式 Linux バイナリには、ランタイム libatomicも必要です。Ubuntu では libatomic1 パッケージとして提供されています。この例は Ubuntu の FFmpeg 6.1.1 と cURL 8.5.0、および FFmpeg 9.0.1 と cURL 8.22.0 で動作します。
video-thumbnail-demo が存在しないディレクトリで、以下を Bash に貼り付けます。長さ 12 秒、640×360、毎秒 20 フレームのテスト動画と、MP4 メタデータを末尾に置いたコピーを作成します。パターンは動き、左上の四角は 1 秒より前は赤、それ以降は青になります。
(
set -euo pipefail
for tool in bash curl ffmpeg ffprobe node; do command -v "$tool" >/dev/null; done
node --version >/dev/null
curl --version >/dev/null
ffmpeg -version >/dev/null
ffprobe -version >/dev/null
mkdir -- video-thumbnail-demo || exit 1
trap 'status=$?; if [ "$status" -ne 0 ]; then
rm -f -- video-thumbnail-demo/fast.mp4 video-thumbnail-demo/tail.mp4
rmdir -- video-thumbnail-demo 2>/dev/null || true
fi' EXIT
ffmpeg -nostdin -n -v error -f lavfi \
-i "testsrc2=size=640x360:rate=20:duration=12" \
-vf "drawbox=x=0:y=0:w=80:h=80:color=red:t=fill:enable='lt(t,1)',drawbox=x=0:y=0:w=80:h=80:color=blue:t=fill:enable='gte(t,1)'" \
-c:v libx264 -preset ultrafast -crf 0 -threads 1 -filter_threads 1 \
-pix_fmt yuv420p -g 20 -movflags +faststart video-thumbnail-demo/fast.mp4
ffmpeg -nostdin -n -v error -i video-thumbnail-demo/fast.mp4 \
-map 0:v:0 -c copy video-thumbnail-demo/tail.mp4
)
生成に失敗すると、このブロックは未完成の動画とディレクトリを削除します。不足しているツールやエンコーダーを用意し、再実行してください。既存のディレクトリは保持されます。丸括弧で囲んでいるため、シェルオプションと作業ディレクトリは変更されません。
以下を video-thumbnail-demo/origin.mts として保存します。この小さなループバックサーバーは、両方のファイルを配信し、先頭部分の範囲指定に対応しますが、/ignore.mp4 では意図的に無視します。利用可能なポートを選び、URL を origin.url に記録します。このチュートリアル用のテストサーバーであり、公開サーバーではありません。
import { rmSync, writeFileSync } from 'node:fs'
import { readFile } from 'node:fs/promises'
import { createServer } from 'node:http'
async function main() {
const fast = await readFile('fast.mp4')
const tail = await readFile('tail.mp4')
const files: Record<string, Buffer> = {
'/fast.mp4': fast, '/tail.mp4': tail, '/ignore.mp4': fast,
}
const port = Number(process.argv[2] ?? 0)
if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port')
const server = createServer((request, response) => {
const path = new URL(request.url ?? '/', 'http://localhost').pathname
const data = files[path]
if (request.method !== 'GET' || !data) {
response.writeHead(404).end('Not found')
return
}
const range = request.headers.range
const match = range?.match(/^bytes=0-(\d+)$/)
if (range && !match && path !== '/ignore.mp4') {
response.writeHead(416).end('Use a prefix range')
return
}
const partial = match !== undefined && match !== null && path !== '/ignore.mp4'
const end = partial ? Math.min(Number(match[1]), data.length - 1) : data.length - 1
const body = data.subarray(0, end + 1)
const contentRange = partial ? `bytes 0-${end}/${data.length}` : undefined
response.setHeader('Content-Type', 'video/mp4')
response.setHeader('Content-Length', body.length)
response.setHeader('Accept-Ranges', 'bytes')
if (contentRange) response.setHeader('Content-Range', contentRange)
response.writeHead(partial ? 206 : 200).end(body)
console.log(JSON.stringify({
path, range, status: partial ? 206 : 200, bodyBytes: body.length, contentRange,
port: response.socket?.localPort,
}))
})
await new Promise<void>((resolve, reject) => {
server.once('error', reject)
server.listen(port, '127.0.0.1', resolve)
})
const address = server.address()
if (address === null || typeof address === 'string') throw new Error('No TCP address')
try {
writeFileSync('origin.url', `http://127.0.0.1:${address.port}\n`, { flag: 'wx' })
} catch (error) {
server.close()
throw error
}
const stop = () => {
server.closeAllConnections()
server.close()
rmSync('origin.url', { force: true })
}
process.once('SIGINT', stop)
process.once('SIGTERM', stop)
}
main().catch((error) => { console.error(error.message); process.exitCode = 1 })
Bash ヘルパーによるワークフローの自動化
以下を video-thumbnail-demo/thumbnail.sh として保存します。引数は HH:MM:SS[.ms]、1~999 Mb/s の整数の推定ビットレート、および出力パスです。一時入力ファイルを使うことで、シークとフォールバックを実現します。デコードの失敗や動画の長さを超えたシークを、FFmpeg がゼロを返しただけで成功と判定してはいけません。そのため、ヘルパーは新たに書き込まれた空でない画像も必要とします。
#!/usr/bin/env bash
set -euo pipefail
VIDEO_URL=${1:-}
TIMESTAMP=${2:-00:00:05} # HH:MM:SS[.ms]
BITRATE_MBPS=${3:-5} # average megabits-per-second
OUT=${4:-thumbnail.jpg}
if [[ -z "$VIDEO_URL" ]]; then
echo "Usage: $0 <url> [timestamp] [bitrate_mbps] [out]" >&2
exit 1
fi
if [[ ! "$TIMESTAMP" =~ ^[0-9]{2}:[0-5][0-9]:[0-5][0-9]([.][0-9]{1,3})?$ ]] ||
[[ ! "$BITRATE_MBPS" =~ ^[1-9][0-9]{0,2}$ ]]; then
echo "Use HH:MM:SS[.ms] and a whole-number bitrate from 1 to 999 Mb/s" >&2
exit 1
fi
if [[ -e "$OUT" || -L "$OUT" ]]; then
echo "Output already exists: $OUT" >&2
exit 1
fi
IFS=: read -r H M S <<< "$TIMESTAMP"
SEEK_SECONDS=$((10#$H * 3600 + 10#$M * 60 + 10#${S%.*} + 1))
BYTES=$((SEEK_SECONDS * BITRATE_MBPS * 125000 + 1048576))
WORK_DIR=$(mktemp -d "${TMPDIR:-/tmp}/video-thumb.XXXXXX")
trap 'rm -f -- "$WORK_DIR/input.mp4" "$WORK_DIR/thumb.jpg" "$WORK_DIR/errors.log"; rmdir "$WORK_DIR"' EXIT
make_thumbnail() {
rm -f -- "$WORK_DIR/thumb.jpg"
ffmpeg -nostdin -y -hide_banner -loglevel error -xerror -threads 1 -filter_threads 1 \
-ss "$TIMESTAMP" -i "$WORK_DIR/input.mp4" -map 0:v:0 \
-frames:v 1 -q:v 2 -c:v mjpeg -threads 1 -update 1 -f image2 "$WORK_DIR/thumb.jpg" \
2>"$WORK_DIR/errors.log" &&
[[ -s "$WORK_DIR/thumb.jpg" && ! -s "$WORK_DIR/errors.log" ]]
}
if curl --disable -fsSL --globoff --retry 3 --connect-timeout 10 --max-time 60 \
--proto '=http,https' --proto-redir '=http,https' \
--range "0-$((BYTES - 1))" --max-filesize "$BYTES" \
--write-out 'HTTP %{http_code}; downloaded %{size_download} bytes\n' \
-o "$WORK_DIR/input.mp4" -- "$VIDEO_URL" && make_thumbnail; then
echo "Thumbnail extracted from the initial download"
else
echo "Retrying with a complete, seekable download" >&2
curl --disable -fsSL --globoff --retry 3 --connect-timeout 10 --max-time 60 \
--proto '=http,https' --proto-redir '=http,https' \
--write-out 'HTTP %{http_code}; downloaded %{size_download} bytes\n' \
-o "$WORK_DIR/input.mp4" -- "$VIDEO_URL"
if ! make_thumbnail; then
cat -- "$WORK_DIR/errors.log" >&2
echo "No thumbnail decoded at $TIMESTAMP" >&2
exit 1
fi
fi
# Refuse to replace a file created while the download was running.
(set -o noclobber; cat "$WORK_DIR/thumb.jpg" > "$OUT")
echo "Thumbnail saved to $OUT"
ヘルパーはダウンロード前に既存のファイルやシンボリックリンクを拒否し、出力の確定時にも Bash の noclobber で再確認します。抽出を再実行する場合は、新しいファイル名を選んでください。一時入力ファイルと一時画像ファイルは終了時に削除されます。最終出力パスは、空白や % も含め、文字どおりに扱われます。
要求したフレームの検証
以下を video-thumbnail-demo/verify.mts として保存します。元の 20 fps 動画のフレームインデックス 30 をデコードし、デコードした 3 枚の JPEG すべてをそのフレームと比較します。このフレームは 1.500 秒から始まります。許容誤差は JPEG 圧縮による差を認めますが、赤い最初のフレームの画像はこの比較に合格しません。
import { execFileSync } from 'node:child_process'
function pixels(input: string, filter: string) {
return execFileSync('ffmpeg', [
'-nostdin', '-v', 'error', '-xerror', '-threads', '1', '-i', input,
'-vf', filter, '-filter_threads', '1', '-frames:v', '1',
'-threads', '1', '-pix_fmt', 'rgb24', '-f', 'rawvideo', 'pipe:1',
], { maxBuffer: 2 * 1024 * 1024 })
}
const reference = pixels('fast.mp4', 'select=eq(n\\,30)')
if (reference.length !== 640 * 360 * 3) throw new Error('Unexpected reference dimensions')
const patch = (20 * 640 + 20) * 3
if (reference[patch] > 10 || reference[patch + 1] > 10 || reference[patch + 2] < 240) {
throw new Error('Expected a blue square at 1.500 seconds')
}
for (const filename of ['thumb-fast.jpg', 'thumb-tail.jpg', 'thumb-ignore.jpg']) {
const actual = pixels(filename, 'null')
if (actual.length !== reference.length) throw new Error(`${filename}: wrong dimensions`)
let difference = 0
for (let index = 0; index < reference.length; index++) {
difference += Math.abs(actual[index] - reference[index])
}
if (difference / reference.length > 5) throw new Error(`${filename}: wrong frame`)
console.log(`${filename}: frame at 1.500 s verified`)
}
以下を video-thumbnail-demo/run-demo.sh として保存します。オリジンサーバーを起動し、ヘルパーの 3 通りの処理経路をすべて実行し、結果を検証してからサーバーを停止します。動画、JPEG、および origin.log は確認用に残ります。origin.url はサーバー停止時に削除されます。
#!/usr/bin/env bash
set -euo pipefail
cd -- "$(dirname -- "$0")"
if [[ -e origin.url || -L origin.url ]]; then
echo "origin.url already exists; check whether a demo origin is still running" >&2
exit 1
fi
node origin.mts >origin.log 2>&1 &
ORIGIN_PID=$!
trap 'kill "$ORIGIN_PID" 2>/dev/null || true; wait "$ORIGIN_PID" 2>/dev/null || true' EXIT
for ((attempt = 0; attempt < 50; attempt++)); do
if [[ -s origin.url ]]; then break; fi
if ! kill -0 "$ORIGIN_PID" 2>/dev/null; then cat origin.log >&2; exit 1; fi
sleep 0.1
done
if [[ ! -s origin.url ]]; then echo "Origin did not start" >&2; exit 1; fi
BASE_URL=$(cat origin.url)
bash ./thumbnail.sh "$BASE_URL/fast.mp4" 00:00:01.500 1 thumb-fast.jpg
bash ./thumbnail.sh "$BASE_URL/tail.mp4" 00:00:01.500 1 thumb-tail.jpg
bash ./thumbnail.sh "$BASE_URL/ignore.mp4" 00:00:01.500 1 thumb-ignore.jpg
node verify.mts
セットアップを実行したディレクトリで、次を実行します。
bash video-thumbnail-demo/run-demo.sh
ダウンロードとフォールバックのメッセージの後、検証ツールは次を出力します。
thumb-fast.jpg: frame at 1.500 s verified
thumb-tail.jpg: frame at 1.500 s verified
thumb-ignore.jpg: frame at 1.500 s verified
JPEG を開き、選択した時刻の青い四角と動くパターンを確認してください。fast.mp4 の最初のダウンロードでは、206 と 1,298,576 バイトが返るはずです。メタデータを末尾に置いたコピーには、全体のダウンロードが必要です。範囲指定を無視する場合は 200 が返ります。通知された全体サイズが先頭部分の上限を超えるため、cURL は拒否し、ヘルパーは範囲指定なしで再試行します。全体ダウンロードの処理経路では、先に受信したバイトに加えて、動画全体を転送します。デモを再実行するには、先に 3 枚の JPEG を別の場所へ移動してください。
cURL の HTTP 範囲リクエストの仕組み
HTTP 範囲リクエストは、オブジェクト全体ではなく、その一部のバイトを要求します。サーバーは Accept-Ranges: bytes を通知できますが、重要なのは実際の範囲 GET への応答です。206 Partial Content と、それに一致する Content-Range が、origin.log またはレスポンスヘッダーにあるか確認してください。cURL の範囲指定は両端を含みます。0-1048575 は先頭の 1 MiB を要求します。サーバーは範囲指定を無視し、200 OK と本文全体を返すことがあります。cURL がこれを自動的に部分ダウンロードへ変換することはありません。
ヘルパーは最終的な HTTP ステータスとダウンロードした本文のバイト数を表示します。レスポンスヘッダーと転送のオーバーヘッドは含みません。先頭部分の上限には
--max-filesizeを使用します。cURL 8.4.0 では、サイズが事前に不明なレスポンスにもこの上限が適用されるようになりました。全体ダウンロードへのフォールバックにはサイズ上限がないため、入力全体を保存・転送できるディスク容量と帯域幅を確保してください。
適切なバイト範囲の計算
必要なバイト数は、ビットレート、タイムスタンプ、コンテナのメタデータ、シーク位置付近のキーフレームによって変わります。簡易的な推定式は bytes ≈ seconds × bitrate(B/s) + buffer です。たとえば、5 Mb/s は約 625,000 B/s で、10 秒分に 1 MiB のバッファーを加えると
7,298,576 バイトになります。ヘルパーはこの推定式を適用する前にさらに 1 秒を加え、FFmpeg には元の小数部分を含むタイムスタンプを渡します。
これはあくまで推定です。可変ビットレートや末尾のメタデータによって、推定が成り立たなくなる場合があります。可逆圧縮のデモ動画は、指定した推定値 1 Mb/s を意図的に超えています。先頭付近のフレームは先頭部分に収まりますが、メタデータが末尾にあるファイルでは収まりません。先頭部分のリクエストを何度も失敗させるより、全体をダウンロードした方が速いこともあります。削減効果を決めつけず、実際のファイルで測定してください。
動画の部分データを FFmpeg にパイプで渡す方法
FFmpeg は pipe:0 で標準入力を読み込めますが、パイプでは後方へシークできません。入力 MP4 は順次読み取りに対応している必要があり、通常は moov メタデータを先頭に配置します。FFmpeg の +faststart オプションで、このメタデータを先頭へ移動できます。末尾にあるメタデータの問題は、ファイル全体を含めない限り、先頭部分の範囲を広げても解決しません。WebM と MKV でも、トラックヘッダーと、目的のフレームに到達するまでの十分なメディアデータが必要です。
cURL の出力を FFmpeg にパイプで渡し、-ss を -i の後に置けば、選択した時刻まで前方へデコードできます。FFmpeg はフレームを取得するとパイプを閉じることがあり、cURL が書き込みエラー(23)を報告します。pipefail を使用すると、画像が生成されていてもパイプラインは失敗します。ヘルパーは、この曖昧さを避けるために一時ファイルへダウンロードします。-ss を -i より前に置く指定では、入力シークを使用し、トランスコード時にはデフォルトで正確なシークが有効になります。
よくある問題のトラブルシューティング
- サムネイルをデコードできない: タイムスタンプが動画の再生時間内にあり、URL が動画データを返すことを確認してください。動画の末尾を超える位置では、FFmpeg はフレームを生成せずに正常終了することがあります。
- HTTP エラーや不完全な転送のエラー: 先頭部分の取得に失敗すると、全体ダウンロードへ切り替わります。そのリクエストも失敗した場合、ヘルパーはサムネイルを出力先に確定せず、異常終了します。
- メタデータの欠落や入力の破損:
-f mp4を強制しても、途中で切れたファイルは修復できません。ヘルパーはデコーダーのエラー診断を拒否しますが、ソース動画全体が正常であると確認するわけではありません。デコードするのは要求したフレームだけです。画像の存在だけでなく、内容も検証してください。 - 想定外の全体ダウンロード: 実際の範囲レスポンスと MP4 の配置を確認してください。
--compressedが圧縮をネゴシエートする対象はヘッダーではなくレスポンス本文で、圧縮済みの動画には通常効果がありません。 - 出力がすでに存在する: 新しいファイル名を選んでください。以前の JPEG が残っていても、最新の抽出が成功した証拠にはなりません。
ホスト型のサムネイル処理ワークフローについては、/video/thumbs Robotをご覧ください。
