Java と Qtfaststart で MP4 配信を効率化
qtfaststart-java を使うと、再エンコードせずに、完成した MP4 の再生インデックスをメディアデータより前に移動できます。このガイドでは、Java のコマンドラインラッパーを作成し、ライブラリの書き込み先を専用の一時ディレクトリに限定して、配信前に結果を元ファイルと比較します。
ファストスタートによる変更点
MP4 ファイルは、トラックとタイミングの情報を moov アトムに、メディアのペイロードを mdat アトムに格納します。moov がメディアの後ろにある場合、プレーヤーはインデックスの取得に追加の HTTP 範囲リクエストを必要とすることがあります。範囲リクエストを利用できなければ、ダウンロードを待つ必要があります。インデックスを前方に移動すると、シーケンシャルダウンロードの開始直後に近い段階で取得できるようになります。
これは、プログレッシブ MP4 ストリーミング向けのファイル構造の最適化です。エンコード済みビットレートやコーデックは変更せず、アダプティブストリーミング用のレンディションも作成しません。再生開始は引き続きプレーヤー、バッファリング、HTTP サーバーに依存します。この例では再生開始時間のベンチマークは行いません。FFmpeg の MOV/MP4 マルチプレクサーのドキュメントでは、ファストスタートとフラグメント化出力が区別されています。
Java プロジェクトのセットアップ
開発元のプロジェクトは、移動処理を純粋な Java で実装しています。0.1.0 タグは 2014年のもので、インストール手順には今も JCenter が記載されています。以下のバージョン固定の
JitPack アーティファクトを使ってください。似た名前の別ライブラリに置き換えないでください。これはレガシーな依存ライブラリであり、汎用的な MP4 検証ツールではありません。
Bash とハードリンク対応のファイルシステムを備えた Linux を使ってください。保守されている JDK 21 のビルド、Maven、および
FFmpeg と FFprobe の両方を含むパッケージをインストールしてください。検証スクリプトには cmp、mktemp、rm も必要です。テスト済みのバージョンは OpenJDK 21.0.12.1、Maven 3.10.0 と 3.9.11、FFmpeg/FFprobe 9.0.1 です。これらはテスト済みのバージョンであり、本質的な最低要件ではありません。
書き込み可能なディレクトリから始めてください。プロジェクトを作成する前に、すべての実行ファイルを確認します。
(
for tool in java javac mvn ffmpeg ffprobe cmp mktemp rm mkdir; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'Missing prerequisite: %s\n' "$tool" >&2
exit 1
}
done
java -version && javac -version &&
MAVEN_SKIP_RC=true MAVEN_BASEDIR="$PWD/qtfaststart-demo" MAVEN_ARGS= mvn -version &&
ffmpeg -version && ffprobe -version &&
mkdir qtfaststart-demo &&
mkdir -p qtfaststart-demo/.mvn qtfaststart-demo/src/main/java
)
qtfaststart-demo が既に存在すると、セットアップは停止します。既存のファイルは残し、別の親ディレクトリで新しく始めてください。2番目の mkdir が失敗した場合は、ディレクトリの権限を修正し、同じプロジェクト内に不足している二つのサブディレクトリを作成してから続行してください。サブシェルを使うため、現在のディレクトリとシェルオプションは変更されません。
次の完全な pom.xml を qtfaststart-demo/ に保存してください。
<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>local.example</groupId>
<artifactId>qtfaststart-demo</artifactId>
<version>1.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.ypresto</groupId>
<artifactId>qtfaststart-java</artifactId>
<version>0.1.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<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>
その隣に settings.xml を保存してください。ビルドには個人の Maven 設定ではなくこの設定を使用し、依存関係をプロジェクトの .m2-repository にダウンロードします。プロジェクト固有の .mvn ディレクトリと明示的なベースディレクトリにより、上位プロジェクトの Maven 設定から分離します。
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"/>
ラッパーの保存と実行
正常であることが分かっている、完成済みの非フラグメント化 MP4 を使ってください。入力の moov メタデータは非圧縮である必要があります。テスト済みの組み合わせは H.264 映像と AAC 音声で、複数トラックも含みます。処理中は入力と出力の親ディレクトリを変更せず、コピーをもう一つ保存できるディスク容量を確保してください。ライブラリは moov をメモリに読み込みます。この例は信頼できるローカルファイルを対象としており、信頼できないアップロードや破損した録画の修復を対象としていません。
OptimizeMp4.java を qtfaststart-demo/src/main/java/ に保存してください。
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import net.ypresto.qtfaststart.QtFastStart;
import net.ypresto.qtfaststart.QtFastStart.QtFastStartException;
public class OptimizeMp4 {
public static boolean optimize(Path input, Path output)
throws IOException, QtFastStartException {
input = input.toRealPath();
if (!Files.isRegularFile(input)) {
throw new IOException("Input must be a regular file: " + input);
}
output = output.toAbsolutePath();
if (Files.exists(output, LinkOption.NOFOLLOW_LINKS)) {
throw new IOException("Output already exists: " + output);
}
Path directory = Files.createTempDirectory(output.getParent(), ".qtfaststart-");
Path temporary = directory.resolve("optimized.mp4");
try {
boolean moved = QtFastStart.fastStart(input.toFile(), temporary.toFile());
if (!moved) return false;
if (Files.size(temporary) != Files.size(input)) {
throw new IOException("Relocation produced an incomplete copy");
}
Files.createLink(output, temporary);
return true;
} finally {
Files.deleteIfExists(temporary);
Files.delete(directory);
}
}
public static void main(String[] args) {
if (args.length != 2) {
System.err.println("Usage: OptimizeMp4 INPUT.mp4 OUTPUT.mp4");
System.exit(64);
}
try {
if (!optimize(Path.of(args[0]), Path.of(args[1]))) {
System.err.println("No output created: already front-indexed or unsupported layout."
+ " This does not validate the input.");
System.exit(2);
}
System.out.println("Relocated MP4 saved to " + args[1] + "; verify it before serving.");
} catch (IOException | QtFastStartException | RuntimeException e) {
System.err.println("Failed for " + args[0] + ": " + e.getMessage());
System.exit(1);
}
}
}
元ファイルを qtfaststart-demo/input.mp4 にコピーし、親ディレクトリで次を貼り付けてください。
(
cd qtfaststart-demo &&
MAVEN_SKIP_RC=true MAVEN_BASEDIR="$PWD" MAVEN_ARGS= \
mvn -B -s settings.xml -gs settings.xml -Dmaven.repo.local=.m2-repository \
clean package dependency:copy-dependencies &&
java -cp 'target/classes:target/dependency/*' OptimizeMp4 \
./input.mp4 ./output_optimized.mp4
)
dependency-copy ゴールは、表示されるクラスパスが参照する JAR を用意します。依存関係の解決やコンパイルが失敗した場合、&& が古いビルドの実行を防ぎます。エラーを修正し、このブロックを再実行してください。移動処理が完了すると、プログラムは output_optimized.mp4 を作成し、終了コードはゼロになります。終了コードが二の場合は出力を残さず、一の場合は処理またはファイルシステムの障害を報告します。再実行時には、既存の出力への書き込みを拒否します。
0.1.0 の実装は、出力を書き込み用に開き、移動処理が完了しなかった場合は削除します。既存のファイルをライブラリに直接渡すと、そのファイルを失うおそれがあります。ラッパーはライブラリに専用のパスだけを渡し、Files.createLink で完成したファイルを公開します。テストした Linux ファイルシステムでは、リンク先のないシンボリックリンクや処理中に作成された出力先も含め、既存の出力先を置き換えずに拒否します。
ファイル構造とメディアの検証
ラッパーの戻り値がゼロでも、確認できるのは移動処理の完了であり、メディアの完全性ではありません。次を qtfaststart-demo/verify-mp4.sh として保存してください。FFprobe が報告する最上位アトムの順序を確認し、すべてのストリームとパケットのタイミングおよびエンコード済みデータのチェックサムを比較します。さらに、デコードしたすべての映像フレームと音声サンプルを比較します。両方の引数には、/、./、または ../ で始まる明示的なローカルパスを使ってください。
#!/usr/bin/env bash
set -euo pipefail
if [ "$#" -ne 2 ]; then
printf 'Usage: bash verify-mp4.sh INPUT.mp4 OUTPUT.mp4\n' >&2
exit 64
fi
input=$1
output=$2
for path in "$input" "$output"; do
case "$path" in
/*|./*|../*) ;;
*) printf 'Use an explicit local path: %s\n' "$path" >&2; exit 64 ;;
esac
done
work=$(mktemp -d)
trap 'rm -rf -- "$work"' EXIT
ffprobe -v trace -i "$output" -show_entries format=format_name \
-of default > /dev/null 2> "$work/atoms.log"
seen_moov=false
seen_mdat=false
while IFS= read -r line; do
case "$line" in
*"type:'moov' parent:'root'"*)
[ "$seen_moov" = false ] || exit 1
seen_moov=true ;;
*"type:'mdat' parent:'root'"*)
[ "$seen_moov" = true ] || { printf 'moov follows media\n' >&2; exit 1; }
seen_mdat=true ;;
*"type:'moof' parent:'root'"*) printf 'Fragmented MP4 is outside this example\n' >&2; exit 1 ;;
esac
done < "$work/atoms.log"
[ "$seen_moov" = true ] && [ "$seen_mdat" = true ]
entries='stream=index,codec_type,codec_name,profile,width,height,pix_fmt,sample_rate,channels,channel_layout,time_base,start_pts,start_time,duration_ts,duration,nb_frames,extradata_hash:stream_tags:stream_side_data:packet=stream_index,pts,dts,duration,size,flags,data_hash'
ffprobe -v error -show_entries "$entries" -show_data_hash sha256 \
-of json -i "$input" > "$work/input.json"
ffprobe -v error -show_entries "$entries" -show_data_hash sha256 \
-of json -i "$output" > "$work/output.json"
cmp "$work/input.json" "$work/output.json"
ffmpeg -nostdin -v error -xerror -threads 1 -noautorotate -i "$input" \
-map 0:v? -map 0:a? -c:v rawvideo -c:a pcm_s16le -threads 1 \
-f framemd5 "$work/input.framemd5"
ffmpeg -nostdin -v error -xerror -threads 1 -noautorotate -i "$output" \
-map 0:v? -map 0:a? -c:v rawvideo -c:a pcm_s16le -threads 1 \
-f framemd5 "$work/output.framemd5"
cmp "$work/input.framemd5" "$work/output.framemd5"
printf 'Verified: moov precedes media; stream data, timing, and decoded audio/video match.\n'
保存したスクリプトは別の Bash プロセスとして実行してください。その set 文と exit 文を現在のシェルに貼り付けないでください。
(
cd qtfaststart-demo &&
bash verify-mp4.sh ./input.mp4 ./output_optimized.mp4
)
成功すると Verified: moov precedes media; stream data, timing, and decoded audio/video match. と表示されます。インデックスの移動とチャンクオフセットの変更により、通常は入力と出力のファイルハッシュが異なります。そのため、この検証ではメディアとタイミングを比較します。自動回転を無効にすることで、デコードしたフレームを一貫した条件で比較します。ストリームのサイドデータでは、回転メタデータが保持されているか確認します。結果が一致しても、元の録画が破損していなかったとは断定できず、ブラウザーでの再生を測定するものでもありません。
出力なしと失敗への対処
ライブラリの最終アトムのチェックは、走査が moov で終わらない場合に false を返します。これにはインデックスが既に前方にあるファイルだけでなく、未対応の構造や一部の不正な入力も含まれます。false を「最適化済み」と解釈したり、存在しない出力を配信したりしないでください。元ファイルを別途調べるか、別の処理方法を選んでください。
圧縮された moov メタデータと、一部のチャンクオフセットのオーバーフローには対応していません。不正なファイルでは、ライブラリ例外、I/O 例外、非検査例外が発生することがあります。検証でデコードエラーや差異が報告された場合は、元ファイルを保持し、出力を配信しないでください。ラッパーのサイズチェックは不完全なコピーを検出しますが、サイズが同じだけではメディアが正しいとは判断できません。
出力の親ディレクトリが書き込み不可または存在しない場合、ハードリンクに対応していない場合、出力が既に存在する場合は、終了コードがゼロ以外になります。通常の失敗では、finally ブロックが専用の一時ファイルとディレクトリを削除します。JVM の強制終了やクリーンアップ中のファイルシステム障害により、.qtfaststart-* ディレクトリが残ることがあります。そのプロセスの停止を確認したうえで、その実行に対応する一時ディレクトリだけを削除してください。
代替手段
処理パイプラインに FFmpeg が既に含まれている場合は、マルチプレクサーのファストスタートオプションを使えば、レガシーな Java 依存ライブラリを追加せずに済みます。同じローカル入力に対して、再エンコードせずにすべてのストリームを再多重化します。
(
cd qtfaststart-demo &&
ffmpeg -nostdin -n -i ./input.mp4 -map 0 -c copy -movflags +faststart ./output_ffmpeg.mp4
)
-n は既存の出力を変更せず、-map 0 はすべてのストリームを選択します。FFmpeg 9.0.1 では、既存ファイルへの書き込み拒否時にエラー診断が出ても戻り値はゼロでした。そのため、新しい出力先を使い、ステータスだけに頼らず結果を確認してください。コーデックは MP4 マルチプレクサーが対応している必要があります。これは再多重化であり、FFmpeg はコンテナのメタデータやタイミングを書き換えることがあります。したがって、上記の厳密な比較は Java による移動処理のためのもので、汎用的な FFmpeg の受け入れテストではありません。
MP4 配信の次のステップ
依存ライブラリの調査には qtfaststart-java の GitHub リポジトリを、マルチプレクサーのオプションには FFmpeg のフォーマットリファレンスを、コンテナとコーデックの基礎知識には MDN の MP4 コンテナガイドを参照してください。より広範なエンコードワークフローについては、Transloadit の 🤖 /video/encode Robotを参照してください。
