Java での動画処理:トランスコード、サイズ変更、透かしの追加
JavaCV を使うと、Java から FFmpeg で動画をデコードし、OpenCV でフレームを加工して、MP4 にエンコードできます。このチュートリアルでは、H.264 へのトランスコード、指定解像度へのサイズ変更、テキスト透かしの焼き込みという三つの操作を行うコマンドラインプログラムを作成します。どの操作でも、音声トラックがある場合は、最初の音声トラックを AAC として保持します。
前提条件
ここで動作確認した環境に合わせて、Bash、JDK 21.0.12.1、Maven 3.9.16 を備えた
Linux x86_64 マシンを使用してください。コマンドラインツールの ffmpeg と ffprobe もインストールしてください。検証コマンドは FFmpeg 9.0.1 で動作確認しています。これらのツールは、JavaCV に同梱された FFmpeg 7.1.1 ライブラリとは別に実行されます。
このサンプルは、読み取り可能なローカルの固定フレームレートの SDR 動画を対象とします。ピクセルは正方形で、回転がなく、音声と映像がともに時刻ゼロから始まることが前提です。映像トラックは一つとし、音声を含める場合はモノラルまたはステレオにしてください。字幕、追加のトラック、メタデータ、HDR、可変フレームレートのタイミングは保持しません。管理下にあるディレクトリで作業し、処理は順番に実行してください。
エディターで新しいプロジェクトディレクトリを作成してください。その中に pom.xml と
src/main/java/VideoProcessor.java を作成します。プロジェクトディレクトリでターミナルを開いてください。以降のコマンドはすべてそこで実行します。次の内容を省略せずに pom.xml に保存してください。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>example</groupId>
<artifactId>java-video</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<native.platform>linux-x86_64</native.platform>
</properties>
<dependencies>
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>javacv</artifactId>
<version>1.5.12</version>
<exclusions>
<exclusion><groupId>*</groupId><artifactId>*</artifactId></exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>ffmpeg</artifactId>
<version>7.1.1-1.5.12</version>
</dependency>
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>ffmpeg</artifactId>
<version>7.1.1-1.5.12</version>
<classifier>${native.platform}</classifier>
</dependency>
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>opencv</artifactId>
<version>4.11.0-1.5.12</version>
</dependency>
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>opencv</artifactId>
<version>4.11.0-1.5.12</version>
<classifier>${native.platform}</classifier>
</dependency>
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>openblas</artifactId>
<version>0.3.30-1.5.12</version>
<classifier>${native.platform}</classifier>
</dependency>
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>javacpp</artifactId>
<version>1.5.12</version>
<classifier>${native.platform}</classifier>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<version>3.4.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.14.1</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.8.1</version>
</plugin>
</plugins>
</build>
</project>
これらのバージョン固定により、Java ラッパーとネイティブライブラリの組み合わせを揃えます。このプロジェクトには、すべてのプラットフォーム向けの JavaCV バックエンドをダウンロードする代わりに、Linux x86_64 向けの FFmpeg、OpenCV とその依存関係を含めます。Java アーティファクトとプラットフォーム固有のネイティブアーティファクトの両方が必要な理由は、Bytedeco のドキュメントで説明されています。
Java での動画のトランスコード
次のクラスを src/main/java/VideoProcessor.java として保存してください。三つの操作はすべて、同じデコーダー、音声処理、エンコーダー設定を共有します。異なるのは画像処理の部分だけです。
エンコーダーには映像用に 5 Mbps を指定します。これはビットレートの目安であり、出力サイズや品質を保証する値ではありません。ここで使用する標準のネイティブバイナリは OpenH264 で H.264 をエンコードするため、このサンプルでは x264 固有の CRF オプションを設定しません。音声は無損失でコピーするのではなく、デコードして再エンコードします。固定したリリース 1.5.12 を使用してください。このリリースでは、ファイルの末尾でレコーダーが遅延した音声パケットをフラッシュします。1.5.11 では最後の AAC パケットが失われる場合があります。
import static org.bytedeco.ffmpeg.global.avcodec.AV_CODEC_ID_AAC;
import static org.bytedeco.ffmpeg.global.avcodec.AV_CODEC_ID_H264;
import static org.bytedeco.ffmpeg.global.avutil.AV_PIX_FMT_YUV420P;
import static org.bytedeco.opencv.global.opencv_imgproc.FONT_HERSHEY_SIMPLEX;
import static org.bytedeco.opencv.global.opencv_imgproc.INTER_AREA;
import static org.bytedeco.opencv.global.opencv_imgproc.INTER_LINEAR;
import static org.bytedeco.opencv.global.opencv_imgproc.LINE_AA;
import static org.bytedeco.opencv.global.opencv_imgproc.getTextSize;
import static org.bytedeco.opencv.global.opencv_imgproc.putText;
import static org.bytedeco.opencv.global.opencv_imgproc.resize;
import java.nio.file.Files;
import java.nio.file.Path;
import org.bytedeco.javacv.FFmpegFrameGrabber;
import org.bytedeco.javacv.FFmpegFrameRecorder;
import org.bytedeco.javacv.Frame;
import org.bytedeco.javacv.OpenCVFrameConverter;
import org.bytedeco.opencv.opencv_core.Mat;
import org.bytedeco.opencv.opencv_core.Point;
import org.bytedeco.opencv.opencv_core.Scalar;
import org.bytedeco.opencv.opencv_core.Size;
public class VideoProcessor {
public static void main(String[] args) throws Exception {
if (args.length < 3) throw new IllegalArgumentException(
"Usage: VideoProcessor transcode INPUT OUTPUT\n"
+ " VideoProcessor resize INPUT OUTPUT WIDTH HEIGHT\n"
+ " VideoProcessor watermark INPUT OUTPUT TEXT");
String operation = args[0];
int expected = switch (operation) {
case "transcode" -> 3;
case "resize" -> 5;
case "watermark" -> 4;
default -> throw new IllegalArgumentException("Unknown operation: " + operation);
};
if (args.length != expected) throw new IllegalArgumentException("Wrong argument count");
int width = operation.equals("resize") ? Integer.parseInt(args[3]) : 0;
int height = operation.equals("resize") ? Integer.parseInt(args[4]) : 0;
if (operation.equals("resize")) checkDimensions(width, height);
String text = operation.equals("watermark") ? args[3] : "";
if (operation.equals("watermark") && (text.isBlank() || !text.matches("[ -~]+"))) {
throw new IllegalArgumentException("Use nonblank printable ASCII watermark text");
}
process(Path.of(args[1]).toAbsolutePath(), Path.of(args[2]).toAbsolutePath(),
operation, width, height, text);
}
private static void checkDimensions(int width, int height) {
if (width <= 0 || height <= 0 || width % 2 != 0 || height % 2 != 0) {
throw new IllegalArgumentException("Output dimensions must be positive and even");
}
}
private static void process(Path input, Path output, String operation,
int width, int height, String text) throws Exception {
if (!Files.isRegularFile(input)) throw new IllegalArgumentException("Video file not found");
// Reserve a new destination; never claim ownership of an existing file.
Files.createFile(output);
boolean completed = false;
try {
try (FFmpegFrameGrabber grabber = new FFmpegFrameGrabber(input.toString());
OpenCVFrameConverter.ToMat converter = new OpenCVFrameConverter.ToMat();
Mat resized = new Mat();
Point origin = new Point(24, 48);
Scalar white = new Scalar(255, 255, 255, 0);
Scalar black = new Scalar(0, 0, 0, 0)) {
grabber.start();
if (grabber.getImageWidth() <= 0 || grabber.getImageHeight() <= 0) {
throw new IllegalArgumentException("Input must contain video");
}
if (!operation.equals("resize")) {
width = grabber.getImageWidth();
height = grabber.getImageHeight();
}
checkDimensions(width, height);
double fps = grabber.getFrameRate();
if (!Double.isFinite(fps) || fps <= 0) {
throw new IllegalArgumentException("Input must have a valid frame rate");
}
if (grabber.getAudioChannels() > 2) {
throw new IllegalArgumentException("Use mono or stereo audio");
}
if (operation.equals("watermark")) {
try (Size bounds = getTextSize(text, FONT_HERSHEY_SIMPLEX, 1.0, 4, new int[1])) {
if (bounds.width() + 48 > width || height < 72) {
throw new IllegalArgumentException("Watermark does not fit the frame");
}
}
}
try (Size size = new Size(width, height);
FFmpegFrameRecorder recorder = new FFmpegFrameRecorder(
output.toString(), width, height, grabber.getAudioChannels())) {
recorder.setFormat("mp4");
recorder.setVideoCodec(AV_CODEC_ID_H264);
recorder.setVideoBitrate(5_000_000);
recorder.setFrameRate(fps);
recorder.setPixelFormat(AV_PIX_FMT_YUV420P);
if (grabber.getAudioChannels() > 0) {
recorder.setAudioCodec(AV_CODEC_ID_AAC);
recorder.setAudioBitrate(128_000);
recorder.setSampleRate(grabber.getSampleRate());
}
recorder.start();
int images = 0;
Frame frame;
while ((frame = grabber.grab()) != null) {
if (frame.image != null) {
Frame image = frame;
if (operation.equals("resize")) {
int interpolation = width < grabber.getImageWidth()
&& height < grabber.getImageHeight() ? INTER_AREA : INTER_LINEAR;
resize(converter.convert(frame), resized, size, 0, 0, interpolation);
image = converter.convert(resized);
} else if (operation.equals("watermark")) {
Mat pixels = converter.convert(frame);
putText(pixels, text, origin, FONT_HERSHEY_SIMPLEX,
1.0, black, 4, LINE_AA, false);
putText(pixels, text, origin, FONT_HERSHEY_SIMPLEX,
1.0, white, 2, LINE_AA, false);
image = converter.convert(pixels);
}
recorder.setTimestamp(frame.timestamp);
recorder.record(image);
images++;
}
if (frame.samples != null) recorder.recordSamples(
frame.sampleRate, frame.audioChannels, frame.samples);
}
if (images == 0) throw new IllegalArgumentException("No video frames decoded");
}
}
completed = true;
} finally {
if (!completed) Files.deleteIfExists(output);
}
}
}
再現可能な入力として、長さ 2.36 秒の 440 Hz のトーンを伴う
640 × 360 のテストパターンを生成します。-n オプションは、既存の input.mp4 の上書きを拒否します。
ffmpeg -nostdin -v error -n \
-f lavfi -i 'testsrc2=size=640x360:rate=25' \
-f lavfi -i 'sine=frequency=440:sample_rate=48000' \
-t 2.36 -c:v mpeg4 -q:v 3 -c:a aac input.mp4
プロジェクトをビルドし、入力全体にデコードエラーがないか検証してから、トランスコードします。
mvn --batch-mode compile dependency:copy-dependencies &&
ffmpeg -nostdin -v error -xerror -err_detect explode -i ./input.mp4 \
-map 0:v:0 -map '0:a:0?' -f null - &&
java -cp 'target/classes:target/dependency/*' VideoProcessor \
transcode ./input.mp4 ./transcoded.mp4
Maven はクラスを target/classes にコンパイルし、依存関係をコピーして
target/dependency に配置します。&& 演算子は削除しないでください。ビルドに失敗した場合に古いコンパイル済みクラスを実行せず、入力の検証に失敗した場合に出力を作成しないためです。Java プロセスも、処理エラーが報告されるとゼロ以外の終了コードで終了します。
厳格な入力検証が重要なのは、JavaCV のグラバーが一部のデコードエラーを無視する場合があるためです。Java クラスの呼び出しだけで破損を検出できるとは考えないでください。FFmpeg の -xerror オプションはエラー時に停止します。ただし、この検証でもエンコードの成功でも、録画するつもりだった映像がすべてソースに含まれていることまでは証明できません。
JavaCV による動画のサイズ変更
同じ入力に対してサイズ変更を実行します。
mvn --batch-mode compile dependency:copy-dependencies &&
ffmpeg -nostdin -v error -xerror -err_detect explode -i ./input.mp4 \
-map 0:v:0 -map '0:a:0?' -f null - &&
java -cp 'target/classes:target/dependency/*' VideoProcessor \
resize ./input.mp4 ./resized.mp4 320 180
これにより、320 × 180 の MP4 が生成されます。このプログラムは YUV420P で出力するため、幅と高さはどちらも正の偶数である必要があります。指定した寸法に直接拡大・縮小するので、引き伸ばしを避けるにはソースと同じアスペクト比を選んでください。切り抜きやパディングの追加は行いません。
OpenCV の resizeは、ここでは幅と高さの両方が縮小される場合に面積補間を使い、それ以外の場合は線形補間を使います。サイズ変更後の画像はトランスコードと同じエンコーダーに渡されます。音声サンプルは OpenCV を経由しません。
動画への透かしの追加
各フレームに短いテキストラベルを焼き込みます。
mvn --batch-mode compile dependency:copy-dependencies &&
ffmpeg -nostdin -v error -xerror -err_detect explode -i ./input.mp4 \
-map 0:v:0 -map '0:a:0?' -f null - &&
java -cp 'target/classes:target/dependency/*' VideoProcessor \
watermark ./input.mp4 ./watermarked.mp4 'Preview'
出力のサイズは 640 × 360 のままです。テキストの開始位置は左端から 24 ピクセル、ベースラインは上端から 48 ピクセルです。最初に黒い文字を描画し、その上に少し細い白い文字を重ねることで、明るい背景でも見える縁取りを作ります。
OpenCV の putTextは Hershey フォントを使用します。このサンプルは印字可能な ASCII を受け付け、空白のみのテキストや収まりきらないラベルは拒否します。任意の Unicode フォントの描画や、取り外し可能な字幕トラックの追加は行いません。
動画処理のテスト
三つのファイルをすべて調べてから、選択された映像ストリームと音声ストリームをすべてデコードします。次のブロックを Bash に貼り付けてください。サブシェル内で実行するため、失敗しても現在のシェルは終了しません。
(
for output in ./transcoded.mp4 ./resized.mp4 ./watermarked.mp4; do
ffprobe -v error -count_frames \
-show_entries stream=codec_type,codec_name,width,height,sample_rate,channels,nb_read_frames:format=duration \
-of json "$output" || exit 1
ffmpeg -nostdin -v error -xerror -err_detect explode -i "$output" \
-map 0:v:0 -map '0:a:0?' -f null - || exit 1
done
)
生成した入力を使う場合、どの出力も H.264 映像となり、デコードされるフレーム数は 59 になるはずです。トランスコードと透かし追加の出力は 640 × 360 のままで、サイズ変更の出力は 320 × 180 です。各ファイルには 48,000 Hz のモノラル AAC 音声も含まれ、長さは約 2.36 秒になるはずです。AAC のフレーム構造により、少量のパディングが加わる場合があります。ffprobe は比較用にこれらのプロパティを表示します。このブロックは値を自動的に検証するものではありません。
出力を最終フレームまで再生し、トーンも最後まで聴いてください。サイズ変更後の縦横比が意図どおりであることと、Preview が透かし追加の出力にだけ表示されることを確認してください。ストリームのメタデータと、ファイルが空でないことだけでは、これらの映像と音声の結果は確認できません。
出力パスには必ず未使用のパスを指定してください。同じ操作を再実行すると、ファイルが既存であることを示すエラーが発生し、既存のバイト列は保持されます。出力に入力自体を指定した場合も同様です。このプログラムが出力先を作成した後で失敗が報告された場合、ネイティブリソースを閉じてから出力先を削除します。ただし、プロセスの強制終了やマシンのクラッシュでは、不完全なファイルが残ることがあります。検証が完了するまでは元のファイルを保持してください。
Maven がコンパイル失敗を報告した場合は、Java を呼び出す前に修正してください。クラスが見つからないエラーは通常、プロジェクトルート以外でコマンドを実行しているか、ビルドが完了していないことを示します。ネイティブライブラリの読み込みエラーが発生した場合は、アーキテクチャと target/dependency 内の classifier 付き JAR を確認してください。ある JavaCV リリースのバインディングと、別のリリースのネイティブライブラリを混在させないでください。
メモリ管理とパフォーマンスの最適化
JavaCV はデコード済みフレームの格納領域を再利用します。ループでは次のフレームを取得する前に各フレームを処理し、サイズ変更用のバッファーを一つ再利用します。また、try-with-resources により、グラバー、レコーダー、コンバーター、所有する OpenCV オブジェクトを閉じます。動画全体を Java ヒープに蓄積することはありません。
最初は一度に一つの処理を実行してください。各エンコーダーは独自のネイティブバッファーを持ち、複数のスレッドを使用する場合もあるため、CPU コアごとに一つの処理という設定は、同時実行数の初期値として適切ではありません。上限付きのワーカーキューを追加する前に、実際に使う解像度でメモリ使用量とスループットを測定してください。入力検証もソース全体をデコードするため、処理量は増えますが、エンコード前に入力の破損を検出できます。
エンコード処理を外部に任せたいアプリケーションには、Transloadit の動画エンコーディングサービスを検討してください。ローカルのエンコーダーをホスト型のワークフローに置き換える場合も、同じ出力検証を行ってください。
