Rust と FFmpeg による動画への透かし追加の並行処理
Rust を使い、FFmpeg で透かしを追加する小規模なバッチを、子プロセスを同時に最大二つまで実行して処理します。以下のツールは各動画に PNG を追加し、最初の音声トラックを保持します。いずれかのジョブが失敗すると、ゼロ以外の終了ステータスを返します。ほかのジョブが失敗しても、成功した動画はそのまま利用できます。
前提条件
- 以下のコマンドを実行する Linux 上の Bash
- Rust 1.85.1 以降。
rustcがPATHに含まれていること - FFmpeg および ffprobe 6.1.1 以降。
libx264エンコーダーと、overlay、color、sineフィルターが利用できること。テスト用ファイルの生成コマンドには、AAC と PNG のエンコーダーも必要です。
この例では、回転していない縦横ともに偶数サイズの映像ストリームと、任意の AAC 音声を含む MP4 動画を使います。透かしには、各フレーム内に収まる大きさの 8 ビット PNG を使います。処理するのは最初の映像ストリームと最初の音声ストリームのみで、字幕や追加のトラックは処理しません。シェルのワークフローは Linux 専用で、Windows や macOS 向けに検証済みのインストールガイドではありません。
FFmpeg プロセス数の制限
Rust はスケジューリングと終了ステータスを、FFmpeg はデコード、合成、エンコードを担当します。FFmpeg のバインディングや外部の Rust クレートは使いません。二つのジョブを同時に実行し、両方が完了してから次のグループを開始します。意図的に単純なグループ分けにしているため、遅いジョブの完了を待つ間、実行枠が空く場合があります。これは同時実行数の制限を示すもので、スループットのベンチマークではありません。
子プロセスが二つでも、CPU スレッドが二つになるわけではありません。コードでは各入力と映像エンコーダーにそれぞれ一つのコーデックスレッドを、複合フィルターグラフに一つのスレッドを要求します。それでも FFmpeg は、ほかの内部スレッドを作成することがあります。これらの設定は、CPU やメモリの総使用量を制限するものではありません。FFmpeg オプションリファレンスを参照してください。
環境のセットアップ
rustup を使い、保守が継続されている安定版の Rust ツールチェーンをインストールします。Ubuntu または Debian では、ディストリビューションの FFmpeg パッケージをインストールします。
sudo apt-get update && sudo apt-get install -y ffmpeg
rustc --version、ffmpeg -version、ffprobe -version を確認します。この例は Rust 1.85.1 と 1.98.1、および FFmpeg 6.1.1 と 9.0.1 で検証済みです。使用するビルドに必要な機能がない場合は、ffmpeg -encoders と
ffmpeg -filters を確認してください。
現在の作業ディレクトリ内に新しいディレクトリを作成します。同名のディレクトリがすでに存在する場合は、削除せずに別の名前を選んでください。
mkdir rust-watermark
以下のソース全体を rust-watermark/watermark.rs として保存します。この単独のファイルを rustc でコンパイルし、エディションと実行ファイルのパスを明示的に指定します。Cargo プロジェクトは作成しないため、上位の Cargo ワークスペースや、そこで設定されたターゲットディレクトリは、このビルドに影響しません。
基本的な透かし追加ツールの構築
use std::env;
use std::fs;
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::process::{Command, ExitCode, Stdio};
use std::thread;
const MAX_CHILDREN: usize = 2;
fn watermark_video(input: &Path, watermark: &Path, output: &Path) -> io::Result<()> {
let input = fs::canonicalize(input)?;
let result = Command::new("ffmpeg")
.args(["-hide_banner", "-loglevel", "error", "-nostdin", "-n", "-xerror"])
.args(["-threads", "1", "-i"])
.arg(input)
.args(["-threads", "1", "-f", "image2", "-pattern_type", "none", "-i"])
.arg(watermark)
.args([
"-filter_complex_threads", "1",
"-filter_complex", "[0:v:0][1:v:0]overlay=10:10:eof_action=repeat:repeatlast=1[v]",
"-map", "[v]", "-map", "0:a:0?",
"-c:v", "libx264", "-threads:v", "1", "-crf", "20",
"-pix_fmt", "yuv420p", "-c:a", "copy",
"-movflags", "+faststart", "-f", "mp4",
])
.arg(output)
.stdin(Stdio::null())
.stdout(Stdio::null())
.output()?;
if result.status.success() && result.stderr.is_empty() {
return Ok(());
}
if output.exists() {
fs::remove_file(output)?;
}
io::stderr().write_all(&result.stderr)?;
Err(io::Error::other(format!("FFmpeg failed ({})", result.status)))
}
fn run() -> io::Result<ExitCode> {
let arguments: Vec<_> = env::args_os().skip(1).collect();
if arguments.len() < 3 {
return Err(io::Error::other(
"Usage: watermark-batch WATERMARK.png NEW_OUTPUT_DIR INPUT.mp4 [INPUT.mp4 ...]",
));
}
let watermark = fs::canonicalize(&arguments[0])?;
let output_directory = PathBuf::from(&arguments[1]);
fs::create_dir(&output_directory)?;
let mut next_job = 1;
let mut succeeded = 0;
let mut failed = 0;
for group in arguments[2..].chunks(MAX_CHILDREN) {
let mut handles = Vec::new();
for input in group {
let input = PathBuf::from(input);
let output = output_directory.join(format!("job-{next_job}.mp4"));
next_job += 1;
let job_input = input.clone();
let job_output = output.clone();
let job_watermark = watermark.clone();
let handle = thread::spawn(move || {
watermark_video(&job_input, &job_watermark, &job_output)
});
handles.push((input, output, handle));
}
for (input, output, handle) in handles {
match handle.join() {
Ok(Ok(())) => {
succeeded += 1;
println!("OK {} -> {}", input.display(), output.display());
}
outcome => {
failed += 1;
match outcome {
Ok(Err(error)) => eprintln!("FAIL {}: {error}", input.display()),
_ => eprintln!("FAIL {}: worker panicked", input.display()),
}
}
}
}
}
eprintln!("Batch: {succeeded} succeeded, {failed} failed");
Ok(if failed == 0 { ExitCode::SUCCESS } else { ExitCode::FAILURE })
}
fn main() -> ExitCode {
match run() {
Ok(status) => status,
Err(error) => {
eprintln!("Batch setup failed: {error}");
ExitCode::FAILURE
}
}
}
overlay フィルターは、透かしの左上隅を、動画の上端と左端からそれぞれ 10 ピクセルの位置に配置します。PNG の最後のフレームを繰り返すことで、単一フレームの入力が終了した後も透かしを表示し続けます。映像は yuv420p で H.264 に再エンコードします。任意指定の 0:a:0? マッピングは、最初の音声トラックを再エンコードせずにコピーします。入力パスを絶対パスにすることで、先頭のハイフンがオプションとして解釈されるのを防ぎます。また、-pattern_type none により、PNG 名を % 文字も含めて文字どおりに扱います。
二つのサンプル動画と透かしの作成
rust-watermark があるディレクトリで、以下のブロックを貼り付けます。440 Hz の音を含む 2.32 秒の青い動画、880 Hz の音を含む赤い動画、48 × 24 ピクセルの白い PNG を作成します。サブシェルを使うため、失敗時も含め、現在のディレクトリとシェルオプションは変わりません。ファイル生成前のガード処理で、テスト用ファイルと同じ名前がすでに存在する場合は処理を拒否します。-n でも上書きを確認しますが、FFmpeg は上書きを拒否してもステータス 0 を返す場合があるため、これをセットアップのガード処理としては使いません。最初からすべてやり直す場合は、新しいプロジェクトディレクトリを使ってください。
(
set -eu
cd rust-watermark
for fixture in video1.mp4 video2.mp4 watermark.png; do
if [ -e "$fixture" ] || [ -L "$fixture" ]; then
printf 'Fixture already exists: %s\n' "$fixture" >&2
exit 1
fi
done
ffmpeg -hide_banner -loglevel error -nostdin -n \
-f lavfi -i 'color=c=blue:s=320x180:r=25:d=2.32' \
-f lavfi -i 'sine=frequency=440:sample_rate=48000:duration=2.32' \
-c:v libx264 -threads 1 -pix_fmt yuv420p -c:a aac -shortest video1.mp4
ffmpeg -hide_banner -loglevel error -nostdin -n \
-f lavfi -i 'color=c=red:s=400x240:r=25:d=2.32' \
-f lavfi -i 'sine=frequency=880:sample_rate=48000:duration=2.32' \
-c:v libx264 -threads 1 -pix_fmt yuv420p -c:a aac -shortest video2.mp4
ffmpeg -hide_banner -loglevel error -nostdin -n \
-f lavfi -i 'color=c=white:s=48x24:r=1:d=1' \
-frames:v 1 -c:v png -threads 1 -f image2 -update 1 watermark.png
)
バッチのビルドと実行
引き続き親ディレクトリで、保存したソースをコンパイルし、その実行ファイルを実行します。
(
cd rust-watermark &&
rustc --edition=2021 watermark.rs -o watermark-batch &&
./watermark-batch ./watermark.png ./output ./video1.mp4 ./video2.mp4
)
&& でコマンドを連結することで、コンパイル失敗後に古い実行ファイルが実行されるのを防ぎます。出力は rust-watermark/output/job-1.mp4 と rust-watermark/output/job-2.mp4 で、入力順に番号が付きます。バッチは Batch: 2 succeeded, 0 failed と表示し、ステータス 0 で終了します。両方のファイルを再生してください。サイズ、背景色、音はそれぞれ異なったままで、各動画の全編を通して(10, 10)の位置に白い長方形が表示されるはずです。
出力ディレクトリは、まだ存在していない必要があります。./output を使って再実行すると、FFmpeg の子プロセスを起動する前に失敗し、既存のファイルは変更されません。別のバッチには新しい出力ディレクトリを使い、ほかのプロセスがそこに書き込まないようにしてください。成功したファイルはバッチの実行中から見えますが、利用する前に最終ステータスを待ってください。この方式はアトミックな公開を実現するものではありません。
エラー処理とログ
Command::output()
は各 FFmpeg 子プロセスの終了を待ち、診断情報を取得します。起動エラー、ゼロ以外の終了ステータス、または -loglevel error 使用時の stderr へのテキスト出力があると、そのジョブは失敗と判定されます。最後の確認は重要です。FFmpeg 6.1.1 は -xerror を指定していても、デコーダーエラーを報告しながらステータス 0 を返す場合があります。
ランナーはグループ内のすべてのワーカーを join し、両方の結果を記録して、後続のグループの処理を続けます。最後のジョブが成功しても、累積した失敗数によって最終ステータスが決まります。
別の新しい出力ディレクトリを使い、二つの有効な動画の間に存在しない入力を挟んで試してください。
(
cd rust-watermark &&
./watermark-batch ./watermark.png ./mixed-output ./video1.mp4 ./missing.mp4 ./video2.mp4
)
これは Batch: 2 succeeded, 1 failed と表示し、ステータス 1 で終了します。mixed-output/job-1.mp4 と mixed-output/job-3.mp4 は残りますが、二番目の入力には成功した出力がありません。FFmpeg が不完全なファイルを作成した後に失敗したりエラーを報告したりすると、ワーカーはそのファイルを削除します。削除エラーはジョブの失敗として報告され、不完全なファイルが残って手動での削除が必要になる場合があります。透かしが見つからない、出力ディレクトリがすでに存在するなどのセットアップエラーは、ジョブを開始する前に発生し、以前の結果を削除しません。
よくある問題と対処法
- FFmpeg が利用できない: 該当するジョブの起動に失敗します。対話型シェルだけでなく、Rust の実行ファイルが継承する
PATHを確認してください。 - コーデックまたはフィルターがない: stderr のエラーと、インストール済みのエンコーダーおよびフィルターを確認します。同時実行中の FFmpeg の診断情報は混在する場合があります。Rust のメッセージには各入力の名前が含まれます。
- ジョブが停止したまま進まない: この例にはタイムアウトやキャンセルハンドラーはありません。通常どおり実行が完了した場合、子プロセスは終了しており、ワーカーも join 済みです。Rust を強制終了しても、子プロセスの終了や不完全なファイルの削除は保証されません。サービスとして運用するには、別途プロセス監視の方針が必要です。
- 破損したファイルからも出力が生成される: ランナーは報告されたエラーを失敗として扱いますが、デコーダーが破損を報告せずに補完することがあります。ジョブの成功は、入力が無傷だった証拠にはなりません。結果を利用する前に、実際の映像と音声を確認してください。
- 診断情報がメモリを消費する: この小さな例は、各子プロセスのエラー出力をメモリに保持します。ログサイズは制限しません。サービスにはプロセス監視に加え、診断情報のサイズ制限やストリーミングが必要です。
このツールはアップロードサービスではなく、ローカルのバッチランナーとして使ってください。より大きなキューを扱う場合は、MAX_CHILDREN を変更する前にリソース使用量を測定し、保持された成功結果と失敗したジョブを呼び出し元でどう扱うかを決めてください。Rust の並行処理だけで、処理の高速化や本番環境でのスケーラビリティが実証されるわけではありません。
