Ruby と FFmpeg による動画ハイライトの自動生成
長い映像から有用な場面を探すには時間がかかります。Ruby でシーン変化の検出を自動化し、FFmpeg で候補クリップを抽出してレビュー用リールにまとめられます。これは視覚的な変化に基づくヒューリスティックであり、場面の重要性を理解するシステムではありません。
動画ハイライト自動生成の概要
このワークフローでは、隣接するフレーム間の大きな変化を検出し、十分な間隔を空けてタイムスタンプを選択して、その前後の短いクリップをエンコードします。カット、フラッシュ、スライドの切り替えは有用な候補になる場合がありますが、ゴールや重要な発言にはシーンの切り替えがない場合もあります。生成したリールは公開前に確認してください。
Ruby と FFmpeg のセットアップ
Linux の Bash を使用し、Ruby、FFmpeg、および付属の ffprobe を
PATH に配置してください。この手順は Ruby 3.4.10 と
FFmpeg/ffprobe 9.0.1 でテストしました。これらはテスト済みのバージョンであり、インストール時に完全に一致させる必要はありません。Ruby インストールガイドから Ruby 3.4 の最新パッチを使用し、メンテナンス状況を確認してください。Ubuntu/Debian では、FFmpeg と ffprobe を一緒にインストールします。
sudo apt-get update && sudo apt-get install -y --no-install-recommends ffmpeg
この例では、サードパーティー製の FFmpeg ラッパーを使わず、Ruby の標準ライブラリを使用します。スクリプトを保存する前に、Ruby が必要なライブラリを読み込めることを確認し、FFmpeg ビルドのフィルターとエンコーダーを調べてください。
env -u RUBYOPT -u RUBYLIB -u BUNDLE_GEMFILE ruby -v &&
env -u RUBYOPT -u RUBYLIB -u BUNDLE_GEMFILE ruby -e "require 'fileutils'; require 'json'; require 'open3'" &&
ffmpeg -version && ffprobe -version && ffmpeg -filters && ffmpeg -encoders
バージョン互換性
FFmpeg ビルドには、select、metadata、atrim、asetpts、concat フィルターと、libx264、aac エンコーダーが必要です。同じ処理設定は FFmpeg 6.1.1 でも動作します。使用するディストリビューション向けのパッチ適用済みパッケージを使用してください。実行時には、継承した Ruby ローダーと
Bundler の設定をクリアするため、親ディレクトリの Ruby プロジェクト内から実行しても、そのプロジェクトの gem は選択されません。
フレームサイズが固定で SDR カラーの、正常と確認済みのローカル動画を選んでください。スクリプトは最初の動画トラックを選択し、音声がある場合は最初の音声トラックも選択します。音声は、選択する動画区間全体をカバーしている必要があります。信頼できないアップロード、破損した録画、途中で解像度が変わるファイルには、別途検証と隔離されたワーカーが必要です。この CLI はその隔離境界を提供しません。FFmpeg は破損したパケットから復旧して警告を出力し、それでも成功を返す場合があります。バッチの完了は入力の完全性を検証するものではありません。診断情報と生成したカットを確認してください。
FFmpeg フィルターによる重要場面の抽出
FFmpeg のシーンスコアは、フレーム間の視覚的な差を推定します。新しい作業ディレクトリで手動検証する場合は、次のコマンドで選択したフレームのタイムスタンプを timestamps.txt に書き出します。
ffmpeg -nostdin -n -threads 2 -filter_threads 1 -i input.mp4 -map 0:v:0 \
-vf "select='gt(scene,0.3)',metadata=print:file=timestamps.txt" \
-an -f null -
シーン検出とクリップ抽出には、どちらも FFmpeg の入力基準のタイムラインを使用してください。音声が最初の動画フレームより前に始まる場合があるため、動画ストリームのタイムスタンプだけをリセットしないでください。検出と抽出では、どちらも最初の動画トラックを明示的に選択します。フィルターのテキストファイルは FFmpeg の通常の出力ファイル確認とは別に扱われるため、既存の timestamps.txt を再利用しないでください。Ruby の実装では、このファイル用に非公開のジョブディレクトリを作成します。
自動化用 Ruby スクリプトの実装
このクラスを highlight_extractor.rb として保存してください。生成ファイル名を固定し、入力パスを個別のプロセス引数として渡すため、パスがシェルやフィルターの構文に入り込むことはありません。いずれかの段階で失敗すると、成功したバッチとして黙って報告するのではなく、エラーを発生させます。
require 'fileutils'
require 'json'
require 'open3'
class HighlightExtractor
def initialize(input_file, output_dir)
@input = File.expand_path(input_file)
raise ArgumentError, 'Input must be a regular file' unless File.file?(@input)
@output = File.expand_path(output_dir)
end
def generate(threshold: 0.3, clip_duration: 5.0, pre_roll: 2.0, min_gap: 10.0)
unless threshold.finite? && (0.0..1.0).cover?(threshold) &&
clip_duration.finite? && clip_duration > 0 &&
pre_roll.finite? && pre_roll >= 0 && min_gap.finite? && min_gap >= clip_duration
raise ArgumentError, 'Invalid scene or clip settings'
end
# Refuse earlier job outputs before taking ownership of this directory.
Dir.mkdir(@output, 0700)
begin
duration = video_duration
selected = detect_scene_changes(threshold).each_with_object([]) do |time, result|
next if time >= duration
result << time if result.empty? || time - result.last >= min_gap
end
# Cap output count so a noisy video cannot create an unlimited clip set.
lengths = []
clips = selected.first(20).each_with_index.map do |time, index|
start = [time - pre_roll, 0.0].max
length = [clip_duration, duration - start].min
lengths << length
name = format('highlight_%03d.mp4', index + 1)
execute('-i', @input, '-ss', start.to_s, '-t', length.to_s,
'-map', '0:v:0', '-map', '0:a:0?', '-c:v', 'libx264', '-preset', 'fast',
'-crf', '23', '-pix_fmt', 'yuv420p', '-c:a', 'aac', '-threads', '2', name)
name
end
create_highlight_compilation(clips, lengths) unless clips.empty?
clips.length
rescue StandardError
FileUtils.remove_entry(@output)
raise
end
end
private
def video_duration
output, status = Open3.capture2('ffprobe', '-v', 'error', '-show_entries',
'format=duration:stream=codec_type', '-of', 'json', @input)
raise IOError, 'Cannot inspect input video' unless status.success?
info = JSON.parse(output)
@has_audio = info.fetch('streams').any? { |stream| stream.fetch('codec_type') == 'audio' }
duration = Float(info.fetch('format').fetch('duration'))
raise ArgumentError, 'Invalid video duration' unless duration.finite? && duration > 0
duration
end
def execute(*arguments)
unless system('ffmpeg', '-nostdin', '-n', '-threads', '2', '-filter_threads', '1',
'-filter_complex_threads', '1',
*arguments, chdir: @output)
raise IOError, 'FFmpeg processing failed'
end
end
def detect_scene_changes(threshold)
execute('-i', @input, '-map', '0:v:0', '-vf',
"select='gt(scene,#{threshold})',metadata=print:file=timestamps.txt",
'-an', '-f', 'null', '-')
File.foreach(File.join(@output, 'timestamps.txt')).each_with_object([]) do |line, times|
match = line.match(/pts_time:([0-9.eE+-]+)/)
times << Float(match[1]) if match
end.uniq.sort
end
def create_highlight_compilation(clips, lengths)
list = clips.each_with_index.map do |name, index|
"file '#{name}'\nduration #{lengths[index]}\n"
end.join
File.write(File.join(@output, 'filelist.txt'), list)
arguments = ['-copyts', '-f', 'concat', '-safe', '1', '-i', 'filelist.txt']
if @has_audio
clips.each { |name| arguments.concat(['-i', name]) }
filters = clips.each_index.map do |index|
"[#{index + 1}:a:0]atrim=duration=#{lengths[index]},asetpts=PTS-STARTPTS[a#{index}]"
end
inputs = clips.each_index.map { |index| "[a#{index}]" }.join
filters << "#{inputs}concat=n=#{clips.length}:v=0:a=1[audio]"
arguments.concat(['-filter_complex', filters.join(';'), '-map', '0:v:0', '-map',
'[audio]', '-c:v', 'copy', '-c:a', 'aac'])
else
arguments.concat(['-map', '0:v:0', '-c:v', 'copy'])
end
execute(*arguments, 'highlight_reel.mp4')
end
end
concat デマルチプレクサーには、ストリームとタイムベースの一致が必要です。これらのクリップは入力とエンコーダー設定を共有します。リストには生成したベース名だけを含めるため、安全なパスモードを有効にしたままにします。明示的な長さの指定で、各動画クリップをリールのタイムライン上に配置します。リールにはエンコード済みの動画をコピーします。音声がある場合は、各クリップを個別にデコードして音声を指定したクリップ長にトリミングし、concat フィルターで結合してから AAC に再エンコードします。これにより、クリップのエンコーダーパディングが音声の遅延として蓄積するのを防ぎます。このレビュー用リールは、ギャップレス音声マスターでも、無関係なファイルを結合するツールでもありません。公開前に結合箇所の音声を確認してください。
libx264 エンコーダーは、ビットレートの上限を設けず、CRF 23 を品質の目標値として使用します。一般に、値を小さくすると細部がより多く保持され、ファイルサイズが大きくなります。fast プリセットはエンコードの処理量を制御するもので、シーンの選択には影響しません。
出力側の -ss オプションは、各クリップの開始時刻より前の映像をデコードして破棄します。この単純なデコード方式は利用可能なシークインデックスに依存しませんが、後半のハイライトでは処理を繰り返すことになります。インデックス付きの長い録画では、入力側の正確なシークをベンチマークし、クリップ境界と音声・動画のオフセットを確認してからこの動作を変更してください。
次の呼び出し側スクリプトを、クラスと同じ場所に generate_highlights.rb として保存してください。
require_relative 'highlight_extractor'
abort 'Usage: ruby generate_highlights.rb <input-video> <new-output-directory>' unless ARGV.length == 2
begin
count = HighlightExtractor.new(*ARGV).generate
puts(count.zero? ? 'No scene changes selected' : "Created #{count} candidate highlights")
rescue StandardError
warn 'Highlight generation failed. Check the input, destination, and FFmpeg installation.'
exit 1
end
ターミナルから実行します。
env -u RUBYOPT -u RUBYLIB -u BUNDLE_GEMFILE \
ruby generate_highlights.rb my_video.mp4 my_highlights_folder
両方のスクリプトを同じ場所に置き、my_video.mp4 を入力パスに置き換えてください。空白を含むパスは引用符で囲んでください。正常に実行されると候補数を報告し、highlight_001.mp4、続く連番のクリップ、highlight_reel.mp4 を
my_highlights_folder 内に書き出します。動画プレーヤーでリールを開いてください。デフォルトでは、各クリップは選択したカットの 2 秒前から始まり、最大 5 秒間続きます。ただし、開始位置は入力の先頭より前にはなりません。カットは時系列順に少なくとも 10 秒間隔で選択し、クリップ数は最大 20 です。
既存の出力ディレクトリは拒否され、変更されません。再試行時には新しい名前を選んでください。ジョブディレクトリの作成後に処理エラーが発生すると、そのジョブの不完全な出力を削除します。入力またはインストール環境を修正してから、同じコマンドを再実行してください。有効な動画でシーン変化が選択されなかった場合は、No scene changes selected と出力し、タイムスタンプファイルを残して、クリップやリールを生成せずに正常終了します。ローカルの FFmpeg 診断情報にはファイル名が含まれる場合があります。機密性の高いパスを共有ログに含めないでください。
パフォーマンスの最適化
まず代表的な短い録画で実行し、生成したカットを確認してください。クリップ数の上限は 20 ですが、入力の長さ、シーン解析の全体走査、出力サイズを制限するものではありません。個々のクリップとリールの両方に十分なディスク空き容量を確保してください。ここではデコーダーとエンコーダーのスレッド数を制限していますが、複数のジョブを実行すると CPU とストレージの使用量はその分増加します。
ハイライト選択の最適化
シーンのしきい値を下げるとノイズを含めてより多くの変化を選択し、上げると微妙な切り替えを見逃す場合があります。min_gap 設定は、選択するタイムスタンプ間に最低限空ける秒数で、少なくとも clip_duration にする必要があります。選択は時系列順であり、盛り上がる場面の順位付けではありません。内容を確認してから、プリロールと長さを調整してください。
実例とユースケース
シーン変化の候補は、編集済みインタビュー、スライドの切り替え、モンタージュ映像の確認に役立ちます。シーン検出がゴール、勝利、特定の話者、発言の結論を認識すると考えないでください。これらのタスクには追加のシグナルと別途の検証が必要です。生成したリールは、編集上のレビューの出発点です。
まとめと今後の拡張
必要な場面がリールに含まれない場合、シーンのしきい値を下げても視覚的なノイズが増えるだけかもしれません。同じショット内の発言や動作を基準に選択する場合は、音声解析や検証済みのイベント検出器を追加してください。
マネージド処理には、Transloadit の動画エンコーディングサービスを利用できます。エンコーディングやメディアワークフロー向けに、FFmpeg ベースの Robotを提供しています。
