dmDVIAudioDecode(3dm)

NAME
     dmDVIAudioDecode - decode audio data compressed using the IMA
     (Interactive Multimedia Association) Recommended ADPCM decompression,
     based on Intel's DVI algorithm.


SYNOPSIS
     #include <dmedia/dm_audioutil.h>

     DMstatus dmDVIAudioDecode(DMDVIaudiodecoder handle,
                               unsigned char *ibuf, short *obuf,
                               int nsamples)


PARAMETER
     handle    DMDVIaudiodecoder structure, created by a previous call to
               dmDVIAudioDecoderCreate(3dm).  It contains the state associated
               with the decoder.


     ibuf      A pointer to the compressed input data buffer. The data format
               is unsigned char (8-bit).


     obuf      A pointer to the output sample data buffer.  The data format is
               short (16-bit).  The samples are assumed to be two's
               complement.  Sampling rate may range from 8 kHz to 48 kHz, but
               has to be the same as encoder.


     nsamples  The number of samples to be processed.  For the 4:1 algorithm
               (the only one currently supported), the value of nsamples
               passed to the DVI encode/decode routines must always be a
               multiple of 2.


RETURNED VALUE
     Returns DM_FAILURE or DM_SUCCESS.


DESCRIPTION
     dmDVIAudioDecode(3dm) implements Intel, Inc.'s DVI IMA4:1 ADPCM
     compression for monaural audio data.

     DVI IMA ADPCM compression exists in two forms, 4 bits per sample (IMA4:1)
     and 3 bits per sample (IMA3:1).  The compression form may be retrieved
     using dmDVIAudioDecoderGetParams(3dm) via the parameter
     DM_DVI_AUDIO_BITS_PER_SAMPLE.  Its possible values are:

     DM_DVI_AUDIO_4BITS_PER_SAMPLE
          4:1 compression.  This is the only form currently supported by the
          SGI Digital Media libraries.
     DM_DVI_AUDIO_3BITS_PER_SAMPLE
          3:1 compression.  Currently not supported.

DVI AUDIO FILE BLOCK MODE
     DVI audio compression uses a linear prediction scheme.  This means that
     the compressed bits are interrelated or interdependent.  If a application
     seeks to an offset into the compressed bit stream file and then starts
     reading at that point in the stream and decompresses it via
     dmDVIAudioDecode(3dm), the interdependency of the bits at the start 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.

     In pure DVI ADPCM data, there is no way to accurately begin decoding data
     in the middle of the bit stream file without starting the beginning.  Two
     solutions to this problem have been developed, one by Intel, Inc. and one
     by Apple, Inc.  Both involve breaking the compressed data up into blocks,
     each with a small header encapsulating the information needed to allow
     decoding to begin at any block boundry with no loss of data. WAVE(4) and
     AIFF-C(4) format sound files using IMA DVI compression take advantage of
     this block method, and if such a file is read using the Audio File
     Library, accurate file seeks are possible.

     The data contained in one of these files may also be decoded accurately
     using dmACConvert(3dm) if it is configured properly.

CONFIGURING DMAC TO PARSE IN BLOCK MODE
     Three parameters are needed to configure the DMaudioconverter to allow
     parsing of these block streams:

     DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK
          Indicates the number of bytes of compressed data per block,
          including the header.  For AIFF-C(4) files, this value is always 34
          * channel_count.  For WAVE(4) files, this value varies.  If
          afOpenFile(3dm) is used to open a WAVE(4) file, the value of this
          parameter can be retrieved directly using afGetFormatParams(3dm).

     DM_AUDIO_CODEC_FRAMES_PER_BLOCK
          Indicates the number of frames of uncompressed data contained in
          each block.  For AIFF-C(4) files, this value is always 64.  For
          WAVE(4) files, this value varies.  If afOpenFile(3dm) is used to
          open a WAVE(4) file, the value of this parameter can be retrieved
          directly using afGetFormatParams(3dm).

     DM_DVI_AUDIO_BLOCK_TYPE
          This DVI-specific parameter specifies whether the data is compressed
          using the Intel scheme, the Apple scheme, or no blocking at all
          (i.e., "pure" DVI).  Its possible values are:

          DM_DVI_AUDIO_BLOCK_TYPE_NONE -- For stream use only.
          DM_DVI_AUDIO_BLOCK_TYPE_APPLE -- For AIFF-C files.
          DM_DVI_AUDIO_BLOCK_TYPE_INTEL -- For WAVE files.
IMPORTANT NOTE
     Stereo audio streams and streams with block data cannot be parsed using
     dmDVIAudioDecode() directly -- you must use dmACConvert(3dm).  It is
     highly recommended that the Audio File Library be used for all to- and
     from-disk compression and decompression.

SEE ALSO
     dmDVIAudioDecoderCreate(3dm), dmDVIAudioDecoderSetParams(3dm),
     dmDVIAudioDecoderDestroy(3dm), dmDVIAudioEncode(3dm),  afReadFrames(3dm),
     IMA Recommended Practices for Enhancing Digital Audio Compatibility in
     Multimedia Systems, rev 3.00.