Positioning in Streams
AVIFile provides several ways to locate and move to a position in a data
stream. The functions and macros in this section let your application find the
starting position, length, and key frames (containing a complete image in the
sample) within a stream. The functions and macros also associate time with positions
in a stream by calculating the elapsed time needed to play a stream from its
beginning to any point in a stream.
Finding the Starting Position
You can retrieve the sample number of the first frame in a video stream by
using the AVIStreamStart
function. (The frames of a movie might start at sample 0 or 1, depending on
the preference of the author.) You can also obtain this information by using the AVIStreamInfo
function. This function stores the sample number in the dwStart
member of the AVISTREAMINFO
structure. You can retrieve the starting time of a stream's first sample by
using the AVIStreamStartTime
You can retrieve the stream length by using the AVIStreamLength
function. This function returns the number of samples in the stream. You can
also obtain this information by using the AVIStreamInfo
function. This function stores the stream length in the dwLength
member of the AVISTREAMINFO
structure. To retrieve the length of a stream in milliseconds, use the AVIStreamLengthTime
In a video stream, each sample generally corresponds to a frame of video.
There might, however, be samples for which no video data is present. If you call
function specifying one of those positions, it returns a data length of 0
bytes. You can find samples that contain data by using the AVIStreamFindSample
function and specifying the FIND_ANY flag.
In an audio stream, each sample corresponds to one data block of audio data.
For example, if the audio data has a 22 kHz ADPCM (Adaptive Differential Pulse
Code Modulation) format, each sample for AVIStreamLength
corresponds to a block of 256 bytes of compressed audio data. This block of
audio data contains approximately 500 audio samples when uncompressed. The
functions and macros of AVIFile, however, treat each 256-byte block as a single
Valid positions within a stream range from the beginning to the end of the
stream, which is the sum of the stream starting point and its length. The
position represented by the sum of the starting position and the length corresponds
to a time after the last data has been rendered; it does not contain any data.
You can retrieve the sample number that represents the end of the stream by
using the AVIStreamEnd
macro. You can retrieve the time value in milliseconds that represents the
end of the stream by using the AVIStreamEndTime
Finding Sample and Key Frames
You can search for different types of samples in a stream by using the AVIStreamFindSample
function. This function searches backward or forward through a stream for a
sample of the appropriate type, beginning with the sample number you specify.
You can search for different types of samples in a stream by specifying a flag in
calling sequence. Specify the FIND_ANY flag to locate nonempty samples or to
skip samples that lack data. Specify the FIND_KEY flag to search for key frames
that contain the data to render a complete image without needing to reference
previous frames. Specify the FIND_FORMAT flag to search for changes to the
is used mainly with video streams.
Several macros that use AVIFile functions supplement the stream search
features. The following list provides a brief description of each macro. The macros
that search for a specific position or type of data require a starting location
to be specified in the stream.
Switching Between Samples and Time
You can determine the elapsed time from the beginning of a stream to a sample
using the AVIStreamSampleToTime
function. This function converts the sample number to a time value expressed
in milliseconds. For a video frame (which spans several milliseconds), this
value represents the time the sample begins to play since playback began and
assumes the video clip plays at normal speed. For an audio sample (which has several
samples in a millisecond), the time value corresponds to the time at which the
sample begins to play and assumes the audio stream plays at normal speed.
Conversely, you can find the sample number associated with a time value by
using the AVIStreamTimeToSample
function. This function converts the millisecond value to a sample number and
assumes the video clip plays at normal speed.
returns the time at which a frame begins to play, the relationship between AVIStreamSampleToTime
is not truly inverse. They determine the position in a file more acurately
than they determine time. For example, two consecutive audio samples might both
play in the same millisecond. Using AVIStreamSampleToTime
to convert the sample numbers would result in identical time values. If you
convert the time value back to a sample number by using AVIStreamTimeToSample
, a single sample would be referenced.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages