libmuroar(7)

📦 version 0.1.13, in ubuntu jammy

🦋 libmuroar — the minimalist RoarAudio sound library, bestie edition 🦋

okay so you opened the manual for libmuroar(7) — that's the System Manager's Manual: MuRoar page, and yes, I'm about to make it make sense. it's giving "small but mighty". let's go 💅

✨ NAME ✨

libmuroar — a minimalist RoarAudio sound library. that's it, that's the whole vibe. tiny library, big purpose. 🎀

🌸 SYNOPSIS 🌸

#include <muroar.h>

that's literally all you need to pull in, no cap. 🫶

💖 DESCRIPTION 💖

so libmuroar is a client side implementation of the RoarAudio protocol. it's the thing you use to comunicate with RoarAudio servers. (yes, the original says "comunicate", I'm keeping it, we don't correct history around here 😭)

here's the thing though — like the name suggests, it only supports a subset of the protocol. and that's by design, not an accident, not a bug, it's the whole point. it's the minimalist icon we stan. 👑

so if your application needs more features of the protocol, you gotta go use libroar(7) or literally any other client library implementation that provides the features you need. libmuroar is not gonna grow extra arms for you. periodt.

🌈 LICENSE 🌈

libmuroar is licensed under the GNU LGPL version 3 (with the "or later" option). ✨

and the tea here is: this license allows non-free applications to use this library, while libroar doesn't. so if you're shipping something closed-source, this is your girl. 💅

see the license text for details. (go read it, fr fr, don't just skim.)

🎀 EXAMPLES 🎀

the source code of the provided program muroarstream(1) can be used as an example of how to use this library. so if you're like "how do I even", go peek at that. free tutorial, no gatekeeping. 🫶

🧚 SERVER ADDRESS 🧚

depending on which features are compiled into MuRoar, different server address types are supported. so like, your build might not have everything. vibe check your compile flags, bestie.

  • UNIX Domain Sockets — the address is in the form /path/to/sock. at least one slash needs to be included. don't forget the slash, it's load-bearing. 😭
  • TCP/IP connections — host:port is what you use. the port (and the colon) is optional though, so host alone is valid too. slay.
  • DECnet connections — the address is in the form node::object. both node and object are optional. when they're not given, defaults are used (the local node, and the default object). ✨

in addition, these special addresses are supported:

  • "+default" — does the same thing as passing a NULL pointer, but it exists to work around applications that don't let the user pass a NULL pointer in some way. it's the polite workaround. 🙈
  • "+invalid" — used to tell the connection to always fail. this is useful for testing and debugging. yes, a deliberate failure. iconic behavior honestly.
  • "+abstract" — a special kind of UNIX Domain Socket, requesting to connect to the abstract namespace.

👑 PROTOCOL FEATURES 👑

here's everything this library supports. some of it may not be compiled in depending on your build time configuration and target Operating System. so like, don't @ me if a feature ghosted your build. 💀

Protocol constants

a lot of protocol constants are exported in the header. this includes:

  • default server addresses
  • default audio profiles
  • command IDs
  • flags needed by commands
  • stream direction parameter
  • codec IDs

and the exported constants are not limited to what this library needs internally. they gave us the whole drawer of snacks. 🍓

Opening a control connection

control connections to a server can be opend using muroar_connect(3). (again, original spelling, keeping it 💜) the function does all the basic protocol setup, including sending client name. one function call, so many chores handled. 🫶

Closing a control or data connection

the functions muroar_quit(3) and muroar_close(3) close a control or data connection. goodbye bestie, connection closed. 👋

Opening a data connection

the function muroar_stream(3) is used to transform a control connection into a data connection (using the EXEC command). glow-up arc for your socket. ✨

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. it's a little "hey!! look at me!!" for your users. 🔔

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
  • act as Keep-Alive on long living connections

so it's both a stopwatch and a "still here btw 🫶". dual purpose, main character energy.

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. so if the number of channels doesn't match, the volume is set using the UNMAPPED mode, in which the channel setup is converted automatically — and 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. yes ma'am. 👑

see section PORTABILITY NOTES for details. ⬇️

💜 PORTABILITY NOTES 💜

this library is designed to be portable. it should work well on all kinds of POSIX systems including UNIX and GNU/Linux.

it's also maintained for Win32 and was ported to OpenVMS. 🎉

porting to YIFF is work in process. (we're getting there, be patient 🙈)

it should work on all CPUs, only depending on the Operating System to provided the needed interfaces. (yes, "to provided", keeping it, it's part of the charm 😭)

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. so like, use it. fr fr.

🌟 ENVIRONMENT VARIABLES 🌟

these variables are used in libmuroar itself, so they're common to all clients using libmuroar. shared ecosystem, shared env vars. 🌈

  • 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. it applies if all types of server addresses are supported. example time:
ln -s /tmp/roar /etc/roarserver
ln -s somehost /etc/roarserver
ln -s mynode:: /etc/roarserver

look at that, three little symlinks, three different address types. versatility. 💅

⭐ NOTES ⭐

this library should not be confused with the similar named server implementation "MuRoarD". different creature entirely. don't mix them up, that's the whole note. 🙈

🔥 SEE ALSO 🔥

🦋 HISTORY 🦋

MuRoar was first released on Fri Oct 09 2009 at 22:42 CEST. a legend was born. ✨

SONAME has been changed last in 0.1rc2 on Sun Feb 28 2010 at 17:08 CET. the last glow-up. 💅

and that's the whole page, bestie!! 🫶 this one came from RoarAudio, dated May 2012, and it lives at libmuroar(7) in the manual. go forth and be portable, you absolute icon 👑💖

📦 where this page comes from