Joshooaj.FFmpeg.Packages

Joshooaj.FFmpeg.Packages provides FFmpeg 8.1 shared libraries for .NET applications on Linux and Windows. Most applications need one package reference. Choose an LGPL or GPL native bundle, with or without the FFmpeg.AutoGen C# bindings.

Package version 8.1.2 uses FFmpeg.AutoGen 8.1.0 and the FFmpeg 8.1 ABI. It selects BtbN autobuild autobuild-2026-06-30-13-34 and FFmpeg commit ce3c09c101c83add623774d414a9f9498caf5c25. Native archives are checksum-pinned in assets/sources.json.

Choose a package

Application package	Includes	Use it when
Joshooaj.FFmpeg.AutoGen	FFmpeg.AutoGen plus LGPL native libraries	You want the simplest FFmpeg.AutoGen setup and do not need GPL-only features.
Joshooaj.FFmpeg.AutoGen.GPL	FFmpeg.AutoGen plus GPL native libraries	You need GPL-enabled FFmpeg features and can comply with GPLv3.
Joshooaj.FFmpeg.LGPL	LGPL native libraries only	You use another binding or load FFmpeg yourself.
Joshooaj.FFmpeg.GPL	GPL native libraries only	You use another binding or load FFmpeg yourself and need GPL features.

Do not reference RID payload packages directly in normal cross-platform applications. The four application packages depend on the appropriate payloads with exact [8.1.2] version ranges.

Package reference

For FFmpeg.AutoGen with LGPL libraries:

<PackageReference Include="Joshooaj.FFmpeg.AutoGen" Version="8.1.2" />

For FFmpeg.AutoGen with GPL libraries:

<PackageReference Include="Joshooaj.FFmpeg.AutoGen.GPL" Version="8.1.2" />

The AutoGen packages inject a module initializer into executable .NET 5+ projects. It sets ffmpeg.RootPath to the current platform's native directory for normal builds, or to the application directory for RID-specific publishes. No loader setup is required on the supported RIDs.

SDK-style .NET Framework 4.8 executable projects that use PackageReference are also supported on win-x64. The package copies FFmpeg native DLLs into the build output root so ffmpeg.RootPath can remain at its default application directory value. AnyCPU consumers automatically run with Prefer32Bit=false; x86 is not supported.

The selected native entry package also copies the applicable FFmpeg license into normal build and publish outputs:

• LGPL packages: licenses/FFmpeg/LICENSE.LGPLv3.txt
• GPL packages: licenses/FFmpeg/LICENSE.GPLv3.txt

Supported platforms

RID	Operating system	Architecture
linux-x64	Linux	x64
linux-arm64	Linux	ARM64
win-x64	Windows	x64
win-arm64	Windows	ARM64

macOS and 32-bit platforms are not included.

For .NET Framework 4.8, only SDK-style PackageReference executable projects on Windows x64 are supported.

Every package

Package	Purpose
Joshooaj.FFmpeg.AutoGen	LGPL one-reference entry package with bindings and automatic loader initialization.
Joshooaj.FFmpeg.AutoGen.GPL	GPL one-reference entry package with bindings and automatic loader initialization.
Joshooaj.FFmpeg.LGPL	Thin cross-platform entry package for all four LGPL payloads. Contains no native binaries itself.
Joshooaj.FFmpeg.GPL	Thin cross-platform entry package for all four GPL payloads. Contains no native binaries itself.
Joshooaj.FFmpeg.LGPL.linux-x64	LGPL native payload for linux-x64.
Joshooaj.FFmpeg.LGPL.linux-arm64	LGPL native payload for linux-arm64.
Joshooaj.FFmpeg.LGPL.win-x64	LGPL native payload for win-x64.
Joshooaj.FFmpeg.LGPL.win-arm64	LGPL native payload for win-arm64.
Joshooaj.FFmpeg.GPL.linux-x64	GPL native payload for linux-x64.
Joshooaj.FFmpeg.GPL.linux-arm64	GPL native payload for linux-arm64.
Joshooaj.FFmpeg.GPL.win-x64	GPL native payload for win-x64.
Joshooaj.FFmpeg.GPL.win-arm64	GPL native payload for win-arm64.

Each RID payload uses NuGet's standard runtimes/<rid>/native/ layout. Linux packages contain one ABI-major filename per FFmpeg library rather than duplicate symlink aliases.

Test local packages

After packing the solution into ./artifacts, create a test application:

dotnet new console --name FFmpegSmokeTest --framework net10.0
Set-Location FFmpegSmokeTest
dotnet add package Joshooaj.FFmpeg.AutoGen --version 8.1.2 --source ../artifacts

Add this property to FFmpegSmokeTest.csproj because FFmpeg.AutoGen exposes pointer-based APIs:

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Replace Program.cs with:

using FFmpeg.AutoGen;

unsafe
{
    Console.WriteLine($"FFmpeg {ffmpeg.av_version_info()}");
    Console.WriteLine($"Root path: {ffmpeg.RootPath}");
}

Run and publish it:

dotnet run -c Release
dotnet publish -c Release -r linux-x64 --self-contained false
./bin/Release/net10.0/linux-x64/publish/FFmpegSmokeTest

Use win-x64, win-arm64, or linux-arm64 when testing those platforms. A no-RID build keeps all runtime folders under the output's runtimes/ directory. A RID-specific publish selects the matching native payload and places its libraries in the publish output.

To test GPL, replace Joshooaj.FFmpeg.AutoGen with Joshooaj.FFmpeg.AutoGen.GPL. To test native-only consumption, reference Joshooaj.FFmpeg.LGPL or Joshooaj.FFmpeg.GPL; those packages intentionally provide no C# API or AutoGen loader initialization.

For SDK-style net48 validation on Windows, use:

dotnet new console --name FFmpegSmokeTest.NetFramework
Set-Location FFmpegSmokeTest.NetFramework
dotnet add package Joshooaj.FFmpeg.AutoGen --version 8.1.2 --source ../artifacts

Set <AllowUnsafeBlocks>true</AllowUnsafeBlocks>, <TargetFramework>net48</TargetFramework> and run:

dotnet run -c Release

The package keeps ffmpeg.RootPath at the application directory and copies FFmpeg DLLs there automatically for supported .NET Framework consumers.

Build packages locally

Download and verify native assets from the checked-in manifest, then pack the solution:

./scripts/Download-Sources.ps1
dotnet pack ./Joshooaj.FFmpeg.sln -c Release -o ./artifacts

The downloader rejects archives whose SHA-256 does not match assets/sources.json.

Monthly updates

.github/workflows/monthly-update.yml runs on the second day of each month and can also be dispatched with a YYYY-MM UTC month. It selects the final BtbN autobuild published in the requested month, resolves exact FFmpeg and BtbN commits, and requires the complete eight-asset RID and license matrix.

For a new candidate, the workflow creates a source evidence bundle, advances the synchronized package family, updates this documentation and assets/sources.json, verifies and packs all 12 packages, and smoke-tests both license families on Linux x64. It uploads the candidate report, packages, validation report, and evidence ZIP for 90 days, then opens or updates a review PR and dispatches the repository's complete four-RID CI matrix. It never publishes packages automatically.

If discovery cannot establish an exact candidate, the workflow uploads the structured blocked report and creates or updates a Monthly FFmpeg update blocked issue. A candidate matching the checked-in release is a successful no-op.

Publish a release

Package publication is a separate, manually dispatched workflow after the monthly update PR is reviewed, passes CI, and is merged to main. Configure a protected GitHub environment named nuget-production, require the desired reviewers, define its NUGET_USER variable as the NuGet.org trusted-publishing policy creator, and register .github/workflows/release.yml for trusted publishing on NuGet.org.

Run the Release workflow with the exact package version from main and the originating monthly-update workflow run ID. It rebuilds and strictly validates all 12 packages, runs both license families on all four supported RIDs, pauses for environment approval, verifies the retained source evidence against assets/sources.json, and publishes to NuGet.org in dependency order. It then verifies every package on NuGet.org and creates a v<version> GitHub Release containing the packages, validation report, candidate report, source manifest, and source evidence ZIP.

Licensing and provenance

The native libraries are redistributed BtbN FFmpeg shared builds. Each RID package includes the upstream license text. LGPL payloads declare LGPL-3.0-only; GPL payloads declare GPL-3.0-only. The thin entry packages and bootstrap source declare MIT for their own content, while their dependencies retain their separate licenses.

Using these packages does not determine whether an application complies with LGPL, GPL, or third-party codec licenses. Review the enabled FFmpeg components, provide required notices and corresponding source where applicable, and obtain legal advice before redistribution. assets/sources.json records immutable BtbN asset URLs and hashes, the exact FFmpeg and BtbN commits, and the matching source evidence bundle hash.

scripts/New-FFmpegSourceBundle.ps1 can archive the exact FFmpeg source snapshot and BtbN build-recipe snapshot selected by a monthly candidate. The current evidence bundle explicitly does not include every external dependency source, build log, configure output, or toolchain image used by BtbN. Preserve it as provenance evidence, not as a guarantee that the archive alone satisfies corresponding-source obligations or reproduces the binaries.