dmFS1016Encode(3dm)

NAME
     dmFS1016Encode - implements the US Federal Standard 1016 4800/7200/9600
     bits/s CELP (Code Excited Linear Predictive) Voice Coder.


SYNOPSIS
     #include <dmedia/dmedia.h>
     #include <dmedia/dm_params.h>
     #include <dmedia/dm_audioutil.h>

     DMstatus dmFS1016Encode(DMFS1016encoder handle,
                       short *ibuf, unsigned char *obuf, int nsamples)


PARAMETER
     handle    DMFS1016encoder structure, created by
               dmFS1016EncoderCreate(3dm), specifies the signal processing
               parameters.


     ibuf      pointer to input sample data buffer. The data format is short
               (16-bit).  The samples are assumed to be two's complement.  The
               sampling rate must be 8 kHz.


     obuf      pointer to output data buffer.  The data format is unsigned
               char (8-bit).  This bitstream buffer must consist of a multiple
               of 18 bytes.


     nsamples  number of samples in the input buffer to be processed.  The
               value of nsamples passed to FS1016 decode/decode routines must
               always be a multiple of 240, 160, or 120 for operations of
               4800, 7200, or 9600 bits/s respectively.


RETURNED VALUE
     Returns DM_FAILURE or DM_SUCCESS.



DESCRIPTION
     dmFS1016Encode(3dm) implements the Federal Standard 1016 decompression.
     The uncompressed data sampling rate is 8000 Hz.  The compression bitrate
     can be

     DM_FS1016_4800_BITS
     DM_FS1016_7200_BITS
     DM_FS1016_9600_BITS
     and is set by a call to dmFS1016EncoderSetParams(3dm). Without calling
     dmFS1016EncoderSetParams(3dm), encoder sets default to 4800 bits/s.


     dmFS1016Encode(3dm) algorithm uses linear prediction analysis operations
     that simply delays the output by half of the analysis frame size.
     Therefore the delays are 120, 80, or 60 samples for operations of 4800,
     7200, or 9600 bit/s respectively.  In file conversion expecting N samples
     in and out, the output signal is offset by 120, 80, or 60 samples from
     the first sample.  The application may want to discard the first 120, 80,
     or 60 samples returned in output date buffer from dmFS1016Decode.


     FS1016 compression uses a linear prediction scheme.  This means that the
     compressed bits, which carrying compressed information, are interrelated
     or interdependent.  If a application calls afSeekFrame() to an offset
     into the compressed bit stream file and then starts reading bits in the
     middle of the bit stream and decompress them with dmFS1016Decode(3dm),
     the interdependency of the bits at the cutting point is lost.  The
     application will initially get back data with a lower amplitude than if
     he had read the same data back during a complete pass over the file from
     the beginning.


     There is no way to exactly recreate the decoded data in the middle of the
     bit stream file without going all the way back to the beginning.
     However, with a "preroll" value to read ahead a portion of the compressed
     file, application can compensate for the amplitude problem.  We recommend
     2 second "preroll".


NOTE
     FS1016 algorithm was developed for sampling rate of 8 kHz.


SEE ALSO
     dmFS1016EncoderCreate(3dm), dmFS1016EncoderDestroy(3dm),
     dmFS1016Decode(3dm), dmFS1016EncoderSetParams(3dm), Federal Standard
     1016.