# shaka-project/static-ffmpeg-binaries architecture

> Architecture diagram of the GitHub repository shaka-project/static-ffmpeg-binaries, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shaka-project/static-ffmpeg-binaries
- Repository: https://github.com/shaka-project/static-ffmpeg-binaries

## Overview

1. This repository is a release-engineering project for producing and publishing prebuilt, static FFmpeg binaries. It is not an application runtime; the main “product” is the generated FFmpeg/ffprobe binaries attached to GitHub Releases.

2. The core build pipeline is scripted in shell and centered around `build.sh` plus the numbered scripts in `build-scripts/`. Those scripts represent the dependency chain in build order: packages/tooling setup, then codec/library dependencies (`libvpx`, `svt-av1`, `x264`, `x265`, `lame`, `opus`, `mbedtls`), then the final FFmpeg build, and finally a static-link verification step.

3. `versions.txt` is the primary configuration input for the build. It defines the source versions that the workflow and scripts use when compiling FFmpeg and its dependencies. `get-version.sh` reads version information for tagging/release naming, so versioning is part of the build control plane.

4. The repository is designed around a GitHub Actions CI/CD boundary. The workflows under `.github/workflows/` split responsibilities: `release.yaml` appears to drive the full release build and publication flow, `build.yaml` and `test.yaml` handle CI validation, while `settings.yaml`, `sync-labels.yaml`, and `update-issues.yaml` support repository automation and issue hygiene.

5. The build matrix is explicitly modeled in `build-matrix.json`, which likely enumerates the supported OS/CPU combinations. This is what makes the output a multi-platform artifact set rather than a single binary package.

6. Platform detection and environment handling are part of the build system. `is-alpine.sh` suggests special-case logic for Alpine Linux, while the README’s local-build instructions show that the scripts expect runner-style environment variables such as `RUNNER_OS`, `SUDO`, and `GITHUB_ENV`.

7. There is a clear source-to-artifact flow: upstream source archives are fetched, codec libraries are compiled statically, FFmpeg is linked against them, and the resulting binaries are placed under a `build/` output directory. The README specifically calls out `build/ffmpeg/ffmpeg` and `build/ffmpeg/ffprobe` as the final outputs.

8. Reproducibility and tamper detection are part of the architecture. The workflow records MD5 sums of the produced binaries, and those sums are included both in workflow logs and in release notes. This creates three consistency points: build logs, published release metadata, and the downloadable artifacts.

9. The repository also contains a small patching layer, such as `ffmpeg-nvenc-jammy.patch`, which indicates that the FFmpeg source is occasionally adapted for specific platform/toolchain combinations before compilation.

10. The release process is tag-driven. A tag of the form `FFMPEG_VERSION-WORKFLOW_RELEASE_NUMBER` triggers a release build, and increasing the suffix allows dependency or build-configuration changes without changing the upstream FFmpeg version. That means tags are both version markers and release orchestration inputs.

11. The security posture is intentionally minimal in terms of third-party automation. The README notes only limited use of external GitHub Actions, with `mxschmitt/action-tmate` reserved for failed builds and only when debug is enabled. This reflects an architecture that prefers local shell scripts and repository-owned workflow logic over opaque build actions.

12. For an architecture diagram, the important boundaries are: upstream source inputs and version metadata on one side; GitHub Actions orchestration in the middle; the shell-based dependency build pipeline and FFmpeg compilation as the processing core; and GitHub Releases plus checksum metadata as the distribution/output layer.

Main entry points: [`build.sh`](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build.sh) (build.sh), [`.github/workflows/release.yaml`](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/release.yaml) (release workflow), [`build-scripts/90-ffmpeg.sh`](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/90-ffmpeg.sh) (FFmpeg build), [`versions.txt`](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/versions.txt) (versions.txt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs & config"]
  node_versions["versions.txt<br/>version config<br/>[versions.txt]"]
  node_version_script["get-version.sh<br/>version helper<br/>[get-version.sh]"]
  node_matrix["build matrix<br/>platform matrix<br/>[build-matrix.json]"]
  node_patch["NVENC patch<br/>source patch"]
end

subgraph group_ci["GitHub Actions"]
  node_release_wf["release workflow<br/>release CI<br/>[release.yaml]"]
  node_build_wf["build workflow<br/>validation CI<br/>[build.yaml]"]
  node_test_wf["test workflow<br/>validation CI<br/>[test.yaml]"]
  node_automation_wf["repo automation<br/>ops CI<br/>[settings.yaml]"]
end

subgraph group_build["Build pipeline"]
  node_build_sh["build.sh<br/>orchestrator<br/>[build.sh]"]
  node_packages["packages<br/>setup stage<br/>[00-packages.sh]"]
  node_libvpx["libvpx<br/>codec dep<br/>[01-libvpx.sh]"]
  node_svtav1["svt-av1<br/>codec dep<br/>[02-svt-av1.sh]"]
  node_media_deps["x264 x265 lame opus mbedtls<br/>media deps"]
  node_ffmpeg_build["FFmpeg build<br/>compile stage<br/>[90-ffmpeg.sh]"]
  node_static_check["static check<br/>verify stage<br/>[99-check-static.sh]"]
  node_alpine["Alpine detect<br/>env helper<br/>[is-alpine.sh]"]
end

subgraph group_release["Artifacts & release"]
  node_outputs[("FFmpeg artifacts<br/>release artifacts")]
  node_checksums["MD5 sums<br/>integrity metadata"]
  node_github_release[("GitHub Releases<br/>distribution")]
end

node_versions -->|"pins versions"| node_build_sh
node_versions -->|"drives release"| node_release_wf
node_version_script -->|"names tags"| node_release_wf
node_matrix -->|"selects platforms"| node_build_wf
node_matrix -->|"selects platforms"| node_release_wf
node_build_wf -->|"runs"| node_build_sh
node_test_wf -->|"validates"| node_build_sh
node_release_wf -->|"orchestrates"| node_build_sh
node_automation_wf -->|"maintains"| node_github_release
node_build_sh -->|"starts"| node_packages
node_build_sh -->|"detects"| node_alpine
node_packages -->|"prepares"| node_libvpx
node_libvpx -->|"feeds"| node_svtav1
node_svtav1 -->|"feeds"| node_media_deps
node_media_deps -->|"enables"| node_ffmpeg_build
node_patch -->|"modifies"| node_ffmpeg_build
node_ffmpeg_build -->|"verifies"| node_static_check
node_static_check -->|"produces"| node_outputs
node_outputs -->|"hashes"| node_checksums
node_checksums -->|"publishes"| node_github_release
node_outputs -->|"attaches"| node_github_release

click node_versions "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/versions.txt"
click node_version_script "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/get-version.sh"
click node_matrix "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-matrix.json"
click node_patch "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/ffmpeg-nvenc-jammy.patch"
click node_release_wf "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/release.yaml"
click node_build_wf "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/build.yaml"
click node_test_wf "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/test.yaml"
click node_automation_wf "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/settings.yaml"
click node_build_sh "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build.sh"
click node_packages "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/00-packages.sh"
click node_libvpx "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/01-libvpx.sh"
click node_svtav1 "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/02-svt-av1.sh"
click node_ffmpeg_build "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/90-ffmpeg.sh"
click node_static_check "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/99-check-static.sh"
click node_alpine "https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/is-alpine.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_versions,node_version_script,node_matrix,node_patch toneBlue
class node_release_wf,node_build_wf,node_test_wf,node_automation_wf toneAmber
class node_build_sh,node_packages,node_libvpx,node_svtav1,node_media_deps,node_ffmpeg_build,node_static_check,node_alpine toneMint
class node_outputs,node_checksums,node_github_release toneRose
```

## Components

### Inputs & config

Versioning, matrix, and patch inputs that shape the build.

- [versions.txt](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/versions.txt): version config · Primary source-version control file for FFmpeg and its dependencies. · `versions.txt`
- [get-version.sh](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/get-version.sh): version helper · Derives version strings for tagging and release naming. · `get-version.sh`
- [build matrix](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-matrix.json): platform matrix · Enumerates supported OS and CPU combinations for multi-platform builds. · `build-matrix.json`
- [NVENC patch](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/ffmpeg-nvenc-jammy.patch): source patch · Targeted FFmpeg source adjustment for specific platform or toolchain cases. · `ffmpeg-nvenc-jammy.patch`

### GitHub Actions

Workflow boundary for release, validation, and repository automation.

- [release workflow](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/release.yaml): release CI · Drives the full build, packaging, and publication flow. · `.github/workflows/release.yaml`
- [build workflow](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/build.yaml): validation CI · Runs build-oriented checks in GitHub Actions. · `.github/workflows/build.yaml`
- [test workflow](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/test.yaml): validation CI · Runs test-oriented validation in GitHub Actions. · `.github/workflows/test.yaml`
- [repo automation](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/.github/workflows/settings.yaml): ops CI · Settings, label sync, and issue upkeep workflows. · `.github/workflows/settings.yaml`

### Build pipeline

Shell-based dependency build and FFmpeg compilation stages.

- [build.sh](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build.sh): orchestrator · Main shell entrypoint that sequences the static build. · `build.sh`
- [packages](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/00-packages.sh): setup stage · Installs packages and prepares tooling for the build environment. · `build-scripts/00-packages.sh`
- [libvpx](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/01-libvpx.sh): codec dep · Builds the VP8/VP9 dependency used by FFmpeg. · `build-scripts/01-libvpx.sh`
- [svt-av1](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/02-svt-av1.sh): codec dep · Builds the AV1 encoder dependency used by FFmpeg. · `build-scripts/02-svt-av1.sh`
- **x264 x265 lame opus mbedtls**: media deps · Remaining static media and crypto dependencies for the final link.
- [FFmpeg build](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/90-ffmpeg.sh): compile stage · Configures and compiles FFmpeg against the static dependency set. · `build-scripts/90-ffmpeg.sh`
- [static check](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/build-scripts/99-check-static.sh): verify stage · Verifies that the final binaries are statically linked. · `build-scripts/99-check-static.sh`
- [Alpine detect](https://github.com/shaka-project/static-ffmpeg-binaries/blob/main/is-alpine.sh): env helper · Special-cases Alpine Linux behavior during builds. · `is-alpine.sh`

### Artifacts & release

Generated binaries, checksums, and published release outputs.

- **FFmpeg artifacts**: release artifacts · Built ffmpeg and ffprobe binaries generated in the build output tree.
- **MD5 sums**: integrity metadata · Checksum records used in logs and release notes for verification.
- **GitHub Releases**: distribution · Published release target for downloadable binaries and notes.

## Connections

- versions.txt → build.sh: pins versions · Build scripts consume the shared version source.
- versions.txt → release workflow: drives release · Release workflow uses version metadata for tagging and naming.
- get-version.sh → release workflow: names tags · Computes version strings for release orchestration.
- build matrix → build workflow: selects platforms · Workflow expands across supported build combinations.
- build matrix → release workflow: selects platforms · Release workflow fans out across the supported matrix.
- build workflow → build.sh: runs · CI validation invokes the shell pipeline.
- test workflow → build.sh: validates · Tests exercise the build logic and resulting artifacts.
- release workflow → build.sh: orchestrates · Release workflow drives the end-to-end build pipeline.
- repo automation → GitHub Releases: maintains · Repository automation supports release-adjacent housekeeping.
- build.sh → packages: starts · Main build entrypoint begins with environment setup.
- build.sh → Alpine detect: detects · Build entrypoint branches for Alpine-specific behavior.
- packages → libvpx: prepares · Base tooling stage precedes codec dependency compilation.
- libvpx → svt-av1: feeds · Core codec dependency work continues with AV1 support.
- svt-av1 → x264 x265 lame opus mbedtls: feeds · Primary codec libraries enable the remaining media deps.
- x264 x265 lame opus mbedtls → FFmpeg build: enables · Static dependencies are linked into the FFmpeg build.
- NVENC patch → FFmpeg build: modifies · Targeted source patch is applied before compilation.
- FFmpeg build → static check: verifies · Static linkage is checked after the FFmpeg build.
- static check → FFmpeg artifacts: produces · Passing verification yields final binaries.
- FFmpeg artifacts → MD5 sums: hashes · Produced binaries are recorded with MD5 sums.
- MD5 sums → GitHub Releases: publishes · Checksum metadata accompanies the released artifacts.
- FFmpeg artifacts → GitHub Releases: attaches · Built ffmpeg and ffprobe binaries are attached to releases.