Rust による動画の HLS・MPEG-DASH 変換
Rust から FFmpeg を実行し、ローカル動画を HLS と MPEG-DASH に変換して、完成したファイルを HTTP で配信します。この手順では、単一の HLS レンディションと二種類の DASH 映像表現を作成し、それぞれの形式を ffplay で再生します。Rust のコードはプロセスとファイルを管理し、エンコードは FFmpeg が行うため、FFmpeg の開発用ヘッダーや Rust バインディングは不要です。
出力の仕組み
HLS は .m3u8 プレイリストを、DASH は XML の
.mpd マニフェストを使用します。どちらも、プレーヤーが
HTTP 経由で取得するメディアセグメントを記述します。アダプティブビットレート再生には、さらに複数の互換性のある表現と、状況の変化に応じてそれらを選択するプレーヤーが必要です。
HLS の例では、単一のエンコード結果をパッケージ化します。DASH の例では、共通の音声トラックを持つ 1920 × 1080 と 1280 × 720 の映像を用意します。これらのファイルを作成してローカルで再生することで確認できるのは、パッケージ化と再生です。帯域幅への適応、配信遅延の改善、本番用ストリーミングサービスの実現を示すものではありません。
Rust プロジェクトの準備
Linux 上の Bash、rustup で導入した安定版の
Rust ツールチェーン、および ffmpeg、ffprobe、ffplay を含む
FFmpeg ディストリビューションを使用します。一部のディストリビューションでは ffplay が別パッケージになっているため、プロジェクトを作成する前に確認してください。再生にはデスクトップセッションと音声出力が必要です。この処理構成は Rust と Cargo 1.98.1、および FFmpeg、ffprobe、ffplay 9.0.1 で検証しました。これらは検証済みのバージョンであり、必須の最低バージョンではありません。別のメンテナンス中のリリースを評価する際は、以下の機能確認を行ってください。
Ubuntu または Debian では、ディストリビューションのパッケージを使ってインストールできます。
sudo apt-get update && sudo apt-get install -y ffmpeg
バージョンと機能を確認してください。使用するビルドには、libx264 と
AAC のエンコーダー、HLS と DASH のマルチプレクサーとデマルチプレクサー、およびサンプル生成で使用する testsrc2、geq、aevalsrc フィルターが必要です。
cargo --version && rustc --version &&
ffmpeg -version && ffprobe -version && ffplay -version &&
ffmpeg -encoders && ffmpeg -muxers && ffmpeg -demuxers && ffmpeg -filters
既存の Cargo プロジェクト内や、祖先ディレクトリの .cargo 設定が適用される場所を避けてプロジェクトを作成してください。Cargo は親ディレクトリから設定を検出するため、プロジェクト作成時に新しいパッケージが上位のワークスペースに登録されることがあります。以下を貼り付けて実行すると、ファイルを作成する前にその境界を確認し、シェルの作業ディレクトリとオプションは変更しません。
(
set -eu
for tool in cargo rustc ffmpeg ffprobe ffplay; do
command -v "$tool" >/dev/null
done
directory=$(pwd -P)
while :; do
for config in "$directory/Cargo.toml" "$directory/.cargo/config" "$directory/.cargo/config.toml"; do
if [ -e "$config" ] || [ -L "$config" ]; then
printf 'Choose a directory outside this Cargo configuration: %s\n' "$config" >&2
exit 1
fi
done
[ "$directory" = / ] && break
directory=$(dirname "$directory")
done
cargo new --vcs none --edition 2021 video_converter
)
video_converter がすでに存在する場合は、既存のプロジェクトを削除せず、新しいディレクトリを選んでください。以降のシェルブロックはすべて、video_converter がある親ディレクトリから実行します。生成された video_converter/Cargo.toml を、以下の完全なマニフェストに置き換えてください。直接依存するパッケージのバージョンは検証済みの API に固定しています。ビルドを再現できるよう、生成された Cargo.lock を保持してください。
[package]
name = "video_converter"
version = "0.1.0"
edition = "2021"
[workspace]
[dependencies]
anyhow = "=1.0.104"
tokio = { version = "=1.53.2", features = ["macros", "rt-multi-thread"] }
warp = { version = "=0.3.7", default-features = false }
内容が既知の入力の作成
音程が上がる音声を含む、長さ 9.375 秒、解像度 1920 × 1080、フレームレート 24 fps の動画を生成します。動くテストパターンの上部には、白黒のブロックが八つ並び、ゼロから始まるフレーム番号を表します。これにより、内容の繰り返しや順序の入れ替わりを識別しやすくなります。サブシェルは FFmpeg の実行前に、入力がすでに存在する場合は処理を拒否します。
(
set -eu
cd video_converter
if [ -e input.mp4 ] || [ -L input.mp4 ]; then
printf 'input.mp4 already exists; use a fresh project for this sample.\n' >&2
exit 1
fi
ffmpeg -hide_banner -loglevel error -nostdin -n \
-f lavfi -i 'testsrc2=size=1920x1080:rate=24:duration=9.375' \
-f lavfi -i 'aevalsrc=0.1*sin(2*PI*(440*t+40*t*t)):s=48000:d=9.375' \
-filter_threads 1 \
-vf "geq=lum='if(lt(Y,120),16+219*mod(floor(N/pow(2,floor(X/240))),2),lum(X,Y))':cb='cb(X,Y)':cr='cr(X,Y)'" \
-c:v libx264 -threads:v 2 -preset fast -crf 18 -pix_fmt yuv420p \
-c:a aac -b:a 128k -shortest input.mp4
)
再生の検証には、この 9.375 秒のサンプルを使用しています。独自のソースを使用する場合は、回転していない正方形ピクセルの 16:9 映像(1920 × 1080 以上)と音声トラックを含む、有効なローカル MP4 を用意してください。この固定のラダーはその入力を対象としており、任意の映像に適したサイズやビットレートを選択するものではありません。使用するのは最初の映像ストリームと最初の音声ストリームのみです。コンバーターは映像を 24 fps と yuv420p に正規化します。長さが異なるクリップや別のプレーヤーは、個別に確認してください。
Rust と FFmpeg の連携
Rust の Command は、シェルを介さず FFmpeg に引数を直接渡します。以下の実行処理は入力のパスを正規化し、出力先が新規ディレクトリであることを要求して、各子プロセスの終了を待ちます。両方の変換がエラーレベルの診断を出さず正常終了した場合にのみ、成功を報告します。
HLS・MPEG-DASH への動画変換の実装
video_converter/src/main.rs を、以下の完全なプログラムに置き換えてください。
use anyhow::{ensure, Context, Result};
use std::io::{self, Write};
use std::path::Path;
use std::process::Command;
const COMMON_ARGS: &[&str] = &[
"-hide_banner", "-loglevel", "error", "-nostdin", "-n", "-xerror",
"-threads", "2",
];
const ENCODING_ARGS: &[&str] = &[
"-c:v", "libx264", "-threads:v", "2", "-filter_threads", "1",
"-preset", "medium", "-profile:v", "main", "-pix_fmt", "yuv420p",
"-r", "24", "-g", "96", "-sc_threshold", "0", "-flags", "+cgop",
"-force_key_frames", "expr:gte(t,n_forced*4)",
"-c:a", "aac", "-b:a", "128k", "-ar", "48000",
];
const HLS_ARGS: &[&str] = &[
"-map", "0:v:0", "-map", "0:a:0",
"-crf", "23", "-f", "hls", "-hls_time", "4",
"-hls_playlist_type", "vod", "-hls_segment_filename", "segment_%03d.ts",
"index.m3u8",
];
const DASH_ARGS: &[&str] = &[
"-map", "0:v:0", "-map", "0:v:0", "-map", "0:a:0",
"-filter:v:0", "scale=1920:1080", "-filter:v:1", "scale=1280:720",
"-b:v:0", "2M", "-b:v:1", "1M",
"-f", "dash", "-seg_duration", "4", "-use_template", "1", "-use_timeline", "1",
"-format_options", "use_editlist=0",
"-init_seg_name", "init-$RepresentationID$.m4s",
"-media_seg_name", "chunk-$RepresentationID$-$Number%05d$.m4s",
"-adaptation_sets", "id=0,streams=v id=1,streams=a", "manifest.mpd",
];
fn convert(input: &Path, output: &Path, format_args: &[&str]) -> Result<()> {
std::fs::create_dir(output).context("Use a new output directory")?;
let result = Command::new("ffmpeg")
.args(COMMON_ARGS)
.arg("-i").arg(input)
.args(ENCODING_ARGS)
.args(format_args)
.current_dir(output)
.output()
.with_context(|| format!("Could not launch FFmpeg for {}", input.display()))?;
io::stderr().write_all(&result.stderr)?;
ensure!(result.status.success() && result.stderr.is_empty(),
"FFmpeg failed for {} ({})", input.display(), result.status);
Ok(())
}
fn main() -> Result<()> {
let args: Vec<_> = std::env::args_os().skip(1).collect();
ensure!(args.len() == 2,
"Usage: cargo run --bin video_converter -- INPUT.mp4 NEW_OUTPUT_DIR");
let input = std::fs::canonicalize(&args[0]).context("Cannot open input")?;
let output = Path::new(&args[1]);
std::fs::create_dir(output).context("Use a new output directory")?;
convert(&input, &output.join("hls"), HLS_ARGS)?;
convert(&input, &output.join("dash"), DASH_ARGS)?;
println!("Conversion complete.");
Ok(())
}
HLS への変換
HLS では hls/index.m3u8 と MPEG-TS セグメントを生成します。このメディアプレイリストを直接開いてください。単一レンディションの例なので、マスタープレイリストは不要です。CRF 23 は一定品質のレート制御を選択するため、ビットレートは映像によって変動します。2 Mbit/s の目標値やピークレートの上限ではありません。
HLS マルチプレクサーは、目標セグメント時間を過ぎたキーフレームで分割します。24 fps では、96 フレームのクローズド GOP と強制キーフレームによって、四秒ごとの境界を揃えます。サンプルの長さ 9.375 秒は四秒の倍数ではないため、最後のセグメントは短くなります。
MPEG-DASH への変換
映像を二重にマッピングすることで、単一の映像適応セット内に、異なる 1080p と 720p の表現を作成します。音声には専用のセットを用意します。DASH マルチプレクサーは、初期化フラグメント、メディアフラグメント、およびそれらのタイムラインを
dash/manifest.mpd に書き込みます。MP4 コンテナオプションの
use_editlist=0 は編集リストを無効にします。検証した FFmpeg の DASH リーダーでは、これにより各フラグメントの境界で
AAC の先頭トリミングが再適用され、セグメント間のサンプルが失われるのを防ぎます。
DASH のエンコーダーでは、例として 2 Mbit/s と 1 Mbit/s の平均ビットレート目標を使用します。CRF を併用すると libx264 で別のレート制御モードが選択されるため、併用しません。これらの値は厳密な帯域幅の上限でも、あらゆる動画に対する画質の推奨値でもありません。両方の映像表現で同じキーフレームのスケジュールを使用します。
Rust による簡易ストリーミングサーバーの構築
別のサーバー実行ファイル用にディレクトリを作成してください。
mkdir video_converter/src/bin
以下の完全なプログラムを video_converter/src/bin/server.rs として保存してください。指定した出力ディレクトリをループバックで配信し、ストリーミングファイルにコンテンツタイプを割り当てます。準備完了メッセージはバインドに成功した後に表示されます。ポートが使用中の場合は、代わりにエラーを返します。
use anyhow::{ensure, Result};
use warp::{Filter, Reply};
#[tokio::main(worker_threads = 2)]
async fn main() -> Result<()> {
let args: Vec<_> = std::env::args().skip(1).collect();
ensure!(args.len() == 2, "Usage: cargo run --bin server -- OUTPUT_DIR PORT");
let directory = std::fs::canonicalize(&args[0])?;
let port: u16 = args[1].parse()?;
let routes = warp::fs::dir(directory).map(|file: warp::fs::File| {
let content_type = match file.path().extension().and_then(|ext| ext.to_str()) {
Some("m3u8") => "application/vnd.apple.mpegurl",
Some("mpd") => "application/dash+xml",
Some("ts") => "video/mp2t",
Some("m4s") => "video/mp4",
_ => return file.into_response(),
};
let mut response = file.into_response();
response.headers_mut().insert(
warp::http::header::CONTENT_TYPE,
warp::http::HeaderValue::from_static(content_type),
);
response
});
let (address, server) = warp::serve(routes)
.try_bind_ephemeral(([127, 0, 0, 1], port))?;
println!("Serving http://{address}/");
server.await;
Ok(())
}
DASH の音声フラグメントと映像フラグメントは、どちらも MP4 コンテナです。それぞれにどのトラックが含まれるかは MPD に記述されています。サーバーとプレーヤーは同じローカルオリジンを使用するため、この例では制限を緩める CORS 設定は不要です。アップロード用エンドポイントや認証機能はありません。
ストリーミング構成のテスト
親ディレクトリからコンバーターをビルドして実行し、変換が成功した場合にのみサーバーを起動します。
(
cd video_converter &&
cargo run --bin video_converter -- ./input.mp4 ./output &&
cargo run --bin server -- ./output 3030
)
コンバーターは Conversion complete. と表示します。続いてサーバーが自身の URL を表示します。ポート 3030 が使用中の場合は、サーバーコマンドで別のポートを指定し、以下の URL でもそのポートを使用してください。配信中は、同じディレクトリを対象に別のコンバーターを実行しないでください。
別のターミナルで、インストール済みの ffplay プレーヤーを使って両方のマニフェストを再生します。最初のプレーヤーは再生終了時に終了し、その後で二つ目が起動します。
ffplay -autoexit -threads 2 http://127.0.0.1:3030/hls/index.m3u8 &&
ffplay -autoexit -threads 2 http://127.0.0.1:3030/dash/manifest.mpd
どちらの再生でも、同じ動くパターンと変化するブロックが約 9.375 秒間表示され、音程が徐々に上がるはずです。生成した入力には 225 の映像フレームが含まれます。DASH は 1920 × 1080 と 1280 × 720 の両方の映像表現を提示しますが、ffplay は映像ストリームを一つ選択するため、この再生では表現間の切り替えは実証しません。プレーヤーを終了するには q を使用してください。フォアグラウンドのサーバーは、そのターミナルで Ctrl+C を押して停止します。出力ファイルはディスクに残ります。
プレイリストが読み込めても、セグメントが欠けていると再生が停止することがあります。output ツリー全体をまとめて保持し、両方のストリームの実際の映像と音声を最後まで確認してください。マニフェストを読み込めただけでは、正しい内容を参照しているとは確認できません。
変換失敗時の対処
出力ディレクトリがすでに存在する場合、置き換えずに失敗します。ファイルの欠落、音声トラックの不在、FFmpeg の起動失敗、ネイティブプロセスのゼロ以外の終了、または報告されたデコーダーエラーがあると、完了メッセージは表示されず、連結したサーバーコマンドも実行されません。FFmpeg は、エラーを報告せずに破損したメディアを復旧できる場合があります。変換に成功しても、任意のソースが破損していなかったことの証明にはなりません。
エンコード開始後に失敗すると、不完全なファイルが残ることがあります。DASH が失敗した場合には、変換済みの HLS が残ることもあります。そのディレクトリは配信しないでください。調査用に保持し、./output-retry などの新しい出力名でコンバーターを再実行してください。成功したら、同じ名前を指定してサーバーを起動します。依存関係のダウンロードやコンパイルが失敗した場合は、プロジェクトを保持し、接続の問題やコンパイラーエラーを修正してからビルドコマンドを再実行してください。Cargo コマンドは実行前にビルドするため、ビルド失敗後に古い実行ファイルが使われることはありません。
この構成は、ローカルでの変換と再生のワークフローとして使用してください。複数の FFmpeg 処理を同時に実行する別の Rust タスクについては、Rust による動画へのウォーターマークの並行追加を参照してください。
