readme_celp32a_c

g729 coding ipaddressing

Note*******
For this PC release, no provision has been made, other than changing file
names to fit within DOS filename constraints, to run on a DOS system.  This
code was written to run on a Sun Workstation, and can be easily made to run
on any UNIX based system.  A small amount of work is needed to make the
code runable on a PC system.


        CELP Version 3.2 C code

Beware, the speech generated by version 3.2 C code and 3.2 FORTRAN
code does not match exactly.  However, this slight mismatch appears
to be within the arithmetic precision difference expected between 
compiled FORTRAN and C.


INSTALLATION, EDITING FILES, COMPILATION and LINKING
----------------------------------------------------

         This directory contains CELP Version 3.2 written in C.  All of the 
        code necessary to make CELP is in this directory.  There are a couple
        of things that need to be done before compiling the code.  First, you
        need to decide whether you wish to run the old version of calculating
        lsps and quantizing them or do you want to run a quicker version that 
        calculates the lsps and quantizes them in the same routine (Lionel 
        Wolovitz's code).  If you want to run the old version then all the code 
        is in place.  If you wish to use the quicker version (there is a slight  
        degradation in the speech quality with this version) then you need to:

        %cp celp_pctolsp3.c celp.c
        %cp specdist_pctolsp3.c specdist.c.

***Note for this release only one version of celp has been included.  The
   other versions referred to here can be created with the code enclosed
   and changing a few calls with respect to pc to lsp conversion.....

        Note:  The degradation incurred by using pctolsp3.c is due to a more
        coarse search (for zero crossings) than is used by pctolsp2.c.  Simply
        searching a grid formed by the quantized values is not sufficient
        for maintaining an accurate representation of spectral information.
        The minimal search we suggest is a grid of quantized values and 
        two interpolated values between each quantized value in order not
        to miss any zero crossings in the method of searching employed by 
        pctolsp3.c.
        
         The second thing you need to do is find out whether your C library 
        contains the nint function for rounding floating point numbers to
        integers.  If your C library does contain nint then you need to do 
        nothing.  If your C library does not have a nint function then a  
        round function is provided with the C code.  All that has to be done 
        to implement the round function is to substitute round for nint in 
        the following files:

        FILE            NUMBER OF OCCURENCES
        --------------------------------------
        celp.c                  2
        cgain.c                 7
        cli.c                   3
        smoothcbgain.c          1
        smoothtau.c             1

         The third option you have is whether to use the durbin routine 
        in the autohf.c file.  If you wish not to use the durbin routine
        you need to make sure the call to autohf in celp.c is correct.  
        The file celp_pctolsp2.c has the correct code for not using the 
        durbin routine.  You will also need to:

        %cp autohf_reg.c autohf.c

         The fourth option is whether to use recursive/non-recursive delay
        routines.  If you choose to use the non-recursive routines you must 
        fix the calls/references in the following files:

        pitchvq.c 
        psearch.c
        makefile 

         If you plan on using the makefile provided then you will have to 
        replace the pathname for the disk_io routine on the SGIO_LIB option
        and set whatever CFLAGS are necessary.  A couple of compilations 
        can be omitted depending on what round routine you are using and 
        which pctolsp routine you choose.  If you are using nint then 
        all references to round in the makefile may be deleted.  If you 
        are using the old version of pctolsp then all references to pctolsp3
        can be deleted from makefile.  If you choose to use the newer version
        then you can delete the references to pctolsp2 from the makefile
        (do not delete lsp34 - you need this).

         At this point you can make celp.

        %make celp


EXECUTION
---------
                       CELP COMMAND
NAME:
     celp - execute the CELP coder

     The celp command generates a code-excited-linear-prediction
     processed output file from an input file.

SYNOPSIS:
     celp [-i ifile] [-o ofile] [-p pfile] [-q qfile] [-m mfile] [-l lfile]
       or
     celp [-c chan] [-o ofile]

ARGUMENTS:
     -i      Input file short data format (16-bit signed samples).
             For defaults, see celp.c data statements.
 
     -o      Speech output file (.spd) short data format
             (16-bit signed samples) and bit stream channel file (.chan).
             For defaults, see celp.c data statements.

     -p      Parameter file specifying celp characteristics.
             For defaults, see celp.c data statements.
             Parameters are stored in a ascii text file in the order below
             with one number per line i.e.,:

               512       [ncsize = Code book size]
               60        [l      = Code word length]
               240       [ll     = LPC analysis frame size]
               10        [no     = LPC filter order]
               60        [lp     = Pitch analysis frame size]
               1         [np     = Pitch order]
               0.8       [gamma  = Noise weighting factor]
               1.0       [scale  = Input speech scaling factor]
               1.0       [descale = Output speech scaling factor]
               0.0       [ber    = % bit error rate]
               1         [mxsw    = modified excitation logical switch]
               0.0       [prewt   = prefilter logical switch]
               hier      [pstype  = type of fractional pitch search]

     -q      Quantization characteristics file.
             For defaults, see celp.c data statements.
             The file has 3 sections: cbgain, pitch, and spectrum.
             Each section type is followed by a quantization type,
             which can be one of the following:  "max", "uniform", "vq",
             "log", "opt", or "none".  If the quantization type is not 
             "none", then the next line is the bit allocation; i.e.:

             cbgain
             none                      [unquantized cbgain]
             pitch
             max                       [Max quantization]
             8 6 5             [8 bit delay, 6 bit delta delay, 5 bit gain]
             spectrum
             kang                      [Kang's quantization]
             3 4 4 4 4 3 3 3 3 3       [lsp1=3,...,lsp10=3]

     -m      Mask file specifying bit protection when introducing bit
             errors to the unpermuted bit stream.  (Note, this protection
             is separate from the Hamming FEC.)  Each line of the mfile
             corresponds to a bit (i.e., 144 lines) where each line is a
             1 (protected) or 0 (not protected).
             See description in biterror.c.  

     -l      Log file output containing run time information.
             Defaults to appending to a file called "celp.log".
             If the file name "none" is specified, no log file
             is generated.

     -c      Input channel file (.chan) hexadecimal format.  Channel
             files generated from previous analysis runs are used as
             imputs to a "synthesis only" run.  During this mode, the
             -i switch is invalid.

EXAMPLES:

     celp
             This causes celp to process ifile.spd into ofile.spd (and a
             nonpostfiltered output in ofilenpf.spd) using the defaults 
             specified by the FORTRAN data statements in celp.c,
             writes the bit stream file ofile.chan and generates a log
             appended to the file "celp.log".  (If SUNGRAPH is enabled,
             a set of files, with .sg_data extension, as defined in
             sungraph_open.com is generated.)

     celp -i speech/dam27 -o dam27.48 -p celp48.p -q celp48.q -l log

             celp processes speech/dam27.spd into the normal, highpassed
             and nonpostfiltered output, dam27.48.spd, dam27_48hpf.spd
             and dam27_48npf.spd, respectively, writes the bit stream
             file dam27_48.chan and appends log information to a file
             called log.  The celp parameters specified by celp48.p and  
             quantization characteristics of celp48.q are used.  (If  
             SUNGRAPH is enabled, a set of files, with .sg_data extension, 
             as defined in sungraph_open.com is generated.)

     celp -c speech/512_dam27.chan -o 512_dam27b

             celp synthesizes speech/512_dam27.chan channel file into 
             the normal, highpassed and nonpostfiltered output, 
             512_dam27b.spd, 512_dam27bhpf.spd and 512_dam27bnpf.spd,
             respectively.


 SEE ALSO
        cli.c


EXECUTION OF SEPARATE SYNTHESIZER
---------------------------------

       In order to run the synthesizer only compile celp without
       the -DANALY option in the makefile.  (Separate analysis is not 
       provided since the combined analyzer and synthesizer generates a  
       bit stream channel file.)  The celp command syntax for synthesis  
       only is:

       celp [-c chan] [-o ofile]


       where: chan is input.chan ascii hex bit stream channel file
              ofile is ofile.spd speech file (postfiltered)

 SEE ALSO 
        makefile