<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kid3 '<application>Kid3</application>'>
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>
<book lang="&language;">

<bookinfo>
<title>The Kid3 Handbook</title>

<authorgroup>
<author>
<firstname>Urs</firstname>
<surname>Fleisch</surname>
<affiliation>
<address><email>ufleisch@users.sourceforge.net</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>2011</year>
<holder>Urs Fleisch</holder>
</copyright>
<legalnotice id="fdl-notice">&FDLNotice;</legalnotice>

<date>2011-01-15</date>
<releaseinfo>1.6</releaseinfo>

<abstract>
<para>
&kid3; is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
an efficient way. Also tags in Ogg/Vorbis, FLAC, MPC, MP4/AAC, MP2, Speex,
TrueAudio, WavPack, WMA, WAV and AIFF files are supported.
It is easy to set tags of multiple files to the same
values (e.g. album, artist, year and genre in all files of the same album) and
generate the tags from the file name or vice versa.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdemultimedia</keyword>
<keyword>MP3</keyword>
<keyword>ID3</keyword>
<keyword>ID3v1</keyword>
<keyword>ID3v2</keyword>
<keyword>Ogg</keyword>
<keyword>Vorbis</keyword>
<keyword>FLAC</keyword>
<keyword>MPC</keyword>
<keyword>APE</keyword>
<keyword>Musepack</keyword>
<keyword>MP4</keyword>
<keyword>M4A</keyword>
<keyword>MP2</keyword>
<keyword>Speex</keyword>
<keyword>TrueAudio</keyword>
<keyword>WavPack</keyword>
<keyword>WMA</keyword>
<keyword>WAV</keyword>
<keyword>AIFF</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
&kid3; is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
an efficient way. These tags can be edited by most MP3 players, but not in
a very comfortable and efficient way. Moreover the tags in Ogg/Vorbis, FLAC,
MPC, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV and AIFF files are supported too.
</para>
<para>
&kid3; does not grab nor encode
MP3 files, but it is targeted to edit the ID3 tags of all files of an album
in an efficient way, i.e. with as few mouse clicks and key strokes as
possible. Where most other programs can edit either ID3v1 or ID3v2 tags,
&kid3; has full control over both versions, can convert tags between the
two formats and has access to all ID3v2 tags. Tags of multiple files can be
set to the same value, e.g. the artist, album, year and genre of all files
of an album typically have the same values and can be set together. If the
information for the tags is contained in the file name, the tags can be
automatically set from the file name. It is also possible to set the file
name according to the tags found in the file in arbitrary formats.
</para>
<para>
The editing task is further supported by automatic replacement of characters
or substrings, for instance to remove illegal characters from
filenames. Automatic control of upper and lower case characters makes it easy
to use a consistent naming scheme in all tags.
</para>
<para>
The tag information for full albums can be taken from
<ulink url="http://gnudb.org">gnudb.org</ulink>, <ulink
url="http://tracktype.org">TrackType.org</ulink>, <ulink
url="http://musicbrainz.org">MusicBrainz</ulink>,  <ulink
url="http://discogs.com">Discogs</ulink>, <ulink
url="http://www.amazon.com">Amazon</ulink> or other sources of
track lists. The import format is freely configurable by regular expressions.
</para>
<para>
Please report any problems or feature requests to the author.
</para>
</chapter>

<chapter id="using-kid3">
<title>Using Kid3</title>

<sect1 id="kid3-features">
<title>Kid3 features</title>
<itemizedlist>
<listitem><para>Edit ID3v1.1 tags</para></listitem>
<listitem><para>Edit all ID3v2.3 and ID3v2.4 frames</para></listitem>
<listitem><para>Edit tags of multiple files</para></listitem>
<listitem><para>Convert between ID3v1 and ID3v2 tags</para></listitem>
<listitem><para>Edit MP3, Ogg/Vorbis, FLAC, MPC, MP4/AAC, MP2, Speex,
TrueAudio, WavPack, WMA, WAV and AIFF tags</para></listitem>
<listitem><para>Generate tags from filename</para></listitem>
<listitem><para>Generate filename from tags</para></listitem>
<listitem><para>Generate and change directory names from tags</para></listitem>
<listitem><para>Generate playlist file</para></listitem>
<listitem><para>Automatic case conversion and string translation</para></listitem>
<listitem><para>Import from <ulink url="http://gnudb.org">gnudb.org</ulink>,
<ulink url="http://tracktype.org">TrackType.org</ulink>,
<ulink url="http://musicbrainz.org">MusicBrainz</ulink>,
<ulink url="http://discogs.com">Discogs</ulink>,
<ulink url="http://www.amazon.com">Amazon</ulink>
and other data sources</para></listitem>
<listitem><para>Export as CSV, HTML, playlist, Kover XML and other
formats. Exported CSV files can be imported again.</para></listitem>
</itemizedlist>
</sect1>

<sect1 id="example-usage">
<title>Example Usage</title>
<para>
This section describes a typical session with &kid3;.
Let's assume we have a directory containing MP3 files with the tracks from
the album "Let's Tag" from the band "One Hit Wonder". The directory is
named in the "artist - album" format, in our case <filename>One Hit Wonder - Let's
Tag</filename>. The directory contains the tracks in the "track title.mp3"
format, which I think is useful because the filenames are short
(important when using mobile MP3 players with small displays) and in the
correct order when sorted alphabetically (important when using hardware MP3
players which play the tracks in alphabetical order or in the order in
which they are burnt on CD and that order is alphabetical when using
<command>mkisofs</command>). Besides this, the artist and album information
is already in the directory name and does not have to be repeated in the filename.
But back to our example, the directory listing looks like this:
</para>
<para><filename>01 Intro.mp3</filename></para>
<para><filename>02 We Only Got This One.mp3</filename></para>
<para><filename>03 Outro.mp3</filename></para>
<para>
These files have no tags yet and we want to generate them using &kid3;. We use
<guimenuitem>Open</guimenuitem> (<guimenu>File</guimenu> menu or toolbar) and
select one of the files in this directory. All files will be displayed in the
file listbox. Lazy as we are, we want to use the information in the directory
and file names to generate tags. Therefore we select all files, then click the
<guilabel>To:</guilabel> <guibutton>Tag 1</guibutton> button in the <guilabel>File</guilabel>
section. This will set the title, artist, album and track values in all files.
To set the year and genre values of all files, we keep all files selected and
type in "2002" for the <guilabel>Year</guilabel> and select "Pop" from the
<guilabel>Genre</guilabel> combobox. To set only these two values, we check their
checkboxes and leave all other checkboxes unchecked. Now we change the
selection by only selecting the first file and we see that all tags contain
the correct values. The tags of the other files can be verified too by
selecting them one by one. When we are satisfied with the tags, we use
<guimenuitem>Save</guimenuitem> (<guimenu>File</guimenu> menu or toolbar).
Selecting <guimenuitem>Create Playlist</guimenuitem> from the
<guimenu>File</guimenu> menu will generate a file
<filename>One Hit Wonder - Let's Tag.m3u</filename> in the directory.
</para>
</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="kid3-window">
<title>The Kid3 Window</title>

<sect2 id="gui-elements">
<title>The GUI Elements</title>
<para>
The &kid3; GUI is separated in five sections: At the left are the file
and directory listboxes, the right side contains the <guilabel>File</guilabel>,
<guilabel>Tag 1</guilabel> and <guilabel>Tag 2</guilabel> sections.
</para>

<variablelist>

<varlistentry><term>Filelist</term>
<listitem>
<para>
The file list contains the names of all the files in the opened
directory which match the selected file name filter (typically
<filename>*.mp3 *.ogg *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2 *.spx
*.tta *.wv *.wma *.wav *.aiff</filename>). A single or multiple files can be selected. To
select no file, click into the empty area after the listbox entries. The
selection determines the files which are affected by the operations which
are available by using the buttons described below.
</para>
<para>
At the left of the names an icon can be displayed: a disc to show that the
file has been modified or information about which tags are present (V1, V2,
V1V2 or NO TAG, no icon is displayed if the file has not been read in yet).
</para>
<para>
Directories are displayed with a folder icon. If a directory is opened, its
files are displayed in a hierarchical tree. By selecting files from
subdirectories, operations can be executed on files in different directories,
which is useful if the music collection is organized with a folder for each
artist containing folders for albums of this artist.
</para>
<para>
Clicking the right mouse button inside the file list opens a context menu with
the following commands:
<itemizedlist>
<listitem><para>
<guimenuitem>Expand all</guimenuitem>: Expands all folder trees
</para></listitem>
<listitem><para>
<guimenuitem>Collapse all</guimenuitem>: Collapses all folder trees
</para></listitem>
<listitem><para>
<guimenuitem>Rename</guimenuitem>: Changes the name of a file
</para></listitem>
<listitem><para>
<guimenuitem>Delete</guimenuitem>: Deletes a file
</para></listitem>
<listitem><para>
<guimenuitem>Play</guimenuitem>: Plays a file,
see <link linkend="play">Play</link>
</para></listitem>
<listitem><para>The subsequent entries are user commands, which can be defined
in the <guilabel>User Actions</guilabel> tab of
<link linkend="configure-kid3">Configure Kid3</link>.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>

<varlistentry><term>Directory List</term>
<listitem>
<para>
The directory list contains the names of the directories in the opened
directory, as well as the current (<filename>.</filename>) and the parent
(<filename>..</filename>) directory. It allows to quickly change the directory
without using the <guimenuitem>Open...</guimenuitem> command or drag and drop.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>File</guilabel></term>

<listitem>
<para>
Shows information about the encoding
(MP3, Ogg, FLAC, MPC, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV, AIFF),
bitrate, sample rate, channels and the length of the file.
</para>
<para>
The <guilabel>Name</guilabel> line edit contains the name of the file
(if only a single file is selected). If this name is changed, the file will
be renamed when the Save command is used.
</para>
<para>
The <guilabel>Format</guilabel> combo box and line edit contains the format
to be used when the filename is generated from first or the second tag.
The filename can contain arbitrary characters, even a directory part separated
by a slash from the file name, but that directory must already exist for the
renaming to succeed. The following special codes are used to insert tag values
into the filename:
</para>

<itemizedlist>
<listitem><para>%s %{title} Title (Song)</para></listitem>
<listitem><para>%a %{artist} Artist</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Comment</para></listitem>
<listitem><para>%y %{year} Year</para></listitem>
<listitem><para>%t %{track} Track (e.g. 01)</para></listitem>
<listitem><para>%t %{track.n} Track with field width n (e.g. 001 for %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Track (without leading zeroes, e.g. 1)</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%g %{ignore} Ignored when generating tags from the file name</para></listitem>
</itemizedlist>

<para>
A second <guilabel>Format</guilabel> combo box (with arrow down) is used
to generate the tags from the filename. If the format
of the filename does not match this pattern, a few other commonly used formats
are tried.
</para>

<para>
Some commonly used filename formats are already available in the combo box,
but it is also possible to type in some special format into the line edit.
</para>
<para>
<guilabel>From:</guilabel> <guibutton>Tag 1</guibutton>,
<guibutton>Tag 2</guibutton>: Sets the filename using the selected format
and the first tag or the second tag, respectively.
</para>
<para>
<guilabel>To:</guilabel> <guibutton>Tag 1</guibutton>,
<guibutton>Tag 2</guibutton>: The tags are set from the filename.
First, the format specified in <guilabel>Format</guilabel> is used. If the
existing filename does not match this format, the following formats
are tried:
<itemizedlist>
<listitem><para><filename>Artist - Album/Track Song</filename></para></listitem>
<listitem><para><filename>Album/Track - Artist - Song</filename></para></listitem>
<listitem><para><filename>/Artist - Album - Track - Song</filename></para></listitem>
<listitem><para><filename>Album/Artist - Track - Song</filename></para></listitem>
<listitem><para><filename>Album/Artist - Song</filename></para></listitem>
<listitem><para><filename>Artist/Album/Track Song</filename></para></listitem>
</itemizedlist>
If a single file is selected, the GUI controls are filled with the values
extracted from the filename. If multiple files are selected, the tags of the
files are directly set according to the filenames.
</para>
</listitem>
</varlistentry>

<varlistentry><term><guilabel>Tag 1</guilabel></term>
<listitem>
<para>
The line edit widgets for <guilabel>Title</guilabel>,
<guilabel>Artist</guilabel>,
<guilabel>Album</guilabel>, <guilabel>Comment</guilabel>,
<guilabel>Year</guilabel>, <guilabel>Track</guilabel> and
<guilabel>Genre</guilabel> are used to edit the corresponding value in the
first tag of the selected files. The value will be changed when the file
selection is altered or before operations like <guimenuitem>Save</guimenuitem>
and <guimenuitem>Quit</guimenuitem> and when the corresponding
check box at the left of the field name is checked. This is useful to
change only some values and leave the other values unchanged.
</para>
<para>
If a single file is selected, all check boxes are checked and the line edit
widgets contain the values found in the tags of this file. If a tag is not
found in the file, the corresponding empty value is displayed, which is an
empty string for the <guilabel>Title</guilabel>, <guilabel>Artist</guilabel>,
<guilabel>Album</guilabel> and <guilabel>Comment</guilabel> line edits, 0 for the
numerical <guilabel>Year</guilabel> and <guilabel>Track</guilabel> edits and
an empty selected value for the <guilabel>Genre</guilabel>
combo box. The values can be changed and if the corresponding check box is
checked, they will be set for the selected file after the selection is
changed. The file is then marked as modified by a disk symbol in the file
listbox but remains unchanged until the <guimenuitem>Save</guimenuitem>
command is used.
</para>
<para>
If multiple files are selected, only the values which are identical in all
selected files are displayed. In all other controls, the empty values as
described above are displayed. All check boxes are unchecked to avoid
unwanted changes. If a value has to be set for all selected files, it can
be edited and the checkbox has to be set. The values will be set for all
selected files when the selection is changed and can be saved using the
<guimenuitem>Save</guimenuitem> command.
</para>
<para>
The check boxes also control the operation of most commands affecting the
tags, such as copy, paste and transfer between tags 1 and 2. To make it
easier to use with multiple files where all check boxes are unchecked, these
commands behave in the same way when all check boxes are checked and when all
check boxes are unchecked.
</para>
<para>
<guibutton>From Tag 2</guibutton>: The tag 1 fields are set from the
corresponding values in tag 2.
If a single file is selected, the GUI controls are filled with the values
from tag 2. If multiple files are selected, the tags of the
files are directly set.
</para>
<para>
<guibutton>Copy</guibutton>: The copy buffer is filled with the Tag 1 values.
Only values with checked checkbox will be used in subsequent Paste commands.
</para>
<para>
<guibutton>Paste</guibutton>: Pastes the values from the copy buffer into the
GUI controls.
</para>
<para>
<guibutton>Remove</guibutton>: This will set all GUI controls to their empty
values which results in removing all values. The saved file will then contain
no tag 1.
</para>
</listitem>
</varlistentry>

<varlistentry><term><guilabel>Tag 2</guilabel></term>
<listitem>
<para>
The GUI controls function in the same way as described for the
<guilabel>Tag 1</guilabel> section, but the size of the strings is not limited.
</para>
<para>
For the tag 2 <guilabel>Genre</guilabel> you can also use your own names
besides the genres listed in the combo box, just type the name into the line
edit.
</para>
<para>
The tag 2 can not only contain the same values
as the tag 1, the format is built in a flexible way from several frames
which are themselves composed of several fields. The tag 2 table shows
all the frames which are available in the selected file.
</para>
<para>
<guibutton>Edit</guibutton>: This will open a window which allows to edit all fields
of the selected frame.
If multiple files are selected, the edited fields are applied to all selected files
which contain such a frame.
</para>
<para>
<guibutton>Add</guibutton>: A requester to select the frame type will appear
and a frame of the selected type can be edited and added to the file. This
works also to add a frame to multiple selected files.
</para>
<para>
<guibutton>Delete</guibutton>: Deletes the selected frame in the selected files.
</para>
<para>
<guilabel>Drag album artwork here</guilabel> is shown if the file does not
contain embedded cover art. A picture can be added using drag and drop from a
browser or file manager and will be displayed here. Picture frames can be
edited or added by double clicking on this control.
</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="file-menu">
<title>The File Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>O</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Open...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a directory.</action> All files matching the selected
file name filter will be displayed in the file listbox
and the chosen file is selected.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Open Recent</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a recently opened directory.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>D</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Open Directory...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a directory.</action> All files matching the selected
file name filter will be displayed in the file listbox.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Save</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves all changed files in the directory.</action> The
changed files are marked with a disk symbol in the file listbox. If any file
names have been changed, those files will be renamed.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Revert</guimenuitem>
</menuchoice></term>
<listitem><para><action>Reverts the changes of one or multiple files.</action> If no
files are selected in the file listbox, the changes of all files will be
reverted, else only the changes of the selected files are reverted.
</para></listitem>
</varlistentry>

<varlistentry id="import">
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Import...</guimenuitem>
</menuchoice></term>
<listitem><para>The <action>Import dialog</action> can be used to import data
directly from a freedb.org server, from the Web-interface of <ulink
url="http://freedb.org">freedb.org</ulink>, from a MusicBrainz server, from
Discogs, Amazon or other sources of album track lists in textual format.
</para>
<para id="import-freedb">
Import from a freedb.org server is possible using a dialog which appears when
<guibutton>From Server:</guibutton>
<guibutton>gnudb.org</guibutton> or <guibutton>TrackType.org</guibutton>
is selected. The artist and album name
to search for can be entered in the two topmost fields,
the albums which match the
query will be displayed when <guibutton>Find</guibutton> is clicked and the
results from <ulink url="http://www.gnudb.org">www.gnudb.org</ulink> are
received. Importing the track data for an album is
done by selecting the album in the list. The freedb.org server to import from
can be selected as well as the CGI path. The
imported data is displayed in the preview table of the import dialog. To work
in that dialog again, the gnudb.org dialog has to be closed - it can be
reopened later by clicking <guibutton>gnudb.org</guibutton> again and
its contents will be restored. When satisfied with the displayed tracks, they
can be imported by terminating the import dialog with
<guibutton>OK</guibutton>.
</para>
<para id="import-discogs">
A search on the Discogs server can be performed using
<guibutton>Discogs</guibutton>. As in the <guibutton>gnudb.org</guibutton> dialog,
you can enter artist and album and then choose from a list of releases.
If <guilabel>Additional Tags</guilabel> is marked, more information is
imported if available, e.g. performers, arrangers, or the publisher.
If <guilabel>Cover Art</guilabel> is marked, cover art will be downloaded if
available.
</para>
<para id="import-amazon">
A search on Amazon can be performed using
<guibutton>Amazon</guibutton>. As in the <guibutton>gnudb.org</guibutton> dialog,
you can enter artist and album and then choose from a list of releases.
If <guilabel>Additional Tags</guilabel> is marked, more information is
imported if available, e.g. performers, arrangers, or the publisher.
If <guilabel>Cover Art</guilabel> is marked, cover art will be downloaded if
available.
</para>
<para id="import-musicbrainzrelease">
You can search in the same way in the release database of MusicBrainz
using <guibutton>From MusicBrainz Release</guibutton>.
The workflow is the same as described for <guibutton>From
gnudb.org</guibutton>.
</para>
<para id="import-musicbrainz">
Import from a MusicBrainz server is possible using the dialog which appears when
<guibutton>From MusicBrainz Fingerprint</guibutton> is selected. The Server can be
selected as in the freedb import dialog. Below is a table displaying the
imported track data. The right column shows the state of the MusicBrainz
query, which starts with "Pending" when the dialog is opened. Then the
fingerprint is looked up and if it does not yield a result, another lookup
using the tags in the file is tried. Thus it can be helpful for a successful
MusicBrainz query to store known information (e.g. artist and album) in the
tags before the import. If a result was found, the search ends in the state
"Recognized", otherwise nothing was found or multiple ambiguous results and one
of them has to be selected by the user.
<guibutton>OK</guibutton> and <guibutton>Apply</guibutton> use the imported
data, <guibutton>Cancel</guibutton> closes the dialog. The closing can take a
while since the whole MusicBrainz machinery has to be shut down.
</para>
<para>
For the import of textual data, several preconfigured import formats are
available. The first two, "CSV unquoted" and "CSV quoted" can be used to
import data which was exported by the Export dialog. The CSV data can be
edited with a spreadsheet, and shall be written using tabs as
delimiters. Import should then be possible using "CSV quoted", which is more
flexible than "CSV unquoted". However, its fields cannot contain any double
quotes. If you only export from &kid3; and import later, "CSV unquoted" can be
used as a simple format for this purpose.
</para>

<para>
The next format, "freedb HTML 
text", can be used to copy information from an HTML page of
<ulink url="http://freedb.org">freedb.org</ulink>. Search an album in freedb
and if the desired information is displayed in the web browser, copy the
contents to the clipboard. Then click the <guibutton>From
Clipboard</guibutton> button and the imported tracks will be displayed in the
preview table at the top of the dialog. If you are satisfied with the imported
data, terminate the dialog with <guibutton>OK</guibutton>, which will insert
the data into the tags of the current directory. The destination
(<guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel> or
<guilabel>Tag 1 and Tag 2</guilabel>) can be selected
with a combo box. The files in the current directory should be in the correct
track order to get their tags assigned. This is the case if they are numbered.
</para>
<para>
The next preconfigured import format, "freedb HTML source", can be used, if
the data is available as an HTML document. Import is possible using the
<guibutton>From File</guibutton> button, which opens a file selector, or
copying its contents from an editor and then importing from clipboard. This
format can be useful for offline import, although the HTML document could also
be opened in a browser and then be imported in the first format via the clipboard.
</para>
<para>
More preconfigured formats, e.g. "Track Title Time", are available. A custom format
is left empty to be set by the user. Two lines below the format name can be
set with a regular expression to capture the fields from the import text. The
first regular expression will be parsed once per document to gather per-album
data such as artist, album, year and genre. The second line is tried to match
from the start of the document to the end to get track data, usually number
and title. The regular expressions include all the features offered by Qt,
which is most of the what Perl offers. Bracketing constructs "(..)" create
capture buffers for the fields to import and are preceded by &kid3; specific
codes to specify which field to capture. The codes are the same as used for
the filename format:
</para>

<itemizedlist>
<listitem><para>%s %{title} Title (Song)</para></listitem>
<listitem><para>%a %{artist} Artist</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Comment</para></listitem>
<listitem><para>%y %{year} Year</para></listitem>
<listitem><para>%t %{track} Track</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%d %{duration} Duration</para></listitem>
</itemizedlist>

<para>
For example, a track regular expression (second line) to import from an 
.m3u playlist could be "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]". All formats can
be changed by editing the regular expressions and the name and then clicking
<guibutton>OK</guibutton>. They will be stored in the
<filename>kid3rc</filename> file in the configuration directory. This file can
be directly edited to have more import formats or it can be deleted to revert
to the default formats.
</para>
<para>
To check whether the imported tracks match the current set of files, the
duration of the imported tracks can be compared with the duration of the
files. This option can be enabled with the checkbox <guibutton>Check maximum
allowable time difference</guibutton> and the maximum tolerated difference in
time can be set in seconds. If a mismatch in a length is detected, the length
is displayed with a red background in the preview table.
</para>
<para>
It the files are ordered differently than the imported tracks, their assigned
tracks have to be changed. This task can be facilitated using
the <guilabel>Match with</guilabel>
buttons <guibutton>Length</guibutton>, <guibutton>Track</guibutton>,
and <guibutton>Title</guibutton>, which will reorder the tracks according to
the corresponding field. To correct the assignments manually, a track can be
dragged with the left mouse button and the <keycap>Ctrl</keycap> key hold
down, and then dropped at the new location.
</para>
<para>
Almost all dialogs feature a <guibutton>Save Settings</guibutton> button,
which can be used to store the dialog specific settings and the window size
persistently.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Import from gnudb.org...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Import from a freedb.org server
using gnudb.org album search.</action> This menu
item opens the same import dialog as <guimenuitem>Import...</guimenuitem>, but
opens directly the <guibutton>gnudb.org</guibutton>
dialog.</para></listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Import from TrackType.org...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Import from the TrackType.org server.</action> This menu
item opens the same import dialog as <guimenuitem>Import...</guimenuitem>, but
opens directly the <guibutton>TrackType.org</guibutton>
dialog.</para></listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Import from Discogs...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Import from the Discogs server.</action>
This menu item opens the same import dialog as
<guimenuitem>Import...</guimenuitem>, but
opens directly the <guibutton>From Discogs</guibutton>
dialog.</para></listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Import from Amazon...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Import from Amazon.</action>
This menu item opens the same import dialog as
<guimenuitem>Import...</guimenuitem>, but
opens directly the <guibutton>From Amazon</guibutton>
dialog.</para></listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Import from MusicBrainz Release...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Import from the MusicBrainz release database.</action>
This menu item opens the same import dialog as
<guimenuitem>Import...</guimenuitem>, but
opens directly the <guibutton>From MusicBrainz Release</guibutton>
dialog.</para></listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Import from MusicBrainz Fingerprint...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Import from a MusicBrainz server.</action> This menu
item opens the same import dialog as <guimenuitem>Import...</guimenuitem>, but
opens directly the <guibutton>From MusicBrainz Fingerprint</guibutton>
dialog.</para></listitem> 
</varlistentry>

<varlistentry id="browse_pictures">
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Browse Cover Art...</guimenuitem>
</menuchoice></term>
<listitem><para>
The <action>Browse Cover Art</action> dialog helps to find album cover
art. <guilabel>Artist/Album</guilabel> is filled from the tags if
possible. <guilabel>Source</guilabel> offers a variety of websites with album
cover art. The URL with artist and album as parameters can be found beneath
the name. URL-encoded values for artist and album can be inserted using
<userinput>%u{artist}</userinput> and <userinput>%u{album}</userinput>, other
values from the tags are possible too, as described
in <link linkend="configure-kid3">Configure Kid3</link>, <guilabel>User
Actions</guilabel>. More sources can be entered after the entry "Custom
Source" by replacing "Custom Source" with the source's name, pressing Enter,
then inserting the URL and finally pressing <guibutton>Save
Settings</guibutton>. The resulting browser command is displayed at the top of
the dialog and can be started by clicking <guibutton>Browse</guibutton>. The
browser, which can be configured in the settings, is started with the selected
source. A cover image can then be dragged from the browser into the &kid3;
window and will be set in the picture frame of the selected files.
</para>
<para>
Because not all browsers support drag'n'drop of images and the pictures on
websites often have a URL, in such cases &kid3; will receive the URL and not
the picture. If the URL points to a picture, it will be downloaded. However,
if the URL refers to some other web resource, it has to be translated to the
corresponding picture. Such mappings are defined in the table <guilabel>URL
extraction</guilabel>. The left column <guilabel>Match</guilabel> contains a
regular expression which is compared with the URL. If it matches, the captured
expressions in parentheses are inserted into the pattern of the
right <guilabel>Picture URL</guilabel> column (at the positions marked with \1
etc.). The replaced regular expression contains the URL of the picture. By
this means cover art can be imported from Amazon, Google Images, etc. using
drag'n'drop. It is also possible to define your own mappings.
</para>
</listitem>
</varlistentry>

<varlistentry id="export">
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Export...</guimenuitem>
</menuchoice></term>
<listitem><para>
The <action>Export Dialog</action> is used to store data from the tags in a
file or the clipboard. The editor at the top shows a preview of the data to
export. The data can be edited before exporting, as it is exactly the contents
of the editor which will be stored. The data will be generated from the tags
in the current directory according to the configured format.
</para>
<para>
The format settings are similar as in the Import dialog: The topmost field
contains the title (e.g. "CSV unquoted"), followed by the header, which will
be generated at the begin of the file. The track data follows; it is used for
every track. Finally, the trailer can be used to generate some finishing
text.
</para>
<para>
The format fields do not contain regular expressions as in the Import dialog,
but only output format expressions with special %-expressions, which will be
replaced by values from the tags. The whole thing works like the file name
format, and the same codes are used plus some additional codes.
</para>

<itemizedlist>
<listitem><para>%s %{title} Title (Song)</para></listitem>
<listitem><para>%a %{artist} Artist</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Comment</para></listitem>
<listitem><para>%y %{year} Year</para></listitem>
<listitem><para>%t %{track} Track (e.g. 01)</para></listitem>
<listitem><para>%t %{track.n} Track with field width n (e.g. 001 for %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Track (without leading zeroes, e.g. 1)</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%f %{file} File name</para></listitem>
<listitem><para>%p %{filepath} Path</para></listitem>
<listitem><para>%u %{url} URL</para></listitem>
<listitem><para>%d %{duration} Duration in minutes:seconds</para></listitem>
<listitem><para>%D %{seconds} Duration in seconds</para></listitem>
<listitem><para>%n %{tracks} Number of tracks of the album</para></listitem>
<listitem><para>%e %{extension} File extension</para></listitem>
<listitem><para>%O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
existing)</para></listitem>
<listitem><para>%o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not existing)</para></listitem>
<listitem><para>%b %{bitrate} Bitrate in kbit/s</para></listitem>
<listitem><para>%v %{vbr} VBR or empty (only for ID3v2.3 with
id3lib)</para></listitem>
<listitem><para>%r %{samplerate} Samplerate in Hz</para></listitem>
<listitem><para>%m %{mode} Channel mode (Stereo or Joint Stereo)</para></listitem>
<listitem><para>%h %{channels} Number of channels (1 or 2)</para></listitem>
<listitem><para>%k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
MPC, ASF, AIFF, WAV)</para></listitem>
</itemizedlist>

<para>
A few formats are predefined. "CSV unquoted" separates the fields by
tabs. Data in this format can be imported again into &kid3; using the import
format with the same name. "CSV quoted" additionally encloses the fields by
double quotes, which eases the import into spreadsheet applications. However,
the fields shall not contain any double quotes when this format is used.
"Extended M3U" and "Extended PLS" generate playlists with extended attributes
and absolute path names. "HTML" can be used to generate an HTML page with
hyperlinks to the tracks. "Kover XML" creates a file which can be imported by
the cover printing program Kover. "Technical Details" provides information
about bitrate, samplerate, channels, etc. Finally, "Custom Format" is left empty for
definition of a custom format. You can define more formats of your own by
adding lines in the file <filename>kid3rc</filename> in the configuration
directory. The other formats can be adapted to your needs.
</para>
<para>
The source of the tags to generate the export data (<guilabel>Tag 1</guilabel>
or <guilabel>Tag 2</guilabel>) can be selected with a combo
box. Pushing <guibutton>To File</guibutton> or
<guibutton>To Clipboard</guibutton> stores the data in a file or on the
clipboard. <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> close
the dialog, whereas <guibutton>OK</guibutton> accepts the current dialog
settings.
</para></listitem> 
</varlistentry>

<varlistentry id="create-playlist">
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Create Playlist</guimenuitem>
</menuchoice></term>
<listitem><para>
<action>Creates a playlist.</action> The format and contents of the playlist
can be set by various options.</para>
<para>
The name of the playlist can be the <guibutton>Same as directory
name</guibutton> or use a <guibutton>Format</guibutton> with values
from the tags, e.g. "%{artist} - %{album}" to have the artist and album
name in the playlist file name. The format codes are the same as for
<link linkend="export">Export</link>. The extension depends on the playlist
format.
</para>
<para>
The location of the generated playlist is determined by the selection of
the <guilabel>Create in</guilabel> combo box.
<variablelist>
<varlistentry><term>Current directory</term>
<listitem><para>The playlist is created in the current directory and contains
only files of the current directory.</para></listitem></varlistentry>
<varlistentry><term>Every directory</term>
<listitem><para>A playlist is created in every directory which contains
listed files, and each playlist contains the files of that directory.
</para></listitem></varlistentry>
<varlistentry><term>Top-level directory</term>
<listitem><para>Only one playlist is created in the top-level
directory (i.e. the directory of the file list) and it contains the listed
files of the top-level directory and all of its sub-directories.
</para></listitem></varlistentry>
</variablelist>
</para>
<para>
The <guilabel>Format</guilabel> of the playlist can
be <guilabel>M3U</guilabel>, <guilabel>PLS</guilabel> or
<guilabel>XSPF</guilabel>.
</para>
<para>
If <guibutton>Include only the selected files</guibutton> is checked, only the
selected files will be included in the playlist. If a directory is selected,
all of its files are selected. If this check box is not activated, all audio
files are included in the playlist.
</para>
<para>
<guibutton>Sort by file name</guibutton> selects the usual case where the
files are ordered by file name. With <guibutton>Sort by tag field</guibutton>,
it is possible to sort by a format string with values from tag fields. For
instance, "%{track.3}" can be used to sort by track number (the ".3" is used
to get three digits with leading zeros because strings are used for
sorting). It is also possible to use multiple fields, e.g. "%{genre}%{year}"
to sort using a string composed of genre and year.
</para>
<para>
The playlist entries will have relative or absolute file paths depending on
whether <guibutton>Use relative path for files in playlist</guibutton> or
<guibutton>Use full path for files in playlist</guibutton> is set.
</para>
<para>
When <guibutton>Write only list of files</guibutton> is set, the playlist
will only contain the paths to the files. To generate an extended playlist
with additional information, a format string can be set using
the <guibutton>Write info using</guibutton> control.
</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits the application.</action></para></listitem>
</varlistentry>

</variablelist>
</para>

</sect2>

<sect2 id="edit-menu">
<title>The Edit Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>A</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Select All</guimenuitem>
</menuchoice></term>
<listitem><para>Selects all files.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>A</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Deselect</guimenuitem>
</menuchoice></term>
<listitem><para>Deselects all files.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Previous File</guimenuitem>
</menuchoice></term>
<listitem><para>Selects the previous file.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Next File</guimenuitem>
</menuchoice></term>
<listitem><para>Selects the next file.</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2 id="tools-menu">
<title>The Tools Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Apply Filename Format</guimenuitem>
</menuchoice></term>
<listitem><para>When <guilabel>Format while editing</guilabel> is switched off
for the filename format in the configuration dialog, this menu item can be used to <action>apply
the configured format to the names of the selected files</action>. This can also be used
to check whether the file names conform with the configured format
by applying the format to all saved files and then checking if any files were
changed (and therefore marked with a disk symbol in the file listbox).
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Apply ID3 Format</guimenuitem>
</menuchoice></term>
<listitem><para>When <guilabel>Format while editing</guilabel> is switched off
for the ID3 format in the configuration dialog, this menu item can be used to <action>apply
the configured format to the tags of the selected files</action>. This can also be used
to check whether the tags conform with the configured format
by applying the format to all saved files and then checking if any files were
changed (and therefore marked with a disk symbol in the file listbox).
</para></listitem>
</varlistentry>

<varlistentry id="rename-directory">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Rename Directory...</guimenuitem>
</menuchoice></term>
<listitem><para>This dialog offers the possibility to automatically rename the
currently open directory according to the tags in the files. Several formats
are preconfigured to include information about artist, album and year in the
directory name. It is also possible to set a custom format, the following
special codes are used to insert tag values into the directory name:
</para>

<itemizedlist>
<listitem><para>%s %{title} Title (Song)</para></listitem>
<listitem><para>%a %{artist} Artist</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Comment</para></listitem>
<listitem><para>%y %{year} Year</para></listitem>
<listitem><para>%t %{track} Track (e.g. 01)</para></listitem>
<listitem><para>%t %{track.n} Track with field width n (e.g. 001 for %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Track (without leading zeroes, e.g. 1)</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
</itemizedlist>

<para>
If a directory separator "/" is found in the format, multiple directories are
created. If you want to create a new directory instead of renaming the current
directory, select <guilabel>Create Directory</guilabel> instead of
<guilabel>Rename Directory</guilabel>. The source of the tag information can
be chosen between <guilabel>From Tag 1 and Tag 2</guilabel>,
<guilabel>From Tag 1</guilabel> and <guilabel>From Tag 2</guilabel>.
A preview for the rename operation performed on the first
file can be seen in the <guilabel>From</guilabel> and <guilabel>To</guilabel>
sections of the dialog.
</para></listitem>
</varlistentry>

<varlistentry id="number-tracks">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Number Tracks...</guimenuitem>
</menuchoice></term>
<listitem><para>
If the track numbers in the tags are not set or have the wrong values, this
function can <action>number the tracks automatically in ascending
order</action>. The start number can be set in the dialog. If only part of the
tracks have to be numbered, they must be selected.
</para><para>
When <guilabel>Total number of tracks</guilabel> is checked, the number
of tracks will also be set in the tags.
</para></listitem>
</varlistentry>

<varlistentry id="filter">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Filter...</guimenuitem>
</menuchoice></term>
<listitem>
<para>
The filter can be used to display only those files which match certain
criteria. This is helpful if you want to organize a large collection and only
edit those files which are not in the desired scheme. The expression defining
which files to display uses the same format codes which are used in the file
name format, import and export.
</para>

<itemizedlist>
<listitem><para>%s %{title} Title (Song)</para></listitem>
<listitem><para>%a %{artist} Artist</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Comment</para></listitem>
<listitem><para>%y %{year} Year</para></listitem>
<listitem><para>%t %{track} Track (e.g. 01)</para></listitem>
<listitem><para>%t %{track.n} Track with field width n (e.g. 001 for %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Track (without leading zeroes, e.g. 1)</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%f %{file} File name</para></listitem>
<listitem><para>%p %{filepath} Absolute path to file</para></listitem>
<listitem><para>%e %{extension} File extension</para></listitem>
<listitem><para>%O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
existing)</para></listitem>
<listitem><para>%o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not existing)</para></listitem>
<listitem><para>%b %{bitrate} Bitrate in kbit/s</para></listitem>
<listitem><para>%v %{vbr} VBR or empty (only for ID3v2.3 with
id3lib)</para></listitem>
<listitem><para>%r %{samplerate} Samplerate in Hz</para></listitem>
<listitem><para>%m %{mode} Channel mode (Stereo or Joint Stereo)</para></listitem>
<listitem><para>%h %{channels} Number of channels (1 or 2)</para></listitem>
<listitem><para>%k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
MPC, ASF, AIFF, WAV)</para></listitem>
<listitem><para>%1a %1{artist}, ... Use the prefix 1 to get values of tag 1</para></listitem>
<listitem><para>%2a %2{artist}, ... Use the prefix 2 to get values of tag 2</para></listitem>
</itemizedlist>

<para>
These codes are replaced with the values for
the file, and the resulting strings can be compared with the following
operations:
</para>
<itemizedlist>
<listitem><para>s1 equals s2: true if s1 and s2 are equal.</para></listitem>
<listitem><para>s1 contains s2: true if s1 contains s2, i.e. s2 is a
substring of s1.</para></listitem>
<listitem><para>s matches re: true if s matches the regular expression re.</para></listitem>
</itemizedlist>
<para>
True expressions are replaced by 1, false by 0. True values are represented by
1, true, on and yes, false values by 0, false, off and no. Boolean operations
are not, and, or (in this order of precedence) and can be grouped by parentheses.
</para>
<para>
Some filter rules are predefined and can serve as examples for your own
expressions:
</para>

<variablelist>
<varlistentry><term>All</term><listitem>
<para>
When the file list is filtered - this is shown by "[filtered]" in the
window title - and all files shall be displayed again,
the filtering can be reverted using this filter. It uses an empty expression,
but a true value would have the same effect.
</para>
</listitem></varlistentry>

<varlistentry><term>Filename Tag Mismatch</term><listitem>
<para><userinput>
not (%{filepath} contains "%{artist} - %{album}/%{track} %{title}")
</userinput></para>
<para>
Tests if the file path conforms with the file name format. This
rule is automatically adapted if the file name format changes.
</para>
</listitem></varlistentry>

<varlistentry><term>No Tag 1</term><listitem>
<para><userinput>
%{tag1} equals ""
</userinput></para>
<para>Displays only files which do not have a tag 1.</para>
</listitem></varlistentry>

<varlistentry><term>No Tag 2</term><listitem>
<para><userinput>
%{tag2} equals ""
</userinput></para>
<para>Displays only files which do not have a tag 2.</para>
</listitem></varlistentry>

<varlistentry><term>ID3v2.3.0 Tag</term><listitem>
<para><userinput>
%{tag2} equals "ID3v2.3.0"
</userinput></para>
<para>Displays only files which have an ID3v2.3.0 tag.</para>
</listitem></varlistentry>

<varlistentry><term>ID3v2.4.0 Tag</term><listitem>
<para><userinput>
%{tag2} equals "ID3v2.4.0"
</userinput></para>
<para>Displays only files which have an ID3v2.4.0 tag.</para>
</listitem></varlistentry>

<varlistentry><term>Tag 1 != Tag 2</term><listitem>
<para><userinput>
not (%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist}
equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals
%2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre})
</userinput></para>
<para>Displays files with differences between tag 1 and tag2.</para>
</listitem></varlistentry>

<varlistentry><term>Tag 1 == Tag 2</term><listitem>
<para><userinput>
%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist}
equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals
%2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre}
</userinput></para>
<para>Displays files with identical tag 1 and tag 2.</para>
</listitem></varlistentry>

<varlistentry><term>No Picture</term><listitem>
<para><userinput>
%{picture} equals ""
</userinput></para>
<para>Displays only files which do not have a picture.</para>
</listitem></varlistentry>

<varlistentry><term>Custom Filter</term><listitem>
<para>
To add your own filter, select this entry. For instance, if you want
to have a filter for artists starting with "The", replace "Custom Filter"
with the name "The Bands" and press Enter. Then insert the following
expression into the line edit:
</para>
<para><userinput>
%{artist} matches "The.*"
</userinput></para>
<para>
Then click <guibutton>Save
Settings</guibutton>. Click <guibutton>Apply</guibutton> to filter the
files. All files processed are displayed in the text view, with a "+" for
those who match the filter and a "-"  for the others. When finished, only the
files with an artist starting with "The" are displayed, and the window title
is marked with "[filtered]".
</para>
</listitem></varlistentry>

</variablelist>
</listitem>
</varlistentry>

<varlistentry id="convert-to-id3v24">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Convert ID3v2.3 to ID3v2.4</guimenuitem>
</menuchoice></term>
<listitem><para>
If there are any ID3v2.3 tags in the selected files, they will
be <action>converted to ID3v2.4</action> tags. Frames which are not supported
by TagLib will be discarded. Only files without unsaved changes will be converted.
</para></listitem>
</varlistentry>

<varlistentry id="convert-to-id3v23">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Convert ID3v2.4 to ID3v2.3</guimenuitem>
</menuchoice></term>
<listitem><para>
If there are any ID3v2.4 tags in the selected files, they will
be <action>converted to ID3v2.3</action> tags. Only files without
unsaved changes will be converted.
</para></listitem>
</varlistentry>

<varlistentry id="play">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Play</guimenuitem>
</menuchoice></term>
<listitem><para>
This opens a simple toolbar to play audio files. It contains buttons for the
basic operations (<guibutton>Play/Pause</guibutton>,
<guibutton>Stop playback</guibutton>, <guibutton>Previous Track</guibutton>,
<guibutton>Next Track</guibutton>, <guibutton>Close</guibutton>),
sliders for position and volume and a display of the current position.
If multiple files are selected, the selected tracks are played, else all
files will be played.
</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2 id="settings-menu">
<title>The Settings Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Toolbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles displaying of the toolbar.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Statusbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles displaying of the statusbar</action>, which displays
longer actions such as opening or saving a directory.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Hide Picture</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles displaying of the album cover art preview
picture.</action>
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Auto Hide Tags</guimenuitem>
</menuchoice></term>
<listitem><para>
Empty tags are automatically hidden if this option is active.
The <guilabel>File</guilabel>, <guilabel>Tag 1</guilabel>
and <guilabel>Tag 2</guilabel> sections can be manually collapsed and expanded
by clicking on the corresponding
<guibutton>-</guibutton>/<guibutton>+</guibutton> buttons.
</para></listitem>
</varlistentry>

<varlistentry id="configure-kid3">
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Kid3...</guimenuitem>
</menuchoice></term>
<listitem><para>Opens the <action>configuration dialog</action>, which
consists of pages for tags, files, user actions, and network settings.
</para>
<para>
Tag specific options can be found on the <guilabel>Tags</guilabel> page.
</para>
<para>
If <guilabel>Mark truncated fields</guilabel> is checked, truncated ID3v1.1
fields will be marked red. The text fields of ID3v1.1 tags can only have 30
characters, the comment only 28 characters. Also the genre and track numbers
are restricted, so that fields can be truncated when imported or transfered
from ID3v2. Truncated fields and the file will be marked red, and the mark
will be removed after the field has been edited.
</para>
<para>
With <guilabel>Text encoding</guilabel> for <guilabel>ID3v1</guilabel> it is
possible to set the character set used in ID3v1 tags. This encoding is
supposed to be ISO-8859-1, so it is recommended to keep this default
value. However, there are tags around with different encoding, so it can be
set here and the ID3v1 tags can then be copied to ID3v2 which supports Unicode.
</para>
<para>
The check box <guilabel>Use track/total number of tracks
format</guilabel> controls whether the track number field of ID3v2 tags
contains simply the track number or additionally the total number of tracks in
the directory.
</para>
<para>
When <guilabel>Genre as text instead of numeric string</guilabel> is checked,
all ID3v2 genres will be stored as a text string even if there is a
corresponding code for ID3v1 genres. If this option is not set, genres for which
an ID3v1 code exists are stored as the number of the genre code (in
parentheses for ID3v2.3). Thus the genre Metal is stored as "Metal" or "(9)"
depending on this option. Genres which are not in the list of ID3v1 genres are
always stored as a text string. The purpose of this option is improved
compatibility with devices which do not correctly interpret genre codes.
</para>
<para>
<guilabel>Text encoding</guilabel> defines the default encoding used for ID3v2
frames and can be set
to <guilabel>ISO-8859-1</guilabel>, <guilabel>UTF16</guilabel>,
or <guilabel>UTF8</guilabel>. <guilabel>UTF8</guilabel> is not valid for
ID3v2.3.0 frames; if it is set, <guilabel>UTF16</guilabel> will be used
instead. For ID3v2.4.0 frames, all three encodings are possible.
</para>
<para>
<guilabel>Version used for new tags</guilabel> determines whether new ID3v2
tags are created as version 2.3.0 or 2.4.0. In the first case, id3lib is used
as it was in earlier versions of &kid3; and TagLib is only applied when an
ID3v2.4.0 tag is encountered. In the second case, <guilabel>ID3v2.4.0
(TagLib)</guilabel>, TagLib is generally used for MP3 files; changed or newly
created tags will then be saved in version 2.4.0.
</para>
<para>
<guilabel>Track number digits</guilabel> is the number of digits in Track
Number fields. Leading zeros are used to pad. For instance, with a value of 2
the track number 5 is set as "05".
</para>
<para>
The combo box <guilabel>Comment field name</guilabel> is only
relevant for Ogg/Vorbis and FLAC files and sets the name of the field used for
comments. Different applications seem to use different names, "COMMENT" for
instance is used by xmms, whereas amaroK uses "DESCRIPTION".
</para>
<para>
The format of pictures in Ogg/Vorbis files is determined by
<guilabel>Picture field name</guilabel>, which can be
<guilabel>METADATA_BLOCK_PICTURE</guilabel> or <guilabel>COVERART</guilabel>.
The first is the official standard and uses the same format as pictures in
FLAC tags. COVERART is an earlier unofficial way to include pictures in
Vorbis comments. It can be used for compatibility with legacy players.
</para>
<para>
<guilabel>Custom Genres</guilabel> can be used to define genres which are not
available in the standard genre list, e.g. "Gothic Metal". Such custom genres
will appear in the <guilabel>Genre</guilabel> combo box of
<guilabel>Tag 2</guilabel>. For ID3v1.1 tags, only the predefined genres can
be used.
</para>
<para>
The list of custom genres can also be used to reduce the number of genres
available in the <guilabel>Genre</guilabel> combo box to those typically used.
If your collection mostly contains music in the genres Metal, Gothic Metal,
Ancient and Hard Rock, you can enter those genres and mark
<guilabel>Show only custom genres</guilabel>. The <guilabel>Tag 2</guilabel>
<guilabel>Genre</guilabel> combo box will then only contain those four genres
and you will not have to search through the complete genres list for them.
In this example, only Metal and Hard Rock will be listed in the tag 1 genres
list, because those two custom genres entries are standard genres.
If <guilabel>Show only custom genres</guilabel> is not active, the custom
genres can be found at the end of the genres list.
</para>
<para>
<guilabel>Tag Format</guilabel> contains options for the format of the tags.
When <guilabel>Format while editing</guilabel> is checked, the format
configuration is automatically used while editing text in the line edits.
The <guilabel>Case conversion</guilabel> can be set to <guilabel>No
changes</guilabel>, <guilabel>All lowercase</guilabel>, <guilabel>All
uppercase</guilabel>, <guilabel>First letter uppercase</guilabel> or
<guilabel>All first letters uppercase</guilabel>. 
The string replacement list can be set to arbitrary string mappings. To add a
new mapping, select the <guilabel>From</guilabel> cell of a row and insert the
text to replace, then go to the <guilabel>To</guilabel> column and enter the
replacement text. To remove a mapping set the <guilabel>From</guilabel> cell
to an empty value (e.g. by first typing space and then backspace). Inserting
and deleting rows is also possible using a context menu which appears when the
right mouse button is clicked.  Replacement is only active, if the
<guilabel>String replacement</guilabel> checkbox is checked.
</para>
<para>
On the page <guilabel>Files</guilabel> the check box <guilabel>Preserve file
timestamp</guilabel> can be marked to preserve the file modification time
stamp.
</para>
<para>
If <guilabel>Mark changes</guilabel> is active, changed fields are marked with
a light gray label background.
</para>
<para>
<guilabel>Filename Format</guilabel> contains options for the format of the
filenames. The same options as in <guilabel>Tag Format</guilabel> are available.
</para>
<para>
The <guilabel>User Actions</guilabel> page contains a table with the commands which are available in the context menu of the file list. For critical
operations such as deleting files, it is advisable to mark
<guilabel>Confirm</guilabel> to pop up a confirmation dialog before executing
the command.
<guilabel>Output</guilabel> can be marked to see the output written by console
commands (standard output and standard error). <guilabel>Name</guilabel> is
the name displayed in the context menu. <guilabel>Command</guilabel> is the
command line to be executed. Arguments can be passed using the following
codes:
</para>

<itemizedlist>
<listitem><para>%F %{files} File paths (a list if multiple files selected)</para></listitem>
<listitem><para>%f %{file} File path to single file</para></listitem>
<listitem><para>%uF %{urls} URLs (a list if multiple files selected)</para></listitem>
<listitem><para>%uf %{url} URL to single file</para></listitem>
<listitem><para>%d %{directory} Directory</para></listitem>
<listitem><para>%s %{title} Title (Song)</para></listitem>
<listitem><para>%a %{artist} Artist</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Comment</para></listitem>
<listitem><para>%y %{year} Year</para></listitem>
<listitem><para>%t %{track} Track (e.g. 01)</para></listitem>
<listitem><para>%t %{track.n} Track with field width n (e.g. 001 for %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Track (without leading zeroes, e.g. 1)</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%b %{browser} Command to start the web browser</para></listitem>
</itemizedlist>

<para>
The command which will be inserted with %{browser} can be defined in the
<guilabel>Web browser</guilabel> line edit above. Commands starting with %{browser}
can be used to fetch information about the audio files from the web,
for instance
<screen width="40">
<userinput>%{browser} http://lyricwiki.org/%u{artist}:%u{title}</userinput>
</screen>
will query the lyrics for the current song in
<ulink url="http://www.lyricwiki.org">LyricWiki</ulink>. The "u" in %u{artist} and %u{title}
is used to URL-encode the artist %{artist} and song %{title} information. It is easy to
define your own queries in the same way, e.g. an image search with
<ulink url="http://www.google.com">Google</ulink>:
<screen width="40">
<userinput>%{browser} http://images.google.com/images?q=%u{artist}%20%u{album}</userinput>
</screen>
</para>
<para>
To add album cover art to tag 2, you can search for images with Google or
Amazon using the commands described above. The picture can be added to the tag
with drag and drop. You can also add an image with <guibutton>Add</guibutton>, then select
the Picture frame and import an image file or paste from the
clipboard. Picture frames are supported for ID3v2, MP4, FLAC, Ogg and ASF tags.
</para>
<para> 
To add and delete entries in the table, a context menu can be
used.
</para>
<para>
The <guilabel>Network</guilabel> page contains only a field to insert the proxy
address and optionally the port, separated by a colon. The proxy will be used
when importing from an internet server when the checkbox is checked.
</para>
</listitem>
</varlistentry>

<varlistentry id="configure-shortcuts">
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem><para>Opens a dialog to assign keyboard shortcuts for most of the
program functions. There are even functions without corresponding menu or
button available, e.g. next file, previous file, select all.
</para>
<para>
</para>
</listitem>
</varlistentry>

</variablelist>
</para>

</sect2>

<sect2 id="help-menu">
<title>The Help Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu>
<guimenuitem>Kid3 Handbook</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens this handbook.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu>
<guimenuitem>About Kid3</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays a short information about Kid3;.
</action></para></listitem>
</varlistentry>


</variablelist>
</para>

</sect2>

</sect1>
</chapter>


<chapter id="credits">

<title>Credits and License</title>

<para>
&kid3;
</para>
<para>
Program written by Urs Fleisch <email>ufleisch@users.sourceforge.net</email>
</para>


&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kid3">
<title>How to obtain Kid3</title>

<para>
&kid3; can be found at
<ulink url="http://kid3.sourceforge.net">http://kid3.sourceforge.net</ulink>.
</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
&kid3; needs <ulink url="http://www.trolltech.com/qt/">Qt</ulink>. <ulink
url="http://www.kde.org">KDE</ulink> is recommended but not necessary, as
&kid3; can also be compiled as a Qt application. &kid3; can be compiled for
systems where these libraries are available, e.g. for GNU/Linux, Windows
and Mac OS X.

To tag Ogg/Vorbis
files, <ulink url="http://xiph.org/ogg/">libogg</ulink>,
<ulink url="http://xiph.org/vorbis/">libvorbis and libvorbisfile</ulink> are
required, for FLAC files <ulink url="http://flac.sourceforge.net">libFLAC++
and libFLAC</ulink>.
<ulink url="http://id3lib.sourceforge.net">id3lib</ulink> is used for MP3
 files.
<ulink url="http://code.google.com/p/mp4v2">mp4v2</ulink> is required for
MP4 files.
These four formats are also supported by
<ulink url="http://developer.kde.org/~wheeler/taglib.html">TagLib</ulink>,
which can also handle MPC, MP2, Speex, TrueAudio, WavPack, WMA, WAV and AIFF files. 
For MusicBrainz support,
<ulink url="http://musicbrainz.org/doc/libtunepimp">libtunepimp</ulink>
is used. As there does not exist a tunepimp SDK for Windows at the moment, the
Windows version is compiled without MusicBrainz import. 
</para>
<para>
&kid3; is available for most Linux distributions, Windows and Mac OS X.
Links can be found on <ulink url="http://kid3.sourceforge.net">
http://kid3.sourceforge.net</ulink>.
</para>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>
You can compile &kid3; with or without KDE. Without KDE, &kid3; is a
simple Qt application and lacks some configuration and session features.
</para>
<para>
For a KDE 4 version, go into the top directory and type 
<screen width="40">
<prompt>%</prompt> <userinput>cmake .</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>
<para>
To compile for different versions of Qt or KDE, set the corresponding
<userinput>configure</userinput> options.
</para>
<para>
If not all libraries are present, &kid3; is built with reduced functionality.
So you should take care to have all desired development packages installed.
On the other side, <userinput>cmake</userinput>-options control which
libraries are compiled in. The default is
<userinput>-D WITH_TAGLIB:BOOL=ON -D WITH_MP4V2:BOOL=ON -D WITH_ID3LIB:BOOL=ON
-D WITH_TUNEPIMP:BOOL=ON -D WITH_VORBIS:BOOL=ON -D WITH_FLAC:BOOL=ON
</userinput>. These options can be disabled using
<userinput>OFF</userinput>.
</para>
<para>
To build &kid3; as a Qt application without KDE, use
<userinput>configure</userinput> and <userinput>make</userinput>
from the <filename>kid3-qt</filename> directory. The
<userinput>configure</userinput> script can be generated with
<userinput>autoconf</userinput>.
<screen width="40">
<prompt>%</prompt> <userinput>cd kid3-qt</userinput>
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>
<para>
Available options are
<userinput>--with-kde --with-id3lib --with-vorbis --with-flac --with-taglib
--with-musicbrainz</userinput> and can be disabled using <userinput>--without-
</userinput>. If multiple versions of Qt are installed, the version can be set
e.g. using <userinput>--with-qmake=qmake-qt4</userinput>.
</para>
<para>
Generation of RPM-Packages is supported by the
file <filename>kid3.spec</filename>, for Debian-Packages,
the script <filename>build-deb.sh</filename>is available.
</para>
<para>
To build &kid3; with KDE 3, use <command>configure</command>:
<screen width="40">
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>
<para>
If the sources are downloaded from Subversion, the
<userinput>configure</userinput> script can be built with 
<screen width="40">
<prompt>%</prompt> <userinput>make -f Makefile.cvs</userinput>
</screen>
</para>
<para>
To speed up compilation, &kid3; can use precompiled headers with GCC
3.4 and above. Start <userinput>configure</userinput> with the option
<userinput>--enable-gcc-pch</userinput> (and setting CC and CXX to gcc and g++
of GCC 3.4 if it is not the default compiler). Then create a precompiled system
include file with <userinput>make pch</userinput>.
</para>

<para>
The Qt application can also be compiled for Windows and Mac OS X.
The scripts in the folders <filename>win32</filename> and
<filename>macosx</filename>  can be used to build and create packages.
The libraries can be installed using <filename>buildlibs.sh</filename>.
</para>

</sect1>

<sect1 id="configuration">
<title>Configuration</title>

<para>With KDE, the file name filter and format, the import formats, the
filename and ID3 formats, the toolbar and statusbar
settings as well as the window size will be be saved in the standard
location in file <filename>kid3rc</filename>.
As a Qt application, this file is in the <filename>.qt</filename> directory,
with Qt 4 in <filename>.config/kid3.sourceforge.net/Kid3.conf</filename>,
with older releases of Qt, a file <filename>kid3.cfg</filename> is created.
On Windows, the configuration is stored in the registry.
</para>

</sect1>

</appendix>

<appendix id="dbus-interface">
<title>D-Bus Interface</title>

<sect1 id="dbus-examples">
<title>D-Bus Examples</title>

<para>
The Qt 4 and KDE 4 versions on Linux offer a D-Bus-Interface to control
&kid3; by scripts. Scripts can be written in any language with D-Bus-bindings
(e.g. in Python) and can be added to the <guilabel>User Actions</guilabel> to
extend the functionality of &kid3;.
</para>

<para>
The artist in tag 2 of the current file can be set to the value "One Hit Wonder"
with the following code:
</para>

<variablelist>
<varlistentry><term>Shell</term>
<listitem>
<programlisting>
dbus-send --dest=net.sourceforge.kid3 --print-reply=literal \
/Kid3 net.sourceforge.Kid3.setFrame int32:2 string:'Artist' \
string:'One Hit Wonder'
</programlisting>
<para>
or easier with Qt's <command>qdbus</command> (<command>qdbusviewer</command>
can be used to explore the interface in a GUI):
</para>
<programlisting>
qdbus net.sourceforge.kid3 /Kid3 setFrame 2 Artist \
'One Hit Wonder'
</programlisting>
</listitem>
</varlistentry>
<varlistentry><term>Python</term>
<listitem>
<programlisting>
import dbus
kid3 = dbus.SessionBus().get_object(
  'net.sourceforge.kid3', '/Kid3')
kid3.setFrame(2, 'Artist', 'One Hit Wonder')
</programlisting>
</listitem>
</varlistentry>
<varlistentry><term>Perl</term>
<listitem>
<programlisting>
use Net::DBus;
$kid3 = Net::DBus->session->get_service(
  "net.sourceforge.kid3")->get_object(
  "/Kid3", "net.sourceforge.Kid3");
$kid3->setFrame(2, "Artist", "One Hit Wonder");
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="dbus-api">
<title>D-Bus API</title>

<para>
The D-Bus API is specified
in <filename>net.sourceforge.Kid3.xml</filename>. The Kid3 interface has the
following methods:
</para>

<sect2 id="dbus-openDirectory">
<title>Open file or directory</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>openDirectory</function></funcdef>
  <paramdef>string <parameter>path</parameter> path to file or directory</paramdef>
</funcprototype>
</funcsynopsis>
<para>Returns true if ok.</para>
</sect2>

<sect2 id="dbus-save">
<title>Save all modified files</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>save</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns true if ok.</para>
</sect2>

<sect2 id="dbus-getErrorMessage">
<title>Get a detailed error message provided by some methods</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getErrorMessage</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns detailed error message.</para>
</sect2>

<sect2 id="dbus-revert">
<title>Revert changes in the selected files</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>revert</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-importFromFile">
<title>Import tags from a file</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>importFromFile</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
  <paramdef>string <parameter>path</parameter> path of file</paramdef>
  <paramdef>int32 <parameter>fmtIdx</parameter> index of format</paramdef>
</funcprototype>
</funcsynopsis>
<para>Returns true if ok.</para>
</sect2>

<sect2 id="dbus-downloadAlbumArt">
<title>Download album cover art</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>downloadAlbumArt</function></funcdef>
  <paramdef>string <parameter>url</parameter> URL of picture file or album art
  resource</paramdef>
  <paramdef>boolean <parameter>allFilesInDir</parameter> true to add the image
  to all files in the directory</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-exportToFile">
<title>Export tags to a file</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>exportToFile</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
  <paramdef>string <parameter>path</parameter> path of file</paramdef>
  <paramdef>int32 <parameter>fmtIdx</parameter> index of format</paramdef>
</funcprototype>
</funcsynopsis>
<para>Returns true if ok.</para>
</sect2>

<sect2 id="dbus-createPlaylist">
<title>Create a playlist</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>createPlaylist</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns true if ok.</para>
</sect2>

<sect2 id="dbus-quit">
<title>Quit the application</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>quit</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-selectAll">
<title>Select all files</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>selectAll</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-deselectAll">
<title>Deselect all files</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>deselectAll</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-firstFile">
<title>Select the first file</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>firstFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns true if there is a first file.</para>
</sect2>

<sect2 id="dbus-previousFile">
<title>Select the previous file</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>previousFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns true if there is a previous file.</para>
</sect2>

<sect2 id="dbus-nextFile">
<title>Select the next file</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>nextFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns true if there is a next file.</para>
</sect2>

<sect2 id="dbus-expandDirectory">
<title>Expand or collapse the current file item if it is a directory</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>expandDirectory</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>A file list item is a directory if getFileName() returns a name with
      '/' as the last character.</para>
<para>Returns true if current file item is a directory.</para>
</sect2>

<sect2 id="dbus-applyFilenameFormat">
<title>Apply the file name format</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>applyFilenameFormat</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-applyTagFormat">
<title>Apply the tag format</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>applyTagFormat</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-setDirNameFromTag">
<title>Set the directory name from the tags</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>setDirNameFromTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag mask (bit 0 for tag 1, bit 1 for tag 2)</paramdef>
  <paramdef>string <parameter>format</parameter> directory name format</paramdef>
  <paramdef>boolean <parameter>create</parameter> true to create, false to rename</paramdef>
</funcprototype>
</funcsynopsis>
<para>Returns true if ok, else the error message is available using getErrorMessage().</para>
</sect2>

<sect2 id="dbus-numberTracks">
<title>Set subsequent track numbers in the selected files</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>numberTracks</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag mask (bit 0 for tag 1, bit 1 for tag 2)</paramdef>
  <paramdef>int32 <parameter>firstTrackNr</parameter> number to use for first file</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-filter">
<title>Filter the files</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>filter</function></funcdef>
  <paramdef>string <parameter>expression</parameter> filter expression</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-convertToId3v24">
<title>Convert ID3v2.3 tags to ID3v2.4</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>convertToId3v24</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-convertToId3v23">
<title>Convert ID3v2.4 tags to ID3v2.3</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>convertToId3v23</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns true if ok.</para>
</sect2>

<sect2 id="dbus-getDirectoryName">
<title>Get path of directory</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getDirectoryName</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns absolute path of directory.</para>
</sect2>

<sect2 id="dbus-getFileName">
<title>Get name of current file</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getFileName</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Returns true absolute file name, ends with "/" if it is a directory.</para>
</sect2>

<sect2 id="dbus-setFileName">
<title>Set name of selected file</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setFileName</function></funcdef>
  <paramdef>string <parameter>name</parameter> file name</paramdef>
</funcprototype>
</funcsynopsis>
<para>The file will be renamed when the directory is saved.</para>
</sect2>

<sect2 id="dbus-setFileNameFormat">
<title>Set format to use when setting the filename from the tags</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setFileNameFormat</function></funcdef>
  <paramdef>string <parameter>format</parameter> file name format</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-setFileNameFromTag">
<title>Set the file names of the selected files from the tags</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setFileNameFromTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-getFrame">
<title>Get value of frame</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getFrame</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
  <paramdef>string <parameter>name</parameter> name of frame (e.g. "artist")</paramdef>
</funcprototype>
</funcsynopsis>
<para>To get binary data like a picture, the name of a file to write can be
      added after the <parameter>name</parameter>, e.g. "Picture:/path/to/file".</para>
<para>Returns value of frame.</para>
</sect2>

<sect2 id="dbus-setFrame">
<title>Set value of frame</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>setFrame</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
  <paramdef>string <parameter>name</parameter> name of frame (e.g. "artist")</paramdef>
  <paramdef>string <parameter>value</parameter> value of frame</paramdef>
</funcprototype>
</funcsynopsis>
<para>For tag 2 (<parameter>tagMask</parameter> 2), if no frame with <parameter>name</parameter> exists, a new frame
      is added, if <parameter>value</parameter> is empty, the frame is deleted.
      To add binary data like a picture, a file can be added after the
      <parameter>name</parameter>, e.g. "Picture:/path/to/file".</para>
<para>Returns true if ok.</para>
</sect2>

<sect2 id="dbus-getTag">
<title>Get all frames of a tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef>array of string <function>getTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
</funcprototype>
</funcsynopsis>
<para>Returns list with alternating frame names and values.</para>
</sect2>

<sect2 id="dbus-getInformation">
<title>Get technical information about file</title>
<funcsynopsis>
<funcprototype>
  <funcdef>array of string <function>getInformation</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Properties are Format, Bitrate, Samplerate, Channels, Duration,
      Channel Mode, VBR, Tag 1, Tag 2.
      Properties which are not available are omitted.</para>
<para>Returns list with alternating property names and values.</para>
</sect2>

<sect2 id="dbus-setTagFromFileName">
<title>Set tag from file name</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setTagFromFileName</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-setTagFromOtherTag">
<title>Set tag from other tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setTagFromOtherTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-copyTag">
<title>Copy tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>copyTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-pasteTag">
<title>Paste tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>pasteTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-removeTag">
<title>Remove tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>removeTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-hideTag">
<title>Hide or show tag in GUI</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>hideTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter> tag bit (1 for tag 1, 2 for tag 2)</paramdef>
  <paramdef>boolean <parameter>hide</parameter> true to hide tag</paramdef>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-reparseConfiguration">
<title>Reparse the configuration</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>reparseConfiguration</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Automated configuration changes are possible by modifying
      the configuration file and then reparsing the configuration.</para>
</sect2>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->