aps.1 (5968B)
1 .Dd May 26, 2023 2 .Dt APS 1 3 .Os 4 .Sh NAME 5 .Nm aps 6 .Nd audio player server 7 .Sh SYNOPSIS 8 .Nm aps 9 .Op Ar command 10 .Sh DESCRIPTION 11 The 12 .Nm 13 server maintains a queue of names and manages the player. When the 14 first item is added to the queue, the player is executed with that 15 item as it's final argument, if the player then exits with a status 16 of zero, the player is executed again on the next item in the queue. 17 This loop goes on until the player fails or a command like 18 .Sx stop 19 is issued: the queue is circularly linked. 20 .Pp 21 .Nm 22 listens for clients on a UNIX socket bound to 23 .Pa /tmp/aps 24 (but see 25 .Sx ENVIRONMENT ) . 26 Before entering the main loop, 27 .Nm 28 will 29 .Xr fork 2 30 and execute 31 .Xr apc 1 32 to re-configure the itself. 33 Once 34 .Nm 35 is fully initialized and listening for clients, it will 36 .Xr fork 2 37 and 38 .Xr exit 2 . 39 (Utilizing this, it's easy to know when you can issue commands as 40 shown in the 41 .Sx EXAMPLES . ) 42 .Pp 43 After a client is accepted, 44 .Nm 45 waits for a command (as described in 46 .Sx "Command Syntax" ) 47 to be sent, and, once received, executes responds with it's output 48 and return status, detailed in 49 .Sx Responses . 50 .Pp 51 The available commands, their arguments, and their functions are 52 listed below: 53 .Bl -tag -width indent 54 .It Cm add Op Ar name ... 55 Add the given names to the queue. 56 .It Cm close 57 Prevent new clients from connecting by removing the bound socket 58 and close down the server when all existing clients disconnect. 59 This is equivalent to manually removing the socket with a tool such 60 as 61 .Xr rm 1 . 62 .It Cm commands 63 List all the commands the server supports. 64 .It Cm list Op Ar pattern 65 List items in the queue. If 66 .Ar pattern 67 is present, only list items which match the pattern (see 68 .Sx Patterns ) . 69 .It Cm log 70 Currently does nothing. May be removed in the future. 71 .It Cm next 72 Play the next item in the queue. 73 .It Cm pause 74 Pause the player (by sending 75 .Dv SIGSTOP ) . 76 .It Cm play Op Ar pattern 77 Play the current item (by either spawning a new one, or by sending 78 .Dv SIGCONT 79 if one already exists). If 80 .Ar pattern 81 is given, first seek to the first item 82 .Ar pattern 83 matches. 84 .It Cm player Op Ar player Op Ar argument ... 85 Get or set the player. With no arguments, the current player command 86 is returned, otherwise the player is set to the given arguments. 87 .It Cm previous 88 Play the previous item in the queue. 89 .It Cm remove Op Ar pattern 90 Remove the items matching 91 .Ar pattern 92 from the queue, returning the items removed. If no pattern is 93 given, remove only the current item. 94 .It Cm root Op Ar path 95 Return the current working directory and change it to 96 .Ar path 97 if given. 98 .It Cm seek Ar pattern 99 Seek to the first item which matches 100 .Ar pattern . 101 .It Cm status 102 Return the player status. (See 103 .Sx "Player Status" ) . 104 .It Cm stop 105 Stop the player by sending 106 .Dv SIGTERM . 107 After the signal is sent, the player process may continue to exist, 108 but is ignored. 109 .It Cm terminate 110 Forcefully close down the server giving clients no warning. 111 .It Cm toggle 112 If the player is running, pause it; otherwise play it. The player 113 status is returned on success. (See 114 .Sx "Player Status" ) . 115 .It Cm truncate Op Ar name ... 116 Replace all the items in the queue with the names specified, or, 117 if no names are specified, the current item. 118 .El 119 .Ss Command Syntax 120 Commands are line delimited; command arguments are whitespace 121 separated, but may be quoted as described in 122 .Sx Quoting 123 to include whitespace. 124 .Ss Responses 125 Responses consist of zero or more lines (the command output) followed 126 by a status line. A status line can either be 127 .Sq ok , 128 for successful completion of the command, or 129 .Sq error: 130 followed by an error message if there was an issue. 131 .Pp 132 If a line which would be interpreted as a status line is output by 133 the command, it will be quoted before being sent. (See 134 .Sx Quoting . ) 135 .Pp 136 Multi-word lines are currently possible, but only occur in the 137 player command and may be removed in the future. 138 .Ss Quoting 139 Quoting works as in the 140 .Xr rc 1 141 shell from plan9/9front: Single quotes surround the string. To 142 insert a single quote into the string, put two together. 143 .Ss Patterns 144 There are three types of patterns: numeric, regex, and string. 145 .Pp 146 Numeric patterns begin with a digit or minus. A single number or a 147 comma separated range may be provided. Numbers refer to the offset 148 from the current item, making zero the current item. Ranges are 149 inclusive. 150 .Pp 151 Regular expression patterns begin with a slash 152 .Sq ( "/" ) 153 (forward-searching) or a question mark 154 .Sq ( "?" ) 155 (backward-searching), or an exclamation point 156 .Sq ( "!" ) 157 followed by a slash or question mark to negate the result. The 158 regular expression is extended and ignores case distinctions, 159 additionally, if prefixed 160 .Pp 161 String expressions begin with a double quote 162 .Sq ( \\" ) 163 and only match items which match it exactly. 164 .Ss Player Status 165 The player status can be one of 166 .Bl -tag -width suspended 167 .It off 168 The player is not alive, but will be started when possible. 169 .It running 170 The player is currently running. 171 .It stopped 172 The player is not alive, and will not be started without manual 173 intervention (such as with 174 .Sx play ) . 175 .It suspended 176 The player is alive, but not running; the result of receiving 177 .Dv SIGTSTP 178 or 179 .Dv SIGSTOP . 180 .It failure 181 The player either exited non-zero or terminated abnormally due to 182 a signal. 183 .It complete 184 Like the off status, but indicates that the previous process had 185 an exit status of 0. 186 .El 187 .Sh ENVIRONMENT 188 .Bl -tag -width apsock 189 .It Ev apsock 190 The path to the socket used to connect to 191 .Xr aps 1 . 192 If 193 .Ev apsock 194 is not set, 195 .Pa /tmp/aps 196 is used. 197 .El 198 .Sh EXIT STATUS 199 .Ex -std 200 .Sh EXAMPLES 201 Log to 202 .Pa /tmp/apslog : 203 .Dl $ aps 2>/tmp/apslog 204 .Pp 205 Add items to the queue once 206 .Nm 207 is up and running: 208 .Dl $ aps && apc add foo bar baz 209 .Sh SECURITY CONSIDERATIONS 210 The player can be changed to be any program using the 211 .Sx player 212 command, so anyone with access to the socket can execute an arbitrary 213 program as the server. 214 .Sh SEE ALSO 215 .Xr apc 1 216 .Sh AUTHORS 217 .An Jacob R. Edwards Aq Mt jacob@jacobedwards.org