# 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