DOKK / manpages / debian 11 / libmuroar-dev / libmuroar.7.en
libmuroar(7) System Manager's Manual: MuRoar libmuroar(7)

libmuroar - minimalist RoarAudio sound library


#include <muroar.h>

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.

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.

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

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.

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.

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.

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

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

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

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.

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.

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.)

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.

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.

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

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

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

/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

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

muroarstream(1), libroar(7).

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.

May 2012 RoarAudio