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 *opt, int p)
	Set RTP port pase.
BGAV_PUBLIC void	bgav_options_set_rtp_try_tcp (bgav_options_t *opt, 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_dump_headers (bgav_options_t *opt, int enable)
	Dump file headers.
BGAV_PUBLIC void	bgav_options_set_dump_indices (bgav_options_t *opt, int enable)
	Dump file indices.
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.
	level	The log level
	log_domain	A string describing the module from which the message comes
	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.
	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.
	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.
	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.
	resource	A string describing the resource (e.g. the hostname of the server)
	username	Returns the username.
	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.
	stream	Index of the video stream (starts with 0)
	pixel_width	New pixel width
	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.
	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
	src	Source

BGAV_PUBLIC void bgav_options_set_connect_timeout	(	bgav_options_t *	opt,
		int	timeout
	)

Set connect timeout.

Parameters:

	opt	Option container
	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
	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 *	opt,
		int	p
	)

Set RTP port pase.

Parameters:

	opt	Option container
	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 *	opt,
		int	enable
	)

Try TCP before UDP.

Parameters:

	opt	Option container
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	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
	factor	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
	vdpau	1 to enable vdpau, 0 else

Since 1.0.2

BGAV_PUBLIC void bgav_options_set_dump_headers	(	bgav_options_t *	opt,
		int	enable
	)

Dump file headers.

Parameters:

	opt	Option container
	enable	1 to dump file headers, 0 else

Since 1.1.1

BGAV_PUBLIC void bgav_options_set_dump_indices	(	bgav_options_t *	opt,
		int	enable
	)

Dump file indices.

Parameters:

	opt	Option container
	enable	1 to dump file indices, 0 else

Since 1.1.1

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
	callback	The callback
	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
	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
	callback	The callback
	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
	callback	The callback
	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
	callback	The callback
	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
	callback	The callback
	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
	callback	The callback
	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
	callback	The callback
	data	Some data you want to get passed to the callback