libmuroar(7)

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 diffrent 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 suppored. 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 usefull 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 protcol 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.