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_track_change_callback )(void *data, int track)
 Function to be called if the track number changes.
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, BGAV_LOG_WARNING, BGAV_LOG_ERROR, BGAV_LOG_INFO }
 Enumeration for log levels. More...

Functions

bgav_options_tbgav_get_options (bgav_t *bgav)
 Get the options of a decoder instance.
bgav_options_tbgav_options_create ()
 Create an options container.
void bgav_options_destroy (bgav_options_t *opt)
 Destroy option cotainer.
void bgav_options_copy (bgav_options_t *dst, const bgav_options_t *src)
 Copy options.
void bgav_options_set_connect_timeout (bgav_options_t *opt, int timeout)
 Set connect timeout.
void bgav_options_set_read_timeout (bgav_options_t *opt, int timeout)
 Set read timeout.
void bgav_options_set_network_bandwidth (bgav_options_t *opt, int bandwidth)
 Set network bandwidth.
void bgav_options_set_network_buffer_size (bgav_options_t *opt, int size)
 Set network buffer size.
void bgav_options_set_http_use_proxy (bgav_options_t *opt, int enable)
 Set proxy usage.
void bgav_options_set_http_proxy_host (bgav_options_t *opt, const char *host)
 Set proxy host.
void bgav_options_set_http_proxy_port (bgav_options_t *opt, int port)
 Set proxy port.
void bgav_options_set_http_proxy_auth (bgav_options_t *opt, int enable)
 Enable or disable proxy authentication.
void bgav_options_set_http_proxy_user (bgav_options_t *opt, const char *user)
 Set proxy username.
void bgav_options_set_http_proxy_pass (bgav_options_t *opt, const char *pass)
 Set proxy password.
void bgav_options_set_http_shoutcast_metadata (bgav_options_t *opt, int enable)
 Enable or disable shoutcast metadata streaming.
void bgav_options_set_ftp_anonymous (bgav_options_t *opt, int enable)
 Enable or disable anonymous ftp login.
void bgav_options_set_ftp_anonymous_password (bgav_options_t *opt, const char *pass)
 Set anonymous password.
void bgav_options_set_default_subtitle_encoding (bgav_options_t *opt, const char *encoding)
 Set default subtitle encoding.
void bgav_options_set_audio_dynrange (bgav_options_t *opt, int audio_dynrange)
 Enable dynamic range control.
void bgav_options_set_seamless (bgav_options_t *opt, int seamless)
 Enable seamless playback.
void bgav_options_set_sample_accurate (bgav_options_t *opt, int enable)
 Try to be sample accurate.
void bgav_options_set_cache_time (bgav_options_t *opt, int t)
 Set the index creation time for caching.
void bgav_options_set_cache_size (bgav_options_t *opt, int s)
 Set the maximum total size of the index cache.
void bgav_options_set_seek_subtitles (bgav_options_t *opt, int seek_subtitles)
 Enable external subtitle files.
void bgav_options_set_pp_level (bgav_options_t *opt, int pp_level)
 Set postprocessing level.
void bgav_options_set_dvb_channels_file (bgav_options_t *opt, const char *file)
 Set DVB channels file.
void bgav_options_set_prefer_ffmpeg_demuxers (bgav_options_t *opt, int prefer)
 Preference of ffmpeg demultiplexers.
void bgav_options_set_log_callback (bgav_options_t *opt, bgav_log_callback callback, void *data)
 Set the callback for log messages.
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.
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.
void bgav_options_set_track_change_callback (bgav_options_t *opt, bgav_track_change_callback callback, void *data)
 Set the callback for track change events.
void bgav_options_set_buffer_callback (bgav_options_t *opt, bgav_buffer_callback callback, void *data)
 Set the callback for buffering notification.
void bgav_options_set_user_pass_callback (bgav_options_t *opt, bgav_user_pass_callback callback, void *data)
 Set the callback for user authentication.
void bgav_options_set_aspect_callback (bgav_options_t *opt, bgav_aspect_callback callback, void *data)
 Set aspect ratio change callback.
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_track_change_callback)(void *data, int track)

Function to be called if the track number changes.

Parameters:
data The data you passed to bgav_options_set_track_change_callback.
track The new track number
This function will be called if the decoder has multiple tracks, but allows seamless playback of the tracks and a track change occurred.

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

Enumeration for log levels.

These will be called from within log callbacks


Function Documentation

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

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.

void bgav_options_copy ( bgav_options_t dst,
const bgav_options_t src 
)

Copy options.

Parameters:
dst Destination
src Source

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

void bgav_options_set_seamless ( bgav_options_t opt,
int  seamless 
)

Enable seamless playback.

Parameters:
opt Option container
seamless 1 for enabling seamless playback
Note:
This function does nothing for now
If a source has multiple tracks, we can sometimes switch to the next track seamlessly (i.e. without closing and reopening the codecs). If you set this option, the decoder will not signal EOF at the end of a track if a seamless transition to the next track is possible. Instead, the track change is signalled with the bgav_track_change_callback (if available) and decoding continues.
Todo:
Seamless playback isn't implemented yet. This function might be removed in future versions.

void bgav_options_set_sample_accurate ( bgav_options_t opt,
int  enable 
)

Try to be sample accurate.

Parameters:
opt Option container
enable 1 is sample accurate mode is requested
When switching to sample accurate mode, other demultiplexing methods are enabled, which might slow things down a bit. Use this only when the application relies on sample accurate positioning of streams.

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.

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.

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.

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)

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.

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.

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

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

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

void bgav_options_set_track_change_callback ( bgav_options_t opt,
bgav_track_change_callback  callback,
void *  data 
)

Set the callback for track change events.

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

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

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.

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

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


Generated on Sun Aug 3 15:34:52 2008 for gmerlin-avdecoder by  doxygen 1.5.6