Ruby と FFmpeg による動画の HLS・MPEG-DASH 変換
Ruby と FFmpeg を使い、ローカル動画をオンデマンド再生用にパッケージ化します。この例では、HLS の画質別ストリームを三つ、実測したセグメント帯域幅を記載したマスタープレイリスト、二つの動画表現を含む DASH マニフェストを生成します。完成したファイルをループバック HTTP で配信し、両形式をブラウザーで再生します。
HLS と MPEG-DASH の基礎
HLS は .m3u8 プレイリスト、MPEG-DASH は .mpd マニフェストを使います。各インデックスはメディアセグメントを参照します。互換性のある画質別ストリームを複数用意すると、プレーヤーが画質を選択できます。ただし、パッケージ化だけでは、実際のネットワークでスムーズに画質を切り替えられることや、バッファリングが減ることは確認できません。ここで使うビットレートラダーは一例であり、あらゆる動画に推奨するものではありません。
動画変換用の Ruby 環境の準備
Linux 上の Bash を使い、Ruby、RubyGems、FFmpeg、ffprobe、Python を PATH に用意してください。検証環境では Ruby 3.4.10、FFmpeg/ffprobe 9.0.1、Python 3.14.7 を使用しています。メンテナンス中の Ruby リリースを選んでください。Ruby 3.2 はサポートを終了しています。FFmpeg のビルドには、libx264 と aac エンコーダー、および HLS と DASH のマルチプレクサーが必要です。
ruby -v && gem -v && python3 --version &&
ffmpeg -version && ffprobe -version && ffmpeg -encoders && ffmpeg -muxers
書き込み可能なディレクトリで、次のブロックを Bash に貼り付けてください。新しいプロジェクトを作成し、RubyGems の明示的なインストール先ディレクトリ指定オプションで、その中に gem をインストールします。video_conversion ディレクトリがすでに存在する場合、セットアップは停止します。インストールに失敗すると元のディレクトリに戻ります。既存の作業を削除せず、新しいディレクトリの内容を確認してから再試行してください。
(
unset RUBYOPT RUBYLIB BUNDLE_GEMFILE
mkdir video_conversion &&
cd video_conversion &&
export GEM_HOME="$PWD/.gems" GEM_PATH="$PWD/.gems" GEM_SPEC_CACHE="$PWD/.gem-specs" &&
gem install streamio-ffmpeg -v 3.0.2 --norc --no-document --no-user-install --install-dir "$GEM_HOME" &&
gem install logger -v 1.7.0 --norc --no-document --no-user-install --install-dir "$GEM_HOME"
) && cd video_conversion
この独立したセットアップでは、サブシェル内で継承した Ruby ローダー設定をクリアするため、上位の Bundler プロジェクトによって gem が選択されることはありません。後述の実行コマンドも同じ方法で分離します。正常であることが確認済みのローカルファイルを、プロジェクト内に input.mp4 としてコピーしてください。正方形ピクセル、1280×720 以上の 16:9 映像、音声トラックを備えた SDR H.264 動画を使います。この固定ラダーでは、ほかのアスペクト比の映像は引き伸ばされます。複数のセグメント境界を試せるよう、20 秒より長いクリップを選んでください。音声のない動画には、別のマッピングとプレイリスト処理が必要です。
Ruby による動画の HLS 形式への変換
Streamio FFMPEG gemは、入力の調査とエンコーダーオプションを提供します。公開されている最新バージョンは 2016 年リリースの 3.0.2で、開発元の互換性に関する記載は、はるかに古い FFmpeg を対象としています。この例では、上記のバージョンで限定的な使用範囲を検証し、引数配列を渡して FFmpeg を直接呼び出し、終了ステータスを確認します。変換ごとに新しい出力ディレクトリを作成します。以前のプレイリストとセグメントを保護するため、既存のディレクトリは受け付けません。
video_converter.rb という名前で新しいファイルを作成してください。
require 'streamio-ffmpeg'
require 'fileutils'
class VideoConverter
def initialize(input_file)
begin
@movie = FFMPEG::Movie.new(input_file)
raise "Invalid file" unless @movie.valid?
@input_file = input_file
rescue FFMPEG::Error => e
raise "FFmpeg error: #{e.message}"
rescue StandardError => e
raise "Error initializing converter: #{e.message}"
end
end
def to_hls(output_dir)
FileUtils.mkdir_p(File.dirname(output_dir))
Dir.mkdir(output_dir)
variants = [
{ resolution: '1280x720', video_bitrate: '2500k', audio_bitrate: '128k' },
{ resolution: '854x480', video_bitrate: '1500k', audio_bitrate: '96k' },
{ resolution: '640x360', video_bitrate: '800k', audio_bitrate: '64k' }
]
begin
variants.each do |variant|
options = {
video_codec: 'libx264',
audio_codec: 'aac',
frame_rate: 30,
resolution: variant[:resolution],
video_bitrate: variant[:video_bitrate],
audio_bitrate: variant[:audio_bitrate],
custom: [
'-map', '0:v:0', '-map', '0:a:0',
'-pix_fmt', 'yuv420p', '-threads', '2',
'-g', '300', '-keyint_min', '300', '-sc_threshold', '0',
'-force_key_frames', 'expr:gte(t,n_forced*10)',
'-hls_time', '10',
'-hls_playlist_type', 'vod',
'-hls_segment_filename', "#{output_dir}/#{variant[:resolution]}_%03d.ts"
]
}
transcode("#{output_dir}/#{variant[:resolution]}.m3u8", options)
end
generate_master_playlist(output_dir, variants)
rescue FFMPEG::Error => e
raise "Transcoding error: #{e.message}"
rescue StandardError => e
raise "General error: #{e.message}"
end
end
def to_dash(output_dir)
FileUtils.mkdir_p(File.dirname(output_dir))
Dir.mkdir(output_dir)
begin
options = {
video_codec: 'libx264',
audio_codec: 'aac',
frame_rate: 30,
custom: [
'-map', '0:v:0', '-map', '0:v:0', '-map', '0:a:0',
'-pix_fmt', 'yuv420p', '-threads', '2',
'-s:v:0', '1280x720', '-b:v:0', '2500k',
'-s:v:1', '640x360', '-b:v:1', '800k',
'-g', '300', '-keyint_min', '300', '-sc_threshold', '0',
'-force_key_frames', 'expr:gte(t,n_forced*10)',
'-use_template', '1',
'-use_timeline', '1',
'-seg_duration', '10',
'-adaptation_sets', 'id=0,streams=v id=1,streams=a',
'-f', 'dash'
]
}
transcode("#{output_dir}/manifest.mpd", options)
rescue FFMPEG::Error => e
raise "DASH conversion error: #{e.message}"
rescue StandardError => e
raise "General error: #{e.message}"
end
end
private
def transcode(output_file, options)
arguments = FFMPEG::EncodingOptions.new(options).to_a
system(FFMPEG.ffmpeg_binary, '-nostdin', '-n', '-i', @input_file,
*arguments, output_file, exception: true)
end
def generate_master_playlist(output_dir, variants)
master_playlist = "#EXTM3U\n#EXT-X-VERSION:3\n"
variants.each do |variant|
# Measure the multiplexed segments, including audio and container overhead.
duration = nil
target_duration = nil
segments = []
File.foreach("#{output_dir}/#{variant[:resolution]}.m3u8") do |line|
if line.start_with?('#EXT-X-TARGETDURATION:')
target_duration = Integer(line.split(':', 2).last)
elsif line.start_with?('#EXTINF:')
duration = Float(line.delete_prefix('#EXTINF:').split(',').first)
elsif !line.start_with?('#') && !line.strip.empty?
raise 'Missing segment duration' unless duration && duration.positive?
segments << { bytes: File.size(File.join(output_dir, line.strip)), duration: duration }
duration = nil
end
end
raise 'Missing HLS target duration' unless target_duration && target_duration.positive?
rates = []
segments.each_index do |first|
bytes = 0
seconds = 0.0
(first...segments.length).each do |last|
bytes += segments[last][:bytes]
seconds += segments[last][:duration]
break if seconds > 1.5 * target_duration
rates << bytes * 8 / seconds if seconds >= 0.5 * target_duration
end
end
raise 'No measurable HLS segment window' if rates.empty?
bandwidth = rates.max.ceil
master_playlist += <<~PLAYLIST
#EXT-X-STREAM-INF:BANDWIDTH=#{bandwidth},RESOLUTION=#{variant[:resolution]}
#{variant[:resolution]}.m3u8
PLAYLIST
end
File.write("#{output_dir}/master.m3u8", master_playlist)
end
end
三つすべてのメディアプレイリストが完成すると、Ruby が master.m3u8 を書き込みます。各画質別ストリームについて、プレイリストのターゲット期間の 0.5 倍から 1.5 倍に収まる、連続したセグメントの区間を測定します。その最大レートを切り上げ、BANDWIDTH に使います。これは HLS のピークセグメントビットレートの定義に従っています。この値には音声と MPEG-TS のオーバーヘッドも含まれます。最後の短いセグメントが単独では条件を満たさない場合は、隣接するセグメントと合わせて測定します。動画エンコーダーのビットレートを使うと、配信データの一部が計算から漏れてしまいます。
Ruby による動画の MPEG-DASH への変換
上記の to_dash メソッドは入力動画を二重にマッピングし、720p と 360p の動画表現と、共有する音声表現を一つ作成します。両方の動画エンコードで同じフレームレートを使い、十秒ごとにキーフレームを強制挿入するため、セグメント境界が揃います。HLS の三つの画質別ストリームにも、同じキーフレーム間隔を使います。最後のセグメントは十秒未満になる場合があります。パッケージ化のオプションについては、FFmpeg の HLS と
DASH のマルチプレクサードキュメントで説明されています。
コンバーターの使い方
二つ目のファイルを convert.rb として、video_converter.rb と input.mp4 と同じディレクトリに保存してください。
require_relative 'video_converter'
begin
converter = VideoConverter.new('input.mp4')
puts 'Converting to HLS…'
converter.to_hls('output/hls')
puts 'Converting to MPEG-DASH…'
converter.to_dash('output/dash')
puts 'Conversion completed successfully'
rescue StandardError => e
warn "Error: #{e.message}"
exit 1
end
video_conversion から実行してください。
env -u RUBYOPT -u RUBYLIB -u BUNDLE_GEMFILE \
GEM_HOME="$PWD/.gems" GEM_PATH="$PWD/.gems" ruby convert.rb
Conversion completed successfully と表示されるまで待ってください。生成されるのは、output/hls/master.m3u8、その三つのメディアプレイリストと .ts セグメント、および output/dash/manifest.mpd、初期化ファイル、.m4s セグメントです。各インデックスは、参照先のファイルと一緒に保管してください。スクリプトを再実行すると、既存の output/hls ディレクトリは拒否されます。
ストリームのテスト
このページを output/player.html として保存してください。各プレーヤーのソースは一つだけなので、HLS のテストが知らないうちに DASH のテストの代わりになることはありません。Video.js HTTP Streaming は標準の Video.js ビルドに含まれ、Media Source Extensions を通じて両形式に対応しています。ライブラリとスタイルシートは CDN から読み込むため、このページにはインターネット接続が必要です。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Local HLS and DASH playback</title>
<link href="https://cdn.jsdelivr.net/npm/video.js@8.24.0/dist/video-js.min.css" rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/video.js@8.24.0/dist/video.min.js"></script>
<style>html { color-scheme: light dark; }</style>
</head>
<body>
<section aria-label="HLS">
<h1>HLS</h1>
<video id="hls" class="video-js" controls preload="metadata" width="640" height="360">
<source src="hls/master.m3u8" type="application/x-mpegURL" />
</video>
</section>
<section aria-label="MPEG-DASH">
<h2>MPEG-DASH</h2>
<video id="dash" class="video-js" controls preload="metadata" width="640" height="360">
<source src="dash/manifest.mpd" type="application/dash+xml" />
</video>
</section>
<script>
videojs('hls', { fluid: true })
videojs('dash', { fluid: true })
</script>
</body>
</html>
video_conversion から、Python のローカル HTTP サーバーをフォアグラウンドで起動してください。
python3 -m http.server 8080 --bind 127.0.0.1 --directory output
H.264/AAC と Media Source Extensions に対応したブラウザーで http://127.0.0.1:8080/player.html を開いてください。各動画を最後まで再生した後、セグメント境界をまたいでシークしてください。このページは Linux 上の Video.js 8.24.0 と Chromium 145 で確認しています。サーバーを停止するには Ctrl+C を押します。ポート 8080 が使用中の場合は、コマンドで別のポートを指定し、URL にも同じポートを使ってください。ここでは Python の HTTP サーバーが配信するのは
output ディレクトリだけです。このローカル検証では、公開用のテストメディアだけを使ってください。
失敗と完成したメディアの確認
入力を開けない、または認識できない場合、音声トラックがない場合、FFmpeg プロセスが失敗した場合、convert.rb はゼロ以外のステータスで終了します。FFmpeg の診断メッセージには、該当する入力または出力が示されます。実行に失敗すると、新しいディレクトリに不完全なファイルが残る場合があります。また、HLS の成功後に DASH が失敗した場合は、完成した HLS ファイルが残ります。スクリプト全体が成功してから公開してください。再試行するには、convert.rb で未使用の出力ディレクトリ名を指定し、プレーヤーのソースパスもそれに合わせて更新してください。
FFmpeg は破損した入力から復旧し、ゼロを返すことがあります。変換の成功は完全性の確認にはなりません。完成した映像、音声、再生時間を元の動画と比較してください。プレーヤーが選んだ画質だけでなく、HLS の三つすべての画質別ストリームと、DASH の両方の動画表現を調べてください。プレイリストやマニフェストのすべての参照先にアクセスでき、想定した終端まで再生されることを確認してください。マニフェストのファイル名や最初のフレームの再生成功だけでは、最後まで再生できるとは確認できません。
ローカル環境の例からの発展
HLS メソッドは入力を順番に三回エンコードし、DASH は一つの FFmpeg プロセスで両方の動画表現を作成します。まず変換タスクを一つ実行し、CPU、メモリ、ディスクの使用量を測定してからワーカーを追加してください。これらのサブプロセス呼び出しでは終了ステータスを確認しますが、タイムアウトや、信頼できないアップロードを隔離する境界は提供しません。本番の配信サービスには、独自の公開処理と HTTP 環境も必要です。このチュートリアルで検証するのは、パッケージ化とローカル再生です。
まとめ
公開環境に結果を移すときは、完成したマニフェストとセグメントを一緒に保管してください。マネージドエンコーディングについては、Transloadit の動画エンコーディングサービスをご覧ください。
