Scala と FFmpeg による動画の連結
同じ設定で書き出したクリップを連結するには、Scala から FFmpeg の concat デマルチプレクサーを呼び出し、映像と音声のストリームを一つの MP4 にコピーします。以下のプログラムは入力を検証し、引数の順序で連結します。検証または FFmpeg の処理に失敗すると、ゼロ以外の終了ステータスを返します。既存の出力先への上書きは拒否します。
環境の準備
このチュートリアルでは、Linux x86-64、Bash、OpenJDK 21.0.12.1、Scala CLI 1.17.1、Scala 3.3.7 を使います。ネイティブツールによるメディア検証には FFmpeg と ffprobe 9.0.1 を使います。java、ffmpeg、ffprobe、curl、gzip を
PATH から実行できるようにしてください。サンプルクリップの生成コマンドには、FFmpeg の libx264 と aac エンコーダーも必要です。
Scala のインストール
Scala CLI の Linux リリースを使い、この例のディレクトリ内にランチャーを配置します。新しいプロジェクトを作成できるディレクトリで、以下のブロックを Bash に貼り付けてください。scala-video-concat がすでに存在する場合は、別の親ディレクトリを選んでください。セットアップは既存のプロジェクトを変更せずに停止します。
(
set -eu
mkdir scala-video-concat
cd scala-video-concat
curl -fsSLo scala-cli.gz https://github.com/VirtusLab/scala-cli/releases/download/v1.17.1/scala-cli-x86_64-pc-linux.gz
gzip -d scala-cli.gz
chmod +x scala-cli
./scala-cli version
)
以降のシェルコマンドも親ディレクトリで実行してください。括弧により、各ブロックでのディレクトリ変更はそのブロック内だけに限定されます。以下の Scala コードを scala-video-concat/Concat.scala として保存してください。コード内の using scala ディレクティブでコンパイラーのバージョンを固定しています。初回実行時にはコンパイラーと標準ライブラリをダウンロードするため、ネットワークアクセスが必要です。アプリケーションライブラリへの依存関係はありません。--jvm system はインストール済みの JDK を使い、--server=false はバックグラウンドのコンパイルサーバーを無効にします。
FFmpeg のインストール
FFmpeg のダウンロードページから、使用するディストリビューション向けの FFmpeg ビルドをインストールしてください。両方のツールが実行できることを確認します。
java -version && ffmpeg -version && ffprobe -version
動画の連結方法
concat デマルチプレクサーは、ファイルのリストを一つの入力として読み込みます。-c copy を指定すると、FFmpeg は圧縮済みパケットを再エンコードせずにリマックスします。ファイルの拡張子が一致するだけでは不十分です。ストリームのコーデック、設定、タイムベースに互換性が必要です。
この例で受け付けるのは、H.264 映像ストリームが一つ、その後に AAC 音声ストリームが一つだけ続く、完全なローカル MP4 クリップです。解像度、フレームレート、ピクセル形式、音声サンプルレート、チャンネルレイアウトなどを同じ設定で書き出してください。音声と映像の長さが揃ったクリップを使います。デマルチプレクサーは直前のファイルの長さに基づいて次のクリップの開始位置をずらすため、トラックの長さが異なると隙間が生じることがあります。回転したクリップや追加のトラックは、この例の対象外です。
事前検証では、ffprobeから取得したストリームの一部のプロパティと、コーデック設定のハッシュを比較します。不一致があれば、変換を試みずに意図的に拒否します。これは互換性の検証であり、破損の有無を全面的に調べるものではありません。ストリームコピーではすべてのフレームをデコードしないため、ヘッダーが一致しても、すべてのパケットが有効だとは判断できません。
Scala プログラム全体の保存
//> using scala 3.3.7
import java.nio.charset.StandardCharsets.UTF_8
import java.nio.file.{Files, LinkOption, Path, Paths}
import java.util.Locale
import scala.sys.process.Process
import scala.util.control.NonFatal
object Concat:
def checkedPath(value: String): Path =
require(!value.exists(c => c == '\n' || c == '\r'), "Paths cannot contain line breaks")
Paths.get(value).toAbsolutePath
def signature(input: Path): String =
val fields = "codec_name,codec_type,profile,level,codec_tag_string,width,height," +
"pix_fmt,sample_aspect_ratio,field_order,r_frame_rate,time_base," +
"sample_fmt,sample_rate,channels,channel_layout,extradata_hash"
val info = Process(Seq(
"ffprobe", "-v", "error", "-show_data_hash", "sha256",
"-show_entries", s"stream=$fields:stream_side_data=rotation",
"-of", "default=noprint_wrappers=1", input.toString
)).!!
val lines = info.linesIterator.toVector
require(
lines.filter(_.startsWith("codec_name=")) == Vector("codec_name=h264", "codec_name=aac"),
s"Expected one H.264 video followed by one AAC audio stream: $input"
)
require(!lines.exists(_.startsWith("rotation=")), s"Rotated video is unsupported: $input")
require(lines.count(_.startsWith("extradata_hash=")) == 2, s"Missing codec configuration: $input")
info
def concatenate(args: Array[String]): Unit =
require(args.length >= 3, "Usage: Concat <output.mp4> <input1.mp4> <input2.mp4> [more.mp4 ...]")
val output = checkedPath(args(0))
require(output.toString.toLowerCase(Locale.ROOT).endsWith(".mp4"), "Output must end in .mp4")
require(!Files.exists(output, LinkOption.NOFOLLOW_LINKS), s"Output already exists: $output")
require(Files.isDirectory(output.getParent), s"Output directory does not exist: ${output.getParent}")
val inputs = args.drop(1).toVector.map { value =>
val path = checkedPath(value).toRealPath()
checkedPath(path.toString)
require(Files.isRegularFile(path) && Files.isReadable(path), s"Not a readable file: $path")
require(path.toString.toLowerCase(Locale.ROOT).endsWith(".mp4"), s"Input must end in .mp4: $path")
path
}
val first = signature(inputs.head)
for input <- inputs.tail do
require(signature(input) == first, s"Stream settings differ from the first clip: $input")
val list = Files.createTempFile("scala-concat-", ".ffconcat")
try
val entries = inputs.map { path =>
val escaped = path.toString.replace("'", "'\\''")
s"file '$escaped'"
}
Files.writeString(list, entries.mkString("\n") + "\n", UTF_8)
val status = Process(Seq(
"ffmpeg", "-hide_banner", "-loglevel", "warning", "-nostdin", "-n",
"-f", "concat", "-safe", "0", "-i", list.toString,
"-map", "0:v:0", "-map", "0:a:0", "-c", "copy", output.toString
)).!
if status != 0 then throw IllegalStateException(s"FFmpeg failed (exit $status)")
finally
Files.deleteIfExists(list)
println(s"Created $output")
def main(args: Array[String]): Unit =
try concatenate(args)
catch
case NonFatal(error) =>
Console.err.println(s"Concatenation failed: ${error.getMessage}")
sys.exit(1)
Process(Seq(...)) はシェルを介さず、個別の引数を渡します。一時リストには FFmpeg 独自の引用規則が適用されるため、コードではリスト内のアポストロフィもエスケープします。ローカルファイル名に空白、アポストロフィ、先頭のハイフンが含まれていても動作しますが、改行は拒否します。-safe 0 は、このプログラムが生成するリスト内の絶対パスを許可します。自分で信頼できるクリップを使い、実行中は変更しないでください。
二つのクリップでの実行
クリップを scala-video-concat に配置するか、以下のコマンドで小さな入力を二つ生成してください。一つ目は赤い映像と 440 Hz の音、二つ目は青い映像と 880 Hz の音です。どちらも長さは二秒です。これらのコマンドも既存のファイルの置き換えを拒否します。
(
set -eu
cd scala-video-concat
for clip in 'part 1.mp4' 'part 2.mp4'; do
if [ -e "$clip" ] || [ -L "$clip" ]; then
printf 'Sample already exists: %s\n' "$clip" >&2
exit 1
fi
done
ffmpeg -hide_banner -loglevel error -nostdin -n \
-f lavfi -i 'color=c=red:s=320x240:r=25:d=2' \
-f lavfi -i 'sine=frequency=440:sample_rate=48000:duration=2' \
-c:v libx264 -pix_fmt yuv420p -c:a aac -ac 2 -shortest 'part 1.mp4'
ffmpeg -hide_banner -loglevel error -nostdin -n \
-f lavfi -i 'color=c=blue:s=320x240:r=25:d=2' \
-f lavfi -i 'sine=frequency=880:sample_rate=48000:duration=2' \
-c:v libx264 -pix_fmt yuv420p -c:a aac -ac 2 -shortest 'part 2.mp4'
)
保存したプログラムを親ディレクトリから実行します。-- より後の引数は Concat に渡されます。最初に出力先を指定し、その後に再生順で入力を指定します。さらに連結するには、入力パスを追加してください。
(
cd scala-video-concat &&
./scala-cli run Concat.scala --server=false --jvm system -- \
joined.mp4 'part 1.mp4' 'part 2.mp4'
)
成功すると、プログラムは joined.mp4 の絶対パスを表示し、終了ステータスゼロで終了します。サンプルクリップでは、ステレオ音声付きの 320 × 240 の動画が約四秒になります。最初に赤い映像と低い音、続いて青い映像と高い音が再生されます。AAC パケットのタイミングにより、コンテナーの長さが四秒を少し超えることがあります。FFmpeg が連結位置で重複する AAC パケットのタイムスタンプを調整し、警告を表示することもあります。ストリームコピーは、サンプル単位で正確なギャップレス音声を保証するものではありません。必要な場合は、音声のデコードとエンコードを行うパイプラインを使ってください。ストリームを調べ、結果全体をデコードします。
(
cd scala-video-concat &&
ffprobe -v error -show_entries stream=codec_name,width,height,sample_rate,channels:format=duration \
-of json joined.mp4 &&
ffmpeg -hide_banner -loglevel error -nostdin -xerror -i joined.mp4 \
-map 0:v:0 -map 0:a:0 -f null -
)
エラー処理と最適化
入力の欠落、読み取れないメディア、未対応のトラック、ストリーム設定の相違がある場合は、標準エラー出力にエラーを出力し、終了ステータス一で終了します。解析または連結に失敗すると、プログラムの失敗メッセージより前に FFmpeg の診断情報が表示されます。対話的に実行する場合は、直後に echo $? でシェルのステータスを確認してください。または、呼び出し元のジョブでプログラムの終了ステータスを利用してください。
出力先の確認は入力の検証より先に行います。joined.mp4 がすでに存在する状態で再実行すると、入力が欠落していても処理は失敗し、既存のファイルは保持されます。FFmpeg の -n オプションも、起動時に上書きを拒否します。-nostdin は対話プロンプトを抑止します。出力先ごとに書き込み元を一つにしてください。この例には並行プロセスを調整する仕組みはありません。
通常の成功時と失敗時には、一時リストを削除します。FFmpeg が出力先を開いた後に失敗すると、不完全な MP4 が残ることがあります。失敗した出力は自分で確認して削除するか、再試行前に別の名前を選んでください。プロセスが突然終了した場合も、一時ファイルが残ることがあります。終了ステータスゼロは、リマックスの完了を示します。メディアの整合性と連結部分は、デコード検証と再生で確認してください。
変換が必要なクリップへの対応
ストリーム検証でクリップが拒否された場合は、このプログラムを使う前に、統一した設定で書き出し直してください。解像度が混在する場合、音声がない場合、コーデックが異なる場合には、別途デコードとエンコードを行うパイプラインが適しています。FFmpeg の concat フィルターには、各セグメントの開始タイムスタンプがゼロであり、解像度に互換性があることが必要です。音声がない場合は、無音を追加するなどの明示的な方針が必要です。デマルチプレクサーからこのフィルターに切り替えるだけでは、任意の入力を正規化できません。
クロスフェードにも再エンコードが必要です。また、クリップが重なるため、連結後の長さも変わります。xfade フィルターには、映像形式とタイムベースに関する要件があり、音声には別途トランジションが必要です。保存したプログラムは単純なカットで連結し、両方のトラックを保持します。トランジションモードは実装していません。
