bg_input_plugin_s Struct Reference
[Media input]

Input plugin. More...

#include <plugin.h>

Data Fields
bg_plugin_common_t	common
	Infos and functions common to all plugin types.
const char *(*	get_protocols )(void *priv)
	Get supported protocols.
const char *(*	get_mimetypes )(void *priv)
	Get supported mimetypes.
const char *(*	get_extensions )(void *priv)
	Get supported extensions.
void(*	set_callbacks )(void *priv, bg_input_callbacks_t *callbacks)
	Set callbacks.
int(*	open )(void *priv, const char *arg)
	Open file/url/device.
int(*	open_fd )(void *priv, int fd, int64_t total_bytes, const char *mimetype)
	Open plugin from filedescriptor (optional).
int(*	open_callbacks )(void *priv, int(*read_callback)(void *priv, uint8_t *data, int len), int64_t(*seek_callback)(void *priv, uint64_t pos, int whence), void *cb_priv, const char *filename, const char *mimetype, int64_t total_bytes)
	Open plugin with callbacks (optional).
const bg_edl_t *(*	get_edl )(void *priv)
	Get the edl (optional).
const char *(*	get_disc_name )(void *priv)
	Get the disc name (optional).
int(*	eject_disc )(const char *device)
	Eject disc (optional).
int(*	get_num_tracks )(void *priv)
	Get the number of tracks.
bg_track_info_t *(*	get_track_info )(void *priv, int track)
	Return information about a track.
int(*	set_track )(void *priv, int track)
	Set the track to be played.
int(*	set_audio_stream )(void *priv, int stream, bg_stream_action_t action)
	Setup audio stream.
int(*	set_video_stream )(void *priv, int stream, bg_stream_action_t action)
	Setup video stream.
int(*	set_subtitle_stream )(void *priv, int stream, bg_stream_action_t action)
	Setup subtitle stream.
int(*	start )(void *priv)
	Start decoding.
bg_read_audio_func_t	read_audio
	Read audio samples.
bg_read_video_func_t	read_video
	Read a video frame.
int(*	has_subtitle )(void *priv, int stream)
	Query if a new subtitle is available.
int(*	read_subtitle_overlay )(void *priv, gavl_overlay_t *ovl, int stream)
	Read one pixmap subtitle.
int(*	read_subtitle_text )(void *priv, char **text, int *text_alloc, int64_t *start_time, int64_t *duration, int stream)
	Read one text subtitle.
int(*	bypass )(void *priv)
	Update a plugin in bypass mode.
void(*	bypass_set_pause )(void *priv, int pause)
	pause a plugin in bypass mode
void(*	bypass_set_volume )(void *priv, float volume)
	Set volume for a plugin in bypass mode.
void(*	seek )(void *priv, int64_t *time, int scale)
	Seek within a media track.
void(*	stop )(void *priv)
	Stop playback.
void(*	close )(void *priv)
	Close plugin.

---

Detailed Description

Input plugin.

This is for all kinds of media inputs (files, disks, urls, etc), except recording from hardware devices (see Recorder).

---

Field Documentation

bg_plugin_common_t bg_input_plugin_s::common

Infos and functions common to all plugin types.

const char*(* bg_input_plugin_s::get_protocols)(void *priv)

Get supported protocols.

Parameters:

priv

The handle returned by the create() method

Returns:

A space separated list of protocols

const char*(* bg_input_plugin_s::get_mimetypes)(void *priv)

Get supported mimetypes.

Parameters:

priv

The handle returned by the create() method

Returns:

A space separated list of mimetypes

const char*(* bg_input_plugin_s::get_extensions)(void *priv)

Get supported extensions.

Parameters:

priv

The handle returned by the create() method

Returns:

A space separated list of extensions

void(* bg_input_plugin_s::set_callbacks)(void *priv, bg_input_callbacks_t *callbacks)

Set callbacks.

Parameters:

	priv	The handle returned by the create() method
	callbacks	Callback structure initialized by the caller before

Set callback functions, which will be called by the plugin. Defining as well as calling this function is optional. Any of the members of callbacks can be NULL.

int(* bg_input_plugin_s::open)(void *priv, const char *arg)

Open file/url/device.

Parameters:

	priv	The handle returned by the create() method
	arg	Filename, URL or device name

Returns:

1 on success, 0 on failure

int(* bg_input_plugin_s::open_fd)(void *priv, int fd, int64_t total_bytes, const char *mimetype)

Open plugin from filedescriptor (optional).

Parameters:

	priv	The handle returned by the create() method
	fd	Open filedescriptor
	total_bytes	Totally available bytes or 0 if unknown
	mimetype	Mimetype from http header (or NULL)

Returns:

1 on success, 0 on failure

int(* bg_input_plugin_s::open_callbacks)(void *priv, int(*read_callback)(void *priv, uint8_t *data, int len), int64_t(*seek_callback)(void *priv, uint64_t pos, int whence), void *cb_priv, const char *filename, const char *mimetype, int64_t total_bytes)

Open plugin with callbacks (optional).

Parameters:

	priv	The handle returned by the create() method
	read_callback	Callback for reading data
	seek_callback	Callback for seeking
	cb_priv	Private argument for the callbacks
	filename	The filename of the input or NULL if this info is not known.
	mimetype	The mimetype of the input or NULL if this info is not known.
	total_bytes	total number of bytes or 0 if this info is not known.

Returns:

1 on success, 0 on failure

const bg_edl_t*(* bg_input_plugin_s::get_edl)(void *priv)

Get the edl (optional).

Parameters:

priv

The handle returned by the create() method

Returns:

The edl if any

const char*(* bg_input_plugin_s::get_disc_name)(void *priv)

Get the disc name (optional).

Parameters:

priv

The handle returned by the create() method

Returns:

The name of the disc if any

This is only for plugins, which access removable discs (e.g. CDs).

int(* bg_input_plugin_s::eject_disc)(const char *device)

Eject disc (optional).

Parameters:

priv

The handle returned by the create() method

Returns:

1 if eject was successful

This is only for plugins, which access removable discs (e.g. CDs).

Todo:

This function doesn't work reliably now. Either fix or remove this

int(* bg_input_plugin_s::get_num_tracks)(void *priv)

Get the number of tracks.

Parameters:

priv

The handle returned by the create() method

Returns:

The number of tracks

This can be NULL for plugins, which support just one track.

bg_track_info_t*(* bg_input_plugin_s::get_track_info)(void *priv, int track)

Return information about a track.

Parameters:

	priv	The handle returned by the create() method
	track	Track index starting with 0

Returns:

The track info

The following fields MUST be valid after this call:

• num_audio_streams
• num_video_streams
• num_subtitle_streams
• duration
• Name (If NULL, the filename minus the suffix will be used)

Other data, especially audio and video formats, will become valid after the start() call (see below).

int(* bg_input_plugin_s::set_track)(void *priv, int track)

Set the track to be played.

Parameters:

	priv	The handle returned by the create() method
	track	Track index starting with 0

This has to be defined even if the plugin doesn't support multiple tracks. In addition to selecting the track, the plugin should also reset it's internal state such that streams can newly be selected.

int(* bg_input_plugin_s::set_audio_stream)(void *priv, int stream, bg_stream_action_t action)

Setup audio stream.

Parameters:

	priv	The handle returned by the create() method
	stream	Stream index starting with 0
	action	What to do with the stream

Returns:

1 on success, 0 on failure

int(* bg_input_plugin_s::set_video_stream)(void *priv, int stream, bg_stream_action_t action)

Setup video stream.

Parameters:

	priv	The handle returned by the create() method
	stream	Stream index starting with 0
	action	What to do with the stream

Returns:

1 on success, 0 on failure

int(* bg_input_plugin_s::set_subtitle_stream)(void *priv, int stream, bg_stream_action_t action)

Setup subtitle stream.

Parameters:

	priv	The handle returned by the create() method
	stream	Stream index starting with 0
	action	What to do with the stream

Returns:

1 on success, 0 on failure

int(* bg_input_plugin_s::start)(void *priv)

Start decoding.

Parameters:

priv

The handle returned by the create() method

Returns:

1 on success, 0 on error

After this call, all remaining members of the track info returned earlier (especially audio- and video formats) must be valid.

From the plugins point of view, this is the last chance to return 0 if something fails

bg_read_audio_func_t bg_input_plugin_s::read_audio

Read audio samples.

Parameters:

	priv	The handle returned by the create() method
	frame	The frame, where the samples will be copied
	stream	Stream index starting with 0
	num_samples	Number of samples

Returns:

The number of decoded samples, 0 means EOF.

The num_samples argument can be larger than the samples_per_frame member of the video format. This means, that all audio decoding plugins must have an internal buffering mechanism.

bg_read_video_func_t bg_input_plugin_s::read_video

Read a video frame.

Parameters:

	priv	The handle returned by the create() method
	frame	The frame, where the image will be copied
	stream	Stream index starting with 0

Returns:

1 if a frame was decoded, 0 means EOF.

int(* bg_input_plugin_s::has_subtitle)(void *priv, int stream)

Query if a new subtitle is available.

Parameters:

	priv	The handle returned by the create() method
	stream	Stream index starting with 0

Returns:

1 if a subtitle is available, 0 else.

int(* bg_input_plugin_s::read_subtitle_overlay)(void *priv, gavl_overlay_t *ovl, int stream)

Read one pixmap subtitle.

Parameters:

	priv	The handle returned by the create() method
	ovl	Where the overlay will be copied
	stream	Stream index starting with 0

Returns:

1 if a subtitle was decoded, 0 else

EOF in a graphical subtitle stream is reached if

• has_subtitle() returned 1 and
• read_subtitle_overlay() returned 0

int(* bg_input_plugin_s::read_subtitle_text)(void *priv, char **text, int *text_alloc, int64_t *start_time, int64_t *duration, int stream)

Read one text subtitle.

Parameters:

	priv	The handle returned by the create() method
	text	Where the text will be copied, the buffer will be realloc()ed.
	text_alloc	Allocated bytes for text. Will be updated by the function.
	start_time	Returns the start time of the subtitle
	duration	Returns the duration of the subtitle
	stream	Stream index starting with 0

Returns:

1 if a subtitle was decoded, 0 else

EOF in a text subtitle stream is reached if

• has_subtitle() returned 1 and
• read_subtitle_text() returned 0

This function automatically handles the text buffer (and text_alloc). Just set both to zero before the first call and free() the text buffer after the last call (if non-NULL).

int(* bg_input_plugin_s::bypass)(void *priv)

Update a plugin in bypass mode.

Parameters:

priv

The handle returned by the create() method

Returns:

1 on success, 0 on error

For plugins in bypass mode, this function must be called periodically by the application, so the plugin can call the callbacks if something interesting happened.

void(* bg_input_plugin_s::bypass_set_pause)(void *priv, int pause)

pause a plugin in bypass mode

Parameters:

	priv	The handle returned by the create() method
	pause	1 for pausing, 0 for resuming

void(* bg_input_plugin_s::bypass_set_volume)(void *priv, float volume)

Set volume for a plugin in bypass mode.

Parameters:

	priv	The handle returned by the create() method
	volume	Volume in dB (0 is maximum).

This function is optional.

void(* bg_input_plugin_s::seek)(void *priv, int64_t *time, int scale)

Seek within a media track.

Parameters:

	priv	The handle returned by the create() method
	time	Time to seek to
	scale	Scale in which time is given

Media streams are supposed to be seekable, if this function is non-NULL AND the duration field of the track info is > 0 AND the seekable flag in the track info is nonzero. The time argument might be changed to the correct value

void(* bg_input_plugin_s::stop)(void *priv)

Stop playback.

Parameters:

priv

The handle returned by the create() method

This is used for plugins in bypass mode to stop playback. The plugin can be started again after

void(* bg_input_plugin_s::close)(void *priv)

Close plugin.

Parameters:

priv

The handle returned by the create() method

Close the file/device/url.

---

The documentation for this struct was generated from the following file:

• /tmp/buildd/gmerlin-0.4.0/include/gmerlin/plugin.h