# Runs on every pull request and on pushes to main (workflow_dispatch stays for manual runs).
# The OSes give several FFmpeg majors: Ubuntu 24.04 apt = 6.1, Ubuntu 26.04 apt = 8.0.1, Homebrew = 8.x,
# gyan.dev on Windows = 9.x (plus the 7.1 Debian job below).
# The "ffmpeg listings" artifact holds each runner's `ffmpeg -filters / -encoders / -bsfs` output
# and `doctor --json`, so a parser regression on a new FFmpeg layout is visible in the log and the
# capture can be copied into tests/fixtures/.
name: tests
on:
  workflow_dispatch:
  pull_request:
  push:
    branches: [main]

# A push while this is still running on the same PR/branch makes the old run pointless -- its
# result is about to be superseded anyway. Cancelling it saves real money here: this matrix
# includes macOS (10x the Ubuntu minute cost) and Windows (2x), so a few stacked pushes without
# this can burn many times the minutes of the one push that actually mattered.
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true


# the jobs only read the repository and upload artifacts; the token gets nothing else
permissions:
  contents: read

jobs:
  test:
    # a part takes 10 to 25 minutes; a filter graph that never ends on one FFmpeg (#514) ran
    # until the six-hour default
    timeout-minutes: 75
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python: ["3.10"]
        # the suite on three machines at once (tests/run_parallel.py --part): about a third of the
        # wall time, and the standard runners cost nothing on a public repository
        part: [1, 2, 3]
        # The docs promise Python 3.10+ (3.0.0 removed 3.9); 3.10 is the floor and every OS runs it. One extra Linux
        # job on the newest CPython proves the ceiling too (3.11-3.12 sit between the two; a
        # stdlib-only codebase that passes on both ends is very unlikely to break in the
        # middle). Linux only: it bills at 1x, macOS at 10x. See #146.
        include:
          - {os: ubuntu-latest, python: "3.13", part: 1}
          - {os: ubuntu-latest, python: "3.13", part: 2}
          - {os: ubuntu-latest, python: "3.13", part: 3}
    # ubuntu-latest is Ubuntu 26.04, whose setup-python builds start above 3.10; keep the floor on
    # the newest image that has it (24.04, which also gives apt's FFmpeg 6.1, the FFmpeg floor)
    runs-on: ${{ matrix.python == '3.10' && startsWith(matrix.os, 'ubuntu') && 'ubuntu-24.04' || matrix.os }}
    name: test (${{ matrix.os }}, py${{ matrix.python }}, ${{ matrix.part }}/3)
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          # Full history (not the default shallow depth-1 clone): test_contract.py's
          # test_changelog_mentions_every_closed_issue_since_last_tag walks git log back to the
          # latest tag to check CHANGELOG.md against "Closes #N" in commit bodies -- a shallow
          # clone would make that check silently a no-op (no tag reachable to diff against).
          fetch-depth: 0
      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: ${{ matrix.python }}
      - name: Install ffmpeg (Linux)
        if: runner.os == 'Linux'
        run: sudo apt-get update && sudo apt-get install -y ffmpeg fonts-dejavu-core
      - name: Install ffmpeg (macOS)
        if: runner.os == 'macOS'
        # Homebrew's `ffmpeg` formula no longer links libass / freetype / harfbuzz / zimg, so it has no
        # subtitles, ass, drawtext or zscale filter; `ffmpeg-full` does. It is keg-only: put it on PATH.
        run: |
          brew install ffmpeg-full
          echo "$(brew --prefix ffmpeg-full)/bin" >> "$GITHUB_PATH"
      - name: Install ffmpeg (Windows)
        if: runner.os == 'Windows'
        # The Chocolatey community feed (community.chocolatey.org) intermittently 503s under load
        # -- seen repeatedly failing CI with nothing wrong in the PR's own diff. Retry with backoff
        # instead of failing the whole job on what's usually a transient upstream blip.
        shell: pwsh
        run: |
          # A zero exit from choco is not proof ffmpeg is usable: seen once returning 0 after
          # ~6 s with nothing on PATH (the next step's `ffmpeg -version` then failed). So the
          # success condition is "ffmpeg actually runs", and a phantom install is retried with
          # --force rather than trusted.
          $attempts = 5
          for ($i = 1; $i -le $attempts; $i++) {
            $force = if ($i -gt 1) { '--force' } else { '' }
            choco install ffmpeg -y --no-progress $force
            $code = $LASTEXITCODE
            if ($code -eq 0 -and (Get-Command ffmpeg -ErrorAction SilentlyContinue) -and (Get-Command ffprobe -ErrorAction SilentlyContinue)) {
              ffmpeg -version | Select-Object -First 1
              break
            }
            if ($code -eq 0) { Write-Host "choco reported success but ffmpeg/ffprobe are not on PATH (attempt $i/$attempts)"; $code = 1 }
            if ($i -eq $attempts) { exit $code }
            $delay = 15 * $i
            Write-Host "choco install ffmpeg failed (attempt $i/$attempts, exit $code) -- retrying in ${delay}s"
            Start-Sleep -Seconds $delay
          }
      - name: ffmpeg version, listings and doctor
        shell: bash
        run: |
          mkdir -p listings
          ffmpeg -version | head -1 | tee listings/version.txt
          ffmpeg -hide_banner -filters > listings/ffmpeg_filters.txt
          ffmpeg -hide_banner -encoders > listings/ffmpeg_encoders.txt
          ffmpeg -hide_banner -bsfs > listings/ffmpeg_bsfs.txt
          head -9 listings/ffmpeg_filters.txt
          # doctor exits 1 when a required capability is missing on this build (e.g. Homebrew without libass);
          # that is reported, not hidden, but the listings must still be uploaded
          python scripts/_contract.py doctor --json > listings/doctor.json || echo "doctor exit $?"
          cat listings/doctor.json
      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        if: always()
        with:
          name: ffmpeg-listings-${{ matrix.os }}-py${{ matrix.python }}-${{ matrix.part }}
          path: listings/
      # this machine's third of test_all.py's modules and test_contract, sharded across its cores.
      # A handful of test_contract tests drive the tools through POSIX shell shims (fake ffmpeg on
      # PATH) and are skipIf'd on Windows; everything else runs on all three OSes.
      - run: python tests/run_parallel.py --part ${{ matrix.part }}/3
      - run: node bin/install.js
        if: matrix.part == 1

  # The docs promise FFmpeg 6.1+ (3.0.0 removed 5.x); the matrix above runs 6.1 (apt on Ubuntu
  # 24.04), 8.x (Homebrew) and 9.x (gyan.dev). This Linux-only (1x cost) job pins 7.1, which
  # needs a different base image altogether. See #146.
  #
  # 7.1.x: no maintained static build carries drawtext any more (John Van Sickle's 7.0.2 lacks
  # the filter; BtbN dropped 7.x), but Debian trixie's apt ffmpeg is 7.1 with libass, freetype
  # and zimg, so this job runs inside a trixie container. It also happens to give Python 3.13.
  test-ffmpeg-7:
    name: test (debian-trixie container, py3.13, ffmpeg 7.1 apt, ${{ matrix.part }}/3)
    timeout-minutes: 75
    strategy:
      fail-fast: false
      matrix:
        part: [1, 2, 3]
    runs-on: ubuntu-latest
    container: debian:trixie
    steps:
      - name: Install ffmpeg 7.1, Python, fonts, git and node
        run: |
          apt-get update -qq
          DEBIAN_FRONTEND=noninteractive apt-get install -y -qq ffmpeg python3 fonts-dejavu-core git nodejs ca-certificates
          git config --global --add safe.directory "$GITHUB_WORKSPACE"
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 0
      - name: ffmpeg version, listings and doctor
        run: |
          mkdir -p listings
          ffmpeg -version | head -1 | tee listings/version.txt
          python3 --version
          ffmpeg -hide_banner -filters > listings/ffmpeg_filters.txt
          ffmpeg -hide_banner -encoders > listings/ffmpeg_encoders.txt
          ffmpeg -hide_banner -bsfs > listings/ffmpeg_bsfs.txt
          python3 scripts/_contract.py doctor --json > listings/doctor.json || echo "doctor exit $?"
          cat listings/doctor.json
      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        if: always()
        with:
          name: ffmpeg-listings-debian-trixie-ffmpeg7-${{ matrix.part }}
          path: listings/
      - run: python3 tests/run_parallel.py --part ${{ matrix.part }}/3   # this machine's third, test_contract included