-
Notifications
You must be signed in to change notification settings - Fork 0
MPEG–H support in FFmpeg
FFmpeg has bindings for the Fraunhofer MPEG-H Decoder. Below you will find build instructions on how to compile and link it with FFmpeg. This will result in both, ffmpeg / ffplay executables that support decoding and rendering of MPEG-H Audio content, as well as libavcodec that can handle MPEG-H Audio bitstreams.
When building a player that takes full advantage of the MPEG-H feature set, the MPEG-H UI Manager is required. Details on how to access the UI-Manager inside an FFmpeg environment, together with code samples can be found in further considerations
These build instructions are for Linux systems and assume system-wide installation in default locations. If you are using a different setup, you might have to adjust your linker accordingly, e.g. by setting $LD_LIBRARY_PATH or $LD_PRELOAD.
In the CMake configuration step, additionally set the following variables:
-DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
After completing the build step, install the shared library and header files:
$ cmake --install build_linux
Optionally, the installation prefix can be changed, by either setting the variable -DCMAKE_INSTALL_PREFIX=<prefix> in the CMake configuration step or setting the path via --prefix <prefix> in the above CMake installation command. On most Linux systems, the default installation prefix path is /usr/local.
- Download the latest FFmpeg source code:
$ git clone --depth=1 https://code.ffmpeg.org/FFmpeg/FFmpeg.git
- Configure the FFmpeg build with the libmpeghdec decoder enabled:
$ cd FFmpeg
$ ./configure --disable-gpl --enable-libmpeghdec
If the libmpeghdec module was configured correctly, it is listed in the Enabled decoders section of the configuration script output.
NOTE: If the mpeghdec shared library was not installed in the default location or the FFmpeg configuration script cannot find the shared library, the path to the installed pkgconfig-file may need to be explicitly specified, e.g.:
$ PKG_CONFIG_PATH=<prefix>/pkgconfig/ ./configure --disable-gpl --enable-libmpeghdec
- Build FFmpeg
$ make -j
The libmpeghdec module requires the output speaker layout to be set. This can be done by specifying the -ch_layout option in the FFmpeg command line.
The list of channel layouts supported by FFmpeg in general can be listed with ./ffmpeg -layouts.
Example command line to decode an MP4 file containing MPEG-H 3D Audio to a stereo WAV file:
$ ./ffmpeg -ch_layout stereo -i <input_file>.mp4 <output_file>.wav
If the mpeghdec shared library was not installed in the default location or the FFmpeg binary cannot find it, the path to the shared library may need to be explicitly specified, e.g.:
$ LD_LIBRARY_PATH=<prefix>/lib/ ./ffmpeg -ch_layout stereo -i <input_file>.mp4 <output_file>.wav
The libmpeghdec module only supports some of these channel layouts, namely the ones matching the supported CICP indices. The table below summarizes the mapping of CICP channel layout to the nomenclature used by FFmpeg.
| CICP | AVChannelLayout | -ch_layout |
|---|---|---|
| 1 | AV_CHANNEL_LAYOUT_MONO | mono |
| 2 | AV_CHANNEL_LAYOUT_STEREO | stereo |
| 3 | AV_CH_LAYOUT_SURROUND | 3.0 |
| 4 | AV_CH_LAYOUT_4POINT0 | 4.0 |
| 5 | AV_CH_LAYOUT_5POINT0 | 5.0 (side) |
| 6 | AV_CH_LAYOUT_5POINT1 | 5.1 (side) |
| 7 | AV_CH_LAYOUT_7POINT1_WIDE | 7.1 (wide-side) |
| 9 | AV_CH_LAYOUT_2_1 | 3.0 (back) |
| 10 | AV_CH_LAYOUT_2_2 | quad (side) |
| 11 | AV_CH_LAYOUT_6POINT1 | 6.1 |
| 12 | AV_CH_LAYOUT_7POINT1 | 7.1 |
| 13 | AV_CH_LAYOUT_22POINT2 | 22.2 |
| 14 | AV_CH_LAYOUT_5POINT1POINT2 | 5.1.2 |
| 15 | Internal format | 12 channels (FL+FR+FC+LFE+SL+SR+TFL+TFR+TBC+LFE2+SSL+SSR) |
| 16 | AV_CH_LAYOUT_5POINT1POINT4_BACK | 5.1.4 |
| 17 | Internal format | 12 channels (FL+FR+FC+LFE+SL+SR+TC+TFL+TFC+TFR+TBL+TBR) |
| 18 | Internal format | 14 channels (FL+FR+FC+LFE+BL+BR+SL+SR+TC+TFL+TFC+TFR+TBL+TBR) |
| 19 | AV_CH_LAYOUT_7POINT1POINT4_BACK | 7.1.4 |
Note: The internal formats are non-default to FFmpeg and do not have a proper name.
Access to the MPEG-H Audio UI-Manager requires functions that are not part of the FFmpeg API. The contents of an MPEG-H Audio AVPacket needs to be passed to the UI-Manager via mpegh_UI_FeedMHAS(), which is part of the mpeghdec API. Manipulating the UI then happens directly on this API and then gets forwarded to the FFmpeg decoder through avcodec_send_packet(). These steps embed MHAS interactivity packets into the compressed audio bitstream and can be processed by the decoder.
A detailed example is provided in examples/ffmpeg.