Warning, /multimedia/kid3/doc/en/index.docbook is written in an unsupported language. File is not indexed.

 <?xml version="1.0" ?>
 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
   <!ENTITY kid3 '<application>Kid3</application>'>
   <!ENTITY doublehyphen '--'>
   <!ENTITY % addindex "IGNORE">
   <!ENTITY % English "INCLUDE"><!-- change language only here -->
 ]>
 <book lang="&language;" id="kid3-handbook">
 
 <bookinfo>
 <title>The &kid3; Handbook</title>
 
 <authorgroup>
 <author>
 <firstname>Urs</firstname>
 <surname>Fleisch</surname>
 <affiliation>
 <address><email>ufleisch@users.sourceforge.net</email></address>
 </affiliation>
 <contrib>Software development</contrib>
 </author>
 
 <!-- TRANS:ROLES_OF_TRANSLATORS -->
 </authorgroup>
 
 <copyright>
 <year>2024</year>
 <holder>Urs Fleisch</holder>
 </copyright>
 <legalnotice id="fdl-notice">&FDLNotice;</legalnotice>
 
 <date>2024-02-24</date>
 <releaseinfo>3.9.5</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, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex,
 TrueAudio, WavPack, WMA, WAV, AIFF files and tracker modules (MOD, S3M, IT, XM) are supported.
 It is easy to set tags of multiple files to the same
 values (<abbrev>e.g.</abbrev> 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>
 <keyword>MOD</keyword>
 <keyword>S3M</keyword>
 <keyword>IT</keyword>
 <keyword>XM</keyword>
 <keyword>Opus</keyword>
 <keyword>DSF</keyword>
 </keywordset>
 
 </bookinfo>
 
 <!--begin manpage include
 <refmeta>
 <refentrytitle>kid3</refentrytitle>
 <manvolnum>1</manvolnum>
 </refmeta>
 
 <refnamediv>
 <refname>kid3</refname>
 <refname>kid3-qt</refname>
 <refname>kid3-cli</refname>
 <refpurpose>Kid3 ID3 Tagger</refpurpose>
 </refnamediv>
 end manpage include-->
 
 <!--change manpage<refsynopsisdiv>--><preface id="synopsis"><title>Synopsis</title>
 <cmdsynopsis>
 <command>kid3</command>
 <group>
 <arg choice="plain"><option>&doublehyphen;help</option></arg>
 <arg choice="plain"><option>&doublehyphen;author</option></arg>
 <arg choice="plain"><option>&doublehyphen;version</option></arg>
 <arg choice="plain"><option>&doublehyphen;license</option></arg>
 <arg choice="plain"><option>&doublehyphen;desktopfile
 <filename>FILE</filename></option></arg>
 </group>
 <arg rep="repeat"><replaceable>FILE</replaceable></arg>
 </cmdsynopsis>
 <cmdsynopsis>
 <command>kid3-qt</command>
 <arg><option>&doublehyphen;portable</option></arg>
 <arg><option>Qt-options</option></arg>
 <arg rep="repeat"><replaceable>FILE</replaceable></arg>
 </cmdsynopsis>
 <cmdsynopsis>
 <command>kid3-cli</command>
 <arg><option>&doublehyphen;portable</option></arg>
 <arg><option>&doublehyphen;dbus</option></arg>
 <group>
 <arg choice="plain"><option>-h</option></arg>
 <arg choice="plain"><option>&doublehyphen;help</option></arg>
 </group>
 <arg><option>-c COMMAND1</option></arg>
 <arg rep="repeat"><option>-c COMMAND2</option></arg>
 <arg rep="repeat"><replaceable>FILE</replaceable></arg>
 </cmdsynopsis>
 <!--change manpage</refsynopsisdiv>--></preface>
 
 <preface id="options"><title>Options</title>
 
 <variablelist>
 <varlistentry>
 <term><option>&doublehyphen;portable</option></term>
 <listitem><para>Store configuration in file <filename>kid3.ini</filename>
 inside application folder.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><replaceable>FILE</replaceable></term>
 <listitem><para>If <filename><replaceable>FILE</replaceable></filename> is the
 path to a folder, it will be opened. If one or more file paths are given,
 their common folder is opened and the files are selected.
  </para></listitem>
 </varlistentry>
 </variablelist>
 
 <sect1 id="options-kid3"><title>kid3</title>
 <variablelist>
 <varlistentry>
 <term><option>&doublehyphen;help</option></term>
 <listitem><para>Show help about options.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><option>&doublehyphen;author</option></term>
 <listitem><para>Show author information.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><option>&doublehyphen;version</option></term>
 <listitem><para>Show version information.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><option>&doublehyphen;license</option></term>
 <listitem><para>Show license information.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><option>&doublehyphen;desktopfile
 <filename>FILE</filename></option></term>
 <listitem><para>The base file name of the desktop entry for this
 application.</para></listitem>
 </varlistentry>
 </variablelist>
 </sect1>
 
 <sect1 id="options-kid3-qt"><title>kid3-qt</title>
 <variablelist>
 <varlistentry>
 <term><option>Qt-options</option></term>
 <listitem><para>See <citerefentry><refentrytitle>qt5options</refentrytitle>
 <manvolnum>7</manvolnum></citerefentry>.</para></listitem>
 </varlistentry>
 </variablelist>
 </sect1>
 
 <sect1 id="options-kid3-cli"><title>kid3-cli</title>
 <variablelist>
 
 <varlistentry>
 <term><option>&doublehyphen;dbus</option></term>
 <listitem><para>Activate the &DBus; interface.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-c</option></term>
 <listitem><para>Execute a command. Multiple <option>-c</option> options are
 possible, they are executed in sequence. See the section about
 <link linkend="kid3-cli">kid3-cli</link> for a description of the available
 commands.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-h</option>|<option>&doublehyphen;help</option></term>
 <listitem><para>Show help about options and commands.</para></listitem>
 </varlistentry>
 
 </variablelist>
 </sect1>
 
 </preface>
 
 <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, Opus, DSF, FLAC,
 MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and
 tracker modules (MOD, S3M, IT, XM) 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, <abbrev>i.e.</abbrev> 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, <abbrev>e.g.</abbrev> 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://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, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex,
 TrueAudio, WavPack, WMA, WAV and AIFF tags</para></listitem>
 <listitem><para>Generate tags from filename</para></listitem>
 <listitem><para>Generate tags from the contents of tag fields</para></listitem>
 <listitem><para>Generate filename from tags</para></listitem>
 <listitem><para>Generate and change folder 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://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 folder containing MP3 files with the tracks from
 the album "Let's Tag" from the band "One Hit Wonder". The folder is
 named in the "artist - album" format, in our case <filename>One Hit Wonder - Let's
 Tag</filename>. The folder 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 folder name and does not have to be repeated in the filename.
 But back to our example, the folder 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
 <menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice>
 menu item (or toolbar button) and select one of the files in this folder. All
 files will be displayed in the file listbox. Lazy as we are, we want to use the
 information in the folder 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>Date</guilabel>
 and select "Pop" from the <guilabel>Genre</guilabel> combobox. To set only these
 two values, their check boxes are automatically checked and all other check boxes
 are left 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 <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
 menu item (or toolbar button). Selecting <menuchoice><guimenu>File</guimenu><guimenuitem>
 Create Playlist</guimenuitem></menuchoice> menu item (or toolbar button) will
 generate a file <filename>One Hit Wonder - Let's Tag.m3u</filename> in the folder.
 </para>
 </sect1>
 
 </chapter>
 
 <chapter id="commands">
 <title>Command Reference</title>
 
 <sect1 id="gui-elements">
 <title>The &GUI; Elements</title>
 <para>
 The &kid3; &GUI; is separated in six sections: At the left are the file
 and folder listboxes, the right side contains the <guilabel>File</guilabel>,
 <guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel> and <guilabel>Tag 3
 </guilabel> sections.
 </para>
 
 <para>
 To navigate between the different sections using the keyboard, several keyboard
 shortcuts are supported. In the tag sections, the shortcuts are active while
 not editing text or when being in the first column.
 
 <itemizedlist>
 <listitem><para>
 <keycombo>&Alt;<keycap>Left</keycap></keycombo>: Go to previous section
 (<keycombo><keycap>Command</keycap><keycap>[</keycap></keycombo> on &macOS;)
 </para></listitem>
 <listitem><para>
 <keycombo>&Alt;<keycap>Right</keycap></keycombo>: Go to next section
 (<keycombo><keycap>Command</keycap><keycap>]</keycap></keycombo> on &macOS;)
 </para></listitem>
 <listitem><para>
 <keycombo>&Ctrl;<keycap>Shift</keycap><keycap>V</keycap></keycombo>: From
 other tag
 </para></listitem>
 <listitem><para>
 <keycombo>&Ctrl;<keycap>C</keycap></keycombo>: Copy
 </para></listitem>
 <listitem><para>
 <keycombo>&Ctrl;<keycap>V</keycap></keycombo>: Paste
 </para></listitem>
 <listitem><para>
 <keycombo><keycap>Shift</keycap><keycap>Delete</keycap></keycombo>: Remove
 </para></listitem>
 <listitem><para>
 <keycombo><keycap>F2</keycap></keycombo>: Edit
 </para></listitem>
 <listitem><para>
 <keycombo><keycap>Insert</keycap></keycombo>: Add
 </para></listitem>
 <listitem><para>
 <keycombo><keycap>Delete</keycap></keycombo>: Delete
 </para></listitem>
 </itemizedlist>
 </para>
 
 <sect2 id="file-list">
 <title>File List</title>
 
 <para>
 The file list contains the names of all the files in the opened
 folder which match the selected file name filter (typically
 <filename class="extension">*.mp3 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a
 *.m4b *.m4p *.mp4 *.mp2 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape</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>
 Besides <guilabel>Name</guilabel>, also other columns
 <guilabel>Size</guilabel>, <guilabel>Type</guilabel>, <guilabel>Date
 Modified</guilabel> with file details can be displayed. Columns can be hidden
 by unchecking their name in the context menu of the list header. The order of
 the columns can be changed by drag and drop. The sort order can be toggled by
 clicking on the column header.
 </para>
 <para>
 The values of the standard tags can also be displayed and edited in columns of
 the file list.
 </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>
 Folders are displayed with a folder icon. If a folder is opened, its
 files are displayed in a hierarchical tree. By selecting files from
 subfolders, operations can be executed on files in different folders,
 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 <mousebutton>right</mousebutton> 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 (only the
 current tree if the <keycap>Shift</keycap> key is pressed)
 </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>Move to Trash</guimenuitem>: Moves a file to the trash
 </para></listitem>
 <listitem><para>
 <guimenuitem>Play</guimenuitem>: Plays a file,
 see <link linkend="play">Play</link>. If the selected file is a playlist, the
 files of the playlist will be played.
 </para></listitem>
 <listitem><para>
 <guimenuitem>Edit</guimenuitem>: Edit a playlist,
 see <link linkend="edit-playlist">Edit Playlist</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>. The playback on double
 click can also be activated there.
 </para><para>
 When <guilabel>Select file on play</guilabel> is activated, the currently
 played track is automatically selected in the file list.
 </para></listitem>
 </itemizedlist>
 </para>
 </sect2>
 
 <sect2 id="edit-playlist">
 <title>Edit Playlist</title>
 
 <para>
 A playlist can be created empty or containing the tracks of a folder, see <link
 linkend="create-playlist">Create Playlist</link>. The playlist file created in
 such a way can be edited by double click or using <guilabel>Edit</guilabel>
 from the file list context menu. A dialog with the entries of the playlist is
 shown. It is possible to open multiple playlists simultaneously.
 </para>
 <para>
 New entries can be added by drag and drop from the file list, a file manager or
 another playlist. If an entry is dragged from another playlist, it will be
 moved or copied depending on the system. To invoke the other
 operation, respectively, the <keycap>Shift</keycap>, &Ctrl; or &Alt; (to copy instead of move on
 &macOS;) key has to be pressed. Reordering entries within the playlist is also
 possible via drag and drop. Alternatively, entries can be moved using the keyboard
 shortcuts <keycombo>&Ctrl;<keycap>Shift</keycap><keycap>Up</keycap></keycombo> and
 <keycombo>&Ctrl;<keycap>Shift</keycap><keycap>Down</keycap></keycombo> (on &macOS; <keycap>Command</keycap> has
 to be pressed instead of &Ctrl;). An entry can be removed using the <keycap>Delete</keycap> key.
 </para>
 <para>
 Please note the following: To drag entries from the file list, they have to be
 held at the left side (near the icons), the same gesture at the right side
 will perform a multi selection, such an action is hereby still easily possible.
 </para>
 <para>
 When a playlist has been modified, the changes can be stored using
 <guibutton>Save</guibutton> or discarded using
 <guibutton>Cancel</guibutton>. When the window is closed, a confirmation
 prompt is shown if there are unsaved changes.
 </para>
 <para>
 Tracks selected in a playlist will be automatically selected in the file list,
 thereby making it possible to edit their tags.
 </para>
 <para>
 To execute actions on a playlist, its file must be selected in the file
 list. <guimenuitem>Edit</guimenuitem> from the context menu will lead to the
 dialog described in this section, and <guimenuitem>Play</guimenuitem> will
 start the media player with the tracks from the playlist. User actions can act
 on playlists, for <link linkend="qml-examples">example</link> <guilabel>Export
 Playlist Folder</guilabel>, which copies the files from a playlist into a
 folder.
 </para>
 </sect2>
 
 <sect2 id="directory-list">
 <title>Folder List</title>
 
 <para>
 The folder list contains the names of the folders in the opened
 folder, as well as the current (<filename class="directory">.</filename>) and
 the parent (<filename class="directory">..</filename>) folder. It allows one
 to quickly change the folder without using the <guimenuitem>Open</guimenuitem>
 command or drag and drop.
 </para>
 <para>
 Column visibility, order and sorting can be configured as described in the
 section about the <link linkend="file-list">file list</link>.
 </para>
 </sect2>
 
 <sect2 id="file">
 <title>File</title>
 
 <para>
 Shows information about the encoding
 (MP3, Ogg, Opus, DSF, FLAC, MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV, AIFF),
 bit rate, 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 the first or the second tag.
 The filename can contain arbitrary characters, even a folder part separated
 by a slash from the file name, but that folder 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 (<abbrev>e.g.</abbrev> 01)</para></listitem>
 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
 <listitem><para>%g %{genre} Genre</para></listitem>
 <listitem><para>   %{ignore} Ignored when generating tags from the file name</para></listitem>
 </itemizedlist>
 
 <para>
 The format codes are not restricted to the examples given above. Any frame
 name can be used, for instance unified frame names
 like <userinput>%{albumartist}</userinput>,
 <userinput>%{discnumber.1}</userinput>, <userinput>%{bpm}</userinput> or
 format specific names like <userinput>%{popm}</userinput>.
 </para>
 
 <para>
 It is possible to prepend and append strings to the replacement for a format
 code by adding them in double quotes inside the curly braces of a format
 code. These strings will only be put into the resulting string if the format
 code yields a nonempty value. For example, if the file name shall
 both contain the title and the subtitle, one could use
 <userinput>%{title} [%{subtitle}]</userinput> in the format string. But this
 would result in a string ending with <computeroutput> []</computeroutput> if
 no subtitle frame exists for a file. In order to omit the brackets if no
 subtitle is present, <userinput>%{title}%{" ["subtitle"]"}</userinput> shall
 be used instead. This will omit the brackets, the leading space and the
 subtitle if not subtitle exists.
 </para>
 
 <para>
 The list of available formats can be edited in the dialog which appears when
 clicking the <guibutton>Filename from tag</guibutton> button in the
 <guilabel>File</guilabel> tab of the
 <link linkend="configure-kid3">settings</link>.
 </para>
 
 <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>
 The list of available formats can be edited in the dialog which appears when
 clicking the <guibutton>Tag from filename</guibutton> button in the
 <guilabel>File</guilabel> tab of the
 <link linkend="configure-kid3">settings</link>.
 </para>
 
 <para>
 Internally, a regular expression is built from the format codes. If advanced
 regular expressions are required, the format to generate the tags from the
 filenames can be given as a complete regular expression with captures which
 are preceded by the format codes, <abbrev>e.g.</abbrev> to extract the track numbers without
 removal of leading zeros, a format like "<userinput>/%{track}(\d+)
  %{title}(.*)</userinput>" could be used.
 </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:
 </para>
 <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>
 <para>
 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>
 </sect2>
 
 <sect2 id="tag1">
 <title>Tag 1</title>
 
 <para>
 The line edit widgets for <guilabel>Title</guilabel>,
 <guilabel>Artist</guilabel>,
 <guilabel>Album</guilabel>, <guilabel>Comment</guilabel>,
 <guilabel>Date</guilabel>, <guilabel>Track Number</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>Date</guilabel> and <guilabel>Track Number</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 check box 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 check box 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>
 </sect2>
 
 <sect2 id="tag2">
 <title>Tag 2</title>
 
 <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 cannot 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 one 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>
 
 </sect2>
 
 <sect2 id="tag3">
 <title>Tag 3</title>
 
 <para>
 Some files can have more than two tags, and a third tag section is visible.
 The following file types can have such a <guilabel>Tag 3</guilabel> section:
 </para>
 <itemizedlist>
 <listitem><para>
 MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0) tag and in the
 third section an APE tag. Such APE tags are used for replay gain
 information. In the <guilabel>Tag 3</guilabel> section, this information is
 visible, and the APE tag can be removed with the <guibutton>Remove</guibutton>
 button.
 </para></listitem>
 <listitem><para>
 The RIFF INFO chunk of WAV files is available in the <guilabel>Tag 3
 </guilabel> section because the <guilabel>Tag 1</guilabel> section is
 dedicated to ID3v1.1 tags and handles their restrictions. The
 <guilabel>Tag 2</guilabel> is still used for ID3v2.4.0 tags, which are also
 supported for WAV files, but RIFF INFO chunks seem to be supported better.
 </para></listitem>
 <listitem><para>
 FLAC files normally use a Vorbis comment for their meta data. However, there
 are FLAC files which have ID3v1 and ID3v2 tags, which can be found in the
 <guilabel>Tag 1</guilabel> and <guilabel>Tag 3</guilabel> sections.
 ID3 tags in FLAC files are only supported by TagLib, therefore the
 OggFlacMetadata plugin has to be disabled in the <guilabel>Plugins</guilabel>
 tab of the <link linkend="configure-kid3">settings</link>.
 </para></listitem>
 </itemizedlist>
 <para>
 The &GUI; controls work in the same way as in the <guilabel>Tag 2</guilabel>
 section.
 </para>
 
 </sect2>
 
 <!--begin manpage ignore-->
 <sect2 id="frame-list">
 <title>Frame List</title>
 
 <para>
 &kid3; can edit most of the frames for all of the supported file types. Some
 frames are accessed using unified names, so that they can be exchanged
 between files with different formats. Frames which are not unified can be accessed as
 format specific frames.
 </para>
 
 <table id="table-frame-list">
   <title>Mapping of Unified Frame Types to Various Formats</title>
    <tgroup cols="7">
      <thead>
        <row><entry>Unified</entry>           <entry>ID3v2.3</entry> <entry>ID3v2.4</entry> <entry>MP4</entry>            <entry>ASF</entry>                        <entry>Vorbis</entry>                 <entry>RIFF</entry></row>
      </thead>
      <tbody>
        <row><entry>Title</entry>             <entry><literal>TIT2</literal></entry>    <entry><literal>TIT2</literal></entry>    <entry><literal>©nam</literal></entry>           <entry><literal>Title</literal></entry>                      <entry><literal>TITLE</literal></entry>                  <entry><literal>INAM</literal></entry></row>
        <row><entry>Artist</entry>            <entry><literal>TPE1</literal></entry>    <entry><literal>TPE1</literal></entry>    <entry><literal>©ART</literal></entry>           <entry><literal>Author</literal></entry>                     <entry><literal>ARTIST</literal></entry>                 <entry><literal>IART</literal></entry></row>
        <row><entry>Album</entry>             <entry><literal>TALB</literal></entry>    <entry><literal>TALB</literal></entry>    <entry><literal>©alb</literal></entry>           <entry><literal>WM/AlbumTitle</literal></entry>              <entry><literal>ALBUM</literal></entry>                  <entry><literal>IPRD</literal></entry></row>
        <row><entry>Comment</entry>           <entry><literal>COMM</literal></entry>    <entry><literal>COMM</literal></entry>    <entry><literal>©cmt</literal></entry>           <entry><literal>Description</literal></entry>                <entry><literal>COMMENT</literal></entry>                <entry><literal>ICMT</literal></entry></row>
        <row><entry>Date</entry>              <entry><literal>TYER</literal></entry>    <entry><literal>TDRC</literal></entry>    <entry><literal>©day</literal></entry>           <entry><literal>WM/Year</literal></entry>                    <entry><literal>DATE</literal></entry>                   <entry><literal>ICRD</literal></entry></row>
        <row><entry>Track Number</entry>      <entry><literal>TRCK</literal></entry>    <entry><literal>TRCK</literal></entry>    <entry><literal>trkn</literal></entry>           <entry><literal>WM/TrackNumber</literal></entry>             <entry><literal>TRACKNUMBER</literal></entry>            <entry><literal>IPRT</literal> or <literal>ITRK</literal></entry></row>
        <row><entry>Genre</entry>             <entry><literal>TCON</literal></entry>    <entry><literal>TCON</literal></entry>    <entry><literal>©gen</literal></entry>           <entry><literal>WM/Genre</literal></entry>                   <entry><literal>GENRE</literal></entry>                  <entry><literal>IGNR</literal></entry></row>
        <row><entry>Album Artist</entry>      <entry><literal>TPE2</literal></entry>    <entry><literal>TPE2</literal></entry>    <entry><literal>aART</literal></entry>           <entry><literal>WM/AlbumArtist</literal></entry>             <entry><literal>ALBUMARTIST</literal></entry>            <entry></entry></row>
        <row><entry>Arranger</entry>          <entry><literal>IPLS</literal></entry>    <entry><literal>TIPL</literal></entry>    <entry><literal>ARRANGER</literal></entry>       <entry><literal>WM/Producer</literal></entry>                <entry><literal>ARRANGER</literal></entry>               <entry><literal>IENG</literal></entry></row>
        <row><entry>Author</entry>            <entry><literal>TOLY</literal></entry>    <entry><literal>TOLY</literal></entry>    <entry><literal>AUTHOR</literal></entry>         <entry></entry>                                              <entry><literal>AUTHOR</literal></entry>                 <entry></entry></row>
        <row><entry>BPM</entry>               <entry><literal>TBPM</literal></entry>    <entry><literal>TBPM</literal></entry>    <entry><literal>tmpo</literal></entry>           <entry><literal>WM/BeatsPerMinute</literal></entry>          <entry><literal>BPM</literal></entry>                    <entry><literal>IBPM</literal></entry></row>
        <row><entry>Catalog Number</entry>    <entry><literal>TXXX:CATALOGNUMBER</literal></entry> <entry><literal>TXXX:CATALOGNUMBER</literal></entry>                            <entry></entry> <entry></entry>                              <entry><literal>CATALOGNUMBER</literal></entry>          <entry></entry></row>
        <row><entry>Compilation</entry>       <entry><literal>TCMP</literal></entry>    <entry><literal>TCMP</literal></entry>    <entry><literal>cpil</literal></entry>           <entry></entry>                                              <entry><literal>COMPILATION</literal></entry>            <entry></entry></row>
        <row><entry>Composer</entry>          <entry><literal>TCOM</literal></entry>    <entry><literal>TCOM</literal></entry>    <entry><literal>©wrt</literal></entry>           <entry><literal>WM/Composer</literal></entry>                <entry><literal>COMPOSER</literal></entry>               <entry><literal>IMUS</literal></entry></row>
        <row><entry>Conductor</entry>         <entry><literal>TPE3</literal></entry>    <entry><literal>TPE3</literal></entry>    <entry><literal>CONDUCTOR</literal></entry>      <entry><literal>WM/Conductor</literal></entry>               <entry><literal>CONDUCTOR</literal></entry>              <entry></entry></row>
        <row><entry>Copyright</entry>         <entry><literal>TCOP</literal></entry>    <entry><literal>TCOP</literal></entry>    <entry><literal>cprt</literal></entry>           <entry><literal>Copyright</literal></entry>                  <entry><literal>COPYRIGHT</literal></entry>              <entry><literal>ICOP</literal></entry></row>
        <row><entry>Description</entry>       <entry><literal>TIT3</literal></entry>    <entry><literal>TIT3</literal></entry>    <entry><literal>desc</literal></entry>           <entry><literal>WM/SubTitleDescription</literal></entry>     <entry><literal>DESCRIPTION</literal></entry>            <entry></entry></row>
        <row><entry>Disc Number</entry>       <entry><literal>TPOS</literal></entry>    <entry><literal>TPOS</literal></entry>    <entry><literal>disk</literal></entry>           <entry><literal>WM/PartOfSet</literal></entry>               <entry><literal>DISCNUMBER</literal></entry>             <entry></entry></row>
        <row><entry>Encoded-by</entry>        <entry><literal>TENC</literal></entry>    <entry><literal>TENC</literal></entry>    <entry><literal>©enc</literal></entry>           <entry><literal>WM/EncodedBy</literal></entry>               <entry><literal>ENCODED-BY</literal></entry>             <entry><literal>ITCH</literal></entry></row>
        <row><entry>Encoder Settings</entry>  <entry><literal>TSSE</literal></entry>    <entry><literal>TSSE</literal></entry>    <entry><literal>©too</literal></entry>           <entry><literal>WM/EncodingSettings</literal></entry>        <entry><literal>ENCODERSETTINGS</literal></entry>        <entry><literal>ISFT</literal></entry></row>
        <row><entry>Encoding Time</entry>     <entry></entry>                           <entry><literal>TDEN</literal></entry>    <entry></entry>                                  <entry><literal>WM/EncodingTime</literal></entry>            <entry><literal>ENCODINGTIME</literal></entry>           <entry><literal>IDIT</literal></entry></row>
        <row><entry>Grouping</entry>          <entry><literal>GRP1</literal></entry>    <entry><literal>GRP1</literal></entry>    <entry><literal>©grp</literal></entry>           <entry></entry>                                              <entry><literal>GROUPING</literal></entry>               <entry></entry></row>
        <row><entry>Initial Key</entry>       <entry><literal>TKEY</literal></entry>    <entry><literal>TKEY</literal></entry>    <entry></entry>                                  <entry><literal>WM/InitialKey</literal></entry>              <entry><literal>INITIALKEY</literal></entry>             <entry></entry></row>
        <row><entry>ISRC</entry>              <entry><literal>TSRC</literal></entry>    <entry><literal>TSRC</literal></entry>    <entry><literal>ISRC</literal></entry>           <entry><literal>WM/ISRC</literal></entry>                    <entry><literal>ISRC</literal></entry>                   <entry><literal>ISRC</literal></entry></row>
        <row><entry>Language</entry>          <entry><literal>TLAN</literal></entry>    <entry><literal>TLAN</literal></entry>    <entry><literal>LANGUAGE</literal></entry>       <entry><literal>WM/Language</literal></entry>                <entry><literal>LANGUAGE</literal></entry>               <entry><literal>ILNG</literal></entry></row>
        <row><entry>Lyricist</entry>          <entry><literal>TEXT</literal></entry>    <entry><literal>TEXT</literal></entry>    <entry><literal>LYRICIST</literal></entry>       <entry><literal>WM/Writer</literal></entry>                  <entry><literal>LYRICIST</literal></entry>               <entry><literal>IWRI</literal></entry></row>
        <row><entry>Lyrics</entry>            <entry><literal>USLT</literal></entry>    <entry><literal>USLT</literal></entry>    <entry><literal>©lyr</literal></entry>           <entry><literal>WM/Lyrics</literal></entry>                  <entry><literal>LYRICS</literal></entry>                 <entry></entry></row>
        <row><entry>Media</entry>             <entry><literal>TMED</literal></entry>    <entry><literal>TMED</literal></entry>    <entry><literal>SOURCEMEDIA</literal></entry>    <entry></entry>                                              <entry><literal>SOURCEMEDIA</literal></entry>            <entry><literal>IMED</literal></entry></row>
        <row><entry>Mood</entry>              <entry></entry>                           <entry><literal>TMOO</literal></entry>    <entry></entry>                                  <entry><literal>WM/Mood</literal></entry>                    <entry><literal>MOOD</literal></entry>                   <entry></entry></row>
        <row><entry>Original Album</entry>    <entry><literal>TOAL</literal></entry>    <entry><literal>TOAL</literal></entry>    <entry><literal>ORIGINALALBUM</literal></entry>  <entry><literal>WM/OriginalAlbumTitle</literal></entry>      <entry><literal>ORIGINALALBUM</literal></entry>          <entry></entry></row>
        <row><entry>Original Artist</entry>   <entry><literal>TOPE</literal></entry>    <entry><literal>TOPE</literal></entry>    <entry><literal>ORIGINALARTIST</literal></entry> <entry><literal>WM/OriginalArtist</literal></entry>          <entry><literal>ORIGINALARTIST</literal></entry>         <entry></entry></row>
        <row><entry>Original Date</entry>     <entry><literal>TORY</literal></entry>    <entry><literal>TDOR</literal></entry>    <entry><literal>ORIGINALDATE</literal></entry>   <entry><literal>WM/OriginalReleaseYear</literal></entry>     <entry><literal>ORIGINALDATE</literal></entry>           <entry></entry></row>
        <row><entry>Performer</entry>         <entry><literal>IPLS</literal></entry>    <entry><literal>TMCL</literal></entry>    <entry><literal>PERFORMER</literal></entry>      <entry></entry>                                              <entry><literal>PERFORMER</literal></entry>              <entry><literal>ISTR</literal></entry></row>
        <row><entry>Picture</entry>           <entry><literal>APIC</literal></entry>    <entry><literal>APIC</literal></entry>    <entry><literal>covr</literal></entry>           <entry><literal>WM/Picture</literal></entry>                 <entry><literal>METADATA_BLOCK_PICTURE</literal></entry> <entry></entry></row>
        <row><entry>Publisher</entry>         <entry><literal>TPUB</literal></entry>    <entry><literal>TPUB</literal></entry>    <entry><literal>PUBLISHER</literal></entry>      <entry><literal>WM/Publisher</literal></entry>               <entry><literal>PUBLISHER</literal></entry>              <entry><literal>IPUB</literal></entry></row>
        <row><entry>Rating</entry>            <entry><literal>POPM</literal></entry>    <entry><literal>POPM</literal></entry>    <entry><literal>rate</literal></entry>           <entry><literal>WM/SharedUserRating</literal></entry>        <entry><literal>RATING</literal></entry>                 <entry><literal>IRTD</literal></entry></row>
        <row><entry>Release Country</entry>   <entry><literal>TXXX:RELEASECOUNTRY</literal></entry> <entry><literal>TXXX:RELEASECOUNTRY</literal></entry>       <entry></entry>    <entry></entry>                                              <entry><literal>RELEASECOUNTRY</literal></entry>         <entry><literal>ICNT</literal></entry></row>
        <row><entry>Release Date</entry>      <entry></entry>                           <entry><literal>TDRL</literal></entry>    <entry><literal>RELEASEDATE</literal></entry>    <entry></entry>                                              <entry><literal>RELEASEDATE</literal></entry>            <entry></entry></row>
        <row><entry>Remixer</entry>           <entry><literal>TPE4</literal></entry>    <entry><literal>TPE4</literal></entry>    <entry><literal>REMIXER</literal></entry>        <entry><literal>WM/ModifiedBy</literal></entry>              <entry><literal>REMIXER</literal></entry>                <entry><literal>IEDT</literal></entry></row>
        <row><entry>Sort Album</entry>        <entry><literal>TSOA</literal></entry>    <entry><literal>TSOA</literal></entry>    <entry><literal>soal</literal></entry>           <entry><literal>WM/AlbumSortOrder</literal></entry>          <entry><literal>ALBUMSORT</literal></entry>              <entry></entry></row>
        <row><entry>Sort Album Artist</entry> <entry><literal>TSO2</literal></entry>    <entry><literal>TSO2</literal></entry>    <entry><literal>soaa</literal></entry>           <entry></entry>                                              <entry><literal>ALBUMARTISTSORT</literal></entry>        <entry></entry></row>
        <row><entry>Sort Artist</entry>       <entry><literal>TSOP</literal></entry>    <entry><literal>TSOP</literal></entry>    <entry><literal>soar</literal></entry>           <entry><literal>WM/ArtistSortOrder</literal></entry>         <entry><literal>ARTISTSORT</literal></entry>             <entry></entry></row>
        <row><entry>Sort Composer</entry>     <entry><literal>TSOC</literal></entry>    <entry><literal>TSOC</literal></entry>    <entry><literal>soco</literal></entry>           <entry></entry>                                              <entry><literal>COMPOSERSORT</literal></entry>           <entry></entry></row>
        <row><entry>Sort Name</entry>         <entry><literal>TSOT</literal></entry>    <entry><literal>TSOT</literal></entry>    <entry><literal>sonm</literal></entry>           <entry><literal>WM/TitleSortOrder</literal></entry>          <entry><literal>TITLESORT</literal></entry>              <entry></entry></row>
        <row><entry>Subtitle</entry>          <entry></entry>                           <entry><literal>TSST</literal></entry>    <entry><literal>SUBTITLE</literal></entry>       <entry><literal>WM/SubTitle</literal></entry>                <entry><literal>SUBTITLE</literal></entry>               <entry><literal>PRT1</literal></entry></row>
        <row><entry>Website</entry>           <entry><literal>WOAR</literal></entry>    <entry><literal>WOAR</literal></entry>    <entry><literal>WEBSITE</literal></entry>        <entry><literal>WM/AuthorURL</literal></entry>               <entry><literal>WEBSITE</literal></entry>                <entry><literal>IBSU</literal></entry></row>
        <row><entry>Work</entry>              <entry><literal>TIT1</literal></entry>    <entry><literal>TIT1</literal></entry>    <entry><literal>©wrk</literal></entry>           <entry><literal>WM/ContentGroupDescription</literal></entry> <entry><literal>WORK</literal></entry>                   <entry></entry></row>
        <row><entry>WWW Audio File</entry>    <entry><literal>WOAF</literal></entry>    <entry><literal>WOAF</literal></entry>    <entry></entry>                                  <entry><literal>WM/AudioFileURL</literal></entry>            <entry><literal>WWWAUDIOFILE</literal></entry>           <entry></entry></row>
        <row><entry>WWW Audio Source</entry>  <entry><literal>WOAS</literal></entry>    <entry><literal>WOAS</literal></entry>    <entry></entry>                                  <entry><literal>WM/AudioSourceURL</literal></entry>          <entry><literal>WWWAUDIOSOURCE</literal></entry>         <entry></entry></row>
      </tbody>
    </tgroup>
  </table>
 
 <para>
 Remarks concerning the mappings to unified frame names:
 <itemizedlist>
 <listitem><para>
 The number of unified frame names is limited by the fact that a sensible
 mapping shall be possible for all supported file formats. Most tags support
 frames with arbitrary names; these will be used if no specific frame is
 available (<abbrev>e.g.</abbrev> the names in uppercase in the column MP4). If no such
 possibility exists, some frame types may not be supported for the format,
 <abbrev>e.g.</abbrev> Author and Performer for ASF (WMA).
 </para></listitem>
 <listitem><para>
 The mappings are not chosen arbitrarily, they are geared to the usage of the
 frames in other applications and devices. Thus the ID3v2 frame "TPE2 -
 Band/orchestra/accompaniment" does not suggest its usage as Album Artist, but
 this is commonly used. The actual meaning for ID3v2 on the other hand is the
 reason why this frame is used for the orchestra when importing (<abbrev>e.g.</abbrev> from
 Discogs), although this may seem a bit strange for other tag formats.
 </para></listitem>
 <listitem><para>
 The mappings are not always bijective. So ID3v2.3 uses an IPLS frame for both
 Arranger and Performer. When reading back, both frames are displayed as
 "Arranger".
 </para></listitem>
 <listitem><para>
 The frames Arranger and Performer use a particular format for their contents:
 "involvement 1|involvee 1|involvement 2|involvee 2|...", for
 instance "Chorus Master|Ernst Dunshirn|Soprano Vocals|Anna Netrebko". This
 will create IPLS (ID3v2.3) or TIPL/TMCL (ID3v2.4) frames with a string list in
 the specified format (the "|" is used as a separator between the strings).
 Values in this format are also set when importing data from servers which
 offer this information.
 </para></listitem>
 <listitem><para>
 To explicitly use a specific frame name which conflicts with a unified frame
 name, prepend an exclamation mark. For example, adding a frame of type
 "<replaceable>Media</replaceable>" to a Vorbis comment will create a frame with
 name "<literal>SOURCEMEDIA</literal>" because of the unified type mapping. In
 order to add a frame with name "<literal>MEDIA</literal>" and not
 "<literal>SOURCEMEDIA</literal>", use "<literal>!MEDIA</literal>" to force the
 explicit name.
 </para></listitem>
 <listitem><para>
 If you need a frame which is not in this list, you still have the possibility
 to enter arbitrary names using the <guibutton>Add</guibutton> button. Often
 used frame names can be added to the <guilabel>Custom Frames</guilabel> in the
 <guilabel>Tags</guilabel> configuration, and will then be available in the
 <guilabel>Quick Access Frames</guilabel>.
 </para></listitem>
 </itemizedlist>
 </para>
 
 </sect2>
 <!--end manpage ignore-->
 
 <sect2 id="synchronized-lyrics">
 <title>Synchronized Lyrics and Event Timing Codes</title>
 
 <para>
 For information synchronized with the audio data, a specific editor is
 available. These frames are supported for ID3v2.3.0 and ID3v2.4.0 tags. To add
 such a frame, the specific frame name has to be selected in the list which
 appears when the <guibutton>Add</guibutton> button is clicked -
 <guilabel>Synchronized Lyrics</guilabel> or <guilabel>Event Timing
 Codes</guilabel>, respectively. The editor is the same for both types, for the
 event timing codes, only a predefined set of events is available whereas for
 the synchronized lyrics, text has to be entered. In the following, editing
 synchronized lyrics is explained.
 </para>
 <para>
 A file having an ID3v2 tag is selected, the lyrics editor is entered using
 <guibutton>Add</guibutton> and selecting <guilabel>Synchronized
 Lyrics</guilabel>. For an existing Synchronized Lyrics frame, it is selected and
 <guibutton>Edit</guibutton> is clicked. The player is automatically opened
 with the current file so that the file can be played and paused to synchronize
 lyrics.
 </para>
 <para>
 The settings at the top of the SYLT editor normally do not have to be
 changed. If the lyrics contains characters which are not present in the Latin 1
 character set, changing the text encoding to UTF16 (or UTF8 for ID3v2.4.0) is
 advisable. For English lyrics and maximum compatibility, ISO-8859-1 should be
 used.
 </para>
 <para>
 The <guilabel>Lyrics</guilabel> section has five buttons at the
 top. <guibutton>Add</guibutton> will add a new time event in the table. The
 time is taken from the position of the player, thus adding an entry while
 playing the track will add a line for the currently played position. The
 events in the table have to be chronologically ordered, therefore the row will
 be inserted accordingly. Entries with an invalid time are treated specially:
 If the currently selected row has an invalid time, its time stamp will be
 replaced by the current time instead of adding a new row. If the current time
 is not invalid, the first row with an invalid time will be used if
 present. This behavior should facilitate adding time stamps if the lyrics text
 is already in the table but the time stamps are missing (which is the case
 when importing unsynchronized lyrics). Note that the invalid time is
 represented as 00:00.00, <abbrev>i.e.</abbrev> the same as the time at the absolute beginning
 of the track, which is not invalid. To make a time invalid, press the
 <keycap>Delete</keycap> key, or use <guimenu>Clear</guimenu> from the context menu. New rows
 inserted using <guimenu>Insert row</guimenu> from the context menu or created
 when importing unsynchronized lyrics with <guibutton>From Clipboard</guibutton>
 or <guibutton>Import</guibutton> also contain invalid time stamps. Rows in the
 table can be deleted by clicking the <guibutton>Delete</guibutton> button or
 using <guimenu>Delete rows</guimenu> from the context menu.
 </para>
 <para>
 Synchronized lyrics can be imported from a file using
 <guibutton>Import</guibutton>. The expected format is simple or enhanced
 LRC. If the selected file does not contain a square bracket in the first line,
 it is supposed to be a simple text file with unsynchronized lyrics. The lines
 from such a file are then imported having invalid time stamps. The time
 information can be added using the <guibutton>Add</guibutton> button or
 by manual entry. It is also possible to import lyrics via copy-paste using
 <guilabel>From Clipboard</guilabel>. Synchronized lyrics can be written to LRC
 files using <guibutton>Export</guibutton>. Note that only entries with valid
 time stamps will be exported and that the entries will be sorted by
 time. Entries with invalid time won't be stored in the SYLT frame either, so
 make sure to include all timing information before leaving the dialog.
 </para>
 <para>
 The <ulink url="http://id3.org/id3v2.4.0-frames">ID3 specification</ulink>
 suggests a time stamp for each syllable. However most players only support the
 granularity of a line or sentence. To support both use cases, &kid3; follows
 the same conventions as <ulink
 url="http://www.compuphase.com/software_sylteditor.htm">SYLT
 Editor</ulink>. Text which is entered into the table is assumed to start a new
 line unless it starts with a space or a hyphen. Exceptions to this rule are
 possible by starting a line with an underscore ('_') to force continuation or
 a hash mark ('#') to force a new line. These escape characters are not stored
 inside the SYLT frame. Inside the SYLT frame, new lines start with a line feed
 character (hex 0A) whereas continuations do not. When reading SYLT frames,
 &kid3; checks if the first entry starts with a line feed. If this is not the
 case, it is assumed that all entries are new lines and that no syllable
 continuations are used.
 </para>
 <para>
 While the track is played, the row associated with the current playing
 position is highlighted, so that the correctness of the synchronization
 information can be verified. If an offset has to be added to one or more time
 stamps, this can be accomplished with the <guimenu>Add offset</guimenu>
 context menu. Negative values can be used to reduce the time. Using
 <guimenu>Seek to position</guimenu> in the context menu, it is possible to set
 the playing position to the time of the selected row.
 </para>
 <para>
 <emphasis>Recommended procedure to add new synchronized lyrics</emphasis>
 <itemizedlist>
 <listitem><para>Get the unsynchronized lyrics, <abbrev>e.g.</abbrev> using
 <menuchoice><guimenu>Lyrics</guimenu><guimenuitem>Embed
 Lyrics</guimenuitem></menuchoice> from the file list context
 menu.</para></listitem>
 <listitem><para>Copy the unsynchronized lyrics to the clipboard, just go to
 the <guilabel>Lyrics</guilabel> row in the frame table and press
 <keycombo>&Ctrl;<keycap>C</keycap></keycombo>.</para></listitem>
 <listitem><para>Add a synchronized lyrics frame
 (<guibutton>Add...</guibutton>, <guilabel>Synchronized
 Lyrics</guilabel>, <guibutton>OK</guibutton>), click
 <guibutton>From Clipboard</guibutton>.</para></listitem>
 <listitem><para>Now all lines from the unsynchronized lyrics are in the table,
 all time stamps are invalid (0:0:0.00). You can delete empty entries
 beforehand.</para></listitem>
 <listitem><para>Start playing the song by clicking the play button
 <guibutton>&#9658;</guibutton> in the play toolbar at the bottom of the main
 window.</para></listitem>
 <listitem><para>When the next lyrics line with invalid timestamp comes, click
 <guibutton>Add</guibutton> or press
 <keycombo>&Alt;<keycap>A</keycap></keycombo>, the timestamp
 will be updated.</para></listitem>
 <listitem><para>Continue like this until all timestamps are set. If you missed
 something, stop playback and clear the timestamps using the <keycap>Delete</keycap> key or by
 selecting them and using <guimenuitem>Clear</guimenuitem> from the context
 menu. To restart playback from a given timestamp, use <guimenuitem>Seek to
 position</guimenuitem> from the context menu.
 </para></listitem>
 </itemizedlist>
 </para>
 </sect2>
 
 <sect2 id="mp4-chapters">
 <title>Chapters in MP4 Files</title>
 
 <para>
 MP4 audiobooks typically have a <filename class="extension">.m4b</filename>
 extension and are rather large because  they contain all chapters in a single
 file. To navigate in such files, they can contain chapter marks, which can be
 edited in &kid3; in a pseudo "Chapters" frame using the same editor which is
 used for <link linkend="synchronized-lyrics">synchronized lyrics</link>. Note,
 however, that this feature is only available with the
 <guilabel>Mp4v2Metadata</guilabel> plugin, so make sure that it is activated
 and above the <guilabel>TaglibMetadata</guilabel> plugin in the
 <guilabel>Plugins</guilabel> tab of the settings if you have to edit MP4
 chapters.
 </para>
 </sect2>
 
 </sect1>
 
 <sect1 id="file-menu">
 <title>The File Menu</title>
 <para>
 <variablelist>
 
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo>&Ctrl;<keycap>O</keycap></keycombo>
 </shortcut>
 <guimenu>File</guimenu>
 <guimenuitem>Open...</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Opens a folder.</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 folder.</action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo>&Ctrl;<keycap>D</keycap></keycombo>
 </shortcut>
 <guimenu>File</guimenu>
 <guimenuitem>Open Folder...</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Opens a folder.</action> All files matching the selected
 file name filter will be displayed in the file listbox.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycap>F5</keycap>
 </shortcut>
 <guimenu>File</guimenu>
 <guimenuitem>Reload</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Reload folder.</action> Modified files have to be
 saved before. Expanded subfolders will be collapsed.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo>&Ctrl;<keycap>S</keycap></keycombo>
 </shortcut>
 <guimenu>File</guimenu>
 <guimenuitem>Save</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Saves all changed files in the folder.</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 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>
 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 double-clicking 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.
 When satisfied with the displayed tracks, they
 can be imported by terminating the import dialog with
 <guibutton>OK</guibutton>.
 </para>
 <para>
 If you already have a search result open in the web browser, you can enter the
 URL into the first search field. The result will then appear in the album list
 and can be directly imported into &kid3;.
 </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.
 A <guilabel>Token</guilabel> can be entered to use the RESTful Discogs API
 instead of their web interface, which is often changed, thereby breaking the
 import parser. You have to register for an account on
 <ulink url="https://www.discogs.com/">Discogs</ulink> and then generate a token
 on their web site (Settings/Developers, Generate new token). Don't forget to
 <guibutton>Save Settings</guibutton> after entering the token in order to use
 it in subsequent requests too.
 If <guilabel>Standard Tags</guilabel> is marked, the standard information is
 imported, <abbrev>e.g.</abbrev> artist, album, and title.
 If <guilabel>Additional Tags</guilabel> is marked, more information is
 imported if available, <abbrev>e.g.</abbrev> 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, <abbrev>e.g.</abbrev> 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 (<abbrev>e.g.</abbrev> 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 id="import-text">
 For the import of textual data, <guibutton>From File/Clipboard</guibutton>
 opens a subdialog, where 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. Note that there are also "Export
 CSV" and "Import CSV" commands in the context menu of the file list, which use
 scripts to export and import CSV data in a more complete, powerful and
 flexible way.
 </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 folder. 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 folder 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, <abbrev>e.g.</abbrev> "Track Title Time", are available. An empty
 custom format can be created with <guibutton>Add</guibutton> 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, besides the codes listed below, any frame name is
 possible:
 </para>
 
 <para id="format-codes">
 <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>
 
 <para>
 For example, a track regular expression (second line) to import from an
 <filename class="extension">.m3u</filename> playlist could be
 "<literal>%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]</literal>". All formats
 can be changed by editing the regular expressions and the name and then clicking
 <guibutton>Save Settings</guibutton>. They will be stored in the <filename>kid3rc</filename>
 file in the configuration folder. This file can be directly edited to have more
 import formats or it can be deleted to revert to the default formats. Formats
 can be deleted using <guibutton>Remove</guibutton>.
 </para>
 <para>
 <guilabel>Accuracy</guilabel> shows an estimation of how good the
 imported information matches the given tracks. It uses track durations or
 file names to calculate the level of similarity in percent.
 <guilabel>Cover Art</guilabel> shows the &URL; of the album cover image
 which will be downloaded.
 </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 check box <guibutton>Check maximum
 allowable time difference (sec):</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>
 If 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> option with the 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 <mousebutton>left</mousebutton> mouse button and the &Ctrl; key hold down,
 and then dropped at the new location.
 </para>
 <para>
 When the import dialog is opened, it contains the actual contents of the
 tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using the
 <guilabel>Destination</guilabel> combo box. The button on the right of this
 combo box can be used to revert the table to the current contents of the
 tags. The check boxes in the first table column can be used to select the
 tracks which are imported. This can be useful if a folder contains the tracks
 of both &CD;s of a double &CD; and only the tracks of the second &CD; have to be
 imported.
 </para>
 <para>
 To identify the tracks which are imported, it is possible to display the file
 names or the full paths to the files using the context menu of the table
 header. The values in the import table can be edited.  The revert-button to
 the right of the <guilabel>Destination</guilabel> combo box can be used to
 restore the contents of the tags, which can also be useful after changing the
 <guilabel>Destination</guilabel>.
 </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>
 
 <para id="import-tags">
 <guibutton>From Tags</guibutton> leads to a subdialog to set tag frames from
 the contents of other tag frames. This can be used to simply copy information
 between tags or extract a part from one frame and insert it in another.
 </para>
 <para>
 As in the <link linkend="import-text">import from file/clipboard</link> dialog,
 there are freely configurable formats to perform different operations. Already
 preconfigured are formats to copy the Album value to Album Artist, Composer or
 Conductor, and to extract the Track Number from Title fields which contain a
 number. There is also a format to extract a Subtitle from a Title field.
 </para>
 <para>
 The following example explains how to add a custom format, which sets the
 information from the Subtitle field also in the Comment field. Create a new
 format using <guibutton>Add</guibutton> button and set a new name, <abbrev>e.g.</abbrev>
 "Subtitle to Comment". Then enter "<userinput>%{subtitle}</userinput>" in
 <guilabel>Source</guilabel> and "<userinput>%{comment}(.*)</userinput>" for
 <guilabel>Extraction</guilabel> and click <guibutton>Save
 Settings</guibutton>.
 </para>
 <para>
 The expression in <guilabel>Source</guilabel> can contain
 <link linkend="format-codes">format codes</link> for arbitrary tag frames,
 multiple codes can be used to combine the contents from different frames. For
 each track, a text is generated from its tags using the <guilabel>Source
 </guilabel> format, and the regular expression from
 <guilabel>Extraction</guilabel> is applied to this text to set new values for
 the tags. Format codes are used before the capturing parentheses to specify
 the tag frame where the captured text shall be stored. It works in the same
 way as for the <link linkend="import-text">import from file/clipboard</link>.
 </para>
 <para>
 <guimenuitem>Import from Tags...</guimenuitem> is also directly available from
 the <guimenu>File</guimenu> menu. The difference between these two functions
 is that the import dialog subdialog operates on all files of the current
 folder whereas the menu function operates on the selected files (which can
 be in different folders). The menu function supports an additional code
 "<literal>%{__return}</literal>" to return the extracted value, which can be
 useful with the CLI and QML interfaces.
 </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 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>
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>Import from Tags...</guimenuitem>
 </menuchoice></term>
 <listitem><para>Like <link linkend="import-tags">From Tags</link>, but the
 import is applied to the selected files.</para></listitem>
 </varlistentry>
 
 <varlistentry id="batch-import">
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>Automatic Import...</guimenuitem>
 </menuchoice></term>
 <listitem><para>
 <action>Automatic Import</action> allows one to import information for multiple
 albums from various web services. If folders are selected in the file
 list, track data for the selected folders will be imported. If no
 folder is selected, all folders in the file list will be imported.
 </para>
 <para>
 The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using the
 <guilabel>Destination</guilabel> combo box.
 </para>
 <para>
 Profiles determine which servers will be contacted to fetch album
 information. Some profiles are predefined (All, MusicBrainz, Discogs,
 Cover Art), custom profiles can be added using the
 <guibutton>Add</guibutton> button at the right of the
 <guilabel>Profile</guilabel> combo box.
 </para>
 <para>
 The table below shows the servers which will be used when importing album
 information using the selected profile. The import process for an album is
 finished if all required information has been found, so the order of the
 rows in the table is important. It can be changed using the
 <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons.
 <guibutton>Edit</guibutton> can be used to change an existing entry. The
 <guibutton>Server</guibutton> selection offers the same servers as can be
 used in the import functions. <guilabel>Standard Tags</guilabel>,
 <guilabel>Additional Tags</guilabel>, <guilabel>Cover Art</guilabel>
 determine the information which shall be fetched from the server. Finally,
 <guilabel>Accuracy</guilabel> is the minimum accuracy which must be
 achieved to accept the imported data. If the accuracy is insufficient, the
 next server in the list will be tried. The same dialog containing the server
 properties appears when <guibutton>Add</guibutton> is clicked to add a new
 server entry. Existing entries can be deleted using
 <guibutton>Remove</guibutton>.
 </para>
 <para>
 To launch an automatic batch import with the selected profile, click
 <guibutton>Start</guibutton>. Details about the running import are displayed
 at the top of the dialog. The process can be aborted with the
 <guibutton>Abort</guibutton> button.
 </para>
 <para>
 </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 <keycap>Enter</keycap>,
 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 and 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
 <abbrev>etc.</abbrev>). The replaced regular expression contains the &URL; of the picture. By
 this means cover art can be imported from Amazon, Google Images, <abbrev>etc.</abbrev> using
 drag and 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. If the export data contain tabulator characters, the export is
 displayed in a table. The data will be generated from the tags
 in the current folder according to the configured format.
 </para>
 <para>
 The format settings are similar as in the Import dialog: The topmost field
 contains the title (<abbrev>e.g.</abbrev> "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. Not only the
 codes listed below but all tag frame names can be used.
 </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 (<abbrev>e.g.</abbrev> 01)</para></listitem>
 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 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>%{modificationdate} Modification date</para></listitem>
 <listitem><para>%{creationdate} Creation date</para></listitem>
 <listitem><para>%u %{url} &URL;</para></listitem>
 <listitem><para>%{dirname} Folder name</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} Bit rate in kbit/s</para></listitem>
 <listitem><para>%v %{vbr} VBR or empty (only for ID3v2.3 with
 id3lib)</para></listitem>
 <listitem><para>%r %{samplerate} Sample rate 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 (<abbrev>e.g.</abbrev> MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
 MPC, APE, 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 bit rate, sample rate, channels, <abbrev>etc.</abbrev> 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
 folder. The other formats can be adapted to your needs.
 </para>
 <para>
 The <guilabel>Source</guilabel> 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 folder name</guibutton>
 or use a <guibutton>Format</guibutton> with values from the tags, <abbrev>e.g.</abbrev>
 "<userinput>%{artist} - %{album}</userinput>" 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 list of available formats can be edited in the <guilabel>Format</guilabel>
 section of the <guilabel>Files</guilabel> tab in the
 <link linkend="configure-kid3">settings</link>.
 <guibutton>Create new empty playlist</guibutton> will make an empty playlist
 with the given name.
 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 folder</term>
 <listitem><para>The playlist is created in the current folder and contains
 only files of the current folder. The current folder is the folder
 where the current file is located. If multiple files are selected, the current
 file is probably the last selected file.</para></listitem></varlistentry>
 <varlistentry><term>Every folder</term>
 <listitem><para>A playlist is created in every folder which contains
 listed files, and each playlist contains the files of that folder.
 </para></listitem></varlistentry>
 <varlistentry><term>Top-level folder</term>
 <listitem><para>Only one playlist is created in the top-level
 folder (<abbrev>i.e.</abbrev> the folder of the file list) and it contains the listed
 files of the top-level folder and all of its sub-folders.
 </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 folder 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, "<userinput>%{track.3}</userinput>" can be used to sort by track
 number (the "<userinput>.3</userinput>" is used to get three digits with
 leading zeros because strings are used for sorting). It is also possible to
 use multiple fields, <abbrev>e.g.</abbrev> "<userinput>%{genre}%{year}</userinput>" 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>&Ctrl;<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>
 
 </sect1>
 
 <sect1 id="edit-menu">
 <title>The Edit Menu</title>
 <para>
 <variablelist>
 
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo>&Alt;<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>&Ctrl;<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>
 <guimenu>Edit</guimenu>
 <guimenuitem>Select All in Folder</guimenuitem>
 </menuchoice></term>
 <listitem><para>Selects all files of the current folder.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo>&Alt;<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>&Alt;<keycap>Down</keycap></keycombo>
 </shortcut>
 <guimenu>Edit</guimenu>
 <guimenuitem>Next File</guimenuitem>
 </menuchoice></term>
 <listitem><para>Selects the next file.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo>&Ctrl;<keycap>F</keycap></keycombo>
 </shortcut>
 <guimenu>Edit</guimenu>
 <guimenuitem>Find...</guimenuitem>
 </menuchoice></term>
 <listitem><para>Find strings in the file names and the tags. The
 <guilabel>Find</guilabel> dialog is a subset of the
 <guilabel>Replace</guilabel> dialog, which is described below.
  </para></listitem>
 </varlistentry>
 
 <varlistentry id="find-replace">
 <term><menuchoice>
 <shortcut>
 <keycombo>&Ctrl;<keycap>R</keycap></keycombo>
 </shortcut>
 <guimenu>Edit</guimenu>
 <guimenuitem>Replace...</guimenuitem>
 </menuchoice></term>
 <listitem><para>This function opens a dialog to find and replace strings in the
 file names and the tags. The set of frames where the search is performed can
 be restricted by deactivating the <guilabel>Select all</guilabel> check box and
 selecting the frames which shall be searched. There are also search options
 available to search backwards, case sensitively, and to use regular
 expressions.</para>
 <para>Depending on the number of files, the search might take some
 time, therefore it can be aborted by closing the dialog.</para></listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 </sect1>
 
 <sect1 id="tools-menu">
 <title>The Tools Menu</title>
 <para>
 <variablelist>
 
 <varlistentry id="apply-filename-format">
 <term><menuchoice>
 <guimenu>Tools</guimenu>
 <guimenuitem>Apply Filename Format</guimenuitem>
 </menuchoice></term>
 <listitem><para>When <guilabel>Automatically apply format</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 id="apply-tag-format">
 <term><menuchoice>
 <guimenu>Tools</guimenu>
 <guimenuitem>Apply Tag Format</guimenuitem>
 </menuchoice></term>
 <listitem><para>When <guilabel>Automatically apply format</guilabel> is switched off
 for the tag 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="apply-text-encoding">
 <term><menuchoice>
 <guimenu>Tools</guimenu>
 <guimenuitem>Apply Text Encoding</guimenuitem>
 </menuchoice></term>
 <listitem><para>Sets the <guilabel>Text encoding</guilabel> selected in
 <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kid3;...
 </guimenuitem><guimenuitem>Tags section</guimenuitem><guimenuitem>Tag 2
 tab</guimenuitem></menuchoice> for all selected files. If UTF8 is selected,
 UTF16 will be used for ID3v2.3.0 tags because UTF8 is not supported for
 this format.</para></listitem>
 </varlistentry>
 
 <varlistentry id="rename-directory">
 <term><menuchoice>
 <guimenu>Tools</guimenu>
 <guimenuitem>Rename Folder...</guimenuitem>
 </menuchoice></term>
 <listitem><para>This dialog offers the possibility to automatically rename the
 currently open folder according to the tags in the files. Several formats
 are preconfigured to include information about artist, album and year in the
 folder name. It is also possible to set a custom format and
 <guibutton>Edit</guibutton> the list of available formats. The following
 special codes are used to insert tag values into the folder 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 (<abbrev>e.g.</abbrev> 01)</para></listitem>
 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
 <listitem><para>%g %{genre} Genre</para></listitem>
 <listitem><para>%{dirname} Folder name (<abbrev>e.g.</abbrev> %{year" "}%{dirname}
 will prepend the year to the current folder name)</para></listitem>
 <listitem><para>%{max-year} The maximum year value found for this folder,
 can also be used with other codes than "year"</para></listitem>
 <listitem><para>%{min-year} The minimum year value found for this
 folder</para></listitem>
 <listitem><para>%{unq-year} The unique year value found for this folder or
 empty if not unique</para></listitem>
 </itemizedlist>
 
 <para>
 If a folder separator "/" is found in the format, multiple folders are
 created. If you want to create a new folder instead of renaming the current
 folder, in the <guilabel>Action</guilabel> combo box select <guilabel>Create
 Folder</guilabel> instead of <guilabel>Rename Folder</guilabel>. The
 <guilabel>Source</guilabel> of the tag information can be chosen between
 <guilabel>Tag 1 and Tag 2</guilabel>, <guilabel>Tag 1</guilabel> and
 <guilabel>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>
 <para>
 Multiple folders can be renamed by selecting them.
 </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><para>
 It is possible to number the tracks over multiple folders. The folders
 have to be expanded and selected.
 </para><para>
 If <guilabel>Reset counter for each folder</guilabel> is checked, track
 numbering is restarted with the given number for each folder when multiple
 folders are selected.
 </para><para>
 The number tracks dialog can also be used to format existing track numbers
 without changing the values when the check box left to <guilabel>Start
 number</guilabel> is deactivated. The total number of tracks will be added if
 the corresponding check box is active, which can be used to set the total for
 all selected tracks. If only formatting of the existing numbers is desired,
 this check box has to be deactivated too.
 </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 (<abbrev>e.g.</abbrev> 01)</para></listitem>
 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 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} Bit rate in kbit/s</para></listitem>
 <listitem><para>%v %{vbr} VBR or empty (only for ID3v2.3 with
 id3lib)</para></listitem>
 <listitem><para>%r %{samplerate} Sample rate 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 (<abbrev>e.g.</abbrev> MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
 MPC, APE, ASF, AIFF, WAV)</para></listitem>
 <listitem><para>%w %{marked} Marked, is 1 if the file is marked (<abbrev>e.g.</abbrev> because
 of truncation or standard violation), empty otherwise</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, <abbrev>i.e.</abbrev> 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>Incomplete</term><listitem>
 <para><userinput>
 %{title} equals "" or %{artist} equals "" or %{album} equals "" or %{year} equals "" or %{tracknumber} equals "" or %{genre} equals ""
 </userinput></para>
 <para>Displays files with empty values in the standard tags (title, artist,
  album, date, track number, genre).</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>Marked</term><listitem>
 <para><userinput>
 not (%{marked} equals "")
 </userinput></para>
 <para>Displays only files which are marked because they violate the ID3
 standard, are truncated or the picture is too large.</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 <keycap>Enter</keycap>. 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><para>
 The time displayed can be toggled between elapsed and remaining time by
 clicking on the display.
 </para></listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 </sect1>
 
 <sect1 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 folder.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>Settings</guimenu>
 <guimenuitem>Show 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-shortcuts">
 <term><menuchoice>
 <guimenu>Settings</guimenu>
 <guimenuitem>Configure Shortcut keys...</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, <abbrev>e.g.</abbrev> next file, previous file, select all.
 </para>
 <para>
 </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,
 which is itself separated into four tabs
 for <guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel>, <guilabel>Tag
 3</guilabel>, and <guilabel>All Tags</guilabel>.
 </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 transferred
 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 folder.
 </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>
 When <guilabel>WAV files with lowercase id3 chunk</guilabel> is checked, the
 RIFF chunk used to store ID3v2 tags in WAV files will be named "id3 " instead
 of "ID3 ". By default, &kid3; and other applications using TagLib accept both
 the lowercase and the uppercase variant when reading WAV files, but they use
 "ID3 " when writing ID3v2 tags to WAV files. As there exist other applications
 which only accept "id3 " (<abbrev>e.g.</abbrev> JRiver Media Center and foobar2000), this
 option can be used to create tags which can be read by such applications.
 </para>
 <para>
 When <guilabel>Mark standard violations</guilabel> is checked, ID3v2 fields
 which violate the standard will be marked red. Details about the violation are
 shown in a tooltip:
 </para>
 <itemizedlist>
 <listitem><para>Must be unique</para></listitem>
 <listitem><para>New line is forbidden</para></listitem>
 <listitem><para>Carriage return is forbidden</para></listitem>
 <listitem><para>Owner must be non-empty</para></listitem>
 <listitem><para>Must be numeric</para></listitem>
 <listitem><para>Must be numeric or number/total</para></listitem>
 <listitem><para>Format is DDMM</para></listitem>
 <listitem><para>Format is HHMM</para></listitem>
 <listitem><para>Format is YYYY</para></listitem>
 <listitem><para>Must begin with a year and a space character</para></listitem>
 <listitem><para>Must be ISO 8601 date/time</para></listitem>
 <listitem><para>Must be musical key, 3 characters, A-G, b, #, m, o</para></listitem>
 <listitem><para>Must have ISO 639-2 language code, 3 lowercase characters</para></listitem>
 <listitem><para>Must be ISRC code, 12 characters</para></listitem>
 <listitem><para>Must be list of strings separated by '|'</para></listitem>
 <listitem><para>Has excess white space</para></listitem>
 </itemizedlist>
 <para>
 The ID3 standard documents are available online:
 </para>
 <itemizedlist>
 <listitem><para><ulink url="http://id3.org/id3v2.3.0">ID3 tag version 2.3.0</ulink></para></listitem>
 <listitem><para><ulink url="http://id3.org/id3v2.4.0-structure">ID3 tag version 2.4.0 - Main Structure</ulink></para></listitem>
 <listitem><para><ulink url="http://id3.org/id3v2.4.0-frames">ID3 tag version 2.4.0 - Native Frames</ulink></para></listitem>
 </itemizedlist>
 <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.
 </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,
 "<literal>COMMENT</literal>" for instance is used by <application>XMMS</application>,
 whereas &amarok; uses "<literal>DESCRIPTION</literal>".
 </para>
 <para>
 The format of pictures in Ogg/Vorbis files is determined by
 <guilabel>Picture field name</guilabel>, which can be
 "<literal>METADATA_BLOCK_PICTURE</literal>" or "<literal>COVERART</literal>".
 The first is the official standard and uses the same format as pictures in FLAC
 tags. "<literal>COVERART</literal>" is an earlier unofficial way to include
 pictures in Vorbis comments. It can be used for compatibility with legacy players.
 </para>
 <para>
 If the <guilabel>Mark if larger than (bytes)</guilabel> check box is activated,
 files containing embedded album cover art exceeding the given size in bytes
 are marked red. This can be used to find files containing oversized pictures
 which are not accepted by some applications and players. The default value is
 131072 bytes (128 KB).
 </para>
 <para>
 <guilabel>Custom Genres</guilabel> can be used to define genres which are not
 available in the standard genre list, <abbrev>e.g.</abbrev> "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>
 In <guilabel>Custom Frames</guilabel>, up to eight custom frame names can be
 defined, which can then be used like the unified frames, for example as
 quick access frames.
 </para>
 <para>
 <guilabel>Quick Access Frames</guilabel> defines which frame types are always
 shown in the <link linkend="tag2">Tag 2</link> section. Such frames can
 then be added without first using the <guibutton>Add</guibutton> button.
 The order of these quick access frames can be changed by dragging and dropping
 items.
 </para>
 <para>
 The combo box <guilabel>Track number field name</guilabel> is only
 relevant for RIFF INFO and sets the name of the field used for
 track numbers. Track numbers are not specified in the original RIFF standard,
 there are applications which use "<literal>ITRK</literal>", others use
 "<literal>IPRT</literal>".
 </para>
 <para>
 <guilabel>Tag Format</guilabel> contains options for the format of the tags.
 When <guilabel>Automatically apply format</guilabel> is checked, the format
 configuration is automatically used while editing text in the line edits.
 <guilabel>Validation</guilabel> enables validators in the controls with
 track/total and date/time values.
 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>. To use locale-aware
 conversion between lowercase and uppercase characters, a locale can be
 selected in the combobox below.
 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. When the text to replace starts and ends with a slash ("/"),
 a regular expression is used. For regular expressions containing capturing
 groups, occurrences of \1, \2, ... in <guilabel>To</guilabel> are replaced
 with the string captured by the corresponding capturing group.
 To remove a mapping set the <guilabel>From</guilabel> cell
 to an empty value (<abbrev>e.g.</abbrev> by first typing space and then backspace). Inserting
 and deleting rows is also possible using a context menu which appears when the
 <mousebutton>right</mousebutton> mouse button is clicked.  Replacement is only active, if the <guilabel>String
 replacement</guilabel> check box is checked.
 </para>
 
 <para>
 The table in <guilabel>Rating</guilabel> contains the mapping of star ratings
 to the effective values stored in the tag. The frames with rating information
 are listed in the Rating row of the
 <!--change manpageframe list.--><link linkend="table-frame-list">frame list</link>.
 For these frames, the rating can be set by giving a number of
 stars out of five stars. Different tag formats and different applications use
 different values to map the star rating to the value stored in the tag. In
 order to display the correct number of stars, &kid3; will look up a map in
 this table. The key to look up the mapping is the frame name, for example
 "RATING" as used for Vorbis comments or "IRTD" for RIFF INFO. For ID3v2 tags,
 a combined key is used consisting of the frame ID "POPM" of the Popularimeter
 frame and its "Email" field, separated by a dot. Therefore, different keys for
 ID3v2 exist, <abbrev>e.g.</abbrev> "POPM.Windows Media Player 9 Series" for the mapping used by
 Windows Media Player and Explorer, and simply "POPM" for POPM frames with an
 empty "Email" field. As multiple entries for "POPM" can exist, their order is
 important. When &kid3; adds a new Popularimeter frame, it will use the first
 "POPM" entry to determine the value to be written into the "Email" field. This
 value will then specify the mapping to be used for star ratings. The first
 entry is also used if no key was found, it is therefore the default entry.
 </para>
 <para>
 Besides the <guilabel>Name</guilabel> column containing the keys, the table
 has columns <guilabel>1</guilabel> to <guilabel>5</guilabel> for the values to
 be stored when the corresponding number of stars is given. The other way
 round, the values determine the number of stars which are displayed for the
 value stored in the frame. For instance, the row in the table below contains
 the values 1, 64, 128, 196, 255. The thresholds for the number of stars to be
 displayed lay between these values and are compatible with what the &Windows;
 Explorer uses.
 </para>
 
 <table id="table-rating">
   <title>Entry in Rating Table</title>
   <tgroup cols="6">
     <thead>
       <row><entry>Name</entry><entry>1</entry> <entry>2</entry>  <entry>3</entry>  <entry>4</entry>  <entry>5</entry></row>
     </thead>
     <tbody>
       <row><entry>POPM</entry><entry>1</entry><entry>64</entry><entry>128</entry><entry>196</entry><entry>255</entry></row>
       <row><entry>Range</entry><entry>1-31</entry><entry>32-95</entry><entry>96-159</entry><entry>160-223</entry><entry>224-255</entry></row>
     </tbody>
   </tgroup>
 </table>
 
 <para>
 On the page <guilabel>Files</guilabel> the check box <guilabel>Load
 last-opened files</guilabel> can be marked so that &kid3; will open and
 select the last selected file when it is started the next time.
 <guilabel>Preserve file timestamp</guilabel> can be checked to preserve
 the file modification time stamp.
 <guilabel>Filename for cover</guilabel> sets the name which is suggested
 when an embedded image is exported to a file.
 With <guilabel>Text encoding (Export, Playlist)</guilabel> the encoding used
 when writing files can be set. The default <guilabel>System</guilabel> can be
 changed for example if playlists have to be used on a different device.
 </para>
 <para>
 If <guilabel>Mark changes</guilabel> is active, changed fields are marked with
 a light gray label background.
 </para>
 <para>
 The section <guilabel>File List</guilabel> determines which files are
 displayed in the file list. A <guilabel>Filter</guilabel> can be used to
 restrict the items in this list to files with supported extensions. To
 explicitly specify which folders to display in the file list or exclude
 certain folders, the options <guilabel>Include folders</guilabel> and
 <guilabel>Exclude folders</guilabel> can be used. They can contain wildcard
 expressions, for instance <filename>*/Music/*</filename> to include only the
 <filename>Music</filename> folder, or <filename>*/iTunes/*</filename> to
 exclude the iTunes folder from the file list. If multiple such expressions
 have to be used, they can be separated by spaces or semicolons.
 </para>
 <para>
 The buttons <guibutton>Filename from tag</guibutton> and <guibutton>Tag from
 filename</guibutton> in section <guilabel>Format</guilabel> open dialogs to
 edit the formats which are available in the <guilabel>Format</guilabel> combo
 boxes (with arrows up and down), which can be found in the
 <link linkend="file">File</link> section of the main window.
 </para>
 <para>
 The <guibutton>Playlist</guibutton> button can be used to edit the file name
 formats available in the <link linkend="create-playlist">Create Playlist</link>
 dialog.
 </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>
 Additionally, the <guilabel>Maximum length</guilabel> allowed for file names can
 be set. Most modern file systems have a limit of 255 characters, but if you want
 to burn the files to CD, you should set the limit to 64.
 If <guilabel>Use for playlist and folder names</guilabel> is checked, the
 file name format is also used when creating playlists and renaming folders.
 </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} &URL;s (a list if multiple files selected)</para></listitem>
 <listitem><para>%uf %{url} &URL; to single file</para></listitem>
 <listitem><para>%d %{directory} Folder</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 (<abbrev>e.g.</abbrev> 01)</para></listitem>
 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
 <listitem><para>%g %{genre} Genre</para></listitem>
 <listitem><para>%b %{browser} Command to start the web browser</para></listitem>
 <listitem><para>%q %{qmlpath} Base folder of provided QML files</para></listitem>
 </itemizedlist>
 
 <para>
 The special code <command>@separator</command> can be set as a command to
 insert a separator into the user actions context menu. Menu items can be put
 into a submenu by enclosing them with <command>@beginmenu</command> and
 <command>@endmenu</command> commands. The name of the submenu is determined by
 the <guilabel>Name</guilabel> column of the <command>@beginmenu</command>
 command.
 </para>
 
 <para id="configure-user-actions-qml">
 To execute QML scripts, <command>@qml</command> is used as a command name. The
 path to the QML script is passed as a parameter. The provided scripts can be
 found in the folder <filename>%{qmlpath}/script/</filename> (on
 &Linux; typically <filename>/usr/share/kid3/qml/script/</filename>, on
 Windows <filename>qml/script/</filename> inside the installation folder,
 and on &macOS; in the app folder
 <filename>kid3.app/Contents/Resources/qml/script/</filename>). Custom scripts
 can be stored in any folder. If the QML code uses &GUI; components,
 <command>@qmlview</command> shall be used instead of
 <command>@qml</command>. Additional parameters are passed to the QML script
 where they will be available via the <function>getArguments()</function>
 function. An overview of some functions and properties which are available in
 QML can be found in the appendix <link linkend="qml-interface">QML Interface</link>.
 </para>
 
 <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, <abbrev>e.g.</abbrev> 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 check box is checked.
 </para>
 <para>
 In the <guilabel>Plugins</guilabel> page, available plugins can be enabled or
 disabled. The plugins are separated into two sections. The <guilabel>Metadata
 Plugins &amp; Priority</guilabel> list contains plugins which support audio
 file formats. The order of the plugins is important because they are tried from
 top to bottom. Some formats are supported by multiple plugins, so files will
 be opened with the first plugin supporting them. The
 <guilabel>TaglibMetadata</guilabel> supports most formats, if it is at the top
 of the list, it will open most of the files. If you want to use a different
 plugin for a file format, make sure that it is listed before the
 <guilabel>TaglibMetadata</guilabel> plugin. Details about the metadata plugin
 and why you may want to use them instead of TagLib are listed below.
 </para>
 <itemizedlist>
 <listitem><para><guilabel>Id3libMetadata</guilabel>:
 Uses <ulink url="http://id3lib.sourceforge.net">id3lib</ulink> for ID3v1.1
 and ID3v2.3 tags in MP3, MP2, AAC files. Supports a few more frame types
 than TagLib.</para></listitem>
 <listitem><para><guilabel>OggFlacMetadata</guilabel>:
 Uses <ulink url="http://xiph.org/ogg/">libogg</ulink>,
 <ulink url="http://xiph.org/vorbis/">libvorbis, libvorbisfile</ulink> for Ogg
 files, and additionally <ulink url="http://flac.sourceforge.net">libFLAC++
 and libFLAC</ulink> for FLAC files. These are the official
 libraries for these formats.</para></listitem>
 <listitem><para><guilabel>TaglibMetadata</guilabel>:
 Uses <ulink url="http://taglib.github.io/">TagLib</ulink> which supports a
 lot of audio file formats. It can be used for all audio files supported by
 &kid3;.</para></listitem>
 <listitem><para><guilabel>Mp4v2Metadata</guilabel>:
 <ulink url="https://mp4v2.org/">mp4v2</ulink> was originally used
 by &kid3; to support M4A files. Can be used in case of problems with the M4A
 support of TagLib.
 </para></listitem>
 </itemizedlist>
 <para>
 The <guilabel>Available Plugins</guilabel> section lists the remaining
 plugins. Their order is not important, but they can be enabled or disabled
 using the check boxes.
 </para>
 <itemizedlist>
 <listitem><para><guilabel>AmazonImport</guilabel>:
 Used for the <guimenuitem>Import from Amazon...</guimenuitem> function.
 </para></listitem>
 <listitem><para><guilabel>DiscogsImport</guilabel>:
 Used for the <guimenuitem>Import from Discogs...</guimenuitem> function.
 </para></listitem>
 <listitem><para><guilabel>FreedbImport</guilabel>:
 Used for the <guimenuitem>Import from gnudb.org...</guimenuitem>
 function.
 </para></listitem>
 <listitem><para><guilabel>MusicBrainzImport</guilabel>:
 Used for the <guimenuitem>Import from MusicBrainz Release...</guimenuitem>
 function.
 </para></listitem>
 <listitem><para><guilabel>AcoustidImport</guilabel>:
 Used for the <guimenuitem>Import from MusicBrainz Fingerprint...</guimenuitem>
 function, which depends on
 the <ulink url="http://acoustid.org/chromaprint">Chromaprint</ulink>
 and <ulink url="http://libav.org/">libav</ulink> libraries.
 </para></listitem>
 </itemizedlist>
 <para>
 Plugins which are disabled will not be loaded. This can be used to optimize
 resource usage and startup time. The settings on this page take only effect
 after a restart of &kid3;.
 </para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect1>
 
 <sect1 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>
 
 </sect1>
 
 </chapter>
 
 <chapter id="kid3-cli">
 <title>kid3-cli</title>
 <sect1 id="kid3-cli-commands">
 <title>Commands</title>
 <para>
 <command>kid3-cli</command> offers a command-line-interface for &kid3;. If a
 folder path is used, the folder is opened. If one or more file paths are
 given, the common folder is opened and the files are selected. Subsequent
 commands will then work on these files. Commands are specified using
 <option>-c</option> options. If multiple commands are passed, they are
 executed in the given order. If files are modified by the commands, they will
 be saved at the end. If no command options are passed,
 <command>kid3-cli</command> starts in interactive mode. Commands can be
 entered and will operate on the current selection. The following sections
 list all available commands.
 </para>
 
 <sect2 id="cli-help">
 <title>Help</title>
 <cmdsynopsis>
 <command>help</command>
 <arg><replaceable>COMMAND-NAME</replaceable></arg>
 </cmdsynopsis>
 <para>Displays help about the parameters of
 <replaceable>COMMAND-NAME</replaceable> or about all commands if no command
 name is given.
 </para>
 </sect2>
 
 <sect2 id="cli-timeout">
 <title>Timeout</title>
 <cmdsynopsis>
 <command>timeout</command>
 <group>
 <arg choice="plain">default</arg>
 <arg choice="plain">off</arg>
 <arg choice="plain"><replaceable>TIME</replaceable></arg>
 </group>
 </cmdsynopsis>
 <para>Overwrite the default command timeout. The CLI commands abort after a
 command specific timeout is expired. This timeout is 10 seconds for
 <command>ls</command> and <command>albumart</command>, 60 seconds for
 <command>autoimport</command> and <command>filter</command>, and 3 seconds for
 all other commands. If a huge number of files has to be processed, these
 timeouts may be too restrictive, thus the timeout for all commands can be set
 to <replaceable>TIME</replaceable> ms, switched off altogether or be left at
 the default values.
 </para>
 </sect2>
 
 <sect2 id="cli-exit">
 <title>Quit application</title>
 <cmdsynopsis>
 <command>exit</command>
 <arg>force</arg>
 </cmdsynopsis>
 <para>Exit application. If there are modified unsaved files, the <parameter
 class="command">force</parameter> parameter is required.
 </para>
 </sect2>
 
 <sect2 id="cli-cd">
 <title>Change folder</title>
 <cmdsynopsis>
 <command>cd</command>
 <arg><replaceable>FOLDER</replaceable></arg>
 </cmdsynopsis>
 <para>If no <replaceable>FOLDER</replaceable> is given, change to the home
 folder. If a folder is given, change into the folder. If one or more
 file paths are given, change to their common folder and select the files.
 </para>
 </sect2>
 
 <sect2 id="cli-pwd">
 <title>Print the filename of the current folder</title>
 <cmdsynopsis>
 <command>pwd</command>
 </cmdsynopsis>
 <para>Print the filename of the current working folder.</para>
 </sect2>
 
 <sect2 id="cli-ls">
 <title>Folder list</title>
 <cmdsynopsis>
 <command>ls</command>
 </cmdsynopsis>
 <para>List the contents of the current folder. This corresponds to the file
 list in the &kid3; &GUI;. Five characters before the file names show the state
 of the file.
 </para>
 
 <itemizedlist>
 <listitem><para><computeroutput>&gt;</computeroutput> File is selected.
 </para></listitem>
 <listitem><para><computeroutput>*</computeroutput> File is modified.
 </para></listitem>
 <listitem><para><computeroutput>1</computeroutput> File has a tag 1,
 otherwise '<computeroutput>-</computeroutput>' is displayed.</para></listitem>
 <listitem><para><computeroutput>2</computeroutput> File has a tag 2,
 otherwise '<computeroutput>-</computeroutput>' is displayed.</para></listitem>
 <listitem><para><computeroutput>3</computeroutput> File has a tag 3,
 otherwise '<computeroutput>-</computeroutput>' is displayed.</para></listitem>
 </itemizedlist>
 
 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
   1-- 01 Intro.mp3
 > 12- 02 We Only Got This One.mp3
  *1-- 03 Outro.mp3</computeroutput></screen>
 
 <para>In this example, all files have a tag 1, the second file also has a tag
 2 and it is selected. The third file is modified.
 </para>
 </sect2>
 
 <sect2 id="cli-save">
 <title>Save the changed files</title>
 <cmdsynopsis>
 <command>save</command>
 </cmdsynopsis>
 <para>
 </para>
 </sect2>
 
 <sect2 id="cli-select">
 <title>Select file</title>
 <cmdsynopsis>
 <command>select</command>
 <group>
 <arg choice="plain">all</arg>
 <arg choice="plain">none</arg>
 <arg choice="plain">first</arg>
 <arg choice="plain">previous</arg>
 <arg choice="plain">next</arg>
 <arg choice="plain" rep="repeat"><replaceable>FILE</replaceable></arg>
 </group>
 </cmdsynopsis>
 <para>To select all files, enter <userinput>select all</userinput>, to
 deselect all files, enter <userinput>select none</userinput>. To traverse the
 files in the current folder start with <userinput>select first</userinput>,
 then go forward using <userinput>select next</userinput> or backward using
 <userinput>select previous</userinput>. Specific files can be added to the
 current selection by giving their file names. Wildcards are possible, so
 <userinput>select *.mp3</userinput> will select all MP3 files in the current
 folder.
 </para>
 
 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>select first</userinput>
 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
 > 1-- 01 Intro.mp3
   12- 02 We Only Got This One.mp3
  *1-- 03 Outro.mp3</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>select next</userinput>
 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
   1-- 01 Intro.mp3
 > 12- 02 We Only Got This One.mp3
  *1-- 03 Outro.mp3</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>select *.mp3</userinput>
 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
 > 1-- 01 Intro.mp3
 > 12- 02 We Only Got This One.mp3
 >*1-- 03 Outro.mp3</computeroutput></screen>
 </sect2>
 
 <sect2 id="cli-tag">
 <title>Select tag</title>
 <cmdsynopsis>
 <command>tag</command>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Many commands have an optional <replaceable>TAG-NUMBERS</replaceable>
 parameter, which specifies whether the command operates on tag 1, 2, or 3. If
 this parameter is omitted, the default tag numbers are used, which can be set
 by this command. At startup, it is set to <literal>12</literal> which means
 that information is read from tag 2 if available, else from tag 1;
 modifications are done on tag 2. The
 <option><replaceable>TAG-NUMBERS</replaceable></option> can be set to
 <userinput>1</userinput>, <userinput>2</userinput>, or
 <userinput>3</userinput> to operate only on the
 corresponding tag. If the parameter is omitted, the current setting is
 displayed.
 </para>
 </sect2>
 
 <sect2 id="cli-get">
 <title>Get tag frame</title>
 <cmdsynopsis>
 <command>get</command>
 <group>
 <arg choice="plain">all</arg>
 <arg choice="plain"><replaceable>FRAME-NAME</replaceable></arg>
 </group>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>This command can be used to read the value of a specific tag frame or
 get information about all tag frames (if the argument is omitted or
 <option>all</option> is used). Modified frames are marked with a
 '<computeroutput>*</computeroutput>'.
 </para>
 
 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>get</userinput><computeroutput>
 File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
   Name: 01 Intro.mp3
 Tag 1: ID3v1.1
   Title         Intro
   Artist        One Hit Wonder
   Album         Let's Tag
   Date          2013
   Track Number  1
   Genre         Pop</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>get title</userinput><computeroutput>
 Intro</computeroutput></screen>
 <para>To save the contents of a picture frame to a file, use
 <screen width="65"><userinput>get picture:'/path/to/folder.jpg'</userinput></screen>
 </para>
 <para>To save synchronized lyrics to an LRC file, use
 <screen width="65"><userinput>get SYLT:'/path/to/lyrics.lrc'</userinput></screen>
 </para>
 <para>It is possible to get only a specific field from a frame, for example
 <userinput>get POPM.Email</userinput> for the Email field of a Popularimeter
 frame. If a file has multiple frames of the same kind, the different frames
 can be indexed with brackets, for example the first performer from a Vorbis
 comment can be retrieved using <userinput>get performer[0]</userinput>,
 the second using <userinput>get performer[1]</userinput>.
 </para>
 <para>
 The pseudo field name "selected" can be used to check if a frame is selected,
 for example <userinput>get artist.selected</userinput> will return
 <computeroutput>1</computeroutput> if the artist frame is selected, else
 <computeroutput>0</computeroutput>.
 </para>
 <para>
 The pseudo frame name "ratingstars" can be used to get the value of the
 "rating" frame as the format specific value corresponding to the number of
 stars (0 to 5). When using "rating", the internal value is returned.
 </para>
 </sect2>
 
 <sect2 id="cli-set">
 <title>Set tag frame</title>
 <cmdsynopsis>
 <command>set</command>
 <arg choice="req"><replaceable>FRAME-NAME</replaceable></arg>
 <arg choice="req"><replaceable>FRAME-VALUE</replaceable></arg>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>This command sets the value of a specific tag frame.
 If <replaceable>FRAME-VALUE</replaceable> is empty, the frame is deleted.
 </para>
 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>set remixer 'O.H. Wonder'</userinput></screen>
 <para>To set the contents of a picture frame from a file, use
 <screen width="65"><userinput>set picture:'/path/to/folder.jpg' 'Picture Description'</userinput></screen>
 </para>
 <para>To set synchronized lyrics from an LRC file, use
 <screen width="65"><userinput>set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'</userinput></screen>
 </para>
 <para>
 To set a specific field of a frame, the field name can be given after a dot,
 <abbrev>e.g.</abbrev> to set the Counter field of a Popularimeter frame, use
 <screen width="65"><userinput>set POPM.Counter 5</userinput></screen>
 </para>
 <para>
 An application for field specifications is the case where you want a custom
 TXXX frame with "rating" description instead of a standard Popularimeter frame
 (this seems to be used by some plugins). You can create such a TXXX rating
 frame with <command>kid3-cli</command>, however, you have to first create a
 TXXX frame with description "rating" and then set the value of this frame to
 the rating value.
 <screen width="65">
 <prompt>kid3-cli&gt; </prompt><userinput>set rating ""</userinput>
 <prompt>kid3-cli&gt; </prompt><userinput>set TXXX.Description rating</userinput>
 <prompt>kid3-cli&gt; </prompt><userinput>set rating 5</userinput>
 </screen>
 The first command will delete an existing POPM frame, because if such a frame
 exists, <userinput>set rating 5</userinput> would set the POPM frame and not
 the TXXX frame. Another possibility would be to use <userinput>set TXXX.Text
 5</userinput>, but this would only work if there is no other TXXX frame
 present.
 </para>
 <para>
 To set multiple frames of the same kind, an index can be given in brackets,
 <abbrev>e.g.</abbrev> to set multiple performers in a Vorbis comment, use
 <screen width="65">
 <prompt>kid3-cli&gt; </prompt><userinput>set performer[0] 'Liza don Getti (soprano)'</userinput>
 <prompt>kid3-cli&gt; </prompt><userinput>set performer[1] 'Joe Barr (piano)'</userinput>
 </screen>
 </para>
 <para>
 To select certain frames before a copy, paste or remove action, the pseudo
 field name "selected" can be used. Normally, all frames are selected, to
 deselect all, use <userinput>set '*.selected' 0</userinput>, then for example
 <userinput>set artist.selected 1</userinput> to select the artist frame.
 </para>
 <para>
 The pseudo frame name "ratingstars" can be used to set the value of the
 "rating" frame to the format specific value corresponding to the number of
 stars (0 to 5). The frame name "rating" can be used to set the internal
 value.
 </para>
 <para>
 Setting "ratingstars" on multiple files having different tag formats will not
 work because the frame with the value mapped from the star count is created
 for the first file and then used for all files. So instead of
 <userinput>kid3-cli -c "set ratingstars 2" *</userinput> you should rather use
 <userinput>for f in *; do kid3-cli -c "set ratingstars 2" "$f"; done</userinput>.
 </para>
 </sect2>
 
 <sect2 id="cli-revert">
 <title>Revert</title>
 <cmdsynopsis>
 <command>revert</command>
 </cmdsynopsis>
 <para>Revert all modifications in the selected files (or all files if no files
 are selected).
 </para>
 </sect2>
 
 <sect2 id="cli-import">
 <title>Import from file</title>
 <cmdsynopsis>
 <command>import</command>
 <arg choice="req"><replaceable>FILE</replaceable></arg>
 <arg choice="req"><replaceable>FORMAT-NAME</replaceable></arg>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Tags are imported from the file <replaceable>FILE</replaceable>
 in the format with the name
 <replaceable>FORMAT-NAME</replaceable> (<abbrev>e.g.</abbrev> <userinput>"CSV
 unquoted"</userinput>, see <link linkend="import-text">Import</link>).
 </para>
 <para>If <userinput>tags</userinput> is given for
 <replaceable>FILE</replaceable>, tags are imported from other tags. Instead of
 <replaceable>FORMAT-NAME</replaceable> parameters
 <replaceable>SOURCE</replaceable> and <replaceable>EXTRACTION</replaceable>
 are required, see <link linkend="import-tags">Import from Tags</link>.
 To apply the import from tags on the selected files, use
 <userinput>tagsel</userinput> instead of <userinput>tags</userinput>.
 This function also supports output of the extracted value by using an
 <replaceable>EXTRACTION</replaceable> with the value
 <userinput>%{__return}(.+)</userinput>.
 </para>
 </sect2>
 
 <sect2 id="cli-autoimport">
 <title>Automatic import</title>
 <cmdsynopsis>
 <command>autoimport</command>
 <arg><replaceable>PROFILE-NAME</replaceable></arg>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Batch import using profile <replaceable>PROFILE-NAME</replaceable> (see
 <link linkend="batch-import">Automatic Import</link>,
 <userinput>"All"</userinput> is used if omitted).
 </para>
 </sect2>
 
 <sect2 id="cli-albumart">
 <title>Download album cover artwork</title>
 <cmdsynopsis>
 <command>albumart</command>
 <arg choice="req"><replaceable>URL</replaceable></arg>
 <arg>all</arg>
 </cmdsynopsis>
 <para>Set the album artwork by downloading a picture from
 <replaceable>URL</replaceable>. The rules defined in the <link
 linkend="browse_pictures">Browse Cover Art</link> dialog are used to transform
 general &URL;s (<abbrev>e.g.</abbrev> from Amazon) to a picture &URL;. To set the album cover from
 a local picture file, use the <link linkend="cli-set">set</link> command.
 </para>
 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>albumart
 http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC</userinput></screen>
 </sect2>
 
 <sect2 id="cli-export">
 <title>Export to file</title>
 <cmdsynopsis>
 <command>export</command>
 <arg choice="req"><replaceable>FILE</replaceable></arg>
 <arg choice="req"><replaceable>FORMAT-NAME</replaceable></arg>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Tags are exported to file <replaceable>FILE</replaceable>
 in the format with the name
 <replaceable>FORMAT-NAME</replaceable> (<abbrev>e.g.</abbrev> <userinput>"CSV
 unquoted"</userinput>, see <link linkend="export">Export</link>).
 </para>
 </sect2>
 
 <sect2 id="cli-playlist">
 <title>Create playlist</title>
 <cmdsynopsis>
 <command>playlist</command>
 </cmdsynopsis>
 <para>Create playlist in the format set in the configuration, see <link
 linkend="create-playlist">Create Playlist</link>.
 </para>
 </sect2>
 
 <sect2 id="cli-filenameformat">
 <title>Apply filename format</title>
 <cmdsynopsis>
 <command>filenameformat</command>
 </cmdsynopsis>
 <para>Apply file name format set in the configuration, see <link linkend="apply-filename-format">Apply Filename Format</link>.
 </para>
 </sect2>
 
 <sect2 id="cli-tagformat">
 <title>Apply tag format</title>
 <cmdsynopsis>
 <command>tagformat</command>
 </cmdsynopsis>
 <para>Apply tag name format set in the configuration, see <link linkend="apply-tag-format">Apply Tag Format</link>.
 </para>
 </sect2>
 
 <sect2 id="cli-textencoding">
 <title>Apply text encoding</title>
 <cmdsynopsis>
 <command>textencoding</command>
 </cmdsynopsis>
 <para>Apply text encoding set in the configuration, see <link linkend="apply-text-encoding">Apply Text Encoding</link>.
 </para>
 </sect2>
 
 <sect2 id="cli-renamedir">
 <title>Rename folder</title>
 <cmdsynopsis>
 <command>renamedir</command>
 <arg><replaceable>FORMAT</replaceable></arg>
 <group>
 <arg choice="plain">create</arg>
 <arg choice="plain">rename</arg>
 <arg choice="plain">dryrun</arg>
 </group>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Rename or create folders from the values in the
 tags according to a given <replaceable>FORMAT</replaceable>
 (<abbrev>e.g.</abbrev> <userinput>%{artist} - %{album}</userinput>, see <link
 linkend="rename-directory">Rename Folder</link>), if no format is given,
 the format defined in the <guilabel>Rename folder</guilabel> dialog is
 used. The default mode is <option>rename</option>; to create folders,
 <option>create</option> must be given explicitly. The rename actions will be
 performed immediately, to just see what would be done, use the
 <option>dryrun</option> option.
 </para>
 </sect2>
 
 <sect2 id="cli-numbertracks">
 <title>Number tracks</title>
 <cmdsynopsis>
 <command>numbertracks</command>
 <arg><replaceable>TRACK-NUMBER</replaceable></arg>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Number the selected tracks starting with
 <replaceable>TRACK-NUMBER</replaceable> (<literal>1</literal> if omitted).
 </para>
 </sect2>
 
 <sect2 id="cli-filter">
 <title>Filter</title>
 <cmdsynopsis>
 <command>filter</command>
 <group>
 <arg choice="plain"><replaceable>FILTER-NAME</replaceable></arg>
 <arg choice="plain"><replaceable>FILTER-FORMAT</replaceable></arg>
 </group>
 </cmdsynopsis>
 <para>Filter the files so that only the files matching the
 <replaceable>FILTER-FORMAT</replaceable> are visible. The name of a predefined
 filter expression (<abbrev>e.g.</abbrev> <userinput>"Filename Tag Mismatch"</userinput>) can be
 used instead of a filter expression, see <link linkend="filter">Filter</link>.
 </para>
 
 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>filter '%{title} contains "tro"'</userinput><computeroutput>
 Started
   /home/urs/One Hit Wonder - Let's Tag
 + 01 Intro.mp3
 - 02 We Only Got This One.mp3
 + 03 Outro.mp3
 Finished</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
   1-- 01 Intro.mp3
   1-- 03 Outro.mp3</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>filter All</userinput><computeroutput>
 Started
   /home/urs/One Hit Wonder - Let's Tag
 + 01 Intro.mp3
 + 02 We Only Got This One.mp3
 + 03 Outro.mp3
 Finished</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
   1-- 01 Intro.mp3
   12- 02 We Only Got This One.mp3
   1-- 03 Outro.mp3</computeroutput></screen>
 </sect2>
 
 <sect2 id="cli-to24">
 <title>Convert ID3v2.3 to ID3v2.4</title>
 <cmdsynopsis>
 <command>to24</command>
 </cmdsynopsis>
 </sect2>
 
 <sect2 id="cli-to23">
 <title>Convert ID3v2.4 to ID3v2.3</title>
 <cmdsynopsis>
 <command>to23</command>
 </cmdsynopsis>
 </sect2>
 
 <sect2 id="cli-fromtag">
 <title>Filename from tag</title>
 <cmdsynopsis>
 <command>fromtag</command>
 <arg><replaceable>FORMAT</replaceable></arg>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Set the file names of the selected files from values in the tags, for
 example <userinput>fromtag '%{track} - %{title}' 1</userinput>. If no format
 is specified, the format set in the &GUI; is used.
 </para>
 </sect2>
 
 <sect2 id="cli-totag">
 <title>Tag from filename</title>
 <cmdsynopsis>
 <command>totag</command>
 <arg><replaceable>FORMAT</replaceable></arg>
 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
 </cmdsynopsis>
 <para>Set the tag frames from the file names, for example <userinput>totag
 '%{albumartist} - %{album}/%{track} %{title}' 2</userinput>. If no format
 is specified, the format set in the &GUI; is used. If the format
 of the filename does not match this pattern, a few other commonly used formats
 are tried.
 </para>
 </sect2>
 
 <sect2 id="cli-syncto">
 <title>Tag to other tag</title>
 <cmdsynopsis>
 <command>syncto</command>
 <arg choice="req"><replaceable>TAG-NUMBER</replaceable></arg>
 </cmdsynopsis>
 <para>Copy the tag frames from one tag to the other tag, <abbrev>e.g.</abbrev> to set the ID3v2
 tag from the ID3v1 tag, use <userinput>syncto 2</userinput>.
 </para>
 </sect2>
 
 <sect2 id="cli-copy">
 <title>Copy</title>
 <cmdsynopsis>
 <command>copy</command>
 <arg><replaceable>TAG-NUMBER</replaceable></arg>
 </cmdsynopsis>
 <para>Copy the tag frames of the selected file to the internal copy
 buffer. They can then be set on another file using the
 <command>paste</command> command.
 </para>
 <para>
 To copy only a subset of the frames, use the "selected" pseudo field with the
 <command>set</command> command. For example, to copy only the disc number and
 copyright frames, use
 <screen width="65">
 <userinput>set '*.selected' 0</userinput>
 <userinput>set discnumber.selected 1</userinput>
 <userinput>set copyright.selected 1</userinput>
 <userinput>copy</userinput>
 </screen>
 </para>
 </sect2>
 
 <sect2 id="cli-paste">
 <title>Paste</title>
 <cmdsynopsis>
 <command>paste</command>
 <arg><replaceable>TAG-NUMBER</replaceable></arg>
 </cmdsynopsis>
 <para>Set tag frames from the contents of the <command>copy</command> buffer
 in the selected files.
 </para>
 </sect2>
 
 <sect2 id="cli-remove">
 <title>Remove</title>
 <cmdsynopsis>
 <command>remove</command>
 <arg><replaceable>TAG-NUMBER</replaceable></arg>
 </cmdsynopsis>
 <para>Remove a tag.
 </para>
 <para>It is possible to remove only a subset of the frames by selecting them
 as described in the <link linkend="cli-copy"><command>copy</command>
 command</link>.
 </para>
 </sect2>
 
 <sect2 id="cli-config">
 <title>Configure Kid3</title>
 <cmdsynopsis>
 <command>config</command>
 <arg><replaceable>OPTION</replaceable></arg>
 <arg><replaceable>VALUE</replaceable></arg>
 </cmdsynopsis>
 <para>Query or set a configuration option.
 </para>
 <para>The <replaceable>OPTION</replaceable> consists of a group name and a
 property name separated by a dot. When no <replaceable>OPTION</replaceable> is
 given, all available groups are displayed. If only a group name is given, all
 available properties of the group are displayed. For a given group and property,
 the currently configured value is displayed. To change the setting, the new
 value can be passed as a second argument.
 </para>
 <para>If the value of a setting is a list, all list elements have to be given
 as arguments. This means that to append an element to an existing list of
 elements, all existing elements have to be passed followed by the new element.
 In such a situation, it is easier to use the JSON mode, where the current
 list can be copied with the new element appended.
 </para>
 </sect2>
 
 <sect2 id="cli-execute">
 <title>Execute program or QML script</title>
 <cmdsynopsis>
 <command>execute</command>
 <arg choice="opt">@qml</arg>
 <arg choice="req"><replaceable>FILE</replaceable></arg>
 <arg choice="opt"><replaceable>ARGS</replaceable></arg>
 </cmdsynopsis>
 <para>Execute a QML script or an executable.
 </para>
 <para>
 Without <option>@qml</option> a program is executed with arguments.
 When <option>@qml</option> is given as the first argument, the following
 arguments are the QML script and its arguments. For example, the tags
 of a folder can be exported to the file <filename>export.csv</filename> with
 the following command.
 </para>
 <screen width="65"><userinput>kid3-cli -c "execute @qml
 /usr/share/kid3/qml/script/ExportCsv.qml export.csv"
 /path/to/folder/</userinput></screen>
 <para>
 Here <option>export.csv</option> is the argument for the
 <filename>ExportCsv.qml</filename> script, whereas
 <option>/path/to/folder/</option> is the
 <option><replaceable>FILE</replaceable></option> argument for
 <command>kid3-cli</command>.
 </para>
 </sect2>
 
 </sect1>
 
 <sect1 id="kid3-cli-examples">
 <title>Examples</title>
 <para>Set title containing an apostrophe. Commands passed to
 <command>kid3-cli</command> with <parameter>-c</parameter>
 have to be in quotes if they do not only consist of a single word. If such a
 command itself has an argument containing spaces, that argument has to be
 quoted too. In &UNIX; shells single or double quotes can be used, but on the
 Windows Command Prompt, it is important that the outer quoting is done using
 double quotes and inside these quotes, single quotes are used. If the text
 inside the single quotes contains a single quote, it has to be escaped using a
 backslash character, as shown in the following example:</para>
 <screen width="65"><userinput>kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder</userinput></screen>
 
 <para>Set album cover in all files of a folder using the batch import
 function:</para>
 <screen width="65"><userinput>kid3-cli -c "autoimport 'Cover Art'" /path/to/folder</userinput></screen>
 
 <para>Remove comment frames and apply the tag format in both tags of all MP3
 files of a folder:</para>
 <screen width="65"><userinput>kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
 -c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3</userinput></screen>
 
 <para>Automatically import tag 2, synchronize to tag 1, set file names from
 tag 2 and finally create a playlist:</para>
 <screen width="65"><userinput>kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
   /path/to/folder/*.mp3</userinput></screen>
 
 <para>For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
 the arranger frame:</para>
 <screen width="65"><userinput>kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
   -c "set arranger ''" /path/to/folder</userinput></screen>
 
 <para>This Python script uses <command>kid3-cli</command> to generate iTunes
 Sound Check iTunNORM frames from replay gain information.</para>
 <programlisting>
 <![CDATA[
 #!/usr/bin/env python3
 # Generate iTunes Sound Check from ReplayGain.
 import os, sys, subprocess
 
 def rg2sc(dirpath):
   for root, dirs, files in os.walk(dirpath):
     for name in files:
       if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
         fn = os.path.join(root, name)
         rg = subprocess.check_output([
           'kid3-cli', '-c', 'get "replaygain_track_gain"',
            fn]).strip()
         if rg.endswith(b' dB'):
           rg = rg[:-3]
         try:
           rg = float(rg)
         except ValueError:
           print('Value %s of %s in not a float' % (rg, fn))
           continue
         sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
         subprocess.call([
           'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
 
 if __name__ == '__main__':
   rg2sc(sys.argv[1])
 ]]>
 </programlisting>
 </sect1>
 
 <sect1 id="kid3-cli-json">
 <title>&JSON; Format</title>
 <para>
 In order to make it easier to parse results from <command>kid3-cli</command>,
 it is possible to get the output in &JSON; format. When the request is in &JSON;
 format, the response will also be &JSON;. A compact format of the request will
 also give a compact representation of the response. If the request contains an
 "id" field, it is assumed to be a &JSON;-RPC request and the response will
 contain a "jsonrpc" field and the "id" of the request. The request format uses
 the same commands as the standard CLI, the "method" field contains the command
 and the parameters (if any) are given in the "params" list. The response
 contains a "result" object, which can also be null if the corresponding
 <command>kid3-cli</command> command does not return a result. In case of an
 error, an "error" object is returned with "code" and "message" fields as used
 in &JSON;-RPC.
 
 <screen width="80">
 <prompt>kid3-cli&gt; </prompt><userinput>{"method":"set","params":["artist","An Artist"]}</userinput>
 <computeroutput>{"result":null}</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>{"method":"get","params":["artist",2]}</userinput>
 <computeroutput>{"result":"An Artist"}</computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>{"method": "get", "params": ["artist"]}</userinput>
 <computeroutput>{
     "result": "An Artist"
 }
 </computeroutput>
 <prompt>kid3-cli&gt; </prompt><userinput>{"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}</userinput>
 <computeroutput>{"id":"123","jsonrpc":"2.0","result":"An Artist"}</computeroutput>
 </screen>
 
 </para>
 </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>
 
 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 
 &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="https://kid3.kde.org">https://kid3.kde.org</ulink>.
 </para>
 </sect1>
 
 <sect1 id="requirements">
 <title>Requirements</title>
 
 <para>
 &kid3; needs <ulink url="https://www.qt.io">&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, <abbrev>e.g.</abbrev> for GNU/&Linux;, &Windows;
 and &macOS;.
 
 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.
 These four formats are also supported by
 <ulink url="http://taglib.github.io/">TagLib</ulink>,
 which can also handle Opus, MPC, APE, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF
 files and tracker modules.
 To import from acoustic fingerprints,
 <ulink url="http://acoustid.org/chromaprint">Chromaprint</ulink>
 and <ulink url="http://libav.org/">libav</ulink> are used.
 </para>
 <para>
 &kid3; is available for most &Linux; distributions, &Windows; and &macOS;.
 Links can be found on <ulink url="https://kid3.kde.org">
 https://kid3.kde.org</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; version, go into the top folder 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>cmake</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>-DWITH_TAGLIB:BOOL=ON -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON
 -DWITH_CHROMAPRINT:BOOL=ON -DWITH_VORBIS:BOOL=ON -DWITH_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 the
 <userinput>cmake</userinput> option <userinput>-DWITH_APPS=Qt</userinput>.
 To build both a &kde; and a &Qt; application, set
 <userinput>-DWITH_APPS="Qt;KDE"</userinput>.
 </para>
 <para>
 To use a specific &Qt; installation, set
 <userinput>-DQT_QMAKE_EXECUTABLE=/path/to/qmake</userinput>.
 </para>
 <para>
 Generation of RPM-Packages is supported by the
 file <filename>kid3.spec</filename>, for &Debian; Packages,
 run <userinput>build.sh deb</userinput>.
 </para>
 
 <para>
 The &Qt; application can also be compiled for &Windows; and &macOS;.
 The script <filename>build.sh</filename> can be used to download
 and build all required libraries and create a &kid3; package.
 </para>
 
 </sect1>
 
 <sect1 id="configuration">
 <title>Configuration</title>
 
 <para>With &kde;, the settings are stored in
 <filename>.config/kid3rc</filename>,
 the application state in <filename>.local/share/kid3/kid3staterc</filename>.
 As a &Qt; application, this file is
 in <filename>.config/Kid3/Kid3.conf</filename>. On &Windows;,
 the configuration is stored in the registry. on &macOS; in a plist file.
 </para>
 <para>The environment variable <varname>KID3_CONFIG_FILE</varname> can be used
 to set the path of the configuration file.</para>
 
 </sect1>
 
 </appendix>
 
 <appendix id="dbus-interface">
 <title>&DBus; Interface</title>
 
 <sect1 id="dbus-examples">
 <title>&DBus; Examples</title>
 
 <para>
 On &Linux; a &DBus;-interface can be used to control
 &kid3; by scripts. Scripts can be written in any language with &DBus;-bindings
 (<abbrev>e.g.</abbrev> 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=org.kde.kid3 --print-reply=literal \
 /Kid3 org.kde.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 org.kde.kid3 /Kid3 setFrame 2 Artist \
 'One Hit Wonder'
 </programlisting>
 </listitem>
 </varlistentry>
 <varlistentry><term>Python</term>
 <listitem>
 <programlisting>
 import dbus
 kid3 = dbus.SessionBus().get_object(
   'org.kde.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(
   "org.kde.kid3")->get_object(
   "/Kid3", "org.kde.Kid3");
 $kid3->setFrame(2, "Artist", "One Hit Wonder");
 </programlisting>
 </listitem>
 </varlistentry>
 </variablelist>
 </sect1>
 
 <sect1 id="dbus-api">
 <title>&DBus; API</title>
 
 <para>
 The &DBus; API is specified
 in <filename>org.kde.Kid3.xml</filename>. The &kid3; interface has the
 following methods:
 </para>
 
 <sect2 id="dbus-openDirectory">
 <title>Open file or folder</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>openDirectory</function></funcdef>
   <paramdef>string <parameter>path</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>path</replaceable></term>
     <listitem><para>path to file or folder</para></listitem>
   </varlistentry>
 </variablelist>
 <para>Returns true if OK.</para>
 </sect2>
 
 <sect2 id="dbus-unloadAllTags">
 <title>Unload the tags of all files which are not modified or selected</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>unloadAllTags</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 </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-batchImport">
 <title>Start an automatic batch import</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>batchImport</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
   <paramdef>string <parameter>profileName</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag mask (bit 0 for tag 1, bit 1 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>profileName</replaceable></term>
     <listitem><para>name of batch import profile to use</para></listitem>
   </varlistentry>
 </variablelist>
 </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></paramdef>
   <paramdef>string <parameter>path</parameter></paramdef>
   <paramdef>int32 <parameter>fmtIdx</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>path</replaceable></term>
     <listitem><para>path of file</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>fmtIdx</replaceable></term>
     <listitem><para>index of format</para></listitem>
   </varlistentry>
 </variablelist>
 <para>Returns true if OK.</para>
 </sect2>
 
 <sect2 id="dbus-importFromTags">
 <title>Import tags from other tags</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>importFromTags</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
   <paramdef>string <parameter>source</parameter></paramdef>
   <paramdef>string <parameter>extraction</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>source</replaceable></term>
     <listitem><para>format to get source text from tags</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>extraction</replaceable></term>
     <listitem><para>regular expression with frame names and captures to
     extract from source text</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-importFromTagsToSelection">
 <title>Import tags from other tags on selected files</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>array <function>importFromTagsToSelection</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
   <paramdef>string <parameter>source</parameter></paramdef>
   <paramdef>string <parameter>extraction</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>source</replaceable></term>
     <listitem><para>format to get source text from tags</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>extraction</replaceable></term>
     <listitem><para>regular expression with frame names and captures to
     extract from source text</para></listitem>
   </varlistentry>
 </variablelist>
 <variablelist>
   <varlistentry>
     <term><replaceable>returnValues</replaceable></term>
     <listitem><para>extracted value for "%{__return}(.+)"</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-downloadAlbumArt">
 <title>Download album cover art</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>downloadAlbumArt</function></funcdef>
   <paramdef>string <parameter>url</parameter></paramdef>
   <paramdef>boolean <parameter>allFilesInDir</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>url</replaceable></term>
     <listitem><para>&URL; of picture file or album art
     resource</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>allFilesInDir</replaceable></term>
     <listitem><para>true to add the image to all files in the
     folder</para></listitem>
   </varlistentry>
 </variablelist>
 </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></paramdef>
   <paramdef>string <parameter>path</parameter></paramdef>
   <paramdef>int32 <parameter>fmtIdx</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>path</replaceable></term>
     <listitem><para>path of file</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>fmtIdx</replaceable></term>
     <listitem><para>index of format</para></listitem>
   </varlistentry>
 </variablelist>
 <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-getPlaylistItems">
 <title>Get items of a playlist</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>array <function>getPlaylistItems</function></funcdef>
   <paramdef>string <parameter>path</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>path</replaceable></term>
     <listitem><para>path to playlist file</para></listitem>
   </varlistentry>
 </variablelist>
 <para>Returns list of absolute paths to playlist items.</para>
 </sect2>
 
 <sect2 id="dbus-setPlaylistItems">
 <title>Set items of a playlist</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>setPlaylistItems</function></funcdef>
   <paramdef>string <parameter>path</parameter></paramdef>
   <paramdef>array <parameter>items</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>path</replaceable></term>
     <listitem><para>path to playlist file</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>items</replaceable></term>
     <listitem><para>list of absolute paths to playlist items</para></listitem>
   </varlistentry>
 </variablelist>
 <para>Returns true if OK, false if not all items were found and added or
 saving failed.</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>Set the first file as the current 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>Set the previous file as the current 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>Set the next file as the current 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-selectFirstFile">
 <title>Select the first file</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>selectFirstFile</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 <para>Returns true if there is a first file.</para>
 </sect2>
 
 <sect2 id="dbus-selectPreviousFile">
 <title>Select the previous file</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>selectPreviousFile</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 <para>Returns true if there is a previous file.</para>
 </sect2>
 
 <sect2 id="dbus-selectNextFile">
 <title>Select the next file</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>selectNextFile</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 <para>Returns true if there is a next file.</para>
 </sect2>
 
 <sect2 id="dbus-selectCurrentFile">
 <title>Select the current file</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>selectCurrentFile</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 <para>Returns true if there is a current file.</para>
 </sect2>
 
 <sect2 id="dbus-expandDirectory">
 <title>Expand or collapse the current file item if it is a folder</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>expandDirectory</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 <para>A file list item is a folder if getFileName() returns a name with
       '/' as the last character.</para>
 <para>Returns true if current file item is a folder.</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-applyTextEncoding">
 <title>Apply text encoding</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>applyTextEncoding</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 </sect2>
 
 <sect2 id="dbus-setDirNameFromTag">
 <title>Set the folder name from the tags</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>boolean <function>setDirNameFromTag</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
   <paramdef>string <parameter>format</parameter></paramdef>
   <paramdef>boolean <parameter>create</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag mask (bit 0 for tag 1, bit 1 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>format</replaceable></term>
     <listitem><para>folder name format</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>create</replaceable></term>
     <listitem><para>true to create, false to rename</para></listitem>
   </varlistentry>
 </variablelist>
 <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></paramdef>
   <paramdef>int32 <parameter>firstTrackNr</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag mask (bit 0 for tag 1, bit 1 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>firstTrackNr</replaceable></term>
     <listitem><para>number to use for first file</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-filter">
 <title>Filter the files</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>filter</function></funcdef>
   <paramdef>string <parameter>expression</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>expression</replaceable></term>
     <listitem><para>filter expression</para></listitem>
   </varlistentry>
 </variablelist>
 </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 folder</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>string <function>getDirectoryName</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 <para>Returns absolute path of folder.</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 folder.</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></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>name</replaceable></term>
     <listitem><para>file name</para></listitem>
   </varlistentry>
 </variablelist>
 <para>The file will be renamed when the folder 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></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>format</replaceable></term>
     <listitem><para>file name format</para></listitem>
   </varlistentry>
 </variablelist>
 </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></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-getFrame">
 <title>Get value of frame</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef>string <function>getFrame</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
   <paramdef>string <parameter>name</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>name</replaceable></term>
     <listitem><para>name of frame (<abbrev>e.g.</abbrev> "artist")</para></listitem>
   </varlistentry>
 </variablelist>
 <para>To get binary data like a picture, the name of a file to write can be
 added after the <parameter>name</parameter>, <abbrev>e.g.</abbrev> "Picture:/path/to/file".
 In the same way, synchronized lyrics can be exported, <abbrev>e.g.</abbrev> "SYLT:/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></paramdef>
   <paramdef>string <parameter>name</parameter></paramdef>
   <paramdef>string <parameter>value</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>name</replaceable></term>
     <listitem><para>name of frame (<abbrev>e.g.</abbrev> "artist")</para></listitem>
   </varlistentry>
   <varlistentry>
     <term><replaceable>value</replaceable></term>
     <listitem><para>value of frame</para></listitem>
   </varlistentry>
 </variablelist>
 <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>, <abbrev>e.g.</abbrev> "Picture:/path/to/file".
 "SYLT:/path/to/file" can be used to import synchronized lyrics.</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></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
 </variablelist>
 <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></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-setTagFromOtherTag">
 <title>Set tag from other tag</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>setTagFromOtherTag</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-copyTag">
 <title>Copy tag</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>copyTag</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-pasteTag">
 <title>Paste tag</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>pasteTag</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
 </variablelist>
 </sect2>
 
 <sect2 id="dbus-removeTag">
 <title>Remove tag</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>removeTag</function></funcdef>
   <paramdef>int32 <parameter>tagMask</parameter></paramdef>
 </funcprototype>
 </funcsynopsis>
 <variablelist>
   <varlistentry>
     <term><replaceable>tagMask</replaceable></term>
     <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
   </varlistentry>
 </variablelist>
 </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>
 
 <sect2 id="dbus-playAudio">
 <title>Plays the selected files</title>
 <funcsynopsis>
 <funcprototype>
   <funcdef><function>playAudio</function></funcdef>
   <void/>
 </funcprototype>
 </funcsynopsis>
 </sect2>
 
 </sect1>
 
 </appendix>
 
 <appendix id="qml-interface">
 <title>QML Interface</title>
 
 <sect1 id="qml-examples">
 <title>QML Examples</title>
 
 <para>
 QML scripts can be invoked via the context menu of the file list and can be
 set in the tab <link linkend="configure-user-actions-qml">User Actions</link>
 of the settings dialog. The scripts which are set there can be used as
 examples to program custom scripts. QML uses &javascript;, here is the
 obligatory "Hello World":
 </para>
 
 <programlisting>
 import Kid3 1.0
 
 Kid3Script {
   onRun: {
     console.log("Hello world, folder is", app.dirName)
     Qt.quit()
   }
 }
 </programlisting>
 
 <para>
 If this script is saved as <filename>/path/to/Example.qml</filename>, the user
 command can be defined as <command>@qml
 /path/to/Example.qml</command> with name <userinput>QML Test</userinput> and
 <guilabel>Output</guilabel> checked. It can then be started using the
 <guilabel>QML Test</guilabel> item in the file list context menu, and the
 output will be visible in the window.
 </para>
 
 <para>
 Unfortunately, starting the QML scripts using the <command>qml</command>
 (e.g. <command>qml -apptype widget -I /usr/lib/kid3/plugins/imports
 /path/to/Example.qml</command>) is broken in recent versions of Qt. But
 <command>kid3-cli</command> offers an alternative way to run a QML script from
 the command line using its
 <link linkend="cli-execute"><command>execute</command></link> command.
 <screen width="80">
 kid3-cli -c "execute @qml /path/to/Example.qml"
 </screen>
 </para>
 
 <para>
 To list the titles in the tags 2 of all files in the current folder, the
 following script could be used:
 </para>
 
 <programlisting>
 import Kid3 1.0
 
 Kid3Script {
   onRun: {
     app.firstFile()
     do {
       if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
         console.log(app.getFrame(tagv2, "title"))
       }
     } while (app.nextFile())
   }
 }
 </programlisting>
 
 <para>
 If the folder contains many files, such a script might block the user
 interface for some time. For longer operations, it should therefore have a
 break from time to time. The alternative implementation below has the work for
 a single file moved out into a function. This function invokes itself with a
 timeout of 1 ms at the end, given that more files have to be processed. This
 will ensure that the &GUI; remains responsive while the script is running.
 </para>
 
 <programlisting>
 import Kid3 1.0
 
 Kid3Script {
   onRun: {
     function doWork() {
       if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
         console.log(app.getFrame(tagv2, "title"))
       }
       if (!app.nextFile()) {
         Qt.quit()
       } else {
         setTimeout(doWork, 1)
       }
     }
 
     app.firstFile()
     doWork()
   }
 }
 </programlisting>
 
 <para>
 When using <command>app.firstFile()</command> with
 <command>app.nextFile()</command>, all files of the current folder will be
 processed. If only the selected files shall be affected, use
 <command>firstFile()</command> and <command>nextFile()</command> instead,
 these are convenience functions of the <classname>Kid3Script</classname>
 component. The following example is a script which copies only the disc number
 and copyright frames of the selected file.
 </para>
 
 <programlisting>
 import Kid3 1.1
 
 Kid3Script {
   onRun: {
     function doWork() {
       if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
         app.setFrame(tagv2, "*.selected", false)
         app.setFrame(tagv2, "discnumber.selected", true)
         app.setFrame(tagv2, "copyright.selected", true)
         app.copyTags(tagv2)
       }
       if (!nextFile()) {
         Qt.quit()
       } else {
         setTimeout(doWork, 1)
       }
     }
 
     firstFile()
     doWork()
   }
 }
 </programlisting>
 
 <para>
 More example scripts come with &kid3; and are already registered as user commands.
 
 <itemizedlist>
 <listitem><para>
 <guilabel>ReplayGain to SoundCheck</guilabel>
 (<filename>ReplayGain2SoundCheck.qml</filename>):
 Create iTunNORM SoundCheck information from replay gain frames.
 </para></listitem>
 <listitem><para>
 <guilabel>Resize Album Art</guilabel>
 (<filename>ResizeAlbumArt.qml</filename>):
 Resize embedded cover art images which are larger than 500x500 pixels.
 </para></listitem>
 <listitem><para>
 <guilabel>Extract Album Art</guilabel>
 (<filename>ExtractAlbumArt.qml</filename>):
 Extract all embedded cover art pictures avoiding duplicates.
 </para></listitem>
 <listitem><para>
 <guilabel>Embed Album Art</guilabel>
 (<filename>EmbedAlbumArt.qml</filename>):
 Embed cover art found in image files into audio files in the same folder.
 </para></listitem>
 <listitem><para>
 <guilabel>Embed Lyrics</guilabel>
 (<filename>EmbedLyrics.qml</filename>):
 Fetch unsynchronized lyrics from web service.
 </para></listitem>
 <listitem><para>
 <guilabel>Text Encoding ID3v1</guilabel>
 (<filename>ShowTextEncodingV1.qml</filename>):
 Helps to find the encoding of ID3v1 tags by showing the tags of the
 current file in all available character encodings.
 </para></listitem>
 <listitem><para>
 <guilabel>ID3v1 to ASCII</guilabel>
 (<filename>Tag1ToAscii.qml</filename>):
 Transliterate extended latin characters in the ID3v1 tag to ASCII.
 </para></listitem>
 <listitem><para>
 <guilabel>English Title Case</guilabel>
 (<filename>TitleCase.qml</filename>):
 Formats text in the tags to English title case.
 </para></listitem>
 <listitem><para>
 <guilabel>Rewrite Tags</guilabel>
 (<filename>RewriteTags.qml</filename>):
 Rewrite all tags in the selected files.
 </para></listitem>
 <listitem><para>
 <guilabel>Export CSV</guilabel>
 (<filename>ExportCsv.qml</filename>):
 Export recursively all tags of all files to a CSV file.
 </para></listitem>
 <listitem><para>
 <guilabel>Import CSV</guilabel>
 (<filename>ImportCsv.qml</filename>):
 Import recursively all tags of all files from a CSV file.
 </para></listitem>
 <listitem><para>
 <guilabel>Export JSON</guilabel>
 (<filename>ExportJson.qml</filename>):
 Export recursively all tags of all files to a JSON file.
 </para></listitem>
 <listitem><para>
 <guilabel>Import JSON</guilabel>
 (<filename>ImportJson.qml</filename>):
 Import recursively all tags of all files from a JSON file.
 </para></listitem>
 <listitem><para>
 <guilabel>Export Playlist Folder</guilabel>
 (<filename>ExportPlaylist.qml</filename>):
 Copy all files from a playlist into a folder and rename them according to
 their position.
 </para></listitem>
 <listitem><para>
 <guilabel>QML Console</guilabel>
 (<filename>QmlConsole.qml</filename>):
 Simple console to play with &kid3;'s QML API.
 </para></listitem>
 </itemizedlist>
 </para>
 
 </sect1>
 
 <sect1 id="qml-api">
 <title>QML API</title>
 
 <para>
 The API can be easily explored using the QML Console, which is available as an
 example script with a user interface.
 </para>
 
 <sect2 id="qml-kid3script">
 <title>Kid3Script</title>
 
 <para>
 <classname>Kid3Script</classname> is a regular QML component located inside
 the plugin folder. You could use another QML component just as well. Using
 <classname>Kid3Script</classname> makes it easy to start the script function
 using the <function>onRun</function> signal handler.
 Moreover it offers some functions:
 
 <programlisting>
 onRun: Signal handler which is invoked when the script is started
 tagv1, tagv2, tagv2v1: Constants for tag parameters
 script: Access to scripting functions
 configs: Access to configuration objects
 getArguments(): List of script arguments
 isStandalone(): true if the script was not started from within Kid3
 setTimeout(callback, delay): Starts callback after delay ms
 firstFile(): To first selected file
 nextFile(): To next selected file
 </programlisting>
 
 </para>
 </sect2>
 
 <sect2 id="qml-script">
 <title>Scripting Functions</title>
 
 <para>
 As &javascript; and therefore QML too has only a limited set of functions for
 scripting, the <function>script</function> object has some additional methods,
 for instance:
 </para>
 
 <programlisting>
 script.properties(obj): String with Qt properties
 script.writeFile(filePath, data): Write data to file, true if OK
 script.readFile(filePath): Read data from file
 script.removeFile(filePath): Delete file, true if OK
 script.fileExists(filePath): true if file exists
 script.fileIsWritable(filePath): true if file is writable
 script.getFilePermissions(filePath): Get file permission mode bits
 script.setFilePermissions(filePath, modeBits): Set file permission mode bits
 script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
   file " ")
 script.renameFile(oldName, newName): Rename file, true if OK
 script.copyFile(source, dest): Copy file, true if OK
 script.makeDir(path): Create folder, true if OK
 script.removeDir(path): Remove folder, true if OK
 script.tempPath(): Path to temporary folder
 script.musicPath(): Path to music folder
 script.listDir(path, [nameFilters], [classify]): List folder entries
 script.system(program, [args], [msecs]): Synchronously start a system command,
   [exit code, standard output, standard error] if not timeout
 script.systemAsync(program, [args], [callback]): Asynchronously start a system
 command, callback will be called with [exit code, standard output, standard
 error]
 script.getEnv(varName): Get value of environment variable
 script.setEnv(varName, value): Set value of environment variable
 script.getQtVersion(): Qt version string, <abbrev>e.g.</abbrev> "5.4.1"
 script.getDataMd5(data): Get hex string of the MD5 hash of data
 script.getDataSize(data): Get size of byte array
 script.dataToImage(data, [format]): Create an image from data bytes
 script.dataFromImage(img, [format]): Get data bytes from image
 script.loadImage(filePath): Load an image from a file
 script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
 script.imageProperties(img): Get properties of an image, map containing
   "width", "height", "depth" and "colorCount", empty if invalid image
 script.scaleImage(img, width, [height]): Scale an image, returns scaled image
 </programlisting>
 
 </sect2>
 
 <sect2 id="qml-app">
 <title>Application Context</title>
 
 <para>
 Using QML, a large part of the &kid3; functions are accessible. The API is
 similar to the one used for <link linkend="dbus-api">&DBus;</link>. For
 details, refer to the respective notes.
 </para>
 
 <programlisting>
 app.openDirectory(path): Open folder
 app.unloadAllTags(): Unload all tags
 app.saveDirectory(): Save folder
 app.revertFileModifications(): Revert
 app.importTags(tag, path, fmtIdx): Import file
 app.importFromTags(tag, source, extraction): Import from tags
 app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
 app.downloadImage(url, allFilesInDir): Download image
 app.exportTags(tag, path, fmtIdx): Export file
 app.writePlaylist(): Write playlist
 app.getPlaylistItems(path): Get items of a playlist
 app.setPlaylistItems(path, items): Set items of a playlist
 app.selectAllFiles(): Select all
 app.deselectAllFiles(): Deselect
 app.firstFile([select], [onlyTaggedFiles]): To first file
 app.nextFile([select], [onlyTaggedFiles]): To next file
 app.previousFile([select], [onlyTaggedFiles]): To previous file
 app.selectCurrentFile([select]): Select current file
 app.selectFile(path, [select]): Select a specific file
 app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
 app.requestExpandFileList(): Expand all
 app.applyFilenameFormat(): Apply filename format
 app.applyTagFormat(): Apply tag format
 app.applyTextEncoding(): Apply text encoding
 app.numberTracks(nr, total, tag, [options]): Number tracks
 app.applyFilter(expr): Filter
 app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
 app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
 app.getFilenameFromTags(tag): Filename from tags
 app.getTagsFromFilename(tag): Filename to tags
 app.getAllFrames(tag): Get object with all frames
 app.getFrame(tag, name): Get frame
 app.setFrame(tag, name, value): Set frame
 app.getPictureData(): Get data from picture frame
 app.setPictureData(data): Set data in picture frame
 app.copyToOtherTag(tag): Tags to other tags
 app.copyTags(tag): Copy
 app.pasteTags(tag): Paste
 app.removeTags(tag): Remove
 app.playAudio(): Play
 app.readConfig(): Read configuration
 app.applyChangedConfiguration(): Apply configuration
 app.dirName: Folder name
 app.selectionInfo.fileName: File name
 app.selectionInfo.filePath: Absolute file path
 app.selectionInfo.detailInfo: Format details
 app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
 app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
 app.selectionInfo.formatString(tag, format): Substitute codes in format string
 app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
 select a file
 app.selectDirName(caption, dir): Open file dialog to select a folder
 </programlisting>
 
 <para>
 For asynchronous operations, callbacks can be connected to signals.
 </para>
 
 <programlisting>
 function automaticImport(profile) {
   function onAutomaticImportFinished() {
     app.batchImporter.finished.disconnect(onAutomaticImportFinished)
   }
   app.batchImporter.finished.connect(onAutomaticImportFinished)
   app.batchImport(profile, tagv2)
 }
 
 function renameDirectory(format) {
   function onRenameActionsScheduled() {
     app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
     app.performRenameActions()
   }
   app.renameActionsScheduled.connect(onRenameActionsScheduled)
   app.renameDirectory(tagv2v1, format, false)
 }
 </programlisting>
 
 </sect2>
 
 <sect2 id="qml-configs">
 <title>Configuration Objects</title>
 
 <para>
 The different configuration sections are accessible via methods of
 <function>configs</function>. Their properties can be listed in the QML console.
 
 <screen width="80">
 script.properties(configs.networkConfig())
 </screen>
 
 Properties can be set:
 <screen width="80">
 configs.networkConfig().useProxy = false
 </screen>
 </para>
 
 <programlisting>
 configs.batchImportConfig()
 configs.exportConfig()
 configs.fileConfig()
 configs.filenameFormatConfig()
 configs.filterConfig()
 configs.findReplaceConfig()
 configs.guiConfig()
 configs.importConfig()
 configs.mainWindowConfig()
 configs.networkConfig()
 configs.numberTracksConfig()
 configs.playlistConfig()
 configs.renDirConfig()
 configs.tagConfig()
 configs.tagFormatConfig()
 configs.userActionsConfig()
 </programlisting>
 
 </sect2>
 
 </sect1>
 
 </appendix>
 
 &documentation.index;
 </book>
 <!--
 Local Variables:
 mode: nxml
 End:
 -->