NAME

       libmuroar - minimalist RoarAudio sound library

SYNOPSIS

        #include <muroar.h>

DESCRIPTION

       libmuroar  is  a  client  side  implementation  of  the RoarAudio protocol.  It is used to
       comunicate with RoarAudio servers. As the name suggests it only supports a subset  of  the
       protocol.  This  is by design. Any application needing more features of the protocol needs
       to use libroar(7) or any other client library implementation providing the  features  they
       need.

LICENSE

       libmuroar  is licensed under the GNU LGPL version 3 (with "or later" option).  This allows
       non-free applications to use this library while libroar doesn't.  See the license text for
       details.

EXAMPLES

       The  source code of the provided program muroarstream(1) can be used as example how to use
       this library.

SERVER ADDRESS

       Depending on which features are compiled into MuRoar different server  address  types  are
       supported.

       For  UNIX Domain Sockets the address is in form /path/to/sock. At least one slash needs to
       be included.  For TCP/IP connections host:port is used. While the port (and the colon)  is
       optional.   For  DECnet  connections  the  address  is in form node::object. Both node and
       object are optional.  When they are not given defaults are used (local node,  and  default
       object).

       In  addition  the  special addresses "+default", "+invalid" and "+abstract" are supported.
       The "+default" address does the same as passing a NULL pointer but is used to work  around
       applications  not  letting  the  user  to pass a NULL pointer in some way.  The "+invalid"
       address is used to tell the connection to always fail. This  is  useful  for  testing  and
       debugging.  The "+abstract" address is a special kind of UNIX Domain Socket, requesting to
       connect to the abstract namespace.

PROTOCOL FEATURES

       The following features are supported by this library. Some of them may not be compiled  in
       depending on the build time configuration and target Operating System.

       Protocol constants
              A  lot  protocol constants are exported in the header. This includes default server
              addresses, default audio profiles, command IDs, flags needed  by  commands,  stream
              direction parameter and codec IDs.

              The exported constants are not limited to what this library needs internally.

       Opening a control connection
              Control connections to a server can be opend using muroar_connect(3).  The function
              does all the basic protocol setup including sending client name.

       Closing a control or data connection
              The  functions  muroar_quit(3)  and  muroar_close(3)  close  a  control   or   data
              connection.

       Opening a data connection
              The function muroar_stream(3) is used to transform a control connection into a data
              connection (using the EXEC command).

       Notify Beeps
              Notify Beeps (sounds) can be send using muroar_beep(3). This function requests  the
              server to emit a beep to notify the user about some event.

       Pinging and Keep-Alive
              The  server can be pinged via muroar_noop(3). This can be used to messure effective
              latency between the client and server. It can also be used as  Keep-Alive  on  long
              living connections.

       Setting volume
              Using  muroar_setvolume(3)  the  volume  of  a stream can be set.  This function is
              limited to setting mono or stereo volumes  but  not  limited  to  mono  and  stereo
              streams.   If  the  number  of  channels does not match the volume is set using the
              UNMAPPED mode in which the channel setup is converted automatically (the  developer
              do not need to care).  (Since version 0.1.8.)

       I/O Abstraction
              The functions muroar_write(3) and muroar_read(3) are provided to do portable I/O on
              the data connection as provided by this library. They should be used.  See  section
              PORTABILITY NOTES for details.

PORTABILITY NOTES

       This  library is designed to be portable. It should work well on all kind of POSIX systems
       including UNIX and GNU/Linux. It is also maintained for Win32 and was ported  to  OpenVMS.
       Porting  to  YIFF  is  work  in process.  It should work on all CPUs only depending on the
       Operating System to provided the needed interfaces.

       The library exports most of it's  internal  I/O-abstraction  to  enable  writing  portable
       clients.  This should be used and seems to be important on Win32.

ENVIRONMENT VARIABLES

       The  following  variables  are  used in libmuroar itself so they are common to all clients
       using libmuroar.

       HOME   The user's home  directory.  This  is  used  to  locate  the  user's  local  socket
              ($HOME/.roar).

       ROAR_SERVER
              The address of the server to use.  See section SERVER ADDRESS for details.

FILES

       /etc/roarserver
              This  is  a  symlink  to  the  server socket.  If all types of server addresses are
              supported.  Example:
               ln -s /tmp/roar /etc/roarserver
               ln -s somehost /etc/roarserver
               ln -s mynode:: /etc/roarserver

NOTES

       This library  should  not  be  confused  with  the  similar  named  server  implementation
       "MuRoarD".

SEE ALSO

       muroarstream(1), libroar(7).

HISTORY

       MuRoar  was first released on Fri Oct 09 2009 at 22:42 CEST.  SONAME has been changed last
       in 0.1rc2 on Sun Feb 28 2010 at 17:08 CET.