Skip to content

Commit

Permalink
Merge pull request #59 from yilun-zhangs/main
Browse files Browse the repository at this point in the history 
update instructions for reference software
  • Loading branch information
@sunghee-hwang
sunghee-hwang authored Sep 1, 2023
2 parents 1477de6 + 8e31330 commit 4268648
Show file tree
Hide file tree
Showing 5 changed files with 229 additions and 110 deletions.
2 changes: 1 addition & 1 deletion code/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
cmake_minimum_required(VERSION 3.5.1)
cmake_minimum_required(VERSION 3.6)

project (iamf)
message(STATUS "start build iamf")
Expand Down
305 changes: 198 additions & 107 deletions code/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,132 +1,223 @@
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

<https://aomediacodec.github.io/iamf/>
## 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
### 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

The iamfplayer is a test application to decode an IAMF bitstream or mp4 file with IAMF encapsulation.

### 1. Build application

~~~
$ 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

Please see the examples in the "test/tools" directory. If you're already building this project.
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> <input file>
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

### Compiling
There are 2 parts to build: iamf(common&iamf_dec) tool(iamfplayer).
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.

"build.sh" is an example to build, you can run it directly at your side.
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]')
~~~

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> <input file>
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.
## 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.

```markdown
~~~
BSD 3-Clause Clear License The Clear BSD License
BSD 3-Clause Clear License The Clear BSD License
Copyright (c) 2022, Alliance for Open Media
Copyright (c) 2022, Alliance for Open Media
All rights reserved.
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:
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.
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.
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.
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. The open
source software listed below is not considered to be part of the IAMF Final Deliverable.


```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)
~~~
23 changes: 23 additions & 0 deletions code/build/cmake/toolchains/x86_64-mingw-gcc.cmake
View file
Original file line number Diff line number Diff line change
@@ -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)
5 changes: 5 additions & 0 deletions code/src/iamf_dec/m2m_rdr.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
This software module is out of scope and not part of the IAMF Final Deliverable.
*/

/**
* @file m2m_rdr.c
* @brief Multichannels to Multichannels rendering.
Expand Down
4 changes: 2 additions & 2 deletions code/test/tools/iamfplayer/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
cmake_minimum_required(VERSION 3.1)
cmake_minimum_required(VERSION 3.6)

project (iamfplayer)

Expand Down Expand Up @@ -33,8 +33,8 @@ include_directories(
${INCLUDE_DEP_EXTERNAL_WAV_DIR}
)
link_directories(
${LIB_DIR}
${LIB_DIR}/binaural
${LIB_DIR}
)


Expand Down

0 comments on commit 4268648

Please sign in to comment.