mvRenderAudio(3dm)                                          mvRenderAudio(3dm)


NAME
     mvRenderMovieToAudioBuffer, mvGetAudioBufferSize - Multi-track, time-
     based access of audio data from movies.

SYNOPSIS
     #include <dmedia/moviefile.h>

     DMstatus mvRenderMovieToAudioBuffer( MVid        movie,
                                          MVtime      renderTime,
                                          MVtime      renderDuration,
                                          MVtimescale timeScale,
                                          MVdirection direction,
                                          size_t      bufferSize,
                                          size_t     *bufferFilled,
                                          MVframe    *framesFilled,
                                          void       *buffer,
                                          DMparams   *formatParams )

     DMstatus mvGetAudioBufferSize( MVtime duration, MVtimescale timeScale,
                                    DMparams *format )


DESCRIPTION
     mvRenderMovieToAudioBuffer renders the movie's enabled audio tracks
     starting at time renderTime for renderDuration time ticks in the given
     scale and direction into the provided memory buffer.  If the direction is
     MV_BACKWARD, the audio frames will be reversed in time, starting at
     renderTime and ending with renderTime - renderDuration.  The buffer will
     be filled with audio frames in the format specified by formatParams.
     This parameter list should include DM_AUDIO_RATE, DM_AUDIO_FORMAT,
     DM_AUDIO_WIDTH, and DM_AUDIO_CHANNELS.  When formatParams is NULL, the
     audio format parameters of movie's first audio track are used.  If any of
     the format parameters are missing, the corresponding format parameter of
     movie's audio track is used. DM_SUCCESS is returned on success.

     If movie has no audio tracks, DM_FAILURE is returned and the errno is set
     to MV_NO_TRACK.

     If the movie has multiple audio tracks that overlap during the requested
     duration, the audio data for the tracks will be mixed (i.e. added and
     clipped according to the requested format).

     If the sample rate of the data in an audio track does not match the
     requested rate, linear interpolation/decimation is used to re-sample the
     data.  If the format, width, or number of channels differs from the track
     data, the appropriate conversions are made.   Currently the only formats
     supported are DM_AUDIO_TWOS_COMPLEMENT and DM_AUDIO_UNSIGNED, the only
     widths supported are 8 and 16, and the only numbers of channels supported
     are 1, 2 and 4.


     If the play volume of a track (see mvGetTrackPlayVolume(3dm)) is < 1.0,
     the data are scaled accordingly before the track is mixed. If the play
     volume of the movie (see mvGetMoviePlayVolume(3dm)) is < 1.0, the post-
     mix samples are scaled accordingly (or silence is used if the volume is
     0).  For example, if a movie has a play volume of .5 and it has one audio
     track with a track volume of .5, a rendering of the audio for this movie
     will scale the data in the track by .25.

     mvRenderMovieToAudioBuffer assumes that there are bufferSize bytes of
     memory pointed to by buffer and it returns the number of bytes of audio
     data rendered in bufferFilled as well as the number of framesFilled.
     bufferFilled may be less than bufferSize, depending on the requested
     duration and the actual duration of audio stored in the movie.  It is the
     application's responsibility to ensure that the rendering will fit in
     bufferSize bytes. If the rendering would require more than bufferSize
     bytes, DM_FAILURE is returned and the movie errno is set to
     MV_BUFFER_TOO_SMALL.

     mvGetAudioBufferSize is a convenience routine that returns the number of
     bytes needed to hold duration ticks of audio (in the given scale) in the
     requested format.  If the format doesn't contain the necessary audio
     parameters described above, 0 is returned.

SEE ALSO
     mvReadFrames(3dm) provides a frame-based version of some of the
     functionality described here.  (It doesn't provide format/rate
     conversions or multi-track mixing).

     dmAudioFrameSize(3dm), dmParams(3dm), mvGetErrno(3dm),
     mvGetMoviePlayVolume(3dm), mvGetTrackPlayVolume(3dm), mvIntro(3dm),
     mvReadFrames(3dm), mvRenderMovieToImageBuffer(3dm).


                                                                        Page 2