.\" RoarAudio .TH "libmuroar" "7" "May 2012" "RoarAudio" "System Manager's Manual: MuRoar" .SH NAME libmuroar \- minimalist RoarAudio sound library .SH SYNOPSIS #include .SH "DESCRIPTION" \fBlibmuroar\fR 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 \fBlibroar\fR(7) or any other client library implementation providing the features they need. .SH "LICENSE" \fBlibmuroar\fR 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. .SH "EXAMPLES" The source code of the provided program \fBmuroarstream\fR(1) can be used as example how to use this library. \".SH "TUTORIALS" \""Tutorials can be found in \fBroartut\fR(7). .SH "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. .SH "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. .TP \fBProtocol constants\fR 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. .TP \fBOpening a control connection\fR Control connections to a server can be opend using \fBmuroar_connect\fR(3). The function does all the basic protocol setup including sending client name. .TP \fBClosing a control or data connection\fR The functions \fBmuroar_quit\fR(3) and \fBmuroar_close\fR(3) close a control or data connection. .TP \fBOpening a data connection\fR The function \fBmuroar_stream\fR(3) is used to transform a control connection into a data connection (using the EXEC command). .TP \fBNotify Beeps\fR Notify Beeps (sounds) can be send using \fBmuroar_beep\fR(3). This function requests the server to emit a beep to notify the user about some event. .TP \fBPinging and Keep-Alive\fR The server can be pinged via \fBmuroar_noop\fR(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. .TP \fBSetting volume\fR Using \fBmuroar_setvolume\fR(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.) .TP \fBI/O Abstraction\fR The functions \fBmuroar_write\fR(3) and \fBmuroar_read\fR(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. .SH "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. .SH "ENVIRONMENT VARIABLES" The following variables are used in libmuroar itself so they are common to all clients using libmuroar. .TP \fBHOME\fR The user's home directory. This is used to locate the user's local socket ($HOME/.roar). .TP \fBROAR_SERVER\fR The address of the server to use. See section SERVER ADDRESS for details. .SH "FILES" .TP \fB/etc/roarserver\fR 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 .SH "NOTES" This library should not be confused with the similar named server implementation "MuRoarD". .SH "SEE ALSO" \fBmuroarstream\fR(1), \fBlibroar\fR(7). .SH "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. .\"ll