Scala と FFmpeg によるリアルタイム動画処理
Scala でライブ RTSP テストフィードを起動し、FFmpeg で変換して、生成した HLS ストリームをローカル HTTP で配信します。タイムスタンプ付きの動くグレースケールパターンを表示し、12秒間の録画を保存します。この例は Linux で動作し、カメラは不要です。デモの終了時には、起動したサービスを停止します。
重要なのは、プロセスを誰が管理するかという境界です。Scala は FFmpeg を起動して実際の終了を待ち、期限とシャットダウンフックで停止できるようにします。Scala の Future を待つだけでは、外部エンコーダーはキャンセルされません。扱うのは、単一品質の映像のみのストリームで、通常の HLS バッファリングを使用します。本番環境の遅延目標やアダプティブビットレート配信を実証する例ではありません。
Scala と FFmpeg のセットアップ
この手順は Linux x86-64 上で、OpenJDK 21.0.12.1、Scala CLI 1.17.1、Scala 2.13.18、MediaMTX 1.21.1、FFmpeg/ffprobe/ffplay 9.0.1 を使ってテストしています。コマンドには Bash を使用してください。libx264、HLS マルチプレクサー、および
testsrc2、scale、hue、drawbox、drawtext フィルターを備えた
Linux 向け FFmpeg ビルドをインストールしてください。上記の JDK、cURL、gzip、tar、awk、fontconfig の fc-match、および Liberation Sans などのインストール済み TrueType フォントも必要です。FFplay で映像を表示するには、グラフィカルデスクトップが必要です。
java -version && ffmpeg -version && ffprobe -version && ffplay -version &&
fc-match 'Liberation Sans'
新しいプロジェクトを作成し、バージョンを固定した
Scala CLI と
MediaMTX のリリースをダウンロードします。MediaMTX はローカルの RTSP 接続先です。FFmpeg がここに配信し、別の FFmpeg プロセスがそのストリームを読み取ります。書き込み可能な親ディレクトリで、次のブロックを貼り付けてください。scala-live-demo がすでに存在する場合、セットアップはそのディレクトリを変更せずに停止します。やり直すには、別の親ディレクトリを選んでください。
(
mkdir scala-live-demo &&
cd scala-live-demo &&
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 &&
curl -fsSLo mediamtx.tar.gz https://github.com/bluenviron/mediamtx/releases/download/v1.21.1/mediamtx_v1.21.1_linux_amd64.tar.gz &&
tar -xzf mediamtx.tar.gz mediamtx &&
font_file=$(fc-match -f '%{file}' 'Liberation Sans') &&
test -r "$font_file" &&
cp "$font_file" font.ttf &&
./scala-cli version && ./mediamtx --version
)
以降のコマンドも親ディレクトリで実行してください。括弧で囲んだ各ブロックでは、ディレクトリの変更とシェルオプションがブロック内だけに適用されます。ダウンロードに失敗すると、新しいプロジェクトが不完全な状態で残ることがあります。内容を確認し、別の親ディレクトリで再試行してください。以下のプログラム全体を
scala-live-demo/Live.scala として保存してください。初回ビルドでは Scala コンパイラーとライブラリをダウンロードします。追加のアプリケーション依存関係はありません。コマンドは
Live.scala を明示的に対象とし、外側の sbt プロジェクトはビルド入力にしません。
Scala と FFmpeg の統合
このプログラムは、シェルコマンドに文字列を埋め込むのではなく、Java の
ProcessBuilder に引数を個別に渡します。非公開の MediaMTX 設定を書き込み、HTTP をループバックにバインドし、デフォルトで利用可能なポートを選択します。配信するのはプレイリストと書き込み完了済みのセグメントファイル名だけで、設定、フォント、ログは HTTP で公開しません。
//> using scala 2.13.18
import com.sun.net.httpserver.{HttpExchange, HttpServer}
import java.net.{InetAddress, InetSocketAddress, ServerSocket}
import java.nio.file.{Files, LinkOption, Path, Paths}
import java.util.concurrent.TimeUnit.SECONDS
import scala.collection.mutable.ArrayBuffer
import scala.util.control.NonFatal
object Live {
private val children = ArrayBuffer.empty[(String, java.lang.Process)]
private var http: Option[HttpServer] = None
private var stopping = false
@volatile private var encoded = false
private def stopOwned(): Unit = synchronized {
stopping = true
http.foreach(_.stop(0))
http = None
for ((name, child) <- children.reverse if child.isAlive) {
child.destroy()
if (!child.waitFor(2, SECONDS)) {
child.destroyForcibly()
require(child.waitFor(2, SECONDS), s"Could not stop $name")
}
}
children.clear()
}
private def start(name: String, args: Seq[String], out: Path): java.lang.Process = synchronized {
require(!stopping, "Run is stopping")
val builder = new ProcessBuilder(args: _*)
.directory(out.toFile)
.redirectErrorStream(true)
.redirectOutput(out.resolve(s"$name.log").toFile)
// Ambient MediaMTX overrides must not reopen listeners disabled by our configuration.
builder.environment().keySet().removeIf(key => key.startsWith("MTX_"))
val child = builder.start()
children += name -> child
println(s"Started $name (PID ${child.pid()})")
child
}
private def serve(exchange: HttpExchange, out: Path): Unit = {
try {
val name = exchange.getRequestURI.getPath.stripPrefix("/")
val allowed = name == "stream.m3u8" || name.matches("segment-[0-9]{3}\\.ts")
val file = out.resolve(name)
if (exchange.getRequestMethod != "GET") exchange.sendResponseHeaders(405, -1)
else if (!allowed || !Files.isRegularFile(file)) exchange.sendResponseHeaders(404, -1)
else {
val contentType = if (name.endsWith(".ts")) "video/mp2t" else "application/vnd.apple.mpegurl"
exchange.getResponseHeaders.set("Content-Type", contentType)
exchange.getResponseHeaders.set("Cache-Control", "no-store")
val bytes = Files.readAllBytes(file)
exchange.sendResponseHeaders(200, bytes.length)
exchange.getResponseBody.write(bytes)
}
} finally exchange.close()
}
private def run(args: Array[String]): Unit = {
require(args.length >= 2 && args.length <= 4,
"Usage: Live <new-directory> <deadline-seconds> [rtsp-port] [http-port]")
val seconds = args(1).toInt
require(seconds >= 1 && seconds <= 120, "Deadline must be between 1 and 120 seconds")
val ports = args.drop(2).map(_.toInt)
require(ports.forall(port => port >= 0 && port <= 65535), "Invalid port")
val project = Paths.get(".").toRealPath()
val out = project.resolve(args(0)).normalize()
require(out.getParent == project, "Use a new direct child directory of this project")
require(!Files.exists(out, LinkOption.NOFOLLOW_LINKS), "Output directory already exists")
require(Files.isReadable(project.resolve("font.ttf")), "Missing readable font.ttf")
Files.createDirectory(out)
Files.copy(project.resolve("font.ttf"), out.resolve("font.ttf"))
val deadline = System.nanoTime() + SECONDS.toNanos(seconds)
def checkDeadline(): Unit =
require(System.nanoTime() < deadline, "Run deadline exceeded; output may be partial")
def alive(name: String, child: java.lang.Process): Unit =
require(child.isAlive, s"$name stopped (exit ${child.exitValue()}); inspect $name.log")
def waitUntil(ready: => Boolean)(check: => Unit): Unit = {
while (!ready) { checkDeadline(); check; Thread.sleep(100) }
checkDeadline()
}
val hook = new Thread(() => {
Console.err.println(if (encoded) "Stopped; completed HLS retained" else "Cancelled; output may be partial")
stopOwned()
})
Runtime.getRuntime.addShutdownHook(hook)
try {
println(s"Controller PID ${ProcessHandle.current().pid()}")
val requestedRtsp = ports.headOption.getOrElse(0)
val reservation = new ServerSocket(requestedRtsp, 1, InetAddress.getByName("127.0.0.1"))
val rtspPort = reservation.getLocalPort
reservation.close()
val server = synchronized {
require(!stopping, "Run is stopping")
val listener = HttpServer.create(new InetSocketAddress("127.0.0.1", ports.lift(1).getOrElse(0)), 0)
http = Some(listener)
listener.createContext("/", exchange => serve(exchange, out))
listener.start()
listener
}
val url = s"rtsp://127.0.0.1:$rtspPort/live"
val config = out.resolve("mediamtx.yml")
Files.writeString(config, s"""logLevel: info
rtsp: yes
rtspAddress: 127.0.0.1:$rtspPort
rtspTransports: [tcp]
rtmp: no
hls: no
webrtc: no
srt: no
moq: no
api: no
metrics: no
pprof: no
playback: no
paths:
live:
source: publisher
""")
val mtx = start("mediamtx", Seq(project.resolve("mediamtx").toString, config.toString), out)
def serverLog: String = Files.readString(out.resolve("mediamtx.log"))
waitUntil(serverLog.contains("[RTSP] started with listeners")) { alive("mediamtx", mtx) }
val common = Seq("ffmpeg", "-hide_banner", "-loglevel", "warning", "-nostdin")
val source = start("source", common ++ Seq(
"-re", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=10", "-t", "45",
"-an", "-c:v", "libx264", "-threads", "2", "-preset", "ultrafast",
"-tune", "zerolatency", "-g", "10", "-pix_fmt", "yuv420p",
"-f", "rtsp", "-rtsp_transport", "tcp", url), out)
waitUntil(serverLog.contains("is publishing to path 'live'")) {
alive("mediamtx", mtx); alive("source", source)
}
val filter = "scale=160:90,hue=s=0,drawbox=x=0:y=0:w=iw:h=22:color=black:t=fill," +
"drawtext=fontfile=font.ttf:text='Scala %{pts\\:hms}':fontcolor=white:fontsize=12:x=5:y=4"
val encoder = start("encoder", common ++ Seq(
"-n", "-rtsp_transport", "tcp", "-timeout", "3000000", "-i", url,
"-map", "0:v:0", "-an", "-vf", filter, "-filter_threads", "2", "-frames:v", "120",
"-c:v", "libx264", "-threads", "2", "-preset", "ultrafast", "-tune", "zerolatency",
"-pix_fmt", "yuv420p", "-g", "20", "-sc_threshold", "0", "-flags", "+cgop",
"-f", "hls", "-hls_time", "2", "-hls_playlist_type", "event",
"-hls_flags", "independent_segments+temp_file", "-hls_segment_filename", "segment-%03d.ts",
"-progress", "progress.txt", "stream.m3u8"), out)
val playlist = out.resolve("stream.m3u8")
waitUntil(Files.exists(playlist)) {
alive("mediamtx", mtx); alive("source", source); alive("encoder", encoder)
}
val playback = s"http://127.0.0.1:${server.getAddress.getPort}/stream.m3u8"
Files.writeString(out.resolve("playback.url"), playback + "\n")
println(s"Play: $playback")
waitUntil(!encoder.isAlive) { alive("mediamtx", mtx); alive("source", source) }
require(encoder.exitValue() == 0, "Encoder failed; inspect encoder.log")
val frames = Files.readString(out.resolve("progress.txt")).linesIterator
.filter(_.startsWith("frame=")).toVector.lastOption
require(frames.exists(_.stripPrefix("frame=").trim == "120"), "Incomplete video; output may be partial")
require(Files.readString(playlist).contains("#EXT-X-ENDLIST"), "Playlist was not finalized")
encoded = true
Files.writeString(out.resolve("complete.txt"), "120 frames encoded\n")
println("Encoding complete; HTTP remains available until the run deadline")
while (System.nanoTime() < deadline) Thread.sleep(100)
} finally {
stopOwned()
Runtime.getRuntime.removeShutdownHook(hook)
}
println("Completed; services stopped and HLS retained")
}
def main(args: Array[String]): Unit = {
try run(args)
catch { case NonFatal(error) => Console.err.println(s"Live demo failed: ${error.getMessage}"); sys.exit(1) }
}
}
リアルタイム動画ストリーム処理
FFmpeg の -re は、CPU がエンコードできる最高速度で配信するのではなく、生成するソースの送出ペースを調整します。MediaMTX は
/live で配信元を受け入れ、エンコーダーは同じ
RTSP パスから
TCP トランスポートで読み取ります。この例では RTSP を使用します。RTMP や任意のカメラが同じ入力動作をするとは仮定しません。
フィルターは映像を 160 × 90 ピクセルにリサイズし、色を除去して、経過時間のタイムスタンプ付きの黒い帯を描画します。drawtext には、フォントファイルを明示した場合でも FFmpeg ビルドのフォント対応が必要です。fontconfig 対応ビルドでは、指定ファイルが無効だと別のフォントにフォールバックすることがあります。セットアップ時に選んだインストール済みフォントを使用し、表示されるオーバーレイを確認してください。動画フィルターにはデコードと再エンコードが必要で、-c:v copy では適用できません。
HLS では、エンコーダーは 10 fps で 20 フレームごとにキーフレームを配置し、2秒というセグメント長の目標に合わせます。event はすべてのセグメントを保持し、temp_file は書き込み完了後に各セグメントを最終的な名前で公開します。実行すると 120 フレームを生成してからプレイリストを確定します。これはライブソースを一定期間録画するもので、無制限のスライディングウィンドウ型アーカイブではありません。
実行可能な JAR をビルドし、デモを起動してください。--jvm system はインストール済みの JDK を使用し、--server=false はバックグラウンドのコンパイルサーバーを使用しないようにします。Scala CLI の --assembly によるパッケージ化は
Scala ランタイムを含めます。-f が置き換えるのは、この例の
live.jar だけです。&& は、再ビルドに失敗した場合に古い JAR が実行されるのを防ぎます。
(
cd scala-live-demo &&
./scala-cli --power package Live.scala --assembly --preamble=false --server=false --jvm system -f -o live.jar &&
java -jar live.jar hls 60
)
60秒の実行期限は、引数の検証とフォントの配置が終わってから計測を開始します。サービスの起動、エンコード、再生時間が対象で、コンパイルとシャットダウン時の待機は含みません。両方のポートは自動で選択されます。省略可能なプログラムの第3引数と第4引数で、RTSP と HTTP のポートを指定できます。ゼロを指定すると利用可能なポートを要求します。要求したポートが使用中なら起動は失敗します。実行ごとにプロジェクト直下の新しい出力ディレクトリが必要なため、hls で再実行しても既存の出力は保持されます。
FFmpeg 統合のテスト
プログラムが再生 URL を出力したら、同じ親ディレクトリで別のターミナルを開き、次のブロックを実行してください。HTTP サーバーはエンコード中から実行期限まで利用できます。上部の帯に白いタイムスタンプが表示された、動くグレースケールパターンが見えるはずです。-autoexit は、確定したストリームの終端で FFplay を閉じます。それより早く閉じるには q を押してください。
(
playback_url=$(cat scala-live-demo/hls/playback.url) &&
ffplay -autoexit "$playback_url"
)
デモが正常に終了すると、scala-live-demo/hls には
stream.m3u8、segment-000.ts から
segment-005.ts までの 6個のファイル、および
complete.txt が保存されます。ストリームを調べ、実際のプレイリストから録画全体をデコードしてください。
(
set -euo pipefail
cd scala-live-demo/hls &&
ffprobe -v error -show_entries stream=codec_name,width,height:format=duration \
-of json stream.m3u8 &&
ffmpeg -hide_banner -loglevel error -nostdin -xerror -progress pipe:1 -i stream.m3u8 \
-map 0:v:0 -f null - |
awk -F= '$1 == "frame" {frames=$2} END {if (frames != 120) {print "Expected 120 decoded frames" > "/dev/stderr"; exit 1}}'
)
想定される結果は、160 × 90 ピクセルの H.264 動画と、長さ 12秒のプレイリストです。プローブとデコードでは録画の構造と読み取り可否を確認し、再生ではフィルターの表示結果を確認します。フレーム数の確認は重要です。FFmpeg は -xerror を指定しても、欠落した HLS セグメントをスキップし、ゼロを返すことがあります。エンコーダーの終了ステータスがゼロでも、カメラフィードの完全性、知覚品質、エンドツーエンドの遅延が確認されたことにはなりません。
エラー処理とリソース管理
コントローラーは、エンコーダーの動作中に配信元と RTSP サーバーが稼働し続けているかを確認します。切断が起きると、FFmpeg は終了ステータスがゼロでもフレーム数が不足したまま終了することがあります。進捗チェックでは、その録画を完了扱いにしません。エンコーダーの失敗、ソースの停止、エンコード完了前の期限到達は、終了ステータス一を返します。ログでは各子プロセスを mediamtx.log、source.log、または encoder.log として識別します。エンコードに失敗した実行では、調査用に部分的なメディアが残ることがあり、complete.txt はありません。
途中で停止するには、デモを起動した最初のターミナルで Ctrl+C を押してください。JVM のシャットダウンフックは、新たな子プロセスの起動を禁止し、HTTP を停止して、子プロセスを終了させます。子プロセスごとに最大2秒待ち、強制終了後にさらに2秒待ちます。これは通常の割り込みと終了に適用され、捕捉できない kill やマシンのシャットダウンには適用されません。書き込み済みの出力は残ります。エンコード中にキャンセルした場合は、完了を報告しません。エンコード成功後に途中停止した場合は、完成した録画を保持します。
通常の期限に達すると、プログラムはサービスを停止し、エンコードが完了していれば終了ステータスゼロを返します。ローカルのプレイリストを再生するには出力ディレクトリを保持し、不要なら確認後にそのディレクトリだけを削除してください。プログラムは過去の実行結果を削除したり上書きしたりしません。プロジェクトにダウンロードしたツールと JAR も残るため、新しいディレクトリ名で再実行できます。
よくある問題のトラブルシューティング
- 起動に失敗した場合は、示されたログを読み、実行ファイルとフォントの前提条件を確認してください。プログラムはエラーを返す前に起動済みの子プロセスを停止します。プレイリストが利用可能になるまでは、再生 URL を出力しません。
- FFplay が接続できない場合は、デモの実行中に起動してください。シャットダウン後は、
ffplay -autoexit scala-live-demo/hls/stream.m3u8で完成したローカルファイルを再生してください。 - エンコードが期限に間に合わない場合は、
encoder.logを確認し、新しい出力ディレクトリで最大 120秒の期限を指定してください。期限を延ばしても、配信元の切断は修復されません。
別のフィルターを使うには、単一の filter 値を変更して
JAR を再ビルドし、新しい出力ディレクトリ名で起動してください。エンコードがソースの速度に追いつくかを測定する間は、FFmpeg のスレッド数制限を維持してください。Scala の Future を追加しても、起動するエンコーダーが増えるだけです。このエンコーダーが高速になったり、それらのプロセスをキャンセルできるようになったりはしません。既存のローカル録画を扱う場合は、Scala の連結ガイドで、互換性のあるファイルを再エンコードせずに結合する方法を説明しています。
