# Android LGPL-only FFmpeg Build Artifacts

This directory records the reproducible source-build path for the Android
app-side FFmpeg runtime used by HL Player media feature backends.

No FFmpeg or FFprobe binary is committed here. Generated runtime artifacts are
staged into the app by the build script and are ignored by git.

## Baseline

- FFmpeg version: 8.1.2 "Hoare"
- Upstream release page: https://ffmpeg.org/download.html
- Upstream legal page: https://ffmpeg.org/legal.html
- Source archive to publish for a shipped build:
  `https://ffmpeg.org/releases/ffmpeg-8.1.2.tar.xz`
- official `ffmpeg-8.1.2.tar.xz` SHA-256:
  `464beb5e7bf0c311e68b45ae2f04e9cc2af88851abb4082231742a74d97b524c`
- Local changes file: `changes.diff`, only when local patches are applied.
- libwebp version: 1.6.0, official `v1.6.0` tag
- libwebp source: https://github.com/webmproject/libwebp/tree/v1.6.0
- libwebp tag target commit: `4fa21912338357f89e4fd51cf2368325b59e9bd9`
- official `libwebp-1.6.0.tar.gz` SHA-256:
  `e4ab7009bf0629fd11982d4c2aa83964cf244cffba7347ecd39019a9e38c4564`
- libwebp license: BSD-3-Clause with the upstream patent grant

## Configure Flags

The exact common LGPL policy flags are recorded in:

- `ffmpeg-android-lgpl-configure.args`

ABI-specific toolchain flags and optional app staging are generated by:

- `build-android-lgpl.ps1`

Each ABI build writes its full configure command to:

- `out/<abi>/configure-command.txt`
- `out/<abi>/configure-license.txt` records the configure-reported license and
  the reviewed GPL/nonfree/libwebp config macros.

To refresh only these configure records without rebuilding native binaries:

```powershell
.\tool\regenerate_ffmpeg_android_config_evidence.ps1 `
  -AndroidNdkHome $env:ANDROID_NDK_HOME
```

## Guardrail Verification

Run this before any Android FFmpeg binary is produced or published:

```powershell
.\third_party\ffmpeg\android\verify-android-lgpl-config.ps1
```

The verifier fails if the common configure flags include GPL/nonfree enable
flags or reviewed-forbidden external codec libraries. It also requires shared
libraries and disables static output for LGPL replacement/debugging posture.

After producing an APK or AAB, inspect package entries, per-ABI configure
records, ELF dependencies, and binary strings with:

```powershell
.\third_party\ffmpeg\android\verify-android-lgpl-artifact.ps1 `
  -ArtifactPath .\build\app\outputs\bundle\release\app-release.aab `
  -AndroidNdkHome $env:ANDROID_NDK_HOME `
  -LicenseOutputRoot .\output\android-animated-clip-qa `
  -LicenseEvidenceAbi arm64-v8a `
  -RequireAnimatedClipRuntime
```

The release gate requires `configure-command.txt` and `configure-license.txt`
for every packaged ABI, then independently checks every ABI's ELF dependencies
and embedded license strings. `LicenseOutputRoot` supplies representative
physical-device execution evidence for the ABI named by
`LicenseEvidenceAbi`. `-RequireAnimatedClipRuntime` additionally requires the
three reviewed libwebp shared libraries and verifies that `libavcodec.so` links
to `libwebp.so` and `libwebpmux.so`.

To execute `ffmpeg -L` on more device or emulator ABIs, add each captured ABI:

```powershell
.\third_party\ffmpeg\android\verify-android-lgpl-artifact.ps1 `
  -ArtifactPath .\build\app\outputs\bundle\release\app-release.aab `
  -AndroidNdkHome $env:ANDROID_NDK_HOME `
  -LicenseOutputRoot .\output\android-animated-clip-qa `
  -LicenseEvidenceAbi arm64-v8a,x86_64 `
  -RequireAnimatedClipRuntime
```

Omitting `LicenseEvidenceAbi` retains the optional strongest mode and requires
an `ffmpeg-license.txt` for every packaged ABI. Cross-ABI license equivalence
does not rely on device output alone: the release gate always inspects the
generated configure-license record and final packaged binary for every ABI.

## Build

Build the reviewed libwebp shared libraries first. Command-line utilities,
image helper dependencies, examples, and static linkage are disabled; only the
encoder/decoder libraries and `libwebpmux` needed by FFmpeg animation output
are installed.

```powershell
.\third_party\ffmpeg\android\build-libwebp-android.ps1 `
  -LibwebpSourceDir C:\src\libwebp-1.6.0 `
  -AndroidNdkHome $env:ANDROID_NDK_HOME `
  -Abi arm64-v8a,armeabi-v7a,x86_64 `
  -MinSdkVersion 24
```

When Android SDK CMake is passed by absolute path, the script automatically
uses the `ninja.exe` installed beside it. Otherwise pass `-NinjaExecutable`
explicitly so the selected build program is reproducible and independent of
the host `PATH`.

Example:

```powershell
.\third_party\ffmpeg\android\build-android-lgpl.ps1 `
  -FfmpegSourceDir C:\src\ffmpeg-8.1.2 `
  -AndroidNdkHome $env:ANDROID_NDK_HOME `
  -LibwebpInstallRoot .\third_party\ffmpeg\android\out\libwebp `
  -Abi arm64-v8a,armeabi-v7a,x86_64 `
  -MinSdkVersion 24 `
  -InstallToApp `
  -BashExecutable bash `
  -MakeExecutable make
```

The build host must provide a POSIX shell and `make`, for example through
MSYS2, Git Bash, or an equivalent Android NDK-compatible shell environment.
The script defaults to the checked-in `libwebp-pkg-config.cmd` wrapper, which
supports only the pinned `libwebp` and `libwebpmux` packages from the ABI-local
install root. This avoids host package autodetection and prevents unrelated
system libraries from entering the FFmpeg link graph.

When `-InstallToApp` is supplied, the script copies FFmpeg shared libraries and
the `ffmpeg`/`ffprobe` command-line programs into:

```text
android/app/src/main/jniLibs/<abi>/
```

The command-line programs are staged as executable-style native libraries named
`libhlplayer_ffmpeg.so` and `libhlplayer_ffprobe.so`. Android extracts these
files into `applicationInfo.nativeLibraryDir`, where the app-side
`FfmpegMediaPlugin` can launch them through `ProcessBuilder`. Do not stage them
as assets or copy them into writable app files; target SDK 35 devices do not
reliably allow executing files from writable app-private storage.

Before shipping any resulting ABI artifact, publish:

- the exact FFmpeg source archive or mirror;
- the exact official libwebp 1.6.0 source archive and recorded checksum;
- libwebp `COPYING` and `PATENTS` notices;
- this directory's build scripts;
- each ABI's `configure-command.txt`;
- any `changes.diff`;
- the final APK/AAB scan evidence;
- the notice entry shown in the app's open-source license screen.
