.TH AUDTOOL "1" "July 2015" "Version 3.7.2" .SH NAME .B audtool - a small tool to control Audacious from the command line. .SH SYNOPSIS .B audtool \fIcommand\fR [\fIparameter\fR ...] ... .SH DESCRIPTION .B audtool sends commands to a running instance of Audacious. .PP 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. .SH COMMANDS .SS Current song information: .TP .B --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 \fB--current-song-tuple-data title\fR instead. .TP .B --current-song-filename Print the file name (full path or URI) of the current song. .TP .B --current-song-length Print the length of the current song in M:SS format. .TP .B --current-song-length-seconds Print the length of the current song in seconds. .TP .B --current-song-length-frames Print the length of the current song in milliseconds. .TP .B --current-song-output-length Print the playback time counter in M:SS format. .TP .B --current-song-output-length-seconds Print the playback time counter in seconds. .TP .B --current-song-output-length-frames Print the playback time counter in milliseconds. .TP .B --current-song-bitrate Print the streaming bitrate in bits per second. .TP .B --current-song-bitrate-kbps Print the streaming bitrate in kilobits per second (1 kilobit = 1000 bits). .TP .B --current-song-frequency Print the sampling rate in hertz. .TP .B --current-song-frequency-khz Print the sampling rate in kilohertz. .TP .B --current-song-channels Print the number of audio channels. .TP .B --current-song-tuple-data \fIfield\fR Print the value of a named field (\fBartist\FR, \fByear\fR, \fBgenre\fR, etc.) for the current song. If the field name is omitted, a list of allowed fields will be printed. .TP .B --current-song-info Print the streaming bitrate, sampling rate, and number of audio channels. .SS Playback commands: .TP .B --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. .TP .B --playback-pause Pause playback, or resume if already paused. .TP .B --playback-playpause Equivalent to \fB--playback-pause\fR if playback is active, otherwise \fB--playback-play\fR. .TP .B --playback-stop Stop playback. .TP .B --playback-playing Return an exit code of 0 (true) if playback is active. .TP .B --playback-paused Return an exit code of 0 (true) if playback is paused. .TP .B --playback-stopped Return an exit code of 0 (true) if playback is not active. .TP .B --playback-status Print the playback status (``playing'', ``paused'', or ``stopped''). .TP .B --playback-seek \fItime\fR Seek to the given time in seconds, relative to the beginning of the song. .TP .B --playback-seek-relative \fItime\fR Seek to the given time in seconds, relative to the current time counter. .SS Playlist commands: .TP .B --playlist-advance Skip to the next song in the playlist. .TP .B --playlist-reverse Skip to the previous song in the playlist. .TP .B --playlist-addurl \fIpath\fR Add a song to end of the playlist. Either a URI or a local file path (absolute or relative) may be given. .TP .B --playlist-insurl \fIpath\fR \fIposition\fR Insert a song at the given position (one-based) in the playlist. .TP .B --playlist-addurl-to-new-playlist \fIpath\fR 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. .TP .B --playlist-delete \fIposition\fR Remove the song at the given position from the playlist. .TP .B --playlist-length Print the number of songs in the playlist. .TP .B --playlist-song \fIposition\fR Print the formatted title of a song in the playlist. .TP .B --playlist-song-filename \fIposition\fR Print the file name (full path or URI) of a song in the playlist. .TP .B --playlist-song-length \fIposition\fR Print the length of a song in the playlist in M:SS format. .TP .B --playlist-song-length-seconds \fIposition\fR Print the length of a song in the playlist in seconds. .TP .B --playlist-song-length-frames \fIposition\fR Print the length of a song in the playlist in milliseconds. .TP .B --playlist-tuple-data \fIfield\fR \fIposition\fR Print the value of a named field for a song in the playlist. .TP .B --playlist-display Print the titles of all the songs in the playlist. .TP .B --playlist-position Print the position of the current song in the playlist. .TP .B --playlist-jump \fIposition\fR Skip to the song at the given position in the playlist. .TP .B --playlist-clear Clear the playlist. .TP .B --playlist-auto-advance-status Print the status of playlist auto-advance (``on'' or ``off''). .TP .B --playlist-auto-advance-toggle Toggle playlist auto-advance. .TP .B --playlist-repeat-status Print the status of playlist repeat (``on'' or ``off''). .TP .B --playlist-repeat-toggle Toggle playlist repeat. .TP .B --playlist-shuffle-status Print the status of playlist shuffle (``on'' or ``off''). .TP .B --playlist-shuffle-toggle Toggle playlist shuffle. .TP .B --playlist-stop-after-status Print the ``stop after current song'' option (``on'' or ``off''). .TP .B --playlist-stop-after-toggle Toggle the ``stop after current song'' option. .SS More playlist commands: .TP .B --number-of-playlists Print the number of open playlists. .TP .B --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. .TP .B --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. .TP .B --set-current-playlist \fIplaylist\fR 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. .TP .B --current-playlist-name Print the title of the current playlist. .TP .B --set-current-playlist-name \fItitle\fR Set the title of the current playlist. .TP .B --new-playlist Insert a new playlist after the current one and switch to it as if \fB--set-current-playlist\fR were used. .TP .B --delete-current-playlist Remove the current playlist. Playback, if active, will be stopped. .SS Playlist queue commands: .TP .B --playqueue-add \fIposition\fR Add the song at the given playlist position to the queue. .TP .B --playqueue-remove \fIposition\fR Remove the song at the given playlist position from the queue. .TP .B --playqueue-is-queued \fIposition\fR Return an exit code of 0 (true) if the song at the given playlist position is in the queue. .TP .B --playqueue-get-queue-position \fIposition\fR Print the queue position of the song at the given playlist position. .TP .B --playqueue-get-list-position \fIposition\fR Print the playlist position of the song at the given queue position. .TP .B --playqueue-length Print the number of songs in the queue. .TP .B --playqueue-display Print the titles of all the songs in the queue. .TP .B --playqueue-clear Clear the queue. .SS Volume control and equalizer: .TP .B --get-volume Print the current volume level in percent. .TP .B --set-volume \fIlevel\fR Set the current volume level in percent. .TP .B --equalizer-activate [on|off] Activate or deactivate the equalizer. .TP .B --equalizer-get Print the equalizer settings (preamp and gain for all bands) in decibels. .TP .B --equalizer-set \fIpreamp\fR \fIband0\fR \fIband1\fR \fIband2\fR \fIband3\fR \fIband4\fR \fIband5\fR \fIband6\fR \fIband7\fR \fIband8\fR \fIband9\fR Set the equalizer settings (preamp and gain for all bands) in decibels. .TP .B --equalizer-get-preamp Print the equalizer pre-amplification in decibels. .TP .B --equalizer-set-preamp \fIpreamp\fR Set the equalizer pre-amplification in decibels. .TP .B --equalizer-get-band \fIband\fR Print the gain of the given equalizer band (0-9) in decibels. .TP .B --equalizer-set-band \fIband\fR \fIgain\fR Set the gain of the given equalizer band (0-9) in decibels. .SS Miscellaneous: .TP .B --mainwin-show [on|off] Show or hide the Audacious window. .TP .B --filebrowser-show [on|off] Show or hide the Add Files window. .TP .B --jumptofile-show [on|off] Show or hide the Jump to Song window. .TP .B --preferences-show [on|off] Show or hide the Settings window. .TP .B --about-show [on|off] Show or hide the About window. .TP .B --version Print version information. .TP .B --shutdown Shut down Audacious. .TP .B --help Print a brief summary of audtool commands. .PP Commands may be prefixed with `--' (GNU-style long options) or not, your choice. .SH BUGS There are no known bugs in audtool at this time; if you find any please report them at \fIhttp://redmine.audacious-media-player.org/projects/audacious\fR. .SH AUTHORS .B audtool was written by George Averill and William Pitcock . .PP This manual page was written by Adam Cecile and Kiyoshi Aman . Some additional tweaks were done by William Pitcock and Tony Vroon . The manual page was updated for Audacious 3.7 by John Lindgren . .PP This work is licensed under a Creative Commons Attribution 3.0 Unported License . .SH "SEE ALSO" .BR audacious (1) .SH WEBSITE .I http://audacious-media-player.org