Configuration of a decoder
[Decoding of multimedia streams]

Typedefs
typedef struct bgav_options_s	bgav_options_t
	Opaque option container.
typedef void(*	bgav_log_callback )(void *data, bgav_log_level_t level, const char *log_domain, const char *message)
	Function to be called for loggins messages.
typedef void(*	bgav_name_change_callback )(void *data, const char *name)
	Function to be called if the track name changes.
typedef void(*	bgav_metadata_change_callback )(void *data, const bgav_metadata_t *metadata)
	Function to be called if the metadata change.
typedef void(*	bgav_buffer_callback )(void *data, float percentage)
	Function to be called if the input module is buffering data.
typedef int(*	bgav_user_pass_callback )(void *data, const char *resource, char **username, char **password)
	Function to be called if the input module needs authentication data.
typedef void(*	bgav_aspect_callback )(void *data, int stream, int pixel_width, int pixel_height)
	Function to be called if a change of the aspect ratio was detected.
typedef void(*	bgav_index_callback )(void *data, float percentage)
	Function to be called periodically while an index is built.
Enumerations
enum	bgav_log_level_t { BGAV_LOG_DEBUG = (1<<0), BGAV_LOG_WARNING = (1<<1), BGAV_LOG_ERROR = (1<<2), BGAV_LOG_INFO = (1<<3) }
	Enumeration for log levels. More...
Functions
BGAV_PUBLIC bgav_options_t *	bgav_get_options (bgav_t *bgav)
	Get the options of a decoder instance.
BGAV_PUBLIC bgav_options_t *	bgav_options_create ()
	Create an options container.
BGAV_PUBLIC void	bgav_options_destroy (bgav_options_t *opt)
	Destroy option cotainer.
BGAV_PUBLIC void	bgav_options_copy (bgav_options_t *dst, const bgav_options_t *src)
	Copy options.
BGAV_PUBLIC void	bgav_options_set_connect_timeout (bgav_options_t *opt, int timeout)
	Set connect timeout.
BGAV_PUBLIC void	bgav_options_set_read_timeout (bgav_options_t *opt, int timeout)
	Set read timeout.
BGAV_PUBLIC void	bgav_options_set_rtp_port_base (bgav_options_t *b, int p)
	Set RTP port pase.
BGAV_PUBLIC void	bgav_options_set_rtp_try_tcp (bgav_options_t *b, int enable)
	Try TCP before UDP.
BGAV_PUBLIC void	bgav_options_set_network_bandwidth (bgav_options_t *opt, int bandwidth)
	Set network bandwidth.
BGAV_PUBLIC void	bgav_options_set_network_buffer_size (bgav_options_t *opt, int size)
	Set network buffer size.
BGAV_PUBLIC void	bgav_options_set_http_use_proxy (bgav_options_t *opt, int enable)
	Set proxy usage.
BGAV_PUBLIC void	bgav_options_set_http_proxy_host (bgav_options_t *opt, const char *host)
	Set proxy host.
BGAV_PUBLIC void	bgav_options_set_http_proxy_port (bgav_options_t *opt, int port)
	Set proxy port.
BGAV_PUBLIC void	bgav_options_set_http_proxy_auth (bgav_options_t *opt, int enable)
	Enable or disable proxy authentication.
BGAV_PUBLIC void	bgav_options_set_http_proxy_user (bgav_options_t *opt, const char *user)
	Set proxy username.
BGAV_PUBLIC void	bgav_options_set_http_proxy_pass (bgav_options_t *opt, const char *pass)
	Set proxy password.
BGAV_PUBLIC void	bgav_options_set_http_shoutcast_metadata (bgav_options_t *opt, int enable)
	Enable or disable shoutcast metadata streaming.
BGAV_PUBLIC void	bgav_options_set_ftp_anonymous (bgav_options_t *opt, int enable)
	Enable or disable anonymous ftp login.
BGAV_PUBLIC void	bgav_options_set_ftp_anonymous_password (bgav_options_t *opt, const char *pass)
	Set anonymous password.
BGAV_PUBLIC void	bgav_options_set_default_subtitle_encoding (bgav_options_t *opt, const char *encoding)
	Set default subtitle encoding.
BGAV_PUBLIC void	bgav_options_set_audio_dynrange (bgav_options_t *opt, int audio_dynrange)
	Enable dynamic range control.
BGAV_PUBLIC void	bgav_options_set_sample_accurate (bgav_options_t *opt, int enable)
	Try to be sample accurate.
BGAV_PUBLIC void	bgav_options_set_cache_time (bgav_options_t *opt, int t)
	Set the index creation time for caching.
BGAV_PUBLIC void	bgav_options_set_cache_size (bgav_options_t *opt, int s)
	Set the maximum total size of the index cache.
BGAV_PUBLIC void	bgav_options_set_seek_subtitles (bgav_options_t *opt, int seek_subtitles)
	Enable external subtitle files.
BGAV_PUBLIC void	bgav_options_set_pp_level (bgav_options_t *opt, int pp_level)
	Set postprocessing level.
BGAV_PUBLIC void	bgav_options_set_postprocessing_level (bgav_options_t *opt, float pp_level)
	Set postprocessing level.
BGAV_PUBLIC void	bgav_options_set_threads (bgav_options_t *opt, int threads)
	Set number of threads.
BGAV_PUBLIC void	bgav_options_set_dvb_channels_file (bgav_options_t *opt, const char *file)
	Set DVB channels file.
BGAV_PUBLIC void	bgav_options_set_prefer_ffmpeg_demuxers (bgav_options_t *opt, int prefer)
	Preference of ffmpeg demultiplexers.
BGAV_PUBLIC void	bgav_options_set_dv_datetime (bgav_options_t *opt, int datetime)
	Exports the date and time as timecode field of DV streams.
BGAV_PUBLIC void	bgav_options_set_shrink (bgav_options_t *opt, int factor)
	Shrink factor.
BGAV_PUBLIC void	bgav_options_set_vdpau (bgav_options_t *opt, int vdpau)
	VDPAU acceleration.
BGAV_PUBLIC void	bgav_options_set_log_callback (bgav_options_t *opt, bgav_log_callback callback, void *data)
	Set the callback for log messages.
BGAV_PUBLIC void	bgav_options_set_log_level (bgav_options_t *opt, int level)
	Set the verbosity for log messages.
BGAV_PUBLIC void	bgav_options_set_name_change_callback (bgav_options_t *opt, bgav_name_change_callback callback, void *data)
	Set the callback for name change events.
BGAV_PUBLIC void	bgav_options_set_metadata_change_callback (bgav_options_t *opt, bgav_metadata_change_callback callback, void *data)
	Set the callback for metadata change events.
BGAV_PUBLIC void	bgav_options_set_buffer_callback (bgav_options_t *opt, bgav_buffer_callback callback, void *data)
	Set the callback for buffering notification.
BGAV_PUBLIC void	bgav_options_set_user_pass_callback (bgav_options_t *opt, bgav_user_pass_callback callback, void *data)
	Set the callback for user authentication.
BGAV_PUBLIC void	bgav_options_set_aspect_callback (bgav_options_t *opt, bgav_aspect_callback callback, void *data)
	Set aspect ratio change callback.
BGAV_PUBLIC void	bgav_options_set_index_callback (bgav_options_t *opt, bgav_index_callback callback, void *data)
	Set index build callback.

---

Detailed Description

These functions are used to configure a decoder and to set callback functions. After you created a bgav_t object, get it's options with bgav_get_options. All options are returned in an option container (bgav_options_t), and the bgav_options_set_* functions allow you to change single options. As an alternative, you can create an independent option container with bgav_options_create, change it as you like and use bgav_options_copy to copy them to the container you got with bgav_get_options.

All options become valid with (and should not be changed after) the call to one of the bgav_open* functions.

---

Typedef Documentation

typedef struct bgav_options_s bgav_options_t

Opaque option container.

typedef void(* bgav_log_callback)(void *data, bgav_log_level_t level, const char *log_domain, const char *message)

Function to be called for loggins messages.

Parameters:

data

The data you passed to bgav_options_set_log_callback. Parameters: level  The log level Parameters: log_domain  A string describing the module from which the message comes Parameters: message  The message itself

typedef void(* bgav_name_change_callback)(void *data, const char *name)

Function to be called if the track name changes.

Parameters:

data

The data you passed to bgav_options_set_name_change_callback. Parameters: name  The new name of the track This function will be called whenever the name of the track changed. Such changes can have different reasons, the most obvious one is a song change in a webradio stream.

typedef void(* bgav_metadata_change_callback)(void *data, const bgav_metadata_t *metadata)

Function to be called if the metadata change.

Parameters:

data

The data you passed to bgav_options_set_metadata_change_callback. Parameters: metadata  The new metadata of the track This function will be called whenever the metadata of the track changed. Such changes can have different reasons, the most obvious one is a song change in a webradio stream.

typedef void(* bgav_buffer_callback)(void *data, float percentage)

Function to be called if the input module is buffering data.

Parameters:

data

The data you passed to bgav_options_set_buffer_callback. Parameters: percentage  The percentage done so far (0.0 .. 1.0) This function will be called when the input module fills a buffer. It is called multiple times with increasing percentage.

typedef int(* bgav_user_pass_callback)(void *data, const char *resource, char **username, char **password)

Function to be called if the input module needs authentication data.

Parameters:

data

The data you passed to bgav_options_set_user_pass_callback. Parameters: resource  A string describing the resource (e.g. the hostname of the server) Parameters: username  Returns the username. Parameters: password  Returns the password. Returns: 1 of the username and password are valid, 0 if the user cancelled the authentication. This is called during one of the bgav_open* calls.

typedef void(* bgav_aspect_callback)(void *data, int stream, int pixel_width, int pixel_height)

Function to be called if a change of the aspect ratio was detected.

Parameters:

data

The data you passed to bgav_options_set_aspect_callback. Parameters: stream  Index of the video stream (starts with 0) Parameters: pixel_width  New pixel width Parameters: pixel_height  New pixel height This is called during bgav_read_video.

typedef void(* bgav_index_callback)(void *data, float percentage)

Function to be called periodically while an index is built.

Parameters:

data

The data you passed to bgav_options_set_index_callback. Parameters: perc  Percentage completed to far

---

Enumeration Type Documentation

enum bgav_log_level_t

Enumeration for log levels.

These will be called from within log callbacks

---

Function Documentation

BGAV_PUBLIC bgav_options_t* bgav_get_options

(

bgav_t *

bgav

)

Get the options of a decoder instance.

Returns:

Options

Use this to get the options container. You can use the bgav_options_set_* functions to change the options. Options will become valid when you call one of the bgav_open*() functions.

BGAV_PUBLIC bgav_options_t* bgav_options_create

(

)

Create an options container.

Returns:

A newly allocated option container

This function returns a newly allocated option container filled with default values. Use this, if you need to store decoder options independently from decoder instances. To destroy the container again, use bgav_options_destroy.

To pass the options to a decoder structure, use bgav_get_options and bgav_options_copy.

BGAV_PUBLIC void bgav_options_destroy

(

bgav_options_t *

opt

)

Destroy option cotainer.

Parameters:

opt

option cotainer

Use the only to destroy options, you created with bgav_options_create. Options returned by bgav_get_options are owned by the bgav_t instance, and must not be freed by you.

BGAV_PUBLIC void bgav_options_copy	(	bgav_options_t *	dst,
		const bgav_options_t *	src
	)

Copy options.

Parameters:

dst

Destination Parameters: src  Source

BGAV_PUBLIC void bgav_options_set_connect_timeout	(	bgav_options_t *	opt,
		int	timeout
	)

Set connect timeout.

Parameters:

opt

Option container Parameters: timeout  Timeout in milliseconds. This timeout will be used until the connection is ready to receive media data.

BGAV_PUBLIC void bgav_options_set_read_timeout	(	bgav_options_t *	opt,
		int	timeout
	)

Set read timeout.

Parameters:

opt

Option container Parameters: timeout  Timeout in milliseconds. This timeout will be used during streaming to detect server/connection failures.

BGAV_PUBLIC void bgav_options_set_rtp_port_base	(	bgav_options_t *	b,
		int	p
	)

Set RTP port pase.

Parameters:

opt

Option container Parameters: p  Port base Values below and including 1024 enable random ports. Random ports should be used if you have no or an RTSP aware firewall. Values above 1024 enable a fixed base port. For usual videos (one audio- one videostream) you need 4 consecutive open ports starting with the base port. If your firewall blocks all UDP traffic, use bgav_options_set_rtp_try_tcp.

BGAV_PUBLIC void bgav_options_set_rtp_try_tcp	(	bgav_options_t *	b,
		int	enable
	)

Try TCP before UDP.

Parameters:

opt

Option container Parameters: enable  1 to try TCP, 0 else Use this if your firewall blocks all UDP traffic. Not all servers, however, support TCP fallback.

BGAV_PUBLIC void bgav_options_set_network_bandwidth	(	bgav_options_t *	opt,
		int	bandwidth
	)

Set network bandwidth.

Parameters:

opt

Option container Parameters: bandwidth  Bandwidth of your internet connection (in bits per second) Some network protocols allow to select among multiple streams according to the speed of the internet connection.

BGAV_PUBLIC void bgav_options_set_network_buffer_size	(	bgav_options_t *	opt,
		int	size
	)

Set network buffer size.

Parameters:

opt

Option container Parameters: size  Buffer size in bytes Set the size of the network buffer. Todo: Make buffer size depend on the stream bitrate.

BGAV_PUBLIC void bgav_options_set_http_use_proxy	(	bgav_options_t *	opt,
		int	enable
	)

Set proxy usage.

Parameters:

opt

Option container Parameters: enable  Set 1 of you use a http proxy, 0 else. Set usage of a http proxy. If you enable proxies, you must specify the proxy host with bgav_options_set_http_proxy_host and the proxy port with bgav_options_set_http_proxy_port.

BGAV_PUBLIC void bgav_options_set_http_proxy_host	(	bgav_options_t *	opt,
		const char *	host
	)

Set proxy host.

Parameters:

opt

Option container Parameters: host  Hostname of the proxy. Note that you must enable proxies with bgav_options_set_http_use_proxy before it's actually used.

BGAV_PUBLIC void bgav_options_set_http_proxy_port	(	bgav_options_t *	opt,
		int	port
	)

Set proxy port.

Parameters:

opt

Option container Parameters: port  Port of the proxy. Note that you must enable proxies with bgav_options_set_http_use_proxy before it's actually used.

BGAV_PUBLIC void bgav_options_set_http_proxy_auth	(	bgav_options_t *	opt,
		int	enable
	)

Enable or disable proxy authentication.

Parameters:

opt

Option container Parameters: enable  Set 1 if your http proxy needs authentication, 0 else. If you enable http proxy authentication, you must specify the username host with bgav_options_set_http_proxy_user and the proxy password with bgav_options_set_http_proxy_pass.

BGAV_PUBLIC void bgav_options_set_http_proxy_user	(	bgav_options_t *	opt,
		const char *	user
	)

Set proxy username.

Parameters:

opt

Option container Parameters: user  The username for the proxy. Note that you must enable proxy authentication with bgav_options_set_http_proxy_auth.

BGAV_PUBLIC void bgav_options_set_http_proxy_pass	(	bgav_options_t *	opt,
		const char *	pass
	)

Set proxy password.

Parameters:

opt

Option container Parameters: pass  The password for the proxy. Note that you must enable proxy authentication with bgav_options_set_http_proxy_auth.

BGAV_PUBLIC void bgav_options_set_http_shoutcast_metadata	(	bgav_options_t *	opt,
		int	enable
	)

Enable or disable shoutcast metadata streaming.

Parameters:

opt

Option container Parameters: enable  Set to 1 if the decoder should try to get shoutcast metadata, 0 else Normally it's ok to enable shoutcast metadata streaming even if we connect to non-shoutcast servers.

BGAV_PUBLIC void bgav_options_set_ftp_anonymous	(	bgav_options_t *	opt,
		int	enable
	)

Enable or disable anonymous ftp login.

Parameters:

opt

Option container Parameters: enable  Set to 1 if the decoder should try log anonymously into ftp servers, 0 else

BGAV_PUBLIC void bgav_options_set_ftp_anonymous_password	(	bgav_options_t *	opt,
		const char *	pass
	)

Set anonymous password.

Parameters:

opt

Option container Parameters: pass  Note that you must enable anonymous ftp login with bgav_options_set_ftp_anonymous.

BGAV_PUBLIC void bgav_options_set_default_subtitle_encoding	(	bgav_options_t *	opt,
		const char *	encoding
	)

Set default subtitle encoding.

Parameters:

opt

Option container Parameters: encoding  Encoding This sets the default encoding for text subtitles, when the right encoding is unknown. It must be a character set name recognized by iconv. Type "iconv -l" at the commandline for a list of supported encodings).

BGAV_PUBLIC void bgav_options_set_audio_dynrange	(	bgav_options_t *	opt,
		int	audio_dynrange
	)

Enable dynamic range control.

Parameters:

opt

Option container Parameters: audio_dynrange  1 for enabling dynamic range control. This enables dynamic range control for codecs, which supports it. By default dynamic range control is enabled. Use this function to switch it off for the case, that you have a better dynamic range control in your processing pipe.

BGAV_PUBLIC void bgav_options_set_sample_accurate	(	bgav_options_t *	opt,
		int	enable
	)

Try to be sample accurate.

Parameters:

opt

Option container Parameters: enable  Specifies how sample accurate mode should be enabled (see below) If enable is 0, sample accuracy will never be enabled. If enable is 1, sample accuracy will always (whenever possible) be enabled. If enable is 2, sample accuracy will only be enabled, if the file would not be seekable otherwise.

When switching to sample accurate mode, other demultiplexing methods are enabled, which might slow things down a bit.

BGAV_PUBLIC void bgav_options_set_cache_time	(	bgav_options_t *	opt,
		int	t
	)

Set the index creation time for caching.

Parameters:

opt

Option container Parameters: t  Time (in milliseconds) needed for creating the index This option controls, which indices are cached, based on the time needed for creating the index. Indices, whose creation takes longer than the specified time will be cached. If you set this to zero, all indices are cached.

BGAV_PUBLIC void bgav_options_set_cache_size	(	bgav_options_t *	opt,
		int	s
	)

Set the maximum total size of the index cache.

Parameters:

opt

Option container Parameters: s  Maximum size (in megabytes) of the whole cache directory If a new index is created and the size becomes larger than the maximum size, older indices will be deleted. Zero means infinite.

BGAV_PUBLIC void bgav_options_set_seek_subtitles	(	bgav_options_t *	opt,
		int	seek_subtitles
	)

Enable external subtitle files.

Parameters:

opt

Option container Parameters: seek_subtitles  If 1, subtitle files will be seeked for video files. If 2, subtitles will be seeked for all files. If the input is a regular file, gmerlin_avdecoder can scan the directory for matching subtitle files. For a file movie.mpg, possible subtitle files are e.g. movie_english.srt, movie_german.srt. The rule is, that the first part of the filename of the subtitle file must be equal to the movie filename up to the extension (hiere: .mpg). Furthermore, the subtitle filename must have an extension supported by any of the subtitle readers.

BGAV_PUBLIC void bgav_options_set_pp_level	(	bgav_options_t *	opt,
		int	pp_level
	)

Set postprocessing level.

Parameters:

opt

Option container Parameters: pp_level  Value between 0 (no postprocessing) and 6 (maximum postprocessing) Warning: This function is depracated, use bgav_options_set_postprocessing_level instead.

BGAV_PUBLIC void bgav_options_set_postprocessing_level	(	bgav_options_t *	opt,
		float	pp_level
	)

Set postprocessing level.

Parameters:

opt

Option container Parameters: pp_level  Value between 0.0 (no postprocessing) and 1.0 (maximum postprocessing) Since 1.0.2

BGAV_PUBLIC void bgav_options_set_threads	(	bgav_options_t *	opt,
		int	threads
	)

Set number of threads.

Parameters:

opt

Option container Parameters: threads  Number of threads to use Not all codecs support this

BGAV_PUBLIC void bgav_options_set_dvb_channels_file	(	bgav_options_t *	opt,
		const char *	file
	)

Set DVB channels file.

Parameters:

opt

Option container Parameters: file  Name of the channel configurations file The channels file must have the format of the dvb-utils programs (like szap, tzap). If you don't set this file, several locations like $HOME/.tzap/channels.conf will be searched.

BGAV_PUBLIC void bgav_options_set_prefer_ffmpeg_demuxers	(	bgav_options_t *	opt,
		int	prefer
	)

Preference of ffmpeg demultiplexers.

Parameters:

opt

Option container Parameters: prefer  1 to prefer ffmpeg demultiplexers, 0 else Usually, native demultiplexers are prefered over the ffmpeg ones. This function allows you to chnage that. If gmerlin_avdecoder was compiled without libavformat support, this function is meaningless.

BGAV_PUBLIC void bgav_options_set_dv_datetime	(	bgav_options_t *	opt,
		int	datetime
	)

Exports the date and time as timecode field of DV streams.

Parameters:

opt

Option container Parameters: datetime  1 to export date and time as timecodes, 0 else

BGAV_PUBLIC void bgav_options_set_shrink	(	bgav_options_t *	opt,
		int	factor
	)

Shrink factor.

Parameters:

opt

Option container Parameters: Exponent  of the shrink factor This enables downscaling of images while decoding. Currently only supported for JPEG-2000.

BGAV_PUBLIC void bgav_options_set_vdpau	(	bgav_options_t *	opt,
		int	vdpau
	)

VDPAU acceleration.

Parameters:

opt

Option container Parameters: 1  to enable vdpau, 0 else Since 1.0.2

BGAV_PUBLIC void bgav_options_set_log_callback	(	bgav_options_t *	opt,
		bgav_log_callback	callback,
		void *	data
	)

Set the callback for log messages.

Parameters:

opt

Option container Parameters: callback  The callback Parameters: data  Some data you want to get passed to the callback

BGAV_PUBLIC void bgav_options_set_log_level	(	bgav_options_t *	opt,
		int	level
	)

Set the verbosity for log messages.

Parameters:

opt

Option container Parameters: level  ORed flags of type bgav_log_level_t Since 1.1.0

BGAV_PUBLIC void bgav_options_set_name_change_callback	(	bgav_options_t *	opt,
		bgav_name_change_callback	callback,
		void *	data
	)

Set the callback for name change events.

Parameters:

opt

Option container Parameters: callback  The callback Parameters: data  Some data you want to get passed to the callback

BGAV_PUBLIC void bgav_options_set_metadata_change_callback	(	bgav_options_t *	opt,
		bgav_metadata_change_callback	callback,
		void *	data
	)

Set the callback for metadata change events.

Parameters:

opt

Option container Parameters: callback  The callback Parameters: data  Some data you want to get passed to the callback

BGAV_PUBLIC void bgav_options_set_buffer_callback	(	bgav_options_t *	opt,
		bgav_buffer_callback	callback,
		void *	data
	)

Set the callback for buffering notification.

Parameters:

opt

Option container Parameters: callback  The callback Parameters: data  Some data you want to get passed to the callback

BGAV_PUBLIC void bgav_options_set_user_pass_callback	(	bgav_options_t *	opt,
		bgav_user_pass_callback	callback,
		void *	data
	)

Set the callback for user authentication.

Parameters:

opt

Option container Parameters: callback  The callback Parameters: data  Some data you want to get passed to the callback Note that there is no default authentication built into the library. Therefore you MUST set a callback, otherwise urls which require the user to enter authentication data, cannot be openend.

BGAV_PUBLIC void bgav_options_set_aspect_callback	(	bgav_options_t *	opt,
		bgav_aspect_callback	callback,
		void *	data
	)

Set aspect ratio change callback.

Parameters:

opt

Option container Parameters: callback  The callback Parameters: data  Some data you want to get passed to the callback

BGAV_PUBLIC void bgav_options_set_index_callback	(	bgav_options_t *	opt,
		bgav_index_callback	callback,
		void *	data
	)

Set index build callback.

Parameters:

opt

Option container Parameters: callback  The callback Parameters: data  Some data you want to get passed to the callback