*************************** MPEG-H 3D Audio Coder - Edition 3.0 ****************************
*                                                                                          *
*                       MPEG-H 3D Audio Reference Software - readme                        *
*                                                                                          *
*                                        2019-03-20                                        *
*                                                                                          *
********************************************************************************************


(1) Content of this package
============================================================================================
 - MPEG-H 3D Audio reference software containing the combined channel/object (CO) and
   higher order ambisonics (HOA) path written in ANSI C/C++ (CO-Part) and C++11 (HOA-Part)
 - Makefiles/project files for Linux/Mac and Microsoft Visual Studio 2012


(2) Requirements to successfully build and run the reference software
============================================================================================
 - Additional software packages:
   . AFsp Audio File Programs and Routines
   . ISOBMFF reference software (libisomediafile)
   . MPEG-D DRC reference software
 - Linux/Mac:
   . GNU make
   . gcc 4.4.5 or higher with C++11 support
 - Windows:
   . Microsoft Visual Studio 2012
   . Microsoft Windows SDK
   . for compatibility to older Microsoft Visual Studio versions see (3)(d)


(2.1) Installing AFsp File Programs and Routines
============================================================================================
(a) General instructions:
-------------------------

 To provide support for a variety of audio file formats, the MPEG-H 3D Audio reference
 software uses the AFsp package for audio file i/o and resampling. The AFsp
 package is written by Prof. Peter Kabal <peter.kabal@mcgill.ca> and is
 available via download:

 required version:  AFsp-v9r0.tar.gz
 download site:     http://www.mmsp.ece.mcgill.ca/Documents/Downloads/AFsp/

 NOTE: Make sure to use version v9r0 (AFsp-v9r0.tar.gz)!

 Unpack the downloaded file and copy/paste the whole AFsp content into the folder
 ./tools/AFsp/

 - such that MSVC.sln is located at:
   ./tools/AFsp/MSVC/MSVC.sln

 - and such that the Unix makefile "Makefile" is located at:
   ./tools/AFsp/Makefile

 For more details, see ./tools/AFsp/readme.txt.

(b) Build the libtsplite library:
---------------------------------

 The AFsp library will be build automatically together with the MPEG-H 3D Audio
 reference software on all platforms.


(2.2) Installing MPEG-4 Base Media File Format (ISOBMFF) software
============================================================================================
(a) General instructions:
-------------------------

 The ISO Base Media File Format (ISOBMFF) is an integral part of the MPEG-H 3D Audio
 reference  software. It provides the interface to the mp4 container in which the MPEG-H
 3D Audio streams are embedded. The ISOBMFF is standardized in ISO/IEC 14996-12 and hosted on
 GitHub.

 GitHub space:      https://github.com/MPEGGroup/isobmff
 download site:     https://github.com/MPEGGroup/isobmff/archive/master.zip

 Unpack the downloaded file and copy/paste the sub-directory
 ./isobmff-master/IsoLib/libisomediafile into the folder ./tools/IsoLib/

 - such that the corresponding VS2008 solution libisomedia.sln is located at:
   ./tools/IsoLib/libisomediafile/w32/libisomediafile/VS2008/libisomedia.sln

 - and such that the corresponding VS2012 solution libisomedia.sln is located at:
   ./tools/IsoLib/libisomediafile/w32/libisomediafile/VS2012/libisomedia.sln

 - and such that the corresponding UNIX makefile "Makefile" is located at:
   ./tools/IsoLib/libisomediafile/linux/libisomediafile/Makefile

 For more details, see ./tools/IsoLib/readme.txt.

 NOTE: In order to download the software a GitHub account is required!
 NOTE: The ISOBMFF software can also be automatically installed, see (3)(d).

(b) Build the MPEG-4 FF reference software:
-------------------------------------------

 The MPEG-4 FF reference software will be build automatically together with the
 MPEG-D USAC Audio reference software on all platforms.


(2.3) Installing MPEG-D DRC reference software
============================================================================================
(a) General instructions:
-------------------------

Copy the unzipped folder /MPEG_D_DRC_refsoft from ISO/IEC 23003-4:2015/Amd 2 (DRC Reference 
Software) into the folder
 ./modules/drcCoder/

 - such that the corresponding compile.bat is located at:
   ./modules/drcCoder/MPEG_D_DRC_refsoft/scripts/compile.bat

 - and such that corresponding compile.sh is located at:
   ./modules/drcCoder/MPEG_D_DRC_refsoft/scripts/compile.sh

 For more details, see ./modules/drcCoder/readme.txt.

(b) Build the MPEG-D DRC reference software:
--------------------------------------------

 The MPEG-D DRC reference software will be build automatically together with the
 MPEG-H 3D Audio reference software on all platforms.


(3) MPEG-H 3D Audio Reference Software build instructions
============================================================================================
(a) Linux/Mac:
--------------

 - Install AFsp and MPEG-D DRC reference software as explained above.
 - Set access permissions if required.
 - Change directory into scripts folder (cd ./scripts).
 - Execute ./compile.sh to automatically compile all modules and tools.
 - Change directory into ./executables_* folder and check if all 44 files are listed (ls -l).

(b) Windows:
------------

 - Install AFsp and MPEG-D DRC reference software as explained above.
 - Make sure that the environment variable VS110COMNTOOLS is present and set according
   to your Visual Studio 2012 installation.
 - Change directory into scripts folder (cd scripts).
 - Execute .\compile.bat to automatically compile all modules and tools.
 - Change directory into .\executables_* folder and check if all 44 files are listed (dir).

(c) general notes:
------------------

 NOTE: A successful build will exit with code 0 and show the message:
       "Build successful."
       A failed build will exit with code 1 and show the message:
       "Build failed."
 NOTE: The path of the MPEG-H 3D Audio reference software directory must not
       contain any white spaces!
 NOTE: To compile single modules open compile.bat/compile.sh to see how single modules are
       compiled.

(d) build options (advanced users):
-----------------------------------

 The Unix compile script (compile.sh) features the following options:
 - ./compile.sh Clean   : The "Clean" option deletes all intermediate files, libraries
                          and executables which were created during the build process.
 - ./compile.sh Release : The "Release" option build the MPEG-H 3D Audio reference software
                          in release mode such that compiler specific optimizations are used.
 - ./compile.sh c89     : The "c89" option builds the MPEG-H 3D Audio reference software in
                          a C89 compliant mode. Please see (3)(e)!
 - ./compile.sh co      : Checkout required software such as the libisomediafile. A GitHub
                          account and a installed SVN and/or GIT software is required to use
                          this option! The additional options "SVN" and "GIT" may be used to
                          determine the version control management system to use, e.g.
                          ./compile.sh co GIT
                          Default: SVN

 The Windows compile script (compile.bat) features the following options:
 - compile.bat x64      : The "x64" option builds the MPEG-H 3D Audio reference software for
                          64-bit Windows operating systems. Default is Win32 (32-bit).
 - compile.bat Release  : The "Release" option build the MPEG-H 3D Audio reference software
                          in release mode such that compiler specific optimizations are used.
 - compile.bat VS2008   : The "VS2008" option builds the MPEG-H 3D Audio reference software
                          using the Microsoft Visual Studio 2008 compiler. Please see (3)(e)!
 - compile.bat co       : Checkout required software such as the libisomediafile. A GitHub
                          account and a installed SVN and/or GIT software is required to use
                          this option! The additional options "SVN" and "GIT" may be used to
                          determine the version control management system to use, e.g.
                          compile.bat co GIT
                          Default: SVN

 NOTE: The use of these options is for advanced users. Please note that the compile scripts
       compile.sh/compile.bat are configured in a way to fit the conformance requirements.
       Use any of these options at your own risk.

(e) compatibility to previous compiler versions (advanced users):
-----------------------------------------------------------------

 The MPEG-H reference software is in parts backward compatible to older compiler versions:
 - Linux/Mac
   . gcc 3.3.5 or higher
   . In order to run the compatibility mode, call: ./compile.sh c89
 - Windows
   . Microsoft Visual Studio Studio 2008 (requires environment variable VS90COMNTOOLS)
   . In order to run the compatibility mode, call: ./compile.bat VS2008

 NOTE: The compatibility mode does NOT support the full MPEG-H 3D Audio functionality!
       In Particular the HOA reference software and the iar Format Converter will not
       be compiled. In total 39 executables will be build in this mode. This mode is not
       compliant to the MPEG-H 3D Audio standard (ISO/IEC 23008-3). Use this mode on your
       own risk.


(4) Quick start: Decoding using the 3DAudioDecoder
============================================================================================
 After running the appropriate compile script, change directory into executables_* folder.
 Then, call 3DAudioDecoder[.exe] without any arguments to see all available command line
 arguments.

 A typical call requires a minimum of two parameters: input file (mp4 or mhas), output file,
 e.g.:
 - Linux/Mac: ./3DAudioDecoder -if <input>.mhas -of <output>.wav
 - Windows:   3DAudioDecoder.exe -if <input>.mhas -of <output>.wav


(4.1) Example Decoding
============================================================================================
(a) Get MPEG-H 3D Audio conformance streams:
--------------------------------------------

 Download MPEG-H 3D Audio conformance streams as defined in:
   ISO/IEC 23008-9 3D Audio conformance testing

 from the ISO supplied Uniform Resource Name (URN):
   http://standards.iso.org/iso-iec/23008/-9/ed-1/en

 and put the files (*.mhas and *.wav files) e.g.:
 *.mhas in ./MPEGH_3DA_mhas folder
 *.wav in  ./MPEGH_3DA_ref folder

(b) Decode MPEG-H 3D Audio conformance streams:
-----------------------------------------------

 Change directory into executables_* folder (cd ./scripts/executables_*) and call
 3DAudioDecoder[.exe] as described above (4).
 
 NOTE: To produce decoded waveforms at a specific conformance point (Cpo-<x>), see (4.2).

(c) Compare MPEG-H 3D Audio conformance streams:
------------------------------------------------

 The correctness of the decoded output can be checked with either the  MPEG-4 conformance
 tool ssnrcd, or with the AFsp tool compAudio.

 The AFsp audio tools are located at
 - Linux/Mac: ./tools/AFsp/bin
 - Windows:   ./tools/AFsp/MSVC/bin

 Use the compAudio command for comparing two audio files:
 - Linux/Mac: ./compAudio <reference>.wav <MPEG-H_3DA_decoded>.wav
 - Windows:   compAudio.exe <reference>.wav <MPEG-H_3DA_decoded>.wav

 The ssnrcd tool is part of the MPEG-4 reference software (ISO/IEC 14496-5).
 The documentation of the MPEG-4 software describes how to build the ssnrcd tool.
 
 Use the following ssnrcd command for comparing two audio files:
 ./ssnrcd <reference>.wav <MPEG-H_3DA_decoded>.wav
 
 
(4.2) Conformance testing: Reproducing waveforms at a defined conformance point (Cpo-<x>)
============================================================================================
 In order to call 3DAudioDecoder[.exe] so as to produce decoded waveforms at a specific
 conformance point (Cpo-<x>) as defined in ISO/IEC 23008-9 3D Audio conformance testing, use
 the following decoder command line call:

 - Linux/Mac: ./3DAudioDecoder –if <input>.mhas -of <output>.wav -cpo <x>
 - Windows:   3DAudioDecoder.exe –if <input>.mhas -of <output>.wav -cpo <x>
  
 If <x> is equal to 1 the following conformance point shall be used: the output of the
 decoder before applying resampling and mixing.

 Default behavior:
 If the -cpo <x> command line switch is not specified (or if <x> is equal to 0), the
 conformance point shall be the output of the complete decoder chain.


(5) Tools overview
============================================================================================
 The reference software modules make use of different helper tools which are listed below:

 - AFsp library as described above

 - AFspCppWrap (Library/Commandline)
   . C++ wrapper for C++ interface, allows handling of AFsp raw pointer as shared pointer

 - cicp2geometry (Library/Commandline)
   . Used to convert CICP setups and CICP loudspeakers to geometry information
   . Used to convert geometry information to CICP setups
   . Used to read explicit geometry information from file
   . Used to write geometry information to file

 - fftlib (Library)
   . C-Implementation for the Fast Fourier Transform

 - libisomediafile (Library)
   . Library for reading and writing MP4 files

 - parDecorrelator (Library)
   . Library for decorrelation

 - qmflib (Library)
   . C-Implementation for QMF Analysis and Synthesis
   . C-Implementation for Hybrid Analysis and Synthesis

 - qmflibCppWrap
    . C++ wrapper for C++ interface, allows handling of qmflib raw pointer as shared pointer

 - readonlybitbuf (Library)
   . Library providing bitbuffer reading

 - separator (Library/Commandline)
   . Used to split combined channel/object multichannel wave files
   . into a multichannel wave file containing channels only
   . and multiple mono wave files containing single object tracks
   . Used to save a number of channels (starting from an offset) of
   . an input wave file to a multichannel output wave file.

 - wavCutterCmdl (Commandline)
   . Uses the wavIO library to process wave and qmf files
   . Used to cut wave files (remove/add delay in the beginning and remove flushing samples
     at the end of file)

 - wavIO (Library)
   . Library for reading and writing PCM data or qmf data into wave files

 - wavM2N (Commandline/Library)
   . Used to combine multiple mono wave files into a multichannel wave file
   . Used to split a multichannel wave file into multiple mono tracks
   . Used to combine/split object files
   . Supports the MPEG-H 3D Audio file naming convention (azimuth, elevation)

 - writeonlybitbuf (Library)
   . Library providing bitbuffer writing


(6) Modules overview
============================================================================================
 The reference software is based on different separate modules which are listed below:

 - ascParser (Commandline/Library)
   . Parser for the Audio Specific Config of an mp4 file
   . Writes optional downmix matrices into files

 - binaural
   . All modules required for Frequency-domain and Time-domain binaural processing
   . Frequency Domain Binaural Renderer (Commandline/Library)
   . Time Domain Binaural Renderer (Commandline/Library)
   . Parametrization of BRIRs for the Frequency Domain Binaural Renderer (Commandline/Library)
   . Parametrization of BRIRs for the Time Domain Binaural Renderer (Commandline/Library)
   . BRIR Bitstream Writer (Commandline/Library)

 - coreCoder (Commandline)
   . USAC Reference Software based core encoder and decoder implementation

 - decoderInterfaces
   . elementInteractionInterface
     module for reading and writing data according to the element interaction interface
   . localSetupInformationInterface
     module for reading and writing data according to the local setup information interface

 - dmxMatrixCoder (Commandline/Library)
   . Downmix Matrix En- and Decoder with optional input channel equalizers

 - domainSwitcherCmdl (Commandline)
   . Perform a QMF Analysis and Synthesis to files
   . Read/write TD files with "*.wav" input/output
   . Read/write FD files with "*_real.qmf" and "*_imag.qmf" input/output

 - drcCoder (Commandline/Library)
   . DRC module for decoding DRC sequences and applying them to the audio signal

 - dynamicObjectPriorityGenerator
   . module that generates dynamic object priority data

 - formatConverter (Commandline/Library)
   . Format Converter module converting input signals to different loudspeaker setups

 - gainDelayTrim (Shell Script Example)
   . Apply trim gains and delays to compensate for varying loudspeaker distances
   . Trim parameters are generated by the formatConverter module if
   . loudspeaker distances are input to formatConverter module

 - gVBAPRenderer (Commandline/Library)
   . Generalized VBAP Renderer Module

 - hoaCoder
   . All modules required for HOA encoding and decoding

 - hoaMatrixCoder
   . Module to encode and decode a signaled HOA rendering matrix

 - iarFormatConverter (Commandline/Library)
   . immersive format Converter module converting input signals to different loudspeaker
     setups

 - metadataPreprocessor (Library)
   . processing and parsing of metadata

 - mixer (Commandline/Library)
   . Mixer for combining two wave files (like objects and channels)
   . Offers delay adjustment between input files
   . Offers possibility to apply gains to the input files

 - oamCoder (Commandline/Library)
     Object Metadata En- and Decoder

 - saocCoder (Commandline/Library)
     Spatial Audio Object Coding En- and Decoder


(7) 3D-Audio Encoder Reference Implementation
============================================================================================
 An example reference implementation for the MPEG-H 3D-Audio Encoder can be found in

 /modules/3DAudioCoder/3DAudioEncoder

 This encoder example shows how the different modules are connected to encode
    - 22.2 channel based encoding
    - Objects based encoding
    - SAOC based object encoding
    - HOA based encoding


(8) 3D-Audio Decoder Reference Implementation
============================================================================================
 The reference implementation for the MPEG-H 3D-Audio decoder can be found in

 /modules/3DAudioCoder/3DAudioDecoder

 This decoder connects the separate modules to decode the submitted test
 bitstreams for all test points including HOA and additionally supports
 metadata decoding and object rendering. Run the 3DAudioDecoder in this
 directory because the relative paths in the binary configuration
 files in "cfg-Files" are relative to this directory. Another solution is
 to copy a config file and replace the relative paths with the absolute
 paths of your specific system.


(9) Technical Support
============================================================================================
 For technical support to build and run the MPEG-H 3D Audio reference software,
 please direct your correspondence to:
 christian.neukam@iis.fraunhofer.de
 christian.ertel@iis-extern.fraunhofer.de
 mpeg-h-3da-maintenance@iis.fraunhofer.de


(10) Revision History
============================================================================================
 See file changes.txt for a complete list of changes
