ffmpeg-cicd-runners

重要なガイドライン

Windows のファイルパスに関する要件

必須：Windows では常にファイルパスにバックスラッシュを使用してください

Windows で Edit または Write ツールを使用する場合、ファイルパスにはスラッシュ（/）ではなく、必ずバックスラッシュ（\）を使用してください。

---

クイックリファレンス

プラットフォーム	インストール方法	例
GitHub Actions	apt-get またはアクション	uses: FedericoCarboni/setup-ffmpeg@v3
GitLab CI	Docker イメージ	image: jrottenberg/ffmpeg:7.1-ubuntu2404
Jenkins	Docker コンテナ	docker { image 'jrottenberg/ffmpeg:7.1' }

タスク	YAML スニペット
FFmpeg をキャッシュする	path: /usr/local/bin/ffmpeg を指定して uses: actions/cache@v4
成果物をアップロードする	uses: actions/upload-artifact@v4
マトリックスビルド	strategy: { matrix: { format: [mp4, webm, mkv] } }

このスキルを使用する場面

CI/CD の動画処理パイプラインに使用します：

• GitHub Actions の FFmpeg ワークフロー
• GitLab CI/CD の動画トランスコーディング
• Jenkins の動画処理ジョブ
• ビルドを高速化するための FFmpeg のキャッシュ
• Windows ランナーの回避策

---

CI/CD パイプラインでの FFmpeg（2025）

GitHub Actions、GitLab CI、Jenkins などの CI/CD システムで FFmpeg を使用するための包括的なガイドです。

概要

一般的な CI/CD のユースケース

• 動画の検証：アップロードされた動画が要件を満たしているか確認します
• トランスコーディング：動画を複数の形式や解像度に変換します
• サムネイルの生成：プレビュー画像を作成します
• 音声の抽出：音声トラックを処理します
• 品質チェック：エンコードパラメーターを検証します
• テスト：動画処理パイプラインをテストします

主な考慮事項

• ビルド時間：FFmpeg のコンパイルには 20～40 分以上かかります
• ランナーのリソース：CPU／メモリの制限が処理に影響します
• キャッシュ：FFmpeg のビルドをキャッシュして実行を高速化します
• プラットフォームの違い：Windows ランナーには固有の問題があります
• 依存関係：コーデックライブラリのインストールが必要な場合があります

GitHub Actions

FFmpeg をインストールする（簡単な方法）

name: Video Processing

on: [push, pull_request]

jobs:
  process:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install FFmpeg
        run: |
          sudo apt-get update
          sudo apt-get install -y ffmpeg

      - name: Check FFmpeg version
        run: ffmpeg -version

      - name: Process video
        run: |
          ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4

特定のバージョンの FFmpeg をインストールする

jobs:
  process:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install FFmpeg 7.1
        run: |
          wget https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-n7.1-latest-linux64-gpl-7.1.tar.xz
          tar xf ffmpeg-n7.1-latest-linux64-gpl-7.1.tar.xz
          sudo cp ffmpeg-n7.1-latest-linux64-gpl-7.1/bin/* /usr/local/bin/
          ffmpeg -version

FedericoCarboni/setup-ffmpeg アクションを使用する

jobs:
  process:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup FFmpeg
        uses: FedericoCarboni/setup-ffmpeg@v3
        with:
          ffmpeg-version: release
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Process video
        run: ffmpeg -i input.mp4 output.webm

Docker ベースの FFmpeg

jobs:
  process:
    runs-on: ubuntu-latest
    container:
      image: jrottenberg/ffmpeg:7.1-ubuntu2404

    steps:
      - uses: actions/checkout@v4

      - name: Process video
        run: |
          ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4

FFmpeg ビルドをキャッシュする

jobs:
  build-ffmpeg:
    runs-on: ubuntu-latest

    steps:
      - name: Cache FFmpeg
        id: cache-ffmpeg
        uses: actions/cache@v4
        with:
          path: /usr/local/bin/ffmpeg
          key: ffmpeg-7.1-linux-${{ runner.arch }}

      - name: Build FFmpeg (if not cached)
        if: steps.cache-ffmpeg.outputs.cache-hit != 'true'
        run: |
          wget https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-n7.1-latest-linux64-gpl-7.1.tar.xz
          tar xf ffmpeg-n7.1-latest-linux64-gpl-7.1.tar.xz
          sudo cp ffmpeg-n7.1-latest-linux64-gpl-7.1/bin/ffmpeg /usr/local/bin/

マトリックスビルド（複数プラットフォーム）

jobs:
  process:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup FFmpeg
        uses: FedericoCarboni/setup-ffmpeg@v3

      - name: Process video
        run: ffmpeg -i input.mp4 -c:v libx264 output_${{ matrix.os }}.mp4
        shell: bash

Windows ランナー（既知の問題）

問題：Windows ランナーでは大幅に時間がかかります（vcpkg による FFmpeg のビルドでは最大 4 時間）。

解決策：

jobs:
  windows-ffmpeg:
    runs-on: windows-latest

    steps:
      - uses: actions/checkout@v4

      # Option 1: Use pre-built binaries (recommended)
      - name: Download FFmpeg
        run: |
          Invoke-WebRequest -Uri "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-n7.1-latest-win64-gpl-7.1.zip" -OutFile ffmpeg.zip
          Expand-Archive ffmpeg.zip -DestinationPath .
          $env:PATH = "$PWD\ffmpeg-n7.1-latest-win64-gpl-7.1\bin;$env:PATH"
          ffmpeg -version

      # Option 2: Use setup-ffmpeg action
      - name: Setup FFmpeg
        uses: FedericoCarboni/setup-ffmpeg@v3

      - name: Process video
        run: ffmpeg -i input.mp4 output.mp4

GPU 対応ランナー

jobs:
  gpu-process:
    runs-on: [self-hosted, gpu, linux]

    steps:
      - uses: actions/checkout@v4

      - name: Process with NVIDIA GPU
        run: |
          ffmpeg -hwaccel cuda -hwaccel_output_format cuda \
            -i input.mp4 \
            -c:v h264_nvenc \
            -preset p4 \
            output.mp4

成果物のアップロード

jobs:
  process:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install FFmpeg
        run: sudo apt-get update && sudo apt-get install -y ffmpeg

      - name: Generate outputs
        run: |
          mkdir -p outputs
          ffmpeg -i input.mp4 -vf scale=1920:1080 outputs/1080p.mp4
          ffmpeg -i input.mp4 -vf scale=1280:720 outputs/720p.mp4
          ffmpeg -i input.mp4 -ss 00:00:05 -vframes 1 outputs/thumbnail.jpg

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: video-outputs
          path: outputs/
          retention-days: 7

動画検証ワークフロー

name: Validate Videos

on:
  pull_request:
    paths:
      - '**.mp4'
      - '**.webm'
      - '**.mov'

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install FFmpeg
        run: sudo apt-get update && sudo apt-get install -y ffmpeg

      - name: Validate videos
        run: |
          for video in $(find . -name "*.mp4" -o -name "*.webm" -o -name "*.mov"); do
            echo "Validating: $video"

            # Check if valid
            if ! ffprobe -v error "$video"; then
              echo "Invalid video: $video"
              exit 1
            fi

            # Get info
            duration=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$video")
            resolution=$(ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 "$video")

            echo "Duration: ${duration}s"
            echo "Resolution: $resolution"

            # Validate constraints
            if (( $(echo "$duration > 300" | bc -l) )); then
              echo "Video too long: $video ($duration seconds)"
              exit 1
            fi
          done

GitLab CI

基本的なパイプライン

# .gitlab-ci.yml

stages:
  - process

video-process:
  stage: process
  image: jrottenberg/ffmpeg:7.1-ubuntu2404
  script:
    - ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4
  artifacts:
    paths:
      - output.mp4
    expire_in: 1 week

複数形式へのトランスコーディング

transcode:
  stage: process
  image: jrottenberg/ffmpeg:7.1-ubuntu2404
  script:
    - mkdir -p outputs
    - ffmpeg -i input.mp4 -c:v libx264 -crf 23 outputs/h264.mp4
    - ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 outputs/vp9.webm
    - ffmpeg -i input.mp4 -vf scale=1280:720 outputs/720p.mp4
  artifacts:
    paths:
      - outputs/

並列処理

.process-template: &process-template
  stage: process
  image: jrottenberg/ffmpeg:7.1-ubuntu2404

process-1080p:
  <<: *process-template
  script:
    - ffmpeg -i input.mp4 -vf scale=1920:1080 output_1080p.mp4
  artifacts:
    paths:
      - output_1080p.mp4

process-720p:
  <<: *process-template
  script:
    - ffmpeg -i input.mp4 -vf scale=1280:720 output_720p.mp4
  artifacts:
    paths:
      - output_720p.mp4

process-480p:
  <<: *process-template
  script:
    - ffmpeg -i input.mp4 -vf scale=854:480 output_480p.mp4
  artifacts:
    paths:
      - output_480p.mp4

GPU ランナー（GitLab）

gpu-transcode:
  stage: process
  tags:
    - gpu
    - linux
  image: jrottenberg/ffmpeg:7.1-nvidia2404
  script:
    - ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc output.mp4

Jenkins

宣言型パイプライン

pipeline {
    agent {
        docker {
            image 'jrottenberg/ffmpeg:7.1-ubuntu2404'
            args '-v /data/videos:/videos'
        }
    }

    stages {
        stage('Process') {
            steps {
                sh '''
                    ffmpeg -i /videos/input.mp4 \
                           -c:v libx264 -crf 23 \
                           -c:a aac -b:a 128k \
                           /videos/output.mp4
                '''
            }
        }
    }

    post {
        success {
            archiveArtifacts artifacts: '/videos/output.mp4'
        }
    }
}

並列トランスコーディング

pipeline {
    agent any

    stages {
        stage('Transcode') {
            parallel {
                stage('1080p') {
                    agent {
                        docker { image 'jrottenberg/ffmpeg:7.1-ubuntu2404' }
                    }
                    steps {
                        sh 'ffmpeg -i input.mp4 -vf scale=1920:1080 output_1080p.mp4'
                    }
                }
                stage('720p') {
                    agent {
                        docker { image 'jrottenberg/ffmpeg:7.1-ubuntu2404' }
                    }
                    steps {
                        sh 'ffmpeg -i input.mp4 -vf scale=1280:720 output_720p.mp4'
                    }
                }
            }
        }
    }
}

BtbN/FFmpeg-Builds

概要

BtbN/FFmpeg-Builds は、複数のプラットフォーム向けにビルド済みの静的バイナリを提供する、最も人気のある FFmpeg 自動ビルドシステムです。

ビルドマトリックス

ターゲット	バリアント	機能
win64	gpl, lgpl, gpl-shared, lgpl-shared	Windows 64 ビット全機能
winarm64	gpl, lgpl	Windows ARM64
linux64	gpl, lgpl, gpl-shared, lgpl-shared	Linux 64 ビット全機能
linuxarm64	gpl, lgpl	Linux ARM64

CI でダウンロードする

- name: Download FFmpeg
  run: |
    # Latest release
    wget https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-n7.1-latest-linux64-gpl-7.1.tar.xz

    # Specific version
    wget https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2025-01-15-12-50/ffmpeg-n7.1-latest-linux64-gpl-7.1.tar.xz

パフォーマンスの最適化

並列処理

# Process multiple files in parallel
jobs:
  process:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        video: [video1.mp4, video2.mp4, video3.mp4]
      max-parallel: 3

    steps:
      - name: Process ${{ matrix.video }}
        run: ffmpeg -i ${{ matrix.video }} -c:v libx264 output_${{ matrix.video }}

リソースを最適化したエンコード

- name: Optimized encoding
  run: |
    # Use appropriate threads for runner
    THREADS=$(nproc)

    ffmpeg -i input.mp4 \
      -threads $THREADS \
      -c:v libx264 \
      -preset fast \
      -crf 23 \
      output.mp4

依存関係のキャッシュ

- name: Cache FFmpeg and libraries
  uses: actions/cache@v4
  with:
    path: |
      ~/.local/bin/ffmpeg
      ~/.local/lib/
    key: ffmpeg-${{ runner.os }}-${{ hashFiles('ffmpeg-version.txt') }}

トラブルシューティング

よくある問題

「ffmpeg: command not found」

# Ensure FFmpeg is in PATH
- name: Add FFmpeg to PATH
  run: echo "/path/to/ffmpeg/bin" >> $GITHUB_PATH

「Cannot allocate memory」

# Reduce memory usage
- name: Process with low memory
  run: |
    ffmpeg -i input.mp4 \
      -threads 2 \
      -preset ultrafast \
      -vf scale=1280:720 \
      output.mp4

Windows のパスの問題

# Use forward slashes on Windows
- name: Process on Windows
  run: ffmpeg -i "./input.mp4" "./output.mp4"
  shell: bash

デバッグ

- name: Debug FFmpeg
  run: |
    # Check FFmpeg capabilities
    ffmpeg -version
    ffmpeg -encoders
    ffmpeg -decoders
    ffmpeg -formats

    # Verbose processing
    ffmpeg -v verbose -i input.mp4 -c:v libx264 output.mp4 2>&1 | tee ffmpeg.log

- name: Upload logs
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: ffmpeg-logs
    path: ffmpeg.log

ベストプラクティス

1. ビルド済みバイナリを使用する - CI で FFmpeg をコンパイルするのは避けてください（時間がかかります）
2. FFmpeg のインストールをキャッシュする - セットアップ時間を短縮できます
3. Docker コンテナを使用する - FFmpeg 環境を統一できます
4. ランナーのリソースに合わせて最適化する - スレッド数やプリセットを、利用可能な CPU に合わせてください
5. 入力を検証する - 処理前に動画ファイルを確認してください
6. アーティファクトをアップロードする - 出力を保存してレビューできるようにします
7. マトリックスビルドを使用する - 複数フォーマットへのトランスコードを並列化できます
8. ビルド時間を監視する - Windows ランナーは処理が遅くなります
9. バージョンを固定する - 再現性を確保するため、latest は避けてください
10. -preset fast/ultrafast を使用する - CI でのエンコードを高速化できます

このガイドでは、CI/CD における FFmpeg のパターンを紹介します。CI でハードウェアアクセラレーションを使用する場合は、セルフホストの GPU ランナーをご検討ください。