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

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.10
|
+- 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.10/import

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


Now build the MPEG Surround reference software using "make" in the
respective folders or by opening the Visual Studio Workspaces (*.dsw)
in the win32 subfolders of the respective folders.

For the mp12_mps tool execute the "configure" script in mp12_mps
first or use the Visual Studio Workspace in the same folder.


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

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

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

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:

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

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


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

spatialdec 0 downmix.wav bitstream.bs output.wav


Additional information can be found in the commandline help of the
binaries using the "-h" commandline parameter.

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


--
