ROARD(1)

📦 version 1.0~beta12, in ubuntu jammy

🌸 ROARD(1) — System Manager's Manual: roard 🌸

okay bestie, welcome to the roard page, aka the manual for the RoarAudio sound server. yes this is long. no we are not skipping anything. grab a snack, we're doing this together 💖

✨ NAME ✨

roard — the RoarAudio sound server, periodt.

✨ SYNOPSIS ✨

roard [OPTIONS]...

✨ DESCRIPTION ✨

so roard is THE most common RoarAudio sound server, like the main character of the whole RoarAudio setup. it's the central component, the glue, the girlboss holding everything together. what it does is mix up all the different audio streams coming from its clients and send them out to its outputs. and bestie, those outputs can be soundcards, monitoring clients, streaming servers, and more. it's giving versatility 💅

✨ GENERAL OPTIONS ✨

heads up: this list is incomplete! so don't come for me if there's more.
  • --help — prints some help text. cute, simple, iconic.
  • --daemon — dips into the background after startup. main character leaves the room quietly.
  • --realtime — asks for higher priority. can be used multiple times (go off, stack it).
  • --memlock LEVEL — sets the default memory locking level to LEVEL.

valid levels are:

  • none — no memory is locked at all. zero. nada.
  • low — only very few (important) objects get locked in memory.
  • medium — few (important) objects get locked in memory.
  • high — many objects get locked in memory.
  • nearlyall — all known objects get locked in memory.
  • nearlyallsys — all known objects get locked in memory, but also pages provided by the system like stack and heap.
  • allcur — all currently used pages get locked in memory.
  • all — all pages get locked in memory, including future allocated pages.
  • default — use defaults (this is the default).
⚠️ real talk: a higher memlock level may result in memory allocation problems at runtime and even segfauls on some systems (VM killed processes). check your current system limits before altering this value. like, actually check. 🙈
  • --watchdog — enables the watchdog. this will terminate the daemon if something bad happened and it halted.
  • --watchdog-time TIME — sets the watchdog time to TIME, in ms.
  • --pidfile PIDFILE — asks the server to use the given pidfile. this one is recommended 🫶
  • --sysclocksync — messures the exact audio clock frequency based on system time. obsolete.

✨ SERVER INFO ✨

  • --location LOC — sets the lion-readable location of the server. examples: livingroom, room 32.
  • --description DESC — sets the lion-readable description of the server. examples: Stereo, UKW Transmitter.
  • --contact CONTACT — sets contact information for the server.
  • --serial SERIAL — sets the serial number for this device or server. normally this is only used by embedded systems.
  • --uiurl UIURL — sets the URL of the user interface for this device or server. again, normally only used by embedded systems. it's common to set this to a URL of type HTTP, but all protocols are considered valid. yes, that includes ssh, telnet and others. valid is valid ✨

✨ STARTUP AND SHUTDOWN ✨

  • --start — start a new server.
  • --stop — stop the currently running server. see also --shutdown.
  • --restart — stop the currently running server and start up a new server. glow up moment.
  • --shutdown — terminates the currently running server after the last client has quit. this is the most clean way to shut down a running server, because it does not kick any clients. do not confuse this with --terminate.
  • --terminate — auto terminates the new server after the last client has quit. and do not confuse this one with --shutdown. they are different girls, okay?
  • --script-postdown S — run script S after server shutdown. the script gets passed to a shell, so any shell feature can be used within the string. sky's the limit bestie 🌈

✨ STANDBY MODE ✨

  • --standby — start in standby mode.
  • --auto-standby — go into standby mode if no streams are active. it just knows when to chill 😌

✨ LOGGING ✨

  • --verbose — increment the verbosity level. can be used multiple times. the more the merrier.
  • --log-syslog — log to syslog.

✨ PLUGINS ✨

  • --plugin-load FILENAME — load the given plugin.
  • --plugin-args ARGS — arguments for the plugin. (must be given before the --plugin-load) — order matters, don't play yourself.
  • --list-plugins — list loaded plugins.

✨ SECURITY ✨

  • --chroot DIR — chroots to the given directory. this improves the security. normally this needs root privileg's.

✨ USER AND GROUPS ✨

  • --setgid — sets GroupID to the audio group as specified via -G.
  • --setuid — sets UserID to the audio user as specified via -U.
  • -G GROUP — sets the group for the UNIX Domain Socket (default: audio). you need the permittions to change the GID.
  • -U USER — sets the user for the UNIX Domain Socket (default: do not set). you need the permittions to change the UID — normally only root has that 👑

✨ AUTH OPTIONS ✨

the following options control the access rights of connections. some of them take an access level, and the access level is one from the following list:

  • none — used to disable an authentication method.
  • idented — used internally. should not be used.
  • conctl — the client is only allowed to do some basic operations, only affecting its own connection.
  • guest — guest access (read only). the client may list resources but not alter them.
  • user — normal user. the client may create and alter most resources.
  • pwruser — Power User. the client can create and alter all resources and do all operations, except operations which would break the POSIX right system. the user is not allowed to control the server itself, like terminating it, or alter (system) resources with the rights of the user runnung roard. this is the access level a fully trusted user in a multi user setup should have.
  • all — the client can do everything. this includes operations which may alter system resources (like files) with the rights of the user running roard. this accesslevel should be given to the user in case of a single user setup, or root, or some administrator in a multi user setup. big power, handle responsibly 💀
  • --guest-acclev ACCESSLEVEL — sets the access level for guest connections. set to "none" to disable guest access.
  • --trust-acclev ACCESSLEVEL — sets the access level for clients authenticated by trust auth. set to "none" to disable trust auth.
  • --trust-root — trust root user.
  • --no-trust-root — do not trust root user.
  • --authfile-gen FILE — generate a new authfile with a fresh cookie. fresh out the oven 🍓
  • --authfile-load FILE — load all keys from a given authfile.
  • --authfile-type TYPE — sets the type for the authfile.
  • --authfile-acclev ACCLEV — sets the access level for the given authfile.
  • --new-authfile — add another authfile.

✨ AUDIO OPTIONS ✨

  • --rate RATE, -R RATE — set server sample rate.
  • --bits BITS, -B BITS — set server bits.
  • --chans CHANNELS, -C CHANNELS — set server channels.
  • --aiprofile PROFILE — use an existing audio profile.

✨ GENERAL STREAM OPTIONS ✨

  • --stream-flags — sets default flags for a given stream direction. examples: play=-meta, bidir=+antiecho.

✨ DRIVER OPTIONS ✨

  • --list-driver — shows a list of all available drivers.
  • --driver, -d — this option is obsolete. use -o instead.
  • --device, -D — this option is obsolete. use -O instead.
  • --odriver, -o — set the output driver. to get a list of all drivers use --list-driver.
  • --odevice, -O — set the device for the output driver. possible devices depend on the driver. they may be a path to a device node or a hostname. use --list-driver to get a hint.
  • -oO — sets options for the new stream. see STREAM OPTIONS.
  • -oN — adds another output.
  • -oP — marks the output primary.

✨ SOURCE OPTIONS ✨

  • --list-sources — list all supported sources.
  • --source, -s — adds a source of the given type.
  • -S — sets the device or filename for the source. type may depend on the source type.
  • -sO — sets options for the current source.
  • -sN — adds another source.
  • -sP — marks the source as primary. if the source reaches EOF, roard will quit automatically. dramatic much? 😭

✨ HARDWARE MIXER OPTIONS ✨

  • --list-mixers — list all supported hardware mixers.
  • --mixer, -m — add a hardware mixer of given type.
  • -M — sets the device used for the hardware mixer.
  • -mO — sets options for the hardware mixer. see MIXER OPTIONS.
  • -mN — adds another hardware mixer.
  • -mP — marks the mixer primary.

✨ CODEC FILTER ✨

  • --list-cf — list all supported codecfilters and codecs.

✨ MIDI OPTIONS ✨

  • --midi-no-console — disable console based MIDI synth.
  • --midi-console-enable — enables console based MIDI synth.
  • --midi-console — sets device for MIDI console. example: /dev/console.
  • --ssynth-enable — enables simple software synth.
  • --ssynth-disable — disables simple software synth.

✨ LIGHT CONTROL OPTIONS ✨

  • --light-channels — sets the number of light channels. examples: 512, 1024. mood lighting but make it technical ✨

✨ RADIO DATA SYSTEM OPTIONS ✨

  • --rds-pi — sets the Programme Identification (PI).
  • --rds-ps — sets the Programme Service Name (PS).
  • --rds-pty — sets the Programme Type (PTY).
  • --rds-tp — sets the Traffic Programme (TP) flag.
  • --rds-ct — enables sending of RDS Clock Time (CT).

✨ X11 OPTIONS ✨

  • --x11-display, --display — sets the display to use.
  • --x11 — enable X11 support.

okay bestie that's part one, and we are NOT done yet — more is coming, so don't go anywhere 💜

🌐 NETWORK OPTIONS 🌐

okay bestie, this is the whole "how does roard even talk to people" section and honestly it's giving main character energy 💅

  • --tcp, -t — sets defaults for TCP/IP Socket. classic, iconic, the OG way to be reachable 🫶
  • -4, -6 — use IPv4 or IPv6 mode. pick your internet era, no wrong answers ✨
  • -64 — tries to downgrade IPv6 sockets into IPv4 sockets. like, it wants to be v4, let it live 💫
  • --unix, -u — sets defaults for UNIX Domain Socket.
  • --decnet, -n — sets defaults for DECnet Socket. yes decnet, it's a whole vintage vibe, we love a throwback 🎀
  • --port, -p — sets the port the server should listen on.
  • --bind, -b, --sock — sets the hostname or path the server should listen on.
  • --list-proto — list supported protocols. window shopping, but for protocols 👀
  • --proto — sets the protocol used for the listening socket.
  • --proto-dir, --proto-rate, --proto-bits, --proto-codec, --proto-chans, --proto-aiprofile — set stream parameters for protocols needing stream options. Defaults to server defaults. (yes that's six flags in one breath, we're efficient 💅)
  • --list-profiles — list supported profiles.
    • --proto-profile — use the given profile for the listening socket.
  • --new-sock — adds a new listening socket. more sockets, more friends, periodt ✨
  • --no-listen — do not listen for new clients (only useful for relaing, impleys --terminate).
  • --client-fh FH — expects a client on the given FH. This may be useful with --no-listen.
  • --close-fh FH — close the given FH. This is not useful for endusers but used internaly.
  • --jumbo-mtu — sets the MTU for Jambo Packets. jumbo, jambo, same energy fr fr 🐘

🧚 OPENSLP OPTIONS 🧚

  • --slp — enable OpenSLP support.

🎧 STREAM OPTIONS 🎧

the way that these are literally the settings for every single stream... obsessed. here's the whole squad 💜

  • rate — sets the sample rate.
  • channels — sets the number of channels.
  • bits — sets the number of bits per sample.
  • codec — sets the codec.
  • blocks — sets the number of memory blocks that should be used by the devices. Most devices only support a few values or don't support this option at all. If this option or the specifyed value is not supported by the device this is not handled as fatal error.
  • blocksize — sets the size of the memory blocks used by the device. Most devices only support a few values or don't support this option at all. If this option or the specifyed value is not supported by the device this is not handled as fatal error.
  • meta — sets the meta flag.
  • sync — sets the sync flag.
  • primary — marks this stream as primary. main character stream, obviously 👑
  • cleanmeta — sets the cleanmeta flag.
  • autoconf — sets the autoconf flag. This flag is not supported by all drivers. If the flag is set and the devices does not support this there is no fatal error if the device could be opend with defaults.
  • Example:
rate=44100,bits=16,channels=2,codec=pcm,sync

like. look at her. comma-separated and everything 😭💖

🎚️ MIXER OPTIONS 🎚️

  • primary — makes this stream as primary.
  • autoconf — sets the autoconf flag.
  • passmixer — sets the passmixer flag.
  • name — sets the name for the device.
  • subs — sets list of subdevices. This is driver specific.

🌈 ENVIRONMENT VARIABLES 🌈

the vibes the server reads from the air around it, iykyk 🦋

  • HOME — the users home directory.
  • ROAR_SERVER — the address of the listening server. This may be in form of host:port for TCP/IP connections and /path/to/sock for UNIX Domain Sockets.
  • ROAR_DRIVER — the driver to select. Same as -d.
  • ROAR_DEVICE — the device to select. Same as -D.

💀 BUGS 💀

There are lots of bugs...

ngl that's the whole section. she said what she said and she was honest about it 😭 iconic transparency fr fr

👀 SEE ALSO 👀

roar-config(1), roarcat(1), roarcat2sock(1), roarcatad(1), roarctl(1), roarfilt(1), roarfish(1), roarmon(1), roarsockconnect(1), roartypes(1), roarvorbis(1), RoarAudio(7).

go read those too bestie, they're all in the group chat 🫶✨

📜 HISTORY 📜

For history information see RoarAudio(7).

and that's the whole page, bestie!! 🎀✨ this one's from the RoarAudio crew, dated October 2010, and it's the ROARD(1) page — so go forth, configure your server, and slay 💅👑🌸

📦 where this page comes from