AQUALUNG(1)

📦 version 2.0, in fedora 43, fedora 44

✨ aqualung ✨

the manual page for aqualung — Music player for GNU/Linux 💖

okay bestie, buckle up, this one's a whole vibe and there's a LOT to cover 🎀

🌸 NAME 🌸

aqualung — a music player for GNU/Linux. that's it, that's the name, short and iconic 💅

🦋 SYNOPSIS 🦋

lowkey there's three ways to roll up on this thing:

aqualung --help
aqualung --version
aqualung [--output (jack|pulse|alsa|oss|sndio|win32)] [options] [file1 [file2 ...]]

so like, you can just ask for help, ask for the version, or full send it with an output driver, some options, and a whole pile of files 💜

👑 DESCRIPTION 👑

so Aqualung is an advanced music player that was originally targeted at the GNU/Linux operating system, and today it's also running on FreeBSD, OpenBSD and Microsoft Windows. periodt. 🌈

she plays audio CDs, internet radio streams and podcasts, <em>plus</em> soundfiles in just about any audio format you can throw at her — and the moment that makes her truly special? no gaps between adjacent tracks. none. zero. gapless queen behavior 👑✨ She also supports high quality sample rate conversion between the file and the output device, whenever that's needed. 💫

Audio CDs can be played back <em>and</em> ripped with on-the-fly conversion to WAV, FLAC, Ogg Vorbis or CBR/VBR MP3 (gapless via LAME). Seamless tagging of the created files is offered as part of the process — like, she does it all in one go, no cap. Internet radio stations streaming Ogg Vorbis or MP3 are supported. Subscribing to RSS and Atom audio podcasts is supported too: Aqualung can automatically download and add new files to the Music Store. And you can optionally set limits for the age, size and number of downloaded files if you want to keep things contained 🎀

Almost all sample-based, uncompressed formats (e.g. WAV, AIFF, AU etc.), as well as files encoded with FLAC (the Free Lossless Audio Codec), Ogg Vorbis, Ogg Speex, MPEG Audio (including the infamous MP3 format), MOD audio formats (MOD, S3M, XM, IT, etc.), Musepack and Monkey's Audio Codec are supported. Numerous formats and codecs are also supported via the FFmpeg project, including AC3, AAC, WMA, WavPack and the soundtrack of many video formats. There's also a native (non-FFmpeg) WavPack decoder, which is a fun little flex 🫶

The program can play the music through OSS, ALSA, sndio, PulseAudio, the JACK Audio Connection Kit, or even using the Win32 Sound API (available only under Cygwin or native Win32).

⚠️ Depending on the compile-time options, not all file formats and output drivers may be usable in a particular build. so don't come for her if something's missing from your build, bestie 😭

Type aqualung -v to get a list of all the compiled-in features. iykyk 💅

Aqualung supports the LADSPA 1.1 plugin standard ✨ You can use any suitable plugin to enhance the music you're listening to. go off, honestly 🎧

Other features of the program are, and I'm gonna list them all because every single one matters:

  • tabbed playlist 📑
  • internally working volume and balance controls (not touching the soundcard mixer) 🎚️
  • multiple skin support 🎨
  • random seeking during playback 🎲
  • track repeat, list repeat and shuffle mode (besides normal playback) 🔁

In track repeat mode the looping range is adjustable. and here's the part that's genuinely iconic: Aqualung will come up in the same state as it was when you closed it, including playback modes, volume and balance settings, currently processing LADSPA plugins, window sizes, positions and visibility, and other miscellaneous options. she remembers everything. main character energy fr fr 💖

Aqualung has the ability to display and edit Ogg Xiph comments, ID3v1, ID3v2 and APE tags, as well as FLAC picture frames found in files that support them. See the section about metadata support for full reference. 📝

The method of assembling the title string of a track is programmable (via a user-provided Lua function) and can include nearly any metadata item or audio file attribute. See the documentation of the Lua extension file config setting for full reference. yes, Lua, she's fancy like that 🧚

You can control any running instance of the program remotely from the command line (start, stop, pause etc.). Remote loading or enqueueing soundfiles as well as complete playlists is also supported. 🕹️

In addition to all this, Aqualung provides a so-called Music Store that is an XML-based music database, capable of storing various metadata about music on your computer (including, but not limited to, the names of artists, and the titles of records and tracks). You can (and <em>should</em>) organize your music into trees of Artists/Records/Tracks, thereby making life easier than with the all-in-one Winamp/XMMS playlist. 🌳

Importing file metadata (ID3v1, ID3v2 tags, Ogg Xiph comments, APE metadata) into the Music Store as well as getting track names from a CDDB/FreeDB database is supported. For audio CDs, CD-Text retrieval is also implemented. 💿

💜 Please refer to the documentation available at the homepage for a detailed description of features, usage tips and troubleshooting issues. This manual page is merely an abstract from the User's Manual, and documents only the command line interface of the program for quick reference.

and that's just the intro, babe — more coming 👀

✨ OPTIONS ✨

Ok bestie, listen 💖 normally you just type aqualung and it works. No options, no drama. In that case it goes and probes for a usable driver for you — in this exact order: JACK, then PulseAudio, then ALSA, then OSS — all with default parameters. Iconic behaviour, honestly.

But if no driver could be started with default parameters, or you're the type of girl who wants to explicitly choose her output configuration (valid 💅), you have to tell the program which output device to use. That's what -o (--output) is for. All five output drivers have their own specific optional parameters. You can also pick which sample rate converter you want, or ask for a list of available converters. Oh, and you can remotely control another instance of the program, or add files to the Playlist. So much power fr fr.

General options 🎀

  • -D, --disk-realtime — try to use realtime (SCHED_FIFO) scheduling for the disk thread. That's the background worker thread doing file decoding and sample rate conversion. Try this (and optionally -Y) if you're getting short audio dropouts caused by other programs — like a web browser loading a complex page. We've all been there 😭
  • -Y, --disk-priority <int> — when you're running -D, this sets the scheduler priority to <int>. Defaults to 1.

Options relevant to ALSA output 🌸

  • -d, --device <name> — set the output device. Defaults to 'default'.
  • -r, --rate <int> — set the output sample rate.
  • -b, --buffer-size <int> — set the ALSA output buffer size, in frames.
  • -R, --realtime — try to use realtime (SCHED_FIFO) scheduling for the ALSA output thread.
  • -P, --priority <int> — when running --realtime, set the scheduler priority to <int>. The default is 1 when -R is used.

Options relevant to OSS output 🦋

  • -d, --device <name> — set the output device. Defaults to /dev/audio on OpenBSD, /dev/dsp on other Unices.
  • -r, --rate <int> — set the output sample rate.
  • -R, --realtime — try to use realtime (SCHED_FIFO) scheduling for the OSS output thread.
  • -P, --priority <int> — when running --realtime, set the scheduler priority to <int>. The default is 1 when -R is used.

Options relevant to JACK output 🎧

  • -a[<port_L>,<port_R>], --auto[=<port_L>,<port_R>] — auto-connect the output ports to the given JACK ports. Defaults to the first two hardware playback ports.
  • -c, --client <name> — set the client name. You need this if you want to run multiple instances of the program, no cap.
Heads up bestie: in the case where JACK output got selected as part of the automatic output device detection, the -a option is implicitly applied. It just happens, okay? 🫶

Options relevant to PulseAudio and sndio output 💜

  • -r, --rate <int> — set the output sample rate.
  • -R, --realtime — try to use realtime (SCHED_FIFO) scheduling for the sndio output thread.
  • -P, --priority <int> — when running --realtime, set the scheduler priority to <int>. The default is 1 when -R is used.

Options relevant to Win32 output 🪟

  • -r, --rate <int> — set the output sample rate.

Options relevant to the Sample Rate Converter 🌈

  • -s[<int>], --srctype[=<int>] — choose the SRC type, or print the list of available types if you give no number. The default is SRC type 4 (Linear Interpolator). She's the default for a reason ✨

Options for remote cue control 📡

Lowkey important: remote controlling of instances is only possible if the instance you want to send a command to is running as the same user as you are when you issue the remote command. Same user or it's not happening, sorry bestie 💀
  • -N, --session <int> — specify the instance number to send the remote command to. Instances are numbered on a per user basis, starting with 0. Except for the zero-th instance (started first), the instance number is displayed in the title bar of the main window (e.g.: Aqualung.3). If you don't use this option, the following options will control the zero-th instance by default — except for -L, which defaults to the present instance (so as to be able to start playback immediately from the command line). Clever, right?
  • -B, --back — jump to previous track.
  • -F, --fwd — jump to next track.
  • -L, --play — start playing.
  • -U, --pause — pause playback, or resume if already paused.
  • -T, --stop — stop playback.
  • -V, --volume [m|M]|[=]<val> — adjust the volume. m/M means mute. If = is present, the remote instance's volume control will be set to the value specified; otherwise the volume will be adjusted by the supplied (signed) value. The values are in dB units.
  • -Q, --quit — terminate the remote instance. Bye bestie 👋

Options for file loading 📂

You may specify filenames on the command line. These may be ordinary soundfiles playable by Aqualung, directories, or playlist files you saved earlier. The program will decide if a file is a playlist, and add its contents accordingly. In addition to Aqualung's native (XML) playlist format, the program will load M3U and PLS playlists whenever possible. Versatile queen 👑

If you used the --session option (see above), the files will be sent to the Aqualung instance you specified. Otherwise a new instance will start up with the files you specified. Note that if you enabled the Save and restore the Playlist on exit/startup option in the Settings dialog, the files you specify will be loaded after the automatically loaded ones.

  • -E, --enqueue — enqueue added files to the Playlist instead of loading them (which removes the previous contents of the Playlist). Use this if you want to keep the existing items in the Playlist. Protect your queue at all costs 💖
  • -t[<name>], --tab[=<name>] — specify the target tab for file loading (either remotely using the --session option, or at startup). If --tab is used without the name parameter, the files will be added to a new (untitled) tab. If a name is supplied, Aqualung will check whether a tab with that name already exists. If so, the files will be loaded (or enqueued if you used -E) to that tab. If no such tab exists, one with that name will be created, and the content goes there. Organised tabs are main character energy fr 🎀

Options for changing state of Playlist/Music Store windows 🪟

  • -l [yes|no], --show-pl=[yes|no] — show/hide the Playlist window.
  • -m [yes|no], --show-ms=[yes|no] — show/hide the Music Store window.

Examples 🍓

$ aqualung -s3 -o alsa -R -r 48000 -d plughw:0,0
$ aqualung --srctype=1 --output oss --rate 96000
$ aqualung -o jack --auto=system:playback_17,system:playback_18
$ aqualung -o jack -a -E --tab="Led Zeppelin" `find ./ledzeppelin/ -name '*.flac'`

🗂️ FILES

Here's the list of files that Aqualung creates, reads and relies on. The receipts, basically 💅

  • $XDG_CONFIG_HOME/aqualung/ — directory containing user settings. $XDG_CONFIG_HOME is the user-specific directory for application configuration information according to the XDG Base Directory Specification. It's most likely equivalent to ~/.config, so the following config files (except the last one, which resides in a system-wide location) are usually found under $HOME/.config/aqualung/.
Note: earlier versions of Aqualung kept these per-user configuration files in ~/.aqualung. This legacy setup is recognized and silently migrated to the XDG-conformant layout. Glow up achieved ✨
  • config.xml — GUI (skin, window size/position, etc.) and other settings.
  • plugin.xml — list of running plugins and all their settings.
  • playlist.xml — automatically saved and restored playlist (if you enable this feature).
  • <skin-name> — locally available skin <skin-name> (useful for skin development). Very DIY of you 🎨
  • ${prefix}/share/aqualung/skin — system-wide skin directory.

🌍 ENVIRONMENT

Aqualung obeys two environment variables concerning LADSPA plugins. Just two. She's low maintenance.

  • LADSPA_PATH — colon-separated list of paths to search for LADSPA plugin .so files.
  • LADSPA_RDF_PATH — colon-separated list of paths to RDF metadata files about these plugins.

When any of these is not specified, the program will use sensible defaults and look in the obvious places. She'll figure it out, don't worry 💜

👑 AUTHORS

  • Tom Szilagyi <tszilagyi@users.sourceforge.net>
  • Peter Szilagyi <peterszilagyi@users.sourceforge.net>
  • Tomasz Maka <pasp@users.sourceforge.net>
  • Jeremy Evans <code@jeremyevans.net>

The whole squad. Legends only 🫶

🐛 BUGS

Yes. 😭 Report them to our bugtracker at <https://github.com/jeremyevans/aqualung/issues>.

🏠 HOMEPAGE

<http://aqualung.jeremyevans.net>

📖 USER'S MANUAL

The latest version of the User's Manual is available at the project homepage. Go read it bestie, it's giving educational ✨

And that's a wrap on the AQUALUNG(1) page — this beauty is dated 29 August 2020 and yes, it's the manual for AQUALUNG(1) 💖 tysm for reading, go make some playlists, you ate. 🌈🎀🦋

📦 where this page comes from