Manual Page Search Parameters
APS(1) General Commands Manual APS(1)

aps — audio player server

aps [command]

The aps server maintains a queue of names and manages the player. When the first item is added to the queue, the player is executed with that item as it's final argument, if the player then exits with a status of zero, the player is executed again on the next item in the queue. This loop goes on until the player fails or a command like stop is issued: the queue is circularly linked.

aps listens for clients on a UNIX socket bound to /tmp/aps (but see ENVIRONMENT). Before entering the main loop, aps will fork(2) and execute apc(1) to re-configure the itself. Once aps is fully initialized and listening for clients, it will fork(2) and exit(2). (Utilizing this, it's easy to know when you can issue commands as shown in the EXAMPLES.)

After a client is accepted, aps waits for a command (as described in Command Syntax) to be sent, and, once received, executes responds with it's output and return status, detailed in Responses.

The available commands, their arguments, and their functions are listed below:

[name ...]
Add the given names to the queue.
Prevent new clients from connecting by removing the bound socket and close down the server when all existing clients disconnect. This is equivalent to manually removing the socket with a tool such as rm(1).
List all the commands the server supports.
[pattern]
List items in the queue. If pattern is present, only list items which match the pattern (see Patterns).
Currently does nothing. May be removed in the future.
Play the next item in the queue.
Pause the player (by sending SIGSTOP).
[pattern]
Play the current item (by either spawning a new one, or by sending SIGCONT if one already exists). If pattern is given, first seek to the first item pattern matches.
[player [argument ...]]
Get or set the player. With no arguments, the current player command is returned, otherwise the player is set to the given arguments.
Play the previous item in the queue.
[pattern]
Remove the items matching pattern from the queue, returning the items removed. If no pattern is given, remove only the current item.
[path]
Return the current working directory and change it to path if given.
pattern
Seek to the first item which matches pattern.
Return the player status. (See Player Status).
Stop the player by sending SIGTERM. After the signal is sent, the player process may continue to exist, but is ignored.
Forcefully close down the server giving clients no warning.
If the player is running, pause it; otherwise play it. The player status is returned on success. (See Player Status).
[name ...]
Replace all the items in the queue with the names specified, or, if no names are specified, the current item.

Commands are line delimited; command arguments are whitespace separated, but may be quoted as described in Quoting to include whitespace.

Responses consist of zero or more lines (the command output) followed by a status line. A status line can either be ‘ok’, for successful completion of the command, or ‘error:’ followed by an error message if there was an issue.

If a line which would be interpreted as a status line is output by the command, it will be quoted before being sent. (See Quoting.)

Multi-word lines are currently possible, but only occur in the player command and may be removed in the future.

Quoting works as in the rc(1) shell from plan9/9front: Single quotes surround the string. To insert a single quote into the string, put two together.

There are three types of patterns: numeric, regex, and string.

Numeric patterns begin with a digit or minus. A single number or a comma separated range may be provided. Numbers refer to the offset from the current item, making zero the current item. Ranges are inclusive.

Regular expression patterns begin with a slash (‘/’) (forward-searching) or a question mark (‘?’) (backward-searching), or an exclamation point (‘!’) followed by a slash or question mark to negate the result. The regular expression is extended and ignores case distinctions, additionally, if prefixed

String expressions begin with a double quote (‘’) and only match items which match it exactly.

The player status can be one of

off
The player is not alive, but will be started when possible.
running
The player is currently running.
stopped
The player is not alive, and will not be started without manual intervention (such as with play).
suspended
The player is alive, but not running; the result of receiving SIGTSTP or SIGSTOP.
failure
The player either exited non-zero or terminated abnormally due to a signal.
complete
Like the off status, but indicates that the previous process had an exit status of 0.

The path to the socket used to connect to aps(1). If apsock is not set, /tmp/aps is used.

The aps utility exits 0 on success, and >0 if an error occurs.

Log to /tmp/apslog:

$ aps 2>/tmp/apslog

Add items to the queue once aps is up and running:

$ aps && apc add foo bar baz

The player can be changed to be any program using the player command, so anyone with access to the socket can execute an arbitrary program as the server.

apc(1)

Jacob R. Edwards <jacob@jacobedwards.org>

May 26, 2023 jacob