Decode media frames
[Decoding of multimedia streams]

Functions
BGAV_PUBLIC int	bgav_video_has_still (bgav_t *bgav, int stream)
	Determine if a still image is available for reading.
BGAV_PUBLIC int	bgav_read_video (bgav_t *bgav, gavl_video_frame_t *frame, int stream)
	Decode a video frame.
BGAV_PUBLIC void	bgav_skip_video (bgav_t *bgav, int stream, int64_t *time, int scale, int exact)
	Skip forward in a video stream.
BGAV_PUBLIC int	bgav_read_audio (bgav_t *bgav, gavl_audio_frame_t *frame, int stream, int num_samples)
	Decode audio samples.
BGAV_PUBLIC int	bgav_has_subtitle (bgav_t *bgav, int stream)
	Check, if a new subtitle is available.
BGAV_PUBLIC int	bgav_read_subtitle_overlay (bgav_t *bgav, gavl_overlay_t *ovl, int stream)
	Decode an overlay subtitle.
BGAV_PUBLIC int	bgav_read_subtitle_text (bgav_t *bgav, char **ret, int *ret_alloc, int64_t *start_time, int64_t *duration, int stream)
	Decode a text subtitle.

---

Function Documentation

BGAV_PUBLIC int bgav_video_has_still	(	bgav_t *	bgav,
		int	stream
	)

Determine if a still image is available for reading.

Parameters:

	bgav	A decoder instance
	stream	Stream index (starting with 0)

Returns:

1 if a still image is available, 0 else

This should be used, if the framerate_mode of the video format is GAVL_FRAMERATE_STILL. In earlier versions, streams consisting of one or more still images outputted the same image repeatedly as if it was a video stream. Since 1.0.1 each image is decoded exactly once. The end-of-file detection happens in a similar way as for subtitles: bgav_video_has_still returns 1 and the following bgav_read_video returns 0.

Since 1.0.1

BGAV_PUBLIC int bgav_read_video	(	bgav_t *	bgav,
		gavl_video_frame_t *	frame,
		int	stream
	)

Decode a video frame.

Parameters:

	bgav	A decoder instance
	frame	The frame to which the image will be decoded.
	stream	Stream index (starting with 0)

Returns:

1 if a frame could be decoded, 0 for EOF.

BGAV_PUBLIC void bgav_skip_video	(	bgav_t *	bgav,
		int	stream,
		int64_t *	time,
		int	scale,
		int	exact
	)

Skip forward in a video stream.

Parameters:

	bgav	A decoder instance
	stream	Stream index (starting with 0)
	time	The time to skip to (will be changed to the true time)
	scale	Scale by which the time is scaled
	exact	1 if an exact skip should be done, 0 for faster approximate skip

Use this function if it turns out, that the machine is too weak to decode all frames. Set exact to 0 to make the skipping even faster but less accurate.

BGAV_PUBLIC int bgav_read_audio	(	bgav_t *	bgav,
		gavl_audio_frame_t *	frame,
		int	stream,
		int	num_samples
	)

Decode audio samples.

Parameters:

	bgav	A decoder instance
	frame	The frame to which the samples will be decoded.
	stream	Stream index (starting with 0)
	num_samples	Number of samples to be decoded

Returns:

The number of actually decoded samples, which can be smaller than num_samples. 0 means EOF.

BGAV_PUBLIC int bgav_has_subtitle	(	bgav_t *	bgav,
		int	stream
	)

Check, if a new subtitle is available.

Parameters:

	bgav	A decoder instance
	stream	Stream index (starting with 0)

Returns:

1 if a subtitle is available.

Use this function to check in advance, if it would make sense to call bgav_read_subtitle_overlay or bgav_read_subtitle_text.

BGAV_PUBLIC int bgav_read_subtitle_overlay	(	bgav_t *	bgav,
		gavl_overlay_t *	ovl,
		int	stream
	)

Decode an overlay subtitle.

Parameters:

	bgav	A decoder instance
	ovl	The overlay to which the subtitle will be decoded.
	stream	Stream index (starting with 0)

Returns:

1 if a subtitle could be decoded, 0 else

If this function returns 1, a subtitle was decoded. If this function returns 0 and bgav_has_subtitle returned 0 before as well, there is no subtitle yet available, but there might come others at a later point in the stream. If this function returns 0 and bgav_has_subtitle returned 1 before, it means, that you reached the end of the subtitle stream.

BGAV_PUBLIC int bgav_read_subtitle_text	(	bgav_t *	bgav,
		char **	ret,
		int *	ret_alloc,
		int64_t *	start_time,
		int64_t *	duration,
		int	stream
	)

Decode a text subtitle.

Parameters:

	bgav	A decoder instance
	ret	The string, where the text will be stored.
	ret_alloc	The number of allocated bytes for ret
	start_time	Returns the start time
	duration	Returns the duration
	stream	Stream index (starting with 0)

Returns:

1 if a subtitle could be decoded, 0 else

If this function returns 1, a subtitle was decoded. If this function returns 0 and bgav_has_subtitle returned 0 before as well, there is no subtitle yet available, but there might come others at a later point in the stream. If this function returns 0 and bgav_has_subtitle returned 1 before, it means, that you reached the end of the subtitle stream. start_time and duration are scaled by the timescale of the subtitle stream (see bgav_get_subtitle_format).