1AUDTOOL(1) General Commands Manual AUDTOOL(1)
2
6 audtool - a small tool to control Audacious from the command line.
7
10 audtool [instance] command [parameter ...] ...
11
14 audtool sends commands to a running instance of Audacious.
15 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 instance may be given as -1, -2, etc. (up to -9) to specify which in‐
21 stance of Audacious to control when multiple instances have been
22 started.
23
26 Current song information:
27 --current-song
28 Print the formatted title of the current song. Depending on Au‐
29 dacious 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 --current-song-filename
34 Print the file name (full path or URI) of the current song.
35 --current-song-length
37 Print the length of the current song in M:SS format.
38 --current-song-length-seconds
40 Print the length of the current song in seconds.
41 --current-song-length-frames
43 Print the length of the current song in milliseconds.
44 --current-song-output-length
46 Print the playback time counter in M:SS format.
47 --current-song-output-length-seconds
49 Print the playback time counter in seconds.
50 --current-song-output-length-frames
52 Print the playback time counter in milliseconds.
53 --current-song-bitrate
55 Print the streaming bitrate in bits per second.
56 --current-song-bitrate-kbps
58 Print the streaming bitrate in kilobits per second (1 kilobit =
59 1000 bits).
60 --current-song-frequency
62 Print the sampling rate in hertz.
63 --current-song-frequency-khz
65 Print the sampling rate in kilohertz.
66 --current-song-channels
68 Print the number of audio channels.
69 --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 --current-song-info
76 Print the streaming bitrate, sampling rate, and number of audio
77 channels.
78 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 --playback-pause
87 Pause playback, or resume if already paused.
88 --playback-playpause
90 Equivalent to --playback-pause if playback is active, otherwise
91 --playback-play.
92 --playback-stop
94 Stop playback.
95 --playback-playing
97 Return an exit code of 0 (true) if playback is active.
98 --playback-paused
100 Return an exit code of 0 (true) if playback is paused.
101 --playback-stopped
103 Return an exit code of 0 (true) if playback is not active.
104 --playback-status
106 Print the playback status (``playing'', ``paused'', or
107 ``stopped'').
108 --playback-seek time
110 Seek to the given time in seconds, relative to the beginning of
111 the song.
112 --playback-seek-relative time
114 Seek to the given time in seconds, relative to the current time
115 counter.
116 --playback-record
118 Toggle recording of the output stream (using FileWriter).
119 --playback-recording
121 Return an exit code of 0 (true) if stream recording is enabled.
122 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 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 --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 Playlist commands:
145 --playlist-advance
146 Skip to the next song in the playlist.
147 --playlist-reverse
149 Skip to the previous song in the playlist.
150 --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 --playlist-insurl path position
156 Insert a song at the given position (one-based) in the playlist.
157 --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 --playlist-delete position
164 Remove the song at the given position from the playlist.
165 --playlist-length
167 Print the number of songs in the playlist.
168 --playlist-song position
170 Print the formatted title of a song in the playlist.
171 --playlist-song-filename position
173 Print the file name (full path or URI) of a song in the
174 playlist.
175 --playlist-song-length position
177 Print the length of a song in the playlist in M:SS format.
178 --playlist-song-length-seconds position
180 Print the length of a song in the playlist in seconds.
181 --playlist-song-length-frames position
183 Print the length of a song in the playlist in milliseconds.
184 --playlist-tuple-data field position
186 Print the value of a named field for a song in the playlist.
187 --playlist-display
189 Print the titles of all the songs in the playlist.
190 --playlist-position
192 Print the position of the current song in the playlist.
193 --playlist-jump position
195 Skip to the song at the given position in the playlist.
196 --playlist-clear
198 Clear the playlist.
199 --playlist-auto-advance-status
201 Print the status of playlist auto-advance (``on'' or ``off'').
202 --playlist-auto-advance-toggle
204 Toggle playlist auto-advance.
205 --playlist-repeat-status
207 Print the status of playlist repeat (``on'' or ``off'').
208 --playlist-repeat-toggle
210 Toggle playlist repeat.
211 --playlist-shuffle-status
213 Print the status of playlist shuffle (``on'' or ``off'').
214 --playlist-shuffle-toggle
216 Toggle playlist shuffle.
217 --playlist-stop-after-status
219 Print the ``stop after current song'' option (``on'' or
220 ``off'').
221 --playlist-stop-after-toggle
223 Toggle the ``stop after current song'' option.
224 More playlist commands:
227 --number-of-playlists
228 Print the number of open playlists.
229 --current-playlist
231 Print the number of the current playlist, where "current" is in‐
232 terpreted according to --select-displayed or --select-playing.
233 --play-current-playlist
235 Start playback in the current playlist, resuming from the last
236 point played if possible. When --select-displayed is in effect,
237 this command can be used to switch playback to the displayed
238 playlist.
239 --set-current-playlist playlist
241 Display the given playlist. When --select-playing is in effect
242 and a different playlist is playing, this command will also
243 switch playback to the given playlist. The --select-displayed
244 option disables this behavior.
245 --current-playlist-name
247 Print the title of the current playlist.
248 --set-current-playlist-name title
250 Set the title of the current playlist.
251 --new-playlist
253 Insert a new playlist after the current one and switch to it as
254 if --set-current-playlist were used.
255 --delete-current-playlist
257 Remove the current playlist.
258 Playlist queue commands:
261 --playqueue-add position
262 Add the song at the given playlist position to the queue.
263 --playqueue-remove position
265 Remove the song at the given playlist position from the queue.
266 --playqueue-is-queued position
268 Return an exit code of 0 (true) if the song at the given
269 playlist position is in the queue.
270 --playqueue-get-queue-position position
272 Print the queue position of the song at the given playlist posi‐
273 tion.
274 --playqueue-get-list-position position
276 Print the playlist position of the song at the given queue posi‐
277 tion.
278 --playqueue-length
280 Print the number of songs in the queue.
281 --playqueue-display
283 Print the titles of all the songs in the queue.
284 --playqueue-clear
286 Clear the queue.
287 Volume control and equalizer:
290 --get-volume
291 Print the current volume level in percent.
292 --set-volume level
294 Set the current volume level in percent.
295 --equalizer-activate [on|off]
297 Activate or deactivate the equalizer.
298 --equalizer-get
300 Print the equalizer settings (preamp and gain for all bands) in
301 decibels.
302 --equalizer-set preamp band0 band1 band2 band3 band4 band5 band6 band7
304 band8 band9
305 Set the equalizer settings (preamp and gain for all bands) in
306 decibels.
307 --equalizer-get-preamp
309 Print the equalizer pre-amplification in decibels.
310 --equalizer-set-preamp preamp
312 Set the equalizer pre-amplification in decibels.
313 --equalizer-get-band band
315 Print the gain of the given equalizer band (0-9) in decibels.
316 --equalizer-set-band band gain
318 Set the gain of the given equalizer band (0-9) in decibels.
319 Miscellaneous:
322 --mainwin-show [on|off]
323 Show or hide the Audacious window.
324 --filebrowser-show [on|off]
326 Show or hide the Add Files window.
327 --jumptofile-show [on|off]
329 Show or hide the Jump to Song window.
330 --preferences-show [on|off]
332 Show or hide the Settings window.
333 --about-show [on|off]
335 Show or hide the About window.
336 --version
338 Print version information.
339 --plugin-is-enabled plugin
341 Return an exit code of 0 (true) if the given plugin is enabled.
342 The plugin is specified using its installed filename minus the
343 folder path and suffix: for example, crossfade for
344 /usr/lib64/audacious/Effect/crossfade.so.
345 --plugin-enable plugin [on|off]
347 Enable or disable the given plugin. Note that interface and
348 output plugins cannot be disabled directly since one of each
349 must always be active. Enabling an interface or output plugin
350 will automatically disable the previous plugin.
351 --config-get [section:]name
353 Print the value of a configuration setting. Any use of this
354 command is entirely unsupported. How to find the section and
355 name of a given setting is left as an exercise for the reader.
356 --config-set [section:]name value
358 Change the value of a configuration setting. This command is
359 unsupported and dangerous. It might have unexpected side ef‐
360 fects (such as crashing Audacious), or it might have no effect
361 at all. Use it at your own risk!
362 --shutdown
364 Shut down Audacious.
365 --help Print a brief summary of audtool commands.
367 Commands may be prefixed with `--' (GNU-style long options) or not,
369 your choice.
370
373 There are no known bugs in audtool at this time; if you find any please
374 report them at https://redmine.audacious-media-player.org/projects/au‐
375 dacious.
376
379 audtool was written by George Averill <nhjm@nhjm.net> and Ariadne
380 Conill <ariadne@dereferenced.org>.
381 This manual page was written by Adam Cecile <gandalf@le-vert.net> and
383 Kiyoshi Aman <kiyoshi@atheme.org>. Some additional tweaks were done by
384 Ariadne Conill <ariadne@dereferenced.org> and Tony Vroon <chainsaw@gen‐
385 too.org>. The manual page was updated for Audacious 3.7 and later by
386 John Lindgren <john@jlindgren.net>.
387 This work is licensed under a Creative Commons Attribution 3.0 Unported
389 License <https://creativecommons.org/licenses/by/3.0/>.
390
393 audacious(1)
394
397 https://audacious-media-player.org
398Version 4.3.1 September 2017 AUDTOOL(1)