MP3::Daemon::Simple - the daemon for the mp3(1p) client

Fork a daemon

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

Start a server, but don't fork into background

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

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

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

File::Basename

This is used to give titles to songs when the mp3 leaves the title undefined.

Getopt::Std

Some methods need to pretend they're command line utilities.

MP3::Daemon

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

MP3::Info

This is for getting information out of mp3s.

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

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

    $socket_path = "$ENV{HOME}/.mp3/mp3_socket";

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::Simple->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::Simple->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::Simple.

    my $client = MP3::Daemon::Simple->client($socket_path);

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

add

This adds mp3s to the playlist. Multiple files may be specified.

del

This deletes items from the playlist by index. More than one index may be specified. If no index is specified, the current mp3 in the playlist is removed. Indices may also be negative in which case they count from the end of the playlist.

play

This plays the current mp3 if no other parameters are given. This command also takes an optional parameter where the index of an mp3 in the playlist may be given.

next

This loads the next mp3 in the playlist.

prev

This loads the previous mp3 in the playlist.

pause

This pauses the currently playing mp3. If the mp3 was already paused, this will unpause it. Note that using the play command on a paused mp3 makes it start over from the beginning.

rw

This rewinds an mp3 by the specified amount of seconds.

ff

This fastforwards an mp3 by the specified amount of seconds.

jump

This will go directly to a part of an mp3 specified by seconds from the beginning of the track. If the number of seconds is prefixed with either a "-" or a "+", a relative jump will be made. This is another way to rewind or fastforward.

stop

This stops the player.

time

This sends back the index of the current track, the amount of time that has elapsed, the amount of time that is left, and the total amount of time. All times are reported in seconds.

info

This sends back information about the current track.

ls [-fl] [REGEX]

First, a warning -- I'm beginning to realize how GNU/ls became so bloated. The ls interface should not be considered stable. I'm still playing with it.

This sends back a list of the titles of all mp3s currently in the playlist. The current track is denoted by a line matching the regexp /^>/.

-f

This makes ls return a listing with index and filename.

-l

This makes ls return a long listing that includes index, title, and filename.

[REGEX]

This allows one to filter the playlist for only titles matching this regex. Of course, one may use grep, instead.

rand

Calling this with no parameters toggles the random play feature. Randomness can be set to be specifically "on" or "off" by passing the scalar "on" or "off" to this method.

loop

This option controls the playlist's looping behaviour. When called with a parameter, loop can be set to "all", "single", or "off". Calling this with no parameters displays the current looping status.

quit

This unloads the MP3::Daemon::Simple that was automagically spawned when you first invoked mp3.

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)