gavl
Defines | Typedefs | Enumerations | Functions

A/V sources

A/V pipeline building elements

Defines

#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_tgavl_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 gavl_video_source_tgavl_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 gavl_video_options_tgavl_video_source_get_options (gavl_video_source_t *s)
 Get coversion 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 const
gavl_video_format_t
gavl_video_source_get_src_format (gavl_video_source_t *s)
 Get the native format.
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_tgavl_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 gavl_audio_source_tgavl_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 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 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_src (gavl_audio_source_t *s, int num_samples)
 Skip audio samples at the input.
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_tgavl_audio_source_get_options (gavl_audio_source_t *s)
 Get coversion 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_tgavl_packet_source_create_audio (gavl_packet_source_func_t func, void *priv, int src_flags, const gavl_compression_info_t *ci, const gavl_audio_format_t *afmt)
 Create an audio packet source.
GAVL_PUBLIC gavl_packet_source_tgavl_packet_source_create_video (gavl_packet_source_func_t func, void *priv, int src_flags, const gavl_compression_info_t *ci, const gavl_video_format_t *vfmt)
 Create a video packet source.
GAVL_PUBLIC gavl_packet_source_tgavl_packet_source_create_text (gavl_packet_source_func_t func, void *priv, int src_flags, int timescale)
 Create a text packet source.
GAVL_PUBLIC gavl_packet_source_tgavl_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 const
gavl_compression_info_t
gavl_packet_source_get_ci (gavl_packet_source_t *s)
 Get the compression info.
GAVL_PUBLIC const
gavl_audio_format_t
gavl_packet_source_get_audio_format (gavl_packet_source_t *s)
 Get the audio format.
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 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.


Define Documentation

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


Typedef Documentation

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

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

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

Prototype for obtaining one audio frame.

Parameters:
privClient data
frameWhere 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

Prototype for obtaining one video frame.

Parameters:
privClient data
frameWhere 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.

Prototype for obtaining one packet.

Parameters:
privClient data
frameWhere 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

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_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:
funcFunction to get the frames from
privClient data to pass to func
src_flagsFlags describing the source
src_formatNative source format
Returns:
A newly created video 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:
funcFunction to get the frames from
privClient data to pass to func
src_flagsFlags describing the source
srcpreceeding source in the pipeline
Returns:
A newly created video source

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

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:
srcA video source
lock_funcFunction called before a frame is read
unlock_funcFunction called after a frame is read
privClient data (e.g. a mutex) to pass to the functions
GAVL_PUBLIC gavl_video_options_t* gavl_video_source_get_options ( gavl_video_source_t s)

Get coversion options of a video source.

Parameters:
sA video source
Returns:
Conversion options
GAVL_PUBLIC void gavl_video_source_reset ( gavl_video_source_t s)

Reset a video source.

Parameters:
sA video source

Call this after seeking to reset the internal state

GAVL_PUBLIC void gavl_video_source_destroy ( gavl_video_source_t s)

Destroy a video source.

Parameters:
sA video source

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

GAVL_PUBLIC const gavl_video_format_t* gavl_video_source_get_src_format ( gavl_video_source_t s)

Get the native format.

Parameters:
sA video source
Returns:
The native video format
GAVL_PUBLIC const gavl_video_format_t* gavl_video_source_get_dst_format ( gavl_video_source_t s)

Get the output format.

Parameters:
sA video source
Returns:
The video format in which frames are read
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:
sA video source
dst_flagsFlags
dst_formatFormat 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_PUBLIC gavl_source_status_t gavl_video_source_read_frame ( void *  s,
gavl_video_frame_t **  frame 
)

Read a video frame.

Parameters:
sA video source
frameAddress 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_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:
funcFunction to get the frames from
privClient data to pass to func
src_flagsFlags describing the source
src_formatNative source format
Returns:
A newly created audio 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:
funcFunction to get the frames from
privClient data to pass to func
src_flagsFlags describing the source
srcpreceeding source in the pipeline
Returns:
A newly created audio source

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

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:
srcAn audio source
lock_funcFunction called before a frame is read
unlock_funcFunction called after a frame is read
privClient data (e.g. a mutex) to pass to the functions
GAVL_PUBLIC const gavl_audio_format_t* gavl_audio_source_get_src_format ( gavl_audio_source_t s)

Get the native format.

Parameters:
sAn audio source
Returns:
The native audio format
GAVL_PUBLIC const gavl_audio_format_t* gavl_audio_source_get_dst_format ( gavl_audio_source_t s)

Get the output format.

Parameters:
sAn audio source
Returns:
The format in which frames will be read
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:
sAn audio source
dst_flagsFlags
dst_formatFormat 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_PUBLIC gavl_source_status_t gavl_audio_source_read_frame ( void *  s,
gavl_audio_frame_t **  frame 
)

Read an audio frame.

Parameters:
sAn audio source
frameAddress 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 imcomplete frame. In this case you must call this function again with exactly the same frame argument.

GAVL_PUBLIC void gavl_audio_source_skip_src ( gavl_audio_source_t s,
int  num_samples 
)

Skip audio samples at the input.

Parameters:
sAn audio source
num_samplesNumber 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_PUBLIC int gavl_audio_source_read_samples ( void *  s,
gavl_audio_frame_t frame,
int  num_samples 
)

Read audio samples.

Parameters:
sAn audio source
frameAn audio frame
num_samplesNumber 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_PUBLIC gavl_audio_options_t* gavl_audio_source_get_options ( gavl_audio_source_t s)

Get coversion options of an audio source.

Parameters:
sAn audio source
Returns:
Conversion options
GAVL_PUBLIC void gavl_audio_source_reset ( gavl_audio_source_t s)

Reset an audio source.

Parameters:
sAn audio source

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

GAVL_PUBLIC void gavl_audio_source_destroy ( gavl_audio_source_t s)

Destroy an audio source.

Parameters:
sAn audio source

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

GAVL_PUBLIC gavl_packet_source_t* gavl_packet_source_create_audio ( gavl_packet_source_func_t  func,
void *  priv,
int  src_flags,
const gavl_compression_info_t ci,
const gavl_audio_format_t afmt 
)

Create an audio packet source.

Parameters:
funcCallback for reading one frame
privClient data to be passed to func
src_flagsFlags
ciCompression info
afmtFormat of the audio stream
GAVL_PUBLIC gavl_packet_source_t* gavl_packet_source_create_video ( gavl_packet_source_func_t  func,
void *  priv,
int  src_flags,
const gavl_compression_info_t ci,
const gavl_video_format_t vfmt 
)

Create a video packet source.

Parameters:
funcCallback for reading one frame
privClient data to be passed to func
src_flagsFlags
ciCompression info
vfmtFormat of the video stream
GAVL_PUBLIC gavl_packet_source_t* gavl_packet_source_create_text ( gavl_packet_source_func_t  func,
void *  priv,
int  src_flags,
int  timescale 
)

Create a text packet source.

Parameters:
funcCallback for reading one frame
privClient data to be passed to func
src_flagsFlags
scaleTimescale of the text packets
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:
funcCallback for reading one frame
privClient data to be passed to func
src_flagsFlags
srcSource to copy the stream specific data from
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:
srcA packet source
lock_funcFunction called before a packet is read
unlock_funcFunction called after a packet is read
privClient data (e.g. a mutex) to pass to the functions
GAVL_PUBLIC const gavl_compression_info_t* gavl_packet_source_get_ci ( gavl_packet_source_t s)

Get the compression info.

Parameters:
sA packet source
Returns:
The compression info or NULL
GAVL_PUBLIC const gavl_audio_format_t* gavl_packet_source_get_audio_format ( gavl_packet_source_t s)

Get the audio format.

Parameters:
sA packet source
Returns:
The audio format or NULL
GAVL_PUBLIC const gavl_video_format_t* gavl_packet_source_get_video_format ( gavl_packet_source_t s)

Get the video format.

Parameters:
sA packet source
Returns:
The video format or NULL
GAVL_PUBLIC int gavl_packet_source_get_timescale ( gavl_packet_source_t s)

Get the time scale.

Parameters:
sA packet source
Returns:
The time scale
GAVL_PUBLIC gavl_source_status_t gavl_packet_source_read_packet ( void *  s,
gavl_packet_t **  p 
)

Read one packet.

Parameters:
sA packet source
Returns:
The status
GAVL_PUBLIC void gavl_packet_source_destroy ( gavl_packet_source_t s)

Destroy a packet source.

Parameters:
sA packet source