gecko-dev/media/ffvpx/README_MOZILLA

# FFVPX

This directory contains files used in gecko builds from FFmpeg
(http://ffmpeg.org). The current files are from FFmpeg as of
revision
d9d56953
git clone https://git.ffmpeg.org/ffmpeg.git ffmpeg
git checkout d9d56953

All source files match their path from the library's source archive.

Currently, we only use the vp8, vp9, av1 (via libdav1d), mp3, flac, vorbis (via
libvorbis), opus (via libopus) and PCM portion of the library. If this changes,
configuration files will most likely need to be updated.

Decoding AV1 via libdav1d and libvorbis is supported, although the decoder
libraries are vendored separately, `ffvpx` only contains the code to use
those libraries through the `ffmpeg` API.

The ffmpeg project recommends to use ffmpeg's tip, not a particular release.

## Source files

This library only use a small part of `ffmpeg`. To update the source tree, run:

> rsync -av --existing ffmpeg-upstream ffmpeg-mozilla-dir

Compilation will reveal if any files are missing.

Then, make sure the files:

- `libavcodec/codec_list.c`
- `libavcodec/bsf_list.c`
- `libavcodec/parser_list.c`

include conditional compilation directives, by probably reverting them (or
reverting and adjusting them if new codecs are added).

## Add headers for a new major ffmpeg version

If a new major version of ffmpeg is being imported in the tree, it's necessary
to vendor the new ffmpeg headers in `dom/media/platforms/ffmpeg/ffmpegxx` where
xx is the new ffmpeg major version number, and to modify the dynamic linker
wrapper in
`dom/media/platforms/dom/media/platforms/ffmpeg/{FFmpegLibWrapper.cpp,FFmpegRungtimeLinker.cpp}` with the new version and the new API in this new version.

## `config.h` generation

Configuration files are generated as follow using the configure script (here
for Linux desktop):

> ./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9,mp3,flac,av1 \
              --enable-parser=vp8,vp9 --disable-static --enable-shared \
              --disable-autodetect --disable-iconv --enable-libdav1d --disable-linux-perf

For Linux Desktop, there are a number of overrides in `config_common.h` for
VAAPI. We can't put them in `config_components.h` because this breaks the build.

`config_components.h` is common to all platforms, and then a specific config
file is included, based on the platform and architecture. This needs to be
regenerated on all OSes. macOS is similar to Linux Desktop. For other OSes,
instructions below:

# Linux 32-bits from a Linux 64-bits host:

To produce `config_unix32.h` on a 64-bits machine, add to the configure command
above: `--disable-asm --disable-x86asm --cc='clang -m32'`

Those files shouldn't be Linux-specific, and are included in e.g. various BSDs,
hence the `--disable-linux-perf` above.

# macOS, x86 and aarch64

Similar to Linux Desktop in all aspects.

# Android

config_android32.h: Only mp3 and flac are enabled on this platform. Assuming
the standard toolchain location for a Firefox Developer, substitute with the
ndk version in use when updating:

> ./configure --disable-all --enable-avcodec --enable-decoder=mp3,flac \
              --disable-static --enable-shared --disable-autodetect \
              --enable-small --target-os=linux --arch=arm --enable-cross-compile \
              --cc=$HOME/.mozbuild/android-ndk-r20/toolchains/llvm/prebuilt/darwin-x86_64/bin/armv7a-linux-androideabi16-clang

config_android64.h, config_androidx86_64.h: substitute with aarch64 and the right compiler.

For config_androidx86_64.h, enable vp8 and vp9.

# Windows

The general idea is to get an msys prompt with an msvc toolchain
configured, so that the configure script for ffmpeg can run successfully
with the thread flavor Gecko prefers on Windows (win32, not pthreads).

- Open Visual Studio (2019 when writing this)
- Tools → Command Line → Developer command prompt
- Check that compiling a small C program with cl.exe works
- Install msys2 from https://www.msys2.org/
- From the Visual Studio Developer Command Prompt, run the following:
    > C:\msys64\msys_shell.cmd -mysy -use-full-path
- This pops up a new shell window, with a 32-bits build environment
- Check that compiling a small C program with `cl.exe` works
- Run ffmpeg's ./configure with the options needed:

> ./configure --disable-all --enable-avcodec
              --enable-decoder=vp8,vp9,mp3,flac --enable-parser=vp8,vp9
              --disable-static --enable-shared --disable-autodetect
              --enable-w32threads --toolchain=msvc

- Copy `config.h` and `config.asm` as `config_win32.h` and `config_win32.asm`
  in this directory
- Close the `msys2` window, go back to the `cmd.exe` window
- Run this command, maybe substituting the Visual Studio version:

> "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64

- This pops up a new shell window, now with a 64-bits build
  environment
- Check that compiling a small C program with `cl.exe` works
- Run ffmpeg's `./configure` with the options needed:

> ./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9,mp3,flac
              --enable-parser=vp8,vp9 --disable-static --enable-shared 
              --disable-autodetect --enable-w32threads --toolchain=msvc

- Copy `config.h` and `config.asm` as `config_win64.h` and `config_win64.asm`.

config_aarch64_win64.h: You will need to install cpp (either using msys or
wsl), then:

> ./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9,mp3,flac \
              --enable-parser=vp8,vp9 --disable-static --enable-shared \
              --disable-autodetect  --toolchain=msvc --enable-cross-compile \
              --target-os=win32 --arch=arm64


# Finally

Run the following command on all config* file:

> sed -i -E '/HAVE_(MALLOC_H|ARC4RANDOM|LOCALTIME_R|MEMALIGN|POSIX_MEMALIGN)/d' config.*

to avoid redefined macros.

# Build, fix errors

Missing files need to be added, and the patch to rename `time.h` to `fftime.h`
might need to be reaplied or extended to other files including `time.h`. The
issue being that it's included instead of the system header, causing all sorts
of issues.

`moz.build` files might need to be modified as well, in light of compilation
and link errors.

There are going to be a lot of changes in terms of symbols exported. Adjust
`libavutil/avutil.symbols` and `libavcodec/avcodec.symbols` by removing and
adding symbols until the build passes.