.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Audio::Moosic 3pm"
.TH Audio::Moosic 3pm "2022-12-12" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Audio::Moosic \- Moosic client library for Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Audio::Moosic;
\&
\&  $moo = Audio::Moosic::Unix\->new();
\&
\&  $moosic\->append(\*(Aq/home/me/somewhat.ogg\*(Aq);
\&  $moosic\->play;
\&  print $moosic\->current, "\en";
\&  $moosic\->pause;
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Audio::Moosic acts as a client for the musical jukebox program Moosic
(http://nanoo.org/~daniel/moosic/) by Daniel Pearson <daniel@nanoo.org>.
.PP
Using Audio::Moosic you can connect to a moosic server either via an \s-1UNIX\s0 socket
or an \s-1INET\s0 socket.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 3
\&  $moo = Audio::Moosic::Unix\->new();
\&  $moo = Audio::Moosic::Unix\->new(\*(Aq/tmp/moosic/socket\*(Aq);
\&  $moo = Audio::Moosic::Inet\->new(\*(Aqlocalhost\*(Aq, 8765);
.Ve
.PP
Constructor. Initializes the class and invokes the connect method. If you're
creating a Audio::Moosic::Unix object you can give the location of your moosic
socket as parameter. If not ~/.moosic/socket is used. If you're creating a
Audio::Moosic::Inet instance you need to pass host and port as arguments.
.PP
You can't create an instance of Audio::Moosic itself. Use Unix or Inet subclass.
.PP
If the object was able to connect to the moosic server a reference to the object
instance is returned. If the connection failed $@ is set and undef returned.
.SS "connect"
.IX Subsection "connect"
.Vb 1
\&  $moo\->connect(\*(Aqfoobar.com\*(Aq, 9876);
.Ve
.PP
Connect to the moosic server. You normally don't need to run this method in your
moosic client.
.SS "disconnect"
.IX Subsection "disconnect"
.Vb 1
\&  $moo\->disconnect;
.Ve
.PP
Disconnect from the moosic daemon. No more calls will be sent to the server
after calling this method. You'll need to \fBreconnect()\fR first.
.SS "reconnect"
.IX Subsection "reconnect"
.Vb 1
\&  $moo\->reconnect;
.Ve
.PP
Disconnects from the server if you're connected and tries to reconnect.
.SS "connected"
.IX Subsection "connected"
.Vb 1
\&  $moo\->reconnect unless $moo\->connected;
.Ve
.PP
Check whether you're connected to the moosic server or not.
.SS "client_config"
.IX Subsection "client_config"
.Vb 2
\&  print $moo\->client_config(\*(Aqlocation\*(Aq);
\&  $conf = $moo\->client_config();
.Ve
.PP
Reads the moosic clients config. If a \f(CW$key\fR argument is given it returns only the
value associated with that key, if not the whole config hash.
.PP
Would it be a good idea to make the user able to edit the client_config here?
Suggestions or maybe patches are welcome.
.SS "ping"
.IX Subsection "ping"
.Vb 1
\&  die unless $moo\->ping;
.Ve
.PP
Checks if we're still connected. This method checks the connection explicitly by
calling the no_op server method. \fBconnected()\fR only checks the value of the
\&'connected' object property.
.SS "error"
.IX Subsection "error"
.Vb 2
\&  my $error = $moo\->error;
\&  $moo\->error(\*(AqWhaaa!\*(Aq);
.Ve
.PP
If an argument is given it adds the error string to the internal error array. If
called in scalar context it returns the last error occurred. If you call \fBerror()\fR
in list context the whole error array of the Audio::Moosic instance is returned.
.SS "call"
.IX Subsection "call"
.Vb 2
\&  $moo\->call(\*(Aqfoo\*(Aq);
\&  $moo\->call(\*(Aqbar\*(Aq, RPC::XML::int\->new(3));
.Ve
.PP
This method calls a xml-rpc method on the moosic server. The first argument
should be the method name. The arguments of that method should follow behind.
.PP
If the request to the moosic server could not be sent the Audio::Moosic instance
disconnects from the server and puts the error message into the internal error
array. Access it via \fBerror()\fR. The object won't send any calls anymore if such an
error occurred. You should try to reconnect.
.PP
If the request could be sent, but returned an error the error message is added
to the error array accessible via \fBerror()\fR.
.PP
If any error occurred \fBcall()\fR returns undef. If everything went fine the value of
the response is returned.
.PP
Normally you don't need to call this method. It is only used by other moosic
methods to send their calls more easily. If a new moosic method is not supported
by this library yet you'll maybe need to use \fBcall()\fR manually. Please notice me
if that happens so I'll add the new method.
.SS "api_version"
.IX Subsection "api_version"
.Vb 2
\&  @api = $moo\->api_version;
\&  $api = $moo\->api_version;
.Ve
.PP
Return the moosic servers \s-1API\s0 version. If called in scalar context a version
string like '1.3' is returned. In list context the mayor and minor numbers of
the \s-1API\s0 version are returned.
.SS "append"
.IX Subsection "append"
.Vb 2
\&  $moo\->append(\*(Aq/home/florian/whatever.ogg\*(Aq);
\&  $moo\->append(\*(Aq/home/florian/foo.ogg\*(Aq, \*(Aq/home/florian/bar.mp3\*(Aq);
.Ve
.PP
Add songs to the moosic queue. The files to add should be the arguments for the
append method. \fBappend()\fR returns 1 if there were no errors or something false if
there were some.
.SS "clear"
.IX Subsection "clear"
.Vb 1
\&  $moo\->clear;
.Ve
.PP
Clears the moosic queue. Only the current song remains playing.
.SS "crop"
.IX Subsection "crop"
.Vb 2
\&  $moo\->crop(4);
\&  $moo\->crop(3, 4);
.Ve
.PP
Remove all playlist items that don't fall within a given range. If the range is
represented by one integer all items whose index is greater than or equal to the
value will be removed. Two integers represent all items whose index is greater
than or equal to the value of first integer and less than the value of the
second integer.
.SS "crop_list"
.IX Subsection "crop_list"
.Vb 1
\&  $moo\->crop_list(1, 4, 3);
.Ve
.PP
Remove all queued items except those referenced by a list of positions.
.SS "current"
.IX Subsection "current"
.Vb 1
\&  print $moo\->current;
.Ve
.PP
Return the name of the current playing song.
.SS "current_time"
.IX Subsection "current_time"
.Vb 1
\&  print $moo\->current_time;
.Ve
.PP
Return the amount of time the current song has been playing.
.SS "cut"
.IX Subsection "cut"
.Vb 2
\&  $moo\->cut(3);
\&  $moo\->cut(4, 10);
.Ve
.PP
Remove all queued items that fall within a given range. See \fBcrop()\fR for details
on how that range should look like.
.SS "cut_list"
.IX Subsection "cut_list"
.Vb 1
\&  $moo\->cut_list(3, 7, 9);
.Ve
.PP
Remove all queued items referenced by list of positions.
.SS "die"
.IX Subsection "die"
.Vb 1
\&  $moo\->die;
.Ve
.PP
Tell the server to terminate itself.
.SS "filter"
.IX Subsection "filter"
.Vb 3
\&  $moo\->filter(\*(Aqfoo\*(Aq);
\&  $moo\->filter(\*(Aqbar\*(Aq, 4);
\&  $moo\->filter(\*(Aqmoo\*(Aq, 7, 11);
.Ve
.PP
Remove all items that don't match the given regular expression. You may limit
this operation to a specific range which is described in \fBcrop()\fR.
.SS "get_history_limit"
.IX Subsection "get_history_limit"
.Vb 1
\&  $limit = $moo\->get_history_limit;
.Ve
.PP
Get the limit on the size of the history list stored in servers memory.
.SS "getconfig"
.IX Subsection "getconfig"
.Vb 1
\&  @config = $moo\->getconfig;
.Ve
.PP
Return a list of the server's filetype-player associations.
.SS "halt_queue"
.IX Subsection "halt_queue"
.Vb 1
\&  $moo\->halt_queue;
.Ve
.PP
Stop any new songs from being played. Use \fBrun_queue()\fR to reverse this state.
.SS "haltqueue"
.IX Subsection "haltqueue"
See \fBhalt_queue()\fR.
.SS "history"
.IX Subsection "history"
.Vb 1
\&  %hist = $moo\->history;
.Ve
.PP
Return a list of items that has been recently played. If a positive integer
argument is given than no more than number of items will be returned. Otherwise
the entire history is printed.
.PP
\&\fBhistory()\fR returns an array of hashrefs like that:
  \f(CW@history\fR = (
    { title => 'foo', start => 123.45, stop => 543.21 },
    { title => 'bar', start => 234.56, stop => 654.32 },
    ...
  );
.SS "indexed_list"
.IX Subsection "indexed_list"
.Vb 3
\&  %list = $moo\->indexed_list;
\&  %list = $moo\->indexed_list(1);
\&  %list = $moo\->indexed_list(2, 5);
.Ve
.PP
List the song queue's contents. If a range is specified, only the items that
fall within that range are listed.
.PP
\&\fBindexed_list()\fR returns a hash like that:
  \f(CW%list\fR = (
    list => [ 'foo', 'bar', 'moo', ... ],
    start => 4
  );
.SS "insert"
.IX Subsection "insert"
.Vb 1
\&  $moo\->insert(4, \*(Aqfoo.ogg\*(Aq, \*(Aqbar.mp3\*(Aq);
.Ve
.PP
Insert items at a given position in the queue.
.SS "is_looping"
.IX Subsection "is_looping"
.Vb 1
\&  $moo\->toggle_loop_mode if $moo\->is_looping;
.Ve
.PP
Check whether the loop mode is on or not.
.SS "is_paused"
.IX Subsection "is_paused"
.Vb 1
\&  $moo\->toggle_pause if $moo\->is_paused;
.Ve
.PP
Check whether the current song is paused or not.
.SS "is_queue_running"
.IX Subsection "is_queue_running"
.Vb 3
\&  if($moo\->is_queue_running) {
\&    ...;
\&  }
.Ve
.PP
Check whether the queue consumption (advancement) is activated.
.SS "last_queue_update"
.IX Subsection "last_queue_update"
.Vb 1
\&  $time = $moo\->last_queue_update
.Ve
.PP
Return the time at which the song queue was last modified.
.SS "length"
.IX Subsection "length"
.Vb 1
\&  $length = $moo\->length
.Ve
.PP
Return the number of items in the song queue.
.SS "list"
.IX Subsection "list"
.Vb 4
\&  @list = $moo\->list();
\&  @list = $moo\->list(2);
\&  @list = $moo\->list(4, 8);
\&  $list_ref = $moo\->list()
.Ve
.PP
List the song queue's contents. If a range is specified, only the items that
fall within that range are listed. Returns an array if called in list context
or an array reference if it's called in scalar context.
.SS "move"
.IX Subsection "move"
.Vb 2
\&  $moo\->move(10, 4);
\&  $moo\->move(4, 7, 1);
.Ve
.PP
Move a range of items to a new position within the queue.
.SS "move_list"
.IX Subsection "move_list"
.Vb 1
\&  $moo\->move(3, 5, 7, 11);
.Ve
.PP
Move the items referenced by a list of positions to a new position.
.SS "next"
.IX Subsection "next"
.Vb 2
\&  $moo\->next;
\&  $moo\->next(5);
.Ve
.PP
Stop the current song (if any), and jumps ahead to a song that is currently in
the queue. The skipped songs are recorded in the history as if they had been
played. When called without arguments, this behaves very much like the \fBskip()\fR
method, except that it will have an effect even if nothing is currently playing.
.SS "no_op"
.IX Subsection "no_op"
.Vb 1
\&  $moo\->no_op
.Ve
.PP
Do nothing, successfully.
.SS "pause"
.IX Subsection "pause"
.Vb 1
\&  $moo\->pause;
.Ve
.PP
Pause the currently playing song.
.SS "prepend"
.IX Subsection "prepend"
.Vb 1
\&  $moo\->prepend(\*(Aqfoo.ogg\*(Aq, \*(Aqbar.mp3\*(Aq);
.Ve
.PP
Add items to the beginning of the queue.
.SS "previous"
.IX Subsection "previous"
.Vb 2
\&  $moo\->previous;
\&  $moo\->previous(3);
.Ve
.PP
Stops the current song (if any), removes the most recently played song from the
history, and puts these songs at the head of the queue. When loop mode is on,
the songs at the tail of the song queue are used instead of the most recently
played songs in the history.
.SS "putback"
.IX Subsection "putback"
.Vb 1
\&  $moo\->putback;
.Ve
.PP
Place the currently playing song at the beginning of the queue.
.SS "queue_length"
.IX Subsection "queue_length"
.Vb 1
\&  $length = $moo\->queue_length;
.Ve
.PP
Return the number of items in the song queue.
.SS "reconfigure"
.IX Subsection "reconfigure"
.Vb 1
\&  $moo\->reconfigure;
.Ve
.PP
Tell the server to reread its player configuration file.
.SS "remove"
.IX Subsection "remove"
.Vb 3
\&  $moo\->remove(\*(Aqregex\*(Aq);
\&  $moo\->remove(\*(Aqregex\*(Aq, 4);
\&  $moo\->remove(\*(Aqregex\*(Aq, 1, 3);
.Ve
.PP
Remove all items that match the given regular expression. You can limit this
operation by giving a range as described in \fBcrop()\fR as last argument.
.SS "replace"
.IX Subsection "replace"
.Vb 1
\&  $moo\->replace(\*(Aqfoo.ogg\*(Aq, \*(Aqbar.mp3\*(Aq);
.Ve
.PP
Replace the contents of the queue with the given items. This is equivalent to
calling \fBclear()\fR and \fBprepend()\fR in succession, except that this operation is
atomic.
.SS "reverse"
.IX Subsection "reverse"
.Vb 3
\&  $moo\->reverse;
\&  $moo\->reverse(2);
\&  $moo\->reverse(5, 7);
.Ve
.PP
Reverse the order of the items in the queue. You can limit this operation by
giving a range as described in \fBcrop()\fR as last argument.
.SS "run_queue"
.IX Subsection "run_queue"
.Vb 1
\&  $moo\->run_queue;
.Ve
.PP
Allows new songs to be played again after \fBhalt_queue()\fR has been called.
.SS "runqueue"
.IX Subsection "runqueue"
See \fBrun_queue()\fR.
.SS "set_history_limit"
.IX Subsection "set_history_limit"
.Vb 1
\&  $moo\->set_history_limit(44);
.Ve
.PP
Set the limit on the size of the history list stored in memory.
.SS "set_loop_mode"
.IX Subsection "set_loop_mode"
.Vb 2
\&  $moo\->set_loop_mode(0);
\&  $moo\->set_loop_mode(1);
.Ve
.PP
Turn loop mode on or off.
.SS "showconfig"
.IX Subsection "showconfig"
.Vb 2
\&  my $config = $moo\->showconfig;
\&  my %config = $moo\->showconfig;
.Ve
.PP
Return the server's player configuration. If \fBshowconfig()\fR is called in scalar
context a scalar containing the textual description of the configuration is
returned. If you call \fBshowconfig()\fR in list context a hash which maps the
configuration regular expression to the player commands is returned.
.SS "shuffle"
.IX Subsection "shuffle"
.Vb 3
\&  $moo\->shuffle;
\&  $moo\->shuffle(2);
\&  $moo\->shuffle(4, 6);
.Ve
.PP
Rearrange the contents of the queue into a random order. You can limit this
operation by giving a range as described for \fBcrop()\fR as last argument.
.SS "skip"
.IX Subsection "skip"
.Vb 1
\&  $moo\->skip;
.Ve
.PP
Skips the rest of the current song to play the next song in the queue. This only
has an effect if there actually is a current song.
.SS "sort"
.IX Subsection "sort"
.Vb 3
\&  $moo\->sort;
\&  $moo\->sort(2);
\&  $moo\->sort(4, 6);
.Ve
.PP
Arrange the contents of the queue into sorted order.
.SS "stop"
.IX Subsection "stop"
.Vb 1
\&  $moo\->stop;
.Ve
.PP
Stop playing the current song and stops new songs from playing. The current
song is returned to the head of the song queue and is not recorded in the
history list. If loop mode is on, the current song won't be placed at the end of
the song queue when it is stopped.
.SS "sub"
.IX Subsection "sub"
.Vb 3
\&  $moo\->sub(\*(Aqregex\*(Aq, \*(Aqsubstitition\*(Aq);
\&  $moo\->sub(\*(Aqregex\*(Aq, \*(Aqsubstitition\*(Aq, 2);
\&  $moo\->sub(\*(Aqregex\*(Aq, \*(Aqsubstitition\*(Aq, 1, 7);
.Ve
.PP
Perform a regular expression substitution on the items in the queue. You can
limit this operation by giving a range as described for \fBcrop()\fR as last argument.
.SS "sub_all"
.IX Subsection "sub_all"
.Vb 3
\&  $moo\->sub_all(\*(Aqregex\*(Aq, \*(Aqsubstition\*(Aq);
\&  $moo\->sub_all(\*(Aqregex\*(Aq, \*(Aqsubstition\*(Aq, 2);
\&  $moo\->sub_all(\*(Aqregex\*(Aq, \*(Aqsubstition\*(Aq, 1, 7);
.Ve
.PP
Performs a global regular expression substitution on the items in the queue.
.SS "swap"
.IX Subsection "swap"
.Vb 1
\&  $moo\->swap( [7, 10], [ 5 ]  );
.Ve
.PP
Swap the items contained in one range with the items contained in the other
range. The ranges for the \fBswap()\fR method needs to be passed as array references
in contrast to other methods that use ranges.
.SS "listMethods"
.IX Subsection "listMethods"
.Vb 1
\&  @methods = $moo\->listMethods;
.Ve
.PP
Return an array of all available XML-RPC methods on this server.
.SS "methodHelp"
.IX Subsection "methodHelp"
.Vb 1
\&  $help = $moo\->methodHelp(\*(Aqsub\*(Aq);
.Ve
.PP
Given the name of a method, return a help string.
.SS "methodSignature"
.IX Subsection "methodSignature"
.Vb 1
\&  $signature = $moo\->methodSignature;
.Ve
.PP
Given the name of a method, return an array of legal signatures. Each signature
is an array of scalars. The first item of each signature is the return type, and
any others items are parameter types.  =cut
.SS "multicall"
.IX Subsection "multicall"
.Vb 1
\&  $moo\->multicall(...);
.Ve
.PP
Process an array of calls, and return an array of results. This is not
implemented yet.
.SS "toggle_loop_mode"
.IX Subsection "toggle_loop_mode"
.Vb 1
\&  $moo\->toggle_loop_mode;
.Ve
.PP
Turn loop mode on if it is off, and turns it off if it is on.
.SS "toggle_pause"
.IX Subsection "toggle_pause"
.Vb 1
\&  $moo\->toggle_pause;
.Ve
.PP
Pause the current song if it is playing, and unpauses if it is paused.
.SS "unpause"
.IX Subsection "unpause"
.Vb 1
\&  $moo\->unpause;
.Ve
.PP
Unpauses the current song.
.SS "version"
.IX Subsection "version"
.Vb 1
\&  $version = $moo\->version;
.Ve
.PP
Return the Moosic server's version string.
.SH "HELPER METHODS"
.IX Header "HELPER METHODS"
The following methods aren't methods defined by the moosic \s-1API\s0 but should be
useful when dealing with a moosic server.
.SS "play"
.IX Subsection "play"
.Vb 1
\&  $moo\->play();
.Ve
.PP
Start playing. If the playback is paused it will be unpaused. If the queue is
stopped it will be started.
.SS "can_play"
.IX Subsection "can_play"
.Vb 1
\&  $moo\->append( $song ) if $moo\->can_play( $song );
.Ve
.PP
Takes a list of songs as argument and returns all items that can be played by
the moosic daemon.
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 4
check arguments more strictly
.Sp
especially for constructors.
.PP
If you find some others please report them to Florian Ragwitz
<flora@cpan.org>
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
implement system_multicall
.IP "\(bu" 4
improve client_config
.IP "\(bu" 4
maybe use autoloader to load subs on demand
.Sp
create the method arguments from methodSignature.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBmoosic\fR\|(1), \fBmoosicd\fR\|(1), http://nanoo.org/~daniel/moosic/
.SH "AUTHOR"
.IX Header "AUTHOR"
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2004\-2008 by Florian Ragwitz
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.4 or,
at your option, any later version of Perl 5 you may have available.