media/ffvpx/README_MOZILLA

   1 # FFVPX
   2
   3 This directory contains files used in gecko builds from FFmpeg
   4 (http://ffmpeg.org). The current files are from FFmpeg as of
   5 revision
   6 d9d56953
   7 git clone https://git.ffmpeg.org/ffmpeg.git ffmpeg
   8 git checkout d9d56953
   9
  10 All source files match their path from the library's source archive.
  11
  12 Currently, we only use the vp8, vp9, av1 (via libdav1d), mp3, flac, vorbis (via
  13 libvorbis), opus (via libopus) and PCM portion of the library. If this changes,
  14 configuration files will most likely need to be updated.
  15
  16 Decoding AV1 via libdav1d and libvorbis is supported, although the decoder
  17 libraries are vendored separately, `ffvpx` only contains the code to use
  18 those libraries through the `ffmpeg` API.
  19
  20 The ffmpeg project recommends to use ffmpeg's tip, not a particular release.
  21
  22 ## Source files
  23
  24 This library only use a small part of `ffmpeg`. To update the source tree, run:
  25
  26 > rsync -av --existing ffmpeg-upstream ffmpeg-mozilla-dir
  27
  28 Compilation will reveal if any files are missing.
  29
  30 Then, make sure the files:
  31
  32 - `libavcodec/codec_list.c`
  33 - `libavcodec/bsf_list.c`
  34 - `libavcodec/parser_list.c`
  35
  36 include conditional compilation directives, by probably reverting them (or
  37 reverting and adjusting them if new codecs are added).
  38
  39 ## Add headers for a new major ffmpeg version
  40
  41 If a new major version of ffmpeg is being imported in the tree, it's necessary
  42 to vendor the new ffmpeg headers in `dom/media/platforms/ffmpeg/ffmpegxx` where
  43 xx is the new ffmpeg major version number, and to modify the dynamic linker
  44 wrapper in
  45 `dom/media/platforms/dom/media/platforms/ffmpeg/{FFmpegLibWrapper.cpp,FFmpegRungtimeLinker.cpp}` with the new version and the new API in this new version.
  46
  47 ## `config.h` generation
  48
  49 Configuration files are generated as follow using the configure script (here
  50 for Linux desktop):
  51
  52 > ./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9,mp3,flac,av1 \
  53               --enable-parser=vp8,vp9 --disable-static --enable-shared \
  54               --disable-autodetect --disable-iconv --enable-libdav1d --disable-linux-perf
  55
  56 For Linux Desktop, there are a number of overrides in `config_common.h` for
  57 VAAPI. We can't put them in `config_components.h` because this breaks the build.
  58
  59 `config_components.h` is common to all platforms, and then a specific config
  60 file is included, based on the platform and architecture. This needs to be
  61 regenerated on all OSes. macOS is similar to Linux Desktop. For other OSes,
  62 instructions below:
  63
  64 # Linux 32-bits from a Linux 64-bits host:
  65
  66 To produce `config_unix32.h` on a 64-bits machine, add to the configure command
  67 above: `--disable-asm --disable-x86asm --cc='clang -m32'`
  68
  69 Those files shouldn't be Linux-specific, and are included in e.g. various BSDs,
  70 hence the `--disable-linux-perf` above.
  71
  72 # macOS, x86 and aarch64
  73
  74 Similar to Linux Desktop in all aspects.
  75
  76 # Android
  77
  78 config_android32.h: Only mp3 and flac are enabled on this platform. Assuming
  79 the standard toolchain location for a Firefox Developer, substitute with the
  80 ndk version in use when updating:
  81
  82 > ./configure --disable-all --enable-avcodec --enable-decoder=mp3,flac \
  83               --disable-static --enable-shared --disable-autodetect \
  84               --enable-small --target-os=linux --arch=arm --enable-cross-compile \
  85               --cc=$HOME/.mozbuild/android-ndk-r20/toolchains/llvm/prebuilt/darwin-x86_64/bin/armv7a-linux-androideabi16-clang
  86
  87 config_android64.h, config_androidx86_64.h: substitute with aarch64 and the right compiler.
  88
  89 For config_androidx86_64.h, enable vp8 and vp9.
  90
  91 # Windows
  92
  93 The general idea is to get an msys prompt with an msvc toolchain
  94 configured, so that the configure script for ffmpeg can run successfully
  95 with the thread flavor Gecko prefers on Windows (win32, not pthreads).
  96
  97 - Open Visual Studio (2019 when writing this)
  98 - Tools → Command Line → Developer command prompt
  99 - Check that compiling a small C program with cl.exe works
 100 - Install msys2 from https://www.msys2.org/
 101 - From the Visual Studio Developer Command Prompt, run the following:
 102     > C:\msys64\msys_shell.cmd -mysy -use-full-path
 103 - This pops up a new shell window, with a 32-bits build environment
 104 - Check that compiling a small C program with `cl.exe` works
 105 - Run ffmpeg's ./configure with the options needed:
 106
 107 > ./configure --disable-all --enable-avcodec
 108               --enable-decoder=vp8,vp9,mp3,flac --enable-parser=vp8,vp9
 109               --disable-static --enable-shared --disable-autodetect
 110               --enable-w32threads --toolchain=msvc
 111
 112 - Copy `config.h` and `config.asm` as `config_win32.h` and `config_win32.asm`
 113   in this directory
 114 - Close the `msys2` window, go back to the `cmd.exe` window
 115 - Run this command, maybe substituting the Visual Studio version:
 116
 117 > "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64
 118
 119 - This pops up a new shell window, now with a 64-bits build
 120   environment
 121 - Check that compiling a small C program with `cl.exe` works
 122 - Run ffmpeg's `./configure` with the options needed:
 123
 124 > ./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9,mp3,flac
 125               --enable-parser=vp8,vp9 --disable-static --enable-shared
 126               --disable-autodetect --enable-w32threads --toolchain=msvc
 127
 128 - Copy `config.h` and `config.asm` as `config_win64.h` and `config_win64.asm`.
 129
 130 config_aarch64_win64.h: You will need to install cpp (either using msys or
 131 wsl), then:
 132
 133 > ./configure --disable-all --enable-avcodec --enable-decoder=vp8,vp9,mp3,flac \
 134               --enable-parser=vp8,vp9 --disable-static --enable-shared \
 135               --disable-autodetect  --toolchain=msvc --enable-cross-compile \
 136               --target-os=win32 --arch=arm64
 137
 138
 139 # Finally
 140
 141 Run the following command on all config* file:
 142
 143 > sed -i -E '/HAVE_(MALLOC_H|ARC4RANDOM|LOCALTIME_R|MEMALIGN|POSIX_MEMALIGN)/d' config.*
 144
 145 to avoid redefined macros.
 146
 147 # Build, fix errors
 148
 149 Missing files need to be added, and the patch to rename `time.h` to `fftime.h`
 150 might need to be reaplied or extended to other files including `time.h`. The
 151 issue being that it's included instead of the system header, causing all sorts
 152 of issues.
 153
 154 `moz.build` files might need to be modified as well, in light of compilation
 155 and link errors.
 156
 157 There are going to be a lot of changes in terms of symbols exported. Adjust
 158 `libavutil/avutil.symbols` and `libavcodec/avcodec.symbols` by removing and
 159 adding symbols until the build passes.
 160
 161 Finally, apply the patch:
 162 - no-unicode-stdio.patch to avoid passing the infity symbol in unicode to an
 163   stdio.h function, that causes bug 1879740 issue on Windows.