Kepler for Android: corresponding source for FFmpeg (edition 2)
================================================================

Kepler for Android (com.keplerplayer.app) decodes some audio formats (AC-3, E-AC-3, DTS, TrueHD,
MPEG audio and others) with FFmpeg, through the FFmpeg decoder extension of Google's Media3
library, and from edition 2 also MPEG-4 Part 2 video (Xvid, DivX) on devices that have no decoder
of their own for it. FFmpeg is licensed under the GNU Lesser General Public License, version 2.1
or later. This archive is the complete corresponding source for the FFmpeg code in the app, and
everything needed to rebuild it.

Applies to: Kepler for Android, version 1.0 (version code 11) and later builds, until a newer
edition is published. Version codes 4 to 10 carry edition 1 (audio decoders only), whose archive
stays available beside this one.


What is in this archive
-----------------------

ffmpeg/
    FFmpeg 6.0.2, release/6.0 branch at commit b4a62c32549b8295691a8e0ff2c9b82188923159,
    unmodified. Upstream: https://git.ffmpeg.org/ffmpeg.git
    Licence: ffmpeg/COPYING.LGPLv2.1 (see ffmpeg/LICENSE.md).

media3/libraries/decoder_ffmpeg/
    Media3 1.10.1's FFmpeg decoder extension, as published: the Java classes, the JNI glue
    (src/main/jni/ffmpeg_jni.cc), CMakeLists.txt and build_ffmpeg.sh, which runs FFmpeg's
    configure. Upstream: https://github.com/androidx/media, tag 1.10.1.
    Licence: Apache License 2.0 (media3/LICENSE).

media3_ffmpeg/ffmpeg_video_jni.cc
    Kepler's MPEG-4 video decoder glue. The build copies it into the extension's jni folder and
    adds it to the sources in CMakeLists.txt, so it is compiled into the same libffmpegJNI.so.
    Licence: Apache License 2.0.

build_media3_ffmpeg.sh
    The script Kepler's own build uses to produce the extension: it fetches the two trees above,
    adds the file above, configures FFmpeg and builds the Android library. It names every pin
    below.


How the app's library was built
-------------------------------

FFmpeg is compiled as static libraries and linked into libffmpegJNI.so, a separate shared
library inside the app (lib/<abi>/libffmpegJNI.so in the APK), which the app loads at run time.

    Android NDK r26b (26.1.10909125), API level 24, ABIs armeabi-v7a, arm64-v8a, x86, x86_64.

    configure options (from media3/.../jni/build_ffmpeg.sh), for every ABI:
        --target-os=android --enable-static --disable-shared --disable-doc --disable-programs
        --disable-everything --disable-avdevice --disable-avformat --disable-swscale
        --disable-postproc --disable-avfilter --disable-symver --enable-swresample
        --extra-ldexeflags=-pie --disable-v4l2-m2m --disable-vulkan
        plus the per-ABI --arch, --cpu and toolchain options in build_ffmpeg.sh.

    Enabled decoders:
        vorbis opus flac alac pcm_mulaw pcm_alaw mp3 amrnb amrwb aac ac3 eac3 dca mlp truehd mpeg4
        (configure adds what mpeg4 depends on, such as the h263 decoder's shared code.)

    FFmpeg was configured without --enable-gpl and without --enable-nonfree; its own config.h
    reports: FFMPEG_LICENSE "LGPL version 2.1 or later".


Rebuilding it
-------------

1. Install the Android SDK and NDK r26b, and a JDK 17 or 21.
2. Run:  ./build_media3_ffmpeg.sh /path/to/a/work/dir
   (it clones the same two trees; to build from this archive instead, put ffmpeg/ at
   media3/libraries/decoder_ffmpeg/src/main/jni/ffmpeg inside a Media3 1.10.1 checkout, copy
   media3_ffmpeg/ffmpeg_video_jni.cc into that jni folder and add it after ffmpeg_jni.cc in
   CMakeLists.txt, run jni/build_ffmpeg.sh with the decoders above, then
   ./gradlew :lib-decoder-ffmpeg:assembleRelease from Media3's root.)
3. The library is in the AAR it produces, at jni/<abi>/libffmpegJNI.so.


Questions
---------

contact@keplerplayer.com
https://keplerplayer.com/opensource