Sample accurate seek API
[Decoding of multimedia streams]

Defines
#define	BGAV_TIMESTAMP_UNDEFINED   GAVL_TIME_UNDEFINED
	Time value indicating an invalid time.
Functions
BGAV_PUBLIC int	bgav_can_seek_sample (bgav_t *bgav)
	Check if a track is seekabkle with sample accuracy.
BGAV_PUBLIC int64_t	bgav_audio_duration (bgav_t *bgav, int stream)
	Get the audio duration.
BGAV_PUBLIC int64_t	bgav_audio_start_time (bgav_t *bgav, int stream)
	Get the audio start time.
BGAV_PUBLIC int64_t	bgav_video_duration (bgav_t *bgav, int stream)
	Get the video duration.
BGAV_PUBLIC int64_t	bgav_video_start_time (bgav_t *bgav, int stream)
	Get the video start time.
BGAV_PUBLIC int64_t	bgav_subtitle_duration (bgav_t *bgav, int stream)
	Get the subtitle duration.
BGAV_PUBLIC void	bgav_seek_audio (bgav_t *bgav, int stream, int64_t sample)
	Seek to a specific audio sample.
BGAV_PUBLIC void	bgav_seek_video (bgav_t *bgav, int stream, int64_t time)
	Seek to a specific video time.
BGAV_PUBLIC int64_t	bgav_video_keyframe_before (bgav_t *bgav, int stream, int64_t time)
	Get the time of the closest keyframe before a given time.
BGAV_PUBLIC int64_t	bgav_video_keyframe_after (bgav_t *bgav, int stream, int64_t time)
	Get the time of the closest keyframe after a given time.
BGAV_PUBLIC void	bgav_seek_subtitle (bgav_t *bgav, int stream, int64_t time)
	Seek to a specific subtitle position.

---

Detailed Description

This mode is optimized for sample accurate access. To use this API, you must call bgav_options_set_sample_accurate before opening the file. After you opened the file and selected the track, you must verify, that sample accurate access is available by checking the return value of bgav_can_seek_sample.

Sample accurate mode has a little more overhead on the demultiplexer side. Therefore you should not enable it when not needed. Some formats don't allow sample accurate access, other formats are *only* seekable in sample accurate mode. For formats, which need to be parsed completely, index files are written to $HOME/.gmerlin-avdecoder/indices. Filenames of the indices are the MD5 sums of the filename passed to bgav_open.

Sample accurate mode also implies, that all streams can be positioned independently.

---

Define Documentation

#define BGAV_TIMESTAMP_UNDEFINED   GAVL_TIME_UNDEFINED

Time value indicating an invalid time.

---

Function Documentation

BGAV_PUBLIC int bgav_can_seek_sample

(

bgav_t *

bgav

)

Check if a track is seekabkle with sample accuracy.

Parameters:

bgav

A decoder handle

Returns:

1 if the track is seekable with sample accuracy, 0 else.

If this function returns zero, applications, which rely on bgav_seek_audio bgav_seek_video and bgav_seek_subtitle should consider the file as unsupported.

The ability of sample accurate seeking also implies, that streams can be positioned indepentently.

If bgav_options_set_sample_accurate was not called, this function will return zero for any file.

BGAV_PUBLIC int64_t bgav_audio_duration	(	bgav_t *	bgav,
		int	stream
	)

Get the audio duration.

Parameters:

	bgav	A decoder handle
	stream	Audio stream index (starting with 0)

Returns:

Duration in samples

Use this only after bgav_can_seek_sample returned 1. The duration is calculated from the total number or decodable samples in the file. The start time (as returned by bgav_audio_start_time) is not included in the duration.

BGAV_PUBLIC int64_t bgav_audio_start_time	(	bgav_t *	bgav,
		int	stream
	)

Get the audio start time.

Parameters:

	bgav	A decoder handle
	stream	Audio stream index (starting with 0)

Returns:

Time (in samplerate tics) of the first sample

Use this only after bgav_can_seek_sample returned 1. The returned value is equal to the timestamp of the first decoded audio frame.

BGAV_PUBLIC int64_t bgav_video_duration	(	bgav_t *	bgav,
		int	stream
	)

Get the video duration.

Parameters:

	bgav	A decoder handle
	stream	Video stream index (starting with 0)

Returns:

Exact duration in stream tics

Use this only after bgav_can_seek_sample returned 1. The duration is calculated from the total number or decodable frames in the file. The start time (as returned by bgav_video_start_time) is not included in the duration.

BGAV_PUBLIC int64_t bgav_video_start_time	(	bgav_t *	bgav,
		int	stream
	)

Get the video start time.

Parameters:

	bgav	A decoder handle
	stream	Video stream index (starting with 0)

Returns:

Time of the first video frame in stream tics

Use this only after bgav_can_seek_sample returned 1. The returned value is equal to the timestamp of the first decoded video frame.

BGAV_PUBLIC int64_t bgav_subtitle_duration	(	bgav_t *	bgav,
		int	stream
	)

Get the subtitle duration.

Parameters:

	bgav	A decoder handle
	stream	Subtitle stream index (starting with 0)

Returns:

Exact duration in stream tics

Use this only after bgav_can_seek_sample returned 1.

BGAV_PUBLIC void bgav_seek_audio	(	bgav_t *	bgav,
		int	stream,
		int64_t	sample
	)

Seek to a specific audio sample.

Parameters:

	bgav	A decoder handle
	stream	Audio stream index (starting with 0)
	sample	The sample to seek to

Use this only after bgav_can_seek_sample returned 1. The time is relative to the first decodable sample (always starting with 0), the offset returned by bgav_audio_start_time is not included here.

BGAV_PUBLIC void bgav_seek_video	(	bgav_t *	bgav,
		int	stream,
		int64_t	time
	)

Seek to a specific video time.

Parameters:

	bgav	A decoder handle
	stream	Video stream index (starting with 0)
	time	Time

Use this only after bgav_can_seek_sample returned 1. If time is between 2 frames, the earlier one will be chosen. The time is relative to the first decodable frame (always starting with 0), the offset returned by bgav_video_start_time is not included here.

BGAV_PUBLIC int64_t bgav_video_keyframe_before	(	bgav_t *	bgav,
		int	stream,
		int64_t	time
	)

Get the time of the closest keyframe before a given time.

Parameters:

	bgav	A decoder handle
	stream	Video stream index (starting with 0)
	time	Time

Returns:

Time of the previous keyframe.

Use this only after bgav_can_seek_sample returned 1. The time argument and return value are relative to the first decodable frame of the file i.e. not including the offset returned by bgav_video_start_time . If there is no keyframe before the given time (i.e if time was 0), this function returns BGAV_TIMESTAMP_UNDEFINED.

BGAV_PUBLIC int64_t bgav_video_keyframe_after	(	bgav_t *	bgav,
		int	stream,
		int64_t	time
	)

Get the time of the closest keyframe after a given time.

Parameters:

	bgav	A decoder handle
	stream	Video stream index (starting with 0)
	time	Time

Returns:

Time of the next keyframe

Use this only after bgav_can_seek_sample returned 1. The time argument and return value are relative to the first decodable frame of the file i.e. not including the offset returned by bgav_video_start_time . If there is no keyframe after the given time, this function returns BGAV_TIMESTAMP_UNDEFINED.

BGAV_PUBLIC void bgav_seek_subtitle	(	bgav_t *	bgav,
		int	stream,
		int64_t	time
	)

Seek to a specific subtitle position.

Parameters:

	bgav	A decoder handle
	stream	Subtitle stream index (starting with 0)
	time	Time

Use this only after bgav_can_seek_sample returned 1. If time is between 2 subtitles, the earlier one will be chosen.