audtool man page

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 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.  When a song is playing, the current playlist is defined as the playlist containing that song.  Otherwise, it is the playlist currently displayed in Audacious.

--play-current-playlist

Start playback.  If paused or previously stopped in the middle of a song, playback will resume from the last point played.  There is no effect if playback is already active and not paused.

--set-current-playlist playlist

Switch to the given playlist.  If another playlist is playing, playback will switch to this one, resuming from the last point played.  If playback is currently paused, it will remain so after the switch.

--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.  Playback, if active, will be stopped.

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/lib64/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.

--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 http://redmine.audacious-media-player.org/projects/audacious.

Authors

audtool was written by George Averill <nhjm@nhjm.net> and William Pitcock <nenolod@atheme.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 William Pitcock <nenolod@atheme.org> and Tony Vroon <chainsaw@gentoo.org>.  The manual page was updated for Audacious 3.7 by John Lindgren <john.lindgren@aol.com>.

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

See Also

audacious(1)

Website

http://audacious-media-player.org

Referenced By

audacious(1).

May 2016 Version 3.8.2