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 /^$/
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($dothis)) { ... }
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.
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 <beppu@ax9.org>
SEE ALSO
mpg123(1), Audio::Play::MPG123(3pm), pimp(1p), mpg123sh(1p), mp3(1p)