NAME

Audio::Play::MPG123 - a frontend to mpg123 version 0.59r and beyond.

SYNOPSIS

  use Audio::Play::MPG123;
  
  $player = new Audio::Play::MPG123;
  $player->load("kult.mp3");
  print $player->artist,"\n";
  $player->poll(1) until $player->state == 0;

  $player->load("http://x.y.z/kult.mp3");

  # see also mpg123sh from the tarball

DESCRIPTION

This is a frontend to the mpg123 player. It works by starting an external mpg123 process with the -R option and feeding commands to it.

While the standard mpg123 player can be used to play back mp3's using this module you will encounter random deadlocks, due to bugs in its communication code. Also, many features (like statfreq) only work with the included copy of mpg123, so better use that one before deciding that this module is broken.

(In case you wonder, the mpg123 author is not interested in including these fixes and enhancements into mpg123).

METHODS

Most methods can be either BLOCKING (they wait until they get an answer, which usually takes half a mpeg frame of playing time), NONBLOCKING (the functions return as soon as they send their message, which is usallly instant) or CACHING (the method returns some cached data which only gets refreshed by an asynchronous STAT event or an explicit call to state).

new [parameter => value, ...]

This creates a new player object and also starts the mpg123 process. New supports the following parameters:

   mpg123args      an arrayreg with additional arguments for the mpg123 process

load(<path or url>) [BLOCKING]

Immediately loads the specified file (or url, http:// and file:/// forms supported) and starts playing it. If you really want to play a file with a name starting with file:// or http:// then consider prefixing all your paths with file:///. Returns a true status when the song could be started, false otherwise.

stat [BLOCKING]

This can be used to poll the player for it's current state (playing mode, frame position &c). As every other function that requires communication with mpg123, it might take up to one frame delay until the answer returns. Using statfreq and infrequent calls to poll is often a better strategy.

pause [BLOCKING]

Pauses or unpauses the song. state (or paused) can be used to find out about the current mode.

paused [CACHING]

Returns the opposite of state, i.e. zero when something is playing and non-zero when the player is stopped or paused.

jump [BLOCKING]

Jumps to the specified frame of the song. If the number is prefixed with "+" or "-", the jump is relative, otherweise it is absolute.

stop [BLOCKING]

Stops the currently playing song and unloads it.

statfreq(rate) [NONBLOCKING]

Sets the rate at which automatic frame updates are sent by mpg123. 0 turns it off, everything else is the average number of frames between updates. This can be a floating pount value, i.e.

 $player->statfreq(0.5/$player->tpf);

will set two updates per second (one every half a second).

state [CACHING]

Returns the current state of the player:

 0  stopped, not playing anything
 1  paused, song loaded but not playing
 2  playing, song loaded and playing

poll(<wait>) [BLOCKING or NONBLOCKING]

Parses all outstanding events and status information. If wait is zero it will only parse as many messages as are currently in the queue, if it is one it will wait until at least one event occured.

This can be used to wait for the end of a song, for example. This function should be called regularly, since mpg123 will stop playing when it can't write out events because the perl program is no longer listening...

title artist album year comment genre url type layer samplerate mode mode_extension bpf channels copyrighted error_protected title artist album year comment genre emphasis bitrate extension [CACHING]

These accessor functions return information about the loaded song. Information about the artist, album, year, comment or genre might not be available and will be returned as undef.

tpf [CACHING]

Returns the "time per frame", i.e. the time in seconds for one frame. Useful with the jump-method:

 $player->jump (60/$player->tpf);

Jumps to second 60.

IN

Returns the input filehandle from the mpg123 player. This can be used for selects() or poll().

AUTHOR

Marc Lehmann <pcg@goof.com>.

SEE ALSO

perl(1).