Zenn
👀

YouTube作業BGM動画作成サービスの舞台裏〜第8章 🎬 ffmpegエラー処理完全ガイド - サーバーレス動画生成の落とし穴と対策

に公開
FFmpeg
CloudWatch
AWS Lambda
logger
trace
tech

こんにちは、AWS Lambda上でffmpegを使って動画を生成しようとして頭を抱えているあなた！
このガイドはあなたのためにあります。「処理中にエラーが発生しました」という恐怖のメッセージとはもうサヨナラしましょう！

💡 重要ポイント: このガイドでは様々な関数例を紹介していますが、共通しているのは 常に logger と exc_info=True を使用してスタックトレースを記録している点です。これはエラー処理の鉄則です！

🔍 なぜffmpegの処理エラーが起きるの？

ffmpegは素晴らしいツールですが、時折気難しい性格を見せます。ちょっとした理由でふてくされて仕事を放棄することも...

エラーの原因は大きく分けて「開発者側の問題」と「ユーザー起点の問題」があります。ここではまず一般的な原因を紹介し、後でユーザー起点の問題に特化した対策を説明します。

1. 入力ファイルの問題

  • 破損したファイル: 「この動画、途中で切れてるんですけど〜」とffmpegが嘆いています
  • サポートされないコーデック: 「このMP3、中身が全然MP3じゃないじゃん！騙された！」とffmpegが怒っています
  • 不正なメタデータ: 「このファイルのメタデータ、意味不明すぎて頭痛がする...」とffmpegが頭を抱えています

2. リソース制約

  • Lambda実行時間の制限: 「15分経ったからもう帰るね〜」とLambdaが言います
  • メモリ不足: 「もう...記憶力の限界...」とLambdaが倒れます
  • ディスク容量不足: 「/tmpディレクトリが満タンでお腹いっぱい...もう食べられない」とLambdaが言い訳します

3. ffmpegコマンドの問題

  • 無効なパラメータ: 「その指示、意味わからないんですけど？」とffmpegが首をかしげます
  • コーデック互換性の問題: 「その入力と出力、相性最悪なんですけど...」とffmpegがため息をつきます

🕵️ エラー検知方法 - ffmpegの悲鳴を聞き逃すな！

1. プロセス終了コードのチェック

try:
    result = subprocess.run([
        'ffmpeg',
        '-i', input_file,
        # その他のオプション
        output_file
    ], check=True, capture_output=True, text=True)
    # 無事に終了！🎉
except subprocess.CalledProcessError as e:
    # ffmpegが「ダメだった〜」と叫んでいる
    error_message = e.stderr
    logger.error(f"ffmpeg error: {error_message}")
    raise Exception(f"動画処理に失敗しました: {error_message[:200]}...")

2. 出力ファイルの検証 - 「本当に生きてる？」チェック

def verify_generated_file(file_path):
    # そもそもファイルは存在する？
    if not os.path.exists(file_path):
        raise Exception("出力ファイルが生成されませんでした...生まれる前に消えちゃった...")
    
    # 赤ちゃんみたいに小さすぎないか確認
    file_size = os.path.getsize(file_path)
    if file_size < 1024:  # 1KB未満は疑わしい
        raise Exception(f"生成されたファイルが異常に小さいです ({file_size} bytes)...これって本当に動画？")
    
    # 動画として再生できる？
    if file_path.endswith('.mp4'):
        try:
            result = subprocess.run([
                'ffprobe',
                '-v', 'error',
                '-show_entries', 'format=duration',
                '-of', 'default=noprint_wrappers=1:nokey=1',
                file_path
            ], capture_output=True, text=True, check=True)
            
            duration = float(result.stdout.strip())
            if duration < 1.0:  # 1秒未満の動画って...
                raise Exception(f"生成された動画の長さが異常です ({duration} 秒)...一瞬すぎない？")
        except Exception as e:
            raise Exception(f"動画ファイルの検証に失敗しました: {str(e)}")

🌩️ CloudWatchで監視する - 雲の上から見守る

「AWS CloudWatch Logsにエラー詳細を記録して、CloudWatch Alarmsでエラー率を監視する」という素晴らしいアイデア！でも、これどうやって設定するの？

CloudWatch Logsへのログ記録 - ffmpegの悲鳴を雲に届ける

import logging

# ロガーの設定 - これで雲の上まで声が届く
logger = logging.getLogger()
logger.setLevel(logging.INFO)

def lambda_handler(event, context):
    try:
        # 元気な挨拶
        logger.info("やあ！処理を開始するよ〜")
        
        # ここで何か素晴らしいことをする...
        
        # 何か問題が...
        if something_wrong:
            logger.error("エラーが起きちゃった！助けて！", exc_info=True)
    except Exception as e:
        # 大惨事！詳細なレポートを送信
        logger.error(f"想定外の事態発生: {str(e)}", exc_info=True)
        raise

ここで exc_info=True を指定すると、例外のスタックトレースも記録されます。これは何かというと...

🔎 スタックトレースって何？ - エラーの「現場写真」

スタックトレースとは、プログラムでエラーが起きたときの「現場の状況証拠」です。

中学生向けに例えると:

あなたは学校で複雑な数学の問題を解いています。問題は何段階もの計算が必要です:

  1. まず、数字を掛け算する
  2. 次に、その結果に別の数を足す
  3. 最後に、その結果を別の数で割る

もし最後のステップで「0で割ろうとした」というエラーが起きたとします。

あなたが先生に「計算でエラーが起きました」とだけ言っても、先生は「で？どこで何が起きたの？」となりますよね。でも、あなたが「最初に12×3をして36になって、次に36+4をして40になって、最後に40÷0をしようとしたときにエラーになりました」と説明すれば、先生は「あ、0で割ろうとしたのが問題ね」とすぐにわかります。

スタックトレースはこの「計算過程の全記録」なのです！

exc_info=True vs exc_info=False - 違いを見てみよう

exc_info=True の場合 （詳細モード）:

ERROR: 予期せぬエラー: division by zero
Traceback (most recent call last):
  File "main.py", line 10, in <module>
    result = calculate_total()
  File "math_utils.py", line 25, in calculate_total
    return divide_numbers(40, 0)
  File "math_utils.py", line 5, in divide_numbers
    return a / b
ZeroDivisionError: division by zero

exc_info=False の場合 （シンプルモード）:

ERROR: 予期せぬエラー: division by zero

「0で割ろうとした」というエラーメッセージは同じですが、最初のケースでは「どこで」「どのように」そのエラーが発生したかがわかります。これは「犯人の顔写真と指紋と足跡」がセットになっているようなものです！

🏠 /tmpディレクトリは誰と共有するの？ - プライベートな作業スペース

AWS Lambdaの/tmpディレクトリは、あなただけの専用作業スペースです！他のユーザーとシェアすることはありません。

これは、各Lambda関数が独自のコンテナで実行されるためです。あなたの関数が実行されるコンテナと、他のユーザーの関数が実行されるコンテナは完全に分離されています。

つまり、/tmpディレクトリは「あなただけの個室」のようなものです。他の人が同時に別の「個室」で作業していても、お互いの作業は干渉しません。

ただし、注意点が2つ:

  1. 各「個室」のサイズは512MBまでという制限があります
  2. 同じ「個室」が再利用されることがあるので、掃除（ファイル削除）はきちんとしましょう

📊 MP3ファイルのサイズ - どれくらい大きいの？

MP3ファイルのサイズは音質と長さで決まります:

  • 普通の音質（128 kbps）: 1分あたり約1MB
  • 高音質（320 kbps）: 1分あたり約2.4MB

作業用BGMは5分〜60分くらいが一般的なので、ファイルサイズは5MB〜150MB程度になることが多いです。

設計書では音声ファイルのアップロード上限が50MBと設定されています。これは中品質の20-30分程度のMP3ファイルなら問題ないサイズです。

🏁 まとめ - ffmpegエラーと仲良くなろう

ffmpegのエラー処理は難しく見えますが、適切な対策を講じれば怖くありません。むしろ、エラーは「何かがうまくいっていないよ」という親切なメッセージと考えましょう。

エラー検知、ログ記録、そして適切な対応策を組み合わせれば、安定した動画生成サービスを構築できます。そして、何か問題が発生したときも、CloudWatchのログとアラームがあなたに知らせてくれます。

エラー処理は面倒ですが、ユーザーに「処理中にエラーが発生しました」という恐怖のメッセージを見せないためには必要な投資です。ユーザーは何が起きているのかを知りたいものです...そして開発者である私たちはなおさらですね！

👥 ユーザー起点のコーデック問題 - ユーザーが送ってくる奇妙なファイルたち

開発側でコーデックの問題を事前に対処できても、ユーザーからアップロードされるファイルには様々な「サプライズ」が待っています。ここでは、ユーザー側から発生する代表的なコーデック問題を紹介します。

1. 非標準または珍しいコーデック

ユーザーは時に珍しいコーデックを使ってファイルを作成します。例えば：

  • 「いつも使っている録音アプリで作成したMP3をアップロードしたのに失敗します！」
    → そのアプリは拡張子はMP3でも、実際には特殊なコーデックを使用していた

2. 誤ったファイル拡張子

よくあるのが手動でファイル拡張子を変更するケース：

  • エラーログ: Unknown decoder 'mp3' for input stream
    → 調査すると、ユーザーがM4AファイルをMP3としてリネームしていた

3. 破損したファイル

ネットワーク問題による不完全なダウンロードからのアップロード：

  • ffmpegエラー: [mp3 @ 0x7f8a1c001b00] Invalid data found when processing input
    → 不安定なネットワークでダウンロードした不完全なファイル

4. 実験的なエンコード設定

ユーザーが最新の技術でエンコードしたファイル：

  • エラー: This file contains features which are not implemented yet
    → 新しすぎるエンコーダーで作成されたファイル

5. 著作権保護付きメディア

DRM保護されたコンテンツ：

  • エラー: Encrypted stream detected but decryption library not found
    → 著作権保護されたオーディオブックからの抜粋

ユーザーファイル対策の実装例

最も効果的な対策は、入力を標準化することです：

def standardize_audio(input_file, output_file):
    """どんな入力でも標準的なMP3に変換するレスキュー関数"""
    try:
        # 標準的な設定でトランスコード
        result = subprocess.run([
            'ffmpeg',
            '-i', input_file,
            '-c:a', 'libmp3lame',
            '-q:a', '4',
            '-ar', '44100',
            output_file
        ], check=True, capture_output=True)
        logger.info("音声ファイルの標準化に成功しました")
        return True, output_file
    except subprocess.CalledProcessError as e:
        # エラーログを記録（スタックトレース付き！）
        logger.error(f"音声トランスコードに失敗: {e.stderr}", exc_info=True)
        
        # フォールバック: より基本的な設定でリトライ
        try:
            subprocess.run([
                'ffmpeg',
                '-i', input_file,
                '-c:a', 'libmp3lame',
                output_file
            ], check=True)
            logger.info("基本設定でのトランスコードに成功しました")
            return True, output_file
        except subprocess.CalledProcessError as e2:
            # 再度エラーログを記録（スタックトレース付き！）
            logger.error(f"基本設定でのトランスコードにも失敗: {e2.stderr}", exc_info=True)
            return False, f"トランスコード失敗: {e2.stderr}"

お気づきの通り、この関数でも logger.error(..., exc_info=True) を使用して詳細なスタックトレースを記録しています。これにより、問題が発生した際に具体的な原因を特定しやすくなります。

📝 まとめ - エラーログは開発者の親友

ffmpegを使った動画・音声処理で最も重要なのは、適切なエラーハンドリングとロギングです。このガイドで紹介したすべての関数に共通するのは、logger と exc_info=True を使ってスタックトレースを記録している点です。

これは偶然ではありません。実際の開発環境では、詳細なエラーログがあるかないかで、問題解決にかかる時間が劇的に変わります。特にサーバーレス環境ではデバッグが難しいため、ロギングの重要性はさらに高まります。

エラーが発生した際に「何が」「どこで」「なぜ」起きたのかを知ることができれば、修正も迅速に行えます。そして、ユーザー体験を損なうことなく、安定したサービスを提供できるのです。

「バグを見つけるのに1日かかることもあるが、それを防ぐコードを書くのには1分しかかからない」 - 賢いプログラマーの格言

「詳細なエラーログは、深夜のデバッグセッションを朝食前の簡単な修正に変える魔法だ」 - 疲れた開発者の本音

Discussion