------------------------------------------------------------
README for the MPEG Surround reference software version 1.15
------------------------------------------------------------

This file contains information about the folder structure of this
package and instructions for building the MPEG Surround reference
software.

The MPEG Surround standard itself is available as ISO/IEC 23003-1.

Please note the that the encoder provided in this package is only
an informative part of the standard. The techniques used for
encoding are not specified by the standard, and the audio quality
and computational complexity of the encoder has not been optimized.


Package Description
-------------------

The MPEG Surround reference software comprises the following folders:

sac-refsoft-v1.15
|
+- conf_mps         Tools for MPEG Surround conformance
|
+- general          platform specific build switches
|
+- import           folder for external libraries, see below
|
+- mp12_mps         Tools for extracting MPEG Surround data
|                   embedded in MPEG-1/2 Layer I/II/III bitstreams
|
+- mp4mcDec         MPEG Surround decoder integrated with
|                   HE-AAC downmix decoder
|
+- mp4spatialdec    MPEG Surround decoder
|
+- mp4spatialenc    MPEG Surround encoder


Build instructions
------------------

In addition to the source code provided by this package, two libraries
are required to build the MPEG Surround reference software. These
libraries are available as source code at the locations specified
below.


The libisomedia library provides support for reading and writing MP4
files. The source code of this library is available from:

http://standards.iso.org/ittf/PubliclyAvailableStandards/c045527_ISO_IEC_14496-5_2001_Amd_12_2007_Reference_Software.zip


The AFsp library provides support for reading and writing audio files
(e.g. WAV files). The source code of this library is available from:

http://www-mmsp.ece.mcgill.ca/Documents/Software/


For the MS Visual C Compiler please build the libisomedia library 
using the same configuration(s) that shall be used for the reference 
software (Debug/Release).


After building these libraries according to the respectively included
build instructions, copy the following folders to the specified
locations inside the MPEG Surround reference software file tree:

- libisomedia library:
    mp4_file_format/libisomediafile -> sac-refsoft-v1.15/import

- AFsp library:
    include -> sac-refsoft-v1.15/import/AFsp
    lib (resp. MSVC/lib for MS Visual C compiler) -> sac-refsoft-v1.15/import/AFsp


Linux:
======

Add the following variable to your environment (shown here for csh/tcsh):

setenv ISOMP4_PATH        /<absolute_path>/sac-refsoft-v1.15/import/libisomediafile/
setenv AFSP_LIBRARY_PATH  /<absolute_path>/sac-refsoft-v1.15/import/AFsp/
setenv AFSP_INCLUDE_PATH  /<absolute_path>/sac-refsoft-v1.15/import/AFsp/include/


Use "make" to build the MPEG Surround reference software in the
respective folders.

Use "make LOW_POWER_MPS=1" to build "Low Power" versions of the decoders
and conformance tool. All low power binary names contain the suffix "_lp"
(e.g. spatialdec_lp)


For the mp12_mps tool execute the "configure" script in mp12_mps
first and then use "make" .


Windows:
========

Use the Visual Studio Workspaces (*.dsw) in the win32 subfolders of the respective folders
to build the MPEG Surround reference software.

Use the "Win32 Debug/Release Low Power" project settings to build "Low
Power" versions of the decoders and conformance tool. All low power
binary names contain the suffix "_lp" (e.g. spatialdec_lp.exe)


Usage instructions
------------------

General:
========

 All information about possible commandline paramenters can be found in the commandline help of the
 binaries using the "-h" commandline parameter.


Encoding:
=========

 Examples for encoding a 5.1 audio file with the MPEG Surround
 reference software encoder using a mono downmix:

          Windows:    spatialenc.exe -tc 5151 -ts 32 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          Linux:      spatialenc     -tc 5151 -ts 32 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          CopyAudio -l 257: downmix_tmp.wav downmix.wav

          Windows:    spatialenc.exe -tc 5151 -ts 16 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          Linux:      spatialenc     -tc 5151 -ts 16 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          CopyAudio -l 769: downmix_tmp.wav downmix.wav


 Examples for encoding a 5.1 audio file with the MPEG Surround
 reference software encoder using a stereo downmix:

          Windows:   spatialenc.exe -tc 525 -ts 32 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          Linux:     spatialenc     -tc 525 -ts 32 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          CopyAudio -l 257: downmix_tmp.wav downmix.wav

          Windows:   spatialenc.exe -tc 525 -ts 16 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          Linux:     spatialenc     -tc 525 -ts 16 -if input.wav -df downmix_tmp.wav -bf bitstream.bs
          CopyAudio -l 769: downmix_tmp.wav downmix.wav


Decoding:
=========

 Example for decoding a mono or stereo downmix and the associated MPEG
 Surround side info:

         Windows:   spatialdec.exe 0 downmix.wav bitstream.bs output.wav
         Linux:     spatialdec     0 downmix.wav bitstream.bs output.wav


 Example for decoding buried MPEG Surround data in PCM 
 (assuming 'downmix.wav' contains MPEG Surround buried data)

         Windows:   spatialdec.exe -s buried 0 downmix.wav output.wav
         Linux:     spatialdec     -s buried 0 downmix.wav output.wav


Decoding with integrated HE-AAC downmix decoder:
===============================================

 Example for decoding a HE-AAC bitsream with embedded MPEG
 Surround side info:

         Windows:   mp4spatialdec.exe -u 0 -3 input.mp4 downmix.wav output.wav
         Linux:     mp4spatialdec     -u 0 -3 input.mp4 downmix.wav output.wav


 Example for decoding an AAC bitstream with external MPEG
 Surround side info:

         Windows:   mp4spatialdec.exe input.mp4 downmix.wav dummy.wav
                    spatialdec.exe    0 downmix.wav bitstream.bs output.wav

         Linux:     mp4spatialdec     input.mp4 downmix.wav dummy.wav
                    spatialdec        0 downmix.wav bitstream.bs output.wav


Conformance Testing:
====================

 Testing the conformance of a decoded HE-AAC conformance bitstream:

         Windows: mpsConfTool.exe conformance.mp4 decoded_conformance.wav
         Linux:   mpsConfTool     conformance.mp4 decoded_conformance.wav




IMPORTANT NOTES:
================

Note that the 'spatialdec' binary requires a certain stack size on Linux. 
When using bash, type:
  ulimit -s 32768  (bash)
or when using csh/tcsh, type:
  limit stacksize 32768

to increase the required stacksize.

--
