[ViewVC] Contents of: cvs/Audio-Play-MPG123/README

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 frame 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".

        The accessor function "frame" returns a reference to an array
        containing the frames played, frames left, seconds played, and
        seconds left in this order. Seconds are returned as floating point
        numbers.

    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 <schmorp@schmorp.de>.

SEE ALSO
    perl(1).

Revision:	1.2
Committed:	Thu Mar 3 17:01:39 2005 UTC (19 years, 2 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+1 -1 lines
Log Message:	* empty log message *
#	Content
1	NAME
2	Audio::Play::MPG123 - a frontend to mpg123 version 0.59r and beyond.
3
4	SYNOPSIS
5	use Audio::Play::MPG123;
6
7	$player = new Audio::Play::MPG123;
8	$player->load("kult.mp3");
9	print $player->artist,"\n";
10	$player->poll(1) until $player->state == 0;
11
12	$player->load("http://x.y.z/kult.mp3");
13
14	# see also mpg123sh from the tarball
15
16	DESCRIPTION
17	This is a frontend to the mpg123 player. It works by starting an
18	external mpg123 process with the "-R" option and feeding commands to it.
19
20	While the standard mpg123 player can be used to play back mp3's using
21	this module you will encounter random deadlocks, due to bugs in its
22	communication code. Also, many features (like "statfreq") only work with
23	the included copy of mpg123, so better use that one before deciding that
24	this module is broken.
25
26	(In case you wonder, the mpg123 author is not interested in including
27	these fixes and enhancements into mpg123).
28
29	METHODS
30	Most methods can be either BLOCKING (they wait until they get an answer,
31	which usually takes half a mpeg frame of playing time), NONBLOCKING (the
32	functions return as soon as they send their message, which is usallly
33	instant) or CACHING (the method returns some cached data which only gets
34	refreshed by an asynchronous STAT event or an explicit call to "state").
35
36	new [parameter => value, ...]
37	This creates a new player object and also starts the mpg123 process.
38	New supports the following parameters:
39
40	mpg123args an arrayreg with additional arguments for the mpg123 process
41
42	load(<path or url>) [BLOCKING]
43	Immediately loads the specified file (or url, http:// and file:///
44	forms supported) and starts playing it. If you really want to play a
45	file with a name starting with "file://" or "http://" then consider
46	prefixing all your paths with "file:///". Returns a true status when
47	the song could be started, false otherwise.
48
49	stat [BLOCKING]
50	This can be used to poll the player for it's current state (playing
51	mode, frame position &c). As every other function that requires
52	communication with mpg123, it might take up to one frame delay until
53	the answer returns. Using "statfreq" and infrequent calls to "poll"
54	is often a better strategy.
55
56	pause [BLOCKING]
57	Pauses or unpauses the song. "state" (or "paused") can be used to
58	find out about the current mode.
59
60	paused [CACHING]
61	Returns the opposite of "state", i.e. zero when something is playing
62	and non-zero when the player is stopped or paused.
63
64	jump [BLOCKING]
65	Jumps to the specified frame of the song. If the number is prefixed
66	with "+" or "-", the jump is relative, otherweise it is absolute.
67
68	stop [BLOCKING]
69	Stops the currently playing song and unloads it.
70
71	statfreq(rate) [NONBLOCKING]
72	Sets the rate at which automatic frame updates are sent by mpg123. 0
73	turns it off, everything else is the average number of frames
74	between updates. This can be a floating pount value, i.e.
75
76	$player->statfreq(0.5/$player->tpf);
77
78	will set two updates per second (one every half a second).
79
80	state [CACHING]
81	Returns the current state of the player:
82
83	0 stopped, not playing anything
84	1 paused, song loaded but not playing
85	2 playing, song loaded and playing
86
87	poll(<wait>) [BLOCKING or NONBLOCKING]
88	Parses all outstanding events and status information. If "wait" is
89	zero it will only parse as many messages as are currently in the
90	queue, if it is one it will wait until at least one event occured.
91
92	This can be used to wait for the end of a song, for example. This
93	function should be called regularly, since mpg123 will stop playing
94	when it can't write out events because the perl program is no longer
95	listening...
96
97	title artist album year comment genre url type layer samplerate mode
98	mode_extension bpf frame channels copyrighted error_protected title
99	artist album year comment genre emphasis bitrate extension [CACHING]
100	These accessor functions return information about the loaded song.
101	Information about the "artist", "album", "year", "comment" or
102	"genre" might not be available and will be returned as "undef".
103
104	The accessor function "frame" returns a reference to an array
105	containing the frames played, frames left, seconds played, and
106	seconds left in this order. Seconds are returned as floating point
107	numbers.
108
109	tpf [CACHING]
110	Returns the "time per frame", i.e. the time in seconds for one
111	frame. Useful with the "jump"-method:
112
113	$player->jump (60/$player->tpf);
114
115	Jumps to second 60.
116
117	IN Returns the input filehandle from the mpg123 player. This can be
118	used for selects() or poll().
119
120	AUTHOR
121	Marc Lehmann <schmorp@schmorp.de>.
122
123	SEE ALSO
124	perl(1).
125