Sample accurate seek API
Decoding of multimedia streams

## Functions

BGAV_PUBLIC int | bgav_can_seek_sample (bgav_t *bgav)
| Time value indicating an invalid time.
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 int64_t | bgav_text_duration (bgav_t *bgav, int stream)
| Get the text duration.
BGAV_PUBLIC int64_t | bgav_overlay_duration (bgav_t *bgav, int stream)
| Get the overlay duration.
BGAV_PUBLIC int | bgav_seek_to_video_frame (bgav_t *bgav, int stream, int frame)
| Seek to video frame given by index.
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.

## 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.

## Function Documentation

## bgav_can_seek_sample()

BGAV_PUBLIC int bgav_can_seek_sample | ( | bgav_t * | bgav | ) |

Time value indicating an invalid time.

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.

## bgav_audio_duration()

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_audio_start_time()

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_video_duration()

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_video_start_time()

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_subtitle_duration()

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_text_duration()

BGAV_PUBLIC int64_t bgav_text_duration | ( | bgav_t * | bgav,
|  | int | stream )

Get the text duration.

Parameters

  bgav | A decoder handle
  stream | Text stream index (starting with 0)

Returns
  Exact duration in stream tics

Use this only after bgav_can_seek_sample returned 1.

## bgav_overlay_duration()

BGAV_PUBLIC int64_t bgav_overlay_duration | ( | bgav_t * | bgav,
|  | int | stream )

Get the overlay duration.

Parameters

  bgav | A decoder handle
  stream | Overlay stream index (starting with 0)

Returns
  Exact duration in stream tics

Use this only after bgav_can_seek_sample returned 1.

## bgav_seek_to_video_frame()

BGAV_PUBLIC int bgav_seek_to_video_frame | ( | bgav_t * | bgav,
|  | int | stream,
|  | int | frame )

Seek to video frame given by index.

Parameters

  bgav | A decoder handle
  stream | Video stream index (starting with 0)
  idx | Frame index (starting with zero)

Returns
  0 if EOF was reached, 1 else

## bgav_video_keyframe_before()

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_video_keyframe_after()

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.