/ 
VideoLAN-LibVLC-0.02
River stage zero No dependents
/ VideoLAN::LibVLC

NAME

VideoLAN::LibVLC - Wrapper for libvlc.so

VERSION

version 0.02

SYNOPSIS

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
  }
}

DESCRIPTION

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)

CONSTANTS

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      =>   LOG_LEVEL_ERROR
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.)

ATTRIBUTES

libvlc_version

Version of LibVLC. This is a package attribute.

libvlc_changeset

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

libvlc_compiler

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

argv

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

app_id

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

app_version

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

app_icon

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

user_agent_name

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

user_agent_http

A HTTP UserAgent string for your application.

audio_filters

An arrayref of all audio filter modules built into LibVLC.

audio_filter_list

List accessor for audio_filters.

video_filters

An arrayref of all video filter modules built into LibVLC.

video_filter_list

List accessor for video_filters.

can_redirect_log

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

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
$vlc->log(undef);

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:

level   - one of LIBVLC_DEBUG LIBVLC_NOTICE LIBVLC_WARNING LIBVLC_ERROR
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".

METHODS

new

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.

new_media

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.

new_media_player

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

callback_fh

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

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.

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.