NAME
   MP3::Daemon - a daemon that possesses mpg123

SYNOPSIS
   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;

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

DESCRIPTION
   MP3::Daemon provides a framework for daemonizing mpg123 and
   communicating with it 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.

 MP3::Daemon::Simple => mp3

   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`;

 MP3::Daemon::PIMP => pimp

   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`;

METHODS
 Server-related Methods

   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") } );

 Client Protocol

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

SUBCLASSES
   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 [email protected] or
       [email protected].

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

AUTHOR
   John BEPPU <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.