AUDTOOL(1)

NAME
audtool - a small tool to control Audacious from the command line.

SYNOPSIS
audtool [instance] command [parameter ...] ...

DESCRIPTION
audtool sends commands to a running instance of Audacious.

It can send many common commands, such as to skip to the next song in the playlist, and can also print status information, such as the title of the current song.

instance may be given as -1, -2, etc. (up to -9) to specify which instance of Audacious to control when multiple instances have been started.

COMMANDS

  Current song information:

--current-song
    Print the formatted title of the current song. Depending on Audacious settings, this may include information such as the artist and album name. To print only the song title, use --current-song-tuple-data title instead.

--current-song-filename
    Print the file name (full path or URI) of the current song.

--current-song-length
    Print the length of the current song in M:SS format.

--current-song-length-seconds
    Print the length of the current song in seconds.

--current-song-length-frames
    Print the length of the current song in milliseconds.

--current-song-output-length
    Print the playback time counter in M:SS format.

--current-song-output-length-seconds
    Print the playback time counter in seconds.

--current-song-output-length-frames
    Print the playback time counter in milliseconds.

--current-song-bitrate
    Print the streaming bitrate in bits per second.

--current-song-bitrate-kbps
    Print the streaming bitrate in kilobits per second (1 kilobit = 1000 bits).

--current-song-frequency
    Print the sampling rate in hertz.

--current-song-frequency-khz
    Print the sampling rate in kilohertz.

--current-song-channels
    Print the number of audio channels.

--current-song-tuple-data field
    Print the value of a named field (artist, year, genre, etc.) for the current song. If the field name is omitted, a list of allowed fields will be printed.

--current-song-info
    Print the streaming bitrate, sampling rate, and number of audio channels.

  Playback commands:

--playback-play
    Start playback. If paused, playback will resume from the same point. If already active and not paused, it will restart from the beginning of the song.

--playback-pause
    Pause playback, or resume if already paused.

--playback-playpause
    Equivalent to --playback-pause if playback is active, otherwise --playback-play.

--playback-stop
    Stop playback.

--playback-playing
    Return an exit code of 0 (true) if playback is active.

--playback-paused
    Return an exit code of 0 (true) if playback is paused.

--playback-stopped
    Return an exit code of 0 (true) if playback is not active.

--playback-status
    Print the playback status (``playing'', ``paused'', or ``stopped'').

--playback-seek time
    Seek to the given time in seconds, relative to the beginning of the song.

--playback-seek-relative time
    Seek to the given time in seconds, relative to the current time counter.

--playback-record
    Toggle recording of the output stream (using FileWriter).

--playback-recording
    Return an exit code of 0 (true) if stream recording is enabled.

  Playlist selection:

--select-displayed
    Specifies that any subsequent playlist commands should apply to the playlist currently displayed by Audacious, regardless of which playlist is playing. This setting takes effect until it is overridden by --select-playing or Audacious is restarted. The following commands are also affected:
        --current-song
        --current-song-filename
        --current-song-length[-seconds,-frames]
        --current-song-tuple-data

--select-playing
    Specifies that when playback is active, any subsequent playlist commands should apply to the playlist currently playing. When playback is stopped, the behavior is the same as --select-displayed. This setting is the default.

  Playlist commands:

--playlist-advance
    Skip to the next song in the playlist.

--playlist-reverse
    Skip to the previous song in the playlist.

--playlist-addurl path
    Add a song to end of the playlist. Either a URI or a local file path (absolute or relative) may be given.

--playlist-insurl path position
    Insert a song at the given position (one-based) in the playlist.

--playlist-addurl-to-new-playlist path
    Add a song to the ``Now Playing'' playlist, creating the playlist if necessary, and begin to play the song. Depending on Audacious settings, the playlist may first be cleared.

--playlist-delete position
    Remove the song at the given position from the playlist.

--playlist-length
    Print the number of songs in the playlist.

--playlist-song position
    Print the formatted title of a song in the playlist.

--playlist-song-filename position
    Print the file name (full path or URI) of a song in the playlist.

--playlist-song-length position
    Print the length of a song in the playlist in M:SS format.

--playlist-song-length-seconds position
    Print the length of a song in the playlist in seconds.

--playlist-song-length-frames position
    Print the length of a song in the playlist in milliseconds.

--playlist-tuple-data field position
    Print the value of a named field for a song in the playlist.

--playlist-display
    Print the titles of all the songs in the playlist.

--playlist-position
    Print the position of the current song in the playlist.

--playlist-jump position
    Skip to the song at the given position in the playlist.

--playlist-clear
    Clear the playlist.

--playlist-auto-advance-status
    Print the status of playlist auto-advance (``on'' or ``off'').

--playlist-auto-advance-toggle
    Toggle playlist auto-advance.

--playlist-repeat-status
    Print the status of playlist repeat (``on'' or ``off'').

--playlist-repeat-toggle
    Toggle playlist repeat.

--playlist-shuffle-status
    Print the status of playlist shuffle (``on'' or ``off'').

--playlist-shuffle-toggle
    Toggle playlist shuffle.

--playlist-stop-after-status
    Print the ``stop after current song'' option (``on'' or ``off'').

--playlist-stop-after-toggle
    Toggle the ``stop after current song'' option.

  More playlist commands:

--number-of-playlists
    Print the number of open playlists.

--current-playlist
    Print the number of the current playlist, where "current" is interpreted according to --select-displayed or --select-playing.

--play-current-playlist
    Start playback in the current playlist, resuming from the last point played if possible. When --select-displayed is in effect, this command can be used to switch playback to the displayed playlist.

--set-current-playlist playlist
    Display the given playlist. When --select-playing is in effect and a different playlist is playing, this command will also switch playback to the given playlist. The --select-displayed option disables this behavior.

--current-playlist-name
    Print the title of the current playlist.

--set-current-playlist-name title
    Set the title of the current playlist.

--new-playlist
    Insert a new playlist after the current one and switch to it as if --set-current-playlist were used.

--delete-current-playlist
    Remove the current playlist.

  Playlist queue commands:

--playqueue-add position
    Add the song at the given playlist position to the queue.

--playqueue-remove position
    Remove the song at the given playlist position from the queue.

--playqueue-is-queued position
    Return an exit code of 0 (true) if the song at the given playlist position is in the queue.

--playqueue-get-queue-position position
    Print the queue position of the song at the given playlist position.

--playqueue-get-list-position position
    Print the playlist position of the song at the given queue position.

--playqueue-length
    Print the number of songs in the queue.

--playqueue-display
    Print the titles of all the songs in the queue.

--playqueue-clear
    Clear the queue.

  Volume control and equalizer:

--get-volume
    Print the current volume level in percent.

--set-volume level
    Set the current volume level in percent.

--equalizer-activate [on|off]
    Activate or deactivate the equalizer.

--equalizer-get
    Print the equalizer settings (preamp and gain for all bands) in decibels.

--equalizer-set preamp band0 band1 band2 band3 band4 band5 band6 band7 band8 band9
    Set the equalizer settings (preamp and gain for all bands) in decibels.

--equalizer-get-preamp
    Print the equalizer pre-amplification in decibels.

--equalizer-set-preamp preamp
    Set the equalizer pre-amplification in decibels.

--equalizer-get-band band
    Print the gain of the given equalizer band (0-9) in decibels.

--equalizer-set-band band gain
    Set the gain of the given equalizer band (0-9) in decibels.

  Miscellaneous:

--mainwin-show [on|off]
    Show or hide the Audacious window.

--filebrowser-show [on|off]
    Show or hide the Add Files window.

--jumptofile-show [on|off]
    Show or hide the Jump to Song window.

--preferences-show [on|off]
    Show or hide the Settings window.

--about-show [on|off]
    Show or hide the About window.

--version
    Print version information.

--plugin-is-enabled plugin
    Return an exit code of 0 (true) if the given plugin is enabled. The plugin is specified using its installed filename minus the folder path and suffix: for example, crossfade for /usr/lib/audacious/Effect/crossfade.so.

--plugin-enable plugin [on|off]
    Enable or disable the given plugin. Note that interface and output plugins cannot be disabled directly since one of each must always be active. Enabling an interface or output plugin will automatically disable the previous plugin.

--config-get [section:]name
    Print the value of a configuration setting. Any use of this command is entirely unsupported. How to find the section and name of a given setting is left as an exercise for the reader.

--config-set [section:]name value
    Change the value of a configuration setting. This command is unsupported and dangerous. It might have unexpected side effects (such as crashing Audacious), or it might have no effect at all. Use it at your own risk!

--shutdown
    Shut down Audacious.

--help
    Print a brief summary of audtool commands.

Commands may be prefixed with `--' (GNU-style long options) or not, your choice.

BUGS
There are no known bugs in audtool at this time; if you find any please report them at https://redmine.audacious-media-player.org/projects/audacious.

AUTHORS
audtool was written by George Averill <nhjm@nhjm.net> and Ariadne Conill <ariadne@dereferenced.org>.

This manual page was written by Adam Cecile <gandalf@le-vert.net> and Kiyoshi Aman <kiyoshi@atheme.org>. Some additional tweaks were done by Ariadne Conill <ariadne@dereferenced.org> and Tony Vroon <chainsaw@gentoo.org>. The manual page was updated for Audacious 3.7 and later by John Lindgren <john@jlindgren.net>.

This work is licensed under a Creative Commons Attribution 3.0 Unported License <https://creativecommons.org/licenses/by/3.0/>.

SEE ALSO
audacious(1)

WEBSITE
https://audacious-media-player.org