オープンソースツールで Ruby から動画に字幕を追加
Ruby と FFmpeg を使い、既存の SRT ファイルを動画のフレームに焼き込みます。メタデータには streamio-ffmpeg、字幕キューの時刻には
srt gem を使います。以下のスクリプトは、字幕付き MP4、2.5 秒遅らせた SRT、別ファイルの WebVTT を生成します。用意した字幕を処理するもので、音声の文字起こしは行いません。
字幕が重要な理由
焼き込み字幕は、字幕トラックを読み込めないプレーヤーでも表示されます。映像の一部になるため、視聴者は字幕を非表示にしたり、別の言語を選んだりできません。プレーヤーで選択できる字幕トラックも必要な場合は、元の動画と字幕ファイルを保存してください。
字幕用のオープンソース Ruby ツール
二つの gem は、それぞれ異なる役割を担います。
- streamio-ffmpeg は、FFprobe で動画のメタデータを読み取ります。ヘルパーはこれを使い、エンコード前に動画ストリームの有無を確認します。
- srt は、SRT のキューを解析し、タイムスタンプをずらして SRT を書き出します。以下の WebVTT 変換では、Ruby から FFmpeg を直接呼び出します。
どちらも古いリリース系列です。streamio-ffmpeg 3.0.2 は 2016 年、srt 0.1.5 は 2021 年にリリースされています。出典は、それぞれの RubyGems のバージョンページです。古いライブラリのため、テスト済みの組み合わせが役立ちます。ラッパーの互換性に関する注記は、現在の FFmpeg リリースとの互換性を保証するものではありません。
streamio-ffmpeg による字幕の追加
サンプルは Linux 上で Ruby 3.4.10 と FFmpeg/FFprobe 9.0.1 を使ってテストしています。これらはテスト済みバージョンであり、本質的な最低要件ではありません。同じリリース系列の保守されている新しいパッチも、以下の確認と併せて試す候補になります。Ruby 3.4 と
FFprobe を含む FFmpeg を個別にインストールしてください。libx264、AAC、WebVTT の各エンコーダー、libass の
subtitles フィルター、字幕の文字をカバーする DejaVu Sans などのフォントが必要です。
書き込み可能な新しいディレクトリで Bash を使い、RUBYOPT と BUNDLE_GEMFILE は未設定にしてください。そこで以下のセットアップを実行し、後続のコマンドでも同じシェルを開いたまま使います。インストールしたファイルと gem のメタデータは、このディレクトリ内に保存されます。インストール先を明示することで、RubyGems で設定済みのユーザーインストールも回避します。
export GEM_HOME="$PWD/.gems"
export GEM_PATH="$GEM_HOME"
export GEM_SPEC_CACHE="$PWD/.gem-spec-cache"
(
if [ -n "${RUBYOPT:-}" ] || [ -n "${BUNDLE_GEMFILE:-}" ]; then
printf 'Use a shell without Bundler or RUBYOPT overrides.\n' >&2
exit 1
fi
for tool in ruby gem ffmpeg ffprobe; do
command -v "$tool" >/dev/null || { printf 'Missing prerequisite: %s\n' "$tool" >&2; exit 1; }
done
gem install --norc --install-dir "$GEM_HOME" --no-user-install --no-document --ignore-dependencies \
multi_json:1.15.0 streamio-ffmpeg:3.0.2 srt:0.1.5
)
一覧にはラッパーが依存する multi_json も含めています。そのため、依存関係の自動インストールを無効にし、以下のヘルパー内で選択した各バージョンを有効にします。ダウンロードに失敗した場合は、接続を修復してから同じディレクトリでこのブロックを再実行してください。入力を作成する前に、インストール済みの FFmpeg ビルドを確認します。
ffmpeg -hide_banner -h filter=subtitles &&
ffmpeg -hide_banner -h encoder=libx264 &&
ffmpeg -hide_banner -h encoder=aac &&
ffmpeg -hide_banner -h encoder=webvtt &&
ffprobe -version
ヘルプに、指定した各フィルターまたはエンコーダーの説明が表示される必要があります。「unknown」というメッセージが出る場合、ヘルプコマンドが正常終了しても、別のビルドが必要です。
この共通実装を subtitle_tools.rb として保存してください。以下のサンプルはすべてこれを再利用します。一時ディレクトリを使うことで、字幕ファイル名が FFmpeg のフィルター構文に入らないようにします。出力の確定には出力先ファイルシステム上のハードリンクを使うため、ファイルシステムがハードリンクに対応している必要があります。
ラッパーの transcode の実装は、FFmpeg の終了ステータスを確認せず、読み取り可能な出力メタデータを検証します。そこでヘルパーでは、メタデータに FFMPEG::Movie を使い、Ruby の system で FFmpeg を呼び出し、終了ステータスを確認してから結果を確定します。
gem 'multi_json', '1.15.0'
gem 'streamio-ffmpeg', '3.0.2'
gem 'srt', '0.1.5'
require 'streamio-ffmpeg'
require 'srt'
require 'tmpdir'
module SubtitleTools
def self.load_srt(path)
raise ArgumentError, 'Subtitle input must be a regular file' unless File.file?(path)
text = File.binread(path, 1024 * 1024 + 1)
raise ArgumentError, 'Subtitle input exceeds 1 MiB' if text.bytesize > 1024 * 1024
text.force_encoding(Encoding::UTF_8)
raise ArgumentError, 'Subtitles must be valid UTF-8' unless text.valid_encoding?
subtitles = SRT::File.parse(text)
if subtitles.lines.empty? || !subtitles.errors.empty?
raise ArgumentError, 'Invalid or empty SRT input'
end
unless subtitles.lines.all? { |line| line.start_time >= 0 && line.end_time > line.start_time }
raise ArgumentError, 'Invalid subtitle timing'
end
raise ArgumentError, 'Caption text must not be empty' if subtitles.lines.any? { |line| line.text.empty? }
subtitles
end
def self.with_output(output_path, extension)
output = File.join(File.realpath(File.dirname(output_path)), File.basename(output_path))
if File.exist?(output) || File.symlink?(output)
raise ArgumentError, 'Output must not exist'
end
Dir.mktmpdir('.subtitles-', File.dirname(output)) do |temporary|
candidate = File.join(temporary, "result#{extension}")
yield candidate, temporary
raise IOError, 'No nonempty output produced' unless File.file?(candidate) && File.size(candidate) > 0
File.link(candidate, output)
end
end
def self.burn(video_path, subtitle_path, output_path)
subtitles = load_srt(subtitle_path)
movie = FFMPEG::Movie.new(File.realpath(video_path))
raise ArgumentError, 'Invalid video input' unless movie.valid? && movie.video_codec
with_output(output_path, '.mp4') do |candidate, temporary|
File.write(File.join(temporary, 'captions.srt'), subtitles.to_s)
# Fixed basenames avoid FFmpeg's separate filter-path escaping rules.
unless system(FFMPEG.ffmpeg_binary, '-nostdin', '-n', '-i', movie.path,
'-c:v', 'libx264', '-c:a', 'aac', '-vf', 'subtitles=captions.srt',
'-threads', '2', candidate, chdir: temporary)
raise IOError, 'Video encoding failed'
end
end
end
def self.write_srt(subtitles, output_path)
with_output(output_path, '.srt') { |candidate| File.write(candidate, subtitles.to_s) }
end
def self.convert_to_vtt(subtitle_path, output_path)
subtitles = load_srt(subtitle_path)
with_output(output_path, '.vtt') do |candidate, temporary|
input = File.join(temporary, 'captions.srt')
File.write(input, subtitles.to_s)
unless system('ffmpeg', '-nostdin', '-n', '-i', input, '-c:s', 'webvtt', candidate)
raise IOError, 'Subtitle conversion failed'
end
end
end
end
後述のバッチ処理は、このヘルパーを順次呼び出します。選択された動画を H.264 に再エンコードし、音声があれば AAC に再エンコードします。FFmpeg のデフォルトのストリーム選択が適用されるため、複数トラックを含むソースの全トラックが保持されるわけではありません。検証済みのローカルメディアを使ってください。これらのスニペットは、アップロード用のサンドボックスを提供しません。
CLI との境界となる次の実装を、同じ場所に add_subtitles.rb として保存します。
require_relative 'subtitle_tools'
abort 'Usage: ruby add_subtitles.rb <video.mp4> <subtitles.srt> <new-output.mp4>' unless ARGV.length == 3
begin
SubtitleTools.burn(*ARGV)
puts 'Subtitles added'
rescue StandardError
warn 'Subtitle processing failed. Check the inputs, output path, and FFmpeg installation.'
exit 1
end
手元の MP4 と UTF-8 の SRT ファイルを使うか、次の短いテスト動画を生成してください。input.mp4 がすでに存在する場合、このコマンドは処理を拒否します。
ffmpeg -nostdin -n -f lavfi -i 'color=c=0x101020:s=320x180:r=10:d=4.3' \
-f lavfi -i 'sine=frequency=660:sample_rate=48000:duration=4.3' \
-c:v libx264 -threads 2 -pix_fmt yuv420p -c:a aac input.mp4
次のキューを subtitles.srt として保存します。
1
00:00:00,600 --> 00:00:01,400
First Ruby caption
2
00:00:02,100 --> 00:00:03,200
Second cue: café
3
00:00:04,000 --> 00:00:04,200
Final cue
ruby add_subtitles.rb input.mp4 subtitles.srt output_with_subs.mp4
output_with_subs.mp4 を動画プレーヤーで開いてください。テストクリップでは、最初の字幕が 0.6 秒から 1.4 秒、次が 2.1 秒から 3.2 秒、最後が 4.0 秒から 4.2 秒に表示されます。その間には字幕が表示されず、4.3 秒の動画には元のトーン音が残っているはずです。再生の確認は最初の確認にすぎません。文字、配置、タイミングを SRT と照合してください。
SRT gem による SRT ファイルの操作
すべての字幕が 2.5 秒早く表示される場合は、全キューをその分だけ遅らせます。次の内容を shift_subtitles.rb として保存してください。
require_relative 'subtitle_tools'
abort 'Usage: ruby shift_subtitles.rb <subtitles.srt> <new-output.srt>' unless ARGV.length == 2
begin
subtitles = SubtitleTools.load_srt(ARGV[0])
subtitles.timeshift(all: '+2.5s')
SubtitleTools.write_srt(subtitles, ARGV[1])
puts 'Subtitles shifted by 2.5 seconds'
rescue StandardError
warn 'Subtitle shift failed. Check the SRT input and use a new output path.'
exit 1
end
ruby shift_subtitles.rb subtitles.srt modified.srt
テスト用のキューは 3.1–3.9 秒、4.6–5.7 秒、6.5–6.7 秒になり、テキストは変わりません。時刻をずらすと字幕のタイムラインが変わるため、これらのキューは短いテスト動画の終了後まで続きます。そのクリップに焼き込む場合は、時刻をずらしていない SRT を使ってください。gem のドキュメントに記載された
timeshift メソッドは、オプションのハッシュを受け取ります。動画に合わせて遅延を調整してください。このサンプルは全キューに同じオフセットを適用するもので、徐々に広がるずれは補正しません。
字幕形式の変換
元のキューの時刻を保持した WebVTT の別ファイルを生成するには、次の内容を convert_subtitles.rb として保存します。
require_relative 'subtitle_tools'
abort 'Usage: ruby convert_subtitles.rb <subtitles.srt> <new-output.vtt>' unless ARGV.length == 2
begin
SubtitleTools.convert_to_vtt(*ARGV)
puts 'WebVTT subtitles saved'
rescue StandardError
warn 'Subtitle conversion failed. Check the SRT input, output path, and FFmpeg installation.'
exit 1
end
ruby convert_subtitles.rb subtitles.srt subtitles.vtt
サンプルの SRT の場合、subtitles.vtt の内容は次のとおりです。
WEBVTT
00:00.600 --> 00:01.400
First Ruby caption
00:02.100 --> 00:03.200
Second cue: café
00:04.000 --> 00:04.200
Final cue
WebVTT にはヘッダーがあり、ミリ秒の区切りにはピリオドを使います。変換では別ファイルを作成し、MP4 にトラックを追加するわけではありません。時刻をずらした SRT を変換する場合は、次のようにします。
ruby convert_subtitles.rb modified.srt shifted.vtt
字幕統合時のエラー処理
各 CLI は、ヘルパーが失敗すると非ゼロのステータスを返します。ローダーは、存在しないファイル、1 MiB を超える SRT、不正な UTF-8、パーサーが報告したエラー、空の字幕テキスト、表示時間が正でないキューを拒否します。gem は個々の行に解析エラーを記録することがあるため、例外がスローされたかどうかだけを確認すると、これらのエラーを見逃します。
すべての出力は新規ファイルである必要があり、親ディレクトリはすでに存在している必要があります。再実行時は既存の出力先を拒否し、そのバイト列を保持します。出力先と同じ場所に一時出力を置き、ハードリンクで確定することで、通常の失敗時に書き込み途中の結果が公開されるのを防ぎます。プロセスを強制終了すると .subtitles-… ディレクトリが残る場合があります。削除する前に内容を確認してください。
FFmpeg は破損したメディアの一部を復旧し、成功を返すことがあります。後半の AAC パケットを破損させたテストでは、音声が短くなった再生可能な MP4 が生成されました。メタデータとデコードの成功だけでは、未知のソースが完全だったとは証明できません。結果の再生時間、音声、末尾のフレームを、内容が既知の入力と比較してください。FFmpeg の診断情報がローカルログに出ることがあります。Web クライアントに送るメッセージとは分離してください。
対応する字幕形式
これらのスクリプトは UTF-8 の SRT を受け取り、SRT、WebVTT、または字幕焼き込み済み MP4 を生成します。サンプルが扱うのは、通常の会話のキューです。ASS のスタイル、WebVTT の配置指定、その他の字幕形式には、別の入力処理が必要です。名前を .srt に変更しても変換にはなりません。
実践例:字幕付き動画のバッチ処理
MP4 ファイルを含むディレクトリでは、同じヘルパーを順次再利用します。次の内容を batch_subtitles.rb として保存してください。lesson.mp4 と lesson.srt を組にします。大文字の .MP4 拡張子も受け付け、シンボリックリンクの項目はスキップします。出力ディレクトリは新規である必要があります。
require_relative 'subtitle_tools'
def batch_process_videos(video_dir, subtitle_dir, output_dir)
video_files = Dir.children(video_dir).sort.filter_map do |name|
path = File.join(video_dir, name)
path if File.extname(name).downcase == '.mp4' && File.file?(path) && !File.symlink?(path)
end
raise ArgumentError, 'No MP4 files found' if video_files.empty?
Dir.mkdir(output_dir, 0700)
failures = 0
video_files.each do |video|
basename = File.basename(video, File.extname(video))
begin
SubtitleTools.burn(video, File.join(subtitle_dir, "#{basename}.srt"),
File.join(output_dir, "#{basename}_subtitled.mp4"))
puts "Converted #{basename}"
rescue StandardError
failures += 1
warn "Conversion failed for #{basename}"
end
end
failures.zero? ? 0 : 1
end
abort 'Usage: ruby batch_subtitles.rb <videos> <subtitles> <new-output-directory>' unless ARGV.length == 3
begin
exit batch_process_videos(*ARGV)
rescue StandardError
warn 'Cannot prepare batch. Check input directories and use a new output directory.'
exit 1
end
ruby batch_subtitles.rb videos captions subtitled
最初に videos と captions を作成し、対応するファイルをそれぞれに配置してください。字幕が存在しない場合や不正な場合は失敗として数え、メッセージに動画のベース名を表示します。残りのファイルも引き続き処理を試み、成功した出力は保持します。終了ステータスがゼロなら、選択されたすべての動画の変換が完了したことを示します。ステータスが一なら、準備または少なくとも一つの変換が失敗したことを示します。再試行時は、完了したファイルを残すため、新しい出力ディレクトリを使ってください。
マネージドな代替手段については、Transloadit の 🤖 /video/subtitle Robot と動画エンコーディングサービスをご覧ください。
