IAMF decoder public source and rebuild kit
=========================================

This kit contains the public sources and build information for the IAMF
decoder bundled with QVplayer. It contains no proprietary application code,
application signing material, precompiled native libraries, build objects,
or Bazel caches. The IAMF archive omits large test/demo media fixtures and the precompiled
web-demo wasm binary. All decoder code, BUILD files, proto/configuration,
scripts, and license notices are retained unchanged. See SOURCE-EXCLUSIONS.txt.

Components
----------
* Media3 IAMF Java/JNI wrapper: androidx/media tag 1.11.1.
* iamf_tools: commit e552e7d6d8b55530d201fd2764ca7e12d2c66cd6.
* FDK-AAC: commit ee76460efbdb147e26d804c798949c23f174460b.
* Eigen: 3.4.0.bcr.3 complete source, including the MPL-2.0 headers used by OBR.
* Exact source origins, archive hashes, and transitive pins: SOURCE-MANIFEST.json.
* All distributed kit files: SHA256SUMS.txt.
* Original IAMF module instructions: media3-iamf/README.upstream.md.
* License notices: IAMF-THIRD-PARTY-NOTICES.txt and media3-iamf/LICENSE.

Reproduction environment
------------------------
The supplied native binaries were built on macOS arm64 using Android NDK
28.2.13676358 (r28c), Bazel 8.5.1, Bazelisk 1.30.0, CMake 3.31.3, and
Ninja 1.12.1.
The upstream Media3 README states that NDK r29 was tested upstream; r28c
was used successfully for this distribution. CMake targets Android API 26
for the JNI shared library, with c++_static and a 16,384-byte maximum page
size. Bazel uses the pinned upstream Android NDK toolchain configuration.

Install Bazelisk, CMake >=3.21, Ninja, and Android NDK 28.2.13676358. The
Android NDK and tool executables are not redistributed in this kit.
Initial builds require internet access for Bazel and the public dependencies
listed by iamf_tools/MODULE.bazel and its generated lock file.

From the extracted kit directory, run:

    export ANDROID_NDK_HOME="/path/to/android-sdk/ndk/28.2.13676358"
    bash ./build-native.sh

Optional environment variables:
* BAZELISK: path to the Bazelisk executable (default: bazelisk on PATH).
* IAMF_BUILD_JOBS: parallel compiler actions (default: 4).
* IAMF_CACHE_PATH: directory for downloaded tools and build caches.

The script verifies kit checksums, extracts the iamf_tools decoder/build sources,
restores the generated MODULE.bazel.lock, builds iamf_decoder_static for
arm64-v8a, armeabi-v7a, x86_64, and x86, then links libiamfJNI.so for each ABI.
Output libraries appear under jniLibs/<ABI>/libiamfJNI.so.
The build/<ABI> directory retains unstripped libraries. The shipped libraries
were additionally stripped with the same NDK's llvm-strip --strip-unneeded.
This affects symbol/debug information, not decoder features.

Changes from upstream
---------------------
No tracked iamf_tools source file was changed. The empty patch file
config/iamf_tools-tracked.patch records that fact. Bazel generated an
untracked MODULE.bazel.lock; its exact contents are included under config/.
The Java wrapper, JNI wrapper, and CMakeLists.txt are original Media3 1.11.1
files. Their hashes are listed in SOURCE-MANIFEST.json and SHA256SUMS.txt.

build-native.sh replaces the upstream shell orchestration with a portable
loop that works with macOS's older Bash without associative arrays. It uses
the same Bazel target and compiler options, selects NDK r28c, explicitly
targets API 26 for JNI, statically links libc++, and supplies the 16KB linker
alignment option. The original build_iamf_tools.sh is included separately
as build_iamf_tools.upstream.sh. There are no decoder source patches.

Modifying and rebuilding public decoder code
-------------------------------------------
After the first build, edit the extracted source under
media3-iamf/src/main/jni/iamf_tools or the Media3 Java/JNI wrapper, then run
the same build command again. The script does not overwrite existing
iamf_tools sources. For wrapper changes, update or skip the kit checksum
verification intentionally after reviewing your own changes.

Complete Eigen sources are included in sources/eigen-3.4.0.bcr.3-source.tar.gz.
Eigen is used through OBR Core/Dense/Geometry headers; the sources and all
upstream COPYING texts are preserved, with BCR BUILD metadata overlays.
Original source download URLs are recorded in SOURCE-MANIFEST.json.
The NDK sysroot and toolchain notice files are included under licenses/ to
cover statically linked NDK runtimes; those notices also cover components
not necessarily linked into this particular decoder.

The complete unmodified FDK-AAC sources are also included independently in
sources/fdk-aac-source-ee76460e.zip, free of charge. The archive contains
the complete FDK NOTICE. Its BUILD.bazel/WORKSPACE.bazel files are Bazel
integration metadata generated from iamf_tools, rather than FDK code edits.
To build with modified FDK sources, change the fdk_aac repository definition
in iamf_tools/MODULE.bazel to a local repository containing that extracted
source and its supplied BUILD.bazel, then rebuild iamf_decoder_static and
libiamfJNI.so. No QVplayer application sources or signing keys are required
to rebuild these public decoder libraries.

License distribution notes
--------------------------
The Media3 wrapper is Apache-2.0; iamf_tools and its transitive dependencies
have their own licenses and notices. The FDK-AAC NOTICE requires binary
recipients to receive access to its complete corresponding source free of
charge. The included FDK archive provides that source. Retain the accompanying
notices and source availability information when redistributing binaries.
This kit does not grant rights beyond those granted by the upstream licenses.

Validation performed for this distribution
-----------------------------------------
All four Android ABI libraries built successfully. ELF LOAD segments were
checked for at least 16KB alignment. Dynamic dependencies are Android system
libraries only. JNI_OnLoad is exported, and its 17 registered methods match
the supplied Java native declarations. Device playback tests were not run.
See IAMF-build-validation.json for binary hashes and build metadata.
