NAME
aqualung - Music player for GNU/Linux
SYNOPSIS
aqualung --help
aqualung --version
aqualung [--output (jack|pulse|alsa|oss|sndio|win32)] [options] [file1
[file2 ...]]
DESCRIPTION
Aqualung is an advanced music player originally targeted at the
GNU/Linux operating system, today also running on FreeBSD, OpenBSD and
Microsoft Windows. It plays audio CDs, internet radio streams and
podcasts as well as soundfiles in just about any audio format and has
the feature of inserting no gaps between adjacent tracks. It also
supports high quality sample rate conversion between the file and the
output device, when necessary.
Audio CDs can be played back and 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.
Internet radio stations streaming Ogg Vorbis or MP3 are supported.
Subscribing to RSS and Atom audio podcasts is supported: Aqualung can
automatically download and add new files to the Music Store. Optional
limits for the age, size and number of downloaded files can be set.
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 is also a native (non-
FFmpeg) WavPack decoder. 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. Type aqualung -v to get a
list of all the compiled-in features.
Aqualung supports the LADSPA 1.1 plugin standard. You can use any
suitable plugin to enhance the music you are listening to.
Other features of the program are: 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. 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.
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 Programmable
title format file config setting for full reference.
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 should)
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.
OPTIONS
Normally you should be able to start Aqualung without any options. This
case the output device will be selected by probing for a usable driver
(in order of JACK, PulseAudio, ALSA, OSS) with default parameters.
If no driver could be started with default parameters, or you want to
explicitly choose a suitable output configuration, you have to tell the
program which output device to use. This is possible with the -o
(--output) option. There are specific optional parameters for all five
output drivers. You can also specify which sample rate converter you
want to use, or request a list of available converters. You may also
control another instance of the program remotely, or add files to the
Playlist.
General options
-D, --disk-realtime
Try to use realtime (SCHED_FIFO) scheduling for disk thread, a
background worker thread doing file decoding and sample rate
conversion. Try this (and optionally -Y) if you experience short
audio dropouts caused by other programs (e.g. web browser
loading a complex page).
-Y, --disk-priority <int>
When running -D, set 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.
-R, --realtime
Try to use realtime (SCHED_FIFO) scheduling for ALSA output
thread.
-P, --priority <int>
When running --realtime, set scheduler priority to <int>
(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 OSS output
thread.
-P, --priority <int>
When running --realtime, set scheduler priority to <int>
(default is 1 when -R is used).
Options relevant to JACK output
-a[<port_L>,<port_R>],
--auto[=<port_L>,<port_R>]
Auto-connect output ports to given JACK ports (defaults to first
two hardware playback ports).
-c, --client <name>
Set client name (needed if you want to run multiple instances of
the program).
Note that in the case when JACK output has been selected as part of the
automatic output device detection, the -a option is implicitly applied.
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 sndio output
thread.
-P, --priority <int>
When running --realtime, set scheduler priority to <int>
(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 no
number given. The default is SRC type 4 (Linear Interpolator).
Options for remote cue control
Note that 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.
-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).
-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 remote instance.
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.
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.
-t[<name>], --tab[=<name>]
Specify 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.
Options for changing state of Playlist/Music Store windows
-l [yes|no], --show-pl=[yes|no]
Show/hide Playlist window.
-m [yes|no], --show-ms=[yes|no]
Show/hide 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 is a list of files that Aqualung creates, reads and relies on.
~/.aqualung
Directory containing user settings.
~/.aqualung/config.xml
GUI (skin, window size/position, etc.) and other settings.
~/.aqualung/plugin.xml
List of running plugins and all their settings.
~/.aqualung/playlist.xml
Automatically saved and restored playlist (if you enable this
feature).
~/.aqualung/<skin-name>
Locally available skin <skin-name> (useful for skin
development).
${prefix}/share/aqualung/skin
System-wide skin directory.
ENVIRONMENT
Aqualung obeys two environment variables concerning LADSPA plugins.
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.
AUTHORS
Tom Szilagyi <tszilagyi@users.sourceforge.net>
Peter Szilagyi <peterszilagyi@users.sourceforge.net>
Tomasz Maka <pasp@users.sourceforge.net>
Jeremy Evans <code@jeremyevans.net>
BUGS
Yes. Report them to our bugtracker at
<http://aqualung.factorial.hu/mantis> or write to our mailing list (the
subscription interface is accessible from the project homepage).
HOMEPAGE
Please go to <http://aqualung.factorial.hu> to download the latest
version, access the Aqualung bugtracker and subscribe to the mailing
list.
USER'S MANUAL
The latest version of the User's Manual is available at the project
homepage.
23 January 2010