How to Use VLC Media Player API in a C Program


Did you know that the VLC media player has a powerful API you can use in your C programs to add VLC-like capabilities to them. For instance, you could use the API to quickly play any media file, extract meta-data from it, or even extract individual video frames from it. In this tutorial, I’ll show you how to create a simple C program that can play an audio file. For the sake of completeness, I’ll also show you how to listen to the events generated by the player while it is playing the file.


To be able to use the API, you must install the libvlc-dev package on your Ubuntu computer. You can easily do so using apt-get.

sudo apt-get install libvlc-dev

Using the API

Before you use the VLC API in your C program, all you need to do is include vlc/vlc.h as one of your header files. In this tutorial, however, we’ll also be using stdlib.h and stdio.h.

#include <stdio.h>
#include <vlc/vlc.h>
#include <stdlib.h>

int main() {
    // More code here

Every program that uses the API must first initialize a VLC instance using the libvlc_new() function. The function might return a NULL if there’s an error creating the instance, so make sure you handle it appropriately.

libvlc_instance_t *my_instance;

my_instance = libvlc_new(0, NULL);

if(my_instance == NULL) {
        printf("There was an error initializing VLC\n");
} else {
        printf("VLC initialized successfully\n");

We will of course use a media file, say a song or a movie, while working with the API. To specify the media file you want to use, you must the libvlc_media_new_path() function, which expects an absolute path. Here’s how you do that:

libvlc_media_t *my_media_file;
my_media_file = libvlc_media_new_path(my_instance, "/tmp/song.flac");

As you can see in the above code, the file I am using is called song.flac, and it’s present in my /tmp directory.

To actually play the media file, you will also need a media player, which can be created using the libvlc_media_player_new_from_media() function. Once the player has been created, you can simply call the libvlc_media_player_play() function to start playing the file.

// Create player
libvlc_media_player_t *my_player;
my_player = libvlc_media_player_new_from_media(my_media_file);

// Start playing

The media will start playing immediately. However, it plays asynchronously. Therefore, unless you add a call to the sleep() function now, your program will exit before the file has completed playing.

sleep(15); /* Wait for 15 seconds */

Lastly, it’s a good idea to release the media player, the media file, and the VLC instance before your program ends. Here’s how you can do so:


Compiling and Running

While compiling a program that uses the VLC API, you must make sure you link it with the vlc library. For example, if your program is called my_program.c, here’s how you would compile and run it:

gcc my_program.c -l vlc -o my_program

At this point, you should be able to hear your file being played.

Listening to Player Events

You already know that the VLC library plays the media file asynchronously. While doing so, it also raises several events. If you wish to listen for those events, you must first create an event manager using the libvlc_media_player_event_manager() function.

Once you have the event manager, you can call the libvlc_event_attach() function to associate an event handler with any event. The following code shows you how to listen for libvlc_MediaPlayerPositionChanged events.

libvlc_event_manager_t *my_event_manager;
my_event_manager = libvlc_media_player_event_manager(my_player);

                    libvlc_MediaPlayerPositionChanged, my_callback, NULL);

In the above code, we’ve used my_callback as the name of our event handler. As you might have guessed, this is going to be nothing but another function. Inside the function, you will have access to a variable of type libvlc_event_t, using which you can learn more about the event. For example, here’s how you simply print the current position of the media player head:

void my_callback(const libvlc_event_t *event, void *param) {
    printf("Position is: %f\n", event->u.media_player_position_changed.new_position);

Go ahead and run the program again. This time, you should see several log messages showing the latest position of the player head.


You now know the basics of using the VLC API. I’m sure you’ll agree with me when I say that it is extremely intuitive and easy to use. There’s a lot more the API offers, and you can learn all about it by referring to the official documentation.

If you found this article useful, please share it with your friends and colleagues!