CLI 字幕ワークフロー:生成、変換、焼き込み
以下のスクリプトに、英語の音声を含む MP4 動画のディレクトリを渡します。タイミング付きの SRT 字幕、WebVTT のコピー、独立した字幕トラック付きの MKV、フレームに字幕を描画した MP4 が生成されます。Whisper.cpp が CPU で文字起こしを行い、FFmpeg が字幕の変換と動画の出力を行います。結果は下書きとして扱い、公開前に確認してください。
選択可能な字幕と焼き込み字幕の選択
| 選択可能な字幕トラック | 焼き込み字幕 | |
|---|---|---|
| 視聴者による非表示切り替え | トラック対応のプレーヤーで可能 | 不可 |
| テキストの変更 | 動画をエンコードせずにトラックを置換 | 新しい動画をエンコード |
| 動画処理 | 既存の映像ストリームをコピー | テキストを描画し、新しいフレームをエンコード |
| 再生要件 | コンテナと字幕への対応 | 出力動画のコーデックへの対応 |
字幕トラックを選択できるようにする場合は MKV を使い、字幕の切り替え操作なしで常にテキストを表示する必要がある場合は、焼き込み済みの MP4 を使います。どちらも、すべてのプレーヤーで出力動画を再生できることを保証するものではありません。ファイルサイズはソースとエンコード設定によって変わり、字幕を焼き込んでも必ず増えるとは限りません。
CPU 文字起こしツールのインストール
Bash とパッケージのインストール権限がある Linux システムを使用してください。以下のコマンドは Ubuntu 24.04 を対象とし、Whisper.cpp の
v1.9.4 リリースを使用します。英語専用の tiny.en モデルで例を小規模にしていますが、精度を保証するものではありません。インストールとモデルのダウンロードにはインターネット接続が必要です。その後の文字起こしはローカルで実行されます。
FFmpeg、C++ コンパイラー、CMake、描画用フォントをインストールします。
(
sudo apt-get update &&
sudo apt-get install -y build-essential cmake curl ca-certificates tar ffmpeg fonts-liberation
)
書き込み可能な作業ディレクトリから、subtitle-tools を作成します。サブシェルを使うため、現在のディレクトリとシェルオプションは変更されません。そのディレクトリがすでに存在する場合、内部へのインストールや書き込みを行う前にセットアップが停止します。既存の作業を削除せず、別の作業ディレクトリを選んでください。
(
mkdir subtitle-tools &&
cd subtitle-tools &&
curl -fsSLo whisper.tar.gz https://github.com/ggml-org/whisper.cpp/archive/refs/tags/v1.9.4.tar.gz &&
mkdir source &&
tar -xzf whisper.tar.gz -C source --strip-components=1 &&
cmake -S source -B build -DCMAKE_BUILD_TYPE=Release \
-DGGML_CUDA=OFF -DGGML_VULKAN=OFF -DGGML_NATIVE=OFF \
-DBUILD_SHARED_LIBS=OFF -DWHISPER_BUILD_TESTS=OFF &&
cmake --build build --target whisper-cli -j2 &&
curl -fsSLo ggml-tiny.en.bin \
https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-tiny.en.bin &&
printf '%s %s\n' \
921e4cf8686fdd993dcd081a5da5b6c365bfde1162e72b08d75ac75289920b1f \
ggml-tiny.en.bin | sha256sum -c -
)
ここでは Whisper.cpp の CMake によるビルドと音声の準備手順を使用します。この CLI は、スクリプトが各動画から抽出するモノラル、16 kHz、16 ビット PCM WAV を受け付けます。SubsAI など、ほかの Whisper ラッパーには独自のコマンド構文がありますが、ここでは不要です。
録音を用意せずにワークフローを試すには、リリースに同梱された JFK の演説サンプルから動画を作成します。セットアップと同じ作業ディレクトリから実行してください。
(
mkdir demo-videos &&
ffmpeg -nostdin -n -v error -f lavfi -i color=c=black:s=640x360:r=24 \
-i ./subtitle-tools/source/samples/jfk.wav \
-map 0:v:0 -map 1:a:0 -c:v libx264 -threads 2 -c:a aac -shortest \
./demo-videos/example.mp4
)
シェルスクリプトによる全工程の自動化
以下を subtitle-tools/subtitles.sh として保存します。処理対象は最上位にある、小文字の .mp4 拡張子を持つ通常ファイルのみで、シンボリックリンクはスキップします。入力ごとに、その隣に
example.mp4.subtitles などの新しいディレクトリを作成します。ファイル名のスペース、引用符、先頭のハイフンに対応していますが、改行文字を含むパスは拒否します。バッチは一度に一つずつ実行してください。
各結果ディレクトリ内で固定のファイル名を使うことで、元のパスが FFmpeg 独自のフィルター構文に入らないようにしています。スクリプトはソースのコピーと PCM 音声ファイルを保存するため、両方の出力動画に加えて、これらの分のディスク容量も確保してください。
#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
fail() { printf '%s\n' "$*" >&2; exit 1; }
[[ $# -eq 1 ]] || fail 'Usage: bash subtitles.sh VIDEO_DIRECTORY'
[[ $PWD != *$'\n'* && $1 != *$'\n'* && ${BASH_SOURCE[0]} != *$'\n'* ]] ||
fail 'Newline characters in paths are not supported'
input_directory=$1
[[ $input_directory == /* ]] || input_directory=$PWD/$input_directory
case ${BASH_SOURCE[0]} in
*/*) tool_directory=${BASH_SOURCE[0]%/*} ;;
*) tool_directory=. ;;
esac
cd -P -- "$tool_directory"
tool_directory=$PWD
[[ $tool_directory != *$'\n'* ]] || fail 'Newline characters in paths are not supported'
whisper=$tool_directory/build/bin/whisper-cli
model=$tool_directory/ggml-tiny.en.bin
[[ -x $whisper && -s $model ]] || fail 'Complete the subtitle-tools setup first'
cd -P -- "$input_directory"
[[ $PWD != *$'\n'* ]] || fail 'Newline characters in paths are not supported'
shopt -s nullglob
process_video() (
local video=$1
local output=$video.subtitles
mkdir -- "$output"
cp -- "$video" "$output/source.mp4"
cd -- "$output"
ffmpeg -nostdin -n -v error -xerror -i source.mp4 -map 0:a:0 \
-ar 16000 -ac 1 -c:a pcm_s16le audio.wav
"$whisper" --no-gpu -t 2 -p 1 -l en -m "$model" -f audio.wav -osrt -of captions
[[ -s captions.srt ]] || fail 'No subtitle file was produced'
grep -q -- '-->' captions.srt || fail 'No timed captions were produced; check for speech'
ffmpeg -nostdin -n -v error -i captions.srt -map 0:s:0 -c:s webvtt captions.vtt
ffmpeg -nostdin -n -v error -i source.mp4 -i captions.srt \
-map 0:v:0 -map 0:a:0 -map 1:s:0 -c copy -metadata:s:s:0 language=eng soft.mkv
ffmpeg -nostdin -n -v error -xerror -i source.mp4 \
-vf "subtitles=captions.srt:force_style='Fontname=Liberation Sans,FontSize=24'" \
-map 0:v:0 -map 0:a:0 -c:v libx264 -threads 2 -crf 20 -preset veryfast \
-c:a copy burned.mp4
)
count=0
current_video='setup'
trap 'status=$?; if [[ $status -ne 0 ]]; then printf "Failed while processing: %s\n" "$current_video" >&2; fi' EXIT
for video in "$PWD"/*.mp4; do
[[ -f $video && ! -L $video ]] || continue
[[ $video != *$'\n'* ]] || fail 'Newline characters in paths are not supported'
current_video=$video
printf 'Processing: %s\n' "$video"
process_video "$video"
count=$((count + 1))
printf 'Created: %s.subtitles\n' "$video"
done
[[ $count -gt 0 ]] || fail 'No regular .mp4 files found'
入力ディレクトリではなく、ツールをインストールした作業ディレクトリから実行してください。
bash ./subtitle-tools/subtitles.sh ./demo-videos
./demo-videos を録音が入ったディレクトリに置き換えてください。スクリプトはファイルを選択する前にそのディレクトリのパスを解決します。呼び出し元のディレクトリにある MP4 を処理するわけではありません。保存したスクリプトと入力ディレクトリの両方に絶対パスを指定することもできます。
ディレクトリが空の場合はエラーになります。音声ストリームのない動画、デコードエラー、後続の変換の失敗があると、バッチは停止し、処理中の入力名を表示します。失敗すると、結果ディレクトリに不完全なファイルが残る場合があります。結果ディレクトリがすでに存在する場合は、そのクリップのコピーや文字起こしを行う前にエラーになるため、再実行しても以前の出力は保持されます。処理を再開するためのスクリプトではありません。修正したクリップだけを再試行するには、既存の結果がない別のディレクトリに配置してください。
無音の音声と、音声ストリームがない状態は異なります。モデルが字幕区間を返さない場合や、非音声ラベル、実際には発話されていないテキストを返す場合があります。たとえば、tiny.en では、録音の長さを超える
[BLANK_AUDIO] という字幕区間が生成されることがあります。スクリプトはタイミング付きの字幕区間があるかを確認しますが、文言やタイミングは検証しません。公開前に音声を聴き、字幕区間の終了時刻を動画の長さと照合してください。
また、FFmpeg は破損したメディアの一部を、エラーとして報告せずに復旧できる場合があります。コマンドが成功しても、入力が破損していないことや、文字起こしが正確であることの証明にはなりません。
SRT と WebVTT 字幕の確認
demo-videos/example.mp4.subtitles 内の captions.srt と
captions.vtt を開きます。SRT には番号付きの字幕区間があり、ミリ秒の区切りにはカンマを使います。VTT は WEBVTT で始まり、タイムスタンプには小数点を使います。どちらにも、サンプルの「ask not what your country can do for you」と「ask what you can do for your country」というフレーズが含まれているはずです。音声と文言を照合し、特に名前、句読点、各字幕区間の開始と終了を確認してください。
スクリプト内の変換には、FFmpeg の webvtt 字幕エンコーダーを使います。この SRT から WebVTT への変換に Subtitle Edit CLI は不要です。WebVTT のサイドカーファイルは、対応するウェブプレーヤーの字幕トラックで使えますが、ファイルを生成するだけではウェブサイトに組み込まれません。
選択可能な字幕トラックの確認
Matroska と SRT 字幕に対応したプレーヤーで soft.mkv を開き、英語の字幕トラックを選択します。スクリプトは最初の映像ストリーム、最初の音声ストリーム、生成した字幕を明示的にマッピングします。FFmpeg の
-c copy ストリームコピーモードは、映像をエンコードせずにこれらのストリームを MKV にコピーします。これにより、MKVToolNix を追加でインストールせずに多重化を行えます。
FFmpeg による字幕の焼き込み(ハードコード)
外部字幕ファイルを有効にせず、burned.mp4 を開きます。動画の映像にすでにテキストが表示されているはずです。FFmpeg の
libass を使用する subtitles フィルターが
SRT を描画し、libx264 が変更されたフレームをエンコードします。このため、字幕の焼き込みには映像のエンコードが必要ですが、選択可能なトラックの追加には不要です。どちらの出力でも音声はコピーされます。
背景が黒のサンプルでは、開始から二秒のフレームをデコードして確認することもできます。新しい preview.png には下部付近に白いテキストが表示されるはずです。同じ時刻のソース動画は一面黒です。
(
cd ./demo-videos/example.mp4.subtitles || exit
[[ ! -e preview.png && ! -L preview.png ]] || { printf 'preview.png already exists\n' >&2; exit 1; }
ffmpeg -nostdin -n -v error -ss 2 -i burned.mp4 -frames:v 1 -threads 2 preview.png
)
-n オプションは、既存のプレビューの上書きを拒否します。後から captions.srt を編集しても、生成済みのどちらの動画も VTT も変わりません。修正した字幕を保存し、公開前に新しい出力をレンダリングしてください。
パフォーマンスと規模拡大のヒント
実際の録音を使い、文字起こしと焼き込みを別々に計測してください。この例では意図的に CPU スレッドを二つ使用し、GPU は使用していません。ほかのハードウェアでの処理速度を予測するものではありません。下書きで発話が抜けている場合は、代表的なクリップでより大きな英語モデルと比較し、その出力も確認してください。大きなモデルでも、文字起こしの確認は省略できません。
確認済みの SRT を録音と一緒に保存しておくと、文字起こしをやり直さずに配信形式を変更できます。バッチスクリプトは新しい結果ディレクトリに対して常に文字起こしを行い、修正内容を自動では再利用しません。
まとめ
確認済みの字幕があり、字幕の焼き込みをマネージドサービスで行いたい場合は、当社の
🤖 /video/subtitle Robot が既存の SRT または WebVTT 字幕を受け付けます。文字起こしは生成しません。動画は input_video フォームフィールドに、字幕ファイルは
input_srt にアップロードしてください。以下の Assembly Instructions では、これらの入力を分けて扱います。
{
"steps": {
"subtitle_video": {
"robot": "/video/subtitle",
"use": {
"steps": [
{ "name": ":original", "fields": "input_video", "as": "video" },
{ "name": ":original", "fields": "input_srt", "as": "subtitles" }
]
},
"subtitles_type": "burned",
"font_size": 24,
"position": "bottom",
"font_color": "FFFFFF",
"border_style": "outline"
}
}
}
