[ViewVC] Annotation 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 *
#	User	Rev	Content
1	root	1.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	root	1.2	Marc Lehmann <schmorp@schmorp.de>.
122	root	1.1
123			SEE ALSO
124			perl(1).
125