It is not hard to get Aqualung up and running on your machine, although for beginners the number of compile-time options might be intimidating at first. The steps you need to take depend on the platform and operating system you use. For detailed information please look at the relevant page of the Aqualung website.

In case you are not used to compiling software yourself, you may check whether there is a distribution-provided package of Aqualung. Installing such a package is generally the easiest and fastest way to get Aqualung, however this way you won't be able to try the latest features. Currently there are Aqualung packages for major Linux distributions such as Debian, Gentoo, SuSE, etc. as well as FreeBSD. If your distribution lacks such a package, consider contacting the organization maintaining the distribution and ask them to provide a package of Aqualung. Anyway, you might have to compile Aqualung from source. This is not very hard, either the configure script tries to adapt Aqualung to your system as much as possible without breaking the program. See the above website for more information.

On Microsoft Windows, all you have to do is download and run the self-extracting installer utility, which guides you through a few easy to follow steps and installs the program on your machine. Make sure to visit this page for more information about the Windows version of Aqualung.

Aqualung has a large number of configuration settings, which are adjustable through the user interface at run-time (no need to edit config files by hand), and are remembered across multiple invocations of the program. When Aqualung starts for the first time, it creates a configuration based on some wired-in defaults. A good way of exploring the program's capabilities is poking through the configuration area. You can access this by clicking in the main window with the right mouse button, which will pop up the program's main menu. Choosing Settings from the menu will open the configuration dialog.

In fact, clicking with the right mouse button almost anywhere is a generally smart idea. Aqualung has lots of context-sensitive popup menus in the Music Store, the Playlist (often embedded in the main window) and elsewhere. It's good to keep this in mind when taking the explorative approach instead of reading the whole manual right away.

Let's add some music to the Playlist and start playback right away. Right-click the Add files button, and choose Add directory from the menu. (The right-clicking trick works for the other two buttons as well. Left-clicking is a shortcut to immediately execute the action denoted by the button's caption.) Choose a directory with some music under it. It's OK to have subdirectories under this directory, the program will search for playable files recursively. After the Playlist starts to get populated with tracks, press play, or double-click on one of the tracks to play. Press i to see metadata information about the selected track.

Now that you have some music playing, let's get more organized. In the Music Store window click in the empty area with the right mouse button and choose Create empty store... from the menu. Enter a meaningful name such as Tom's Music and choose a location to save the XML file of the store to. This should be a writable location, so it is wise to stick to a location inside your home directory. (A system-wide path or a remote NFS mount with read-only access won't do.)

You can have any number of such stores in the Music Store organizer, and it is indeed a great idea to have separate stores for music differentiated by origin, genre, or some other aspect. One great use is multiple stores with the actual music files stored on multiple remote machines, one store for each machine. Or just a store for your local music and another for files on your bedroom file server box. There are several possibilities.

But how do you populate the store with music you already have on your drive? It's easy if your music is stored in an organized manner on the filesystem level. As a minimum, this means that tracks intended to go into one store are found under a common root directory in the filesystem (there may be several directory layers down from the root to the individual files, but there must be a common ancestor). In this case the so-called Music Store Builder will take care of things for you. Right-click on your newly-created empty store and choose Build / Update store from filesystem. Choose Independent mode and in the dialog you get, enter the root directory under which your collection resides. As you can probably guess at this point, the store builder interface is pretty flexible, however the default settings should be good to get something together quickly without further hassle.

Pressing OK will start the process, during which the directory structure below the root you specified will be traversed. The artist/record/track names are determined from potentially multiple data sources (CDDB, metadata e.g. ID3v2 tags or Ogg Xiph comments, and filesystem names). The logic involved is fairly elaborate. You are strongly advised to read the detailed usage instructions for the Music Store Builder.

You can play CDs with Aqualung easily. Just put the CD in one of your CD drives, and if everything goes well, Aqualung will detect it, do a CDDB lookup to retrieve artist, record and track info (CD-Text is also used if the CD has it), and make it available to you through the special Music Store node called CD Audio.

You don't have to be happy with what you have so far. The Music Store paradigm is fairly addictive, as it's much easier to drop something into the Playlist from the Music Store than physically placing a CD in the drive. So as you keep expanding your CD collection, you will probably want to have those records in one of your music stores, too. In this case all you have to do is choose Rip CD... from the disc's popup menu, and supply some information. We won't go into details here (please refer to this section in case the interface is not obvious). However, it is worth stating that you should have a separate directory for the files of each record. Ripping multiple CDs into the same directory won't work.

aqualung --help

Print help message with valid parameters and example invocations.

aqualung --version

Print version information and list of compiled-in features.

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

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.

-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).

-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).

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.

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.

-l [yes|no], --show-pl=[yes|no]

Show/hide Playlist window.

-m [yes|no], --show-ms=[yes|no]

Show/hide Music Store window.

$ 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'`

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.

Here is a list of files that Aqualung creates, reads and relies on.

$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 is 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.

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).

${prefix}/share/aqualung/skin

System-wide skin directory.

You can control most of the program from this window. The cue controls in the bottom-left corner are fairly obvious. You can drag the large slider in the middle for seeking. There are two smaller sliders above that, the left one is for adjusting the volume and the right one for adjusting the balance. Above these, there are two horizontal text areas showing information about the currently playing track, and input/output parameters such as sample rate, mono/stereo, bitrate, output driver (e.g. OSS, ALSA, JACK) etc. The first trick to learn is that these lines are horizontally draggable with the mouse if the text does not fit in the available visible space. However, they don't scroll automatically, and for a very good reason.

In the upper left corner, you find one bigger and two smaller displays that show track times: elapsed time, remaining time and total track time. The big display also shows the current volume and balance setting when appropriate. By clicking in these displays, you can rearrange the displays as you want them. The following figure shows how the displays switch their contents after clicking into them with the left (L) or right (R) mouse button.

In the bottom right corner there are additional buttons. The buttons with the letters display or hide additional windows of the program:

Note that depending on the skin, these buttons may come with images instead of the letters above. However, their functionality does not change.

The remaining three buttons are to select the playback mode. When none of these buttons is depressed, playback goes the normal way. The buttons are mutually exclusive, and select track repeat, list repeat or shuffle mode. I'm sure you can figure out which is which. If you select track repeat, a loop bar appears above the seek bar, with two markers. The markers can be dragged to select the looping range. When they are at the left and right end positions, the whole song is repeated. The looping range can also be selected using keyboard shortcuts. When track repeat is enabled and the current song is playing (or paused), < will set the start of the looping range to the current playing position; > does the same for the end of the looping range.

Volume and balance slider tricks:

• Shift + any mouse button sets the volume and balance sliders back to 0 dB and Center position, respectively. This combination also works for the loop bar, in which case the looping range is set to the whole song.
• Clicking and holding the right mouse button on these sliders shows their position in the big time display without altering the value.

An additional thing to know about the volume control is that it ranges up to +6 dB. This means you can send a bigger signal to the audio device than in the original file. With 0 dB corresponding to 100% signal level, +6 dB is almost exactly 200% signal level (and 4 times signal power as well). This means you can overdrive your output device, and since clipping will occur at 100% anyway, it will cause nasty digital distortion much worse than simple analog overdrive. If you have a track with a reasonably low level, you can go above 0 dB with the volume control. But today most CDs are mastered to keep the average volume level very close to the 0 dB (or 100%) top, and so they will likely distort with as little as +1 dB additional gain. The moral is: if you want it loud, turn up your external amp. You can also consider using RVA if the volume level of your tracks tends to vary in a wide range see this section for details.

On a related note, another thing to watch out for is LADSPA plugins (in case you use them). It is very common that the signal level leaving a plugin is greater than the signal level the plugin gets on its input. So it is best to leave a few dB of headroom if you do that. A very typical case is boosting some frequency bands a few dB with an EQ plugin. You should decrease the overall volume level with as much dB as the largest boost (or even more), or you are risking that the signal will get chopped causing bad distortion. Alternatively, apply this limiter plugin as the last one in the processing chain, but only if you know what you are doing.

Right-clicking almost anywhere in the window will bring up a menu that allows access to the Settings dialog, the Skin Chooser, the JACK Port Setup dialog (present only when running the program with JACK output), and the About box. The latter may be useful to see which features have been compiled into the program. (If you haven't read the page about compiling yet: the configuration of the program can be adapted so as not to require certain libraries when compiling, and not provide certain features accordingly.)

The Playlist normally receives its contents from the Music Store. However, you can put any file in the Playlist regardless of the contents of your Music Store, using the Add files button at the bottom of the window. Adding a directory or a URL are also supported, by right-clicking on the button and selecting the appropriate menu item, Add directory or Add URL.

The Add URL menu item can be used to listen to Internet radio stations streaming Ogg Vorbis or MP3. You will be shown a dialog with an entry, in which you should enter the URL of the stream. Pressing OK will add it to the Playlist. After you start playing the stream, the Playlist entry changes to the name of the radio station, with the description provided by the station in brackets.

The other two buttons (Select all, Remove selected) function as you would expect them when clicked with the left mouse button. Clicking with the right mouse button brings up popup menus that contain further options as seen with the Add files button.

There is a statusbar under the list showing the total time of the Playlist and the duration of the selected tracks, as well as the size of the songs (if enabled).

The Playlist can not only maintain a linear list of songs, but is also capable of keeping the tracks of albums together. This is done when a Store, Artist or Record has been added to the Playlist using the so-called Album mode, available from the popup menu in Music Store. If you tend to use it extensively, there is an option on the Settings / Playlist page to make it default, so drag & drop and adding via keyboard shortcut will use this mode automatically.

Aqualung supports playlist tabs, which allow you to have multiple playlists for your music at the same time, very similarly to multiple tabbed browsing in Firefox. Creating new tabs is possible via CTRL+T in the Playlist window, double-clicking on the tab bar, or using the right-click context menu of the tab labels. This context menu can also be used to rename tabs, close other tabs, or undo closing. Another trick is that middle clicking on an item in the Music Store adds the content to a new playlist tab, which will be named after the middle-clicked element by default. Closing a tab has several ways: clicking the close button located on each tab, middle-clicking on a tab, using the tab context menu, or by pressing CTRL+W in the Playlist window. Undo close tab is possible until you quit Aqualung. Tabs can be reordered via drag & drop.

The contents of the Playlist can be saved and restored automatically when the program exits and starts up, and/or periodically with adjustable interval. (Whether this should be done is a configuration option, covered later.) In addition to this, you can save the Playlist manually at any time, or load a previously saved playlist file. To do this, right-click in the Playlist area, which will bring up a popup menu with these features.

The Playlist is saved as an XML file, unless you specify a filename ending in .m3u, in which case it is saved in M3U format (one filename per line). When saving an XML playlist, you should normally end your filename with .xml however, this is only good practice and not necessary. If you choose Save all playlists, the XML will be a multi-tabbed playlist, containing all tabs, while Save playlist saves the current playlist only. When saving all playlists, it will always use the XML format, as the M3U file format does not support multiple playlists. Note that the XML playlist file format is not compatible with Winamp/XMMS .m3u files. However, Aqualung will open playlists in M3U and PLS formats whenever possible.

When opening a multi-tabbed playlist, all opened tabs will be appended after the present ones, and the existing tabs will be remained intact, regardless of whether you chose loading (which normally clears the current playlist before adding) or enqueueing (which appends songs to the playlist). Opening any other playlist type (single XML playlist created by Save playlist, M3U or PLS playlists) will behave according to the option you chose (Load in new tab, Load or Enqueue).

The usual cut, copy and paste functions are accessible via keyboard shortcuts, and work across playlist tabs as well. Rearranging tracks by drag & dropping items is also supported. You can even drag a track from a playlist into another, by dragging on the tab first in order to switch to the target playlist. The only restriction is that album nodes cannot be pasted or dropped inside another album node.

If you use JACK output, you need this dialog to route the outputs of the program somewhere (most likely to the playback ports representing the soundcard driver). If you want the outputs to be connected automatically to the first two hardware playback devices, use the -a (or --auto) command line option.

On the left, each output port has a list of its current connections. By clicking on any list item, that connection will be removed. The Clear connections button removes all connections from the output ports.

The notebook on the right has a page for all client programs and hardware devices available to the JACK server. Naturally only those are shown which are data sinks (hardware playback devices or inputs of JACK clients), thus connectable to outputs which are data sources. By selecting a notebook page, you will see a list of that client's input ports. Clicking on a list item connects the port to the currently selected Aqualung output port (which has a blue header). You can change the selected output port by clicking on the unselected (grey) list header. When you add connections to the output ports, the selection alters between the two outputs so connecting both outputs is very fast and easy.

If you start up another JACK client while the dialog is open, you may press the Rescan button to make it appear in the notebook. Closing and re-opening the dialog has the same effect, since JACK ports are re-read and a new dialog instance is built every time.

This dialog lets you choose from the available skins at any time. All officially supported skins are shipped with Aqualung, and installed in the system-wide skin directory during make install. Skins placed in the local skin directory will only be locally available, which is useful for developing new skins or experimenting with the existing ones. If there are skins in the system-wide directory and the local directory having the same name, the local one takes precedence.

When compiled with Systray support, Aqualung will place its icon in the system tray (notification area), and lets all of its windows be closed while still playing music. In this mode pressing the upper right X on the main window will not exit the program, only hide its windows.

Clicking on the systray icon with the left mouse button will toggle visibility of the program's windows. Clicking with the right button will bring up a popup menu allowing showing/hiding the windows, basic cueing, and quitting Aqualung.

The systray icon has a tooltip displaying the same text as the main window's title. So it's easy to see what track is currently playing, and also the Aqualung instance ID (in case of more instances).

It is possible to export files from the Music Store or Playlist to external formats. This is especially handy if you own a portable music player, since it can be easily filled with music you already have on your computer, transcoding and tagging the files so they can be readily used by the device. The feature is available from the right-click popup menus (both in Music Store and Playlist), and via the shortcut x or X (in Music Store only). It operates on the selected Music Store node, or the selected tracks in the Playlist.

The export dialog handles the settings of output directory, filename and file format. Subdirectories can be created for artists and/or records, with adjustable limit for the length of the created directory names. The actual filename is generated using the filename template. This template is very similar to the well-known Title format in Settings / General, only it accepts a few more special sequences: %o for the original audio filename (without extension), %n for the track number (two digit, zero padded), %i for an identifier which is unique within an export session, and %x for the file extension. The latter is determined by the output file format, and will be one of flac, ogg, mp3 or wav.

The file format setting is exactly the same as with CD ripping, refer to this section for details.

The metadata of the exported files is transcoded to the new format as well as the audio data; read more about this here.

One great feature of the program is that you can apply LADSPA plugins to the music. You can use the equalizer of your choice instead of a built-in one, along with other plugins. You can process your sound with Aqualung in ways that the author of this program never thought of. A recommended set is TAP-plugins.

Of course, faithful reproduction of music does not require or permit pervasive signal processing, since that is not the purpose of such activity. However, the technology is at your disposal and it's up to you to use or misuse it. It may be necessary to adapt your listening gear to the acoustic environment, using small amounts of equalization preferably in a subtractive manner. In addition to this, I also like to spice my tracks with a small amount of tubewarmth to feel that warm tube sound even with my transistor amplifiers, and to bring out even the finest details of the music.

The plugin chain you build is automatically saved and restored, so once you get it right for your listening environment, you should rarely need to touch it.

Some tricks concerning the LADSPA patch builder:

• Multiple plugins can be selected from the available plugins list and added at once by clicking on the Add button or pressing a or A.
• A single plugin can be added immediately by double-clicking it in the available plugins list.
• Plugins in the running list can be (un)bypassed with the middle mouse button.
• The configuration window of the running plugins can be brought up by double-clicking on them (same as clicking on the Configure button).
• If a plugin is selected in the running plugins list, pressing DELETE will remove it (same as pressing the Remove button).
• Running plugins can be rearranged at any time (changing the order in which they are processed) via dragging them with the mouse.
• In the configuration windows of plugins, setting input controls back to their default value is possible by shift-clicking on the slider. This does not work for toggled or integer inputs (those that don't have a slider displayed for them).

RVA stands for Relative Volume Adjustment, and refers to a system that is supposed to compensate for the fact that the perceived volume levels of tracks from different records are sometimes quite different. With usual players, you are left with the possibility to adjust the volume manually, when necessary; but not with Aqualung.

Besides having a fully-fledged system for RVA, Aqualung also supports using already existing ReplayGain or RVA information present in your audio files' metadata. If you are interested in this, read on, but make sure to also check out this section.

You have to do two things prior to using RVA in Aqualung. First, you have to calculate the volume of the tracks you want affected by the RVA system. To do this, use the Calculate volume option in the Music Store found in the right-click popup menus of Stores, Artists, Records and Tracks. When you activate this option, a small window will pop up with a progress bar. You can move this window out of your way, and proceed with using Aqualung. Processing will be carried out in the background, and should not affect your ability to play music at all. Calculated volume levels will be saved and restored with the rest of the Music Store. The values are shown in the Edit track dialog.

When you are done with this, open the Settings dialog (right-click almost anywhere in the main window), and select the Playback RVA notebook page.

If Enable playback RVA is unchecked, the whole RVA system is turned off. No tracks receive adjustment. If playback RVA is enabled, you can select a listening environment that matches your setup. The idea is that the better your environment, the smaller adjustment you need to enjoy the music. If you work in a noisy workshop (and listen to Aqualung-played music) then it is best to minimize the volume differences between tracks so all tracks will be uniformly audible at a particular volume setting. If you can afford to listen to music in a silent room with high quality headphones or good near-field monitors, you should choose Audiophile which will yield no change to volumes.

The diagram shows the input/output transfer function applied to the previously measured track loudness to obtain the adjustment needed for a particular track. The diagram is 24 dB large in both directions, with the (0, 0) point being in the upper right corner. The blue line shows the identity function (no change), while the red line shows the output volume (the actual transfer function). The adjustment applied at a particular track volume is the vertical distance between the two lines at that position. The transfer function is linear. You can use the Reference volume and Steepness controls to change its position.

In most cases, it is desirable that tracks of the same record receive the same adjustment, so as to preserve the volume differences internal to the record. This can be enabled by checking Apply averaged RVA to tracks of the same record. When enabled, volume levels of the same record will be averaged and all tracks will be adjusted by an average value. Please note that measured volume levels are converted to RVA values when you add something from the Music Store to the Playlist. Therefore, this feature works only when you add an Artist or a Record. If you add a record by adding all the Tracks manually one after another, they will all receive independent RVA values. Also, changing RVA settings will not affect entries already in the Playlist.

There are many records having one or two tracks that really stand out of the average volume level. (For example, there is one very silent track on an otherwise loud record.) In this case, these tracks would pull down the average volume. To get around this, you can adjust a threshold that will be used to sort out tracks that stand out too much and will be disregarded when computing the average volume.

You can select whether you want to specify a threshold in linear volume units [dBFS] or you want to specify a percentage of the standard deviation of the set of individual track volumes to use as a threshold. The default values should work well for the vast majority of records. If you always want every track's volume to count in the average adjustment of the record, choose the linear threshold and set it to a really big value (say, 30 dB) so all tracks will be within this range.

For external tracks added to the Playlist and having no volume information, you can specify a fixed RVA value using RVA for Unmeasured Files. This applies to all tracks coming from outside the Music Store or a native XML playlist file, and to URLs.

You also have the possibility to always use a manually specified, fixed value as RVA for a particular track. In the Edit track dialog for that track, check the Use manual RVA value checkbox and set the value with the spinbutton on its right. If you e.g. import an ID3v2.4 RVA tag from an MP3 file, it will also set this field thereby circumventing Aqualung's own RVA calculation.

It is possible to have more volume calculations in progress at a time. If you need to measure a few records, you don't have to wait for the previous one to finish. RVA calculations can also be paused, so should you suddenly need the whole CPU capacity, you don't have to abort the process just pause it, and resume when things go down.

Aqualung's Music Store Builder allows you to easily create a store from your existing audio files. This is essential if you already have a large music collection on your harddrive.

The Builder supports two approaches for automatically adding audio files to the Music Store. The directory driven mode requires the collection to be organized in a strict filesystem structure, where the directory structure itself specifies which files belong to a record, and which records belong to an artist. The structure should conform to one of the following patterns:

Pattern a) is useful when you do not have separate subdirectories for artists, only for records. The b) means that each artist and record has its own subdirectory. It corresponds to the structure introduced above along with the Music Store. The patterns c) and d) are for those who have too many artists to keep them at the same level; you may thus have a subdirectory for every artist starting with letter a, b, etc., or you can even dedicate two levels to them, perhaps as b/be/beatles, c/cr/crimson, etc.

The independent mode does not follow any directory structure, only searches for audio files recursively starting from root. This doesn't allow the Builder to perform CDDB lookups, so only metadata and filename transformations are available with this mode. If your audio files are basically organized in a directory structure that allows a directory driven build to be performed, but you also happen to have audio files on higher (record or artist) levels, run the Builder in directory driven mode first, then use the independent mode on the same root directory to add the outstanding files too.

The Builder can gain information about your music from three sources: metadata (if your audio files are correctly tagged), CDDB lookups, and the filesystem names of the audio files and directories themselves.

If you are up to building a new store, first create an empty store (right-click in Music Store, then choose the Create empty store item), then right-click on the new store and choose Build / Update store from filesystem. After selecting the desired building mode, the builder dialog appears with several options broken down into five notebook pages. Later, if you only want to update the content of a store, you can start a build process on a non-empty store as well.

On the General page you have to select the root directory of your music collection. With the directory driven mode, the appropriate structure should also be selected.

You can exclude files from the build process that match a wildcard pattern (or more precisely, at least one element in a list of wildcard patterns). The list is comma-separated, e.g. *.jpg,*.png,*.gif will cause all files having jpg, png, or gif extension to be left out. Note that hidden files (whose name starts with a period) are always excluded. Also note that no spaces should be used around the commas, because they would be counted in the wildcard patterns, causing a lot of headache.

Similarly, you may include only those files that match a wildcard pattern. The syntax is the same as with the exclusion. This easily allows you to build a store containing music e.g. encoded with FLAC, and another store for Ogg, while the audio files can be placed together even in the same directory. Exclude and include patterns are case-insensitive.

If you choose to reset existing data, only track name, length, manual RVA and empty comment fields will be overwritten, and the latter two are only if you have enabled importing the Replaygain and Comment tags on the Track tab. Removing non-existing files will remove all tracks from the store that no longer exist on the filesystem. Empty artists and records will also be removed.

The builder dialog has separate notebook pages for artists, records and tracks. The settings made on a page only concern the appropriate category (either artist, record or track). The operations and transformations are performed in the same order as they are placed on the page, from top to bottom.

The File info dialog (accessible from the Music Store and the Playlist) acts as a graphical shell for the metadata editing capabilities. Its usage is fairly self-explanatory. For read-only tags, the dialog has no editing controls, so the only available operation is viewing the fields, copy-pasting them to another location, or (if the dialog was opened from the Music Store) importing the field to the Music Store database. Embedded images can also be saved to file.

For writable files, the metadata is editable. Each metadata tag present in the file will be displayed in a separate notebook tab. On each tab the information present in a tag is usually organized as a list of frames, displayed in a key:value fashion. The values of each frame are editable, mostly by means of a simple text entry, but in some cases other widgets (such as a drop-down menu) may also be present. The frame itself can be removed by clicking on the frame's rightmost icon displaying a trash can. Some frames cannot be removed, because their existence is mandated by the corresponding metadata standard for the tag. In this case the trash can is greyed out.

Adding new frames is possible via the drop-down box at the bottom of the tab. This box contains all possible frames that you can add to the present tag. Some frames can only occur once in a tag; in this case after adding it once (or if a frame of this type is already present in the tag) it is no more present in the drop-down box.

Adding and removing whole tags is also supported. Just press the trash can icon at the bottom right corner of the tab, and the whole tag will be removed. Adding a new tag is possible via the drop-down box at the bottom of the window. This box contains all possible tags you can add to this file. This depends on the audio file format and what tags are already present in the file (naturally, only one instance of a particular tag may exist in a file).

Aqualung supports mass tagging, that is, writing data from the Music Store into file metadata. The feature can be invoked on a store, artist, record or a single track using the Batch-update file metadata... popup menu item. Supported metadata fields are artist, record and track name, track number, track comment and year. The names are copied from the visible name fields of the artist, record and track, the track number and comment are set from the sort name and comment field of the track, respectively. The year is extracted from the sort name field of the record.

The General tab itself is further divided into tabs, which are explained below.

The Playlist is embedded in the Main window by default to achieve a more compact look. Turn it off to put the Playlist into a separate window.

You can set whether to use Album mode by default when adding songs from Music Store to the Playlist. Regardless of this setting, you can always add tracks without using Album mode by using the Add to playlist popup menu in Music Store.

Settings concerning playlist tabs can be made too. You can control whether to have close buttons on playlist tabs. If you don't want the tab bar to be hidden when only one tab is open, uncheck the Always show the tab bar item.

The option to save/restore the Playlist when exiting and starting the program is turned on by default. If you prefer starting with an empty Playlist every time, turn it off. You can also set whether to save the Playlist periodically. The interval for this is adjustable between 1 and 60 minutes.

Here you can also set the visibility of the track lengths and RVA values in the Playlist. By drag & dropping entries in the list, you can rearrange the columns. The position of those that are not shown is of course irrelevant. Other options should be obvious, such as hiding the statusbar, or showing active track name in bold.

The purpose and usage of Music Store and database files have been covered. On this page you can somewhat customize the Music Store, decide whether to hide the comment pane or the status bar, or to enable rules hint. If you choose to expand stores on startup, all toplevel tree nodes will automatically be expanded after starting Aqualung.

As already mentioned before, this page is also the place to manage music store database files too. Pressing the Refresh button will update the accessibility (r, rw, unreachable) flags of the specified store files.

Changing the two options on the DSP page takes effect immediately, and stays that way regardless of whether you leave the dialog with the OK or Cancel button.

The sample rate converter type should be chosen to fit the resources of your computer, and provide the best affordable quality at the same time. So fire up top or something similar on a spare terminal, and start with the best converter. If your machine is not very new, this will consume huge amounts of CPU, and the playback will very likely be choppy. If this is the case, you will have to pick another converter. Fastest Sinc Interpolator is usable on today's most machines. If not, use Linear Interpolator instead of ZOH since both are blindingly fast, but linear is naturally much better than zero-order (constant hold). It should also be noted that the CPU usage of sample rate conversion is greatly affected by the difference between the two sample rates: upsampling 32k to 96k will be much more expensive than, say, upsampling from 44.1k to 48k.

Of course, sample rate conversion springs into action only when the output sample rate (the sample rate you specified in case of OSS or ALSA, or the sample rate the JACK server specified in case of JACK) does not match the sample rate of the track you are playing. A typical situation is when you have 44.1k files grabbed from CD and play back at 48k.

This page is for setting the RVA options. RVA itself has already been discussed above.

On this page you can configure how the Aqualung metadata subsystem works. See this section for a detailed description.

You can set the drive speed for CD playing in CD-ROM speed units. Lower speed usually means less drive noise. However, when using Paranoia error correction modes for increased accuracy, generally much larger speeds are required to prevent buffer underruns (and thus audible drop-outs), but this is very device-specific.

Most drives let Aqualung know when a CD has been inserted or removed. However, some drives don't report correctly, and thus it may happen that a newly inserted CD remains unnoticed to Aqualung. In such cases, forcing TOC re-read on every drive scan should help.

Aqualung can automatically add newly inserted CDs to the Playlist, and remove them when the CD is removed from the drive. A CD will only be added if the Playlist doesn't already contain any of its tracks. The newly added CD will appear at the top of the Playlist, but after all CD tracks or albums being in the list.

Removal from Playlist will happen if the CD is removed from the drive, or the user quits Aqualung while the CD is in the drive. All tracks of the CD will be removed, even if they were mixed with other audio files or some of them were removed manually.

You can set some parameters of the CDDB lookups here. As for the query protocol, standard CDDBP (port 888) and CDDB over HTTP (port 80) are supported. The standard CDDBP port is the recommended choice unless some unavoidable firewall settings prevent you from using it. For submission HTTP is always used.

The default CDDB database server address is freedb.org, but you may specify another server (maybe a close mirror). The connection timeout can also be set here.

If you want to submit records to the CDDB server, you will have to give a valid email address. Should your submission be rejected for some reason, you will receive a note about the failure to this address.

Retrieved matches are cached in the ~/.cddbslave directory by default. If you prefer an other location instead, specify a local CDDB directory. If you do not intend to download from a CDDB server at all, you can set to use the local database only.

Instead of connecting directly to the Internet you can use an HTTP proxy. In this case you have to specify the proxy server address and port. You may also provide a list of domains that should be accessed without using the proxy. Setting a proxy affects Internet radio streaming, podcast downloading and CDDB lookups.

Timeout for socket I/O is used to prevent Aqualung from hanging if data is coming too slowly or not at all from a radio station.

On this page you can decide whether to override some fonts and colors provided by the skins. You can change the font of the Music Store, Playlist, the track and timer labels, and set the color of the active track in Playlist. Useful if you have problems with font size or your system lacks or improperly renders a font specified in a skin.

You can entirely get rid of all skin settings by selecting Disable skin support. It allows you to flawlessly use a GTK or other theme with Aqualung.

In addition to the popup menu items and keyboard shortcuts, you can also add an item to the Playlist by drag & dropping from the Music Store window into the Playlist. This method has a further advantage: you can place the newly added items in any position, not just append to the end of the list.

Another trick is that middle clicking on an item in the Music Store adds the content to a new playlist tab, which will be named after the middle-clicked element by default.

Aqualung is written in the C programming language, but if compiled with Lua support, embeds a Lua interpreter that can used by the user to change Aqualung's behavior or add custom functions without recompiling the program. Aqualung supports the following 5 types of extensions:

• Title Format
• Hooks
• Playlist Menu Commands
• Remote Commands
• Keybindings

The Lua extension file setting appears if Aqualung is compiled with Lua support. It allows you to choose a .lua file containing Lua code that implements any of the above extensions. You can type in the path to the file or click Browse to get a file chooser. The .lua file should be a valid Lua source code file.

If you change the Lua extension file setting in the options page, and accept the changes, Aqualung will close the existing Lua interpreter and create a new Lua intepreter. To close the existing Lua interpreter and immediately reopen it with the same extension file, use the Reload Lua interpreter setting. Note that whenever the Lua interpreter is closed, all Lua-internal state is lost.

By specifying a function named playlist_title in your Lua extension file, which should accept no arguments and should return a string, you can override the default title formatting specified by the Title format setting. Similarly, by specifying a function named application_title with the same API, you have the application window's title set separately from the playlist title. If you would like the application title and playlist title to be the same, you can have your application_title function just call playlist_title.

Aqualung defines two functions for you to use to get data to use in the title format, m and i. m stands for metadata, and i stands for file info. The m function is used to get metadata from file tags, while the i function is used to get information about the file itself, such as the length, bitrate, and number of channels. If there are multiple metadata entries (such as multiple artists), m will return them as a single string separated with comma (,). If there is no metadata entry, m will return the empty string. If you ask for a metadata or file info entry that Aqualung doesn't understand, Aqualung will log an error and will fallback to using the standard title formatting code.

Here are some examples.

Changing the Lua extension file entry takes effect immediately, but does not affect existing titles in the playlist. In order to update existing titles in the playlist, the Reread file metadata setting should be used.

Aqualung allows you to add hooks to certain events to have extension code executed when those events occur. Hooks are added by calling the add_hook function with a string and a function. The string is the type of hook you are adding, and the function is the function to call when the related event occurs. You can have multiple hook functions added to the same hook type, and they will be executed in order of addition.

You can add custom playlist menu commands to Aqualung by calling the add_playlist_menu_command function with a string and a function. The string is the label of the playlist menu entry, and the function is the function to call when the playlist menu entry is clicked. You can include /'s inside the string to create submenus (there is currently no support for a / to appear inside a label). The function should accept 0 arguments.

You can add custom remote commands to Aqualung by calling the add_remote_command function with a string and a function. The string is the name of the remote command, and the function is the function to call when the remote command is triggered. You can call a custom remote command using the -C argument to aqualung (e.g. aqualung -C function_name). The string argument/function name should be fewer than 250 characters. The function should accept zero arguments.

You can add custom keybindings for Aqualungs main window by calling the add_main_keybinding function with a string and a function. The string is the GDK name of the key, optionally preceded by modifiers, and the function is the function to call when the keybinding is used in the main window directly after a Ctrl-z or Ctrl-Z keybinding. The function should accept zero arguments.

These are global methods that you can call inside the methods described above in order to get information from Aqualung, or change Aqualung's settings or behavior.

• current_file(): Returns the filename (string) of currently playing file, or nil if no file is playing.
• current_file_percent_complete(): Returns number between 0 and 100 with the percent complete of the current playing file, or nil if no file is playing.
• selected_files(): Returns an array (integer-keyed table) of selected filenames (strings) for the current playlist.