MP3::Daemon - a daemon that possesses mpg123

MP3::Daemon is meant to be subclassed -- not used directly.

    package MP3::Daemon::Simple;

    use strict;
    use vars qw(@ISA);
    use MP3::Daemon;

    @ISA = qw(MP3::Daemon);

Other perl scripts would use MP3::Daemon::Simple like this:

    my $socket_path = "/tmp/mp3d_socket";

    # start up a daemon
    MP3::Daemon::Simple->spawn($socket_path);

    # get a socket that's good for one request to the daemon
    my $client = MP3::Daemon::Simple->client($socket_path);

    print $client @command;

Audio::Play::MPG123

This is used to control mpg123 in remote-mode.

IO::Socket::UNIX

This is for client/server communication.

IO::Select

I like the OO interface. I didn't feel like using normal select() and messing with vec().

MP3::Info

This is for getting information from mp3 files.

Pod::Usage

This is an optional module that bin/mp3 uses to generate help messages.

POSIX

This is just for setsid.

MP3::Daemon provides a framework for daemonizing mpg123 and communicating with this daemonized process using unix domain sockets. It provides an event loop that listens for client requests and also polls the mpg123 player to monitor its state and change mp3s when one finishes.

The types of client requests available are not defined in MP3::Daemon. It is up to subclasses of MP3::Daemon to flesh out their own protocol for communicating with the daemon. This was done to allow people freedom in defining their own mp3 player semantics.

The following is a short description of the subclasses of MP3::Daemon that are packaged with the MP3::Daemon distribution.

This subclass of MP3::Daemon provides a very straightforward mp3 player. It comes with a client called mp3 that you'll find in the bin/ directory. It implements a very simple playlist. It also implements common commands one would expect from an player, and it feels very similar to cdcd(1). It is touted as an mpg123 front-end for UNIX::Philosophers, because it does not have a Captive User Interface.

For more information, `perldoc mp3`;

This subclass of MP3::Daemon has yet to be written. The significant difference between M:D:Simple and M:D:PIMP will be the Plaqueluster. A Plaqueluster is a pseudorandom playlist that enforces a user-definable level of non-repetitiveness. It is also capable of maintaining a median volume such that all mp3s are played at the same relative volume. Never again will you be startled by having an mp3 recorded at a low volume being followed by an mp3 recorded VERY LOUDLY.

For more information, `perldoc pimp`;

MP3::Daemon 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->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->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.

    my $client = MP3::Daemon->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") } );

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].

When writing a subclass of MP3::Daemon keep the following in mind.

Writing the constructor

The new() method provided by MP3::Daemon returns a blessed hashref. Feel free to add more attributes to the blessed hash as long as you don't accidentally stomp on the following keys.

player

This is an instance of Audio::Play::MPG123.

server

This is an instance of IO::Socket::UNIX.

client

This is another instance of IO::Socket::UNIX that the daemon may write to in order to reply to a client.

socket_path

This is where in the filesystem the unix domain socket is sitting.

You must implement a next() method.

The event loop in &MP3::Daemon::main relies on it. When a song ends, it will execute $self->next.

Only methods prefixed with "_" will be available to clients.

This was done to prevent mischievous clients from trying to execute methods like new(), spawn() or main(). That would be evil. By only allowing methods with names matching /^_/ to be executed, this allows the author of a daemon to control what the client can and can't request the daemon to do.

When a client makes a request, the following sequence happens in the event loop.

    my @args = $self->readCommand;
    my $do_this = "_" . shift(@args);
    if ($self->can($do_this)) { ... }

If a client requested the daemon to "play", the event loop will ask itself if ($self->can('_play')) before taking any action.

Letting us know

If you write a subclass of MP3::Daemon, we (pip and beppu) would be happy to hear from you. Write to us at beppu@binq.org or pip@binq.org.

I need to be able to report errors in the daemon better. They currently go to /dev/null. I need to learn how to use syslog.

Copyleft (!c) 2001 John BEPPU. All rights reversed. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

John BEPPU <beppu@ax9.org>

mpg123(1), Audio::Play::MPG123(3pm), pimp(1p), mpg123sh(1p), mp3(1p)