Focused software HDR conversion
==============================

The first-party Java/JNI bridge uses FFmpeg's public libav* APIs. It does not
contain FFmpegKit Java code, native glue, command execution or dependencies.
PROVENANCE.txt records the independent implementation's permitted inputs.
This separation is an engineering record, not a legal clean-room certification.

The separately replaceable FFmpeg shared libraries are LGPL 2.1 or later.
Their only bundled external codec/filter dependencies are permissive zimg
(WTFPL) and dav1d (BSD 2-Clause). Android's zlib is a system library. The NDK
C++ runtime has its own LLVM/permissive notices. GPL, nonfree and version3
components are explicitly disabled. No x264/x265 or FFmpeg CLI is built.

Building
--------

Use a Linux host with Python 3.12+, make, autoconf, automake, libtool and
pkg-config. Install the NDK version pinned in sources.json through the Android
SDK Manager. Set ANDROID_HOME or the project's local sdk.dir; do not commit a
machine-specific SDK path.

Run the Gradle wrapper normally. Generated JNI/resources invoke scripts/build-native-hdr.py;
both arm64-v8a and x86_64 are built at API 28, with 16 KB ELF segment alignment.
Source downloads are verified against sources.json before extraction. Native
build tools Meson/Ninja are pinned and installed into an isolated build venv;
checksum-pinned NASM is built there for normal x86 codec SIMD support.
Outputs and downloaded sources stay in ignored build directories. The first
build requires network access; subsequent builds reuse the verified cache.

The bridge is a separate shared library, dynamically linked to FFmpeg.
Only JNI entrypoints/callbacks are protected against R8 renaming; there is no
LGPL Java implementation for R8 to inline into application DEX.

Release source and replacement
------------------------------

Run:
  python3 scripts/build-native-hdr.py --bundle build/native-hdr/corresponding-source.tar.gz

This bundles exact upstream source archives, their hashes, dependency/build
requirements, the build script and ABI build configurations. First-party Java/
JNI and editor sources are not required for replacing FFmpeg and are not
included. Extract into a working directory, set ANDROID_HOME, and run:
  python3 scripts/build-native-hdr.py --dependencies-only
The standalone FFmpeg build does not require editor or first-party bridge source.

To test a compatible modified FFmpeg, use an isolated working copy, modify its
extracted build/native-hdr/sources/ffmpeg-9.0.2 sources, remove only the target
ABI's dependencies.sha256 cache marker, and rerun with --dependencies-only. Keep the
original upstream archive/hash as the base and distribute the modification
patch and exact build configuration with modified binaries.

Replace the matching lib/<abi>/libav*.so and libsw*.so APK entries with the
rebuilt interface-compatible libraries. Preserve the editor's DEX, resources
and first-party bridge. Realign using Android zipalign -P 16, then sign with
your own key using apksigner. Test on a separate emulator/device: a different
key cannot update the official installation in place. Do not uninstall an
existing installation or erase projects merely to bypass that mismatch.

Publish the release-specific source bundle and usable replacement instructions
alongside each distributed APK and link them from the app's credits/download
page. Bundling development instructions alone does not complete commercial
distribution compliance. Never publish the production signing key. Terms must
permit modification and reverse engineering for debugging LGPL modifications.

The CPU path remains explicitly opt-in and format/resource dependent. It
decodes video, performs linear-light tone mapping and encodes MPEG-4/AAC;
normal editor export remains Media3 H.264. Actual output frames and minimum-
API behavior must be checked when updating the bridge, FFmpeg or dependencies.
