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 This instantiates a new MP3::Daemon. my $mp3d = MP3::Daemon->new("$ENV{HOME}/.mp3/mp3_socket"); 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 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("$ENV{HOME}/.mp3/mp3_socket"); 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 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. 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 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@binq.org> SEE ALSO mpg123(1), Audio::Play::MPG123(3pm), pimp(1p), mpg123sh(1p), mp3(1p)