FFmpeg と .NET による動画サムネイル生成の自動化
C# で動画のサムネイルを生成するには、指定時刻にシークして一つのフレームをエンコードし、画像が実際に書き込まれたかを確認します。動画の末尾を超えてシークすると、FFmpeg はフレームを生成せずに終了することがあります。このコンソールプロジェクトでは、FFMpegCore で JPEG を作成し、サムネイルを作成できなかった場合は 0 以外の終了コードを返します。
FFmpeg と .NET プロジェクトのセットアップ
.NET 10 SDK があり、ffmpeg と ffprobe の両方が
PATH にある Linux シェルを使用します。FFmpeg はディストリビューションのパッケージ、または
FFmpeg のダウンロードページからインストールしてください。以下の例では H.264 のサンプルを作成するため、FFmpeg のビルドには
libx264 エンコーダーも必要です。
インストール済みのツールを確認します。
dotnet --version && ffmpeg -version && ffprobe -version
プロジェクトを保存するディレクトリで、次のセットアップ用ブロックを実行します。新しいディレクトリが作成され、シェルの作業ディレクトリがそこに移ります。いずれかのコマンドが失敗した場合は、続行する前に作業を止めてエラーを解消してください。&& 演算子により、失敗後のセットアップコマンドは実行されません。
mkdir ThumbnailDemo &&
cd ThumbnailDemo &&
dotnet new console --framework net10.0 --no-restore &&
dotnet add package FFMpegCore --version 5.2.0
ここで使用するラッパーのバージョンを FFMpegCore 5.2.0 に固定します。ネイティブの FFmpeg 実行ファイルは別途インストールします。この例では、ログ用パッケージや画像ライブラリは不要です。
サムネイルサービスの作成
次のコードを ThumbnailService.cs として
ThumbnailDemo 内に保存します。ローカルの動画ファイル、新しい .jpg の出力先、動画の先頭からの時刻を受け取ります。出力先ディレクトリはあらかじめ存在している必要があります。
using FFMpegCore;
public static class ThumbnailService
{
public static async Task GenerateAsync(
string inputFile, string outputFile, TimeSpan captureTime)
{
if (captureTime < TimeSpan.Zero)
throw new ArgumentException("The timestamp must not be negative.");
inputFile = Path.GetFullPath(inputFile);
outputFile = Path.GetFullPath(outputFile);
if (!File.Exists(inputFile))
throw new FileNotFoundException("The input video does not exist.", inputFile);
if (!Path.GetExtension(outputFile).Equals(".jpg", StringComparison.OrdinalIgnoreCase))
throw new ArgumentException("Use a .jpg output filename.");
if (File.Exists(outputFile) || Directory.Exists(outputFile))
throw new IOException("The destination already exists. Choose a new filename.");
var directory = Path.GetDirectoryName(outputFile)!;
if (!Directory.Exists(directory))
throw new DirectoryNotFoundException("The output directory does not exist.");
var temporaryFile = Path.Combine(directory, $".thumbnail-{Guid.NewGuid():N}.jpg");
try
{
await FFMpegArguments
.FromFileInput(inputFile, addArguments: options => options.Seek(captureTime))
.OutputToFile(temporaryFile, false, options => options
.WithVideoCodec("mjpeg")
.WithFrameOutputCount(1)
.WithVideoFilters(filters => filters.Scale(320, -2))
.ForceFormat("image2")
.WithCustomArgument("-map 0:v:0 -pix_fmt yuvj420p -update 1"))
.ProcessAsynchronously();
if (!File.Exists(temporaryFile) || new FileInfo(temporaryFile).Length == 0)
throw new InvalidOperationException("No frame was produced. Try an earlier timestamp.");
var image = await FFProbe.AnalyseAsync(temporaryFile);
if (!image.VideoStreams.Any(stream =>
stream.CodecName == "mjpeg" && stream.Width == 320 && stream.Height > 0))
throw new InvalidOperationException("The output is not the expected JPEG thumbnail.");
File.Move(temporaryFile, outputFile, overwrite: false);
}
finally
{
File.Delete(temporaryFile);
}
}
}
コードの仕組み
入力の Seek は、-ss を
-i より前に配置します。トランスコード時、FFmpeg は指定位置より前のシークポイントに移動し、指定位置までのフレームをデコードして破棄します。詳しくはシークのドキュメントを参照してください。明示的な -map 0:v:0 は最初の映像ストリームを選択します。音声のみのファイルで、音声ストリームが暗黙に代用されることはありません。
出力では、フルレンジの JPEG ピクセル形式で一つの MJPEG フレームを要求します。320:-2 へのスケーリングでは、元の縦横比から偶数の高さを算出します。そのため、以下の正方形ピクセルのサンプルは 320 × 240 に引き伸ばされず、320 × 180 になります。負の高さの値については、scale フィルターのドキュメントで説明されています。この手順では、正方形ピクセルの通常の SDR 動画を使用してください。HDR トーンマッピングやアナモルフィック動画の処理には、別途フィルターの選定が必要です。
image2 の update オプションは、一時出力を単一のファイル名として扱います。FFmpeg の終了後、サービスはファイルサイズを確認し、コーデックと寸法を調べます。その後に初めて、ファイルを指定の出力先に移動します。上書きしない移動では、FFmpeg の実行中に出力先ファイルが作成された場合も移動を拒否します。通常の完了時や失敗時には、finally ブロックが一時ファイルを削除します。ただし、プロセスが強制終了された場合は、一時ファイルが残ることがあります。
コンソールプログラムの実行
生成された Program.cs を、次の完全な呼び出し側コードに置き換えます。0.25 のように小数点を使った秒数を受け取り、診断情報を標準エラー出力に表示します。戻り値がプロセスの終了コードになります。成功時は 0、引数が無効な場合は 2、処理が失敗した場合は 1 を返します。
using System.Globalization;
if (args.Length != 3 ||
!double.TryParse(args[2], NumberStyles.Float, CultureInfo.InvariantCulture, out var seconds) ||
!double.IsFinite(seconds) || seconds < 0)
{
Console.Error.WriteLine("Usage: dotnet run -- <input-video> <output.jpg> <seconds>");
return 2;
}
try
{
await ThumbnailService.GenerateAsync(args[0], args[1], TimeSpan.FromSeconds(seconds));
Console.WriteLine($"Created {Path.GetFullPath(args[1])}");
return 0;
}
catch (Exception error)
{
Console.Error.WriteLine($"Thumbnail failed: {error.Message}");
return 1;
}
ThumbnailDemo 内で、赤が 2 秒、その後に青が 2 秒続く、4 秒間のテスト動画を作成します。sample.mp4 がすでに存在する場合は、最初のチェックでこのブロックが 0 以外のステータスで停止し、既存のファイルは保持されます。新しいサンプルを作成する場合は、新しいプロジェクトディレクトリを使用してください。
test ! -e sample.mp4 &&
ffmpeg -n -f lavfi -i "color=c=red:s=640x360:r=25:d=2" \
-f lavfi -i "color=c=blue:s=640x360:r=25:d=2" \
-filter_complex "[0:v][1:v]concat=n=2:v=1:a=0[v]" \
-map "[v]" -c:v libx264 -pix_fmt yuv420p sample.mp4
3 秒の位置のフレームを取得します。
dotnet run -- sample.mp4 thumbnail.jpg 3
thumbnail.jpg を開いてください。青い画像で、寸法は 320 × 180 ピクセルになっているはずです。ffprobe で調べた後、別の画像を書き込まずに FFmpeg でデコードすることもできます。
ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height \
-of default=noprint_wrappers=1 thumbnail.jpg &&
ffmpeg -v error -xerror -i thumbnail.jpg -f null -
プローブ結果には codec_name=mjpeg、width=320、height=180 が表示されます。デコードに成功した場合は何も表示されません。sample.mp4 を手元のローカル動画のパスに置き換え、フレームが存在する時刻を選んでください。空白を含むパスは引用符で囲みます。同じ時刻を繰り返し指定する場合も、呼び出しごとに新しい出力名が必要です。
フレームの欠落と繰り返し実行への対応
短いクリップでは、指定した時刻より前に動画が終わることがあります。最初のフレームには 0 を、またはより小さい小数の時刻を試してください。末尾またはそれ以降にシークすると、FFmpeg が失敗するか、画像が生成されない場合があります。どちらも処理の失敗として扱われます。サービスが別の時点のフレームを暗黙に代用することはありません。
4 秒間のサンプルでは、次のコマンドは必ず 0 以外のステータスを返し、出力先ファイルを残しません。
dotnet run -- sample.mp4 beyond-end.jpg 10
読み取れない動画、存在しない入力、音声のみのファイルも失敗します。ツールが見つからない場合は、プログラムを実行するのと同じシェルで
PATH を確認してください。出力先がすでに存在する場合は、プログラムは既存のバイト列を保持して失敗します。再試行するには別の名前を選んでください。これにより、誤って入力を出力先に指定した場合も入力が保護されます。引数の検証に失敗した場合、既存のファイルは変更されません。
複数のプレビューを作成するには、時刻と出力名を変えて
GenerateAsync を順番に呼び出します。サムネイルの生成失敗をスキップしたバッチが全件成功と報告しないよう、例外を呼び出し側に伝播させます。この単一フレームの例では、スケジューリングと並行処理はサービスの外部で扱います。
デプロイ先のランタイムの確認
この手順は、Linux 上の .NET SDK 10.0.111、FFMpegCore 5.2.0、および FFmpeg/ffprobe 6.1.1 と 9.0.1 で検証しました。その間のすべてのリリース、古い .NET バージョン、Windows、macOS との互換性を確認したものではありません。プログラムを実行するアカウントから、両方のネイティブ実行ファイルを利用できる状態にしてください。デプロイ先の FFmpeg ビルドを変更する際は、サンプルと失敗ケースを再実行してください。
ホスト型のサムネイル生成ワークフローが必要な場合は、動画サムネイル Robot のドキュメントを参照してください。このローカルプロジェクトでは、ランタイムの更新後も期待するフレームを作成できるかを手早く確認できるよう、サンプル動画を保存しておいてください。
