LibVLC core

Modules
	LibVLC error handling
	LibVLC asynchronous events
	LibVLC logging

Classes
struct	libvlc_module_description_t

Typedefs
typedef struct libvlc_module_description_t	libvlc_module_description_t

Functions
LIBVLC_API libvlc_instance_t *	libvlc_new (int argc, const char *const *argv)
LIBVLC_API void	libvlc_release (libvlc_instance_t *p_instance)
LIBVLC_API void	libvlc_retain (libvlc_instance_t *p_instance)
LIBVLC_API int	libvlc_add_intf (libvlc_instance_t *p_instance, const char *name)
LIBVLC_API void	libvlc_set_exit_handler (libvlc_instance_t *p_instance, void(*cb)(void *), void *opaque)
LIBVLC_DEPRECATED LIBVLC_API void	libvlc_wait (libvlc_instance_t *p_instance)
LIBVLC_API void	libvlc_set_user_agent (libvlc_instance_t *p_instance, const char *name, const char *http)
LIBVLC_API void	libvlc_set_app_id (libvlc_instance_t *p_instance, const char *id, const char *version, const char *icon)
LIBVLC_API const char *	libvlc_get_version (void)
LIBVLC_API const char *	libvlc_get_compiler (void)
LIBVLC_API const char *	libvlc_get_changeset (void)
LIBVLC_API void	libvlc_free (void *ptr)
LIBVLC_API void	libvlc_module_description_list_release (libvlc_module_description_t *p_list)
LIBVLC_API libvlc_module_description_t *	libvlc_audio_filter_list_get (libvlc_instance_t *p_instance)
LIBVLC_API libvlc_module_description_t *	libvlc_video_filter_list_get (libvlc_instance_t *p_instance)
typedef struct libvlc_instance_t	libvlc_instance_t
typedef int64_t	libvlc_time_t

Detailed Description

Before it can do anything useful, LibVLC must be initialized. You can create one (or more) instance(s) of LibVLC in a given process, with libvlc_new() and destroy them with libvlc_release().

Version

Unless otherwise stated, these functions are available from LibVLC versions numbered 1.1.0 or more. Earlier versions (0.9.x and 1.0.x) are not compatible.

Typedef Documentation

typedef struct libvlc_instance_t libvlc_instance_t

This structure is opaque. It represents a libvlc instance

typedef struct libvlc_module_description_t libvlc_module_description_t

Description of a module.

Function Documentation

LIBVLC_API int libvlc_add_intf	(	libvlc_instance_t *	p_instance,
		const char *	name
	)

Try to start a user interface for the libvlc instance.

Parameters

p_instance	the instance
name	interface name, or NULL for default

Returns

0 on success, -1 on error.

LIBVLC_API libvlc_module_description_t* libvlc_audio_filter_list_get

(

libvlc_instance_t *

p_instance

)

Returns a list of audio filters that are available.

Parameters

p_instance

libvlc instance

Returns

a list of module descriptions. It should be freed with libvlc_module_description_list_release(). In case of an error, NULL is returned.

See also

libvlc_module_description_t

libvlc_module_description_list_release

LIBVLC_API void libvlc_free

(

void *

ptr

)

Frees an heap allocation returned by a LibVLC function. If you know you're using the same underlying C run-time as the LibVLC implementation, then you can call ANSI C free() directly instead.

Parameters

ptr	the pointer

LIBVLC_API const char* libvlc_get_changeset

(

void

)

Retrieve libvlc changeset.

Example: "aa9bce0bc4"

Returns

a string containing the libvlc changeset

LIBVLC_API const char* libvlc_get_compiler

(

void

)

Retrieve libvlc compiler version.

Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"

Returns

a string containing the libvlc compiler version

LIBVLC_API const char* libvlc_get_version

(

void

)

Retrieve libvlc version.

Example: "1.1.0-git The Luggage"

Returns

a string containing the libvlc version

LIBVLC_API void libvlc_module_description_list_release

(

libvlc_module_description_t *

p_list

)

Release a list of module descriptions.

Parameters

p_list

the list to be released

LIBVLC_API libvlc_instance_t* libvlc_new	(	int	argc,
		const char *const *	argv
	)

Create and initialize a libvlc instance. This functions accept a list of "command line" arguments similar to the main(). These arguments affect the LibVLC instance default configuration.

Version

Arguments are meant to be passed from the command line to LibVLC, just like VLC media player does. The list of valid arguments depends on the LibVLC version, the operating system and platform, and set of available LibVLC plugins. Invalid or unsupported arguments will cause the function to fail (i.e. return NULL). Also, some arguments may alter the behaviour or otherwise interfere with other LibVLC functions.

Warning

There is absolutely no warranty or promise of forward, backward and cross-platform compatibility with regards to libvlc_new() arguments. We recommend that you do not use them, other than when debugging.

Parameters

argc	the number of arguments (should be 0)
argv	list of arguments (should be NULL)

Returns

the libvlc instance or NULL in case of error

LIBVLC_API void libvlc_release

(

libvlc_instance_t *

p_instance

)

Decrement the reference count of a libvlc instance, and destroy it if it reaches zero.

Parameters

p_instance

the instance to destroy

LIBVLC_API void libvlc_retain

(

libvlc_instance_t *

p_instance

)

Increments the reference count of a libvlc instance. The initial reference count is 1 after libvlc_new() returns.

Parameters

p_instance

the instance to reference

LIBVLC_API void libvlc_set_app_id	(	libvlc_instance_t *	p_instance,
		const char *	id,
		const char *	version,
		const char *	icon
	)

Sets some meta-informations about the application. See also libvlc_set_user_agent().

Parameters

p_instance	LibVLC instance
id	Java-style application identifier, e.g. "com.acme.foobar"
version	application version numbers, e.g. "1.2.3"
icon	application icon name, e.g. "foobar"

Version

LibVLC 2.1.0 or later.

LIBVLC_API void libvlc_set_exit_handler	(	libvlc_instance_t *	p_instance,
		void(*)(void *)	cb,
		void *	opaque
	)

Registers a callback for the LibVLC exit event. This is mostly useful if the VLC playlist and/or at least one interface are started with libvlc_playlist_play() or libvlc_add_intf() respectively. Typically, this function will wake up your application main loop (from another thread).

Note

This function should be called before the playlist or interface are started. Otherwise, there is a small race condition: the exit event could be raised before the handler is registered.

Parameters

p_instance	LibVLC instance
cb	callback to invoke when LibVLC wants to exit, or NULL to disable the exit handler (as by default)
opaque	data pointer for the callback

Warning

This function and libvlc_wait() cannot be used at the same time.

LIBVLC_API void libvlc_set_user_agent	(	libvlc_instance_t *	p_instance,
		const char *	name,
		const char *	http
	)

Sets the application name. LibVLC passes this as the user agent string when a protocol requires it.

Parameters

p_instance	LibVLC instance
name	human-readable application name, e.g. "FooBar player 1.2.3"
http	HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"

Version

LibVLC 1.1.1 or later

LIBVLC_API libvlc_module_description_t* libvlc_video_filter_list_get

(

libvlc_instance_t *

p_instance

)

Returns a list of video filters that are available.

Parameters

p_instance

libvlc instance

Returns

a list of module descriptions. It should be freed with libvlc_module_description_list_release(). In case of an error, NULL is returned.

See also

libvlc_module_description_t

libvlc_module_description_list_release

LIBVLC_DEPRECATED LIBVLC_API void libvlc_wait

(

libvlc_instance_t *

p_instance

)

Waits until an interface causes the instance to exit. You should start at least one interface first, using libvlc_add_intf().

Parameters

p_instance

the instance

Warning

This function wastes one thread doing basically nothing. libvlc_set_exit_handler() should be used instead.