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.

RoarAudio                                           May 2012                                        libmuroar(7)