roarctl(1)

📦 version 1.0~beta12, in ubuntu jammy

💖 roarctl(1) 💖

okay bestie, so this is roarctl(1), straight out of the System Manager's Manual: roard — and it's literally the remote control for your RoarAudio sound server. sit down, get comfy, we're doing this. 🎀

✨ NAME ✨

roarctl — the RoarAudio sound server control tool. that's it, that's the girl. 💅

🌸 SYNOPSIS 🌸

roarcat [OPTIONS]... COMMAND [OPTS] [COMMAND [OPTS] [COMMAND [OPTS]
[...]]]

(yes, it really says roarcat up there in the original synopsis and we are not touching it, no cap. icon behavior. 💀)

🦋 DESCRIPTION 🦋

So what does this thing do?? It controls the RoarAudio sound server. How? By sending commands to the server. That's the whole vibe. Go look at COMMANDS for the full list of what you can throw at it. ✨

👑 GENERAL OPTIONS 👑

  • --help — prints some help text. classic.
  • --verbose, -v — be verbose. and yeah, you can stack this one multiple times if you want it extra chatty. 🔥
  • --list-libstandards — similar to serverstandards, reports the list of standards libroar supports.
  • --list-aiprofiles — shows audio info profiles and then dips out (exits).
  • --enum-servers — lists servers found on the network. depending on the build options of libroar, this includes results from many tests, like standard server locations, OpenSLP located servers, X11 located servers, DECnet's neighbor, IP's ARP table, and other sources. she's thorough. 🧚

🌈 NETWORK OPTIONS 🌈

  • --server SERVER — the server to connect to. simple as that.

⭐ BASIC COMMANDS ⭐

  • help — same as --help.
  • listaiprofiles — lists audio info profiles.
  • aiprofileget PROFILE — displays the given audio info profile.
  • sleep TIME — sleeps for TIME seconds. self-care command fr.
  • ping NUM — pings the server NUM times. it does this by sending NOOP commands to the server, and prints the response time plus a small statistics section.
not supported on all platforms, bestie. just so you know. 😭
  • servername — shows the server address of the server you're currently connected to. this can be different from what you gave, like in the case of special server names such as +fork.
  • whoami — reports the client ID of roarctl on the current server. main character moment.
  • standby, off, resume, on — brings the server into standby mode, or back into active (operating) mode.
  • standbymode — tells you if the server is in standby mode or not.
  • exit — quits the server.
  • terminate — terminates the server as soon as all clients are disconnected and all streams reach EOF.

💜 STREAM COMMANDS 💜

  • volume STREAMID CHANNELS VOL0 VOL1 VOL2... — sets the mixing level for a stream with id STREAMID.

CHANNELS is the number of channels to set volume on. this should be the number of channels of the stream, or a symbolic name. currently the symbolic names mono and stereo are allowed. if you use mono, all channels get the level you give as VOL0. if you use stereo, it'll try to set the mixing levels the way you're used to from stereo setups — even if the setup isn't actually in stereo.

The parameters VOL0 ... VOLn and how many of them there are depends on what you gave as CHANNELS. you have to give exactly CHANNELS parameters.

⚠️ if you give a numerical (not symbolic) value for CHANNELS and the stream actually has a different number of channels, the behavior is undefined. in the current implementation only the first CHANNELS channels will be updated. this behavior may change in the future. so like, be careful bestie. 💀
  • kick TYPE ID — kicks an object of TYPE with id ID. possible types are: client stream sample source

you can get the ID via list* (see below).

  • newvirtual P D E R B C — adds a new virtual (child) stream. this is used with container formats such as RAUM, Ogg and Matroska.

parameters, one by one:

  • P — stream ID of Parent stream.
  • D — stream Direction.
  • E — stream codEc.
  • R — sample Rate.
  • B — Bits per sample.
  • C — number of Channels.
  • flag ID FLAGS, unflag ID FLAGS, toogleflag ID FLAGS — sets, removes or toggles flags on a stream. ID is the stream id, FLAGS is a comma separated list of flags.
it is not possible to set all kinds of flags at runtime. 🙈
  • protectflag ID FLAGS — protects flags on a stream. ID is the stream id, FLAGS is a comma separated list of flags.

protected flags can't be changed anymore after they got protected. periodt. 🔒

🎀 META DATA COMMANDS 🎀

  • role ID ROLE — set stream role ROLE on stream ID.
  • metaget ID TYPE — read meta date of type TYPE from stream ID.
  • metasave ID FILE — saves the meta data of stream ID to file FILE. the format is one KEY=Value pair per line, and the same format is used by Xiph's tools.
  • metaload ID FILE — loads meta data from file FILE into stream ID. the format is the same as for metasave.

🍓 SERVER INFO COMMANDS 🍓

  • serverinfo — gets general information about the server. this includes software vendor and version.
  • servertime — reports the server's system time.
  • serverstandards — reports a list of standards the server supports.
  • libstandards — similar to serverstandards, reports the list of standards libroar supports. same as --list-libstandards.
  • serveroinfo — gets information about server output.
  • serveroinfo2 DIR — gets information about server output for a given direction.

🫶 LISTING COMMANDS 🫶

  • listclients — gets information about clients.
  • clientinfo ID — gets information about client ID.
  • liststreams — gets information about streams.
  • streaminfo ID — gets information about stream ID.
  • allinfo — same as "serveroinfo listclients liststreams".

🌸 ENVIRONMENT VARIABLES 🌸

below are only the basic environment variables, bestie — for a complete list see libroar(7). ✨

  • HOME — the user's home directory.
  • ROAR_SERVER — the address of the listening server. this may be in the form of host:port for TCP/IP connections, and /path/to/sock for UNIX Domain Sockets. this is the same as the --server option.

💀 BUGS 💀

  1. Make the meta data commands api-fixed and list them here.
  2. more often check if the user gave us enough arguments.

🌈 SEE ALSO 🌈

roarvorbis(1), roarfish(1), roarbaseclients(1), roartestclients(1), libroar(7), RoarAudio(7).

⭐ HISTORY ⭐

for history information see RoarAudio(7).

and that's the whole page, babe 💖 this gorgeous piece of documentation is brought to you by RoarAudio, dated July 2008 (vintage! iconic!), and it lives in section roarctl(1) of the manual. go forth and control that sound server. mwah. 🎀✨

📦 where this page comes from