From 719639c7f122ab5f59d1d276d34c8163a30cfe0d Mon Sep 17 00:00:00 2001 From: "yilun.zhang" Date: Thu, 31 Aug 2023 13:25:58 +0800 Subject: [PATCH 1/4] update instructions for reference software --- code/CMakeLists.txt | 2 +- code/README.md | 312 +++++++++++------- .../cmake/toolchains/x86_64-mingw-gcc.cmake | 23 ++ code/src/iamf_dec/m2m_rdr.c | 5 + code/test/tools/iamfplayer/CMakeLists.txt | 4 +- 5 files changed, 232 insertions(+), 114 deletions(-) create mode 100755 code/build/cmake/toolchains/x86_64-mingw-gcc.cmake diff --git a/code/CMakeLists.txt b/code/CMakeLists.txt index c3f790ed..e5ac76ce 100755 --- a/code/CMakeLists.txt +++ b/code/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.5.1) +cmake_minimum_required(VERSION 3.6) project (iamf) message(STATUS "start build iamf") diff --git a/code/README.md b/code/README.md index 0a0385dc..87bad4fa 100755 --- a/code/README.md +++ b/code/README.md @@ -1,131 +1,221 @@ -This library aims to be a friendly, portable C implementation of the immersive audio model and format(IAMF), -as described here: +README.md +========= +# [IAMF](https://aomediacodec.github.io/iamf/) Library - +## Contents +1. [Building the lib](#Building-the-library) + - [Prerequisites](#Prerequisites) + - [Get the code](#Get-the-code) + - [Basics](#Basic-build) + - [Configuration options](#Configuration-options) + - [Dylib builds](#Dylib-builds) + - [Cross compiling](#Cross-compiling) + - [MSVC builds](#Microsoft-Visual-Studio-builds) +2. [Testing the library](#Testing-the-IAMF) + - [Build application](#1-Build-application) + - [Decoder tests](#2-Decoder-tests) +3. [Coding style](#Coding-style) +4. [Bug reports](#Bug-reports) +5. [License](#License) +## Building the library -## Usage - -Please see the examples in the "test/tools" directory. If you're already building this project. - -### Compiling -There are 2 parts to build: iamf(common&iamf_dec) tool(iamfplayer). - -"build.sh" is an example to build, you can run it directly at your side. - -1. build iamf in "src" directory. -```sh -% BUILD_LIBS=$PWD/build_libs -% cmake ./ -DCMAKE_INSTALL_PREFIX=${BUILD_LIBS} -DBINAURALIZER=ON -% make -% make install -``` - -2. build tool in "test/tools/iamfplayer" directory -```sh -% cmake ./ -DCMAKE_INSTALL_PREFIX=${BUILD_LIBS} -DBINAURALIZER=ON -% make -``` - -Remark: please ensure that they have same CMAKE_INSTALL_PREFIX. - - -### Tools(iamfplayer) -This tool aims to decode IA bitstream and dump to wav file. - -`If want to run binaural cases, please download 'default.tf' file from this link: https://github.com/ebu/bear/releases/download/v0.0.1-pre/default.tf` -```sh -./iamfplayer -options: --i[0-1] 0 : IAMF bitstream input.(default) - 1 : mp4 input. --o2 2 : pcm output. --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) - b : Binaural. --p [dB] : Peak threshold in dB. --l [LKFS] : Normalization loudness in LKFS. --d [bit] : Bit depth of pcm output. --mp [id] : Set mix presentation id. --m : Generate a metadata file with the suffix .met. --disable_limiter - : Disable peak limiter. - -Example: ./iamfplayer -o2 -s9 simple_profile.iamf - ./iamfplayer -i1 -o2 -s9 simple_profile.mp4 - -``` - - -## Build Notes - -1) Building this project requires [CMake](https://cmake.org/). - -2) Building this project requires opus or aac or flac library, please ensure that there are library in "dep_codecs/lib", -and there are headers in "dep_codecs/include" already. If not, please build(patch_script.sh) and install in advance. +### Prerequisites + 1. [CMake](https://cmake.org) version 3.6 or higher. + 2. [Git](https://git-scm.com/). + 3. Building the libiamf requires dependent audio codec libraries: [opus](https://downloads.xiph.org/releases/opus/opus-1.4.tar.gz) [fdk-aac](https://people.freedesktop.org/~wtay/fdk-aac-free-2.0.0.tar.gz) [flac](https://downloads.xiph.org/releases/flac/flac-1.4.2.tar.xz) + 4. Enabling the binaural rendering in libiamf requires external libraries: [bear](https://github.com/ebu/bear) [resonance-audio](https://github.com/resonance-audio/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 libriaries complied under x64 linux have been provided in advance) + +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 `BINAURALIZER`. +~~~ + $ cmake ./ -DBINAURALIZER=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 IAMF 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 IAMF CMake build handles +cross compiling via the use of toolchain files included in the AV1 repository. +The toolchain files available at the time of this writing are: + +- x86_64-mingw-gcc.cmake + +NOTE: Only x86_64 mingw cross compiling is available currently, in a future version we can consider adding more. +Please note that all dependent codec and external libraries should have been cross compiling already. + +The following example demonstrates use of the x86_64-mingw-gcc.cmake toolchain file on +a x86\_64 Windows host: + +~~~ + $ cmake ./ -DCMAKE_TOOLCHAIN_FILE=build/cmake/toolchains/x86_64-mingw-gcc.cmake + $ make +~~~ + +### Microsoft Visual Studio builds + +Building the IAMF library in Microsoft Visual Studio is supported. Visual +Studio 2015 (14.0) solution has been provided. + +Open win32/VS2015/iamf.sln directly. + +## Testing the IAMF + +### 1. Build application + +iamfplayer is is a test application used to decode IAMF bitstream or mp4 file which is IAMF encapsulation. +~~~ + $ cd test/tools/iamfplayer + + $ cmake -DCMAKE_INSTALL_PREFIX=${BUILD_LIBS} . + # ${BUILD_LIBS} is the iamf library and header files installing directory. + # If enable binaural rendering, add option `BINAURALIZER` + + $ make +~~~ + +### 2. Decoder tests + +If want to run binaural cases, please download [default.tf](https://github.com/ebu/bear/releases/download/v0.0.1-pre/default.tf) file into your executing directory. +~~~ + ./iamfplayer + options: + -i[0-1] 0 : IAMF bitstream input.(default) + 1 : mp4 input. + -o2 2 : pcm output. + -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) + b : Binaural. + -p [dB] : Peak threshold in dB. + -l [LKFS] : Normalization loudness in LKFS. + -d [bit] : Bit depth of pcm output. + -mp [id] : Set mix presentation id. + -m : Generate a metadata file with the suffix .met. + -disable_limiter + : Disable peak limiter. + + Example: ./iamfplayer -o2 -s9 simple_profile.iamf + ./iamfplayer -i1 -o2 -s9 simple_profile.mp4 +~~~ + +## Coding style + +We are using the Google C Coding Style defined by the +[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). + +The coding style used by this project is enforced with clang-format using the +configuration contained in the +[.clang-format](https://chromium.googlesource.com/webm/aom/+/main/.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](https://github.com/AOMediaCodec/libiamf/issues/list). ## License -Released under the BSD License. +~~~ + BSD 3-Clause Clear License The Clear BSD License -```markdown + Copyright (c) 2022, Alliance for Open Media -BSD 3-Clause Clear License The Clear BSD License + All rights reserved. -Copyright (c) 2022, Alliance for Open Media + 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: -All rights reserved. + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. -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: + 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. -1. Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. + 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. -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. -``` + 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. - -```markdown - -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) -``` +~~~ + 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) +~~~ \ No newline at end of file diff --git a/code/build/cmake/toolchains/x86_64-mingw-gcc.cmake b/code/build/cmake/toolchains/x86_64-mingw-gcc.cmake new file mode 100755 index 00000000..ec64a9f0 --- /dev/null +++ b/code/build/cmake/toolchains/x86_64-mingw-gcc.cmake @@ -0,0 +1,23 @@ +# +# Copyright (c) 2017, Alliance for Open Media. All rights reserved +# +# This source code is subject to the terms of the BSD 2 Clause License and the +# Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License was +# not distributed with this source code in the LICENSE file, you can obtain it +# at www.aomedia.org/license/software. If the Alliance for Open Media Patent +# License 1.0 was not distributed with this source code in the PATENTS file, you +# can obtain it at www.aomedia.org/license/patent. +# +set(CMAKE_SYSTEM_PROCESSOR "x86_64") +set(CMAKE_SYSTEM_NAME "Windows") + +if("${CROSS}" STREQUAL "") + set(CROSS x86_64-w64-mingw32-) +endif() + +set(CMAKE_C_COMPILER ${CROSS}gcc) +set(CMAKE_CXX_COMPILER ${CROSS}g++) +set(CMAKE_RC_COMPILER ${CROSS}windres) +set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) +set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) +set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) \ No newline at end of file diff --git a/code/src/iamf_dec/m2m_rdr.c b/code/src/iamf_dec/m2m_rdr.c index 74e98472..17f277c0 100755 --- a/code/src/iamf_dec/m2m_rdr.c +++ b/code/src/iamf_dec/m2m_rdr.c @@ -25,6 +25,11 @@ 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. */ +/* +AOM-IAMF Standard Deliverable Status: +The following function is out of scope and not part of the IAMF Final Deliverable. +*/ + /** * @file m2m_rdr.c * @brief Multichannels to Multichannels rendering. diff --git a/code/test/tools/iamfplayer/CMakeLists.txt b/code/test/tools/iamfplayer/CMakeLists.txt index 3dd2c9e9..ee78a492 100755 --- a/code/test/tools/iamfplayer/CMakeLists.txt +++ b/code/test/tools/iamfplayer/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.1) +cmake_minimum_required(VERSION 3.6) project (iamfplayer) @@ -33,8 +33,8 @@ include_directories( ${INCLUDE_DEP_EXTERNAL_WAV_DIR} ) link_directories( - ${LIB_DIR} ${LIB_DIR}/binaural + ${LIB_DIR} ) From ef95a4e63f0928c262fbc3091859c353d2277f91 Mon Sep 17 00:00:00 2001 From: sunghee-hwang <97494915+sunghee-hwang@users.noreply.github.com> Date: Fri, 1 Sep 2023 10:28:24 +0900 Subject: [PATCH 2/4] Apply the suggestion from code review --- code/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/README.md b/code/README.md index 87bad4fa..da5e00ac 100755 --- a/code/README.md +++ b/code/README.md @@ -115,7 +115,7 @@ iamfplayer is is a test application used to decode IAMF bitstream or mp4 file wh ### 2. Decoder tests -If want to run binaural cases, please download [default.tf](https://github.com/ebu/bear/releases/download/v0.0.1-pre/default.tf) file into your executing directory. +To produce binaural output, please download the following file and place it in your working directory [default.tf](https://github.com/ebu/bear/releases/download/v0.0.1-pre/default.tf). ~~~ ./iamfplayer options: From b0f88283fa5fd4e828cb2d30cedc8a3285a437b4 Mon Sep 17 00:00:00 2001 From: sunghee-hwang <97494915+sunghee-hwang@users.noreply.github.com> Date: Fri, 1 Sep 2023 10:28:34 +0900 Subject: [PATCH 3/4] Apply the suggestion from code review --- code/src/iamf_dec/m2m_rdr.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/src/iamf_dec/m2m_rdr.c b/code/src/iamf_dec/m2m_rdr.c index 17f277c0..883ccda9 100755 --- a/code/src/iamf_dec/m2m_rdr.c +++ b/code/src/iamf_dec/m2m_rdr.c @@ -27,7 +27,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /* AOM-IAMF Standard Deliverable Status: -The following function is out of scope and not part of the IAMF Final Deliverable. +This software module is out of scope and not part of the IAMF Final Deliverable. */ /** From 8e313304d21ea72e497168f9f028091a1294c661 Mon Sep 17 00:00:00 2001 From: yilun-zhangs <105910509+yilun-zhangs@users.noreply.github.com> Date: Fri, 1 Sep 2023 10:05:07 +0800 Subject: [PATCH 4/4] Apply the suggestion from code review --- code/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/code/README.md b/code/README.md index fe11a3f0..bec2b9d4 100755 --- a/code/README.md +++ b/code/README.md @@ -100,9 +100,10 @@ Open win32/VS2015/iamf.sln directly. ## Testing the IAMF +The iamfplayer is a test application to decode an IAMF bitstream or mp4 file with IAMF encapsulation. + ### 1. Build application -iamfplayer is is a test application used to decode IAMF bitstream or mp4 file which is IAMF encapsulation. ~~~ $ cd test/tools/iamfplayer @@ -219,4 +220,4 @@ source software listed below is not considered to be part of the IAMF Final Deli 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) -~~~ \ No newline at end of file +~~~