use VideoLAN::LibVLC::MediaPlayer;
  my $player= VideoLAN::LibVLC::MediaPlayer->new("cat_video.mpg");
  $player->video_lock_cb(sub { ... });   # allocate a buffer for video decoding
  $player->video_unlock_cb(sub { ... }); # do something with the decoded video frame
  $player->play; # start VLC thread that decodes and generates callbacks
  my $fh= $player->libvlc->callback_fh;
  while (1) {
    if (IO::Select->new($fh)->can_read) {  # set up your main loop to watch the $fh
      $player->libvlc->callback_dispatch # fire perl callbacks


This module wraps LibVLC. LibVLC already has a very nice object-ish (but yet still function-based) API, so this package wraps each group of functions into a perl object in the logical manner. One difficulty, however, is that LibVLC uses its own threads when doing video playback, and most of the "interesting" possibilities for using LibVLC would require you to write your own callbacks, which must happen in the main Perl thread. To work around that (and also not force you to use this module as your main event loop) this module passes each VLC callback through a pipe. This allows you to select() on that file handle or use an event-driven system like AnyEvent for your program's main loop, and still gain the parallel processing benefit of VLC running its own thread.

If you're worried about the latency of VLC's playback thread needing a round- trip to your callbacks, you can create a double-buffering effect by returning two values from the first callback. The next VLC callback event will get the callback result without blocking. (but it still sends another callback event, so the perl callback still happens and you can stay one step ahead of the VLC thread)


This module can export constants used by LibVLC, however I renamed them a bit because libvlc uses a mix of uppercase/lowercase/camel-case that is distracting and confusing when used as perl const-subs, the LIBVLC_ prefix is annoying for perl scripts, and some constants only differ by case.

The renaming rules are:

  • Remove any "LIBVLC_" or "libvlc_" prefix

  • If the constant does not begin with the same word as the enum it belongs to, add the enum's name to the beginning of the constant

  • Uppercase everything

for example:

  libvlc_Error      =>   STATE_ERROR
  libvlc_meta_Album =>   META_ALBUM

Each of LibVLC's enums can be exported individually:

  use VideoLAN::LibVLC qw( :log_level_t :media_parse_flag_t :media_parsed_status_t
   :media_slave_type_t :media_type_t :position_t :state_t :track_type_t
   :video_orient_t :video_projection_t );

Or get all of them with :constants.

However, be aware that the constants change significantly across libvlc versions, but this module always exports all of them. Accessing a constant not supported by your version of libvlc will throw an exception. (I figured it would be better to allow the exceptions at runtime than for programs to break at compile time due to the host's version of libvlc.)



Version of LibVLC. This is a package attribute.


Precise revision-control version of LibVLC. This is a package attribute.


Compiler used to create LibVLC. This is a package attribute.


A copy of the argv that you passed to the constructor. Read-only.


A java-style name identifying the application. Defaults to an empty string if you set app_version or app_icon.


The version of your application. Defaults to empty string if you assign an app_id or app_icon.


The name of the icon for your application. Defaults to empty string if you assign an app_id or app_version.


A human-facing description of your application as a user agent for web requests.


A HTTP UserAgent string for your application.


An arrayref of all audio filter modules built into LibVLC.


List accessor for audio_filters.


An arrayref of all video filter modules built into LibVLC.


List accessor for video_filters.


Whether or not this version of libvlc supports redirecting the log.


  # get
  my $current= $vlc->log
  # set to logger object
  $vlc->log( $log );
  $vlc->log( $log, \%options );
  # set to logging callback
  $vlc->log( sub { my ($event)= @_; ... } );
  $vlc->log( sub { my ($event)= @_; ... }, \%options );
  # disable logging

Set the logger object or logging callback or logging file handle for this LibVLC instance. It can be either a logger object like Log::Any, or a callback.

The optional second argumnt \%options can request more or less information for the callback. Available options are:

  context - boolean of whether to collect the attributes "module", "file", and "line".
  object  - boolean of whether to collect the attributes "name", "header", "id".

Note that logging can happen from other threads, so you won't see the messages until you call "callback_dispatch".



  my $vlc= VideoLAN::VLC->new( \@ARGV );
  my $vlc= VideoLAN::VLC->new( %attributes );
  my $vlc= VideoLAN::VLC->new( \%attributes );

Create a new instance of LibVLC (which directly corresponds to an initialization of libvlc via libvlc_new)

Note that libvlc suggests against passing command line arguments except for debugging, since they can differ by version and by platform.

The returned object is based on a hashref, and the libvlc pointer is magically attached.


  my $media= $vlc->new_media( $path );
  my $media= $vlc->new_media( $uri );
  my $media= $vlc->new_media( $file_handle );
  my $media= $vlc->new_media( %attributes );
  my $media= $vlc->new_media( \%attributes );

This nice heavily-overloaded method helps you quickly open new media streams. VLC can open paths, URIs, or file handles, and if you only pass one argument to this method it attempts to decide which of those three you intended.

You an instead pass a hash or hashref, and then it just passes them along to the Media constructor.


  my $player= $vlc->new_media_player();


The file handle of the read-end of the callback pipe. Listen on this file handle to know when to call "callback_dispatch".


Read any pending callback messages from the pipe(s), and execute the callback.

The "wire format" used to stream the callbacks is deliberately hidden within this module, and might change drastically in future versions. The provided API is to either call "wait_callback" or perform your own wait on the file handle, and then call this method to unpack the arguments and deliver them to the callback.