Before it can do anything useful, LibVLC must be initialized. More...

Collaboration diagram for LibVLC core:

Modules
	LibVLC error handling

	LibVLC asynchronous events
	LibVLC emits asynchronous events.

	LibVLC logging
	libvlc_log_* functions provide access to the LibVLC messages log.

Data Structures
struct	libvlc_module_description_t
	Description of a module. More...

Typedefs
typedef struct libvlc_instance_t	libvlc_instance_t
	This structure is opaque. More...

typedef int64_t	libvlc_time_t

typedef struct libvlc_module_description_t	libvlc_module_description_t
	Description of a module. More...

Functions
libvlc_instance_t *	libvlc_new (int argc, const char const argv)
	Create and initialize a libvlc instance. More...

void	libvlc_release (libvlc_instance_t *p_instance)
	Decrement the reference count of a libvlc instance, and destroy it if it reaches zero. More...

libvlc_instance_t *	libvlc_retain (libvlc_instance_t *p_instance)
	Increments the reference count of a libvlc instance. More...

int	libvlc_abi_version (void)
	Get the ABI version of the libvlc library. More...

int	libvlc_add_intf (libvlc_instance_t p_instance, const char name)
	Try to start a user interface for the libvlc instance. More...

void	libvlc_set_exit_handler (libvlc_instance_t p_instance, void(cb)(void ), void opaque)
	Registers a callback for the LibVLC exit event. More...

void	libvlc_set_user_agent (libvlc_instance_t p_instance, const char name, const char *http)
	Sets the application name. More...

void	libvlc_set_app_id (libvlc_instance_t p_instance, const char id, const char version, const char icon)
	Sets some meta-information about the application. More...

const char *	libvlc_get_version (void)
	Retrieve libvlc version. More...

const char *	libvlc_get_compiler (void)
	Retrieve libvlc compiler version. More...

const char *	libvlc_get_changeset (void)
	Retrieve libvlc changeset. More...

void	libvlc_free (void *ptr)
	Frees an heap allocation returned by a LibVLC function. More...

void	libvlc_module_description_list_release (libvlc_module_description_t *p_list)
	Release a list of module descriptions. More...

libvlc_module_description_t *	libvlc_audio_filter_list_get (libvlc_instance_t *p_instance)
	Returns a list of audio filters that are available. More...

libvlc_module_description_t *	libvlc_video_filter_list_get (libvlc_instance_t *p_instance)
	Returns a list of video filters that are available. More...

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

◆ libvlc_instance_t

typedef struct libvlc_instance_t libvlc_instance_t

This structure is opaque.

It represents a libvlc instance

◆ libvlc_module_description_t

typedef struct libvlc_module_description_t libvlc_module_description_t

Description of a module.

◆ libvlc_time_t

typedef int64_t libvlc_time_t

Function Documentation

◆ libvlc_abi_version()

int libvlc_abi_version ( void )

Get the ABI version of the libvlc library.

This is different than the VLC version, which is the version of the whole VLC package. The value is the same as LIBVLC_ABI_VERSION_INT used when compiling.

Returns: a value with the following mask in hexadecimal 0xFF000000: major VLC version, similar to VLC major version, 0x00FF0000: major ABI version, incremented incompatible changes are added, 0x0000FF00: minor ABI version, incremented when new functions are added 0x000000FF: micro ABI version, incremented with new release/builds

Note: This the same value as the .so version but cross platform.

◆ libvlc_add_intf()

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_audio_filter_list_get()

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_free()

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_get_changeset()

const char * libvlc_get_changeset ( void )

Retrieve libvlc changeset.

Example: "aa9bce0bc4"

Returns: a string containing the libvlc changeset

◆ libvlc_get_compiler()

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_get_version()

const char * libvlc_get_version ( void )

Retrieve libvlc version.

Example: "1.1.0-git The Luggage"

Returns: a string containing the libvlc version

◆ libvlc_module_description_list_release()

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_new()

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.

Note

LibVLC may create threads. Therefore, any thread-unsafe process initialization must be performed before calling libvlc_new(). In particular and where applicable:

setlocale() and textdomain(),
setenv(), unsetenv() and putenv(),
with the X11 display system, XInitThreads() (see also libvlc_media_player_set_xwindow()) and
on Microsoft Windows, SetErrorMode().
sigprocmask() shall never be invoked; pthread_sigmask() can be used.

On POSIX systems, the SIGCHLD signal must not be ignored, i.e. the signal handler must set to SIG_DFL or a function pointer, not SIG_IGN. Also while LibVLC is active, the wait() function shall not be called, and any call to waitpid() shall use a strictly positive value for the first parameter (i.e. the PID). Failure to follow those rules may lead to a deadlock or a busy loop. Also on POSIX systems, it is recommended that the SIGPIPE signal be blocked, even if it is not, in principles, necessary, e.g.:

sigset_t set;
 
signal(SIGCHLD, SIG_DFL);
sigemptyset(&set);
sigaddset(&set, SIGPIPE);
pthread_sigmask(SIG_BLOCK, &set, NULL);

On Microsoft Windows, setting the default DLL directories to SYSTEM32 exclusively is strongly recommended for security reasons:

SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_SYSTEM32);

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_release()

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_retain()

libvlc_instance_t * 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

Returns: the same object

◆ libvlc_set_app_id()

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

Sets some meta-information about the application.

◆ libvlc_set_exit_handler()

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

◆ libvlc_set_user_agent()

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_video_filter_list_get()

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

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"

Modules

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ libvlc_instance_t

◆ libvlc_module_description_t

◆ libvlc_time_t

Function Documentation

◆ libvlc_abi_version()

◆ libvlc_add_intf()

◆ libvlc_audio_filter_list_get()

◆ libvlc_free()

◆ libvlc_get_changeset()

◆ libvlc_get_compiler()

◆ libvlc_get_version()

◆ libvlc_module_description_list_release()

◆ libvlc_new()

◆ libvlc_release()

◆ libvlc_retain()

◆ libvlc_set_app_id()

◆ libvlc_set_exit_handler()

◆ libvlc_set_user_agent()

◆ libvlc_video_filter_list_get()