Go と qt-faststart による QuickTime ストリーミングの最適化
MP4 または MOV を HTTP のプログレッシブ再生に対応させるには、Go の os/exec パッケージで FFmpeg を
-c copy -movflags +faststart 付きで実行します。以下のプログラムは、再生インデックスをメディアデータの前に配置した非フラグメント形式の MP4 を作成し、最初の映像ストリームとすべての音声ストリームを保持して、既存の出力を拒否します。サードパーティーの Go パッケージや別の qt-faststart 実行ファイルを使わずに、qtfaststart 方式を利用します。
QuickTime ストリーミングの課題
MP4 と QuickTime のコンテナーは、アトムとも呼ばれるボックスに情報を格納します。moov ボックスにはトラックとタイミングの情報が入り、mdat にはメディアデータが格納されます。moov が mdat の後にあると、プレーヤーはインデックスの取得に追加の HTTP Range リクエストを必要とする場合があります。Range リクエストに対応していない場合は、インデックスを読み取る前にファイルをダウンロードする必要がある場合があります。
moov を mdat の前に移すと、順次ダウンロードの開始直後にインデックスを取得できます。ただし、再生は引き続きバッファリング、コーデック、プレーヤー、HTTP サーバーに依存します。これはファイルの配置を変更するもので、再生開始時間やシーク性能のベンチマークを示すものではありません。
FFmpeg の高速再生開始処理の利用
FFmpeg は qt-faststart ユーティリティと
-movflags +faststart マルチプレクサーオプションの両方を提供しています。後者は二回目の処理でインデックスをファイルの先頭に移動します。MOV/MP4 マルチプレクサーのドキュメントにあるとおり、フラグメント化された出力には適用できません。このチュートリアルでは、FFmpeg のコマンドラインプログラムでリマックスし、一時ストレージと出力の確定を Go で処理します。
Go 環境のセットアップ
ハードリンクをサポートする Linux ファイルシステム、書き込み可能な出力ディレクトリ、映像を含む有効なローカルの MP4 または MOV を用意します。入力で選択する映像と音声のコーデックは、MP4 マルチプレクサーと使用予定のプレーヤーの両方がサポートしている必要があります。テスト済みの組み合わせは H.264 映像と AAC 音声です。.mov 拡張子だけでは、コーデックの互換性は確認できません。シェルコマンドでは Bash と grep を使用します。
Goと、FFmpeg および FFprobeの両方を含むパッケージをインストールします。FFprobe は検査に使用する別の実行ファイルです。これらの例は、Linux 上の Go 1.26.8 と FFmpeg/FFprobe 9.0.1 でテストしています。これはテスト済みのバージョンであり、本質的な最小要件ではありません。それぞれのリリース系列でメンテナンスされているパッチリリースを使用してください。Go のリリースアーカイブには、テスト済みの Go バージョンがあります。モジュールの初期化やサードパーティーの Go 依存パッケージは不要です。
プログラムを保存する前に、三つのコマンドがすべて
PATH 上にあることを確認します。
go version && ffmpeg -version && ffprobe -version
Go による QuickTime ファイルの最適化
このプログラムを作業ディレクトリに faststart.go として保存します。出力先ディレクトリ内の非公開の一時ディレクトリにリマックスし、指定された出力パスにハードリンクを作成します。Go の os.Linkが、出力を確定する処理を担います。入力は置き換えずに読み取り、シンボリックリンクを含め、既存の出力は拒否します。
package main
import (
"context"
"fmt"
"os"
"os/exec"
"path/filepath"
"time"
)
func optimize(inputPath, outputPath string) error {
input, err := filepath.EvalSymlinks(inputPath)
if err != nil {
return err
}
input, err = filepath.Abs(input)
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")
}
parent, name := filepath.Split(outputPath)
if name == "" {
return fmt.Errorf("output must name a new file")
}
if parent == "" {
parent = "."
}
parent, err = filepath.EvalSymlinks(parent)
if err != nil {
return err
}
parent, err = filepath.Abs(parent)
if err != nil {
return err
}
output := filepath.Join(parent, name)
if _, err := os.Lstat(output); !os.IsNotExist(err) {
return fmt.Errorf("output must not exist")
}
temporary, err := os.MkdirTemp(parent, ".faststart-")
if err != nil {
return err
}
defer os.RemoveAll(temporary)
candidate := filepath.Join(temporary, "result.mp4")
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
cmd := exec.CommandContext(ctx, "ffmpeg", "-nostdin", "-n", "-i", input,
"-map", "0:v:0", "-map", "0:a?", "-c", "copy", "-movflags", "+faststart", candidate)
cmd.Stderr = os.Stderr
if err := cmd.Run(); err != nil {
return fmt.Errorf("fast-start conversion failed: %w", err)
}
if err := os.Link(candidate, output); err != nil {
return fmt.Errorf("cannot publish result without overwriting: %w", err)
}
return nil
}
func main() {
if len(os.Args) != 3 {
fmt.Fprintln(os.Stderr, "Usage: go run faststart.go <input.mp4> <new-output.mp4>")
os.Exit(1)
}
if err := optimize(os.Args[1], os.Args[2]); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
fmt.Println("Fast-start conversion complete")
}
input.mp4 をローカルの MP4 または MOV のパスに置き換えます。出力には、まだ存在しないファイル名を選びます。入力のコンテナーや出力先の拡張子にかかわらず、出力は MP4 です。
go run faststart.go input.mp4 output_optimized.mp4
成功すると、プログラムは Fast-start conversion complete と表示します。FFmpeg の診断メッセージはターミナルに出力されます。リマックスまたは出力の確定に失敗すると、ゼロ以外のステータスを返します。その終了経路では、Go が一時ディレクトリを削除します。報告された問題を修正し、新しい出力名で再試行してください。成功後に同じ入力を再度リマックスする場合も、別の出力名を選んでください。
ストリームは、意図的に次のように選択しています。
-map 0:v:0は、別の映像ストリームがデフォルトに指定されていても、最初の映像ストリームを選択します。-map 0:a?は、すべての音声ストリームを保持し、映像のみの入力も許容します。-c copyは、再エンコードせずにストリームコピーを行います。
字幕、データトラック、追加の映像ストリームは除外されます。リマックスではコンテナーのメタデータやパケットの表現が変わる場合があるため、出力ファイルは入力のバイト単位のコピーではありません。
結果の確認
新しいファイルの最上位ボックスを調べます。
(
set -o pipefail
ffprobe -v trace output_optimized.mp4 2>&1 |
grep -E "type:'(moov|mdat|moof)' parent:'root'"
)
行を順番に確認します。moov は
mdat より前にある必要があり、この非フラグメント形式の出力には moof ボックスがないはずです。トレースの書式は診断出力であり、安定したパーサー API ではありません。これはテスト済みの FFprobe バージョンで手動確認する手順です。リマックスが必要かを判断する前に、ファイル名を入力ファイル名に置き換えて配置を確認してください。すでに最適化済みの入力でも、このラッパーを実行すると新しいファイルが生成されます。
選択されたトラックを確認してから、その内容全体をデコードし、ヘッダーの調査では見逃す可能性のあるエラーを検出します。
ffprobe -v error -show_entries stream=codec_type,codec_name -of compact output_optimized.mp4 &&
ffmpeg -nostdin -v error -xerror -i output_optimized.mp4 -map 0:v:0 -map '0:a?' -f null -
映像ストリームは一つ、音声ストリームは入力と同じ数になるはずです。デコーダーはエラーなく実行できた場合、何も表示せず、ステータスゼロで終了します。使用している FFmpeg ビルドがゼロを返しても、エラーの診断メッセージがあれば確認失敗と判断してください。これらの確認でわかるのは配置と FFmpeg でのデコード可否であり、すべてのプレーヤーでの対応を保証するものではありません。配信前に、使用予定のプレーヤーで結果を試してください。
よくある問題とトラブルシューティング
- 互換性のないコーデック: ストリームコピーでは、非対応のコーデックを対応するコーデックに変換できません。MOV には、MP4 マルチプレクサーが拒否する音声や映像が含まれる場合があります。必要に応じて、別のワークフローで明示的にトランスコードしてください。このラッパーがエンコードにフォールバックすることはありません。
- 出力ディレクトリがない、またはハードリンク非対応: ハードリンクをサポートするファイルシステム上に、書き込み可能なディレクトリを作成するか選択してください。出力の確定に失敗した場合、このプログラムは指定された出力先を作成しません。その場所に別の主体が作成したファイルを置き換えることもありません。
- ディスク容量と処理時間: 元のファイルと、それにおおむね近いサイズの別の MP4 を保存できる空き容量を確保してください。高速再生開始処理では出力を再度処理し、ラッパーは FFmpeg の実行時間を五分に制限しています。タイムアウトした場合は、原因を解消するか、意図的にこの制限を調整する必要があります。
- 破損した入力: ストリームコピーはソースをデコードも修復もしません。リマックスの成功は、すべてのパケットが正常だったことの証明にはなりません。有効なメディアを入力に使い、デコードの診断メッセージを確認してください。
- プロセスの中断: 遅延実行されるクリーンアップは、Go の関数が戻るときに行われます。プロセスが突然終了すると、
.faststart-*ディレクトリが残る場合があります。削除する前に内容を確認してください。
高速再生開始処理は、単一のファイルをプログレッシブ配信向けに準備します。HLS と DASH はマニフェストとメディアセグメントを使用します。この MP4 の moov ボックスを移動しても、アダプティブストリーミング用のラダーは作成されません。その処理は、この非フラグメント形式の MP4 リマックスとは分けてください。
ほかのコンテナーオプションについては、FFmpeg マルチプレクサーリファレンスを参照してください。信頼できないアップロードを扱う場合は、隔離されたワーカーでメディア処理を実行してください。この例のタイムアウトだけでは、サンドボックスにはなりません。
