Lua と FFmpeg による動画への字幕の焼き込み
Lua から FFmpeg を実行し、既存の SRT ファイルを動画に焼き込みます。以下のスクリプトは、字幕を焼き込み、音声をコピーした MP4 を出力します。生成したテスト動画でテキストとタイミングを確認してから、自分のファイルを使えます。
焼き込んだ字幕は動画のピクセルになります。視聴者は字幕をオフにしたり、別の言語を選択したりできず、スクリーンリーダーもテキストトラックとして読み上げられません。プレーヤーで選択可能な字幕が必要な場合は、SRT を別途保持してください。このサンプルは指定されたテキストを描画するもので、音声の文字起こしや翻訳は行いません。
Linux の前提条件の確認
POSIX シェル、/dev/fd、Lua 5.4 または 5.5、および libass の subtitles フィルターと
libx264 エンコーダーを備えた FFmpeg を使用します。この手順は Linux を対象としています。以下のコマンドは Ubuntu 24.04 に前提ソフトウェアをインストールします。他のパッケージビルドでは、FFmpeg の機能が異なる場合があります。デコードの確認では、通常の Linux coreutils パッケージに含まれる
mktemp、cat、rm も使用します。
このサンプルは、Ubuntu の Lua 5.4.6 と FFmpeg 6.1.1、および Lua 5.5.1 と FFmpeg 9.0.1 でテスト済みです。テスト済みのバージョンに合わせるためだけに古いリリースをインストールせず、メンテナンスされているパッケージを使用してください。
Lua、FFmpeg、およびこのサンプルで使う文字を含むフォントをインストールします。
sudo apt-get update && sudo apt-get install lua5.4 ffmpeg fonts-dejavu-core
ファイルを作成する前に、lua という名前の実行ファイルを確認します。ディストリビューションが lua5.4 のみを提供している場合は、以降の Lua の呼び出しで毎回その名前を使用してください。libass の要件については、FFmpeg の
subtitles フィルターのドキュメントで説明されています。
lua -v &&
ffmpeg -hide_banner -h filter=subtitles &&
ffmpeg -hide_banner -h encoder=libx264 &&
ffprobe -version &&
command -v mktemp && command -v cat && command -v rm
フィルターやエンコーダーが認識されない場合は、ここで中止してください。Lua はシェルコマンドを実行し、FFmpeg がデコード、描画、エンコードを行います。Lua のメディアライブラリは不要です。
動画とタイミング付き字幕の作成
他の処理が同時に書き込まない、新しい非公開ディレクトリで作業します。660 Hz のテストトーンと AAC 音声を含む、8.25 秒の黒い動画を生成します。フレームサイズを小さくし、エンコーダーのスレッド数を制限することで、この確認にかかるリソースを抑えています。
(
mkdir lua-subtitles-demo && cd lua-subtitles-demo &&
ffmpeg -nostdin -n -f lavfi -i 'color=c=black:s=640x360:r=24:d=8.25' \
-f lavfi -i 'sine=frequency=660:sample_rate=48000:duration=8.25' \
-c:v libx264 -threads 2 -pix_fmt yuv420p -c:a aac -shortest input.mp4
)
コマンドが成功したら、新しいディレクトリに移動して残りの手順を実行します。
cd lua-subtitles-demo
以下を UTF-8 で subtitles.srt として保存します。SRT のタイムスタンプではミリ秒の前にカンマを使い、キューを空行で区切ります。アクセント付きの単語で、フォントと文字エンコーディングの整合性を確認します。
1
00:00:01,000 --> 00:00:02,000
Hello from Lua: café!
2
00:00:04,000 --> 00:00:05,000
The second subtitle.
セットアップが途中で止まった場合は、作成されたファイルを保持してください。FFmpeg の -n は、既存の
input.mp4 への出力を拒否します。再試行前に内容を調べるか、別の新しいディレクトリで最初からやり直してください。最初のディレクトリ内で
mkdir コマンドを繰り返し実行しないでください。
Lua プログラムの保存と実行
以下を動画と SRT と同じ場所に add_subtitles.lua として保存します。このプログラムはシェル引数を引用符で囲み、字幕ファイルを記述子 3 経由で渡すため、ファイル名が FFmpeg のフィルター構文に組み込まれることはありません。ローカルファイル名に含まれるスペース、アポストロフィ、コロン、角括弧、先頭のハイフンを扱えます。
#!/usr/bin/env lua
if #arg ~= 0 and #arg ~= 3 then
io.stderr:write("Usage: lua add_subtitles.lua <video.mp4> <subtitles.srt> <new-output.mp4>\n")
os.exit(1)
end
local video_file = arg[1] or "input.mp4"
local subtitles_file = arg[2] or "subtitles.srt"
local output_file = arg[3] or "output.mp4"
local existing = io.open(output_file, "rb")
if existing then
existing:close()
io.stderr:write("Output already exists; choose a new filename.\n")
os.exit(1)
end
local function shell_quote(value)
return "'" .. value:gsub("'", "'\\''") .. "'"
end
local function local_path(value)
if value:sub(1, 1) == "/" then return value end
return "./" .. value
end
local filter = "subtitles=/dev/fd/3"
local command = string.format(
"ffmpeg -nostdin -n -filter_threads 1 -i %s -vf %s -c:v libx264 -threads 2 -crf 23 -c:a copy %s 3<%s",
shell_quote(local_path(video_file)),
shell_quote(filter),
shell_quote(local_path(output_file)),
shell_quote(local_path(subtitles_file))
)
local success = os.execute(command)
if not success then
io.stderr:write("Subtitle conversion failed. Inspect any partial output before retrying.\n")
os.exit(1)
end
print("Subtitles added successfully.")
動画、字幕ファイル、新しい出力ファイル名の順に指定して実行します。
lua add_subtitles.lua input.mp4 subtitles.srt output.mp4
FFmpeg が完了すると、プログラムは次のように出力します。
Subtitles added successfully.
プログラムは既存の出力をエラーとして報告し、-n によって
FFmpeg にも上書きを禁止します。Lua のシェルコマンドの終了ステータスを使い、FFmpeg が失敗した場合は成功メッセージを表示しません。ただし、出力の公開をトランザクションとして扱う仕組みではありません。変換に失敗すると新しい不完全なファイルが残る場合があり、存在確認では同時書き込みを調整しません。再試行前に不完全な出力を調べ、新しい出力パスを選んでください。
表示結果と音声の確認
動画プレーヤーで output.mp4 を開きます。全体を通してトーンが聞こえ、1 秒から 2 秒には「Hello from Lua: café!」、4 秒から 5 秒には「The second subtitle.」と表示されるはずです。それ以外の時間帯は、テキストのない黒い背景になるはずです。タイミングだけでなくアクセント記号も確認してください。エンコードの成功だけでは、字幕が読めることの証明にはなりません。
追加の確認として、ストリームを調べ、出力全体をデコードします。
ffprobe -v error -show_entries stream=codec_type,codec_name -of compact output.mp4 &&
(
decode_log=$(mktemp) || exit 1
trap 'rm -f "$decode_log"' EXIT
if ffmpeg -nostdin -v error -xerror -i output.mp4 -map 0:v:0 -map 0:a:0 -f null - \
2>"$decode_log" && [ ! -s "$decode_log" ]; then
printf 'Full decode finished without errors.\n'
else
cat "$decode_log" >&2
false
fi
)
生成したテストデータでは、H.264 動画、AAC 音声、および「Full decode finished without errors.」という出力が期待されます。サブシェルは FFmpeg の終了ステータスだけでなくエラー出力も確認します。ビルドによっては、デコーダーのエラーを報告しても終了ステータスがゼロになるためです。どちらの結果でも一時ログを削除し、呼び出し元のシェルは終了させません。この確認では字幕のテキストやタイミングは評価しないため、目視確認も行ってください。自分のメディアを使う場合は、有効なローカル動画と MP4 がサポートする音声コーデックを使います。-c:a copy は、選択した音声ストリームを変換せずにコピーするためです。
コピーするため、出力に破損した音声パケットが残っていても Lua コマンドが完了する場合があります。ストリーム一覧が正しく見えても、上記の全体デコードでその破損が見つかることがあります。成功メッセージだけでは完全性を確認できません。
字幕の遅延またはフォントの選択
すべてのキューを 2.5 秒遅らせるには、時刻をずらした SRT を別途作成し、同じプログラムに渡します。FFmpeg の
-itsoffset オプションは、入力タイムスタンプにオフセットを加算します。
ffmpeg -nostdin -n -itsoffset 2.5 -i subtitles.srt -c:s srt shifted.srt &&
lua add_subtitles.lua input.mp4 shifted.srt delayed.mp4
delayed.mp4 では、最初のキューが 3.5 秒から 4.5 秒、次のキューが 6.5 秒から 7.5 秒に表示されるはずです。1.5 秒にはテキストがないはずです。元のタイミングのまま表示される場合は、shifted.srt を開き、変更後のタイムスタンプを確認してください。
フォントとサイズを固定するには、保存したプログラム内の
filter 変数だけを以下の行に置き換えます。DejaVu Sans がインストールされている必要があります。
local filter = "subtitles=/dev/fd/3:force_style='FontName=DejaVu Sans,FontSize=24'"
変更したプログラムを、新しい出力ファイル名で実行します。
lua add_subtitles.lua input.mp4 subtitles.srt styled.mp4
このスタイル文字列はスクリプト内で固定してください。ユーザーが指定する任意のフィルター式には、別途検証が必要です。シェルの引用処理では FFmpeg のフィルター構文を検証できません。force_style の設定については、上記の subtitles フィルターのリファレンスに記載されています。
自分のファイルの使用と失敗の診断
自分のパスを三つの引数として渡します。元のファイルは入力のまま保持し、.mp4 拡張子の別の出力を選んでください。ファイルがない場合、SRT が無効な場合、MP4 にコピーできない音声の場合は、ゼロ以外の終了ステータスになるはずです。再試行前に FFmpeg の診断メッセージを読んでください。この小さなラッパーは、すべてのパケットや字幕キューを検証するものではありません。デコーダーは破損したメディアを復旧できる場合があるため、録画の最後まで元の内容と比較してください。
アクセント付き文字が正しく描画されない場合は、SRT が UTF-8 であり、選択したフォントにその文字が含まれることを確認します。既知のレガシーエンコーディングを変換する場合は、元のファイルを上書きせず、別のファイルに出力します。
iconv -f ISO-8859-1 -t UTF-8 legacy.srt > converted.srt
このリダイレクトには、まだ使われていない出力先を指定してください。そうしないと、変換に失敗してもファイルが上書きされる場合があります。信頼できないアップロードをこのローカルコマンドに直接渡さないでください。ファイルシステム、ネットワーク、メモリ、実行時間を制限した隔離ワーカーで FFmpeg を実行します。シェルの引用処理はメディアのサンドボックスにはなりません。
