manual.lyx

Aqualung is an advanced music player primarily targeted for the GNU/Linux operating system, but als

 has metadata for the artist or record name) the string candidate that occurred
 most cases is chosen in order to avoid typos and other garbage whenever
 possible.
\end_layout

\begin_layout Standard
The sort key for artists and records can be chosen between the real name
 and the directory name of the corresponding artist or record, both can
 be forced lowercase.
 For records there is another choice, the year of the album, which can be
 retrieved from metadata or through CDDB query (the priority of the sources
 applies here too).
 The year can also be automatically added to the comment field of new records
 found by the build process.
\end_layout

\begin_layout Standard
You can exclude files from the build process that match a wildcard pattern.
 The pattern is a comma-separated list of wildcards, e.g.\InsetSpace ~
`*.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.
\end_layout

\begin_layout Standard
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.\InsetSpace ~
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.
\end_layout

\begin_layout Standard
Capitalization of the strings can be controlled too.
 You may choose from capitalizing all words, or only the first one.
 If you allow one of them, you can supply a case-sensitive comma-separated
 list of words, whose case will be preserved.
 It is useful to make roman numerals and other acronyms appear uppercase
 (or in the case you like them).
\end_layout

\begin_layout Standard
If you rebuild a store, existing data is not touched in any way.
 The only change to be made to the store is that new audio files in a record's
 directory will be added to the record.
 However, you have the option to re-read data for existing tracks too.
 It will only reset the track title, duration and RVA from the appropriate
 Replaygain tag (if such tag exists and you enabled RVA import on the `Metadata'
 page, see below).
 Note that any other data such as comment or manual RVA value will strictly
 be kept intact.
\end_layout

\begin_layout Standard
The `Metadata' page lets you choose whether to use metadata at all, and
 if yes, where.
 You have the option to exclude metadata containing only whitespace, which
 is a kind of protection.
\end_layout

\begin_layout Standard
The `CDDB' page has similar settings for the CDDB lookup as the `Metadata'
 page had for metadata -- you can decide whether to perform CDDB lookup
 and for what kind of strings.
\end_layout

\begin_layout Standard
At last, the `Filesystem' page is for generating the track names from the
 filenames.
 You can decide whether to use the predefined transformations, or an extended
 regular expression based substitution method.
 The former choice should be quite obvious and intended to provide acceptable
 result in most cases.
 The regexp is for those who are familiar with the regexp syntax and have
 to perform some unusual transformations.
 It has the effect of a `sed s/regexp/replacement/g' call on each filename.
 The regexp must not match the empty string, but the replacement is allowed
 to be empty in which case the matched parts are deleted.
 The replacement may contain the special escapes 
\backslash
1 through 
\backslash
9 to refer to the corresponding matching sub-expressions in the regexp.
 See sed(1) and grep(1) for more information on sed substitution and regexp
 syntax.
 There is a sandbox where you can enter a filename and see how it would
 be transformed, providing a safe environment for experiments.
 It works both for predefined and regexp transforms.
\end_layout

\begin_layout Standard
Once you are satisfied with the settings click `OK'.
 A new window showing the progress is displayed, and the store is filled
 up.
 You can abort the process if you encounter some error or weirdness, or
 just want to refine some settings.
\end_layout

\begin_layout Standard
The building process can be narrowed to only one artist, which can strongly
 speed up the operation.
 It may come in handy if you made changes to only one artist (or just a
 few ones).
 The feature is accessible from the right-click menu of the artists.
 Note that you will have to specify the directory of the artist instead
 of the root directory of the entire music collection.
\end_layout

\begin_layout Subsubsection
Arranging your collection
\end_layout

\begin_layout Standard
Each store, artist, record and track has fields you can fill in via bringing
 up the `Edit' dialog for that item.
 The `Visible name' is obviously the string that will appear in the Music
 Store tree, and in the Playlist.
 The `Name to sort by' is a string key used for sorting items on the same
 level of hierarchy (all artists, records of a given artist, and tracks
 of a given record).
\end_layout

\begin_layout Standard
For artists, you should enter the same here as the `Visible name' for ordinary
 band names (you can use copy & paste to do that).
 However, for some artists you will enter a slightly modified string: `Mayall,
 John' or just `Mayall' for John Mayall, for example.
 This is to ensure that `John Mayall' (which is the visible name) appears
 between `Mahavishnu' and `Morphine', and not somewhere near `Jethro Tull'.
\end_layout

\begin_layout Standard
For records and tracks, the `Name to sort by' should be a decimal numbering
 of the items.
 If you added tracks to the records using the aforementioned `Auto-create
 tracks from these files' feature of the Record add dialog, the tracks will
 be automatically numbered for you this way.
\end_layout

\begin_layout Standard
Last but not least, every item has a `Comment' field that may contain multiple
 lines of text, and is perfectly optional to use for any store, artist,
 record or track.
 When you have entered something in this field, it will be displayed in
 the lower area of the Music Store window when the corresponding item is
 selected in the tree.
 Use this to store miscellaneous data, such as birth dates of artists, release
 dates or comments like `Recorded live at Royal Albert Hall, \SpecialChar \ldots{}
' or `Digitized
 from original LP' for records, and movement subtitles for tracks that have
 them.
 
\end_layout

\begin_layout Subsubsection
Dealing with multiple stores
\end_layout

\begin_layout Standard
As mentioned before, you may maintain several collections of audio files
 on several machines.
 Each collection is arranged in an artist/record/track hierarchy, and appears
 under a store item in the Music Store tree.
 The metadata describing one collection is located in one file on your filesyste
m.
\end_layout

\begin_layout Standard
On the Settings/Music Store page you can specify several database files
 whose content is intended to appear in your Music Store.
 If a given file is unavailable, the corresponding store item will be missing
 from the Music Store.
 If the file is readonly, you can play the music, but you won't be allowed
 to change (add, edit, remove, etc.) the items in the store.
 Finally, if you have write permission on the file, you will be allowed
 to change the items.
\end_layout

\begin_layout Standard
The order in which the stores appear in the Music Store is the order of
 the corresponding database files in the list.
 The list can be reordered via drag & drop.
\end_layout

\begin_layout Subsubsection
Handling file metadata
\end_layout

\begin_layout Standard
The program can read and write Ogg Xiph comments, ID3v1, ID3v2 and APE tags
 present in the files themselves.
 To see such metadata for a particular track, you will utilize the `File
 info' dialog accessible from the Music Store (right-click popup menus for
 Tracks, or press `i') and the Playlist (right-click popup menu for playlist
 entries, or press `i').
\end_layout

\begin_layout Standard
When you open the `File info' dialog from the Music Store, you will find
 buttons to the right of every metadata field that was read from the file
 (unless the store is readonly).
 By pressing these buttons, the associated data will be imported into the
 corresponding field of the relevant Track.
 For metadata fields that don't have a corresponding field in the Music
 Store, you can append their contents to the `Comment' field as a catch-all
 solution.
\end_layout

\begin_layout Standard
The so-called basic fields (that are common in all supported metadata formats)
 are editable, thus you can modify their contents and save them by pressing
 the `Save basic fields' button.
 Other format specific fields are also displayed, but modifying them is
 not supported.
 Creation and removal of the tags is also supported for the appropriate
 file formats.
\end_layout

\begin_layout Standard
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\SpecialChar \ldots{}
' 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.
\end_layout

\begin_layout Subsubsection
Using the RVA system
\begin_inset LatexCommand \label{sub:RVA}

\end_inset


\end_layout

\begin_layout Standard
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.
\end_layout

\begin_layout Standard
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 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.
\end_layout

\begin_layout Standard
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.
\end_layout

\begin_layout Standard
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.
\end_layout

\begin_layout Standard
The diagram shows the input/output transfer function applied to the previously
 measured track loudness to obtain the needed 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.
\end_layout

\begin_layout Standard
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.
\end_layout

\begin_layout Standard
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.
 
\end_layout

\begin_layout Standard
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.
\end_layout

\begin_layout Standard
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.\InsetSpace ~
import an ID3v2.4 RVA tag from an MP3 file, it will also set this
 field thereby circumventing Aqualung's own RVA calculation.
 
\end_layout

\begin_layout Subsubsection
CDDB Support
\end_layout

\begin_layout Standard
Aqualung supports retrieving matches from a CDDB database, as well as submitting
 new records or updating existing ones.
 The features are available by right-clicking on a record in the Music Store
 and choosing the appropriate menu item.
\end_layout

\begin_layout Standard
The CDDB query option starts a query (which can last a bit long if there
 are a lot of matches), and displays a dialog with the search results.
 It tends to work even if you have already encoded your audio files in a
 lossy format.
\end_layout

\begin_layout Standard
If there are multiple matches, you can select any of them using the combo
 box at the top of the dialog.
 The displayed fields are all editable, which is useful in case you find
 no fully acceptable match, but want to use one that is almost perfect.
 The track names can be edited by double-clicking on the desired track,
 or single clicking on an already selected entry.
\end_layout

\begin_layout Standard
By pressing the `OK' button the track names of the currently selected lookup
 results will be propagated into the Music Store.
 The artist name and record title are not automatically set, but can be
 imported using the `Import as Artist' and `Import as Title' buttons on
 the right.
 Year can be imported as the sort key of the record.
 Other data (category, genre and extended data) can be appended to the comment
 field of the record in question using the `Add to Comments' button next
 to the appropriate text entry.
\end_layout

\begin_layout Standard
The CDDB submission option brings up a dialog which contains the artist,
 title, year, category, genre and extended data fields, and the tracklist.
 All fields (including track names) are editable.
 The artist, title, year and category fields are mandatory, the genre and
 extended data are optional.
 Track names should be all set as well.
 If you are about to update or correct an existing CDDB record, make sure
 that you choose the same category as the existing record has (this information
 can be retrieved via a CDDB query).
 You are also recommended to comply with the 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
href{http://freedb.org/modules.php?name=Sections&sop=viewarticle&artid=26#2-2}{nam
ing rules}
\end_layout

\end_inset

 when submitting new records.
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Subsubsection
Shortcuts for this window
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="14" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="block" valignment="top" leftline="true" rightline="true" width="10cm">
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
double click
\family default
\series default
\shape default
\size default
\emph default
\bar default
\noun default
,
\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
 a, A
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
add 
\family default
\series default
\shape default
\size default
\emph default
\bar default
\noun default
store/
\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
artist/record/track to playlist
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
n, N
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
new 
\family default
\series default
\shape default
\size default
\emph default
\bar default
\noun default
store/
\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
artist/record/track
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
s, S
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
save store
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
b, B
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="tr