Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ jobs:
"$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --install "ndk;${ndk_version}" >/dev/null

- name: Verify repository
run: ./gradlew verify
run: scripts/verify-release-shape.sh

- name: Check Markdown links
uses: putdotio/.github/.github/actions/links@e07dede03892f9b80fec82bf38afcd5f76b763b0 # v2.3.3
Expand Down
435 changes: 424 additions & 11 deletions NOTICE

Large diffs are not rendered by default.

25 changes: 22 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,19 @@ Needs Java 21, the NDK in `ndkVersion`, Linux x86_64 or macOS, and shallow submo

```bash
git clone --recurse-submodules --shallow-submodules https://github.com/putdotio/media3-ffmpeg-decoder.git
cd media3-ffmpeg-decoder
./gradlew verify
./gradlew publishToMavenLocal -Pversion=1.11.1+1
```

`./gradlew verify` builds FFmpeg with Media3's own `build_ffmpeg.sh`, then [check-aar.sh](./scripts/check-aar.sh) fails the build on a non-LGPL FFmpeg, a 64-bit library not aligned to 16 KB, a missing ABI or a missing renderer class.
`./gradlew verify` builds FFmpeg with Media3's own `build_ffmpeg.sh`, then publishes to Maven Local and fails the build on what a release must not ship:

- [check-ffmpeg-licenses.sh](./scripts/check-ffmpeg-licenses.sh): any GPL source compiled into any ABI, from the objects each ABI actually built, or a compiled non-LGPL notice missing from [NOTICE](./NOTICE). Runs during `buildFfmpeg`.
- [check-aar.sh](./scripts/check-aar.sh): a non-LGPL FFmpeg, a decoder outside the allowed set, a missing per-ABI configure line, a 64-bit library not aligned to 16 KB, a missing ABI, a missing renderer class, a missing notice file, or a `RELEASE` that disagrees with the pinned tag.
- [check-publication.sh](./scripts/check-publication.sh): a POM without the single combined license entry, a missing sources or javadoc jar, an `ffmpeg-source` archive that differs from the pinned FFmpeg plus [patches/ffmpeg-lgpl-only.patch](./patches/ffmpeg-lgpl-only.patch), or a GPL file in that archive.
- [check-negative-controls.sh](./scripts/check-negative-controls.sh): proves each check fails on broken input.

CI runs [verify-release-shape.sh](./scripts/verify-release-shape.sh), which does the same with a release version and a throwaway signing key.

## Bump Media3

Expand Down Expand Up @@ -53,19 +61,30 @@ git add .gitmodules ffmpeg
./gradlew verify
```

[check-ffmpeg-licenses.sh](./scripts/check-ffmpeg-licenses.sh) fails on a new GPL source or a new third-party notice. Remove a GPL source with [patches/ffmpeg-lgpl-only.patch](./patches/ffmpeg-lgpl-only.patch). Add a new notice to [NOTICE](./NOTICE) from `scripts/classify-license.pl --print-notices <ffmpeg tree> <<<path`.

## Release

```bash
git tag 'v1.11.1+1'
git push origin 'v1.11.1+1'
```

Pushing a `v*` tag publishes the AAR, sources and POM, signed, from the [release job](./.github/workflows/ci.yml). The tag must be on `main`. The version must be the current Media3 version plus `+<build>`. Central rejects a re-upload, so never delete or re-push a tag: bump the build number instead.
Pushing a `v*` tag publishes the AAR, sources, javadoc, `ffmpeg-source` archive and POM, signed, from the [release job](./.github/workflows/ci.yml). The tag must be on `main`. The version must be the current Media3 version plus `+<build>`. Central rejects a re-upload, so never delete or re-push a tag: bump the build number instead.

The job reads `MAVEN_CENTRAL_USERNAME`, `MAVEN_CENTRAL_PASSWORD`, `SIGNING_KEY_ID`, `SIGNING_KEY` and `SIGNING_PASSWORD` from the protected `release` environment.

## License

This project is [Apache-2.0](./LICENSE), the license of Media3's module.

The AAR bundles FFmpeg, which is LGPL-2.1-or-later. FFmpeg is built without `--enable-gpl`, `--enable-nonfree` and `--enable-version3`. Each AAR carries the exact FFmpeg commit, configure string and LGPL text under `META-INF/media3-ffmpeg-decoder/`, and the corresponding source is the `ffmpeg` submodule at the release tag. See [NOTICE](./NOTICE).
The AAR bundles FFmpeg, which is LGPL-2.1-or-later. FFmpeg is built without `--enable-gpl`, `--enable-nonfree` and `--enable-version3`. On arm64, [patches/ffmpeg-lgpl-only.patch](./patches/ffmpeg-lgpl-only.patch) removes FFmpeg's GPL AC-3 NEON assembly, so the ac3 and eac3 decoders run the C implementation. Each AAR carries the exact FFmpeg commit, per-ABI configure lines, LGPL text, FFmpeg's `LICENSE.md` and the third-party notices under `META-INF/media3-ffmpeg-decoder/`. The corresponding source is published next to the AAR on Maven Central as `media3-ffmpeg-decoder-<version>-ffmpeg-source.tar.xz`: the FFmpeg tree that was built, the patch, the JNI wrapper, the build scripts and a `BUILD.txt` with the commands to rebuild FFmpeg and relink `libffmpegJNI.so`. See [NOTICE](./NOTICE).

## Shipping this in an app

An app that bundles this AAR carries FFmpeg under the LGPL. To stay compliant:

- Keep the notices. Show the contents of `META-INF/media3-ffmpeg-decoder/` (`NOTICE`, `LICENSE`, `COPYING.LGPLv2.1`, `FFMPEG-LICENSE.md`) in your app's licenses screen or docs, or ship them next to it.
- Offer the matching source: the `ffmpeg-source` archive of the exact version you ship, from Maven Central or your own host.
- Do not strip the notices with packaging excludes. `packaging { resources { excludes } }` must not match `META-INF/media3-ffmpeg-decoder/**`, including broad patterns like `META-INF/*` or `META-INF/**`.
- Do not prevent users from replacing `libffmpegJNI.so` with one they rebuilt from that archive. `BUILD.txt` has the commands.
97 changes: 91 additions & 6 deletions build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ val upstreamModule = layout.projectDirectory.dir("media/libraries/decoder_ffmpeg
val stagedModule = layout.buildDirectory.dir("ffmpeg-module")
val stagedCMakeLists = stagedModule.map { it.file("jni/CMakeLists.txt") }
val ffmpegBuildLog = stagedModule.map { it.file("build.log") }
val stagedFfmpeg = stagedModule.map { it.dir("jni/ffmpeg") }
val ffmpegSourceArchive = layout.buildDirectory.file("ffmpeg-source/ffmpeg-source.tar.xz")

group = "io.put"
version = providers.gradleProperty("version").orNull?.takeUnless { it == "unspecified" } ?: "$media3Version-SNAPSHOT"
Expand Down Expand Up @@ -90,21 +92,51 @@ val gitCommit = { path: String ->

val ndkDirectoryPath = androidComponents.sdkComponents.ndkDirectory.map { it.asFile.path }

val ffmpegLicenseInputs =
listOf(
"NOTICE",
"LICENSE",
"patches",
"scripts/stage-ffmpeg-source.sh",
"scripts/apply-ffmpeg-patch.sh",
"scripts/ffmpeg-gpl-files.sh",
"scripts/classify-license.pl",
"scripts/list-compiled-sources.pl",
"scripts/check-ffmpeg-licenses.sh",
"scripts/record-objects",
)

val buildFfmpeg =
tasks.register<RunScript>("buildFfmpeg") {
group = "build"
description = "Builds LGPL FFmpeg static libraries with Media3's build_ffmpeg.sh"
script = layout.projectDirectory.file("scripts/build-ffmpeg.sh")
inputs.property("ffmpegCommit", gitCommit("ffmpeg"))
inputs.property("media3Commit", gitCommit("media"))
inputs.file(layout.projectDirectory.file("NOTICE")).withPathSensitivity(PathSensitivity.RELATIVE)
inputs
.files(ffmpegLicenseInputs)
.withPathSensitivity(PathSensitivity.RELATIVE)
outputs.dir(stagedModule)
arguments.add(ndkDirectoryPath)
arguments.add(ffmpegMinSdk.toString())
arguments.add(stagedModule.map { it.asFile.path })
arguments.addAll(ffmpegDecoders)
}

val packageFfmpegSource =
tasks.register<RunScript>("packageFfmpegSource") {
group = "build"
description = "Packages the FFmpeg source, JNI wrapper and build scripts for LGPL distribution"
script = layout.projectDirectory.file("scripts/package-ffmpeg-source.sh")
inputs.property("ffmpegCommit", gitCommit("ffmpeg"))
inputs.property("media3Commit", gitCommit("media"))
inputs
.files(ffmpegLicenseInputs, "gradle.properties", "scripts/build-ffmpeg.sh")
.withPathSensitivity(PathSensitivity.RELATIVE)
outputs.file(ffmpegSourceArchive)
arguments.add(ffmpegSourceArchive.map { it.asFile.path })
}

androidComponents {
beforeVariants(selector().withBuildType("debug")) { it.enable = false }
onVariants { variant ->
Expand All @@ -119,18 +151,60 @@ tasks.matching { it.name.startsWith("configureCMake") }.configureEach {
val checkAar =
tasks.register<RunScript>("checkAar") {
group = "verification"
description = "Checks the AAR for 16 KB alignment, ABIs, FFmpeg's license and the renderer class"
description = "Checks the AAR for 16 KB alignment, ABIs, decoders, FFmpeg's license and the renderer class"
dependsOn("assembleRelease")
outputs.upToDateWhen { false }
script = layout.projectDirectory.file("scripts/check-aar.sh")
arguments.add(layout.buildDirectory.file("outputs/aar/media3-ffmpeg-decoder-release.aar").map { it.asFile.path })
arguments.add(ffmpegBuildLog.map { it.asFile.path })
arguments.add(ndkDirectoryPath)
arguments.add(stagedFfmpeg.map { it.asFile.path })
}

val publicationSigning = if (providers.gradleProperty("signingInMemoryKey").isPresent) "signed" else "unsigned"
val publishedVersionDirectory =
version.toString().let { publishedVersion ->
providers
.systemProperty("maven.repo.local")
.orElse(providers.systemProperty("user.home").map { "$it/.m2/repository" })
.map { "$it/io/put/media3-ffmpeg-decoder/$publishedVersion" }
}

val checkPublication =
tasks.register<RunScript>("checkPublication") {
group = "verification"
description = "Checks the publication in Maven Local for everything Maven Central and the LGPL require"
dependsOn("publishToMavenLocal")
outputs.upToDateWhen { false }
script = layout.projectDirectory.file("scripts/check-publication.sh")
arguments.add(publishedVersionDirectory)
arguments.add(version.toString())
arguments.add(publicationSigning)
}

val checkNegativeControls =
tasks.register<RunScript>("checkNegativeControls") {
group = "verification"
description = "Proves the AAR and publication checks fail on broken input"
dependsOn(checkAar, checkPublication)
outputs.upToDateWhen { false }
script = layout.projectDirectory.file("scripts/check-negative-controls.sh")
inputs
.files("scripts/check-aar.sh", "scripts/check-publication.sh")
.withPathSensitivity(PathSensitivity.RELATIVE)
arguments.add(layout.buildDirectory.file("outputs/aar/media3-ffmpeg-decoder-release.aar").map { it.asFile.path })
arguments.add(ffmpegBuildLog.map { it.asFile.path })
arguments.add(ndkDirectoryPath)
arguments.add(stagedFfmpeg.map { it.asFile.path })
arguments.add(publishedVersionDirectory)
arguments.add(version.toString())
arguments.add(publicationSigning)
}

tasks.register("verify") {
group = "verification"
description = "Builds the AAR and enforces the release checks"
dependsOn(checkAar)
description = "Builds the AAR, publishes to Maven Local and enforces the release checks"
dependsOn(checkAar, checkPublication, checkNegativeControls)
}

dependencies {
Expand All @@ -151,6 +225,16 @@ tasks.matching { it.name.startsWith("publish") && !it.name.endsWith("ToMavenLoca
}
}

publishing {
publications.withType<MavenPublication>().configureEach {
artifact(ffmpegSourceArchive) {
builtBy(packageFfmpegSource)
classifier = "ffmpeg-source"
extension = "tar.xz"
}
}
}

mavenPublishing {
publishToMavenCentral(automaticRelease = true)
if (providers.gradleProperty("signingInMemoryKey").isPresent) {
Expand All @@ -173,8 +257,9 @@ mavenPublishing {

licenses {
license {
name.set("Apache-2.0")
url.set("https://www.apache.org/licenses/LICENSE-2.0.txt")
name.set("Apache-2.0 AND LGPL-2.1-or-later")
url.set("https://github.com/putdotio/media3-ffmpeg-decoder/blob/main/NOTICE")
comments.set("Apache-2.0 for the Java classes and JNI wrapper, LGPL-2.1-or-later for the FFmpeg libraries statically linked into libffmpegJNI")
}
}

Expand Down
4 changes: 2 additions & 2 deletions gradle/wrapper/gradle-wrapper.properties
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.1-bin.zip
networkTimeout=10000
retries=0
networkTimeout=60000
retries=3
retryBackOffMs=500
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
Expand Down
44 changes: 44 additions & 0 deletions patches/ffmpeg-lgpl-only.patch
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
--- a/libavcodec/aarch64/Makefile
+++ b/libavcodec/aarch64/Makefile
@@ -1,5 +1,7 @@
+# Modified by put.io on 2026-11-08: removed ac3dsp_init_aarch64.o and
+# ac3dsp_neon.o, whose sources are licensed under the GPL.
+
# subsystems
-OBJS-$(CONFIG_AC3DSP) += aarch64/ac3dsp_init_aarch64.o
OBJS-$(CONFIG_FDCTDSP) += aarch64/fdctdsp_init_aarch64.o
OBJS-$(CONFIG_FMTCONVERT) += aarch64/fmtconvert_init.o
OBJS-$(CONFIG_H264CHROMA) += aarch64/h264chroma_init_aarch64.o
@@ -38,7 +40,6 @@

# subsystems
NEON-OBJS-$(CONFIG_AAC_DECODER) += aarch64/sbrdsp_neon.o
-NEON-OBJS-$(CONFIG_AC3DSP) += aarch64/ac3dsp_neon.o
NEON-OBJS-$(CONFIG_FDCTDSP) += aarch64/fdctdsp_neon.o
NEON-OBJS-$(CONFIG_FMTCONVERT) += aarch64/fmtconvert_neon.o
NEON-OBJS-$(CONFIG_H264CHROMA) += aarch64/h264cmc_neon.o
--- a/libavcodec/ac3dsp.c
+++ b/libavcodec/ac3dsp.c
@@ -19,6 +19,11 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/

+/*
+ * Modified by put.io on 2026-11-08: aarch64 uses the C implementation, because
+ * FFmpeg's aarch64 assembly for this DSP is licensed under the GPL.
+ */
+
#include <math.h>
#include <stdlib.h>
#include <string.h>
@@ -389,9 +394,7 @@
c->downmix = NULL;
c->downmix_fixed = NULL;

-#if ARCH_AARCH64
- ff_ac3dsp_init_aarch64(c);
-#elif ARCH_ARM
+#if ARCH_ARM
ff_ac3dsp_init_arm(c);
#elif ARCH_X86
ff_ac3dsp_init_x86(c);
5 changes: 5 additions & 0 deletions renovate.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@
"enabled": true
},
"packageRules": [
{
"description": "git-refs returns no release timestamps, so a release age would stall every submodule update",
"matchManagers": ["git-submodules"],
"minimumReleaseAge": null
},
{
"matchManagers": ["git-submodules"],
"matchDepNames": ["media"],
Expand Down
10 changes: 10 additions & 0 deletions scripts/apply-ffmpeg-patch.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
#!/usr/bin/env bash
set -euo pipefail

scripts_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
tree="$1"

patch -d "$tree" -p1 -N -F 0 -s -i "$scripts_dir/../patches/ffmpeg-lgpl-only.patch"
"$scripts_dir/ffmpeg-gpl-files.sh" "$tree" | while IFS= read -r gpl_file; do
rm "$tree/$gpl_file"
done
27 changes: 19 additions & 8 deletions scripts/build-ffmpeg.sh
Original file line number Diff line number Diff line change
Expand Up @@ -15,36 +15,47 @@ case "$(uname -s)" in
*) echo "unsupported host: $(uname -s)" >&2; exit 1 ;;
esac

upstream_jni="$repo_root/media/libraries/decoder_ffmpeg/src/main/jni"
build_log="$module_dir/build.log"

rm -rf "$module_dir"
mkdir -p "$module_dir/jni/ffmpeg"
cp "$upstream_jni/build_ffmpeg.sh" "$upstream_jni/CMakeLists.txt" "$upstream_jni/ffmpeg_jni.cc" "$module_dir/jni/"
git -C "$repo_root/ffmpeg" archive HEAD | tar -x -C "$module_dir/jni/ffmpeg"
"$repo_root/scripts/stage-ffmpeg-source.sh" "$module_dir"

if ! "$module_dir/jni/build_ffmpeg.sh" "$module_dir" "$ndk_path" "$host_platform" "$min_sdk" "${decoders[@]}" >"$build_log" 2>&1; then
objects_dir="$module_dir/compiled-objects"
export FFMPEG_OBJECTS_DIR="$objects_dir"
FFMPEG_REAL_MAKE="$(command -v make)"
export FFMPEG_REAL_MAKE
if ! PATH="$repo_root/scripts/record-objects:$PATH" "$module_dir/jni/build_ffmpeg.sh" "$module_dir" "$ndk_path" "$host_platform" "$min_sdk" "${decoders[@]}" >"$build_log" 2>&1; then
tail -n 80 "$build_log" >&2
exit 1
fi
"$repo_root/scripts/check-ffmpeg-licenses.sh" "$module_dir/jni/ffmpeg" "$objects_dir" "$repo_root/NOTICE" "$ndk_path" "$module_dir/compiled-licenses.txt"
rm "$module_dir/jni/ffmpeg/VERSION"

ffmpeg_commit="$(git -C "$repo_root/ffmpeg" rev-parse HEAD)"
media3_commit="$(git -C "$repo_root/media" rev-parse HEAD)"
ffmpeg_tag="$(git -C "$repo_root" config -f .gitmodules submodule.ffmpeg.branch)"
media3_tag="$(git -C "$repo_root" config -f .gitmodules submodule.media.branch)"
configuration="$(sed -n 's/^#define FFMPEG_CONFIGURATION "\(.*\)"$/\1/p' "$module_dir/jni/ffmpeg/config.h")"
strings_tools=("$ndk_path"/toolchains/llvm/prebuilt/*/bin/llvm-strings)
configurations=""
for abi in arm64-v8a armeabi-v7a x86_64 x86; do
archive_strings="$("${strings_tools[0]}" "$module_dir/jni/ffmpeg/android-libs/$abi/libavutil.a")"
configuration="$(awk -v prefix="--libdir=android-libs/$abi " 'index($0, prefix) == 1 { print; exit }' <<<"$archive_strings" | sed "s#$ndk_path#\$NDK#g")"
configurations+="${configurations:+$'\n'}Configuration $abi: $configuration"
done

license_dir="$resources_dir/META-INF/media3-ffmpeg-decoder"
rm -rf "$license_dir"
mkdir -p "$license_dir"
cp "$repo_root/LICENSE" "$license_dir/LICENSE"
cp "$repo_root/NOTICE" "$license_dir/NOTICE"
cp "$repo_root/ffmpeg/COPYING.LGPLv2.1" "$license_dir/COPYING.LGPLv2.1"
cp "$repo_root/ffmpeg/LICENSE.md" "$license_dir/FFMPEG-LICENSE.md"
cat >"$license_dir/ffmpeg-build.txt" <<INFO
FFmpeg tag: $ffmpeg_tag
FFmpeg source: https://github.com/FFmpeg/FFmpeg/tree/$ffmpeg_commit
FFmpeg source: https://github.com/FFmpeg/FFmpeg/tree/$ffmpeg_commit, with the changes listed in NOTICE
Media3 tag: $media3_tag
Build script: https://github.com/androidx/media/blob/$media3_commit/libraries/decoder_ffmpeg/src/main/jni/build_ffmpeg.sh
Minimum SDK: $min_sdk
Decoders: ${decoders[*]}
Configuration: $configuration
$configurations
INFO
Loading