Go と FFmpeg によるアダプティブ動画配信
Go から FFmpeg を実行し、ローカル動画を HLS または MPEG-DASH にパッケージ化して、完成したファイルをブラウザーで再生します。この例では、二つの映像表現を持つ DASH ストリームも作成します。ローカルでのパッケージ化と再生を扱う手順であり、本番用の配信サービスや、ネットワーク状況の変化に応じた品質の切り替えを実演するものではありません。
アダプティブストリーミング入門:HLS と MPEG-DASH の比較
アダプティブビットレートストリーミングは、視聴者のネットワーク状況に応じて動画の品質を動的に調整します。広く使われている規格には、Apple が開発した HLS と、オープン標準の MPEG-DASH があります。HLS は .m3u8 マニフェストファイルを、MPEG-DASH は .mpd ファイルを使用します。どちらの形式も動画を小さなセグメントに分割します。プレーヤーが品質を切り替えるには、互換性のある複数の表現が必要です。一つのエンコード結果をセグメントに分割するだけでは、アダプティブストリーミングにはなりません。
Go で FFmpeg を使うための準備:適切なラッパーの選択
このガイドでは、Go 標準の os/exec パッケージと、FFmpeg の公式ドキュメントに記載されたコマンドラインインターフェースを使用します。Go 用のラッパーは不要です。シェルコマンドには Bash を使い、Go、FFmpeg、ffprobe、cURL を
PATH に配置してください。変換は Linux 上の Go 1.26.8 と FFmpeg/ffprobe 9.0.1 でテストしました。使用する FFmpeg ビルドには、libx264 と AAC のエンコーダー、および HLS と DASH のマルチプレクサーが必要です。
go version && ffmpeg -version && ffprobe -version && ffmpeg -encoders && ffmpeg -muxers
音声トラックを持ち、高さが 360 ピクセル以上の、有効な横向きのローカル動画
input.mp4 があるディレクトリで作業してください。二つの Go プログラムを以下に示すファイル名で保存し、個別に実行します。go run . では、二つの main 関数がまとめて扱われてしまいます。変換プログラムは動画を毎秒 24 フレームに正規化し、四秒ごとにキーフレームを揃えます。解像度とビットレートラダーは素材に合わせて調整してください。二つの表現を生成すること自体が、推奨品質を意味するわけではありません。
Go と FFmpeg による動画の HLS 形式への変換
以下の完全なプログラムを stream.go として保存してください。同じ実行プログラムで、HLS、単一映像の DASH、二つの映像表現を持つ DASH に対応します。以前のジョブのマニフェストやセグメントと衝突しないよう、実行ごとに新しい出力ディレクトリが必要です。FFmpeg はシェルを介さずに起動します。
package main
import (
"context"
"fmt"
"os"
"os/exec"
"path/filepath"
"time"
)
func convert(inputPath, outputPath, format string) (err error) {
if format != "hls" && format != "dash" && format != "adaptive-dash" {
return fmt.Errorf("format must be hls, dash, or adaptive-dash")
}
input, err := filepath.Abs(inputPath)
if err != nil {
return err
}
info, err := os.Stat(input)
if err != nil {
return err
}
if !info.Mode().IsRegular() {
return fmt.Errorf("input must be a regular local file")
}
output, err := filepath.Abs(outputPath)
if err != nil {
return err
}
if err = os.Mkdir(output, 0700); err != nil {
return fmt.Errorf("use a new output directory: %w", err)
}
defer func() {
if err != nil {
if cleanupErr := os.RemoveAll(output); cleanupErr != nil {
fmt.Fprintln(os.Stderr, "Cannot remove partial output:", cleanupErr)
}
}
}()
args := []string{"-nostdin", "-n", "-i", input, "-map", "0:v:0"}
if format == "adaptive-dash" {
args = append(args, "-map", "0:v:0")
}
args = append(args, "-map", "0:a:0", "-c:v", "libx264", "-preset", "fast",
"-pix_fmt", "yuv420p", "-r", "24", "-g", "96", "-keyint_min", "96",
"-sc_threshold", "0", "-force_key_frames", "expr:gte(t,n_forced*4)",
"-c:a", "aac", "-b:a", "96k", "-ac", "2", "-threads", "2", "-filter_threads", "1")
if format == "adaptive-dash" {
args = append(args, "-filter:v:0", "scale=-2:180", "-b:v:0", "400k",
"-filter:v:1", "scale=-2:360", "-b:v:1", "800k")
} else {
args = append(args, "-b:v", "800k")
}
if format == "hls" {
args = append(args, "-f", "hls", "-hls_time", "4", "-hls_playlist_type", "vod",
"-hls_segment_filename", "segment-%04d.ts", "index.m3u8")
} else {
args = append(args, "-f", "dash", "-seg_duration", "4", "-use_template", "1",
"-use_timeline", "1", "-adaptation_sets", "id=0,streams=v id=1,streams=a", "index.mpd")
}
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
defer cancel()
cmd := exec.CommandContext(ctx, "ffmpeg", args...)
cmd.Dir = output
cmd.Stderr = os.Stderr
if err = cmd.Run(); err != nil {
return fmt.Errorf("conversion failed: %w", err)
}
return nil
}
func main() {
if len(os.Args) != 4 {
fmt.Fprintln(os.Stderr, "Usage: go run stream.go <input.mp4> <new-output-directory> <hls|dash|adaptive-dash>")
os.Exit(1)
}
if err := convert(os.Args[1], os.Args[2], os.Args[3]); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
fmt.Println("Conversion complete")
}
次のコマンドを実行します。
go run stream.go input.mp4 hls-output hls
これにより、VOD メディアプレイリストと、映像ビットレートが一種類の MPEG-TS セグメントを生成します。これはセグメント化されたストリーミングであり、まだアダプティブビットレートストリーミングではありません。コマンドが成功するまで、出力ディレクトリを視聴者に公開しないでください。
Go による MPEG-DASH 変換の実装
同じプログラムを dash モードで使用します。
go run stream.go input.mp4 dash-output dash
出力には index.mpd、初期化セグメント、メディアセグメントが含まれます。公開時も、これらのファイル名と相対的な配置を維持してください。このモードは、一つの映像表現と、独立した音声の適応セットを生成します。
アダプティブビットレート用バリアントの作成
adaptive-dash モードは入力映像を二回マッピングし、各出力をスケーリングして、それぞれに異なるビットレートを割り当てます。-b:v:1 の設定だけでは二つ目の映像ストリームは作成されず、追加のマッピングが不可欠です。両方の表現でキーフレームの位置を揃え、一つの音声ストリームを共有します。
go run stream.go input.mp4 adaptive-output adaptive-dash
この例示用の 180p/360p ラダーには、高さが 360 ピクセル以上のソースを使用し、両方の品質で文字、動き、アスペクト比を確認してください。本番用のビットレートラダーは、コンテンツと対象デバイスに合わせる必要があります。複数バリアントの HLS には、複数のメディアプレイリストとマスタープレイリストも必要です。上記の単一バリアントの HLS モードでは、これらは作成されません。
セグメントを処理するストリーミングサーバーの構築
ローカルで再生を確認するため、videos ディレクトリには、処理が完了した公開用のテスト出力だけを配置してください。三つの変換がすべて成功したら、出力ディレクトリをまとめて移動します。
test -f hls-output/index.m3u8 &&
test -f dash-output/index.mpd &&
test -f adaptive-output/index.mpd &&
mkdir videos &&
mv hls-output dash-output adaptive-output videos/
videos ディレクトリがすでに存在する場合、このコマンドは内容を置き換えずに停止します。最初からすべて再実行する際は、既存データを削除するのではなく、新しいプロジェクトディレクトリを使用してください。
以下の別プログラムを serve.go として保存してください。ループバックにバインドし、必要な MIME タイプを設定します。ここでは Go の http.FileServer によりディレクトリ一覧が有効になるため、公開ディレクトリに非公開ファイルを置かないでください。
package main
import (
"flag"
"fmt"
"log"
"mime"
"net"
"net/http"
"time"
)
func main() {
port := flag.Int("port", 8080, "Loopback port for local playback")
flag.Parse()
for extension, contentType := range map[string]string{
".m3u8": "application/vnd.apple.mpegurl", ".mpd": "application/dash+xml",
".ts": "video/mp2t", ".m4s": "video/iso.segment", ".mp4": "video/mp4",
} {
if err := mime.AddExtensionType(extension, contentType); err != nil {
log.Fatal(err)
}
}
mux := http.NewServeMux()
mux.Handle("/videos/", http.StripPrefix("/videos/", http.FileServer(http.Dir("./videos"))))
listener, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", *port))
if err != nil {
log.Fatal(err)
}
server := &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second}
log.Printf("Serving local test media at http://%s/videos/", listener.Addr())
log.Fatal(server.Serve(listener))
}
バージョンを固定した Shaka Player のビルドを、同じ公開ディレクトリにダウンロードします。このコマンドにはインターネット接続が必要です。同じファイル名のライブラリがすでに存在する場合は置き換えます。ダウンロードが成功してから、次に進んでください。
curl -fsSLo videos/shaka-player.compiled.js https://cdn.jsdelivr.net/npm/shaka-player@5.2.12/dist/shaka-player.compiled.js
このページを videos/player.html として保存してください。Shaka の基本設定に従い、ページからの相対パスでマニフェストを読み込むため、メディアとプレーヤーが同じオリジンを共有します。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Local HLS and DASH playback</title>
<style>
html { color-scheme: light dark; }
video { max-width: 100%; height: auto; }
</style>
<script src="shaka-player.compiled.js"></script>
</head>
<body>
<form id="streams">
<label>Stream
<select id="manifest" disabled>
<option value="hls-output/index.m3u8">HLS</option>
<option value="dash-output/index.mpd">DASH</option>
<option value="adaptive-output/index.mpd">Adaptive DASH</option>
</select>
</label>
<button disabled>Load stream</button>
</form>
<p id="status" role="status">Initializing player…</p>
<video id="video" aria-label="Video preview" controls width="640"></video>
<script>
async function initialize() {
const status = document.getElementById('status')
const form = document.getElementById('streams')
const manifest = document.getElementById('manifest')
const button = form.querySelector('button')
shaka.polyfill.installAll()
if (!shaka.Player.isBrowserSupported()) {
status.textContent = 'This browser cannot play these streams.'
return
}
const player = new shaka.Player()
await player.attach(document.getElementById('video'))
window.player = player
player.addEventListener('error', () => {
status.textContent = 'Playback failed. Check the manifest and segments.'
})
form.addEventListener('submit', async (event) => {
event.preventDefault()
button.disabled = manifest.disabled = true
status.textContent = 'Loading stream…'
try {
await player.load(manifest.value)
status.textContent = 'Ready. Press play.'
} catch {
status.textContent = 'Playback failed. Check the manifest and segments.'
} finally {
button.disabled = manifest.disabled = false
}
})
button.disabled = manifest.disabled = false
status.textContent = 'Choose a stream.'
}
initialize().catch(() => {
document.getElementById('status').textContent = 'Player initialization failed.'
})
</script>
</body>
</html>
serve.go と videos があるディレクトリから、サーバーをフォアグラウンドで起動します。
go run serve.go -port 8080
H.264/AAC と Media Source Extensions に対応したブラウザーで
http://127.0.0.1:8080/videos/player.html を開いてください。ストリームを選び、Load stream をクリックして、Ready. Press play. が表示されるまで待ち、動画の再生コントロールを操作します。三つの項目をすべて試し、終わり近くまでシークしてください。サーバーは Ctrl+C で停止します。ポート 8080 が使用中の場合は、別の -port 値を選び、ブラウザーの URL でもそのポートを使用してください。バインドに失敗すると、配信 URL を表示せずにエラーで終了します。再生は Shaka Player 5.2.12 と Chromium 145 で確認しました。
並行処理によるパフォーマンスの最適化
まず変換ワーカーを一つにして、CPU、メモリ、ディスクの使用状況を測定します。キュー内のアップロードごとに goroutine を作るのではなく、上限のあるワーカープールで並行処理数を増やしてください。ジョブごとに専用の出力ディレクトリを用意し、意図的に再試行できるよう、各失敗をキューに報告します。プログラムのタイムアウトは一つの FFmpeg プロセスの実行時間を制限するものであり、OS の制限やサンドボックスの代わりにはなりません。
信頼できないメディアには、認証情報を持たず、無制限のネットワークアクセスもできない隔離ワーカーを使用してください。完成した出力は、適切に設定した Web サーバーまたは CDN を通じて公開します。HTTPS、キャッシュルール、必要に応じたアクセス制御を設定し、CORS は対応対象とするプレーヤーのオリジンにのみ許可してください。ループバックの開発用サーバーは、本番用のストリーミングサービスではありません。
ストリーミング実装のテストとデバッグ
上記のプレーヤーで確認できるのは、ローカルでの再生です。ビットレートラダーの見た目が良好であることや、実際のネットワーク状況で自動切り替えがうまく働くことは証明しません。公開前に、録画の終端も含めてデコード後の映像と音声を確認し、FFmpeg の診断情報も確認してください。
入力がない場合、音声トラックがない場合、または FFmpeg プロセスが失敗した場合は、ゼロ以外のステータスを返します。実行プログラムは変換に失敗すると新しい出力ディレクトリを削除し、既存の出力先への上書きは拒否します。FFmpeg は一部の破損した入力から回復し、成功を返す場合があります。「Conversion complete」は、入力が破損していなかったことを保証しません。有効であることが確認済みのソースファイルを使用し、出力の内容と長さをソースと比較してください。
プロジェクトディレクトリから、アダプティブ DASH のストリームを調べ、完成した各出力内のすべてのストリームをデコードします。マニフェストに絶対パスを指定すると、DASH デマルチプレクサーがセグメントのファイル名を解決する際の曖昧さを避けられます。
(
decodeStream() {
local diagnostics
if diagnostics=$(ffmpeg -v error -xerror -i "$1" -map 0 -f null - 2>&1); then
if [ -z "$diagnostics" ]; then return 0; fi
fi
printf 'Decode check failed for %s\n%s\n' "$1" "$diagnostics" >&2
return 1
}
ffprobe -v error -count_frames -show_entries stream=codec_name,codec_type,width,height,nb_read_frames -of json "$PWD/videos/adaptive-output/index.mpd" &&
decodeStream "$PWD/videos/hls-output/index.m3u8" &&
decodeStream "$PWD/videos/dash-output/index.mpd" &&
decodeStream "$PWD/videos/adaptive-output/index.mpd"
)
JSON には、高さが 180 ピクセルと 360 ピクセルの H.264 映像と、AAC 音声が表示されるはずです。幅はソースのアスペクト比によって変わります。両方の映像表現の nb_read_frames を比較してください。入力が同じでフレームレートも正規化していれば、数は同じになるはずです。最終フラグメントが破損していると、FFmpeg がエラーの診断情報を出さずにゼロを返しても、一方の表現だけが警告なく短くなる場合があります。数が一致しない場合は、公開せずに調査が必要です。最終的な映像と音声もソースと照合してください。数が一致するだけでは、内容が欠けていないことを証明できません。デコーダーによるチェックは成功時に何も出力せず、プロセスの失敗やエラーの診断情報があれば、FFmpeg が回復してゼロを返しても、一連の処理を停止します。それでも、元の録画が破損していなかったことや、想定するすべてのフレームが残っていることまでは確認できません。AAC のパディングにより音声が映像よりわずかに長くなる場合があるため、丸められたマニフェストの再生時間だけに頼らず、デコードした内容とタイムスタンプを比較してください。
参照される初期化セグメントとメディアセグメントがすべて存在し、想定する MIME タイプを持ち、成功レスポンスを返すことも確認してください。adaptive-dash については、ファイル名からアダプティブ配信だと推測せず、MPD に二つの映像表現があるかを調べてください。パッケージ化の詳細は、FFmpeg の DASH および HLS マルチプレクサーのオプションを参照してください。
まとめ
これで、ローカルの HLS ストリーム、単一映像の DASH ストリーム、二つの映像表現を持つ DASH ストリームができました。このループバックでの確認から公開環境へ移す際も、各マニフェストとそのセグメントをまとめて保持してください。
マネージドソリューションをお探しの場合は、Transloadit の 🤖 /video/adaptive Robot が HLS と MPEG-DASH のパッケージ化を処理します。Go との連携には、当社の go-sdk を参照してください。
