A/V sources
A/V pipeline building elements

## Macros

#define | GAVL_SOURCE_SRC_ALLOC (1<<0)
| Source provides a pointer to an internal structure.
#define | GAVL_SOURCE_SRC_FRAMESIZE_MAX (1<<2)
| Samples per frame is just an upper bound. Frames can have smaller sizes also. The last frame is always allowed to have fewer samples, even if this flag is not set.
#define | GAVL_SOURCE_SRC_DISCONTINUOUS (1<<3)
| Stream is discontinuous. Set this for video sources delivering graphical subtitles.

## Typedefs

typedef struct gavl_video_source_s | gavl_video_source_t
| Forward declaration of the video source.
typedef struct gavl_audio_source_s | gavl_audio_source_t
| Forward declaration of the audio source.
typedef struct gavl_packet_source_s | gavl_packet_source_t
| Forward declaration of the packet source.
typedef gavl_source_status_t(* | gavl_audio_source_func_t) (void *priv, gavl_audio_frame_t **frame)
| Prototype for obtaining one audio frame.
typedef gavl_source_status_t(* | gavl_video_source_func_t) (void *priv, gavl_video_frame_t **frame)
| Prototype for obtaining one video frame.
typedef gavl_source_status_t(* | gavl_packet_source_func_t) (void *priv, gavl_packet_t **p)
| Prototype for obtaining one packet.

## Enumerations

enum | gavl_source_status_t { GAVL_SOURCE_EOF = 0 , GAVL_SOURCE_OK = 1 , GAVL_SOURCE_AGAIN = 2 }
| Return value of the source function. More...

## Functions

GAVL_PUBLIC gavl_video_source_t * | gavl_video_source_create (gavl_video_source_func_t func, void *priv, int src_flags, const gavl_video_format_t *src_format)
| Create a video source.
GAVL_PUBLIC void | gavl_video_source_set_pts_offset (gavl_video_source_t *src, int64_t offset)
GAVL_PUBLIC void | gavl_video_source_drain (gavl_video_source_t *s)
GAVL_PUBLIC gavl_video_source_t * | gavl_video_source_create_source (gavl_video_source_func_t func, void *priv, int src_flags, gavl_video_source_t *src)
| Create a video source from another source.
GAVL_PUBLIC void | gavl_video_source_set_lock_funcs (gavl_video_source_t *src, gavl_connector_lock_func_t lock_func, gavl_connector_lock_func_t unlock_func, void *priv)
| Set lock functions.
GAVL_PUBLIC void | gavl_video_source_set_free_func (gavl_video_source_t *src, gavl_connector_free_func_t free_func)
| Set free function.
GAVL_PUBLIC gavl_video_options_t * | gavl_video_source_get_options (gavl_video_source_t *s)
| Get conversion options of a video source.
GAVL_PUBLIC void | gavl_video_source_reset (gavl_video_source_t *s)
| Reset a video source.
GAVL_PUBLIC void | gavl_video_source_destroy (gavl_video_source_t *s)
| Destroy a video source.
GAVL_PUBLIC void | gavl_video_source_support_hw (gavl_video_source_t *s)
| Enable hardware surfaces.
GAVL_PUBLIC const gavl_video_format_t * | gavl_video_source_get_src_format (gavl_video_source_t *s)
| Get the native format.
GAVL_PUBLIC int | gavl_video_source_get_src_flags (gavl_video_source_t *s)
| Get the source flags.
GAVL_PUBLIC const gavl_video_format_t * | gavl_video_source_get_dst_format (gavl_video_source_t *s)
| Get the output format.
GAVL_PUBLIC void | gavl_video_source_set_dst (gavl_video_source_t *s, int dst_flags, const gavl_video_format_t *dst_format)
| Set the destination mode.
GAVL_PUBLIC gavl_source_status_t | gavl_video_source_read_frame (void *s, gavl_video_frame_t **frame)
| Read a video frame.
GAVL_PUBLIC gavl_audio_source_t * | gavl_audio_source_create (gavl_audio_source_func_t func, void *priv, int src_flags, const gavl_audio_format_t *src_format)
| Create an audio source.
GAVL_PUBLIC void | gavl_audio_source_drain (gavl_audio_source_t *s)
GAVL_PUBLIC void | gavl_audio_source_set_pts_offset (gavl_audio_source_t *src, int64_t offset)
GAVL_PUBLIC gavl_audio_source_t * | gavl_audio_source_create_source (gavl_audio_source_func_t func, void *priv, int src_flags, gavl_audio_source_t *src)
| Create an audio source from another source.
GAVL_PUBLIC void | gavl_audio_source_set_lock_funcs (gavl_audio_source_t *src, gavl_connector_lock_func_t lock_func, gavl_connector_lock_func_t unlock_func, void *priv)
| Set lock functions.
GAVL_PUBLIC void | gavl_audio_source_set_free_func (gavl_audio_source_t *src, gavl_connector_free_func_t free_func)
| Set free function.
GAVL_PUBLIC const gavl_audio_format_t * | gavl_audio_source_get_src_format (gavl_audio_source_t *s)
| Get the native format.
GAVL_PUBLIC const gavl_audio_format_t * | gavl_audio_source_get_dst_format (gavl_audio_source_t *s)
| Get the output format.
GAVL_PUBLIC int | gavl_audio_source_get_dst_flags (gavl_audio_source_t *s)
| Get the output flags.
GAVL_PUBLIC void | gavl_audio_source_set_dst (gavl_audio_source_t *s, int dst_flags, const gavl_audio_format_t *dst_format)
| Set the destination mode.
GAVL_PUBLIC gavl_source_status_t | gavl_audio_source_read_frame (void *s, gavl_audio_frame_t **frame)
| Read an audio frame.
GAVL_PUBLIC void | gavl_audio_source_skip (gavl_audio_source_t *s, int num_samples)
| Skip audio samples at the input.
GAVL_PUBLIC void | gavl_audio_source_skip_to (gavl_audio_source_t *s, int64_t t, int scale)
GAVL_PUBLIC int | gavl_audio_source_read_samples (void *s, gavl_audio_frame_t *frame, int num_samples)
| Read audio samples.
GAVL_PUBLIC gavl_audio_options_t * | gavl_audio_source_get_options (gavl_audio_source_t *s)
| Get conversion options of an audio source.
GAVL_PUBLIC void | gavl_audio_source_reset (gavl_audio_source_t *s)
| Reset an audio source.
GAVL_PUBLIC void | gavl_audio_source_destroy (gavl_audio_source_t *s)
| Destroy an audio source.
GAVL_PUBLIC gavl_packet_source_t * | gavl_packet_source_create (gavl_packet_source_func_t func, void *priv, int src_flags, const gavl_dictionary_t *s)
| Create a packet source.
GAVL_PUBLIC void | gavl_packet_source_set_pts_offset (gavl_packet_source_t *src, int64_t offset)
GAVL_PUBLIC void | gavl_packet_source_drain (gavl_packet_source_t *src)
GAVL_PUBLIC void | gavl_packet_source_reset (gavl_packet_source_t *s)
GAVL_PUBLIC const gavl_dictionary_t * | gavl_packet_source_get_stream (gavl_packet_source_t *s)
GAVL_PUBLIC gavl_dictionary_t * | gavl_packet_source_get_stream_nc (gavl_packet_source_t *s)
GAVL_PUBLIC gavl_packet_source_t * | gavl_packet_source_create_source (gavl_packet_source_func_t func, void *priv, int src_flags, gavl_packet_source_t *src)
| Create a packet source from another packet source.
GAVL_PUBLIC void | gavl_packet_source_set_lock_funcs (gavl_packet_source_t *src, gavl_connector_lock_func_t lock_func, gavl_connector_lock_func_t unlock_func, void *priv)
| Set lock functions.
GAVL_PUBLIC void | gavl_packet_source_set_free_func (gavl_packet_source_t *src, gavl_connector_free_func_t free_func)
| Set free function.
GAVL_PUBLIC const gavl_audio_format_t * | gavl_packet_source_get_audio_format (gavl_packet_source_t *s)
| Get the compression info.
GAVL_PUBLIC const gavl_video_format_t * | gavl_packet_source_get_video_format (gavl_packet_source_t *s)
| Get the video format.
GAVL_PUBLIC int | gavl_packet_source_get_timescale (gavl_packet_source_t *s)
| Get the time scale.
GAVL_PUBLIC gavl_source_status_t | gavl_packet_source_read_packet (void *s, gavl_packet_t **p)
| Read one packet.
GAVL_PUBLIC gavl_source_status_t | gavl_packet_source_peek_packet (void *sp, gavl_packet_t **p)
GAVL_PUBLIC void | gavl_packet_source_destroy (gavl_packet_source_t *s)
| Destroy a packet source.

## Detailed Description

A/V sources are elements, which can be used to conveniently pass audio or video frames from one program module to another. They do implicit format conversion and optimized buffer handling.

A module, which provides A/V frames, creates a source module and tells the native format in which it provides the frames. If you want to obtain the frames from the source, you tell the desired output format and if you intend to overwrite the frames.

To obtain the frames, you pass the address of the pointer of the frame. If the pointer is NULL, it will be set to an internal buffer.

The return value is of the type gavl_source_status_t, which can have 3 states depending on whether the stream ended (EOF) or a frame is available or if no frame is available right now. The latter can be used to implement parts of the pipeline in pull mode (the default) and others in push mode.

## Macro Definition Documentation

## GAVL_SOURCE_SRC_ALLOC

#define GAVL_SOURCE_SRC_ALLOC (1<<0)

Source provides a pointer to an internal structure.

## GAVL_SOURCE_SRC_FRAMESIZE_MAX

#define GAVL_SOURCE_SRC_FRAMESIZE_MAX (1<<2)

Samples per frame is just an upper bound. Frames can have smaller sizes also. The last frame is always allowed to have fewer samples, even if this flag is not set.

## GAVL_SOURCE_SRC_DISCONTINUOUS

#define GAVL_SOURCE_SRC_DISCONTINUOUS (1<<3)

Stream is discontinuous. Set this for video sources delivering graphical subtitles.

## Typedef Documentation

## gavl_video_source_t

typedef struct gavl_video_source_s gavl_video_source_t

Forward declaration of the video source.

You don't want to know what's inside

## gavl_audio_source_t

typedef struct gavl_audio_source_s gavl_audio_source_t

Forward declaration of the audio source.

You don't want to know what's inside

## gavl_packet_source_t

typedef struct gavl_packet_source_s gavl_packet_source_t

Forward declaration of the packet source.

You don't want to know what's inside

## gavl_audio_source_func_t

typedef gavl_source_status_t(* gavl_audio_source_func_t) (void *priv, gavl_audio_frame_t **frame)

Prototype for obtaining one audio frame.

Parameters

  priv | Client data
  frame | Where to store the frame

If *frame is non-null, the data will be copied there, otherwise the address of an internally allocated frame is returned

## gavl_video_source_func_t

typedef gavl_source_status_t(* gavl_video_source_func_t) (void *priv, gavl_video_frame_t **frame)

Prototype for obtaining one video frame.

Parameters

  priv | Client data
  frame | Where to store the frame

If *frame is non-null, the data will be copied there, otherwise the address of an internally allocated frame is returned.

## gavl_packet_source_func_t

typedef gavl_source_status_t(* gavl_packet_source_func_t) (void *priv, gavl_packet_t **p)

Prototype for obtaining one packet.

Parameters

  priv | Client data
  frame | Where to store the packet

If *packet is non-null, the data will be copied there, otherwise the address of an internally allocated packet is returned.

## Enumeration Type Documentation

## gavl_source_status_t

enum gavl_source_status_t

Return value of the source function.

Enumerator
GAVL_SOURCE_EOF | End of file, no more frames available.
GAVL_SOURCE_OK | Frame available.
GAVL_SOURCE_AGAIN | No frame available right now, might try later.

## Function Documentation

## gavl_video_source_create()

GAVL_PUBLIC gavl_video_source_t * gavl_video_source_create | ( | gavl_video_source_func_t | func,
|  | void * | priv,
|  | int | src_flags,
|  | const gavl_video_format_t * | src_format )

Create a video source.

Parameters

  func | Function to get the frames from
  priv | Client data to pass to func
  src_flags | Flags describing the source
  src_format | Native source format

Returns
  A newly created video source

## gavl_video_source_create_source()

GAVL_PUBLIC gavl_video_source_t * gavl_video_source_create_source | ( | gavl_video_source_func_t | func,
|  | void * | priv,
|  | int | src_flags,
|  | gavl_video_source_t * | src )

Create a video source from another source.

Parameters

  func | Function to get the frames from
  priv | Client data to pass to func
  src_flags | Flags describing the source
  src | preceding source in the pipeline

Returns
  A newly created video source

This will take the destination format of the preceding source as the input format

## gavl_video_source_set_lock_funcs()

GAVL_PUBLIC void gavl_video_source_set_lock_funcs | ( | gavl_video_source_t * | src,
|  | gavl_connector_lock_func_t | lock_func,
|  | gavl_connector_lock_func_t | unlock_func,
|  | void * | priv )

Set lock functions.

Parameters

  src | A video source
  lock_func | Function called before a frame is read
  unlock_func | Function called after a frame is read
  priv | Client data (e.g. a mutex) to pass to the functions

## gavl_video_source_set_free_func()

GAVL_PUBLIC void gavl_video_source_set_free_func | ( | gavl_video_source_t * | src,
|  | gavl_connector_free_func_t | free_func )

Set free function.

Parameters

  src | A video source
  free_func | Function called with the private data when the source is destroyed

Use this if you don't want to keep a reference to the private data along with the source

## gavl_video_source_get_options()

GAVL_PUBLIC gavl_video_options_t * gavl_video_source_get_options | ( | gavl_video_source_t * | s | ) |

Get conversion options of a video source.

Parameters

  s | A video source

Returns
  Conversion options

## gavl_video_source_reset()

GAVL_PUBLIC void gavl_video_source_reset | ( | gavl_video_source_t * | s | ) |

Reset a video source.

Parameters

  s | A video source

Call this after seeking to reset the internal state

## gavl_video_source_destroy()

GAVL_PUBLIC void gavl_video_source_destroy | ( | gavl_video_source_t * | s | ) |

Destroy a video source.

Parameters

  s | A video source

Destroy a video source including all video frames ever created by it.

## gavl_video_source_support_hw()

GAVL_PUBLIC void gavl_video_source_support_hw | ( | gavl_video_source_t * | s | ) |

Enable hardware surfaces.

Parameters

  s | A video source

Call this function if you can handle hardware surfaces on the destination side. If this function is not called, hardware surfaces are copied to RAM before they are passed to the destination.

## gavl_video_source_get_src_format()

GAVL_PUBLIC const gavl_video_format_t * gavl_video_source_get_src_format | ( | gavl_video_source_t * | s | ) |

Get the native format.

Parameters

  s | A video source

Returns
  The native video format

## gavl_video_source_get_src_flags()

GAVL_PUBLIC int gavl_video_source_get_src_flags | ( | gavl_video_source_t * | s | ) |

Get the source flags.

Parameters

  s | A video source

Returns
  The source flags

## gavl_video_source_get_dst_format()

GAVL_PUBLIC const gavl_video_format_t * gavl_video_source_get_dst_format | ( | gavl_video_source_t * | s | ) |

Get the output format.

Parameters

  s | A video source

Returns
  The video format in which frames are read

## gavl_video_source_set_dst()

GAVL_PUBLIC void gavl_video_source_set_dst | ( | gavl_video_source_t * | s,
|  | int | dst_flags,
|  | const gavl_video_format_t * | dst_format )

Set the destination mode.

Parameters

  s | A video source
  dst_flags | Flags
  dst_format | Format in which the frames will be read

If you accept the source format (as returned by gavl_video_source_get_src_format) you can pass NULL for the dst_format.

If the destination format differs from the source format, the frames will converted. For this, we have a gavl_video_converter_t and also do simple framerate conversion which repeats/drops frames.

## gavl_video_source_read_frame()

GAVL_PUBLIC gavl_source_status_t gavl_video_source_read_frame | ( | void * | s,
|  | gavl_video_frame_t ** | frame )

Read a video frame.

Parameters

  s | A video source
  frame | Address of a frame.

This reads one frame from the source. If *frame is NULL it will be set to an internal buffer, otherwise the data is copied to the frame you pass.

## gavl_audio_source_create()

GAVL_PUBLIC gavl_audio_source_t * gavl_audio_source_create | ( | gavl_audio_source_func_t | func,
|  | void * | priv,
|  | int | src_flags,
|  | const gavl_audio_format_t * | src_format )

Create an audio source.

Parameters

  func | Function to get the frames from
  priv | Client data to pass to func
  src_flags | Flags describing the source
  src_format | Native source format

Returns
  A newly created audio source

## gavl_audio_source_create_source()

GAVL_PUBLIC gavl_audio_source_t * gavl_audio_source_create_source | ( | gavl_audio_source_func_t | func,
|  | void * | priv,
|  | int | src_flags,
|  | gavl_audio_source_t * | src )

Create an audio source from another source.

Parameters

  func | Function to get the frames from
  priv | Client data to pass to func
  src_flags | Flags describing the source
  src | preceding source in the pipeline

Returns
  A newly created audio source

This will take the destination format of the preceding source as the input format

## gavl_audio_source_set_lock_funcs()

GAVL_PUBLIC void gavl_audio_source_set_lock_funcs | ( | gavl_audio_source_t * | src,
|  | gavl_connector_lock_func_t | lock_func,
|  | gavl_connector_lock_func_t | unlock_func,
|  | void * | priv )

Set lock functions.

Parameters

  src | An audio source
  lock_func | Function called before a frame is read
  unlock_func | Function called after a frame is read
  priv | Client data (e.g. a mutex) to pass to the functions

## gavl_audio_source_set_free_func()

GAVL_PUBLIC void gavl_audio_source_set_free_func | ( | gavl_audio_source_t * | src,
|  | gavl_connector_free_func_t | free_func )

Set free function.

Parameters

  src | A audio source
  free_func | Function called with the private data when the source is destroyed

Use this if you don't want to keep a reference to the private data along with the source

## gavl_audio_source_get_src_format()

GAVL_PUBLIC const gavl_audio_format_t * gavl_audio_source_get_src_format | ( | gavl_audio_source_t * | s | ) |

Get the native format.

Parameters

  s | An audio source

Returns
  The native audio format

## gavl_audio_source_get_dst_format()

GAVL_PUBLIC const gavl_audio_format_t * gavl_audio_source_get_dst_format | ( | gavl_audio_source_t * | s | ) |

Get the output format.

Parameters

  s | An audio source

Returns
  The format in which frames will be read

## gavl_audio_source_get_dst_flags()

GAVL_PUBLIC int gavl_audio_source_get_dst_flags | ( | gavl_audio_source_t * | s | ) |

Get the output flags.

Parameters

  s | An audio source

Returns
  The flags, which were passed to gavl_audio_source_set_dst

## gavl_audio_source_set_dst()

GAVL_PUBLIC void gavl_audio_source_set_dst | ( | gavl_audio_source_t * | s,
|  | int | dst_flags,
|  | const gavl_audio_format_t * | dst_format )

Set the destination mode.

Parameters

  s | An audio source
  dst_flags | Flags
  dst_format | Format in which the frames will be read

If you accept the source format (as returned by gavl_video_source_get_src_format) you can pass NULL for the dst_format.

If the destination format differs from the source format, the frames will converted. For this, we have a gavl_audio_converter_t. In addition, if the samples_per_frame members are different, the frames will be repackaged.

## gavl_audio_source_read_frame()

GAVL_PUBLIC gavl_source_status_t gavl_audio_source_read_frame | ( | void * | s,
|  | gavl_audio_frame_t ** | frame )

Read an audio frame.

Parameters

  s | An audio source
  frame | Address of a frame.

Returns
  The status

This reads one frame from the source. If *frame is NULL it will be set to an internal buffer, otherwise the data is copied to the frame you pass.

If the return value is GAVL_SOURCE_AGAIN, you might have an incomplete frame. In this case you must call this function again with exactly the same frame argument.

## gavl_audio_source_skip()

GAVL_PUBLIC void gavl_audio_source_skip | ( | gavl_audio_source_t * | s,
|  | int | num_samples )

Skip audio samples at the input.

Parameters

  s | An audio source
  num_samples | Number of samples to skip

This skips a number of input samples. It can be used after seeking if the sample position after a seek is no multiple of the frame size.

## gavl_audio_source_read_samples()

GAVL_PUBLIC int gavl_audio_source_read_samples | ( | void * | s,
|  | gavl_audio_frame_t * | frame,
|  | int | num_samples )

Read audio samples.

Parameters

  s | An audio source
  frame | An audio frame
  num_samples | Number of samples to read

This is for APIs, which pass the number of samples to each read() call and the number is not known in advance.

## gavl_audio_source_get_options()

GAVL_PUBLIC gavl_audio_options_t * gavl_audio_source_get_options | ( | gavl_audio_source_t * | s | ) |

Get conversion options of an audio source.

Parameters

  s | An audio source

Returns
  Conversion options

## gavl_audio_source_reset()

GAVL_PUBLIC void gavl_audio_source_reset | ( | gavl_audio_source_t * | s | ) |

Reset an audio source.

Parameters

  s | An audio source

This resets the internal state as if no frame was read yet.

## gavl_audio_source_destroy()

GAVL_PUBLIC void gavl_audio_source_destroy | ( | gavl_audio_source_t * | s | ) |

Destroy an audio source.

Parameters

  s | An audio source

Destroy an audio source including all audio frames ever created by it.

## gavl_packet_source_create()

GAVL_PUBLIC gavl_packet_source_t * gavl_packet_source_create | ( | gavl_packet_source_func_t | func,
|  | void * | priv,
|  | int | src_flags,
|  | const gavl_dictionary_t * | s )

Create a packet source.

Parameters

  func | Callback for reading one frame
  priv | Client data to be passed to func
  src_flags | Flags

Typically, you'll use the more specific functions gavl_packet_source_create_audio, gavl_packet_source_create_video, gavl_packet_source_create_text and gavl_packet_source_create_source

## gavl_packet_source_create_source()

GAVL_PUBLIC gavl_packet_source_t * gavl_packet_source_create_source | ( | gavl_packet_source_func_t | func,
|  | void * | priv,
|  | int | src_flags,
|  | gavl_packet_source_t * | src )

Create a packet source from another packet source.

Parameters

  func | Callback for reading one frame
  priv | Client data to be passed to func
  src_flags | Flags
  src | Source to copy the stream specific data from

## gavl_packet_source_set_lock_funcs()

GAVL_PUBLIC void gavl_packet_source_set_lock_funcs | ( | gavl_packet_source_t * | src,
|  | gavl_connector_lock_func_t | lock_func,
|  | gavl_connector_lock_func_t | unlock_func,
|  | void * | priv )

Set lock functions.

Parameters

  src | A packet source
  lock_func | Function called before a packet is read
  unlock_func | Function called after a packet is read
  priv | Client data (e.g. a mutex) to pass to the functions

## gavl_packet_source_set_free_func()

GAVL_PUBLIC void gavl_packet_source_set_free_func | ( | gavl_packet_source_t * | src,
|  | gavl_connector_free_func_t | free_func )

Set free function.

Parameters

  src | A packet source
  free_func | Function called with the private data when the source is destroyed

Use this if you don't want to keep a reference to the private data along with the source

## gavl_packet_source_get_audio_format()

GAVL_PUBLIC const gavl_audio_format_t * gavl_packet_source_get_audio_format | ( | gavl_packet_source_t * | s | ) |

Get the compression info.

Parameters

  s | A packet source

Returns
  The compression info or NULL

Get the audio format

Parameters

  s | A packet source

Returns
  The audio format or NULL

## gavl_packet_source_get_video_format()

GAVL_PUBLIC const gavl_video_format_t * gavl_packet_source_get_video_format | ( | gavl_packet_source_t * | s | ) |

Get the video format.

Parameters

  s | A packet source

Returns
  The video format or NULL

## gavl_packet_source_get_timescale()

GAVL_PUBLIC int gavl_packet_source_get_timescale | ( | gavl_packet_source_t * | s | ) |

Get the time scale.

Parameters

  s | A packet source

Returns
  The time scale

## gavl_packet_source_read_packet()

GAVL_PUBLIC gavl_source_status_t gavl_packet_source_read_packet | ( | void * | s,
|  | gavl_packet_t ** | p )

Read one packet.

Parameters

  s | A packet source

Returns
  The status

## gavl_packet_source_destroy()

GAVL_PUBLIC void gavl_packet_source_destroy | ( | gavl_packet_source_t * | s | ) |

Destroy a packet source.

Parameters

  s | A packet source