**********************************************************************
***                                                                ***
***              MPEG-4 Audio Reference Software                   ***
***                                                                ***
**********************************************************************



Content of README_refsoft
=========================

1   About MPEG-4 Audio Reference Software
2   Further Information
3   ISO Copyright Header
4   How to compile and run this software
5   Audio File I/O



1   About MPEG-4 Audio Reference Software
=========================================

This is the MPEG-4 Reference Software for Natural Audio and Natural
Speech Coding.

This software was developed by many contributors in the course of
development of the MPEG-2 NBC/MPEG-4 Audio standard ISO/IEC 13818-7,
14496-1,2 and 3. This software is an implementation of a part of one
or more MPEG-2 NBC/MPEG-4 Audio tools as specified by the MPEG-2
NBC/MPEG-4 Audio standard.

In the following the MPEG-4 Audio Reference Software is also refered to
as Verification Model (VM) software.



2   Further Information
=======================

Further information about MPEG-4 Audio is available on the following
sites:

The official MPEG Home Page:
  http://www.cselt.it/mpeg

MPEG Audio Web Page:
  http://www.tnt.uni-hannover.de/project/mpeg/audio/

MPEG Audio ftp server:
  ftp://ftp.tnt.uni-hannover.de/pub/MPEG/audio/



3   ISO Copyright Header
========================

All files of the Reference Software have the following copyright
header:


This software module was originally developed by

FirstName LastName (CompanyName)

and edited by

FirstName LastName (CompanyName)
FirstName LastName (CompanyName)

in the course of development of the MPEG-2 NBC/MPEG-4 Audio standard
ISO/IEC 13818-7, 14496-1,2 and 3. This software module is an
implementation of a part of one or more MPEG-2 NBC/MPEG-4 Audio tools
as specified by the MPEG-2 NBC/MPEG-4 Audio standard. ISO/IEC gives
users of the MPEG-2 NBC/MPEG-4 Audio standards free license to this
software module or modifications thereof for use in hardware or
software products claiming conformance to the MPEG-2 NBC/ MPEG-4 Audio
standards. Those intending to use this software module in hardware or
software products are advised that this use may infringe existing
patents. The original developer of this software module and his/her
company, the subsequent editors and their companies, and ISO/IEC have
no liability for use of this software module or modifications thereof
in an implementation. Copyright is not released for non MPEG-2
NBC/MPEG-4 Audio conforming products. The original developer retains
full right to use the code for his/her own purpose, assign or donate
the code to a third party and to inhibit third party from using the
code for non MPEG-2 NBC/MPEG-4 Audio conforming products. This
copyright notice must be included in all copies or derivative works.

Copyright (c) 1997.



4   How to compile and run this software
========================================

The VM software is written in ANSI C and is C++ compilable. It can be
compiled and linked using GNU's gcc/g++ and GNU's make.


4.1   Structure of the software
-------------------------------

vm/
	README_refsoft			(this file)
	makefile*			makefiles
	src_frame/*			frame work source code (decoder)
	src_frame_enc/*			frame work source code (encoder)
	src_par*/*			PARA core source code
	src_lpc*/*			CELP core source code
	src_tf*/*			T/F core source code
	include/			library include files (decoder)
		libtsp.h		afsp include file
		libtsp/AFpar.h		afsp include file
		*.h			other library include files
	include_enc/			library include files (encoder)
	tables/				runtime data tables
	sunos/				platform: SunOS
		mp4enc			encoder executable
		mp4dec			decoder executable
		obj/			object files
		lib/			libraries
			libtsp.a	afsp library
			*.a		other libraries
	sgi/				platform: SGI (IRIX)
	linux/				platform: Linux
	sol/				platform: Solaris


4.2   Making the executables
----------------------------

Before making the VM executables, set the environment variable
SYSTEM_NAME according to your software platform (SunOS, IRIX, Linux,
OS2, Solaris):

  setenv SYSTEM_NAME SunOS

In the following, <platform> is to be replaced by your local software
platform (sunos, sgi, linux, os2, sol).

Now make can be invoked

  cd vm
  make all

It is possible to disable different modules of the VM when making the
executable. The disabled modules are replaced by corresponding dummy
modules to maintain linkability. E.g. to enable the LPC core only, use

  make TF=0 LPC=1 PAR=0

Instead of specifying these options on the command line, you can also
write them as

  TF = 0
  LPC = 1
  PAR = 0

into the file

  makefile.cfg .

For further available options, check the sub-makfiles

  makefile.par
  makefile.lpc
  makefile.tf .


4.3   Running the encoder and decoder
-------------------------------------

Before running the VM, you should set the following environment variables according to your local path names, audio file formats etc.:

MP4_ORI_PATH       path for original audio files
MP4_BIT_PATH       path for bit stream files
MP4_DEC_PATH       path for decoded audio files
MP4_ORI_FORMAT     format of original audio files
MP4_DEC_FORMAT     format of decoded audio files
MP4_RAWAUDIOFILE   raw audio file format (for reading headerless files)
                     (sample format, num header bytes, sampling rate,
                     byte order, num channels, gain factor)

Example:

  setenv MP4_ORI_PATH /data/mp4/ori/
  setenv MP4_BIT_PATH /data/mp4/bit/
  setenv MP4_DEC_PATH /data/mp4/dec/
  setenv MP4_ORI_FORMAT .au
  setenv MP4_DEC_FORMAT .au
  setenv MP4_RAWAUDIOFILE "integer16, 0, 8000.0, native, 1, 1.0"

Invoke the encoder and decoder with the option -h to get a list of the
command line options available:

  cd vm
  <platform>/mp4enc -h
  <platform>/mp4dec -h

The following example encodes the file test.au to the bit stream file
test_hvx.mp4 and then decodes this bit stream to the file
test_hvx.aiff using the parametric HVXC mode at 2 kbit/s:

  <platform>/mp4enc -d 3 -m par -r 2000 -c "m=hvx" test -o test_hvx
  <platform>/mp4dec -d 3 -ed .aiff test_hvx



5   Audio File I/O
==================

All audio file i/o of the VM software is handled via the audio.h
interface. The current implementation of audio.c is based on the AFsp
package to support a wide range of audio file formats. Further details
about the AFsp package are give below:


5.1   The AFsp Audio File I/O Package
-------------------------------------

To provide support for a variety of audio file formats, the VM
software uses the AFsp package for all audio file i/o. The AFsp
package is written by Peter Kabal <kabal@TSP.EE.McGill.CA> and is
available via ftp:

current version:	AFsp-V3R2.tar.Z
WWW site:		http://www.TSP.EE.McGill.CA/software.html
ftp site:		ftp://ftp.TSP.EE.McGill.CA/pub/AFsp
mirror site:		ftp://ftp.tnt.uni-hannover.de/pub/audio/AFsp

To make the libtsp library required by the VM software, unpack
AFsp-V3R2.tar.Z, goto AFsp-V3R2/libtsp and start make. Finally the
following three files have to be copied to the vm directory tree:

vm/include/libtsp.h
vm/include/libtsp/AFpar.h
vm/<platform>/lib/libtsp.a


5.2   Excerpt from the AFsp Copying file
----------------------------------------

Copyright (C) 1997 Peter Kabal
 
The AFsp audio file routines are provided free of charge without warranty of
any kind.  All components are copyrighted.  They may be distributed free of
charge provided that the recipients also acquire the right to distribute them.
In no case can this software be incorporated into a work which is distributed
for a fee.
 

--
$Id: README_refsoft,v 1.2 1997/11/11 17:59:00 purnhage Exp $
