1AUDTOOL(1)                  General Commands Manual                 AUDTOOL(1)
2
3
4

NAME

6       audtool - a small tool to control Audacious from the command line.
7
8

SYNOPSIS

10       audtool [instance] command [parameter ...] ...
11
12

DESCRIPTION

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 in‐
21       stance of Audacious  to  control  when  multiple  instances  have  been
22       started.
23
24

COMMANDS

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
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 in‐
232              terpreted according to --select-displayed or --select-playing.
233
234       --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
240       --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
246       --current-playlist-name
247              Print the title of the current playlist.
248
249       --set-current-playlist-name title
250              Set the title of the current playlist.
251
252       --new-playlist
253              Insert a new playlist after the current one and switch to it  as
254              if --set-current-playlist were used.
255
256       --delete-current-playlist
257              Remove the current playlist.
258
259
260   Playlist queue commands:
261       --playqueue-add position
262              Add the song at the given playlist position to the queue.
263
264       --playqueue-remove position
265              Remove the song at the given playlist position from the queue.
266
267       --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
271       --playqueue-get-queue-position position
272              Print the queue position of the song at the given playlist posi‐
273              tion.
274
275       --playqueue-get-list-position position
276              Print the playlist position of the song at the given queue posi‐
277              tion.
278
279       --playqueue-length
280              Print the number of songs in the queue.
281
282       --playqueue-display
283              Print the titles of all the songs in the queue.
284
285       --playqueue-clear
286              Clear the queue.
287
288
289   Volume control and equalizer:
290       --get-volume
291              Print the current volume level in percent.
292
293       --set-volume level
294              Set the current volume level in percent.
295
296       --equalizer-activate [on|off]
297              Activate or deactivate the equalizer.
298
299       --equalizer-get
300              Print the equalizer settings (preamp and gain for all bands)  in
301              decibels.
302
303       --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
308       --equalizer-get-preamp
309              Print the equalizer pre-amplification in decibels.
310
311       --equalizer-set-preamp preamp
312              Set the equalizer pre-amplification in decibels.
313
314       --equalizer-get-band band
315              Print the gain of the given equalizer band (0-9) in decibels.
316
317       --equalizer-set-band band gain
318              Set the gain of the given equalizer band (0-9) in decibels.
319
320
321   Miscellaneous:
322       --mainwin-show [on|off]
323              Show or hide the Audacious window.
324
325       --filebrowser-show [on|off]
326              Show or hide the Add Files window.
327
328       --jumptofile-show [on|off]
329              Show or hide the Jump to Song window.
330
331       --preferences-show [on|off]
332              Show or hide the Settings window.
333
334       --about-show [on|off]
335              Show or hide the About window.
336
337       --version
338              Print version information.
339
340       --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
346       --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
352       --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
357       --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
363       --shutdown
364              Shut down Audacious.
365
366       --help Print a brief summary of audtool commands.
367
368       Commands may be prefixed with `--' (GNU-style  long  options)  or  not,
369       your choice.
370
371

BUGS

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
377

AUTHORS

379       audtool  was  written  by  George  Averill  <nhjm@nhjm.net> and Ariadne
380       Conill <ariadne@dereferenced.org>.
381
382       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
388       This work is licensed under a Creative Commons Attribution 3.0 Unported
389       License <https://creativecommons.org/licenses/by/3.0/>.
390
391

SEE ALSO

393       audacious(1)
394
395

WEBSITE

397       https://audacious-media-player.org
398
399
400
401Version 4.3.1                   September 2017                      AUDTOOL(1)
Impressum