9.5 KiB
README.md
IAMF Library
Contents
Building the library
Prerequisites
- CMake version 3.6 or higher.
- Git.
- Building the libiamf requires dependent audio codec libraries: opus fdk-aac flac
- Enabling the binaural rendering in libiamf requires external libraries: bear resonance-audio
Get the code
The IAMF library source code is stored in the Alliance for Open Media Git repository:
$ git clone https://github.com/AOMediaCodec/libiamf
# By default, the above command stores the source in the libiamf/code directory:
$ cd libiamf/code
Basic build
"build.sh" is an example to build, you can run it directly at your side.
(dependent codec libraries and external libraries complied under x64 linux have been provided in advance,
if compile other platform versions, please refer to dependent codecs and dependent externals)
CMake replaces the configure step typical of many projects. Running CMake will produce configuration and build files for the currently selected CMake generator. For most systems the default generator is Unix Makefiles. The basic form of a makefile build is the following:
$ cmake .
$ make
Configuration options
The IAMF library has few configuration options, There are one option which is used to enable binaural rendering:
Build binaural rendering configuration options. These have the form MULTICHANNEL_BINAURALIZER and HOA_BINAURALIZER.
(If binaural rendering is not enabled, there is no need to provide external libraries)
$ cmake ./ -DMULTICHANNEL_BINAURALIZER=ON -DHOA_BINAURALIZER=ON
$ make
Dylib builds
A dylib (shared object) build of the IAMF library is enabled by default.
$ cmake .
$ make
Cross compiling
For the purposes of building the codec and applications and relative to the scope of this guide, all builds for architectures differing from the native host architecture will be considered cross compiles. The CMake build handles cross compiling via the use of toolchain files included in the repository. The toolchain files available at the time of this writing are:
- arm64-ios.cmake
- arm64-linux.cmake
- x86_64-mingw.cmake
- x86-macos.cmake
Please note that all dependent codecs and dependent externals should have been cross compiled already.
The following example demonstrates use of the x86-macos.cmake toolchain file on a x86_64 MacOS host:
$ cmake ./ -DCMAKE_TOOLCHAIN_FILE=build/cmake/toolchains/x86-macos.cmake
$ make
Microsoft Visual Studio builds
Building the IAMF library in Microsoft Visual Studio is supported. Visual Studio 2022(v143) solution has been provided.
Open win64/VS2022/iamf.sln directly.
MacOS builds
Please note that all dependent codecs and dependent externals should have been MacOS compiled already.
$ cmake .
$ make
Testing the IAMF
The iamfdec is a test application to decode an IAMF bitstream or mp4 file with IAMF encapsulation.
1. Build application
$ cd test/tools/iamfdec
$ cmake -DCMAKE_INSTALL_PREFIX=${BUILD_LIBS} .
# ${BUILD_LIBS} is the iamf library and header files installing directory.
# If enable binaural rendering, add option `MULTICHANNEL_BINAURALIZER` and `HOA_BINAURALIZER`
$ make
2. Decoder tests
To produce binaural output, please download the following file and place it in your working directory default.tf.
./iamfdec <options> <input file>
options:
-i[0-1] 0 : IAMF bitstream input.(default)
1 : MP4 input.
-o[2-3] 2 : WAVE output, same path as binary.(default)
3 [path]
: WAVE output, user setting path.
-r [rate] : Audio signal sampling rate, 48000 is the default.
-s[0~11,b] : Output layout, the sound system A~J and extensions (Upper + Middle + Bottom).
0 : Sound system A (0+2+0)
1 : Sound system B (0+5+0)
2 : Sound system C (2+5+0)
3 : Sound system D (4+5+0)
4 : Sound system E (4+5+1)
5 : Sound system F (3+7+0)
6 : Sound system G (4+9+0)
7 : Sound system H (9+10+3)
8 : Sound system I (0+7+0)
9 : Sound system J (4+7+0)
10 : Sound system extension 712 (2+7+0)
11 : Sound system extension 312 (2+3+0)
12 : Sound system mono (0+1+0)
13 : Sound system extension 916 (6+9+0)
b : Binaural.
-p [dB] : Peak threshold in dB.
-l [LKFS] : Normalization loudness(<0) in LKFS.
-d [bit] : Bit depth of WAVE output.
-mp [id] : Set mix presentation id.
-m : Generate a metadata file with the suffix .met.
-disable_limiter
: Disable peak limiter.
Example: ./iamfdec -o2 -s9 simple_profile.iamf
./iamfdec -i1 -o2 -s9 simple_profile.mp4
./iamfdec -i1 -o3 /tmp/out.wav -s9 simple_profile.mp4
Coding style
We are using the Google C Coding Style defined by the Google C++ Style Guide.
The coding style used by this project is enforced with clang-format using the configuration contained in the .clang-format file in the root of the repository.
Before pushing changes for review you can format your code with:
# Apply clang-format to modified .c, .h files
$ clang-format -i --style=file \
$(git diff --name-only --diff-filter=ACMR '*.[hc]')
Bug reports
Bug reports can be filed in the Alliance for Open Media issue tracker.
License
BSD 3-Clause Clear License The Clear BSD License
Copyright (c) 2022, Alliance for Open Media
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted (subject to the limitations in the disclaimer below) provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the distribution.
3. Neither the name of the Alliance for Open Media nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This IAMF reference software decoder uses the following open source software. Each open source software complies with its respective license terms, and the license files have been stored in a directory with their respective source code or library used. The open source software listed below is not considered to be part of the IAMF Final Deliverable.
https://downloads.xiph.org/releases/opus/opus-1.4.tar.gz (code/dep_codecs/lib/opus.license)
https://people.freedesktop.org/~wtay/fdk-aac-free-2.0.0.tar.gz (code/dep_codecs/lib/fdk_aac.license)
https://downloads.xiph.org/releases/flac/flac-1.4.2.tar.xz (code/dep_codecs/lib/flac.license)
https://svn.xiph.org/trunk/speex/libspeex/resample.c (code/src/iamf_dec/resample.license)
https://github.com/BelledonneCommunications/opencore-amr/blob/master/test/wavwriter.c (code/dep_external/src/wav/dep_wavwriter.license)