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.
Page 1
mvRenderAudio(3dm)mvRenderAudio(3dm)
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 ALSOmvReadFrames(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
