Python と FFmpeg で Twitch のハイライト動画を作成
冒頭の場面、最高のプレイ、締めくくりのリアクションを好みの順序に並べ、Python と FFmpeg でローカルのクリップを一つの MP4 にまとめます。この手順では、縦長映像の周囲に黒い余白を加えた 1280×720 のハイライト動画を作成します。音声のないクリップには無音を補い、途切れのないステレオ音声トラックを作成します。
素材クリップの選択
所有している、または使用許可を得ている MP4 クリップを、あらかじめディスクに保存しておきます。素材の取得は別の作業です。このプログラムは Twitch からクリップを取得せず、API トークンも必要ありません。使用する場面と順序は自分で決めてください。人気クリップの一覧では、こうした編集上の判断はできません。
このサンプルで使用できるのは、8 ビット H.264 yuv420p 動画ストリームが一つあり、ピクセルが正方形で、回転メタデータのない、完全な SDR クリップです。音声は、なし、またはモノラルかステレオの AAC ストリーム一つに対応します。トラックはゼロから開始する必要があります。解像度、縦長・横長の形状、フレームレート、音声サンプルレートは異なっていてもかまいません。ほかの形式は、先にこの設定で書き出してください。HDR、複数の音声トラック、開始位置がずれた音声は、別途編集する必要があります。
設定が一致する書き出し済み動画を再エンコードせずに結合する方法とは異なり、この処理では設定の異なるクリップを統一してから結合します。映像を再エンコードするため、元のファイルは保管してください。出力は毎秒 30 フレームで、各クリップの長さは最も近いフレーム単位に丸められます。音声は 48 kHz のステレオにリサンプリングし、短い場合は無音で補い、長い場合はそのクリップの映像の終端で切り詰めます。選択した音声は維持されますが、ラウドネスは均一化しません。
Python と FFmpeg の確認
Bash を備えた Linux と、保守されている Python 3 環境、ffprobe を含む FFmpeg を使用してください。FFmpeg は Python パッケージではなく、別途インストールします。使用するビルドには libx264 と aac のエンコーダーと、以下で使用するフィルターが必要です。pip の依存パッケージはありません。この手順は Python 3.14.8 および 3.15.2 と FFmpeg/ffprobe 9.0.2 で検証しています。Python を新規にインストールする場合は、最新のパッチが適用された 3.15 リリースを使用してください。
プログラムを保存する前に、以下を Bash に貼り付けて各実行ファイルを確認してください。
(
set -eu
command -v python3
command -v ffmpeg
command -v ffprobe
python3 --version
ffmpeg -version
ffprobe -version
)
ハードリンクに対応したファイルシステム上に、書き込み可能なローカル出力ディレクトリを用意してください。エンコード後の動画を保存できる十分な空き容量を確保してください。動画の作成は一度に一つだけ実行し、完了するまで入力ファイルを変更しないでください。各サブプロセスのタイムアウトは 10 分のため、このサンプルは配信全体のアーカイブではなく、短いハイライト動画向けです。
完全な Python プログラムの保存
以下を作業ディレクトリに highlight_reel.py として保存してください。Python は各ファイル名を個別の引数として
subprocess.run に渡すため、クリップ名に空白やアポストロフィが含まれていても、シェルコマンドとして扱われません。パスは有効な UTF-8 である必要があります。
import argparse
import json
import math
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
def run(argv, stage):
result = subprocess.run(
argv, capture_output=True, text=True, encoding="utf-8", errors="replace",
timeout=600,
)
if result.returncode != 0 or result.stderr.strip():
raise RuntimeError(f"{stage}: {result.stderr.strip() or 'command failed'}")
return result.stdout
def inspect(path):
info = json.loads(run([
"ffprobe", "-v", "error", "-show_streams", "-show_format", "-of", "json",
str(path),
], f"Inspecting {str(path)!r}"))
streams = info["streams"]
videos = [s for s in streams if s["codec_type"] == "video"]
audios = [s for s in streams if s["codec_type"] == "audio"]
if len(videos) != 1 or len(audios) > 1 or len(streams) != 1 + len(audios):
raise ValueError(f"{path!s}: expected one video and at most one audio stream")
video = videos[0]
if (video["codec_name"] != "h264" or video.get("pix_fmt") != "yuv420p"
or video.get("sample_aspect_ratio") != "1:1"
or any("rotation" in item for item in video.get("side_data_list", []))
or "rotate" in video.get("tags", {})
or video.get("color_transfer") in ("smpte2084", "arib-std-b67")
or video.get("color_primaries") == "bt2020"):
raise ValueError(f"{path!s}: use SDR H.264, yuv420p, square pixels, no rotation")
if audios and (audios[0]["codec_name"] != "aac" or audios[0]["channels"] not in (1, 2)):
raise ValueError(f"{path!s}: use mono or stereo AAC audio")
if any(abs(float(s.get("start_time", "nan"))) > 0.001
or not math.isfinite(float(s.get("start_time", "nan"))) for s in streams):
raise ValueError(f"{path!s}: tracks must start at zero")
duration = float(video.get("duration", "nan"))
if not math.isfinite(duration) or duration < 1 / 30:
raise ValueError(f"{path!s}: video needs a finite duration of at least one frame")
return round(duration * 30) / 30, bool(audios)
def main():
parser = argparse.ArgumentParser(description="Compile local clips in argument order")
parser.add_argument("--output", required=True)
parser.add_argument("clips", nargs="+")
args = parser.parse_args()
for tool in ("ffmpeg", "ffprobe"):
if shutil.which(tool) is None:
raise ValueError(f"Install {tool} and put it on PATH")
for value in [args.output, *args.clips]:
value.encode("utf-8")
requested = Path(args.output).absolute()
output = requested.parent.resolve(strict=True) / requested.name
if output.suffix.lower() != ".mp4":
raise ValueError("Output must end in .mp4")
if os.path.lexists(output):
raise FileExistsError(f"Destination already exists: {output}")
inputs = []
filters = []
for index, name in enumerate(args.clips):
path = Path(name).resolve(strict=True)
if not path.is_file() or path.suffix.lower() != ".mp4":
raise ValueError(f"{name!r}: expected a local MP4 file")
duration, has_audio = inspect(path)
inputs.extend(["-i", str(path)])
filters.append(
f"[{index}:v:0]setpts=PTS-STARTPTS,"
"scale=1280:720:force_original_aspect_ratio=decrease:force_divisible_by=2,"
"pad=1280:720:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1,fps=30,"
f"tpad=stop_mode=clone:stop_duration=1,trim=duration={duration}[v{index}]"
)
audio = (f"[{index}:a:0]aresample=48000,"
"aformat=sample_fmts=fltp:channel_layouts=stereo,asetpts=PTS-STARTPTS,apad"
if has_audio else "anullsrc=r=48000:cl=stereo")
filters.append(f"{audio},atrim=duration={duration}[a{index}]")
labels = "".join(f"[v{i}][a{i}]" for i in range(len(args.clips)))
filters.append(f"{labels}concat=n={len(args.clips)}:v=1:a=1[v][a]")
with tempfile.TemporaryDirectory(prefix=".twitch-reel-", dir=output.parent) as work:
staged = Path(work) / "reel.mp4"
print(f"Encoding {len(args.clips)} clips…", flush=True)
run([
"ffmpeg", "-nostdin", "-hide_banner", "-v", "error", "-xerror", "-n",
*inputs, "-filter_complex_threads", "1", "-filter_complex", ";".join(filters),
"-map", "[v]", "-map", "[a]", "-c:v", "libx264", "-preset", "medium",
"-crf", "22", "-pix_fmt", "yuv420p", "-threads", "2",
"-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", str(staged),
], f"Encoding clips {list(enumerate(args.clips))}")
run([
"ffmpeg", "-nostdin", "-v", "error", "-xerror", "-i", str(staged),
"-map", "0:v:0", "-map", "0:a:0", "-f", "null", "-",
], "Checking encoded reel")
os.chmod(staged, 0o600)
os.link(staged, output)
print(f"Created {output}")
if __name__ == "__main__":
try:
main()
except (OSError, ValueError, KeyError, RuntimeError, subprocess.TimeoutExpired) as error:
print(f"Cannot create reel: {error}", file=sys.stderr)
sys.exit(1)
FFmpeg の scale フィルターで映像全体をキャンバス内に収め、余白を加えて黒い背景の中央に配置します。縦長のクリップには左右に黒い帯が入ります。エンコード時の幅と高さは偶数でなければならないため、丸めによるわずかな差が生じる場合があります。続いて concat フィルターが、設定を統一した映像と音声のペアを Python から渡された順序で結合します。
選択したクリップを順番に処理
プログラムと同じ場所にある clips ディレクトリにクリップを配置するか、以下のコマンドのパスを実際のパスに置き換えてください。出力先は既存のカレントディレクトリです。ハイフンで始まるファイル名もクリップとして扱われるように、入力リストの前に -- を指定してください。
python3 highlight_reel.py --output highlights.mp4 -- "clips/opening.mp4" "clips/best play.mp4" "clips/reaction.mp4"
正常に完了すると、最終的なパスを表示し、終了コードゼロで終了します。生成されるファイルには H.264 映像と AAC 音声が含まれます。CRF 22 は目標ファイルサイズではなく、x264 の品質ベースのモードを選択する設定です。クリップ間はカットで切り替わります。プログラムが順序を入れ替えたり、処理に失敗した入力をスキップしたりすることはありません。
共有前のハイライト動画の確認
動画プレーヤーで highlights.mp4 を開いてください。冒頭の場面、各カットの前後、縦長映像の端、最後のリアクションを確認してください。各クリップの音声も最後まで聴いてください。無音の素材もタイムライン上で本来の長さを占め、その区間が削除されたり、次の音声の位置がずれたりしていないことを確認します。トランジション、音楽、タイトルは別途編集するもので、このプログラムでは追加しません。
実行に失敗した場合は、診断メッセージを読み、そこに示された入力を確認してください。エンコード段階の診断には、引数リストの先頭をゼロとして数えた FFmpeg の入力インデックスが含まれる場合があります。非対応のストリーム設定は書き出し直す必要があり、デコードエラーには破損のない素材を新たに用意する必要があります。FFmpeg は破損したメディアの一部をエラーの報告なしに復旧できるため、デコードの成功は、意図したすべてのフレームが素材に含まれている証明にはなりません。公開前に映像と音声を確認してください。
プログラムは一時 MP4 をエンコードし、全体をデコードしてから、指定された名前にリンクします。通常の失敗ではゼロ以外の終了コードを返し、未完成の highlights.mp4 を出力先に配置せずに一時ディレクトリを削除します。既存の出力先は保持されるため、再試行時は新しい出力名を選んでください。完成したファイルは所有者が読み書きできます。強制終了や停電が発生すると、隠しディレクトリ .twitch-reel-… が残る場合があります。処理が停止したことを確認してから、その処理で残ったディレクトリだけを削除してください。動画の確認が済むまでは、元のクリップを保管してください。
