1AUDTOOL(1) General Commands Manual AUDTOOL(1)
2
3
4
6 audtool - a small tool to control Audacious from the command line.
7
8
10 audtool [instance] command [parameter ...] ...
11
12
14 audtool sends commands to a running instance of Audacious.
15
16 It can send many common commands, such as to skip to the next song in
17 the playlist, and can also print status information, such as the title
18 of the current song.
19
20 instance may be given as -1, -2, etc. (up to -9) to specify which
21 instance of Audacious to control when multiple instances have been
22 started.
23
24
26 Current song information:
27 --current-song
28 Print the formatted title of the current song. Depending on
29 Audacious settings, this may include information such as the
30 artist and album name. To print only the song title, use --cur‐
31 rent-song-tuple-data title instead.
32
33 --current-song-filename
34 Print the file name (full path or URI) of the current song.
35
36 --current-song-length
37 Print the length of the current song in M:SS format.
38
39 --current-song-length-seconds
40 Print the length of the current song in seconds.
41
42 --current-song-length-frames
43 Print the length of the current song in milliseconds.
44
45 --current-song-output-length
46 Print the playback time counter in M:SS format.
47
48 --current-song-output-length-seconds
49 Print the playback time counter in seconds.
50
51 --current-song-output-length-frames
52 Print the playback time counter in milliseconds.
53
54 --current-song-bitrate
55 Print the streaming bitrate in bits per second.
56
57 --current-song-bitrate-kbps
58 Print the streaming bitrate in kilobits per second (1 kilobit =
59 1000 bits).
60
61 --current-song-frequency
62 Print the sampling rate in hertz.
63
64 --current-song-frequency-khz
65 Print the sampling rate in kilohertz.
66
67 --current-song-channels
68 Print the number of audio channels.
69
70 --current-song-tuple-data field
71 Print the value of a named field (artist, year, genre, etc.)
72 for the current song. If the field name is omitted, a list of
73 allowed fields will be printed.
74
75 --current-song-info
76 Print the streaming bitrate, sampling rate, and number of audio
77 channels.
78
79
80 Playback commands:
81 --playback-play
82 Start playback. If paused, playback will resume from the same
83 point. If already active and not paused, it will restart from
84 the beginning of the song.
85
86 --playback-pause
87 Pause playback, or resume if already paused.
88
89 --playback-playpause
90 Equivalent to --playback-pause if playback is active, otherwise
91 --playback-play.
92
93 --playback-stop
94 Stop playback.
95
96 --playback-playing
97 Return an exit code of 0 (true) if playback is active.
98
99 --playback-paused
100 Return an exit code of 0 (true) if playback is paused.
101
102 --playback-stopped
103 Return an exit code of 0 (true) if playback is not active.
104
105 --playback-status
106 Print the playback status (``playing'', ``paused'', or
107 ``stopped'').
108
109 --playback-seek time
110 Seek to the given time in seconds, relative to the beginning of
111 the song.
112
113 --playback-seek-relative time
114 Seek to the given time in seconds, relative to the current time
115 counter.
116
117 --playback-record
118 Toggle recording of the output stream (using FileWriter).
119
120 --playback-recording
121 Return an exit code of 0 (true) if stream recording is enabled.
122
123
124 Playlist selection:
125 --select-displayed
126 Specifies that any subsequent playlist commands should apply to
127 the playlist currently displayed by Audacious, regardless of
128 which playlist is playing. This setting takes effect until it
129 is overridden by --select-playing or Audacious is restarted.
130
131 The following commands are also affected:
132 --current-song
133 --current-song-filename
134 --current-song-length[-seconds,-frames]
135 --current-song-tuple-data
136
137 --select-playing
138 Specifies that when playback is active, any subsequent playlist
139 commands should apply to the playlist currently playing. When
140 playback is stopped, the behavior is the same as --select-dis‐
141 played. This setting is the default.
142
143
144 Playlist commands:
145 --playlist-advance
146 Skip to the next song in the playlist.
147
148 --playlist-reverse
149 Skip to the previous song in the playlist.
150
151 --playlist-addurl path
152 Add a song to end of the playlist. Either a URI or a local file
153 path (absolute or relative) may be given.
154
155 --playlist-insurl path position
156 Insert a song at the given position (one-based) in the playlist.
157
158 --playlist-addurl-to-new-playlist path
159 Add a song to the ``Now Playing'' playlist, creating the
160 playlist if necessary, and begin to play the song. Depending on
161 Audacious settings, the playlist may first be cleared.
162
163 --playlist-delete position
164 Remove the song at the given position from the playlist.
165
166 --playlist-length
167 Print the number of songs in the playlist.
168
169 --playlist-song position
170 Print the formatted title of a song in the playlist.
171
172 --playlist-song-filename position
173 Print the file name (full path or URI) of a song in the
174 playlist.
175
176 --playlist-song-length position
177 Print the length of a song in the playlist in M:SS format.
178
179 --playlist-song-length-seconds position
180 Print the length of a song in the playlist in seconds.
181
182 --playlist-song-length-frames position
183 Print the length of a song in the playlist in milliseconds.
184
185 --playlist-tuple-data field position
186 Print the value of a named field for a song in the playlist.
187
188 --playlist-display
189 Print the titles of all the songs in the playlist.
190
191 --playlist-position
192 Print the position of the current song in the playlist.
193
194 --playlist-jump position
195 Skip to the song at the given position in the playlist.
196
197 --playlist-clear
198 Clear the playlist.
199
200 --playlist-auto-advance-status
201 Print the status of playlist auto-advance (``on'' or ``off'').
202
203 --playlist-auto-advance-toggle
204 Toggle playlist auto-advance.
205
206 --playlist-repeat-status
207 Print the status of playlist repeat (``on'' or ``off'').
208
209 --playlist-repeat-toggle
210 Toggle playlist repeat.
211
212 --playlist-shuffle-status
213 Print the status of playlist shuffle (``on'' or ``off'').
214
215 --playlist-shuffle-toggle
216 Toggle playlist shuffle.
217
218 --playlist-stop-after-status
219 Print the ``stop after current song'' option (``on'' or
220 ``off'').
221
222 --playlist-stop-after-toggle
223 Toggle the ``stop after current song'' option.
224
225
226 More playlist commands:
227 --number-of-playlists
228 Print the number of open playlists.
229
230 --current-playlist
231 Print the number of the current playlist, where "current" is
232 interpreted according to --select-displayed or fB--select-play‐
233 ing.
234
235 --play-current-playlist
236 Start playback in the current playlist, resuming from the last
237 point played if possible. When --select-displayed is in effect,
238 this command can be used to switch playback to the displayed
239 playlist.
240
241 --set-current-playlist playlist
242 Display the given playlist. When --select-playing is in effect
243 and a different playlist is playing, this command will also
244 switch playback to the given playlist. The --select-displayed
245 option disables this behavior.
246
247 --current-playlist-name
248 Print the title of the current playlist.
249
250 --set-current-playlist-name title
251 Set the title of the current playlist.
252
253 --new-playlist
254 Insert a new playlist after the current one and switch to it as
255 if --set-current-playlist were used.
256
257 --delete-current-playlist
258 Remove the current playlist.
259
260
261 Playlist queue commands:
262 --playqueue-add position
263 Add the song at the given playlist position to the queue.
264
265 --playqueue-remove position
266 Remove the song at the given playlist position from the queue.
267
268 --playqueue-is-queued position
269 Return an exit code of 0 (true) if the song at the given
270 playlist position is in the queue.
271
272 --playqueue-get-queue-position position
273 Print the queue position of the song at the given playlist posi‐
274 tion.
275
276 --playqueue-get-list-position position
277 Print the playlist position of the song at the given queue posi‐
278 tion.
279
280 --playqueue-length
281 Print the number of songs in the queue.
282
283 --playqueue-display
284 Print the titles of all the songs in the queue.
285
286 --playqueue-clear
287 Clear the queue.
288
289
290 Volume control and equalizer:
291 --get-volume
292 Print the current volume level in percent.
293
294 --set-volume level
295 Set the current volume level in percent.
296
297 --equalizer-activate [on|off]
298 Activate or deactivate the equalizer.
299
300 --equalizer-get
301 Print the equalizer settings (preamp and gain for all bands) in
302 decibels.
303
304 --equalizer-set preamp band0 band1 band2 band3 band4 band5 band6 band7
305 band8 band9
306 Set the equalizer settings (preamp and gain for all bands) in
307 decibels.
308
309 --equalizer-get-preamp
310 Print the equalizer pre-amplification in decibels.
311
312 --equalizer-set-preamp preamp
313 Set the equalizer pre-amplification in decibels.
314
315 --equalizer-get-band band
316 Print the gain of the given equalizer band (0-9) in decibels.
317
318 --equalizer-set-band band gain
319 Set the gain of the given equalizer band (0-9) in decibels.
320
321
322 Miscellaneous:
323 --mainwin-show [on|off]
324 Show or hide the Audacious window.
325
326 --filebrowser-show [on|off]
327 Show or hide the Add Files window.
328
329 --jumptofile-show [on|off]
330 Show or hide the Jump to Song window.
331
332 --preferences-show [on|off]
333 Show or hide the Settings window.
334
335 --about-show [on|off]
336 Show or hide the About window.
337
338 --version
339 Print version information.
340
341 --plugin-is-enabled plugin
342 Return an exit code of 0 (true) if the given plugin is enabled.
343 The plugin is specified using its installed filename minus the
344 folder path and suffix: for example, crossfade for
345 /usr/lib64/audacious/Effect/crossfade.so.
346
347 --plugin-enable plugin [on|off]
348 Enable or disable the given plugin. Note that interface and
349 output plugins cannot be disabled directly since one of each
350 must always be active. Enabling an interface or output plugin
351 will automatically disable the previous plugin.
352
353 --config-get [section:]name
354 Print the value of a configuration setting. Any use of this
355 command is entirely unsupported. How to find the section and
356 name of a given setting is left as an exercise for the reader.
357
358 --config-set [section:]name value
359 Change the value of a configuration setting. This command is
360 unsupported and dangerous. It might have unexpected side
361 effects (such as crashing Audacious), or it might have no effect
362 at all. Use it at your own risk!
363
364 --shutdown
365 Shut down Audacious.
366
367 --help Print a brief summary of audtool commands.
368
369 Commands may be prefixed with `--' (GNU-style long options) or not,
370 your choice.
371
372
374 There are no known bugs in audtool at this time; if you find any please
375 report them at https://redmine.audacious-media-
376 player.org/projects/audacious.
377
378
380 audtool was written by George Averill <nhjm@nhjm.net> and William Pit‐
381 cock <nenolod@atheme.org>.
382
383 This manual page was written by Adam Cecile <gandalf@le-vert.net> and
384 Kiyoshi Aman <kiyoshi@atheme.org>. Some additional tweaks were done by
385 William Pitcock <nenolod@atheme.org> and Tony Vroon <chainsaw@gen‐
386 too.org>. The manual page was updated for Audacious 3.7 and later by
387 John Lindgren <john@jlindgren.net>.
388
389 This work is licensed under a Creative Commons Attribution 3.0 Unported
390 License <https://creativecommons.org/licenses/by/3.0/>.
391
392
394 audacious(1)
395
396
398 https://audacious-media-player.org
399
400
401
402Version 3.10.1 September 2017 AUDTOOL(1)