VLC 4.0.0-dev
Loading...
Searching...
No Matches
LibVLC core

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.
 
typedef int64_t libvlc_time_t
 
typedef struct libvlc_module_description_t libvlc_module_description_t
 Description of a module.
 

Functions

libvlc_instance_tlibvlc_new (int argc, const char *const *argv)
 Create and initialize a libvlc instance.
 
void libvlc_release (libvlc_instance_t *p_instance)
 Decrement the reference count of a libvlc instance, and destroy it if it reaches zero.
 
libvlc_instance_tlibvlc_retain (libvlc_instance_t *p_instance)
 Increments the reference count of a libvlc instance.
 
int libvlc_abi_version (void)
 Get the ABI version of the libvlc library.
 
void libvlc_set_user_agent (libvlc_instance_t *p_instance, const char *name, const char *http)
 Sets the application name.
 
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.
 
const char * libvlc_get_version (void)
 Retrieve libvlc version.
 
const char * libvlc_get_compiler (void)
 Retrieve libvlc compiler version.
 
const char * libvlc_get_changeset (void)
 Retrieve libvlc changeset.
 
void libvlc_free (void *ptr)
 Frees an heap allocation returned by a LibVLC function.
 
void libvlc_module_description_list_release (libvlc_module_description_t *p_list)
 Release a list of module descriptions.
 
libvlc_module_description_tlibvlc_audio_filter_list_get (libvlc_instance_t *p_instance)
 Returns a list of audio filters that are available.
 
libvlc_module_description_tlibvlc_video_filter_list_get (libvlc_instance_t *p_instance)
 Returns a list of video filters that are available.
 

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

This structure is opaque.

It represents a libvlc instance

◆ 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_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_instancelibvlc 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
ptrthe 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_listthe 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
argcthe number of arguments (should be 0)
argvlist 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_instancethe 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_instancethe 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.

See also libvlc_set_user_agent().

Parameters
p_instanceLibVLC instance
idJava-style application identifier, e.g. "com.acme.foobar"
versionapplication version numbers, e.g. "1.2.3"
iconapplication icon name, e.g. "foobar"
Version
LibVLC 2.1.0 or later.

◆ 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_instanceLibVLC instance
namehuman-readable application name, e.g. "FooBar player 1.2.3"
httpHTTP 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_instancelibvlc 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