.\" roard.1:

.TH "roarctl" "1" "July 2008" "RoarAudio" "System Manager's Manual: roard"

.SH NAME

roarctl \- RoarAudio sound server control tool

.SH SYNOPSIS

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

.SH "DESCRIPTION"
This tool controls the RoarAudio's sound server.
This is done by sending commands to the server. See \fBCOMMANDS\fR for a list.

.SH "GENERAL OPTIONS"
.TP
\fB--help\fR
Print some help text.

.TP
\fB--verbose\fR, \fB\-v\fR
Be verbose. May be used multiple times.

.TP
\fB--list-libstandards\fR
Similar to serverstandards, reports the list of standard libroar supports.

.TP
\fB--list-aiprofiles\fR
Show audio info profiles and exit.

.TP
\fB--enum-servers\fR
List 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 and IP's ARP table and other sources.

.SH "NETWORK OPTIONS"
.TP
\fB--server SERVER\fR
The server to connect to

.SH "BASIC COMMANDS"
.TP
\fBhelp\fR
Same as \fB--help\fR.

.TP
\fBlistaiprofiles\fR
List audio info profiles.

.TP
\fBaiprofileget PROFILE\fR
Display a the given audio info profile.

.TP
\fBsleep TIME\fR
Sleeps for TIME seconds.

.TP
\fBping NUM\fR
Pings the server NUM times. This is done by sending NOOP commands to the server.
The response time as well as as a small statistics section is printed.

This is not supported on all platforms.

.TP
\fBservername\fR
This command shows the server address of the server currently connected to.
This can be different from what has given e.g. in case of special server
names like +fork.

.TP
\fBwhoami\fR
Report client ID of roarctl on the current server.

.TP
\fBstandby\fR, \fBoff\fR, \fBresume\fR, \fBon\fR
Brings the server into standby mode or back into achtive (operating mode).

.TP
\fBstandbymode\fR
Tells if the server is in standby mode or not.

.TP
\fBexit\fR
Quits the server.

.TP
\fBterminate\fR
Terminates the server as soon as all clients disconnected and all streams reaches EOF.


.SH "STREAM COMMANDS"
.TP
\fBvolume STREAMID CHANNELS VOL0 VOL1 VOL2...\fR
Sets the mixing level for a stream with id \fISTREAMID\fR.

\fICHANNELS\fR is the nummber of channels to set volume.
This should be the number of channels of the stream or a symbolic name.
Currently the symbolic names \fBmono\fR and \fBstereo\fR are allowed.
If you use \fBmono\fR all channels will get the level you give as
\fIVOL0\fR. If you use \fBstereo\fR it will try to set the mixing levels
as you are used from stereo setups even if the setup is not in stereo.

The parameters \fIVOL0\fR ... \fIVOLn\fR and the number of them depends
on what you gave as \fICHANNELS\fR. You have to give exactly \fICHANNELS\fR
parameters.

If you give a numerical (not symbolic) value for \fICHANNELS\fR and
the stream does have a different number of channels the behavor is undefined.
In the current implementation only the first \fICHANNELS\fR channels will be updated.
This behavor may change in the future.

.TP
\fBkick TYPE ID\fR
Kicks an object of \fITYPE\fR with id \fIID\fR.
Possible types are: \fBclient stream sample source\fR

You can get the \fIID\fR via \fBlist*\fR (see below).

.TP
\fBnewvirtual P D E R B C\fR
Adds a new virtual (child) stream.
This is used with container formats such as RAUM, Ogg and Matroska.


Parameters:
.RS
.TP
\fBP\fR
Stream ID of \fBP\fRarent stream.
.TP
\fBD\fR
Stream \fBD\fRirection.
.TP
\fBE\fR
Stream cod\fBE\fRc.
.TP
\fBR\fR
Sample \fBR\fRate.
.TP
\fBB\fR
\fBB\fRits per sample.
.TP
\fBC\fR
Number of \fBC\fRhannels.
.RE

.TP
\fBflag ID FLAGS\fR, \fBunflag ID FLAGS\fR, \fBtoogleflag ID FLAGS\fR
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.

.TP
\fBprotectflag ID FLAGS\fR
Protects flags on a stream. ID is the stream id.
FLAGS is a comma separated list of flags.

Protected flags can not be changed anymore after the they got protected.

.SH "META DATA COMMANDS"
.TP
\fBrole ID ROLE\fR
Set stream role ROLE on stream ID.

.TP
\fBmetaget ID TYPE\fR
Read meta date of type TYPE from stream ID.

.TP
\fBmetasave ID FILE\fR
Saves the meta data of stream ID to file FILE.
The Format is one KEY=Value pair per line.
The same format is used by Xiph's tools.

.TP
\fBmetaload ID FILE\fR
Load meta data from file FILE into stream ID. The format is the same
as for \fBmetasave\fR.

.SH "SERVER INFO COMMANDS"
.TP
\fBserverinfo\fR
Gets general information about the server.
This includes software vendor and version.

.TP
\fBservertime\fR
Reports the server's system time.

.TP
\fBserverstandards\fR
Report a list of standards the server supports.

.TP
\fBlibstandards\fR
Similar to serverstandards, reports the list of standard libroar supports.
Same as \fB--list-libstandards\fR.

.TP
\fBserveroinfo\fR
Gets Information about server output.

.TP
\fBserveroinfo2 DIR\fR
Gets Information about server output for a given direction.

.SH "LISTING COMMANDS"
.TP
\fBlistclients\fR
Gets Information about clients.

.TP
\fBclientinfo ID\fR
Gets Information about client ID.

.TP
\fBliststreams\fR
Gets Information about streams.

.TP
\fBstreaminfo ID\fR
Gets Information about stream ID.

.TP
\fBallinfo\fR
Same as "\fBserveroinfo\fR \fBlistclients\fR \fBliststreams\fR".

.SH "ENVIRONMENT VARIABLES"
Below only the basic environment variables are listend.
For a complete list see \fBlibroar\fR(7).

.TP
\fBHOME\fR
The users home directory.

.TP
\fBROAR_SERVER\fR
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.
This is the same as the \fB--server\fR option.

.SH "BUGS"
1) Make the meta data commands api-fixed and list them here.

2) more often check if the user gave us enough arguments.

.SH "SEE ALSO"
\fBroarvorbis\fR(1),
\fBroarfish\fR(1),
\fBroarbaseclients\fR(1),
\fBroartestclients\fR(1),
\fBlibroar\fR(7),
\fBRoarAudio\fR(7).

.SH "HISTORY"

For history information see \fBRoarAudio\fR(7).

.\" ll