AUDTOOL(1)

📦
version 4.6.2 · 9 versions
, in arch rolling, nixpkgs unstable

🎀 AUDTOOL(1) 🎀

okay so this is straight out of your General Commands Manual bestie, and it's the whole audtool(1) page, served fresh 💅

✨ NAME ✨

audtool — a small tool to control Audacious from the command line. that's it, that's the vibe. it's your lil terminal remote control for your music player 🫶

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

so audtool sends commands to a running instance of Audacious. like, it's talking to the app that's already open, not opening its own lil music world 💖

it can send so many common commands, like skipping to the next song in the playlist, and it can also print status info, like the title of the current song. literally your own personal status-report bestie ✨

instance can be given as -1, -2, etc. (up to -9) to specify which instance of Audacious to control when multiple instances have been started. so if you've got like nine Audaciouses open (iconic behavior tbh 👑), you can pick which one gets the message.

💜 COMMANDS 💜

🍓 Current song information:

  • --current-song — prints the formatted title of the current song. depending on your Audacious settings, this may include stuff like the artist and album name. and if you want only the song title? use --current-song-tuple-data title instead. iykyk 😌
  • --current-song-filename — prints the file name (full path or URI) of the current song.
  • --current-song-length — prints the length of the current song in M:SS format.
  • --current-song-length-seconds — prints the length of the current song in seconds.
  • --current-song-length-frames — prints the length of the current song in milliseconds.
  • --current-song-output-length — prints the playback time counter in M:SS format.
  • --current-song-output-length-seconds — prints the playback time counter in seconds.
  • --current-song-output-length-frames — prints the playback time counter in milliseconds.
  • --current-song-bitrate — prints the streaming bitrate in bits per second.
  • --current-song-bitrate-kbps — prints the streaming bitrate in kilobits per second (1 kilobit = 1000 bits). math bestie 🧮
  • --current-song-frequency — prints the sampling rate in hertz.
  • --current-song-frequency-khz — prints the sampling rate in kilohertz.
  • --current-song-channels — prints the number of audio channels.
  • --current-song-tuple-data field — prints the value of a named field (artist, year, genre, etc.) for the current song. and if you just leave the field name off entirely? it'll print you a list of the allowed fields. thoughtful queen ✨
  • --current-song-info — prints the streaming bitrate, sampling rate, and number of audio channels. all the stats in one go, we love a bundle 🎀

💀 Playback commands:

  • --playback-play — start playback. if paused, playback will resume from the same point. if it's already active and not paused, it will restart from the beginning of the song. heads up, that second one is a real "wait no—" moment 😭
  • --playback-pause — pause playback, or resume if already paused. toggle queen 💅
  • --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 — prints the playback status ('playing', 'paused', or 'stopped'). three moods, one command 🌈
  • --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. so like, it sticks around 👑

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. the main character of the two, fr fr 💖

🌟 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. come one, come all 🎶
  • --playlist-insurl path position — insert a song at the given position (one-based) in the playlist. yes bestie, one-based, count like a human 💅
  • --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. so like, don't be shocked if your old queue ghosts you 🙈
  • --playlist-delete position — remove the song at the given position from the playlist.
  • --playlist-length — prints the number of songs in the playlist.
  • --playlist-song position — prints the formatted title of a song in the playlist.
  • --playlist-song-filename position — prints the file name (full path or URI) of a song in the playlist.
  • --playlist-song-length position — prints the length of a song in the playlist in M:SS format.
  • --playlist-song-length-seconds position — prints the length of a song in the playlist in seconds.
  • --playlist-song-length-frames position — prints the length of a song in the playlist in milliseconds.
  • --playlist-tuple-data field position — prints the value of a named field for a song in the playlist. pick your field, pick your song 🎀
  • --playlist-display — prints the titles of all the songs in the playlist. the whole roster, exposed ✨
  • --playlist-position — prints the position of the current song in the playlist.
  • --playlist-jump position — skip to the song at the given position in the playlist. teleportation but make it music 🦋
  • --playlist-clear — clear the playlist. ruthless. iconic. ✨
  • --playlist-auto-advance-status — prints the status of playlist auto-advance ('on' or 'off').
  • --playlist-auto-advance-toggle — toggle playlist auto-advance.
  • --playlist-repeat-status — prints the status of playlist repeat ('on' or 'off').
  • --playlist-repeat-toggle — toggle playlist repeat. for the girls who listen to the same song forty times 🎧
  • --playlist-shuffle-status — prints the status of playlist shuffle ('on' or 'off').
  • --playlist-shuffle-toggle — toggle playlist shuffle.
  • --playlist-stop-after-status — prints the 'stop after current song' option ('on' or 'off').
  • --playlist-stop-after-toggle — toggle the 'stop after current song' option.
  • --playlist-save path — save the playlist to the given file path. the format is determined by the file extension. so like, name your file thoughtfully bestie, that extension is doing real work 💅

🔥 More playlist commands:

  • --number-of-playlists — prints the number of open playlists.
  • --current-playlist — prints the number of the current playlist, where "current" is interpreted according to --select-displayed or --select-playing. it's giving context-dependent 💀
  • --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. cute little switcheroo 🫶
  • --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. so heads up, the two flags interact 👀
  • --current-playlist-name — prints the title of the current playlist.
  • --set-current-playlist-name title — set the title of the current playlist. name your playlist something unhinged, i believe in you 💜
  • --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 — prints the queue position of the song at the given playlist position.
  • --playqueue-get-list-position position — prints the playlist position of the song at the given queue position. yes it's the reverse of the one above, no you're not buggin 🫠
  • --playqueue-length — prints the number of songs in the queue.
  • --playqueue-display — prints the titles of all the songs in the queue.
  • --playqueue-clear — clear the queue. bye bestie 👋

🎀 Volume control and equalizer:

  • --get-volume — prints 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 — prints 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. that's a whole lotta numbers, stay strong 💪
--equalizer-set preamp band0 band1 band2 band3 band4 band5 band6 band7
band8 band9
  • --equalizer-get-preamp — prints the equalizer pre-amplification in decibels.
  • --equalizer-set-preamp preamp — set the equalizer pre-amplification in decibels.
  • --equalizer-get-band band — prints 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. gotta know what you're working with ✨
  • --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 lib/audacious/Effect/crossfade.so. so like, strip the path and the .so and you're golden 🧚

okay so the command list keeps going, bestie — these last ones are the handle-with-care / housekeeping girlies, and they’re lowkey important. 💅

  • --plugin-enable plugin [on|off] — turns the given plugin on or off. Heads up: interface and output plugins cannot be disabled directly, because one of each must always be active. Enabling an interface or output plugin will automatically disable the previous plugin. Slay, but respect the rules. 💖
  • --config-get [section:]name — prints the value of a configuration setting. Warning bestie: 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. 😭 good luck, iykyk.
  • --config-set [section:]name value — changes 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 — shuts down Audacious. bye-bye, main character. 👋
  • --help — prints a brief summary of audtool commands. the little cheat sheet we all need. ✨

also, commands may be prefixed with -- (GNU-style long options) or not — your choice, bestie. no cap.

🐛 BUGS 🐛

There are no known bugs in audtool at this time; if you find any please report them at https://github.com/audacious-media-player/audacious/issues. not me being a snitch, but the maintainers wanna know fr fr 🦋

💖 AUTHORS 💖

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

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/. periodt. 🎀

👀 SEE ALSO 👀

audacious(1) — go check on her, she’s the whole reason this little tool exists. 🌸

🌐 WEBSITE 🌐

https://audacious-media-player.org — come thru, bestie. 💻✨

mwah 💋 this page is rocking Version 4.6.2, dated September 2017, and it’s the AUDTOOL(1) manual — catch you in the group chat, bestie 🫶🌈

📦 where this page comes from