1AQUALUNG(1) General Commands Manual AQUALUNG(1)
2
6 aqualung - Music player for GNU/Linux
7
9 aqualung --help
10 aqualung --version
12 aqualung [--output (jack|pulse|alsa|oss|sndio|win32)] [options] [file1
14 [file2 ...]]
15
17 Aqualung is an advanced music player originally targeted at the
18 GNU/Linux operating system, today also running on FreeBSD, OpenBSD and
19 Microsoft Windows. It plays audio CDs, internet radio streams and pod‐
20 casts as well as soundfiles in just about any audio format and has the
21 feature of inserting no gaps between adjacent tracks. It also supports
22 high quality sample rate conversion between the file and the output de‐
23 vice, when necessary.
24 Audio CDs can be played back and ripped with on-the-fly conversion to
26 WAV, FLAC, Ogg Vorbis or CBR/VBR MP3 (gapless via LAME). Seamless tag‐
27 ging of the created files is offered as part of the process. Internet
28 radio stations streaming Ogg Vorbis or MP3 are supported. Subscribing
29 to RSS and Atom audio podcasts is supported: Aqualung can automatically
30 download and add new files to the Music Store. Optional limits for the
31 age, size and number of downloaded files can be set.
32 Almost all sample-based, uncompressed formats (e.g. WAV, AIFF, AU
34 etc.), as well as files encoded with FLAC (the Free Lossless Audio
35 Codec), Ogg Vorbis, Ogg Speex, MPEG Audio (including the infamous MP3
36 format), MOD audio formats (MOD, S3M, XM, IT, etc.), Musepack and Mon‐
37 key's Audio Codec are supported. Numerous formats and codecs are also
38 supported via the FFmpeg project, including AC3, AAC, WMA, WavPack and
39 the soundtrack of many video formats. There is also a native (non-FFm‐
40 peg) WavPack decoder. The program can play the music through OSS, ALSA,
41 sndio, PulseAudio, the JACK Audio Connection Kit, or even using the
42 Win32 Sound API (available only under Cygwin or native Win32). Depend‐
43 ing on the compile-time options, not all file formats and output driv‐
44 ers may be usable in a particular build. Type aqualung -v to get a list
45 of all the compiled-in features.
46 Aqualung supports the LADSPA 1.1 plugin standard. You can use any suit‐
48 able plugin to enhance the music you are listening to.
49 Other features of the program are: tabbed playlist, internally working
51 volume and balance controls (not touching the soundcard mixer), multi‐
52 ple skin support, random seeking during playback, track repeat, list
53 repeat and shuffle mode (besides normal playback). In track repeat mode
54 the looping range is adjustable. Aqualung will come up in the same
55 state as it was when you closed it, including playback modes, volume
56 and balance settings, currently processing LADSPA plugins, window
57 sizes, positions and visibility, and other miscellaneous options.
58 Aqualung has the ability to display and edit Ogg Xiph comments, ID3v1,
59 ID3v2 and APE tags, as well as FLAC picture frames found in files that
60 support them. See the section about metadata support for full refer‐
61 ence.
62 The method of assembling the title string of a track is programmable
64 (via a user-provided Lua function) and can include nearly any metadata
65 item or audio file attribute. See the documentation of the Lua exten‐
66 sion file config setting for full reference.
67 You can control any running instance of the program remotely from the
69 command line (start, stop, pause etc.). Remote loading or enqueueing
70 soundfiles as well as complete playlists is also supported.
71 In addition to all this, Aqualung provides a so-called Music Store that
73 is an XML-based music database, capable of storing various metadata
74 about music on your computer (including, but not limited to, the names
75 of artists, and the titles of records and tracks). You can (and should)
76 organize your music into trees of Artists/Records/Tracks, thereby mak‐
77 ing life easier than with the all-in-one Winamp/XMMS playlist. Import‐
78 ing file metadata (ID3v1, ID3v2 tags, Ogg Xiph comments, APE metadata)
79 into the Music Store as well as getting track names from a CDDB/FreeDB
80 database is supported. For audio CDs, CD-Text retrieval is also imple‐
81 mented.
82 Please refer to the documentation available at the homepage for a de‐
84 tailed description of features, usage tips and troubleshooting issues.
85 This manual page is merely an abstract from the User's Manual, and doc‐
86 uments only the command line interface of the program for quick refer‐
87 ence.
88
90 Normally you should be able to start Aqualung without any options. This
91 case the output device will be selected by probing for a usable driver
92 (in order of JACK, PulseAudio, ALSA, OSS) with default parameters.
93 If no driver could be started with default parameters, or you want to
95 explicitly choose a suitable output configuration, you have to tell the
96 program which output device to use. This is possible with the -o
97 (--output) option. There are specific optional parameters for all five
98 output drivers. You can also specify which sample rate converter you
99 want to use, or request a list of available converters. You may also
100 control another instance of the program remotely, or add files to the
101 Playlist.
102 General options
105 -D, --disk-realtime
107 Try to use realtime (SCHED_FIFO) scheduling for disk thread, a
108 background worker thread doing file decoding and sample rate
109 conversion. Try this (and optionally -Y) if you experience short
110 audio dropouts caused by other programs (e.g. web browser load‐
111 ing a complex page).
112 -Y, --disk-priority <int>
114 When running -D, set scheduler priority to <int> (defaults to
115 1).
116 Options relevant to ALSA output
119 -d, --device <name>
121 Set the output device (defaults to 'default').
122 -r, --rate <int>
124 Set the output sample rate.
125 -b, --buffer-size <int>
127 Set the ALSA output buffer size (in frames).
128 -R, --realtime
130 Try to use realtime (SCHED_FIFO) scheduling for ALSA output
131 thread.
132 -P, --priority <int>
134 When running --realtime, set scheduler priority to <int> (de‐
135 fault is 1 when -R is used).
136 Options relevant to OSS output
139 -d, --device <name>
141 Set the output device (defaults to /dev/audio on OpenBSD,
142 /dev/dsp on other Unices).
143 -r, --rate <int>
145 Set the output sample rate.
146 -R, --realtime
148 Try to use realtime (SCHED_FIFO) scheduling for OSS output
149 thread.
150 -P, --priority <int>
152 When running --realtime, set scheduler priority to <int> (de‐
153 fault is 1 when -R is used).
154 Options relevant to JACK output
157 -a[<port_L>,<port_R>],
159 --auto[=<port_L>,<port_R>]
160 Auto-connect output ports to given JACK ports (defaults to first
161 two hardware playback ports).
162 -c, --client <name>
164 Set client name (needed if you want to run multiple instances of
165 the program).
166 Note that in the case when JACK output has been selected as part of the
168 automatic output device detection, the -a option is implicitly applied.
169 Options relevant to PulseAudio and sndio output
172 -r, --rate <int>
174 Set the output sample rate.
175 -R, --realtime
177 Try to use realtime (SCHED_FIFO) scheduling for sndio output
178 thread.
179 -P, --priority <int>
181 When running --realtime, set scheduler priority to <int> (de‐
182 fault is 1 when -R is used).
183 Options relevant to Win32 output
186 -r, --rate <int>
188 Set the output sample rate.
189 Options relevant to the Sample Rate Converter
192 -s[<int>], --srctype[=<int>]
194 Choose the SRC type, or print the list of available types if no
195 number given. The default is SRC type 4 (Linear Interpolator).
196 Options for remote cue control
199 Note that remote controlling of instances is only possible if the in‐
201 stance you want to send a command to is running as the same user as you
202 are when you issue the remote command.
203 -N, --session <int>
205 Specify the instance number to send the remote command to. In‐
206 stances are numbered on a per user basis, starting with 0. Ex‐
207 cept for the zero-th instance (started first), the instance num‐
208 ber is displayed in the title bar of the main window (e.g.:
209 `Aqualung.3'). If you don't use this option, the following op‐
210 tions will control the zero-th instance by default, except for
211 -L which defaults to the present instance (so as to be able to
212 start playback immediately from the command line).
213 -B, --back
215 Jump to previous track.
216 -F, --fwd
218 Jump to next track.
219 -L, --play
221 Start playing.
222 -U, --pause
224 Pause playback, or resume if already paused.
225 -T, --stop
227 Stop playback.
228 -V, --volume [m|M]|[=]<val>
230 Adjust the volume. m/M means mute; if = is present, the remote
231 instance's volume control will be set to the value specified,
232 otherwise, the volume will be adjusted by the supplied (signed)
233 value. The values are in dB units.
234 -Q, --quit
236 Terminate remote instance.
237 Options for file loading
240 You may specify filenames on the command line. These may be ordinary
242 soundfiles playable by Aqualung, directories, or playlist files you
243 saved earlier. The program will decide if a file is a playlist, and add
244 its contents accordingly. In addition to Aqualung's native (XML)
245 playlist format, the program will load M3U and PLS playlists whenever
246 possible.
247 If you used the --session option (see above), the files will be sent to
249 the Aqualung instance you specified. Otherwise a new instance will
250 start up with the files you specified. Note that if you enabled the
251 Save and restore the Playlist on exit/startup option in the Settings
252 dialog, the files you specify will be loaded after the automatically
253 loaded ones.
254 -E, --enqueue
256 Enqueue added files to the Playlist instead of loading them
257 (which removes the previous contents of the Playlist). Use this
258 if you want to keep the existing items in the Playlist.
259 -t[<name>], --tab[=<name>]
261 Specify target tab for file loading (either remotely using the
262 --session option, or at startup). If --tab is used without the
263 name parameter, the files will be added to a new (untitled) tab.
264 If a name is supplied, Aqualung will check whether a tab with
265 that name already exists. If so, the files will be loaded (or
266 enqueued if you used -E) to that tab. If no such tab exists, one
267 with that name will be created, and the content goes there.
268 Options for changing state of Playlist/Music Store windows
271 -l [yes|no], --show-pl=[yes|no]
273 Show/hide Playlist window.
274 -m [yes|no], --show-ms=[yes|no]
276 Show/hide Music Store window.
277 Examples
280 $ aqualung -s3 -o alsa -R -r 48000 -d plughw:0,0
282 $ aqualung --srctype=1 --output oss --rate 96000
284 $ aqualung -o jack --auto=system:playback_17,system:playback_18
286 $ aqualung -o jack -a -E --tab="Led Zeppelin" `find ./ledzeppelin/ -name '*.flac'`
288
290 Here is a list of files that Aqualung creates, reads and relies on.
291 $XDG_CONFIG_HOME/aqualung/
293 Directory containing user settings. $XDG_CONFIG_HOME is the
294 user-specific directory for application configuration informa‐
295 tion according to the XDG Base Directory Specification. It is
296 most likely equivalent to ~/.config, so the following config
297 files (except the last one, which resides in a system-wide loca‐
298 tion) are usually found under $HOME/.config/aqualung/
299 Note: earlier versions of Aqualung kept these per-user configu‐
300 ration files in ~/.aqualung. This legacy setup is recognized and
301 silently migrated to the XDG-conformant layout.
302 config.xml
304 GUI (skin, window size/position, etc.) and other settings.
305 plugin.xml
307 List of running plugins and all their settings.
308 playlist.xml
310 Automatically saved and restored playlist (if you enable this
311 feature).
312 <skin-name>
314 Locally available skin <skin-name> (useful for skin develop‐
315 ment).
316 ${prefix}/share/aqualung/skin
318 System-wide skin directory.
319
321 Aqualung obeys two environment variables concerning LADSPA plugins.
322 LADSPA_PATH
324 Colon-separated list of paths to search for LADSPA plugin .so
325 files.
326 LADSPA_RDF_PATH
328 Colon-separated list of paths to RDF metadata files about these
329 plugins.
330 When any of these is not specified, the program will use sensible de‐
332 faults and look in the obvious places.
333
336 Tom Szilagyi <tszilagyi@users.sourceforge.net>
337 Peter Szilagyi <peterszilagyi@users.sourceforge.net>
338 Tomasz Maka <pasp@users.sourceforge.net>
339 Jeremy Evans <code@jeremyevans.net>
340
342 Yes. Report them to our bugtracker at <https://github.com/jeremye‐
343 vans/aqualung/issues>.
344
346 <http://aqualung.jeremyevans.net>
347
349 The latest version of the User's Manual is available at the project
350 homepage.
351 29 August 2020 AQUALUNG(1)