NAME

MP3::Daemon::PIMP - the daemon for Pip's Intergallactive Moosex Plaqueluster

SYNOPSIS

Fork a daemon

    MP3::Daemon::PIMP->spawn($socket_path);

Start a server, but don't fork into background

    my $mp3d = MP3::Daemon::PIMP->new($socket_path);
    $mp3d->main;

You're a client wanting a socket to talk to the daemon

    my $client = MP3::Daemon::PIMP->client($socket_path);
    print $client @command;

REQUIRES

MP3::Daemon: This is the base class. It provides the daemonization and event loop.

DESCRIPTION

MP3::Daemon::PIMP provides a server that controls mpg123. Clients such as mp3(1p) may connect to it and request the server to manipulate its internal playlists.

METHODS

Server-related Methods

MP3::Daemon::PIMP relies on unix domain sockets to communicate. The socket requires a place in the file system which is referred to as $socket_path in the following descriptions.

new (socket_path => $socket_path, at_exit => $code_ref)

This instantiates a new MP3::Daemon. The parameter, socket_path is mandatory, but at_exit is optional.

    my $mp3d = MP3::Daemon::PIMP->new (
        socket_path => "$ENV{HOME}/.mp3/mp3_socket"
        at_exit     => sub { print "farewell\n" },
    );

main

This starts the event loop. This will be listening to the socket for client requests while polling mpg123 in times of idleness. This method will never return.

    $mp3d->main;

spawn (socket_path => $socket_path, at_exit => $code_ref)

This combines new() and main() while also forking itself into the background. The spawn method will return immediately to the parent process while the child process becomes an MP3::Daemon that is waiting for client requests.

    MP3::Daemon::PIMP->spawn (
        socket_path => "$ENV{HOME}/.mp3/mp3_socket"
        at_exit     => sub { print "farewell\n" },
    );

client $socket_path

This is a factory method for use by clients who want a socket to communicate with a previously instantiated MP3::Daemon::PIMP.

    my $client = MP3::Daemon::PIMP->client("$ENV{HOME}/.mp3/mp3_socket");

idle $code_ref

This method has 2 purposes. When called with a parameter that is a code reference, the purpose of this method is to specify a code reference to execute during times of idleness. When called with no parameters, the specified code reference will be invoked w/ an MP3::Daemon object passed to it as its only parameter. This method will be invoked at regular intervals while main() runs.

Example: Go to the next song when there are 8 or fewer seconds left in the current mp3.

    $mp3d->idle (
        sub {
            my $self   = shift;             # M:D:Simple
            my $player = $self->{player};   # A:P:MPG123
            my $f      = $player->{frame};  # hashref w/ time info

            $self->next() if ($f->[2] <= 8);
        }
    );

This is a flexible mechanism for adding additional behaviours during playback.

atExit $code_ref

This mimics the C function atexit(). It allows one to give an MP3::Daemon some CODEREFs to execute when the destructor is called. Like the C version, the CODEREFs will be called in the reverse order of their registration. Unlike the C version, $self will be given as a parameter to each CODEREF.

    $mp3d->atExit( sub { unlink("$ENV{HOME}/.mp3/mp3.pid") } );

Client API

These methods are usually not invoked directly. They are invoked when a client makes a request. The protocol is very simple. The first line is the name of the method. Each argument to the method is specified on successive lines. A final blank line signifies the end of the request.

    0   method name
    1   $arg[0]
    .   ...
    n-1 $arg[n-2]
    n   /^$/

Example:

    print $client <<REQUEST;
    play
    5

    REQUEST

This plays $self->{playlist}[5].

command
command

COPYLEFT

AUTHOR

pip <pip@binq.org>

CPAN RT