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
21       instance 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
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

BUGS

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

AUTHORS

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

SEE ALSO

394       audacious(1)
395
396

WEBSITE

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