Debian Codegraph @

doc/en/index.docbook

raw
1 <?xml version="1.0" ?>
2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
3 <!ENTITY kid3 '<application>Kid3</application>'>
4 <!ENTITY doublehyphen '--'>
5 <!ENTITY % addindex "IGNORE">
6 <!ENTITY % English "INCLUDE"><!-- change language only here -->
7 ]>
8 <book lang="&language;" id="kid3-handbook">
9
10 <bookinfo>
11 <title>The &kid3; Handbook</title>
12
13 <authorgroup>
14 <author>
15 <firstname>Urs</firstname>
16 <surname>Fleisch</surname>
17 <affiliation>
18 <address><email>[email protected]</email></address>
19 </affiliation>
20 <contrib>Software development</contrib>
21 </author>
22
23 <!-- TRANS:ROLES_OF_TRANSLATORS -->
24 </authorgroup>
25
26 <copyright>
27 <year>2026</year>
28 <holder>Urs Fleisch</holder>
29 </copyright>
30 <legalnotice id="fdl-notice">&FDLNotice;</legalnotice>
31
32 <date>2026-07-24</date>
33 <releaseinfo>3.10.1</releaseinfo>
34
35 <abstract>
36 <para>
37 &kid3; is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
38 an efficient way. Also tags in Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex,
39 TrueAudio, WavPack, WMA, WAV, AIFF files and tracker modules (MOD, S3M, IT, XM) are supported.
40 It is easy to set tags of multiple files to the same
41 values (<abbrev>e.g.</abbrev> album, artist, year and genre in all files of the same album) and
42 generate the tags from the file name or vice versa.
43 </para>
44 </abstract>
45
46 <keywordset>
47 <keyword>KDE</keyword>
48 <keyword>kdemultimedia</keyword>
49 <keyword>MP3</keyword>
50 <keyword>ID3</keyword>
51 <keyword>ID3v1</keyword>
52 <keyword>ID3v2</keyword>
53 <keyword>Ogg</keyword>
54 <keyword>Vorbis</keyword>
55 <keyword>FLAC</keyword>
56 <keyword>MPC</keyword>
57 <keyword>APE</keyword>
58 <keyword>Musepack</keyword>
59 <keyword>MP4</keyword>
60 <keyword>M4A</keyword>
61 <keyword>MP2</keyword>
62 <keyword>Speex</keyword>
63 <keyword>TrueAudio</keyword>
64 <keyword>WavPack</keyword>
65 <keyword>WMA</keyword>
66 <keyword>WAV</keyword>
67 <keyword>AIFF</keyword>
68 <keyword>MOD</keyword>
69 <keyword>S3M</keyword>
70 <keyword>IT</keyword>
71 <keyword>XM</keyword>
72 <keyword>Opus</keyword>
73 <keyword>DSF</keyword>
74 </keywordset>
75
76 </bookinfo>
77
78 <!--begin manpage include
79 <refmeta>
80 <refentrytitle>kid3</refentrytitle>
81 <manvolnum>1</manvolnum>
82 </refmeta>
83
84 <refnamediv>
85 <refname>kid3</refname>
86 <refname>kid3-qt</refname>
87 <refname>kid3-cli</refname>
88 <refpurpose>Kid3 ID3 Tagger</refpurpose>
89 </refnamediv>
90 end manpage include-->
91
92 <!--change manpage<refsynopsisdiv>--><preface id="synopsis"><title>Synopsis</title>
93 <cmdsynopsis>
94 <command>kid3</command>
95 <group>
96 <arg choice="plain"><option>&doublehyphen;help</option></arg>
97 <arg choice="plain"><option>&doublehyphen;author</option></arg>
98 <arg choice="plain"><option>&doublehyphen;version</option></arg>
99 <arg choice="plain"><option>&doublehyphen;license</option></arg>
100 <arg choice="plain"><option>&doublehyphen;desktopfile
101 <filename>FILE</filename></option></arg>
102 </group>
103 <arg rep="repeat"><replaceable>FILE</replaceable></arg>
104 </cmdsynopsis>
105 <cmdsynopsis>
106 <command>kid3-qt</command>
107 <arg><option>&doublehyphen;portable</option></arg>
108 <arg><option>Qt-options</option></arg>
109 <arg rep="repeat"><replaceable>FILE</replaceable></arg>
110 </cmdsynopsis>
111 <cmdsynopsis>
112 <command>kid3-cli</command>
113 <arg><option>&doublehyphen;portable</option></arg>
114 <arg><option>&doublehyphen;dbus</option></arg>
115 <group>
116 <arg choice="plain"><option>-h</option></arg>
117 <arg choice="plain"><option>&doublehyphen;help</option></arg>
118 </group>
119 <arg><option>-c COMMAND1</option></arg>
120 <arg rep="repeat"><option>-c COMMAND2</option></arg>
121 <arg rep="repeat"><replaceable>FILE</replaceable></arg>
122 </cmdsynopsis>
123 <!--change manpage</refsynopsisdiv>--></preface>
124
125 <preface id="options"><title>Options</title>
126
127 <variablelist>
128 <varlistentry>
129 <term><option>&doublehyphen;portable</option></term>
130 <listitem><para>Store configuration in file <filename>kid3.ini</filename>
131 inside application folder.</para></listitem>
132 </varlistentry>
133 <varlistentry>
134 <term><replaceable>FILE</replaceable></term>
135 <listitem><para>If <filename><replaceable>FILE</replaceable></filename> is the
136 path to a folder, it will be opened. If one or more file paths are given,
137 their common folder is opened and the files are selected.
138 </para></listitem>
139 </varlistentry>
140 </variablelist>
141
142 <sect1 id="options-kid3"><title>kid3</title>
143 <variablelist>
144 <varlistentry>
145 <term><option>&doublehyphen;help</option></term>
146 <listitem><para>Show help about options.</para></listitem>
147 </varlistentry>
148 <varlistentry>
149 <term><option>&doublehyphen;author</option></term>
150 <listitem><para>Show author information.</para></listitem>
151 </varlistentry>
152 <varlistentry>
153 <term><option>&doublehyphen;version</option></term>
154 <listitem><para>Show version information.</para></listitem>
155 </varlistentry>
156 <varlistentry>
157 <term><option>&doublehyphen;license</option></term>
158 <listitem><para>Show license information.</para></listitem>
159 </varlistentry>
160 <varlistentry>
161 <term><option>&doublehyphen;desktopfile
162 <filename>FILE</filename></option></term>
163 <listitem><para>The base file name of the desktop entry for this
164 application.</para></listitem>
165 </varlistentry>
166 </variablelist>
167 </sect1>
168
169 <sect1 id="options-kid3-qt"><title>kid3-qt</title>
170 <variablelist>
171 <varlistentry>
172 <term><option>Qt-options</option></term>
173 <listitem><para>See <citerefentry><refentrytitle>qt5options</refentrytitle>
174 <manvolnum>7</manvolnum></citerefentry>.</para></listitem>
175 </varlistentry>
176 </variablelist>
177 </sect1>
178
179 <sect1 id="options-kid3-cli"><title>kid3-cli</title>
180 <variablelist>
181
182 <varlistentry>
183 <term><option>&doublehyphen;dbus</option></term>
184 <listitem><para>Activate the &DBus; interface.</para></listitem>
185 </varlistentry>
186
187 <varlistentry>
188 <term><option>-c</option></term>
189 <listitem><para>Execute a command. Multiple <option>-c</option> options are
190 possible, they are executed in sequence. See the section about
191 <link linkend="kid3-cli">kid3-cli</link> for a description of the available
192 commands.</para></listitem>
193 </varlistentry>
194
195 <varlistentry>
196 <term><option>-h</option>|<option>&doublehyphen;help</option></term>
197 <listitem><para>Show help about options and commands.</para></listitem>
198 </varlistentry>
199
200 </variablelist>
201 </sect1>
202
203 </preface>
204
205 <chapter id="introduction">
206 <title>Introduction</title>
207
208 <para>
209 &kid3; is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
210 an efficient way. These tags can be edited by most MP3 players, but not in
211 a very comfortable and efficient way. Moreover the tags in Ogg/Vorbis, Opus, DSF, FLAC,
212 MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and
213 tracker modules (MOD, S3M, IT, XM) are supported too.
214 </para>
215 <para>
216 &kid3; does not grab nor encode
217 MP3 files, but it is targeted to edit the ID3 tags of all files of an album
218 in an efficient way, <abbrev>i.e.</abbrev> with as few mouse clicks and key strokes as
219 possible. Where most other programs can edit either ID3v1 or ID3v2 tags,
220 &kid3; has full control over both versions, can convert tags between the
221 two formats and has access to all ID3v2 tags. Tags of multiple files can be
222 set to the same value, <abbrev>e.g.</abbrev> the artist, album, year and genre of all files
223 of an album typically have the same values and can be set together. If the
224 information for the tags is contained in the file name, the tags can be
225 automatically set from the file name. It is also possible to set the file
226 name according to the tags found in the file in arbitrary formats.
227 </para>
228 <para>
229 The editing task is further supported by automatic replacement of characters
230 or substrings, for instance to remove illegal characters from
231 filenames. Automatic control of upper and lower case characters makes it easy
232 to use a consistent naming scheme in all tags.
233 </para>
234 <para>
235 The tag information for full albums can be taken from
236 <ulink url="http://gnudb.org">gnudb.org</ulink>, <ulink
237 url="http://musicbrainz.org">MusicBrainz</ulink>, <ulink
238 url="http://discogs.com">Discogs</ulink>, <ulink
239 url="http://www.amazon.com">Amazon</ulink> or other sources of
240 track lists. The import format is freely configurable by regular expressions.
241 </para>
242 <para>
243 Please report any problems or feature requests to the author.
244 </para>
245 </chapter>
246
247 <chapter id="using-kid3">
248 <title>Using &kid3;</title>
249
250 <sect1 id="kid3-features">
251 <title>&kid3; features</title>
252 <itemizedlist>
253 <listitem><para>Edit ID3v1.1 tags</para></listitem>
254 <listitem><para>Edit all ID3v2.3 and ID3v2.4 frames</para></listitem>
255 <listitem><para>Edit tags of multiple files</para></listitem>
256 <listitem><para>Convert between ID3v1 and ID3v2 tags</para></listitem>
257 <listitem><para>Edit MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex,
258 TrueAudio, WavPack, WMA, WAV and AIFF tags</para></listitem>
259 <listitem><para>Generate tags from filename</para></listitem>
260 <listitem><para>Generate tags from the contents of tag fields</para></listitem>
261 <listitem><para>Generate filename from tags</para></listitem>
262 <listitem><para>Generate and change folder names from tags</para></listitem>
263 <listitem><para>Generate playlist file</para></listitem>
264 <listitem><para>Automatic case conversion and string translation</para></listitem>
265 <listitem><para>Import from <ulink url="http://gnudb.org">gnudb.org</ulink>,
266 <ulink url="http://musicbrainz.org">MusicBrainz</ulink>,
267 <ulink url="http://discogs.com">Discogs</ulink>,
268 <ulink url="http://www.amazon.com">Amazon</ulink>
269 and other data sources</para></listitem>
270 <listitem><para>Export as CSV, &HTML;, playlist, Kover &XML; and other
271 formats. Exported CSV files can be imported again.</para></listitem>
272 </itemizedlist>
273 </sect1>
274
275 <sect1 id="example-usage">
276 <title>Example Usage</title>
277 <para>
278 This section describes a typical session with &kid3;.
279 Let's assume we have a folder containing MP3 files with the tracks from
280 the album "Let's Tag" from the band "One Hit Wonder". The folder is
281 named in the "artist - album" format, in our case <filename>One Hit Wonder - Let's
282 Tag</filename>. The folder contains the tracks in the "track title.mp3"
283 format, which I think is useful because the filenames are short
284 (important when using mobile MP3 players with small displays) and in the
285 correct order when sorted alphabetically (important when using hardware MP3
286 players which play the tracks in alphabetical order or in the order in
287 which they are burnt on &CD; and that order is alphabetical when using
288 <command>mkisofs</command>). Besides this, the artist and album information
289 is already in the folder name and does not have to be repeated in the filename.
290 But back to our example, the folder listing looks like this:
291 </para>
292 <para><filename>01 Intro.mp3</filename></para>
293 <para><filename>02 We Only Got This One.mp3</filename></para>
294 <para><filename>03 Outro.mp3</filename></para>
295 <para>
296 These files have no tags yet and we want to generate them using &kid3;. We use
297 <menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice>
298 menu item (or toolbar button) and select one of the files in this folder. All
299 files will be displayed in the file listbox. Lazy as we are, we want to use the
300 information in the folder and file names to generate tags. Therefore we select
301 all files, then click the <guilabel>To:</guilabel> <guibutton>Tag 1</guibutton>
302 button in the <guilabel>File</guilabel> section. This will set the title, artist,
303 album and track values in all files. To set the year and genre values of all
304 files, we keep all files selected and type in "2002" for the <guilabel>Date</guilabel>
305 and select "Pop" from the <guilabel>Genre</guilabel> combobox. To set only these
306 two values, their check boxes are automatically checked and all other check boxes
307 are left unchecked. Now we change the selection by only selecting the first file
308 and we see that all tags contain the correct values. The tags of the other files
309 can be verified too by selecting them one by one. When we are satisfied with the
310 tags, we use <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
311 menu item (or toolbar button). Selecting <menuchoice><guimenu>File</guimenu><guimenuitem>
312 Create Playlist</guimenuitem></menuchoice> menu item (or toolbar button) will
313 generate a file <filename>One Hit Wonder - Let's Tag.m3u</filename> in the folder.
314 </para>
315 </sect1>
316
317 </chapter>
318
319 <chapter id="commands">
320 <title>Command Reference</title>
321
322 <sect1 id="gui-elements">
323 <title>The &GUI; Elements</title>
324 <para>
325 The &kid3; &GUI; is separated in six sections: At the left are the file
326 and folder listboxes, the right side contains the <guilabel>File</guilabel>,
327 <guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel> and <guilabel>Tag 3
328 </guilabel> sections.
329 </para>
330
331 <para>
332 To navigate between the different sections using the keyboard, several keyboard
333 shortcuts are supported. In the tag sections, the shortcuts are active while
334 not editing text or when being in the first column.
335
336 <itemizedlist>
337 <listitem><para>
338 <keycombo>&Alt;<keycap>Left</keycap></keycombo>: Go to previous section
339 (<keycombo><keycap>Command</keycap><keycap>[</keycap></keycombo> on &macOS;)
340 </para></listitem>
341 <listitem><para>
342 <keycombo>&Alt;<keycap>Right</keycap></keycombo>: Go to next section
343 (<keycombo><keycap>Command</keycap><keycap>]</keycap></keycombo> on &macOS;)
344 </para></listitem>
345 <listitem><para>
346 <keycombo>&Ctrl;<keycap>Shift</keycap><keycap>V</keycap></keycombo>: From
347 other tag
348 </para></listitem>
349 <listitem><para>
350 <keycombo>&Ctrl;<keycap>C</keycap></keycombo>: Copy
351 </para></listitem>
352 <listitem><para>
353 <keycombo>&Ctrl;<keycap>V</keycap></keycombo>: Paste
354 </para></listitem>
355 <listitem><para>
356 <keycombo><keycap>Shift</keycap><keycap>Delete</keycap></keycombo>: Remove
357 </para></listitem>
358 <listitem><para>
359 <keycombo><keycap>F2</keycap></keycombo>: Edit
360 </para></listitem>
361 <listitem><para>
362 <keycombo><keycap>Insert</keycap></keycombo>: Add
363 </para></listitem>
364 <listitem><para>
365 <keycombo><keycap>Delete</keycap></keycombo>: Delete
366 </para></listitem>
367 </itemizedlist>
368 </para>
369
370 <sect2 id="file-list">
371 <title>File List</title>
372
373 <para>
374 The file list contains the names of all the files in the opened
375 folder which match the selected file name filter (typically
376 <filename class="extension">*.mp3 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a
377 *.m4b *.m4p *.mp4 *.mp2 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape</filename>).
378 A single or multiple files can be selected. To select no file, click into the
379 empty area after the listbox entries. The selection determines the files which
380 are affected by the operations which are available by using the buttons described
381 below.
382 </para>
383 <para>
384 Besides <guilabel>Name</guilabel>, also other columns
385 <guilabel>Size</guilabel>, <guilabel>Type</guilabel>, <guilabel>Date
386 Modified</guilabel> with file details can be displayed. Columns can be hidden
387 by unchecking their name in the context menu of the list header. The order of
388 the columns can be changed by drag and drop. The sort order can be toggled by
389 clicking on the column header.
390 </para>
391 <para>
392 The values of the standard tags can also be displayed and edited in columns of
393 the file list.
394 </para>
395 <para>
396 At the left of the names an icon can be displayed: a disc to show that the
397 file has been modified or information about which tags are present (V1, V2,
398 V1V2 or NO TAG, no icon is displayed if the file has not been read in yet).
399 </para>
400 <para>
401 Folders are displayed with a folder icon. If a folder is opened, its
402 files are displayed in a hierarchical tree. By selecting files from
403 subfolders, operations can be executed on files in different folders,
404 which is useful if the music collection is organized with a folder for each
405 artist containing folders for albums of this artist.
406 </para>
407 <para>
408 Clicking the <mousebutton>right</mousebutton> mouse button inside the file list opens a context menu with
409 the following commands:
410 <itemizedlist>
411 <listitem><para>
412 <guimenuitem>Expand all</guimenuitem>: Expands all folder trees (only the
413 current tree if the <keycap>Shift</keycap> key is pressed)
414 </para></listitem>
415 <listitem><para>
416 <guimenuitem>Collapse all</guimenuitem>: Collapses all folder trees
417 </para></listitem>
418 <listitem><para>
419 <guimenuitem>Rename</guimenuitem>: Changes the name of a file
420 </para></listitem>
421 <listitem><para>
422 <guimenuitem>Move to Trash</guimenuitem>: Moves a file to the trash
423 </para></listitem>
424 <listitem><para>
425 <guimenuitem>Play</guimenuitem>: Plays a file,
426 see <link linkend="play">Play</link>. If the selected file is a playlist, the
427 files of the playlist will be played.
428 </para></listitem>
429 <listitem><para>
430 <guimenuitem>Edit</guimenuitem>: Edit a playlist,
431 see <link linkend="edit-playlist">Edit Playlist</link>.
432 </para></listitem>
433 <listitem><para>The subsequent entries are user commands, which can be defined
434 in the <guilabel>User Actions</guilabel> tab of
435 <link linkend="configure-kid3">Configure &kid3;</link>. The playback on double
436 click can also be activated there.
437 </para><para>
438 When <guilabel>Select file on play</guilabel> is activated, the currently
439 played track is automatically selected in the file list.
440 </para></listitem>
441 </itemizedlist>
442 </para>
443 </sect2>
444
445 <sect2 id="edit-playlist">
446 <title>Edit Playlist</title>
447
448 <para>
449 A playlist can be created empty or containing the tracks of a folder, see <link
450 linkend="create-playlist">Create Playlist</link>. The playlist file created in
451 such a way can be edited by double click or using <guilabel>Edit</guilabel>
452 from the file list context menu. A dialog with the entries of the playlist is
453 shown. It is possible to open multiple playlists simultaneously.
454 </para>
455 <para>
456 New entries can be added by drag and drop from the file list, a file manager or
457 another playlist. If an entry is dragged from another playlist, it will be
458 moved or copied depending on the system. To invoke the other
459 operation, respectively, the <keycap>Shift</keycap>, &Ctrl; or &Alt; (to copy instead of move on
460 &macOS;) key has to be pressed. Reordering entries within the playlist is also
461 possible via drag and drop. Alternatively, entries can be moved using the keyboard
462 shortcuts <keycombo>&Ctrl;<keycap>Shift</keycap><keycap>Up</keycap></keycombo> and
463 <keycombo>&Ctrl;<keycap>Shift</keycap><keycap>Down</keycap></keycombo> (on &macOS; <keycap>Command</keycap> has
464 to be pressed instead of &Ctrl;). An entry can be removed using the <keycap>Delete</keycap> key.
465 </para>
466 <para>
467 Please note the following: To drag entries from the file list, they have to be
468 held at the left side (near the icons), the same gesture at the right side
469 will perform a multi selection, such an action is hereby still easily possible.
470 </para>
471 <para>
472 When a playlist has been modified, the changes can be stored using
473 <guibutton>Save</guibutton> or discarded using
474 <guibutton>Cancel</guibutton>. When the window is closed, a confirmation
475 prompt is shown if there are unsaved changes.
476 </para>
477 <para>
478 Tracks selected in a playlist will be automatically selected in the file list,
479 thereby making it possible to edit their tags.
480 </para>
481 <para>
482 To execute actions on a playlist, its file must be selected in the file
483 list. <guimenuitem>Edit</guimenuitem> from the context menu will lead to the
484 dialog described in this section, and <guimenuitem>Play</guimenuitem> will
485 start the media player with the tracks from the playlist. User actions can act
486 on playlists, for <link linkend="qml-examples">example</link> <guilabel>Export
487 Playlist Folder</guilabel>, which copies the files from a playlist into a
488 folder.
489 </para>
490 </sect2>
491
492 <sect2 id="directory-list">
493 <title>Folder List</title>
494
495 <para>
496 The folder list contains the names of the folders in the opened
497 folder, as well as the current (<filename class="directory">.</filename>) and
498 the parent (<filename class="directory">..</filename>) folder. It allows one
499 to quickly change the folder without using the <guimenuitem>Open</guimenuitem>
500 command or drag and drop.
501 </para>
502 <para>
503 Column visibility, order and sorting can be configured as described in the
504 section about the <link linkend="file-list">file list</link>.
505 </para>
506 </sect2>
507
508 <sect2 id="file">
509 <title>File</title>
510
511 <para>
512 Shows information about the encoding
513 (MP3, Ogg, Opus, DSF, FLAC, MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV, AIFF),
514 bit rate, sample rate, channels and the length of the file.
515 </para>
516 <para>
517 The <guilabel>Name</guilabel> line edit contains the name of the file
518 (if only a single file is selected). If this name is changed, the file will
519 be renamed when the Save command is used.
520 </para>
521 <para>
522 The <guilabel>Format</guilabel> combo box and line edit contains the format
523 to be used when the filename is generated from the first or the second tag.
524 The filename can contain arbitrary characters, even a folder part separated
525 by a slash from the file name, but that folder must already exist for the
526 renaming to succeed. The following special codes are used to insert tag values
527 into the filename:
528 </para>
529
530 <itemizedlist>
531 <listitem><para>%s %{title} Title (Song)</para></listitem>
532 <listitem><para>%a %{artist} Artist</para></listitem>
533 <listitem><para>%l %{album} Album</para></listitem>
534 <listitem><para>%c %{comment} Comment</para></listitem>
535 <listitem><para>%y %{year} Year</para></listitem>
536 <listitem><para>%t %{track} Track (<abbrev>e.g.</abbrev> 01)</para></listitem>
537 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
538 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
539 <listitem><para>%g %{genre} Genre</para></listitem>
540 <listitem><para> %{ignore} Ignored when generating tags from the file name</para></listitem>
541 </itemizedlist>
542
543 <para>
544 The format codes are not restricted to the examples given above. Any frame
545 name can be used, for instance unified frame names
546 like <userinput>%{albumartist}</userinput>,
547 <userinput>%{discnumber.1}</userinput>, <userinput>%{bpm}</userinput> or
548 format specific names like <userinput>%{popm}</userinput>.
549 </para>
550
551 <para>
552 It is possible to prepend and append strings to the replacement for a format
553 code by adding them in double quotes inside the curly braces of a format
554 code. These strings will only be put into the resulting string if the format
555 code yields a nonempty value. For example, if the file name shall
556 both contain the title and the subtitle, one could use
557 <userinput>%{title} [%{subtitle}]</userinput> in the format string. But this
558 would result in a string ending with <computeroutput> []</computeroutput> if
559 no subtitle frame exists for a file. In order to omit the brackets if no
560 subtitle is present, <userinput>%{title}%{" ["subtitle"]"}</userinput> shall
561 be used instead. This will omit the brackets, the leading space and the
562 subtitle if not subtitle exists.
563 </para>
564
565 <para>
566 The list of available formats can be edited in the dialog which appears when
567 clicking the <guibutton>Filename from tag</guibutton> button in the
568 <guilabel>File</guilabel> tab of the
569 <link linkend="configure-kid3">settings</link>.
570 </para>
571
572 <para>
573 A second <guilabel>Format</guilabel> combo box (with arrow down) is used
574 to generate the tags from the filename. If the format
575 of the filename does not match this pattern, a few other commonly used formats
576 are tried.
577 </para>
578
579 <para>
580 Some commonly used filename formats are already available in the combo box,
581 but it is also possible to type in some special format into the line edit.
582 </para>
583
584 <para>
585 The list of available formats can be edited in the dialog which appears when
586 clicking the <guibutton>Tag from filename</guibutton> button in the
587 <guilabel>File</guilabel> tab of the
588 <link linkend="configure-kid3">settings</link>.
589 </para>
590
591 <para>
592 Internally, a regular expression is built from the format codes. If advanced
593 regular expressions are required, the format to generate the tags from the
594 filenames can be given as a complete regular expression with captures which
595 are preceded by the format codes, <abbrev>e.g.</abbrev> to extract the track numbers without
596 removal of leading zeros, a format like "<userinput>/%{track}(\d+)
597 %{title}(.*)</userinput>" could be used.
598 </para>
599 <para>
600 <guilabel>From:</guilabel> <guibutton>Tag 1</guibutton>,
601 <guibutton>Tag 2</guibutton>: Sets the filename using the selected format
602 and the first tag or the second tag, respectively.
603 </para>
604 <para>
605 <guilabel>To:</guilabel> <guibutton>Tag 1</guibutton>,
606 <guibutton>Tag 2</guibutton>: The tags are set from the filename.
607 First, the format specified in <guilabel>Format</guilabel> is used. If the
608 existing filename does not match this format, the following formats
609 are tried:
610 </para>
611 <itemizedlist>
612 <listitem><para><filename>Artist - Album/Track Song</filename></para></listitem>
613 <listitem><para><filename>Album/Track - Artist - Song</filename></para></listitem>
614 <listitem><para><filename>/Artist - Album - Track - Song</filename></para></listitem>
615 <listitem><para><filename>Album/Artist - Track - Song</filename></para></listitem>
616 <listitem><para><filename>Album/Artist - Song</filename></para></listitem>
617 <listitem><para><filename>Artist/Album/Track Song</filename></para></listitem>
618 </itemizedlist>
619 <para>
620 If a single file is selected, the &GUI; controls are filled with the values
621 extracted from the filename. If multiple files are selected, the tags of the
622 files are directly set according to the filenames.
623 </para>
624 </sect2>
625
626 <sect2 id="tag1">
627 <title>Tag 1</title>
628
629 <para>
630 The line edit widgets for <guilabel>Title</guilabel>,
631 <guilabel>Artist</guilabel>,
632 <guilabel>Album</guilabel>, <guilabel>Comment</guilabel>,
633 <guilabel>Date</guilabel>, <guilabel>Track Number</guilabel> and
634 <guilabel>Genre</guilabel> are used to edit the corresponding value in the
635 first tag of the selected files. The value will be changed when the file
636 selection is altered or before operations like <guimenuitem>Save</guimenuitem>
637 and <guimenuitem>Quit</guimenuitem> and when the corresponding
638 check box at the left of the field name is checked. This is useful to
639 change only some values and leave the other values unchanged.
640 </para>
641 <para>
642 If a single file is selected, all check boxes are checked and the line edit
643 widgets contain the values found in the tags of this file. If a tag is not
644 found in the file, the corresponding empty value is displayed, which is an
645 empty string for the <guilabel>Title</guilabel>, <guilabel>Artist</guilabel>,
646 <guilabel>Album</guilabel> and <guilabel>Comment</guilabel> line edits, 0 for the
647 numerical <guilabel>Date</guilabel> and <guilabel>Track Number</guilabel> edits and
648 an empty selected value for the <guilabel>Genre</guilabel>
649 combo box. The values can be changed and if the corresponding check box is
650 checked, they will be set for the selected file after the selection is
651 changed. The file is then marked as modified by a disk symbol in the file
652 listbox but remains unchanged until the <guimenuitem>Save</guimenuitem>
653 command is used.
654 </para>
655 <para>
656 If multiple files are selected, only the values which are identical in all
657 selected files are displayed. In all other controls, the empty values as
658 described above are displayed. All check boxes are unchecked to avoid
659 unwanted changes. If a value has to be set for all selected files, it can
660 be edited and the check box has to be set. The values will be set for all
661 selected files when the selection is changed and can be saved using the
662 <guimenuitem>Save</guimenuitem> command.
663 </para>
664 <para>
665 The check boxes also control the operation of most commands affecting the
666 tags, such as copy, paste and transfer between tags 1 and 2. To make it
667 easier to use with multiple files where all check boxes are unchecked, these
668 commands behave in the same way when all check boxes are checked and when all
669 check boxes are unchecked.
670 </para>
671 <para>
672 <guibutton>From Tag 2</guibutton>: The tag 1 fields are set from the
673 corresponding values in tag 2.
674 If a single file is selected, the &GUI; controls are filled with the values
675 from tag 2. If multiple files are selected, the tags of the
676 files are directly set.
677 </para>
678 <para>
679 <guibutton>Copy</guibutton>: The copy buffer is filled with the Tag 1 values.
680 Only values with checked check box will be used in subsequent Paste commands.
681 </para>
682 <para>
683 <guibutton>Paste</guibutton>: Pastes the values from the copy buffer into the
684 &GUI; controls.
685 </para>
686 <para>
687 <guibutton>Remove</guibutton>: This will set all &GUI; controls to their empty
688 values which results in removing all values. The saved file will then contain
689 no tag 1.
690 </para>
691 </sect2>
692
693 <sect2 id="tag2">
694 <title>Tag 2</title>
695
696 <para>
697 The &GUI; controls function in the same way as described for the
698 <guilabel>Tag 1</guilabel> section, but the size of the strings is not limited.
699 </para>
700 <para>
701 For the tag 2 <guilabel>Genre</guilabel> you can also use your own names
702 besides the genres listed in the combo box, just type the name into the line
703 edit.
704 </para>
705 <para>
706 The tag 2 cannot only contain the same values
707 as the tag 1, the format is built in a flexible way from several frames
708 which are themselves composed of several fields. The tag 2 table shows
709 all the frames which are available in the selected file.
710 </para>
711 <para>
712 <guibutton>Edit</guibutton>: This will open a window which allows one to edit all fields
713 of the selected frame.
714 If multiple files are selected, the edited fields are applied to all selected files
715 which contain such a frame.
716 </para>
717 <para>
718 <guibutton>Add</guibutton>: A requester to select the frame type will appear
719 and a frame of the selected type can be edited and added to the file. This
720 works also to add a frame to multiple selected files.
721 </para>
722 <para>
723 <guibutton>Delete</guibutton>: Deletes the selected frame in the selected files.
724 </para>
725 <para>
726 <guilabel>Drag album artwork here</guilabel> is shown if the file does not
727 contain embedded cover art. A picture can be added using drag and drop from a
728 browser or file manager and will be displayed here. Picture frames can be
729 edited or added by double clicking on this control.
730 </para>
731
732 </sect2>
733
734 <sect2 id="tag3">
735 <title>Tag 3</title>
736
737 <para>
738 Some files can have more than two tags, and a third tag section is visible.
739 The following file types can have such a <guilabel>Tag 3</guilabel> section:
740 </para>
741 <itemizedlist>
742 <listitem><para>
743 MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0) tag and in the
744 third section an APE tag. Such APE tags are used for replay gain
745 information. In the <guilabel>Tag 3</guilabel> section, this information is
746 visible, and the APE tag can be removed with the <guibutton>Remove</guibutton>
747 button.
748 </para></listitem>
749 <listitem><para>
750 The RIFF INFO chunk of WAV files is available in the <guilabel>Tag 3
751 </guilabel> section because the <guilabel>Tag 1</guilabel> section is
752 dedicated to ID3v1.1 tags and handles their restrictions. The
753 <guilabel>Tag 2</guilabel> is still used for ID3v2.4.0 tags, which are also
754 supported for WAV files, but RIFF INFO chunks seem to be supported better.
755 </para></listitem>
756 <listitem><para>
757 FLAC files normally use a Vorbis comment for their meta data. However, there
758 are FLAC files which have ID3v1 and ID3v2 tags, which can be found in the
759 <guilabel>Tag 1</guilabel> and <guilabel>Tag 3</guilabel> sections.
760 ID3 tags in FLAC files are only supported by TagLib, therefore the
761 OggFlacMetadata plugin has to be disabled in the <guilabel>Plugins</guilabel>
762 tab of the <link linkend="configure-kid3">settings</link>.
763 </para></listitem>
764 </itemizedlist>
765 <para>
766 The &GUI; controls work in the same way as in the <guilabel>Tag 2</guilabel>
767 section.
768 </para>
769
770 </sect2>
771
772 <!--begin manpage ignore-->
773 <sect2 id="frame-list">
774 <title>Frame List</title>
775
776 <para>
777 &kid3; can edit most of the frames for all of the supported file types. Some
778 frames are accessed using unified names, so that they can be exchanged
779 between files with different formats. Frames which are not unified can be accessed as
780 format specific frames.
781 </para>
782
783 <table id="table-frame-list">
784 <title>Mapping of Unified Frame Types to Various Formats</title>
785 <tgroup cols="7">
786 <thead>
787 <row><entry>Unified</entry> <entry>ID3v2.3</entry> <entry>ID3v2.4</entry> <entry>MP4</entry> <entry>ASF</entry> <entry>Vorbis</entry> <entry>RIFF</entry> <entry>Matroska</entry></row>
788 </thead>
789 <tbody>
790 <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> <entry><literal>TITLE</literal></entry></row>
791 <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> <entry><literal>ARTIST</literal></entry></row>
792 <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> <entry><literal>TITLE/50</literal></entry></row>
793 <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> <entry><literal>COMMENT</literal></entry></row>
794 <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> <entry><literal>DATE_RECORDED</literal></entry></row>
795 <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> <entry><literal>PART_NUMBER</literal></entry></row>
796 <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> <entry><literal>GENRE</literal></entry></row>
797 <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> <entry><literal>ARTIST/50</literal></entry></row>
798 <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> <entry><literal>ARRANGER</literal></entry></row>
799 <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> <entry><literal>WRITTEN_BY</literal></entry></row>
800 <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> <entry><literal>BPM</literal></entry></row>
801 <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> <entry><literal>CATALOG_NUMBER</literal></entry></row>
802 <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> <entry><literal>COMPILATION</literal></entry></row>
803 <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> <entry><literal>COMPOSER</literal></entry></row>
804 <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> <entry><literal>CONDUCTOR</literal></entry></row>
805 <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> <entry><literal>COPYRIGHT</literal></entry></row>
806 <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> <entry><literal>DESCRIPTION</literal></entry></row>
807 <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> <entry><literal>PART_NUMBER/50</literal></entry></row>
808 <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> <entry><literal>ENCODER</literal></entry></row>
809 <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> <entry><literal>ENCODER_SETTINGS</literal></entry></row>
810 <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> <entry><literal>DATE_ENCODED</literal></entry></row>
811 <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> <entry><literal>GROUPING</literal></entry></row>
812 <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> <entry><literal>INITIAL_KEY</literal></entry></row>
813 <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> <entry><literal>ISRC</literal></entry></row>
814 <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> <entry><literal>LANGUAGE</literal></entry></row>
815 <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> <entry><literal>LYRICIST</literal></entry></row>
816 <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> <entry><literal>LYRICS</literal></entry></row>
817 <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> <entry><literal>ORIGINAL_MEDIA_TYPE</literal></entry></row>
818 <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> <entry><literal>MOOD</literal></entry></row>
819 <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> <entry><literal>ORIGINALALBUM</literal></entry></row>
820 <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> <entry><literal>ORIGINALARTIST</literal></entry></row>
821 <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> <entry><literal>ORIGINALDATE</literal></entry></row>
822 <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> <entry><literal>PERFORMER</literal></entry></row>
823 <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> <entry>Attachment</entry></row>
824 <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> <entry><literal>LABEL_CODE</literal></entry></row>
825 <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> <entry><literal>RATING</literal></entry></row>
826 <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> <entry><literal>RELEASECOUNTRY</literal></entry></row>
827 <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> <entry><literal>DATE_RELEASED/50</literal></entry></row>
828 <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> <entry><literal>REMIXED_BY</literal></entry></row>
829 <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> <entry><literal>TITLESORT/50</literal></entry></row>
830 <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> <entry><literal>ARTISTSORT/50</literal></entry></row>
831 <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> <entry><literal>ARTISTSORT</literal></entry></row>
832 <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> <entry><literal>COMPOSERSORT</literal></entry></row>
833 <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> <entry><literal>TITLESORT</literal></entry></row>
834 <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> <entry><literal>SUBTITLE</literal></entry></row>
835 <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> <entry><literal>WEBSITE</literal></entry></row>
836 <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> <entry><literal>WORK</literal></entry></row>
837 <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> <entry><literal>WWWAUDIOFILE</literal></entry></row>
838 <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> <entry><literal>WWWAUDIOSOURCE</literal></entry></row>
839 </tbody>
840 </tgroup>
841 </table>
842
843 <para>
844 Remarks concerning the mappings to unified frame names:
845 <itemizedlist>
846 <listitem><para>
847 The number of unified frame names is limited by the fact that a sensible
848 mapping shall be possible for all supported file formats. Most tags support
849 frames with arbitrary names; these will be used if no specific frame is
850 available (<abbrev>e.g.</abbrev> the names in uppercase in the column MP4). If no such
851 possibility exists, some frame types may not be supported for the format,
852 <abbrev>e.g.</abbrev> Author and Performer for ASF (WMA).
853 </para></listitem>
854 <listitem><para>
855 The mappings are not chosen arbitrarily, they are geared to the usage of the
856 frames in other applications and devices. Thus the ID3v2 frame "TPE2 -
857 Band/orchestra/accompaniment" does not suggest its usage as Album Artist, but
858 this is commonly used. The actual meaning for ID3v2 on the other hand is the
859 reason why this frame is used for the orchestra when importing (<abbrev>e.g.</abbrev> from
860 Discogs), although this may seem a bit strange for other tag formats.
861 </para></listitem>
862 <listitem><para>
863 The mappings are not always bijective. So ID3v2.3 uses an IPLS frame for both
864 Arranger and Performer. When reading back, both frames are displayed as
865 "Arranger".
866 </para></listitem>
867 <listitem><para>
868 The frames Arranger and Performer use a particular format for their contents:
869 "involvement 1|involvee 1|involvement 2|involvee 2|...", for
870 instance "Chorus Master|Ernst Dunshirn|Soprano Vocals|Anna Netrebko". This
871 will create IPLS (ID3v2.3) or TIPL/TMCL (ID3v2.4) frames with a string list in
872 the specified format (the "|" is used as a separator between the strings).
873 Values in this format are also set when importing data from servers which
874 offer this information.
875 </para></listitem>
876 <listitem><para>
877 For Matroska the target level is listed, e.g. /50 for Album, unless it is the
878 default of /30 for Track. If you want to create a Matroska simple tag with
879 binary content, append " - binary" when adding the frame. Note that such tags
880 are rarely used, cover art is stored as an attached file.
881 </para></listitem>
882 <listitem><para>
883 To explicitly use a specific frame name which conflicts with a unified frame
884 name, prepend an exclamation mark. For example, adding a frame of type
885 "<replaceable>Media</replaceable>" to a Vorbis comment will create a frame with
886 name "<literal>SOURCEMEDIA</literal>" because of the unified type mapping. In
887 order to add a frame with name "<literal>MEDIA</literal>" and not
888 "<literal>SOURCEMEDIA</literal>", use "<literal>!MEDIA</literal>" to force the
889 explicit name.
890 </para></listitem>
891 <listitem><para>
892 If you need a frame which is not in this list, you still have the possibility
893 to enter arbitrary names using the <guibutton>Add</guibutton> button. Often
894 used frame names can be added to the <guilabel>Custom Frames</guilabel> in the
895 <guilabel>Tags</guilabel> configuration, and will then be available in the
896 <guilabel>Quick Access Frames</guilabel>.
897 </para></listitem>
898 </itemizedlist>
899 </para>
900
901 </sect2>
902 <!--end manpage ignore-->
903
904 <sect2 id="synchronized-lyrics">
905 <title>Synchronized Lyrics and Event Timing Codes</title>
906
907 <para>
908 For information synchronized with the audio data, a specific editor is
909 available. These frames are supported for ID3v2.3.0 and ID3v2.4.0 tags. To add
910 such a frame, the specific frame name has to be selected in the list which
911 appears when the <guibutton>Add</guibutton> button is clicked -
912 <guilabel>Synchronized Lyrics</guilabel> or <guilabel>Event Timing
913 Codes</guilabel>, respectively. The editor is the same for both types, for the
914 event timing codes, only a predefined set of events is available whereas for
915 the synchronized lyrics, text has to be entered. In the following, editing
916 synchronized lyrics is explained.
917 </para>
918 <para>
919 A file having an ID3v2 tag is selected, the lyrics editor is entered using
920 <guibutton>Add</guibutton> and selecting <guilabel>Synchronized
921 Lyrics</guilabel>. For an existing Synchronized Lyrics frame, it is selected and
922 <guibutton>Edit</guibutton> is clicked. The player is automatically opened
923 with the current file so that the file can be played and paused to synchronize
924 lyrics.
925 </para>
926 <para>
927 The settings at the top of the SYLT editor normally do not have to be
928 changed. If the lyrics contains characters which are not present in the Latin 1
929 character set, changing the text encoding to UTF16 (or UTF8 for ID3v2.4.0) is
930 advisable. For English lyrics and maximum compatibility, ISO-8859-1 should be
931 used.
932 </para>
933 <para>
934 The <guilabel>Lyrics</guilabel> section has five buttons at the
935 top. <guibutton>Add</guibutton> will add a new time event in the table. The
936 time is taken from the position of the player, thus adding an entry while
937 playing the track will add a line for the currently played position. The
938 events in the table have to be chronologically ordered, therefore the row will
939 be inserted accordingly. Entries with an invalid time are treated specially:
940 If the currently selected row has an invalid time, its time stamp will be
941 replaced by the current time instead of adding a new row. If the current time
942 is not invalid, the first row with an invalid time will be used if
943 present. This behavior should facilitate adding time stamps if the lyrics text
944 is already in the table but the time stamps are missing (which is the case
945 when importing unsynchronized lyrics). Note that the invalid time is
946 represented as 00:00.00, <abbrev>i.e.</abbrev> the same as the time at the absolute beginning
947 of the track, which is not invalid. To make a time invalid, press the
948 <keycap>Delete</keycap> key, or use <guimenu>Clear</guimenu> from the context menu. New rows
949 inserted using <guimenu>Insert row</guimenu> from the context menu or created
950 when importing unsynchronized lyrics with <guibutton>From Clipboard</guibutton>
951 or <guibutton>Import</guibutton> also contain invalid time stamps. Rows in the
952 table can be deleted by clicking the <guibutton>Delete</guibutton> button or
953 using <guimenu>Delete rows</guimenu> from the context menu.
954 </para>
955 <para>
956 Synchronized lyrics can be imported from a file using
957 <guibutton>Import</guibutton>. The expected format is simple or enhanced
958 LRC. If the selected file does not contain a square bracket in the first line,
959 it is supposed to be a simple text file with unsynchronized lyrics. The lines
960 from such a file are then imported having invalid time stamps. The time
961 information can be added using the <guibutton>Add</guibutton> button or
962 by manual entry. It is also possible to import lyrics via copy-paste using
963 <guilabel>From Clipboard</guilabel>. Synchronized lyrics can be written to LRC
964 files using <guibutton>Export</guibutton>. Note that only entries with valid
965 time stamps will be exported and that the entries will be sorted by
966 time. Entries with invalid time won't be stored in the SYLT frame either, so
967 make sure to include all timing information before leaving the dialog.
968 </para>
969 <para>
970 The <ulink url="http://id3.org/id3v2.4.0-frames">ID3 specification</ulink>
971 suggests a time stamp for each syllable. However most players only support the
972 granularity of a line or sentence. To support both use cases, &kid3; follows
973 the same conventions as <ulink
974 url="http://www.compuphase.com/software_sylteditor.htm">SYLT
975 Editor</ulink>. Text which is entered into the table is assumed to start a new
976 line unless it starts with a space or a hyphen. Exceptions to this rule are
977 possible by starting a line with an underscore ('_') to force continuation or
978 a hash mark ('#') to force a new line. These escape characters are not stored
979 inside the SYLT frame. Inside the SYLT frame, new lines start with a line feed
980 character (hex 0A) whereas continuations do not. When reading SYLT frames,
981 &kid3; checks if the first entry starts with a line feed. If this is not the
982 case, it is assumed that all entries are new lines and that no syllable
983 continuations are used.
984 </para>
985 <para>
986 While the track is played, the row associated with the current playing
987 position is highlighted, so that the correctness of the synchronization
988 information can be verified. If an offset has to be added to one or more time
989 stamps, this can be accomplished with the <guimenu>Add offset</guimenu>
990 context menu. Negative values can be used to reduce the time. Using
991 <guimenu>Seek to position</guimenu> in the context menu, it is possible to set
992 the playing position to the time of the selected row.
993 </para>
994 <para>
995 <emphasis>Recommended procedure to add new synchronized lyrics</emphasis>
996 <itemizedlist>
997 <listitem><para>Get the unsynchronized lyrics, <abbrev>e.g.</abbrev> using
998 <menuchoice><guimenu>Lyrics</guimenu><guimenuitem>Embed
999 Lyrics</guimenuitem></menuchoice> from the file list context
1000 menu.</para></listitem>
1001 <listitem><para>Copy the unsynchronized lyrics to the clipboard, just go to
1002 the <guilabel>Lyrics</guilabel> row in the frame table and press
1003 <keycombo>&Ctrl;<keycap>C</keycap></keycombo>.</para></listitem>
1004 <listitem><para>Add a synchronized lyrics frame
1005 (<guibutton>Add...</guibutton>, <guilabel>Synchronized
1006 Lyrics</guilabel>, <guibutton>OK</guibutton>), click
1007 <guibutton>From Clipboard</guibutton>.</para></listitem>
1008 <listitem><para>Now all lines from the unsynchronized lyrics are in the table,
1009 all time stamps are invalid (0:0:0.00). You can delete empty entries
1010 beforehand.</para></listitem>
1011 <listitem><para>Start playing the song by clicking the play button
1012 <guibutton>&#9658;</guibutton> in the play toolbar at the bottom of the main
1013 window.</para></listitem>
1014 <listitem><para>When the next lyrics line with invalid timestamp comes, click
1015 <guibutton>Add</guibutton> or press
1016 <keycombo>&Alt;<keycap>A</keycap></keycombo>, the timestamp
1017 will be updated.</para></listitem>
1018 <listitem><para>Continue like this until all timestamps are set. If you missed
1019 something, stop playback and clear the timestamps using the <keycap>Delete</keycap> key or by
1020 selecting them and using <guimenuitem>Clear</guimenuitem> from the context
1021 menu. To restart playback from a given timestamp, use <guimenuitem>Seek to
1022 position</guimenuitem> from the context menu.
1023 </para></listitem>
1024 </itemizedlist>
1025 </para>
1026 </sect2>
1027
1028 <sect2 id="mp4-chapters">
1029 <title>Chapters in MP4 Files</title>
1030
1031 <para>
1032 MP4 audiobooks typically have a <filename class="extension">.m4b</filename>
1033 extension and are rather large because they contain all chapters in a single
1034 file. To navigate in such files, they can contain chapter marks, which can be
1035 edited in &kid3; in a pseudo "Chapters" frame using the same editor which is
1036 used for <link linkend="synchronized-lyrics">synchronized lyrics</link>.
1037 There are two types of chapters in MP4 files: "Nero" and "QuickTime (QT)".
1038 </para>
1039 <para>
1040 The chapter information in MP3 audiobooks is stored in multiple "Chapter"
1041 (CHAP) frames which are referenced by a "Table of Contents" (CTOC) frame,
1042 and these frames have embedded subframes. To edit this information in a single
1043 place, a pseudo "Chapters" frame can also be used for ID3v2 tags. Its contents
1044 are used to create the real chapter, table of contents and embedded frames:
1045 The <guilabel>Description</guilabel> is used as the table of contents title,
1046 the <guilabel>Text</guilabel> column contains the chapter titles, and the
1047 corresponding <guilabel>Time</guilabel> value will be the chapter start time
1048 and the end time of the preceding chapter. The end time of last chapter is
1049 determined by the <guilabel>Time</guilabel> of the last row if its
1050 <guilabel>Text</guilabel> is empty.
1051 </para>
1052 </sect2>
1053
1054 </sect1>
1055
1056 <sect1 id="file-menu">
1057 <title>The File Menu</title>
1058 <para>
1059 <variablelist>
1060
1061 <varlistentry>
1062 <term><menuchoice>
1063 <shortcut>
1064 <keycombo>&Ctrl;<keycap>O</keycap></keycombo>
1065 </shortcut>
1066 <guimenu>File</guimenu>
1067 <guimenuitem>Open...</guimenuitem>
1068 </menuchoice></term>
1069 <listitem><para><action>Opens a folder.</action> All files matching the selected
1070 file name filter will be displayed in the file listbox
1071 and the chosen file is selected.</para></listitem>
1072 </varlistentry>
1073
1074 <varlistentry>
1075 <term><menuchoice>
1076 <guimenu>File</guimenu>
1077 <guimenuitem>Open Recent</guimenuitem>
1078 </menuchoice></term>
1079 <listitem><para><action>Opens a recently opened folder.</action></para></listitem>
1080 </varlistentry>
1081
1082 <varlistentry>
1083 <term><menuchoice>
1084 <shortcut>
1085 <keycombo>&Ctrl;<keycap>D</keycap></keycombo>
1086 </shortcut>
1087 <guimenu>File</guimenu>
1088 <guimenuitem>Open Folder...</guimenuitem>
1089 </menuchoice></term>
1090 <listitem><para><action>Opens a folder.</action> All files matching the selected
1091 file name filter will be displayed in the file listbox.</para></listitem>
1092 </varlistentry>
1093
1094 <varlistentry>
1095 <term><menuchoice>
1096 <shortcut>
1097 <keycap>F5</keycap>
1098 </shortcut>
1099 <guimenu>File</guimenu>
1100 <guimenuitem>Reload</guimenuitem>
1101 </menuchoice></term>
1102 <listitem><para><action>Reload folder.</action> Modified files have to be
1103 saved before. Expanded subfolders will be collapsed.</para></listitem>
1104 </varlistentry>
1105
1106 <varlistentry>
1107 <term><menuchoice>
1108 <shortcut>
1109 <keycombo>&Ctrl;<keycap>S</keycap></keycombo>
1110 </shortcut>
1111 <guimenu>File</guimenu>
1112 <guimenuitem>Save</guimenuitem>
1113 </menuchoice></term>
1114 <listitem><para><action>Saves all changed files in the folder.</action> The
1115 changed files are marked with a disk symbol in the file listbox. If any file
1116 names have been changed, those files will be renamed.</para></listitem>
1117 </varlistentry>
1118
1119 <varlistentry>
1120 <term><menuchoice>
1121 <guimenu>File</guimenu>
1122 <guimenuitem>Revert</guimenuitem>
1123 </menuchoice></term>
1124 <listitem><para><action>Reverts the changes of one or multiple files.</action> If no
1125 files are selected in the file listbox, the changes of all files will be
1126 reverted, else only the changes of the selected files are reverted.
1127 </para></listitem>
1128 </varlistentry>
1129
1130 <varlistentry id="import">
1131 <term><menuchoice>
1132 <guimenu>File</guimenu>
1133 <guimenuitem>Import...</guimenuitem>
1134 </menuchoice></term>
1135 <listitem><para>The <action>Import dialog</action> can be used to import data
1136 directly from a freedb.org server, from a MusicBrainz server, from
1137 Discogs, Amazon or other sources of album track lists in textual format.
1138 </para>
1139 <para id="import-freedb">
1140 Import from a freedb.org server is possible using a dialog which appears when
1141 <guibutton>From Server:</guibutton>
1142 <guibutton>gnudb.org</guibutton>
1143 is selected. The artist and album name
1144 to search for can be entered in the two topmost fields,
1145 the albums which match the
1146 query will be displayed when <guibutton>Find</guibutton> is clicked and the
1147 results from <ulink url="http://www.gnudb.org">www.gnudb.org</ulink> are
1148 received. Importing the track data for an album is
1149 done by double-clicking the album in the list. The freedb.org server to import
1150 from can be selected as well as the CGI path. The
1151 imported data is displayed in the preview table of the import dialog.
1152 When satisfied with the displayed tracks, they
1153 can be imported by terminating the import dialog with
1154 <guibutton>OK</guibutton>.
1155 </para>
1156 <para>
1157 If you already have a search result open in the web browser, you can enter the
1158 URL into the first search field. The result will then appear in the album list
1159 and can be directly imported into &kid3;.
1160 </para>
1161 <para>
1162 An e-mail address registered at <ulink url="https://gnudb.org/info.php">
1163 gnudb.org</ulink> can be entered into the <guilabel>Token</guilabel> field.
1164 </para>
1165 <para id="import-discogs">
1166 A search on the Discogs server can be performed using
1167 <guibutton>Discogs</guibutton>. As in the <guibutton>gnudb.org</guibutton> dialog,
1168 you can enter artist and album and then choose from a list of releases.
1169 A <guilabel>Token</guilabel> can be entered to use the RESTful Discogs API
1170 instead of their web interface, which is often changed, thereby breaking the
1171 import parser. You have to register for an account on
1172 <ulink url="https://www.discogs.com/">Discogs</ulink> and then generate a token
1173 on their web site (Settings/Developers, Generate new token). Don't forget to
1174 <guibutton>Save Settings</guibutton> after entering the token in order to use
1175 it in subsequent requests too.
1176 If <guilabel>Standard Tags</guilabel> is marked, the standard information is
1177 imported, <abbrev>e.g.</abbrev> artist, album, and title.
1178 If <guilabel>Additional Tags</guilabel> is marked, more information is
1179 imported if available, <abbrev>e.g.</abbrev> performers, arrangers, or the publisher.
1180 If <guilabel>Cover Art</guilabel> is marked, cover art will be downloaded if
1181 available.
1182 </para>
1183 <para id="import-amazon">
1184 A search on Amazon can be performed using
1185 <guibutton>Amazon</guibutton>. As in the <guibutton>gnudb.org</guibutton> dialog,
1186 you can enter artist and album and then choose from a list of releases.
1187 If <guilabel>Additional Tags</guilabel> is marked, more information is
1188 imported if available, <abbrev>e.g.</abbrev> performers, arrangers, or the publisher.
1189 If <guilabel>Cover Art</guilabel> is marked, cover art will be downloaded if
1190 available.
1191 </para>
1192 <para id="import-musicbrainzrelease">
1193 You can search in the same way in the release database of MusicBrainz
1194 using <guibutton>From MusicBrainz Release</guibutton>.
1195 The workflow is the same as described for <guibutton>From
1196 gnudb.org</guibutton>.
1197 </para>
1198 <para id="import-musicbrainz">
1199 Import from a MusicBrainz server is possible using the dialog which appears when
1200 <guibutton>From MusicBrainz Fingerprint</guibutton> is selected. The Server can be
1201 selected as in the freedb import dialog. Below is a table displaying the
1202 imported track data. The right column shows the state of the MusicBrainz
1203 query, which starts with "Pending" when the dialog is opened. Then the
1204 fingerprint is looked up and if it does not yield a result, another lookup
1205 using the tags in the file is tried. Thus it can be helpful for a successful
1206 MusicBrainz query to store known information (<abbrev>e.g.</abbrev> artist and album) in the
1207 tags before the import. If a result was found, the search ends in the state
1208 "Recognized", otherwise nothing was found or multiple ambiguous results and one
1209 of them has to be selected by the user.
1210 <guibutton>OK</guibutton> and <guibutton>Apply</guibutton> use the imported
1211 data, <guibutton>Cancel</guibutton> closes the dialog. The closing can take a
1212 while since the whole MusicBrainz machinery has to be shut down.
1213 </para>
1214
1215 <para id="import-text">
1216 For the import of textual data, <guibutton>From File/Clipboard</guibutton>
1217 opens a subdialog, where several preconfigured import formats are
1218 available. The first two, "CSV unquoted" and "CSV quoted" can be used to
1219 import data which was exported by the Export dialog. The CSV data can be
1220 edited with a spreadsheet, and shall be written using tabs as
1221 delimiters. Import should then be possible using "CSV quoted", which is more
1222 flexible than "CSV unquoted". However, its fields cannot contain any double
1223 quotes. If you only export from &kid3; and import later, "CSV unquoted" can be
1224 used as a simple format for this purpose. Note that there are also "Export
1225 CSV" and "Import CSV" commands in the context menu of the file list, which use
1226 scripts to export and import CSV data in a more complete, powerful and
1227 flexible way.
1228 </para>
1229
1230 <para>
1231 The next format, "freedb &HTML;
1232 text", can be used to copy information from an &HTML; page of
1233 <ulink url="http://freedb.org">freedb.org</ulink>. Search an album in freedb
1234 and if the desired information is displayed in the web browser, copy the
1235 contents to the clipboard. Then click the <guibutton>From
1236 Clipboard</guibutton> button and the imported tracks will be displayed in the
1237 preview table at the top of the dialog. If you are satisfied with the imported
1238 data, terminate the dialog with <guibutton>OK</guibutton>, which will insert
1239 the data into the tags of the current folder. The destination
1240 (<guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel> or
1241 <guilabel>Tag 1 and Tag 2</guilabel>) can be selected
1242 with a combo box. The files in the current folder should be in the correct
1243 track order to get their tags assigned. This is the case if they are numbered.
1244 </para>
1245 <para>
1246 The next preconfigured import format, "freedb &HTML; source", can be used, if
1247 the data is available as an &HTML; document. Import is possible using the
1248 <guibutton>From File</guibutton> button, which opens a file selector, or
1249 copying its contents from an editor and then importing from clipboard. This
1250 format can be useful for offline import, although the &HTML; document could also
1251 be opened in a browser and then be imported in the first format via the clipboard.
1252 </para>
1253 <para>
1254 More preconfigured formats, <abbrev>e.g.</abbrev> "Track Title Time", are available. An empty
1255 custom format can be created with <guibutton>Add</guibutton> to be set by the
1256 user. Two lines below the format name can be
1257 set with a regular expression to capture the fields from the import text. The
1258 first regular expression will be parsed once per document to gather per-album
1259 data such as artist, album, year and genre. The second line is tried to match
1260 from the start of the document to the end to get track data, usually number
1261 and title. The regular expressions include all the features offered by &Qt;,
1262 which is most of the what Perl offers. Bracketing constructs "(..)" create
1263 capture buffers for the fields to import and are preceded by &kid3; specific
1264 codes to specify which field to capture. The codes are the same as used for
1265 the filename format, besides the codes listed below, any frame name is
1266 possible:
1267 </para>
1268
1269 <para id="format-codes">
1270 <itemizedlist>
1271 <listitem><para>%s %{title} Title (Song)</para></listitem>
1272 <listitem><para>%a %{artist} Artist</para></listitem>
1273 <listitem><para>%l %{album} Album</para></listitem>
1274 <listitem><para>%c %{comment} Comment</para></listitem>
1275 <listitem><para>%y %{year} Year</para></listitem>
1276 <listitem><para>%t %{track} Track</para></listitem>
1277 <listitem><para>%g %{genre} Genre</para></listitem>
1278 <listitem><para>%d %{duration} Duration</para></listitem>
1279 </itemizedlist>
1280 </para>
1281
1282 <para>
1283 For example, a track regular expression (second line) to import from an
1284 <filename class="extension">.m3u</filename> playlist could be
1285 "<literal>%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]</literal>". All formats
1286 can be changed by editing the regular expressions and the name and then clicking
1287 <guibutton>Save Settings</guibutton>. They will be stored in the <filename>kid3rc</filename>
1288 file in the configuration folder. This file can be directly edited to have more
1289 import formats or it can be deleted to revert to the default formats. Formats
1290 can be deleted using <guibutton>Remove</guibutton>.
1291 </para>
1292 <para>
1293 <guilabel>Accuracy</guilabel> shows an estimation of how good the
1294 imported information matches the given tracks. It uses track durations or
1295 file names to calculate the level of similarity in percent.
1296 <guilabel>Cover Art</guilabel> shows the &URL; of the album cover image
1297 which will be downloaded.
1298 </para>
1299 <para>
1300 To check whether the imported tracks match the current set of files, the
1301 duration of the imported tracks can be compared with the duration of the
1302 files. This option can be enabled with the check box <guibutton>Check maximum
1303 allowable time difference (sec):</guibutton> and the maximum tolerated difference in
1304 time can be set in seconds. If a mismatch in a length is detected, the length
1305 is displayed with a red background in the preview table.
1306 </para>
1307 <para>
1308 If the files are ordered differently than the imported tracks, their assigned
1309 tracks have to be changed. This task can be facilitated using the <guilabel>Match
1310 with</guilabel> option with the buttons <guibutton>Length</guibutton>,
1311 <guibutton>Track</guibutton>, and <guibutton>Title</guibutton>, which will reorder
1312 the tracks according to the corresponding field. To correct the assignments
1313 manually, a track can be dragged with the <mousebutton>left</mousebutton> mouse button and the &Ctrl; key hold down,
1314 and then dropped at the new location.
1315 </para>
1316 <para>
1317 If there are more imported tracks than files, for example if the current folder
1318 contains only the second disc of a two disc album but the tracks of both discs
1319 are imported, it is possible to delete the tracks of the first disc by selecting
1320 them by clicking on the row label of the first track, then clicking on the row
1321 label of the last track of the first disc while holding down the
1322 <keycap>Shift</keycap> key, and finally removing the tracks by pressing the
1323 <keycap>Delete</keycap> key.
1324 </para>
1325 <para>
1326 When the import dialog is opened, it contains the actual contents of the
1327 tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using the
1328 <guilabel>Destination</guilabel> combo box. The button on the right of this
1329 combo box can be used to revert the table to the current contents of the
1330 tags. The check boxes in the first table column can be used to select the
1331 tracks which are imported. This can be useful if a folder contains the tracks
1332 of both &CD;s of a double &CD; and only the tracks of the second &CD; have to be
1333 imported.
1334 </para>
1335 <para>
1336 To identify the tracks which are imported, it is possible to display the file
1337 names or the full paths to the files using the context menu of the table
1338 header. The values in the import table can be edited. The revert-button to
1339 the right of the <guilabel>Destination</guilabel> combo box can be used to
1340 restore the contents of the tags, which can also be useful after changing the
1341 <guilabel>Destination</guilabel>.
1342 </para>
1343 <para>
1344 Almost all dialogs feature a <guibutton>Save Settings</guibutton> button,
1345 which can be used to store the dialog specific settings and the window size
1346 persistently.
1347 </para>
1348
1349 <para id="import-tags">
1350 <guibutton>From Tags</guibutton> leads to a subdialog to set tag frames from
1351 the contents of other tag frames. This can be used to simply copy information
1352 between tags or extract a part from one frame and insert it in another.
1353 </para>
1354 <para>
1355 As in the <link linkend="import-text">import from file/clipboard</link> dialog,
1356 there are freely configurable formats to perform different operations. Already
1357 preconfigured are formats to copy the Album value to Album Artist, Composer or
1358 Conductor, and to extract the Track Number from Title fields which contain a
1359 number. There is also a format to extract a Subtitle from a Title field.
1360 </para>
1361 <para>
1362 The following example explains how to add a custom format, which sets the
1363 information from the Subtitle field also in the Comment field. Create a new
1364 format using <guibutton>Add</guibutton> button and set a new name, <abbrev>e.g.</abbrev>
1365 "Subtitle to Comment". Then enter "<userinput>%{subtitle}</userinput>" in
1366 <guilabel>Source</guilabel> and "<userinput>%{comment}(.*)</userinput>" for
1367 <guilabel>Extraction</guilabel> and click <guibutton>Save
1368 Settings</guibutton>.
1369 </para>
1370 <para>
1371 The expression in <guilabel>Source</guilabel> can contain
1372 <link linkend="format-codes">format codes</link> for arbitrary tag frames,
1373 multiple codes can be used to combine the contents from different frames. For
1374 each track, a text is generated from its tags using the <guilabel>Source
1375 </guilabel> format, and the regular expression from
1376 <guilabel>Extraction</guilabel> is applied to this text to set new values for
1377 the tags. Format codes are used before the capturing parentheses to specify
1378 the tag frame where the captured text shall be stored. It works in the same
1379 way as for the <link linkend="import-text">import from file/clipboard</link>.
1380 </para>
1381 <para>
1382 <guimenuitem>Import from Tags...</guimenuitem> is also directly available from
1383 the <guimenu>File</guimenu> menu. The difference between these two functions
1384 is that the import dialog subdialog operates on all files of the current
1385 folder whereas the menu function operates on the selected files (which can
1386 be in different folders). The menu function supports an additional code
1387 "<literal>%{__return}</literal>" to return the extracted value, which can be
1388 useful with the CLI and QML interfaces.
1389 </para>
1390 </listitem>
1391 </varlistentry>
1392
1393 <varlistentry>
1394 <term><menuchoice>
1395 <guimenu>File</guimenu>
1396 <guimenuitem>Import from gnudb.org...</guimenuitem>
1397 </menuchoice></term>
1398 <listitem><para><action>Import from a freedb.org server
1399 using gnudb.org album search.</action> This menu
1400 item opens the same import dialog as <guimenuitem>Import...</guimenuitem>, but
1401 opens directly the <guibutton>gnudb.org</guibutton>
1402 dialog.</para></listitem>
1403 </varlistentry>
1404
1405 <varlistentry>
1406 <term><menuchoice>
1407 <guimenu>File</guimenu>
1408 <guimenuitem>Import from Discogs...</guimenuitem>
1409 </menuchoice></term>
1410 <listitem><para><action>Import from the Discogs server.</action>
1411 This menu item opens the same import dialog as
1412 <guimenuitem>Import...</guimenuitem>, but
1413 opens directly the <guibutton>From Discogs</guibutton>
1414 dialog.</para></listitem>
1415 </varlistentry>
1416
1417 <varlistentry>
1418 <term><menuchoice>
1419 <guimenu>File</guimenu>
1420 <guimenuitem>Import from Amazon...</guimenuitem>
1421 </menuchoice></term>
1422 <listitem><para><action>Import from Amazon.</action>
1423 This menu item opens the same import dialog as
1424 <guimenuitem>Import...</guimenuitem>, but
1425 opens directly the <guibutton>From Amazon</guibutton>
1426 dialog.</para></listitem>
1427 </varlistentry>
1428
1429 <varlistentry>
1430 <term><menuchoice>
1431 <guimenu>File</guimenu>
1432 <guimenuitem>Import from MusicBrainz Release...</guimenuitem>
1433 </menuchoice></term>
1434 <listitem><para><action>Import from the MusicBrainz release database.</action>
1435 This menu item opens the same import dialog as
1436 <guimenuitem>Import...</guimenuitem>, but
1437 opens directly the <guibutton>From MusicBrainz Release</guibutton>
1438 dialog.</para></listitem>
1439 </varlistentry>
1440
1441 <varlistentry>
1442 <term><menuchoice>
1443 <guimenu>File</guimenu>
1444 <guimenuitem>Import from MusicBrainz Fingerprint...</guimenuitem>
1445 </menuchoice></term>
1446 <listitem><para><action>Import from a MusicBrainz server.</action> This menu
1447 item opens the same import dialog as <guimenuitem>Import...</guimenuitem>, but
1448 opens directly the <guibutton>From MusicBrainz Fingerprint</guibutton>
1449 dialog.</para></listitem>
1450 </varlistentry>
1451
1452 <varlistentry>
1453 <term><menuchoice>
1454 <guimenu>File</guimenu>
1455 <guimenuitem>Import from Tags...</guimenuitem>
1456 </menuchoice></term>
1457 <listitem><para>Like <link linkend="import-tags">From Tags</link>, but the
1458 import is applied to the selected files.</para></listitem>
1459 </varlistentry>
1460
1461 <varlistentry id="batch-import">
1462 <term><menuchoice>
1463 <guimenu>File</guimenu>
1464 <guimenuitem>Automatic Import...</guimenuitem>
1465 </menuchoice></term>
1466 <listitem><para>
1467 <action>Automatic Import</action> allows one to import information for multiple
1468 albums from various web services. If folders are selected in the file
1469 list, track data for the selected folders will be imported. If no
1470 folder is selected, all folders in the file list will be imported.
1471 </para>
1472 <para>
1473 The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using the
1474 <guilabel>Destination</guilabel> combo box.
1475 </para>
1476 <para>
1477 Profiles determine which servers will be contacted to fetch album
1478 information. Some profiles are predefined (All, MusicBrainz, Discogs,
1479 Cover Art), custom profiles can be added using the
1480 <guibutton>Add</guibutton> button at the right of the
1481 <guilabel>Profile</guilabel> combo box.
1482 </para>
1483 <para>
1484 The table below shows the servers which will be used when importing album
1485 information using the selected profile. The import process for an album is
1486 finished if all required information has been found, so the order of the
1487 rows in the table is important. It can be changed using the
1488 <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons.
1489 <guibutton>Edit</guibutton> can be used to change an existing entry. The
1490 <guibutton>Server</guibutton> selection offers the same servers as can be
1491 used in the import functions. <guilabel>Standard Tags</guilabel>,
1492 <guilabel>Additional Tags</guilabel>, <guilabel>Cover Art</guilabel>
1493 determine the information which shall be fetched from the server. Finally,
1494 <guilabel>Accuracy</guilabel> is the minimum accuracy which must be
1495 achieved to accept the imported data. If the accuracy is insufficient, the
1496 next server in the list will be tried. The same dialog containing the server
1497 properties appears when <guibutton>Add</guibutton> is clicked to add a new
1498 server entry. Existing entries can be deleted using
1499 <guibutton>Remove</guibutton>.
1500 </para>
1501 <para>
1502 To launch an automatic batch import with the selected profile, click
1503 <guibutton>Start</guibutton>. Details about the running import are displayed
1504 at the top of the dialog. The process can be aborted with the
1505 <guibutton>Abort</guibutton> button.
1506 </para>
1507 <para>
1508 </para></listitem>
1509 </varlistentry>
1510
1511 <varlistentry id="browse_pictures">
1512 <term><menuchoice>
1513 <guimenu>File</guimenu>
1514 <guimenuitem>Browse Cover Art...</guimenuitem>
1515 </menuchoice></term>
1516 <listitem><para>
1517 The <action>Browse Cover Art</action> dialog helps to find album cover
1518 art. <guilabel>Artist/Album</guilabel> is filled from the tags if
1519 possible. <guilabel>Source</guilabel> offers a variety of websites with album
1520 cover art. The &URL; with artist and album as parameters can be found beneath
1521 the name. &URL;-encoded values for artist and album can be inserted using
1522 "<userinput>%u{artist}</userinput>" and "<userinput>%u{album}</userinput>",
1523 other values from the tags are possible too, as described in
1524 <link linkend="configure-kid3">Configure &kid3;</link>, <guilabel>User
1525 Actions</guilabel>. More sources can be entered after the entry "Custom
1526 Source" by replacing "Custom Source" with the source's name, pressing <keycap>Enter</keycap>,
1527 then inserting the &URL; and finally pressing <guibutton>Save
1528 Settings</guibutton>. The resulting browser command is displayed at the top of
1529 the dialog and can be started by clicking <guibutton>Browse</guibutton>. The
1530 browser, which can be configured in the settings, is started with the selected
1531 source. A cover image can then be dragged from the browser into the &kid3;
1532 window and will be set in the picture frame of the selected files.
1533 </para>
1534 <para>
1535 Because not all browsers support drag and drop of images and the pictures on
1536 websites often have a &URL;, in such cases &kid3; will receive the &URL; and not
1537 the picture. If the &URL; points to a picture, it will be downloaded. However,
1538 if the &URL; refers to some other web resource, it has to be translated to the
1539 corresponding picture. Such mappings are defined in the table <guilabel>&URL;
1540 extraction</guilabel>. The left column <guilabel>Match</guilabel> contains a
1541 regular expression which is compared with the &URL;. If it matches, the captured
1542 expressions in parentheses are inserted into the pattern of the
1543 right <guilabel>Picture &URL;</guilabel> column (at the positions marked with \1
1544 <abbrev>etc.</abbrev>). The replaced regular expression contains the &URL; of the picture. By
1545 this means cover art can be imported from Amazon, Google Images, <abbrev>etc.</abbrev> using
1546 drag and drop. It is also possible to define your own mappings.
1547 </para>
1548 </listitem>
1549 </varlistentry>
1550
1551 <varlistentry id="export">
1552 <term><menuchoice>
1553 <guimenu>File</guimenu>
1554 <guimenuitem>Export...</guimenuitem>
1555 </menuchoice></term>
1556 <listitem><para>
1557 The <action>Export Dialog</action> is used to store data from the tags in a
1558 file or the clipboard. The editor at the top shows a preview of the data to
1559 export. If the export data contain tabulator characters, the export is
1560 displayed in a table. The data will be generated from the tags
1561 in the current folder according to the configured format.
1562 </para>
1563 <para>
1564 The format settings are similar as in the Import dialog: The topmost field
1565 contains the title (<abbrev>e.g.</abbrev> "CSV unquoted"), followed by the header, which will
1566 be generated at the begin of the file. The track data follows; it is used for
1567 every track. Finally, the trailer can be used to generate some finishing
1568 text.
1569 </para>
1570 <para>
1571 The format fields do not contain regular expressions as in the Import dialog,
1572 but only output format expressions with special %-expressions, which will be
1573 replaced by values from the tags. The whole thing works like the file name
1574 format, and the same codes are used plus some additional codes. Not only the
1575 codes listed below but all tag frame names can be used.
1576 </para>
1577
1578 <itemizedlist>
1579 <listitem><para>%s %{title} Title (Song)</para></listitem>
1580 <listitem><para>%a %{artist} Artist</para></listitem>
1581 <listitem><para>%l %{album} Album</para></listitem>
1582 <listitem><para>%c %{comment} Comment</para></listitem>
1583 <listitem><para>%y %{year} Year</para></listitem>
1584 <listitem><para>%t %{track} Track (<abbrev>e.g.</abbrev> 01)</para></listitem>
1585 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
1586 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
1587 <listitem><para>%g %{genre} Genre</para></listitem>
1588 <listitem><para>%f %{file} File name</para></listitem>
1589 <listitem><para>%p %{filepath} Path</para></listitem>
1590 <listitem><para>%{modificationdate} Modification date</para></listitem>
1591 <listitem><para>%{creationdate} Creation date</para></listitem>
1592 <listitem><para>%u %{url} &URL;</para></listitem>
1593 <listitem><para>%{dirname} Folder name</para></listitem>
1594 <listitem><para>%d %{duration} Duration in minutes:seconds</para></listitem>
1595 <listitem><para>%D %{seconds} Duration in seconds</para></listitem>
1596 <listitem><para>%n %{tracks} Number of tracks of the album</para></listitem>
1597 <listitem><para>%e %{extension} File extension</para></listitem>
1598 <listitem><para>%O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1599 existing)</para></listitem>
1600 <listitem><para>%o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1601 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not existing)</para></listitem>
1602 <listitem><para>%b %{bitrate} Bit rate in kbit/s</para></listitem>
1603 <listitem><para>%v %{vbr} VBR or empty (only for ID3v2.3 with
1604 id3lib)</para></listitem>
1605 <listitem><para>%r %{samplerate} Sample rate in Hz</para></listitem>
1606 <listitem><para>%m %{mode} Channel mode (Stereo or Joint Stereo)</para></listitem>
1607 <listitem><para>%h %{channels} Number of channels (1 or 2)</para></listitem>
1608 <listitem><para>%k %{codec} Codec (<abbrev>e.g.</abbrev> MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1609 MPC, APE, ASF, AIFF, WAV)</para></listitem>
1610 </itemizedlist>
1611
1612 <para>
1613 A few formats are predefined. "CSV unquoted" separates the fields by
1614 tabs. Data in this format can be imported again into &kid3; using the import
1615 format with the same name. "CSV quoted" additionally encloses the fields by
1616 double quotes, which eases the import into spreadsheet applications. However,
1617 the fields shall not contain any double quotes when this format is used.
1618 "Extended M3U" and "Extended PLS" generate playlists with extended attributes
1619 and absolute path names. "HTML" can be used to generate an &HTML; page with
1620 hyperlinks to the tracks. "Kover &XML;" creates a file which can be imported by
1621 the cover printing program Kover. "Technical Details" provides information
1622 about bit rate, sample rate, channels, <abbrev>etc.</abbrev> Finally, "Custom Format" is left empty for
1623 definition of a custom format. You can define more formats of your own by
1624 adding lines in the file <filename>kid3rc</filename> in the configuration
1625 folder. The other formats can be adapted to your needs.
1626 </para>
1627 <para>
1628 The <guilabel>Source</guilabel> of the tags to generate the export data
1629 (<guilabel>Tag 1</guilabel> or <guilabel>Tag 2</guilabel>) can be selected
1630 with a combo box. Pushing <guibutton>To File</guibutton> or <guibutton>To
1631 Clipboard</guibutton> stores the data in a file or on the clipboard.
1632 <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> close the dialog,
1633 whereas <guibutton>OK</guibutton> accepts the current dialog settings.
1634 </para></listitem>
1635 </varlistentry>
1636
1637 <varlistentry id="create-playlist">
1638 <term><menuchoice>
1639 <guimenu>File</guimenu>
1640 <guimenuitem>Create Playlist...</guimenuitem>
1641 </menuchoice></term>
1642 <listitem><para>
1643 <action>Creates a playlist.</action> The format and contents of the playlist
1644 can be set by various options.</para>
1645 <para>
1646 The name of the playlist can be the <guibutton>Same as folder name</guibutton>
1647 or use a <guibutton>Format</guibutton> with values from the tags, <abbrev>e.g.</abbrev>
1648 "<userinput>%{artist} - %{album}</userinput>" to have the artist and album
1649 name in the playlist file name. The format codes are the same as for
1650 <link linkend="export">Export</link>.
1651 The list of available formats can be edited in the <guilabel>Format</guilabel>
1652 section of the <guilabel>Files</guilabel> tab in the
1653 <link linkend="configure-kid3">settings</link>.
1654 <guibutton>Create new empty playlist</guibutton> will make an empty playlist
1655 with the given name.
1656 The extension depends on the playlist format.
1657 </para>
1658 <para>
1659 The location of the generated playlist is determined by the selection of
1660 the <guilabel>Create in</guilabel> combo box.
1661 <variablelist>
1662 <varlistentry><term>Current folder</term>
1663 <listitem><para>The playlist is created in the current folder and contains
1664 only files of the current folder. The current folder is the folder
1665 where the current file is located. If multiple files are selected, the current
1666 file is probably the last selected file.</para></listitem></varlistentry>
1667 <varlistentry><term>Every folder</term>
1668 <listitem><para>A playlist is created in every folder which contains
1669 listed files, and each playlist contains the files of that folder.
1670 </para></listitem></varlistentry>
1671 <varlistentry><term>Top-level folder</term>
1672 <listitem><para>Only one playlist is created in the top-level
1673 folder (<abbrev>i.e.</abbrev> the folder of the file list) and it contains the listed
1674 files of the top-level folder and all of its sub-folders.
1675 </para></listitem></varlistentry>
1676 </variablelist>
1677 </para>
1678 <para>
1679 The <guilabel>Format</guilabel> of the playlist can
1680 be <guilabel>M3U</guilabel>, <guilabel>PLS</guilabel> or
1681 <guilabel>XSPF</guilabel>.
1682 </para>
1683 <para>
1684 If <guibutton>Include only the selected files</guibutton> is checked, only the
1685 selected files will be included in the playlist. If a folder is selected,
1686 all of its files are selected. If this check box is not activated, all audio
1687 files are included in the playlist.
1688 </para>
1689 <para>
1690 <guibutton>Sort by file name</guibutton> selects the usual case where the
1691 files are ordered by file name. With <guibutton>Sort by tag field</guibutton>,
1692 it is possible to sort by a format string with values from tag fields. For
1693 instance, "<userinput>%{track.3}</userinput>" can be used to sort by track
1694 number (the "<userinput>.3</userinput>" is used to get three digits with
1695 leading zeros because strings are used for sorting). It is also possible to
1696 use multiple fields, <abbrev>e.g.</abbrev> "<userinput>%{genre}%{year}</userinput>" to sort
1697 using a string composed of genre and year.
1698 </para>
1699 <para>
1700 The playlist entries will have relative or absolute file paths depending on
1701 whether <guibutton>Use relative path for files in playlist</guibutton> or
1702 <guibutton>Use full path for files in playlist</guibutton> is set.
1703 </para>
1704 <para>
1705 When <guibutton>Write only list of files</guibutton> is set, the playlist
1706 will only contain the paths to the files. To generate an extended playlist
1707 with additional information, a format string can be set using
1708 the <guibutton>Write info using</guibutton> control.
1709 </para>
1710 </listitem>
1711 </varlistentry>
1712
1713 <varlistentry>
1714 <term><menuchoice>
1715 <shortcut>
1716 <keycombo>&Ctrl;<keycap>Q</keycap></keycombo>
1717 </shortcut>
1718 <guimenu>File</guimenu>
1719 <guimenuitem>Quit</guimenuitem>
1720 </menuchoice></term>
1721 <listitem><para><action>Quits the application.</action></para></listitem>
1722 </varlistentry>
1723
1724 </variablelist>
1725 </para>
1726
1727 </sect1>
1728
1729 <sect1 id="edit-menu">
1730 <title>The Edit Menu</title>
1731 <para>
1732 <variablelist>
1733
1734 <varlistentry>
1735 <term><menuchoice>
1736 <shortcut>
1737 <keycombo>&Alt;<keycap>A</keycap></keycombo>
1738 </shortcut>
1739 <guimenu>Edit</guimenu>
1740 <guimenuitem>Select All</guimenuitem>
1741 </menuchoice></term>
1742 <listitem><para>Selects all files.</para></listitem>
1743 </varlistentry>
1744
1745 <varlistentry>
1746 <term><menuchoice>
1747 <shortcut>
1748 <keycombo>&Ctrl;<keycap>Shift</keycap><keycap>A</keycap></keycombo>
1749 </shortcut>
1750 <guimenu>Edit</guimenu>
1751 <guimenuitem>Deselect</guimenuitem>
1752 </menuchoice></term>
1753 <listitem><para>Deselects all files.</para></listitem>
1754 </varlistentry>
1755
1756 <varlistentry>
1757 <term><menuchoice>
1758 <guimenu>Edit</guimenu>
1759 <guimenuitem>Select All in Folder</guimenuitem>
1760 </menuchoice></term>
1761 <listitem><para>Selects all files of the current folder.</para></listitem>
1762 </varlistentry>
1763
1764 <varlistentry>
1765 <term><menuchoice>
1766 <shortcut>
1767 <keycombo>&Alt;<keycap>Up</keycap></keycombo>
1768 </shortcut>
1769 <guimenu>Edit</guimenu>
1770 <guimenuitem>Previous File</guimenuitem>
1771 </menuchoice></term>
1772 <listitem><para>Selects the previous file.</para></listitem>
1773 </varlistentry>
1774
1775 <varlistentry>
1776 <term><menuchoice>
1777 <shortcut>
1778 <keycombo>&Alt;<keycap>Down</keycap></keycombo>
1779 </shortcut>
1780 <guimenu>Edit</guimenu>
1781 <guimenuitem>Next File</guimenuitem>
1782 </menuchoice></term>
1783 <listitem><para>Selects the next file.</para></listitem>
1784 </varlistentry>
1785
1786 <varlistentry>
1787 <term><menuchoice>
1788 <shortcut>
1789 <keycombo>&Ctrl;<keycap>F</keycap></keycombo>
1790 </shortcut>
1791 <guimenu>Edit</guimenu>
1792 <guimenuitem>Find...</guimenuitem>
1793 </menuchoice></term>
1794 <listitem><para>Find strings in the file names and the tags. The
1795 <guilabel>Find</guilabel> dialog is a subset of the
1796 <guilabel>Replace</guilabel> dialog, which is described below.
1797 </para></listitem>
1798 </varlistentry>
1799
1800 <varlistentry id="find-replace">
1801 <term><menuchoice>
1802 <shortcut>
1803 <keycombo>&Ctrl;<keycap>R</keycap></keycombo>
1804 </shortcut>
1805 <guimenu>Edit</guimenu>
1806 <guimenuitem>Replace...</guimenuitem>
1807 </menuchoice></term>
1808 <listitem><para>This function opens a dialog to find and replace strings in the
1809 file names and the tags. The set of frames where the search is performed can
1810 be restricted by deactivating the <guilabel>Select all</guilabel> check box and
1811 selecting the frames which shall be searched. There are also search options
1812 available to search backwards, case sensitively, and to use regular
1813 expressions.</para>
1814 <para>Depending on the number of files, the search might take some
1815 time, therefore it can be aborted by closing the dialog.</para></listitem>
1816 </varlistentry>
1817
1818 </variablelist>
1819 </para>
1820 </sect1>
1821
1822 <sect1 id="tools-menu">
1823 <title>The Tools Menu</title>
1824 <para>
1825 <variablelist>
1826
1827 <varlistentry id="apply-filename-format">
1828 <term><menuchoice>
1829 <guimenu>Tools</guimenu>
1830 <guimenuitem>Apply Filename Format</guimenuitem>
1831 </menuchoice></term>
1832 <listitem><para>When <guilabel>Automatically apply format</guilabel> is switched off
1833 for the filename format in the configuration dialog, this menu item can be used to <action>apply
1834 the configured format to the names of the selected files</action>. This can also be used
1835 to check whether the file names conform with the configured format
1836 by applying the format to all saved files and then checking if any files were
1837 changed (and therefore marked with a disk symbol in the file listbox).
1838 </para></listitem>
1839 </varlistentry>
1840
1841 <varlistentry id="apply-tag-format">
1842 <term><menuchoice>
1843 <guimenu>Tools</guimenu>
1844 <guimenuitem>Apply Tag Format</guimenuitem>
1845 </menuchoice></term>
1846 <listitem><para>When <guilabel>Automatically apply format</guilabel> is switched off
1847 for the tag format in the configuration dialog, this menu item can be used to <action>apply
1848 the configured format to the tags of the selected files</action>. This can also be used
1849 to check whether the tags conform with the configured format
1850 by applying the format to all saved files and then checking if any files were
1851 changed (and therefore marked with a disk symbol in the file listbox).
1852 </para></listitem>
1853 </varlistentry>
1854
1855 <varlistentry id="apply-text-encoding">
1856 <term><menuchoice>
1857 <guimenu>Tools</guimenu>
1858 <guimenuitem>Apply Text Encoding</guimenuitem>
1859 </menuchoice></term>
1860 <listitem><para>Sets the <guilabel>Text encoding</guilabel> selected in
1861 <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kid3;...
1862 </guimenuitem><guimenuitem>Tags section</guimenuitem><guimenuitem>Tag 2
1863 tab</guimenuitem></menuchoice> for all selected files. If UTF8 is selected,
1864 UTF16 will be used for ID3v2.3.0 tags because UTF8 is not supported for
1865 this format.</para></listitem>
1866 </varlistentry>
1867
1868 <varlistentry id="rename-directory">
1869 <term><menuchoice>
1870 <guimenu>Tools</guimenu>
1871 <guimenuitem>Rename Folder...</guimenuitem>
1872 </menuchoice></term>
1873 <listitem><para>This dialog offers the possibility to automatically rename the
1874 currently open folder according to the tags in the files. Several formats
1875 are preconfigured to include information about artist, album and year in the
1876 folder name. It is also possible to set a custom format and
1877 <guibutton>Edit</guibutton> the list of available formats. The following
1878 special codes are used to insert tag values into the folder name:
1879 </para>
1880
1881 <itemizedlist>
1882 <listitem><para>%s %{title} Title (Song)</para></listitem>
1883 <listitem><para>%a %{artist} Artist</para></listitem>
1884 <listitem><para>%l %{album} Album</para></listitem>
1885 <listitem><para>%c %{comment} Comment</para></listitem>
1886 <listitem><para>%y %{year} Year</para></listitem>
1887 <listitem><para>%t %{track} Track (<abbrev>e.g.</abbrev> 01)</para></listitem>
1888 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
1889 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
1890 <listitem><para>%g %{genre} Genre</para></listitem>
1891 <listitem><para>%{dirname} Folder name (<abbrev>e.g.</abbrev> %{year" "}%{dirname}
1892 will prepend the year to the current folder name)</para></listitem>
1893 <listitem><para>%{max-year} The maximum year value found for this folder,
1894 can also be used with other codes than "year"</para></listitem>
1895 <listitem><para>%{min-year} The minimum year value found for this
1896 folder</para></listitem>
1897 <listitem><para>%{unq-year} The unique year value found for this folder or
1898 empty if not unique</para></listitem>
1899 </itemizedlist>
1900
1901 <para>
1902 If a folder separator "/" is found in the format, multiple folders are
1903 created. If you want to create a new folder instead of renaming the current
1904 folder, in the <guilabel>Action</guilabel> combo box select <guilabel>Create
1905 Folder</guilabel> instead of <guilabel>Rename Folder</guilabel>. The
1906 <guilabel>Source</guilabel> of the tag information can be chosen between
1907 <guilabel>Tag 1 and Tag 2</guilabel>, <guilabel>Tag 1</guilabel> and
1908 <guilabel>Tag 2</guilabel>. A preview for the rename operation performed on
1909 the first file can be seen in the <guilabel>From</guilabel>
1910 and <guilabel>To</guilabel> sections of the dialog.
1911 </para>
1912 <para>
1913 Multiple folders can be renamed by selecting them.
1914 </para></listitem>
1915 </varlistentry>
1916
1917 <varlistentry id="number-tracks">
1918 <term><menuchoice>
1919 <guimenu>Tools</guimenu>
1920 <guimenuitem>Number Tracks...</guimenuitem>
1921 </menuchoice></term>
1922 <listitem><para>
1923 If the track numbers in the tags are not set or have the wrong values, this
1924 function can <action>number the tracks automatically in ascending
1925 order</action>. The start number can be set in the dialog. If only part of the
1926 tracks have to be numbered, they must be selected.
1927 </para><para>
1928 When <guilabel>Total number of tracks</guilabel> is checked, the number
1929 of tracks will also be set in the tags.
1930 </para><para>
1931 It is possible to number the tracks over multiple folders. The folders
1932 have to be expanded and selected.
1933 </para><para>
1934 If <guilabel>Reset counter for each folder</guilabel> is checked, track
1935 numbering is restarted with the given number for each folder when multiple
1936 folders are selected.
1937 </para><para>
1938 The number tracks dialog can also be used to format existing track numbers
1939 without changing the values when the check box left to <guilabel>Start
1940 number</guilabel> is deactivated. The total number of tracks will be added if
1941 the corresponding check box is active, which can be used to set the total for
1942 all selected tracks. If only formatting of the existing numbers is desired,
1943 this check box has to be deactivated too.
1944 </para></listitem>
1945 </varlistentry>
1946
1947 <varlistentry id="filter">
1948 <term><menuchoice>
1949 <guimenu>Tools</guimenu>
1950 <guimenuitem>Filter...</guimenuitem>
1951 </menuchoice></term>
1952 <listitem>
1953 <para>
1954 The filter can be used to display only those files which match certain
1955 criteria. This is helpful if you want to organize a large collection and only
1956 edit those files which are not in the desired scheme. The expression defining
1957 which files to display uses the same format codes which are used in the file
1958 name format, import and export.
1959 </para>
1960
1961 <itemizedlist>
1962 <listitem><para>%s %{title} Title (Song)</para></listitem>
1963 <listitem><para>%a %{artist} Artist</para></listitem>
1964 <listitem><para>%l %{album} Album</para></listitem>
1965 <listitem><para>%c %{comment} Comment</para></listitem>
1966 <listitem><para>%y %{year} Year</para></listitem>
1967 <listitem><para>%t %{track} Track (<abbrev>e.g.</abbrev> 01)</para></listitem>
1968 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
1969 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
1970 <listitem><para>%g %{genre} Genre</para></listitem>
1971 <listitem><para>%f %{file} File name</para></listitem>
1972 <listitem><para>%p %{filepath} Absolute path to file</para></listitem>
1973 <listitem><para>%e %{extension} File extension</para></listitem>
1974 <listitem><para>%O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1975 existing)</para></listitem>
1976 <listitem><para>%o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1977 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not existing)</para></listitem>
1978 <listitem><para>%b %{bitrate} Bit rate in kbit/s</para></listitem>
1979 <listitem><para>%v %{vbr} VBR or empty (only for ID3v2.3 with
1980 id3lib)</para></listitem>
1981 <listitem><para>%r %{samplerate} Sample rate in Hz</para></listitem>
1982 <listitem><para>%m %{mode} Channel mode (Stereo or Joint Stereo)</para></listitem>
1983 <listitem><para>%h %{channels} Number of channels (1 or 2)</para></listitem>
1984 <listitem><para>%k %{codec} Codec (<abbrev>e.g.</abbrev> MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1985 MPC, APE, ASF, AIFF, WAV)</para></listitem>
1986 <listitem><para>%w %{marked} Marked, is 1 if the file is marked (<abbrev>e.g.</abbrev> because
1987 of truncation or standard violation), empty otherwise</para></listitem>
1988 <listitem><para>%1a %1{artist}, ... Use the prefix 1 to get values of tag 1</para></listitem>
1989 <listitem><para>%2a %2{artist}, ... Use the prefix 2 to get values of tag 2</para></listitem>
1990 </itemizedlist>
1991
1992 <para>
1993 These codes are replaced with the values for
1994 the file, and the resulting strings can be compared with the following
1995 operations:
1996 </para>
1997 <itemizedlist>
1998 <listitem><para>s1 equals s2: true if s1 and s2 are equal.</para></listitem>
1999 <listitem><para>s1 contains s2: true if s1 contains s2, <abbrev>i.e.</abbrev> s2 is a
2000 substring of s1.</para></listitem>
2001 <listitem><para>s matches re: true if s matches the regular expression re.</para></listitem>
2002 </itemizedlist>
2003 <para>
2004 True expressions are replaced by 1, false by 0. True values are represented by
2005 1, true, on and yes, false values by 0, false, off and no. Boolean operations
2006 are not, and, or (in this order of precedence) and can be grouped by parentheses.
2007 </para>
2008 <para>
2009 Some filter rules are predefined and can serve as examples for your own
2010 expressions:
2011 </para>
2012
2013 <variablelist>
2014 <varlistentry><term>All</term><listitem>
2015 <para>
2016 When the file list is filtered - this is shown by "[filtered]" in the
2017 window title - and all files shall be displayed again,
2018 the filtering can be reverted using this filter. It uses an empty expression,
2019 but a true value would have the same effect.
2020 </para>
2021 </listitem></varlistentry>
2022
2023 <varlistentry><term>Filename Tag Mismatch</term><listitem>
2024 <para><userinput>
2025 not (%{filepath} contains "%{artist} - %{album}/%{track} %{title}")
2026 </userinput></para>
2027 <para>
2028 Tests if the file path conforms with the file name format. This
2029 rule is automatically adapted if the file name format changes.
2030 </para>
2031 </listitem></varlistentry>
2032
2033 <varlistentry><term>No Tag 1</term><listitem>
2034 <para><userinput>
2035 %{tag1} equals ""
2036 </userinput></para>
2037 <para>Displays only files which do not have a tag 1.</para>
2038 </listitem></varlistentry>
2039
2040 <varlistentry><term>No Tag 2</term><listitem>
2041 <para><userinput>
2042 %{tag2} equals ""
2043 </userinput></para>
2044 <para>Displays only files which do not have a tag 2.</para>
2045 </listitem></varlistentry>
2046
2047 <varlistentry><term>ID3v2.3.0 Tag</term><listitem>
2048 <para><userinput>
2049 %{tag2} equals "ID3v2.3.0"
2050 </userinput></para>
2051 <para>Displays only files which have an ID3v2.3.0 tag.</para>
2052 </listitem></varlistentry>
2053
2054 <varlistentry><term>ID3v2.4.0 Tag</term><listitem>
2055 <para><userinput>
2056 %{tag2} equals "ID3v2.4.0"
2057 </userinput></para>
2058 <para>Displays only files which have an ID3v2.4.0 tag.</para>
2059 </listitem></varlistentry>
2060
2061 <varlistentry><term>Tag 1 != Tag 2</term><listitem>
2062 <para><userinput>
2063 not (%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist}
2064 equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals
2065 %2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre})
2066 </userinput></para>
2067 <para>Displays files with differences between tag 1 and tag2.</para>
2068 </listitem></varlistentry>
2069
2070 <varlistentry><term>Tag 1 == Tag 2</term><listitem>
2071 <para><userinput>
2072 %1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist}
2073 equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals
2074 %2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre}
2075 </userinput></para>
2076 <para>Displays files with identical tag 1 and tag 2.</para>
2077 </listitem></varlistentry>
2078
2079 <varlistentry><term>Incomplete</term><listitem>
2080 <para><userinput>
2081 %{title} equals "" or %{artist} equals "" or %{album} equals "" or %{year} equals "" or %{tracknumber} equals "" or %{genre} equals ""
2082 </userinput></para>
2083 <para>Displays files with empty values in the standard tags (title, artist,
2084 album, date, track number, genre).</para>
2085 </listitem></varlistentry>
2086
2087 <varlistentry><term>No Picture</term><listitem>
2088 <para><userinput>
2089 %{picture} equals ""
2090 </userinput></para>
2091 <para>Displays only files which do not have a picture.</para>
2092 </listitem></varlistentry>
2093
2094 <varlistentry><term>Marked</term><listitem>
2095 <para><userinput>
2096 not (%{marked} equals "")
2097 </userinput></para>
2098 <para>Displays only files which are marked because they violate the ID3
2099 standard, are truncated or the picture is too large.</para>
2100 </listitem></varlistentry>
2101
2102 <varlistentry><term>Custom Filter</term><listitem>
2103 <para>
2104 To add your own filter, select this entry. For instance, if you want
2105 to have a filter for artists starting with "The", replace "Custom Filter"
2106 with the name "The Bands" and press <keycap>Enter</keycap>. Then insert the following
2107 expression into the line edit:
2108 </para>
2109 <para><userinput>
2110 %{artist} matches "The.*"
2111 </userinput></para>
2112 <para>
2113 Then click <guibutton>Save
2114 Settings</guibutton>. Click <guibutton>Apply</guibutton> to filter the
2115 files. All files processed are displayed in the text view, with a "+" for
2116 those who match the filter and a "-" for the others. When finished, only the
2117 files with an artist starting with "The" are displayed, and the window title
2118 is marked with "[filtered]".
2119 </para>
2120 </listitem></varlistentry>
2121
2122 </variablelist>
2123 </listitem>
2124 </varlistentry>
2125
2126 <varlistentry id="convert-to-id3v24">
2127 <term><menuchoice>
2128 <guimenu>Tools</guimenu>
2129 <guimenuitem>Convert ID3v2.3 to ID3v2.4</guimenuitem>
2130 </menuchoice></term>
2131 <listitem><para>
2132 If there are any ID3v2.3 tags in the selected files, they will
2133 be <action>converted to ID3v2.4</action> tags. Frames which are not supported
2134 by TagLib will be discarded. Only files without unsaved changes will be converted.
2135 </para></listitem>
2136 </varlistentry>
2137
2138 <varlistentry id="convert-to-id3v23">
2139 <term><menuchoice>
2140 <guimenu>Tools</guimenu>
2141 <guimenuitem>Convert ID3v2.4 to ID3v2.3</guimenuitem>
2142 </menuchoice></term>
2143 <listitem><para>
2144 If there are any ID3v2.4 tags in the selected files, they will
2145 be <action>converted to ID3v2.3</action> tags. Only files without
2146 unsaved changes will be converted.
2147 </para></listitem>
2148 </varlistentry>
2149
2150 <varlistentry id="play">
2151 <term><menuchoice>
2152 <guimenu>Tools</guimenu>
2153 <guimenuitem>Play</guimenuitem>
2154 </menuchoice></term>
2155 <listitem><para>
2156 This opens a simple toolbar to play audio files. It contains buttons for the
2157 basic operations (<guibutton>Play/Pause</guibutton>,
2158 <guibutton>Stop playback</guibutton>, <guibutton>Previous Track</guibutton>,
2159 <guibutton>Next Track</guibutton>, <guibutton>Close</guibutton>),
2160 sliders for position and volume and a display of the current position.
2161 If multiple files are selected, the selected tracks are played, else all
2162 files will be played.
2163 </para><para>
2164 The time displayed can be toggled between elapsed and remaining time by
2165 clicking on the display.
2166 </para></listitem>
2167 </varlistentry>
2168
2169 </variablelist>
2170 </para>
2171 </sect1>
2172
2173 <sect1 id="settings-menu">
2174 <title>The Settings Menu</title>
2175 <para>
2176 <variablelist>
2177
2178 <varlistentry>
2179 <term><menuchoice>
2180 <guimenu>Settings</guimenu>
2181 <guimenuitem>Show Toolbar</guimenuitem>
2182 </menuchoice></term>
2183 <listitem><para><action>Toggles displaying of the toolbar.</action></para></listitem>
2184 </varlistentry>
2185
2186 <varlistentry>
2187 <term><menuchoice>
2188 <guimenu>Settings</guimenu>
2189 <guimenuitem>Show Statusbar</guimenuitem>
2190 </menuchoice></term>
2191 <listitem><para><action>Toggles displaying of the statusbar</action>, which displays
2192 longer actions such as opening or saving a folder.</para></listitem>
2193 </varlistentry>
2194
2195 <varlistentry>
2196 <term><menuchoice>
2197 <guimenu>Settings</guimenu>
2198 <guimenuitem>Show Picture</guimenuitem>
2199 </menuchoice></term>
2200 <listitem><para><action>Toggles displaying of the album cover art preview
2201 picture.</action>
2202 </para></listitem>
2203 </varlistentry>
2204
2205 <varlistentry>
2206 <term><menuchoice>
2207 <guimenu>Settings</guimenu>
2208 <guimenuitem>Auto Hide Tags</guimenuitem>
2209 </menuchoice></term>
2210 <listitem><para>
2211 Empty tags are automatically hidden if this option is active.
2212 The <guilabel>File</guilabel>, <guilabel>Tag 1</guilabel>
2213 and <guilabel>Tag 2</guilabel> sections can be manually collapsed and expanded
2214 by clicking on the corresponding
2215 <guibutton>-</guibutton>/<guibutton>+</guibutton> buttons.
2216 </para></listitem>
2217 </varlistentry>
2218
2219 <varlistentry id="configure-shortcuts">
2220 <term><menuchoice>
2221 <guimenu>Settings</guimenu>
2222 <guimenuitem>Configure Shortcut keys...</guimenuitem>
2223 </menuchoice></term>
2224 <listitem><para>Opens a dialog to assign keyboard shortcuts for most of the
2225 program functions. There are even functions without corresponding menu or
2226 button available, <abbrev>e.g.</abbrev> next file, previous file, select all.
2227 </para>
2228 <para>
2229 </para>
2230 </listitem>
2231 </varlistentry>
2232
2233 <varlistentry id="configure-kid3">
2234 <term><menuchoice>
2235 <guimenu>Settings</guimenu>
2236 <guimenuitem>Configure &kid3;...</guimenuitem>
2237 </menuchoice></term>
2238 <listitem><para>Opens the <action>configuration dialog</action>, which
2239 consists of pages for tags, files, user actions, and network settings.
2240 </para>
2241 <para>
2242 Tag specific options can be found on the <guilabel>Tags</guilabel> page,
2243 which is itself separated into four tabs
2244 for <guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel>, <guilabel>Tag
2245 3</guilabel>, and <guilabel>All Tags</guilabel>.
2246 </para>
2247 <para>
2248 If <guilabel>Mark truncated fields</guilabel> is checked, truncated ID3v1.1
2249 fields will be marked red. The text fields of ID3v1.1 tags can only have 30
2250 characters, the comment only 28 characters. Also the genre and track numbers
2251 are restricted, so that fields can be truncated when imported or transferred
2252 from ID3v2. Truncated fields and the file will be marked red, and the mark
2253 will be removed after the field has been edited.
2254 </para>
2255 <para>
2256 With <guilabel>Text encoding</guilabel> for <guilabel>ID3v1</guilabel> it is
2257 possible to set the character set used in ID3v1 tags. This encoding is
2258 supposed to be ISO-8859-1, so it is recommended to keep this default
2259 value. However, there are tags around with different encoding, so it can be
2260 set here and the ID3v1 tags can then be copied to ID3v2 which supports Unicode.
2261 </para>
2262 <para>
2263 The check box <guilabel>Use track/total number of tracks
2264 format</guilabel> controls whether the track number field of ID3v2 tags
2265 contains simply the track number or additionally the total number of tracks in
2266 the folder.
2267 </para>
2268 <para>
2269 When <guilabel>Genre as text instead of numeric string</guilabel> is checked,
2270 all ID3v2 genres will be stored as a text string even if there is a
2271 corresponding code for ID3v1 genres. If this option is not set, genres for which
2272 an ID3v1 code exists are stored as the number of the genre code (in
2273 parentheses for ID3v2.3). Thus the genre Metal is stored as "Metal" or "(9)"
2274 depending on this option. Genres which are not in the list of ID3v1 genres are
2275 always stored as a text string. The purpose of this option is improved
2276 compatibility with devices which do not correctly interpret genre codes.
2277 </para>
2278 <para>
2279 When <guilabel>WAV files with lowercase id3 chunk</guilabel> is checked, the
2280 RIFF chunk used to store ID3v2 tags in WAV files will be named "id3 " instead
2281 of "ID3 ". By default, &kid3; and other applications using TagLib accept both
2282 the lowercase and the uppercase variant when reading WAV files, but they use
2283 "ID3 " when writing ID3v2 tags to WAV files. As there exist other applications
2284 which only accept "id3 " (<abbrev>e.g.</abbrev> JRiver Media Center and foobar2000), this
2285 option can be used to create tags which can be read by such applications.
2286 </para>
2287 <para>
2288 When <guilabel>Mark standard violations</guilabel> is checked, ID3v2 fields
2289 which violate the standard will be marked red. Details about the violation are
2290 shown in a tooltip:
2291 </para>
2292 <itemizedlist>
2293 <listitem><para>Must be unique</para></listitem>
2294 <listitem><para>New line is forbidden</para></listitem>
2295 <listitem><para>Carriage return is forbidden</para></listitem>
2296 <listitem><para>Owner must be non-empty</para></listitem>
2297 <listitem><para>Must be numeric</para></listitem>
2298 <listitem><para>Must be numeric or number/total</para></listitem>
2299 <listitem><para>Format is DDMM</para></listitem>
2300 <listitem><para>Format is HHMM</para></listitem>
2301 <listitem><para>Format is YYYY</para></listitem>
2302 <listitem><para>Must begin with a year and a space character</para></listitem>
2303 <listitem><para>Must be ISO 8601 date/time</para></listitem>
2304 <listitem><para>Must be musical key, 3 characters, A-G, b, #, m, o</para></listitem>
2305 <listitem><para>Must have ISO 639-2 language code, 3 lowercase characters</para></listitem>
2306 <listitem><para>Must be ISRC code, 12 characters</para></listitem>
2307 <listitem><para>Must be list of strings separated by '|'</para></listitem>
2308 <listitem><para>Has excess white space</para></listitem>
2309 </itemizedlist>
2310 <para>
2311 The ID3 standard documents are available online:
2312 </para>
2313 <itemizedlist>
2314 <listitem><para><ulink url="http://id3.org/id3v2.3.0">ID3 tag version 2.3.0</ulink></para></listitem>
2315 <listitem><para><ulink url="http://id3.org/id3v2.4.0-structure">ID3 tag version 2.4.0 - Main Structure</ulink></para></listitem>
2316 <listitem><para><ulink url="http://id3.org/id3v2.4.0-frames">ID3 tag version 2.4.0 - Native Frames</ulink></para></listitem>
2317 </itemizedlist>
2318 <para>
2319 <guilabel>Text encoding</guilabel> defines the default encoding used for ID3v2
2320 frames and can be set
2321 to <guilabel>ISO-8859-1</guilabel>, <guilabel>UTF16</guilabel>,
2322 or <guilabel>UTF8</guilabel>. <guilabel>UTF8</guilabel> is not valid for
2323 ID3v2.3.0 frames; if it is set, <guilabel>UTF16</guilabel> will be used
2324 instead. For ID3v2.4.0 frames, all three encodings are possible.
2325 </para>
2326 <para>
2327 <guilabel>Version used for new tags</guilabel> determines whether new ID3v2
2328 tags are created as version 2.3.0 or 2.4.0.
2329 </para>
2330 <para>
2331 <guilabel>Track number digits</guilabel> is the number of digits in Track
2332 Number fields. Leading zeros are used to pad. For instance, with a value of 2
2333 the track number 5 is set as "05".
2334 </para>
2335 <para>
2336 The combo box <guilabel>Comment field name</guilabel> is only
2337 relevant for Ogg/Vorbis and FLAC files and sets the name of the field used for
2338 comments. Different applications seem to use different names,
2339 "<literal>COMMENT</literal>" for instance is used by <application>XMMS</application>,
2340 whereas &amarok; uses "<literal>DESCRIPTION</literal>".
2341 </para>
2342 <para>
2343 The format of pictures in Ogg/Vorbis files is determined by
2344 <guilabel>Picture field name</guilabel>, which can be
2345 "<literal>METADATA_BLOCK_PICTURE</literal>" or "<literal>COVERART</literal>".
2346 The first is the official standard and uses the same format as pictures in FLAC
2347 tags. "<literal>COVERART</literal>" is an earlier unofficial way to include
2348 pictures in Vorbis comments. It can be used for compatibility with legacy players.
2349 </para>
2350 <para>
2351 The mode used when saving <guilabel>Matroska</guilabel> files can be selected
2352 with <guilabel>Write mode</guilabel>. It controls the trade-off between file
2353 size and write speed when saving tags, attachments and chapters to the file.
2354 For very large files and/or slow (network) filesystems, using
2355 <guilabel>Avoid insert</guilabel> will reduce write time significantly.
2356 There are three possible modes:
2357 </para>
2358 <itemizedlist>
2359 <listitem><para>Compact: Write tags, attachments and chapters as compact as
2360 possible. This is the default mode.</para></listitem>
2361 <listitem><para>Do not shrink: Do not shrink blocks when writing, add padding
2362 when content gets smaller. Allow inserts when content gets larger.
2363 </para></listitem>
2364 <listitem><para>Avoid insert: Like <guilabel>Do not shrink</guilabel> but also
2365 avoid inserts for blocks which are not at the end of the file: Replace a growing
2366 non-last block with padding of the old size and append a new block at the end of
2367 the file.</para></listitem>
2368 </itemizedlist>
2369 <para>
2370 If the <guilabel>Mark if larger than (bytes)</guilabel> check box is activated,
2371 files containing embedded album cover art exceeding the given size in bytes
2372 are marked red. This can be used to find files containing oversized pictures
2373 which are not accepted by some applications and players. The default value is
2374 131072 bytes (128 KB).
2375 </para>
2376 <para>
2377 <guilabel>Custom Genres</guilabel> can be used to define genres which are not
2378 available in the standard genre list, <abbrev>e.g.</abbrev> "Gothic Metal". Such custom genres
2379 will appear in the <guilabel>Genre</guilabel> combo box of
2380 <guilabel>Tag 2</guilabel>. For ID3v1.1 tags, only the predefined genres can
2381 be used.
2382 </para>
2383 <para>
2384 The list of custom genres can also be used to reduce the number of genres
2385 available in the <guilabel>Genre</guilabel> combo box to those typically used.
2386 If your collection mostly contains music in the genres Metal, Gothic Metal,
2387 Ancient and Hard Rock, you can enter those genres and mark
2388 <guilabel>Show only custom genres</guilabel>. The <guilabel>Tag 2</guilabel>
2389 <guilabel>Genre</guilabel> combo box will then only contain those four genres
2390 and you will not have to search through the complete genres list for them.
2391 In this example, only Metal and Hard Rock will be listed in the tag 1 genres
2392 list, because those two custom genres entries are standard genres.
2393 If <guilabel>Show only custom genres</guilabel> is not active, the custom
2394 genres can be found at the end of the genres list.
2395 </para>
2396 <para>
2397 In <guilabel>Custom Frames</guilabel>, up to eight custom frame names can be
2398 defined, which can then be used like the unified frames, for example as
2399 quick access frames.
2400 </para>
2401 <para>
2402 <guilabel>Quick Access Frames</guilabel> defines which frame types are always
2403 shown in the <link linkend="tag2">Tag 2</link> section. Such frames can
2404 then be added without first using the <guibutton>Add</guibutton> button.
2405 The order of these quick access frames can be changed by dragging and dropping
2406 items.
2407 </para>
2408 <para>
2409 The combo box <guilabel>Track number field name</guilabel> is only
2410 relevant for RIFF INFO and sets the name of the field used for
2411 track numbers. Track numbers are not specified in the original RIFF standard,
2412 there are applications which use "<literal>ITRK</literal>", others use
2413 "<literal>IPRT</literal>".
2414 </para>
2415 <para>
2416 <guilabel>Tag Format</guilabel> contains options for the format of the tags.
2417 When <guilabel>Automatically apply format</guilabel> is checked, the format
2418 configuration is automatically used while editing text in the line edits.
2419 <guilabel>Validation</guilabel> enables validators in the controls with
2420 track/total and date/time values.
2421 The <guilabel>Case conversion</guilabel> can be set to <guilabel>No
2422 changes</guilabel>, <guilabel>All lowercase</guilabel>, <guilabel>All
2423 uppercase</guilabel>, <guilabel>First letter uppercase</guilabel> or
2424 <guilabel>All first letters uppercase</guilabel>. To use locale-aware
2425 conversion between lowercase and uppercase characters, a locale can be
2426 selected in the combobox below.
2427 The string replacement list can be set to arbitrary string mappings. To add a
2428 new mapping, select the <guilabel>From</guilabel> cell of a row and insert the
2429 text to replace, then go to the <guilabel>To</guilabel> column and enter the
2430 replacement text. When the text to replace starts and ends with a slash ("/"),
2431 a regular expression is used. For regular expressions containing capturing
2432 groups, occurrences of \1, \2, ... in <guilabel>To</guilabel> are replaced
2433 with the string captured by the corresponding capturing group.
2434 To remove a mapping set the <guilabel>From</guilabel> cell
2435 to an empty value (<abbrev>e.g.</abbrev> by first typing space and then backspace). Inserting
2436 and deleting rows is also possible using a context menu which appears when the
2437 <mousebutton>right</mousebutton> mouse button is clicked. Replacement is only active, if the <guilabel>String
2438 replacement</guilabel> check box is checked.
2439 </para>
2440
2441 <para>
2442 The table in <guilabel>Rating</guilabel> contains the mapping of star ratings
2443 to the effective values stored in the tag. The frames with rating information
2444 are listed in the Rating row of the
2445 <!--change manpageframe list.--><link linkend="table-frame-list">frame list</link>.
2446 For these frames, the rating can be set by giving a number of
2447 stars out of five stars. Different tag formats and different applications use
2448 different values to map the star rating to the value stored in the tag. In
2449 order to display the correct number of stars, &kid3; will look up a map in
2450 this table. The key to look up the mapping is the frame name, for example
2451 "RATING" as used for Vorbis comments or "IRTD" for RIFF INFO. For ID3v2 tags,
2452 a combined key is used consisting of the frame ID "POPM" of the Popularimeter
2453 frame and its "Email" field, separated by a dot. Therefore, different keys for
2454 ID3v2 exist, <abbrev>e.g.</abbrev> "POPM.Windows Media Player 9 Series" for the mapping used by
2455 Windows Media Player and Explorer, and simply "POPM" for POPM frames with an
2456 empty "Email" field. As multiple entries for "POPM" can exist, their order is
2457 important. When &kid3; adds a new Popularimeter frame, it will use the first
2458 "POPM" entry to determine the value to be written into the "Email" field. This
2459 value will then specify the mapping to be used for star ratings. The first
2460 entry is also used if no key was found, it is therefore the default entry.
2461 </para>
2462 <para>
2463 Besides the <guilabel>Name</guilabel> column containing the keys, the table
2464 has columns <guilabel>1</guilabel> to <guilabel>5</guilabel> for the values to
2465 be stored when the corresponding number of stars is given. The other way
2466 round, the values determine the number of stars which are displayed for the
2467 value stored in the frame. For instance, the row in the table below contains
2468 the values 1, 64, 128, 196, 255. The thresholds for the number of stars to be
2469 displayed lay between these values and are compatible with what the &Windows;
2470 Explorer uses.
2471 </para>
2472
2473 <table id="table-rating">
2474 <title>Entry in Rating Table</title>
2475 <tgroup cols="6">
2476 <thead>
2477 <row><entry>Name</entry><entry>1</entry> <entry>2</entry> <entry>3</entry> <entry>4</entry> <entry>5</entry></row>
2478 </thead>
2479 <tbody>
2480 <row><entry>POPM</entry><entry>1</entry><entry>64</entry><entry>128</entry><entry>196</entry><entry>255</entry></row>
2481 <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>
2482 </tbody>
2483 </tgroup>
2484 </table>
2485
2486 <para>
2487 On the page <guilabel>Files</guilabel> the check box <guilabel>Load
2488 last-opened files</guilabel> can be marked so that &kid3; will open and
2489 select the last selected file when it is started the next time.
2490 <guilabel>Preserve file timestamp</guilabel> can be checked to preserve
2491 the file modification time stamp.
2492 <guilabel>Filename for cover</guilabel> sets the name which is suggested
2493 when an embedded image is exported to a file.
2494 With <guilabel>Text encoding (Export, Playlist)</guilabel> the encoding used
2495 when writing files can be set. The default <guilabel>System</guilabel> can be
2496 changed for example if playlists have to be used on a different device.
2497 </para>
2498 <para>
2499 If <guilabel>Mark changes</guilabel> is active, changed fields are marked with
2500 a light gray label background.
2501 </para>
2502 <para>
2503 The section <guilabel>File List</guilabel> determines which files are
2504 displayed in the file list. A <guilabel>Filter</guilabel> can be used to
2505 restrict the items in this list to files with supported extensions. To
2506 explicitly specify which folders to display in the file list or exclude
2507 certain folders, the options <guilabel>Include folders</guilabel> and
2508 <guilabel>Exclude folders</guilabel> can be used. They can contain wildcard
2509 expressions, for instance <filename>*/Music/*</filename> to include only the
2510 <filename>Music</filename> folder, or <filename>*/iTunes/*</filename> to
2511 exclude the iTunes folder from the file list. If multiple such expressions
2512 have to be used, they can be separated by spaces or semicolons.
2513 </para>
2514 <para>
2515 The buttons <guibutton>Filename from tag</guibutton> and <guibutton>Tag from
2516 filename</guibutton> in section <guilabel>Format</guilabel> open dialogs to
2517 edit the formats which are available in the <guilabel>Format</guilabel> combo
2518 boxes (with arrows up and down), which can be found in the
2519 <link linkend="file">File</link> section of the main window.
2520 </para>
2521 <para>
2522 The <guibutton>Playlist</guibutton> button can be used to edit the file name
2523 formats available in the <link linkend="create-playlist">Create Playlist</link>
2524 dialog.
2525 </para>
2526 <para>
2527 <guilabel>Filename Format</guilabel> contains options for the format of the
2528 filenames. The same options as in <guilabel>Tag Format</guilabel> are available.
2529 </para>
2530 <para>
2531 Additionally, the <guilabel>Maximum length</guilabel> allowed for file names can
2532 be set. Most modern file systems have a limit of 255 characters, but if you want
2533 to burn the files to CD, you should set the limit to 64.
2534 If <guilabel>Use for playlist and folder names</guilabel> is checked, the
2535 file name format is also used when creating playlists and renaming folders.
2536 </para>
2537 <para>
2538 The <guilabel>User Actions</guilabel> page contains a table with the commands
2539 which are available in the context menu of the file list. For critical
2540 operations such as deleting files, it is advisable to mark
2541 <guilabel>Confirm</guilabel> to pop up a confirmation dialog before executing
2542 the command.
2543 <guilabel>Output</guilabel> can be marked to see the output written by console
2544 commands (standard output and standard error). <guilabel>Name</guilabel> is
2545 the name displayed in the context menu. <guilabel>Command</guilabel> is the
2546 command line to be executed. Arguments can be passed using the following
2547 codes:
2548 </para>
2549
2550 <itemizedlist>
2551 <listitem><para>%F %{files} File paths (a list if multiple files selected)</para></listitem>
2552 <listitem><para>%f %{file} File path to single file</para></listitem>
2553 <listitem><para>%uF %{urls} &URL;s (a list if multiple files selected)</para></listitem>
2554 <listitem><para>%uf %{url} &URL; to single file</para></listitem>
2555 <listitem><para>%d %{directory} Folder</para></listitem>
2556 <listitem><para>%s %{title} Title (Song)</para></listitem>
2557 <listitem><para>%a %{artist} Artist</para></listitem>
2558 <listitem><para>%l %{album} Album</para></listitem>
2559 <listitem><para>%c %{comment} Comment</para></listitem>
2560 <listitem><para>%y %{year} Year</para></listitem>
2561 <listitem><para>%t %{track} Track (<abbrev>e.g.</abbrev> 01)</para></listitem>
2562 <listitem><para>%t %{track.n} Track with field width n (<abbrev>e.g.</abbrev> 001 for %{track.3})</para></listitem>
2563 <listitem><para>%T %{tracknumber} Track (without leading zeros, <abbrev>e.g.</abbrev> 1)</para></listitem>
2564 <listitem><para>%g %{genre} Genre</para></listitem>
2565 <listitem><para>%b %{browser} Command to start the web browser</para></listitem>
2566 <listitem><para>%q %{qmlpath} Base folder of provided QML files</para></listitem>
2567 </itemizedlist>
2568
2569 <para>
2570 The special code <command>@separator</command> can be set as a command to
2571 insert a separator into the user actions context menu. Menu items can be put
2572 into a submenu by enclosing them with <command>@beginmenu</command> and
2573 <command>@endmenu</command> commands. The name of the submenu is determined by
2574 the <guilabel>Name</guilabel> column of the <command>@beginmenu</command>
2575 command.
2576 </para>
2577
2578 <para id="configure-user-actions-qml">
2579 To execute QML scripts, <command>@qml</command> is used as a command name. The
2580 path to the QML script is passed as a parameter. The provided scripts can be
2581 found in the folder <filename>%{qmlpath}/script/</filename> (on
2582 &Linux; typically <filename>/usr/share/kid3/qml/script/</filename>, on
2583 Windows <filename>qml/script/</filename> inside the installation folder,
2584 and on &macOS; in the app folder
2585 <filename>kid3.app/Contents/Resources/qml/script/</filename>). Custom scripts
2586 can be stored in any folder. If the QML code uses &GUI; components,
2587 <command>@qmlview</command> shall be used instead of
2588 <command>@qml</command>. Additional parameters are passed to the QML script
2589 where they will be available via the <function>getArguments()</function>
2590 function. An overview of some functions and properties which are available in
2591 QML can be found in the appendix <link linkend="qml-interface">QML Interface</link>.
2592 </para>
2593
2594 <para>
2595 The command which will be inserted with %{browser} can be defined in the
2596 <guilabel>Web browser</guilabel> line edit above. Commands starting with %{browser}
2597 can be used to fetch information about the audio files from the web,
2598 for instance
2599 <screen width="40">
2600 <userinput>%{browser} http://lyricwiki.org/%u{artist}:%u{title}</userinput>
2601 </screen>
2602 will query the lyrics for the current song in
2603 <ulink url="http://www.lyricwiki.org">LyricWiki</ulink>. The "u" in %u{artist} and %u{title}
2604 is used to &URL;-encode the artist %{artist} and song %{title} information. It is easy to
2605 define your own queries in the same way, <abbrev>e.g.</abbrev> an image search with
2606 <ulink url="http://www.google.com">Google</ulink>:
2607 <screen width="40">
2608 <userinput>%{browser} http://images.google.com/images?q=%u{artist}%20%u{album}</userinput>
2609 </screen>
2610 </para>
2611 <para>
2612 To add album cover art to tag 2, you can search for images with Google or
2613 Amazon using the commands described above. The picture can be added to the tag
2614 with drag and drop. You can also add an image with <guibutton>Add</guibutton>, then select
2615 the Picture frame and import an image file or paste from the
2616 clipboard. Picture frames are supported for ID3v2, MP4, FLAC, Ogg and ASF tags.
2617 </para>
2618 <para>
2619 To add and delete entries in the table, a context menu can be
2620 used.
2621 </para>
2622 <para>
2623 The <guilabel>Network</guilabel> page contains only a field to insert the proxy
2624 address and optionally the port, separated by a colon. The proxy will be used
2625 when importing from an Internet server when the check box is checked.
2626 </para>
2627 <para>
2628 In the <guilabel>Plugins</guilabel> page, available plugins can be enabled or
2629 disabled. The plugins are separated into two sections. The <guilabel>Metadata
2630 Plugins &amp; Priority</guilabel> list contains plugins which support audio
2631 file formats. The order of the plugins is important because they are tried from
2632 top to bottom. Some formats are supported by multiple plugins, so files will
2633 be opened with the first plugin supporting them. The
2634 <guilabel>TaglibMetadata</guilabel> supports most formats, if it is at the top
2635 of the list, it will open most of the files. If you want to use a different
2636 plugin for a file format, make sure that it is listed before the
2637 <guilabel>TaglibMetadata</guilabel> plugin. Details about the metadata plugin
2638 and why you may want to use them instead of TagLib are listed below.
2639 </para>
2640 <itemizedlist>
2641 <listitem><para><guilabel>Id3libMetadata</guilabel>:
2642 Uses <ulink url="http://id3lib.sourceforge.net">id3lib</ulink> for ID3v1.1
2643 and ID3v2.3 tags in MP3, MP2, AAC files. Supports a few more frame types
2644 than TagLib.</para></listitem>
2645 <listitem><para><guilabel>OggFlacMetadata</guilabel>:
2646 Uses <ulink url="http://xiph.org/ogg/">libogg</ulink>,
2647 <ulink url="http://xiph.org/vorbis/">libvorbis, libvorbisfile</ulink> for Ogg
2648 files, and additionally <ulink url="http://flac.sourceforge.net">libFLAC++
2649 and libFLAC</ulink> for FLAC files. These are the official
2650 libraries for these formats.</para></listitem>
2651 <listitem><para><guilabel>TaglibMetadata</guilabel>:
2652 Uses <ulink url="http://taglib.github.io/">TagLib</ulink> which supports a
2653 lot of audio file formats. It can be used for all audio files supported by
2654 &kid3;.</para></listitem>
2655 <listitem><para><guilabel>Mp4v2Metadata</guilabel>:
2656 <ulink url="https://mp4v2.org/">mp4v2</ulink> was originally used
2657 by &kid3; to support M4A files. Can be used in case of problems with the M4A
2658 support of TagLib.
2659 </para></listitem>
2660 </itemizedlist>
2661 <para>
2662 The <guilabel>Available Plugins</guilabel> section lists the remaining
2663 plugins. Their order is not important, but they can be enabled or disabled
2664 using the check boxes.
2665 </para>
2666 <itemizedlist>
2667 <listitem><para><guilabel>AmazonImport</guilabel>:
2668 Used for the <guimenuitem>Import from Amazon...</guimenuitem> function.
2669 </para></listitem>
2670 <listitem><para><guilabel>DiscogsImport</guilabel>:
2671 Used for the <guimenuitem>Import from Discogs...</guimenuitem> function.
2672 </para></listitem>
2673 <listitem><para><guilabel>FreedbImport</guilabel>:
2674 Used for the <guimenuitem>Import from gnudb.org...</guimenuitem>
2675 function.
2676 </para></listitem>
2677 <listitem><para><guilabel>MusicBrainzImport</guilabel>:
2678 Used for the <guimenuitem>Import from MusicBrainz Release...</guimenuitem>
2679 function.
2680 </para></listitem>
2681 <listitem><para><guilabel>AcoustidImport</guilabel>:
2682 Used for the <guimenuitem>Import from MusicBrainz Fingerprint...</guimenuitem>
2683 function, which depends on
2684 the <ulink url="http://acoustid.org/chromaprint">Chromaprint</ulink>
2685 and <ulink url="http://libav.org/">libav</ulink> libraries.
2686 </para></listitem>
2687 </itemizedlist>
2688 <para>
2689 Plugins which are disabled will not be loaded. This can be used to optimize
2690 resource usage and startup time. The settings on this page take only effect
2691 after a restart of &kid3;.
2692 </para>
2693 </listitem>
2694 </varlistentry>
2695
2696 </variablelist>
2697 </para>
2698
2699 </sect1>
2700
2701 <sect1 id="help-menu">
2702 <title>The Help Menu</title>
2703 <para>
2704 <variablelist>
2705
2706 <varlistentry>
2707 <term><menuchoice>
2708 <guimenu>Help</guimenu>
2709 <guimenuitem>&kid3; Handbook</guimenuitem>
2710 </menuchoice></term>
2711 <listitem><para><action>Opens this handbook.</action></para></listitem>
2712 </varlistentry>
2713
2714 <varlistentry>
2715 <term><menuchoice>
2716 <guimenu>Help</guimenu>
2717 <guimenuitem>About &kid3;</guimenuitem>
2718 </menuchoice></term>
2719 <listitem><para><action>Displays a short information about &kid3;.
2720 </action></para></listitem>
2721 </varlistentry>
2722
2723
2724 </variablelist>
2725 </para>
2726
2727 </sect1>
2728
2729 </chapter>
2730
2731 <chapter id="kid3-cli">
2732 <title>kid3-cli</title>
2733 <sect1 id="kid3-cli-commands">
2734 <title>Commands</title>
2735 <para>
2736 <command>kid3-cli</command> offers a command-line-interface for &kid3;. If a
2737 folder path is used, the folder is opened. If one or more file paths are
2738 given, the common folder is opened and the files are selected. Subsequent
2739 commands will then work on these files. Commands are specified using
2740 <option>-c</option> options. If multiple commands are passed, they are
2741 executed in the given order. If files are modified by the commands, they will
2742 be saved at the end. If no command options are passed,
2743 <command>kid3-cli</command> starts in interactive mode. Commands can be
2744 entered and will operate on the current selection. The following sections
2745 list all available commands.
2746 </para>
2747
2748 <sect2 id="cli-help">
2749 <title>Help</title>
2750 <cmdsynopsis>
2751 <command>help</command>
2752 <arg><replaceable>COMMAND-NAME</replaceable></arg>
2753 </cmdsynopsis>
2754 <para>Displays help about the parameters of
2755 <replaceable>COMMAND-NAME</replaceable> or about all commands if no command
2756 name is given.
2757 </para>
2758 </sect2>
2759
2760 <sect2 id="cli-timeout">
2761 <title>Timeout</title>
2762 <cmdsynopsis>
2763 <command>timeout</command>
2764 <group>
2765 <arg choice="plain">default</arg>
2766 <arg choice="plain">off</arg>
2767 <arg choice="plain"><replaceable>TIME</replaceable></arg>
2768 </group>
2769 </cmdsynopsis>
2770 <para>Overwrite the default command timeout. The CLI commands abort after a
2771 command specific timeout is expired. This timeout is 10 seconds for
2772 <command>ls</command> and <command>albumart</command>, 60 seconds for
2773 <command>autoimport</command> and <command>filter</command>, and 3 seconds for
2774 all other commands. If a huge number of files has to be processed, these
2775 timeouts may be too restrictive, thus the timeout for all commands can be set
2776 to <replaceable>TIME</replaceable> ms, switched off altogether or be left at
2777 the default values.
2778 </para>
2779 </sect2>
2780
2781 <sect2 id="cli-exit">
2782 <title>Quit application</title>
2783 <cmdsynopsis>
2784 <command>exit</command>
2785 <arg>force</arg>
2786 </cmdsynopsis>
2787 <para>Exit application. If there are modified unsaved files, the <parameter
2788 class="command">force</parameter> parameter is required.
2789 </para>
2790 </sect2>
2791
2792 <sect2 id="cli-cd">
2793 <title>Change folder</title>
2794 <cmdsynopsis>
2795 <command>cd</command>
2796 <arg><replaceable>FOLDER</replaceable></arg>
2797 </cmdsynopsis>
2798 <para>If no <replaceable>FOLDER</replaceable> is given, change to the home
2799 folder. If a folder is given, change into the folder. If one or more
2800 file paths are given, change to their common folder and select the files.
2801 </para>
2802 </sect2>
2803
2804 <sect2 id="cli-pwd">
2805 <title>Print the filename of the current folder</title>
2806 <cmdsynopsis>
2807 <command>pwd</command>
2808 </cmdsynopsis>
2809 <para>Print the filename of the current working folder.</para>
2810 </sect2>
2811
2812 <sect2 id="cli-ls">
2813 <title>Folder list</title>
2814 <cmdsynopsis>
2815 <command>ls</command>
2816 </cmdsynopsis>
2817 <para>List the contents of the current folder. This corresponds to the file
2818 list in the &kid3; &GUI;. Five characters before the file names show the state
2819 of the file.
2820 </para>
2821
2822 <itemizedlist>
2823 <listitem><para><computeroutput>&gt;</computeroutput> File is selected.
2824 </para></listitem>
2825 <listitem><para><computeroutput>*</computeroutput> File is modified.
2826 </para></listitem>
2827 <listitem><para><computeroutput>1</computeroutput> File has a tag 1,
2828 otherwise '<computeroutput>-</computeroutput>' is displayed.</para></listitem>
2829 <listitem><para><computeroutput>2</computeroutput> File has a tag 2,
2830 otherwise '<computeroutput>-</computeroutput>' is displayed.</para></listitem>
2831 <listitem><para><computeroutput>3</computeroutput> File has a tag 3,
2832 otherwise '<computeroutput>-</computeroutput>' is displayed.</para></listitem>
2833 </itemizedlist>
2834
2835 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
2836 1-- 01 Intro.mp3
2837 > 12- 02 We Only Got This One.mp3
2838 *1-- 03 Outro.mp3</computeroutput></screen>
2839
2840 <para>In this example, all files have a tag 1, the second file also has a tag
2841 2 and it is selected. The third file is modified.
2842 </para>
2843 </sect2>
2844
2845 <sect2 id="cli-save">
2846 <title>Save the changed files</title>
2847 <cmdsynopsis>
2848 <command>save</command>
2849 </cmdsynopsis>
2850 <para>
2851 </para>
2852 </sect2>
2853
2854 <sect2 id="cli-select">
2855 <title>Select file</title>
2856 <cmdsynopsis>
2857 <command>select</command>
2858 <group>
2859 <arg choice="plain">all</arg>
2860 <arg choice="plain">none</arg>
2861 <arg choice="plain">first</arg>
2862 <arg choice="plain">previous</arg>
2863 <arg choice="plain">next</arg>
2864 <arg choice="plain" rep="repeat"><replaceable>FILE</replaceable></arg>
2865 </group>
2866 </cmdsynopsis>
2867 <para>To select all files, enter <userinput>select all</userinput>, to
2868 deselect all files, enter <userinput>select none</userinput>. To traverse the
2869 files in the current folder start with <userinput>select first</userinput>,
2870 then go forward using <userinput>select next</userinput> or backward using
2871 <userinput>select previous</userinput>. Specific files can be added to the
2872 current selection by giving their file names. Wildcards are possible, so
2873 <userinput>select *.mp3</userinput> will select all MP3 files in the current
2874 folder.
2875 </para>
2876
2877 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>select first</userinput>
2878 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
2879 > 1-- 01 Intro.mp3
2880 12- 02 We Only Got This One.mp3
2881 *1-- 03 Outro.mp3</computeroutput>
2882 <prompt>kid3-cli&gt; </prompt><userinput>select next</userinput>
2883 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
2884 1-- 01 Intro.mp3
2885 > 12- 02 We Only Got This One.mp3
2886 *1-- 03 Outro.mp3</computeroutput>
2887 <prompt>kid3-cli&gt; </prompt><userinput>select *.mp3</userinput>
2888 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
2889 > 1-- 01 Intro.mp3
2890 > 12- 02 We Only Got This One.mp3
2891 >*1-- 03 Outro.mp3</computeroutput></screen>
2892 </sect2>
2893
2894 <sect2 id="cli-tag">
2895 <title>Select tag</title>
2896 <cmdsynopsis>
2897 <command>tag</command>
2898 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
2899 </cmdsynopsis>
2900 <para>Many commands have an optional <replaceable>TAG-NUMBERS</replaceable>
2901 parameter, which specifies whether the command operates on tag 1, 2, or 3. If
2902 this parameter is omitted, the default tag numbers are used, which can be set
2903 by this command. At startup, it is set to <literal>12</literal> which means
2904 that information is read from tag 2 if available, else from tag 1;
2905 modifications are done on tag 2. The
2906 <option><replaceable>TAG-NUMBERS</replaceable></option> can be set to
2907 <userinput>1</userinput>, <userinput>2</userinput>, or
2908 <userinput>3</userinput> to operate only on the
2909 corresponding tag. If the parameter is omitted, the current setting is
2910 displayed.
2911 </para>
2912 </sect2>
2913
2914 <sect2 id="cli-get">
2915 <title>Get tag frame</title>
2916 <cmdsynopsis>
2917 <command>get</command>
2918 <group>
2919 <arg choice="plain">all</arg>
2920 <arg choice="plain"><replaceable>FRAME-NAME</replaceable></arg>
2921 </group>
2922 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
2923 </cmdsynopsis>
2924 <para>This command can be used to read the value of a specific tag frame or
2925 get information about all tag frames (if the argument is omitted or
2926 <option>all</option> is used). Modified frames are marked with a
2927 '<computeroutput>*</computeroutput>'.
2928 </para>
2929
2930 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>get</userinput><computeroutput>
2931 File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
2932 Name: 01 Intro.mp3
2933 Tag 1: ID3v1.1
2934 Title Intro
2935 Artist One Hit Wonder
2936 Album Let's Tag
2937 Date 2013
2938 Track Number 1
2939 Genre Pop</computeroutput>
2940 <prompt>kid3-cli&gt; </prompt><userinput>get title</userinput><computeroutput>
2941 Intro</computeroutput></screen>
2942 <para>To save the contents of a picture frame to a file, use
2943 <screen width="65"><userinput>get picture:'/path/to/folder.jpg'</userinput></screen>
2944 </para>
2945 <para>To save synchronized lyrics to an LRC file, use
2946 <screen width="65"><userinput>get SYLT:'/path/to/lyrics.lrc'</userinput></screen>
2947 </para>
2948 <para>It is possible to get only a specific field from a frame, for example
2949 <userinput>get POPM.Email</userinput> for the Email field of a Popularimeter
2950 frame. If a file has multiple frames of the same kind, the different frames
2951 can be indexed with brackets, for example the first performer from a Vorbis
2952 comment can be retrieved using <userinput>get performer[0]</userinput>,
2953 the second using <userinput>get performer[1]</userinput>.
2954 </para>
2955 <para>
2956 The pseudo field name "selected" can be used to check if a frame is selected,
2957 for example <userinput>get artist.selected</userinput> will return
2958 <computeroutput>1</computeroutput> if the artist frame is selected, else
2959 <computeroutput>0</computeroutput>.
2960 </para>
2961 <para>
2962 The pseudo frame name "ratingstars" can be used to get the value of the
2963 "rating" frame as the format specific value corresponding to the number of
2964 stars (0 to 5). When using "rating", the internal value is returned.
2965 </para>
2966 </sect2>
2967
2968 <sect2 id="cli-set">
2969 <title>Set tag frame</title>
2970 <cmdsynopsis>
2971 <command>set</command>
2972 <arg choice="req"><replaceable>FRAME-NAME</replaceable></arg>
2973 <arg choice="req"><replaceable>FRAME-VALUE</replaceable></arg>
2974 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
2975 </cmdsynopsis>
2976 <para>This command sets the value of a specific tag frame.
2977 If <replaceable>FRAME-VALUE</replaceable> is empty, the frame is deleted.
2978 </para>
2979 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>set remixer 'O.H. Wonder'</userinput></screen>
2980 <para>To set the contents of a picture frame from a file, use
2981 <screen width="65"><userinput>set picture:'/path/to/folder.jpg' 'Picture Description'</userinput></screen>
2982 </para>
2983 <para>To set synchronized lyrics from an LRC file, use
2984 <screen width="65"><userinput>set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'</userinput></screen>
2985 </para>
2986 <para>
2987 To set a specific field of a frame, the field name can be given after a dot,
2988 <abbrev>e.g.</abbrev> to set the Counter field of a Popularimeter frame, use
2989 <screen width="65"><userinput>set POPM.Counter 5</userinput></screen>
2990 </para>
2991 <para>
2992 An application for field specifications is the case where you want a custom
2993 TXXX frame with "rating" description instead of a standard Popularimeter frame
2994 (this seems to be used by some plugins). You can create such a TXXX rating
2995 frame with <command>kid3-cli</command>, however, you have to first create a
2996 TXXX frame with description "rating" and then set the value of this frame to
2997 the rating value.
2998 <screen width="65">
2999 <prompt>kid3-cli&gt; </prompt><userinput>set rating ""</userinput>
3000 <prompt>kid3-cli&gt; </prompt><userinput>set TXXX.Description rating</userinput>
3001 <prompt>kid3-cli&gt; </prompt><userinput>set rating 5</userinput>
3002 </screen>
3003 The first command will delete an existing POPM frame, because if such a frame
3004 exists, <userinput>set rating 5</userinput> would set the POPM frame and not
3005 the TXXX frame. Another possibility would be to use <userinput>set TXXX.Text
3006 5</userinput>, but this would only work if there is no other TXXX frame
3007 present.
3008 </para>
3009 <para>
3010 To set multiple frames of the same kind, an index can be given in brackets,
3011 <abbrev>e.g.</abbrev> to set multiple performers in a Vorbis comment, use
3012 <screen width="65">
3013 <prompt>kid3-cli&gt; </prompt><userinput>set performer[0] 'Liza don Getti (soprano)'</userinput>
3014 <prompt>kid3-cli&gt; </prompt><userinput>set performer[1] 'Joe Barr (piano)'</userinput>
3015 </screen>
3016 </para>
3017 <para>
3018 To select certain frames before a copy, paste or remove action, the pseudo
3019 field name "selected" can be used. Normally, all frames are selected, to
3020 deselect all, use <userinput>set '*.selected' 0</userinput>, then for example
3021 <userinput>set artist.selected 1</userinput> to select the artist frame.
3022 </para>
3023 <para>
3024 The pseudo frame name "ratingstars" can be used to set the value of the
3025 "rating" frame to the format specific value corresponding to the number of
3026 stars (0 to 5). The frame name "rating" can be used to set the internal
3027 value.
3028 </para>
3029 <para>
3030 Setting "ratingstars" on multiple files having different tag formats will not
3031 work because the frame with the value mapped from the star count is created
3032 for the first file and then used for all files. So instead of
3033 <userinput>kid3-cli -c "set ratingstars 2" *</userinput> you should rather use
3034 <userinput>for f in *; do kid3-cli -c "set ratingstars 2" "$f"; done</userinput>.
3035 </para>
3036 </sect2>
3037
3038 <sect2 id="cli-revert">
3039 <title>Revert</title>
3040 <cmdsynopsis>
3041 <command>revert</command>
3042 </cmdsynopsis>
3043 <para>Revert all modifications in the selected files (or all files if no files
3044 are selected).
3045 </para>
3046 </sect2>
3047
3048 <sect2 id="cli-import">
3049 <title>Import from file</title>
3050 <cmdsynopsis>
3051 <command>import</command>
3052 <arg choice="req"><replaceable>FILE</replaceable></arg>
3053 <arg choice="req"><replaceable>FORMAT-NAME</replaceable></arg>
3054 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
3055 </cmdsynopsis>
3056 <para>Tags are imported from the file <replaceable>FILE</replaceable>
3057 in the format with the name
3058 <replaceable>FORMAT-NAME</replaceable> (<abbrev>e.g.</abbrev> <userinput>"CSV
3059 unquoted"</userinput>, see <link linkend="import-text">Import</link>).
3060 </para>
3061 <para>If <userinput>tags</userinput> is given for
3062 <replaceable>FILE</replaceable>, tags are imported from other tags. Instead of
3063 <replaceable>FORMAT-NAME</replaceable> parameters
3064 <replaceable>SOURCE</replaceable> and <replaceable>EXTRACTION</replaceable>
3065 are required, see <link linkend="import-tags">Import from Tags</link>.
3066 To apply the import from tags on the selected files, use
3067 <userinput>tagsel</userinput> instead of <userinput>tags</userinput>.
3068 This function also supports output of the extracted value by using an
3069 <replaceable>EXTRACTION</replaceable> with the value
3070 <userinput>%{__return}(.+)</userinput>.
3071 </para>
3072 </sect2>
3073
3074 <sect2 id="cli-autoimport">
3075 <title>Automatic import</title>
3076 <cmdsynopsis>
3077 <command>autoimport</command>
3078 <arg><replaceable>PROFILE-NAME</replaceable></arg>
3079 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
3080 </cmdsynopsis>
3081 <para>Batch import using profile <replaceable>PROFILE-NAME</replaceable> (see
3082 <link linkend="batch-import">Automatic Import</link>,
3083 <userinput>"All"</userinput> is used if omitted).
3084 </para>
3085 </sect2>
3086
3087 <sect2 id="cli-albumart">
3088 <title>Download album cover artwork</title>
3089 <cmdsynopsis>
3090 <command>albumart</command>
3091 <arg choice="req"><replaceable>URL</replaceable></arg>
3092 <arg>all</arg>
3093 </cmdsynopsis>
3094 <para>Set the album artwork by downloading a picture from
3095 <replaceable>URL</replaceable>. The rules defined in the <link
3096 linkend="browse_pictures">Browse Cover Art</link> dialog are used to transform
3097 general &URL;s (<abbrev>e.g.</abbrev> from Amazon) to a picture &URL;. To set the album cover from
3098 a local picture file, use the <link linkend="cli-set">set</link> command.
3099 </para>
3100 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>albumart
3101 http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC</userinput></screen>
3102 </sect2>
3103
3104 <sect2 id="cli-export">
3105 <title>Export to file</title>
3106 <cmdsynopsis>
3107 <command>export</command>
3108 <arg choice="req"><replaceable>FILE</replaceable></arg>
3109 <arg choice="req"><replaceable>FORMAT-NAME</replaceable></arg>
3110 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
3111 </cmdsynopsis>
3112 <para>Tags are exported to file <replaceable>FILE</replaceable>
3113 in the format with the name
3114 <replaceable>FORMAT-NAME</replaceable> (<abbrev>e.g.</abbrev> <userinput>"CSV
3115 unquoted"</userinput>, see <link linkend="export">Export</link>).
3116 </para>
3117 </sect2>
3118
3119 <sect2 id="cli-playlist">
3120 <title>Create playlist</title>
3121 <cmdsynopsis>
3122 <command>playlist</command>
3123 </cmdsynopsis>
3124 <para>Create playlist in the format set in the configuration, see <link
3125 linkend="create-playlist">Create Playlist</link>.
3126 </para>
3127 </sect2>
3128
3129 <sect2 id="cli-filenameformat">
3130 <title>Apply filename format</title>
3131 <cmdsynopsis>
3132 <command>filenameformat</command>
3133 </cmdsynopsis>
3134 <para>Apply file name format set in the configuration, see <link linkend="apply-filename-format">Apply Filename Format</link>.
3135 </para>
3136 </sect2>
3137
3138 <sect2 id="cli-tagformat">
3139 <title>Apply tag format</title>
3140 <cmdsynopsis>
3141 <command>tagformat</command>
3142 </cmdsynopsis>
3143 <para>Apply tag name format set in the configuration, see <link linkend="apply-tag-format">Apply Tag Format</link>.
3144 </para>
3145 </sect2>
3146
3147 <sect2 id="cli-textencoding">
3148 <title>Apply text encoding</title>
3149 <cmdsynopsis>
3150 <command>textencoding</command>
3151 </cmdsynopsis>
3152 <para>Apply text encoding set in the configuration, see <link linkend="apply-text-encoding">Apply Text Encoding</link>.
3153 </para>
3154 </sect2>
3155
3156 <sect2 id="cli-renamedir">
3157 <title>Rename folder</title>
3158 <cmdsynopsis>
3159 <command>renamedir</command>
3160 <arg><replaceable>FORMAT</replaceable></arg>
3161 <group>
3162 <arg choice="plain">create</arg>
3163 <arg choice="plain">rename</arg>
3164 <arg choice="plain">dryrun</arg>
3165 </group>
3166 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
3167 </cmdsynopsis>
3168 <para>Rename or create folders from the values in the
3169 tags according to a given <replaceable>FORMAT</replaceable>
3170 (<abbrev>e.g.</abbrev> <userinput>%{artist} - %{album}</userinput>, see <link
3171 linkend="rename-directory">Rename Folder</link>), if no format is given,
3172 the format defined in the <guilabel>Rename folder</guilabel> dialog is
3173 used. The default mode is <option>rename</option>; to create folders,
3174 <option>create</option> must be given explicitly. The rename actions will be
3175 performed immediately, to just see what would be done, use the
3176 <option>dryrun</option> option.
3177 </para>
3178 </sect2>
3179
3180 <sect2 id="cli-numbertracks">
3181 <title>Number tracks</title>
3182 <cmdsynopsis>
3183 <command>numbertracks</command>
3184 <arg><replaceable>TRACK-NUMBER</replaceable></arg>
3185 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
3186 </cmdsynopsis>
3187 <para>Number the selected tracks starting with
3188 <replaceable>TRACK-NUMBER</replaceable> (<literal>1</literal> if omitted).
3189 </para>
3190 </sect2>
3191
3192 <sect2 id="cli-filter">
3193 <title>Filter</title>
3194 <cmdsynopsis>
3195 <command>filter</command>
3196 <group>
3197 <arg choice="plain"><replaceable>FILTER-NAME</replaceable></arg>
3198 <arg choice="plain"><replaceable>FILTER-FORMAT</replaceable></arg>
3199 </group>
3200 </cmdsynopsis>
3201 <para>Filter the files so that only the files matching the
3202 <replaceable>FILTER-FORMAT</replaceable> are visible. The name of a predefined
3203 filter expression (<abbrev>e.g.</abbrev> <userinput>"Filename Tag Mismatch"</userinput>) can be
3204 used instead of a filter expression, see <link linkend="filter">Filter</link>.
3205 </para>
3206
3207 <screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>filter '%{title} contains "tro"'</userinput><computeroutput>
3208 Started
3209 /home/urs/One Hit Wonder - Let's Tag
3210 + 01 Intro.mp3
3211 - 02 We Only Got This One.mp3
3212 + 03 Outro.mp3
3213 Finished</computeroutput>
3214 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
3215 1-- 01 Intro.mp3
3216 1-- 03 Outro.mp3</computeroutput>
3217 <prompt>kid3-cli&gt; </prompt><userinput>filter All</userinput><computeroutput>
3218 Started
3219 /home/urs/One Hit Wonder - Let's Tag
3220 + 01 Intro.mp3
3221 + 02 We Only Got This One.mp3
3222 + 03 Outro.mp3
3223 Finished</computeroutput>
3224 <prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
3225 1-- 01 Intro.mp3
3226 12- 02 We Only Got This One.mp3
3227 1-- 03 Outro.mp3</computeroutput></screen>
3228 </sect2>
3229
3230 <sect2 id="cli-to24">
3231 <title>Convert ID3v2.3 to ID3v2.4</title>
3232 <cmdsynopsis>
3233 <command>to24</command>
3234 </cmdsynopsis>
3235 </sect2>
3236
3237 <sect2 id="cli-to23">
3238 <title>Convert ID3v2.4 to ID3v2.3</title>
3239 <cmdsynopsis>
3240 <command>to23</command>
3241 </cmdsynopsis>
3242 </sect2>
3243
3244 <sect2 id="cli-fromtag">
3245 <title>Filename from tag</title>
3246 <cmdsynopsis>
3247 <command>fromtag</command>
3248 <arg><replaceable>FORMAT</replaceable></arg>
3249 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
3250 </cmdsynopsis>
3251 <para>Set the file names of the selected files from values in the tags, for
3252 example <userinput>fromtag '%{track} - %{title}' 1</userinput>. If no format
3253 is specified, the format set in the &GUI; is used.
3254 </para>
3255 </sect2>
3256
3257 <sect2 id="cli-totag">
3258 <title>Tag from filename</title>
3259 <cmdsynopsis>
3260 <command>totag</command>
3261 <arg><replaceable>FORMAT</replaceable></arg>
3262 <arg><replaceable>TAG-NUMBERS</replaceable></arg>
3263 </cmdsynopsis>
3264 <para>Set the tag frames from the file names, for example <userinput>totag
3265 '%{albumartist} - %{album}/%{track} %{title}' 2</userinput>. If no format
3266 is specified, the format set in the &GUI; is used. If the format
3267 of the filename does not match this pattern, a few other commonly used formats
3268 are tried.
3269 </para>
3270 </sect2>
3271
3272 <sect2 id="cli-syncto">
3273 <title>Tag to other tag</title>
3274 <cmdsynopsis>
3275 <command>syncto</command>
3276 <arg choice="req"><replaceable>TAG-NUMBER</replaceable></arg>
3277 </cmdsynopsis>
3278 <para>Copy the tag frames from one tag to the other tag, <abbrev>e.g.</abbrev> to set the ID3v2
3279 tag from the ID3v1 tag, use <userinput>syncto 2</userinput>.
3280 </para>
3281 </sect2>
3282
3283 <sect2 id="cli-copy">
3284 <title>Copy</title>
3285 <cmdsynopsis>
3286 <command>copy</command>
3287 <arg><replaceable>TAG-NUMBER</replaceable></arg>
3288 </cmdsynopsis>
3289 <para>Copy the tag frames of the selected file to the internal copy
3290 buffer. They can then be set on another file using the
3291 <command>paste</command> command.
3292 </para>
3293 <para>
3294 To copy only a subset of the frames, use the "selected" pseudo field with the
3295 <command>set</command> command. For example, to copy only the disc number and
3296 copyright frames, use
3297 <screen width="65">
3298 <userinput>set '*.selected' 0</userinput>
3299 <userinput>set discnumber.selected 1</userinput>
3300 <userinput>set copyright.selected 1</userinput>
3301 <userinput>copy</userinput>
3302 </screen>
3303 </para>
3304 </sect2>
3305
3306 <sect2 id="cli-paste">
3307 <title>Paste</title>
3308 <cmdsynopsis>
3309 <command>paste</command>
3310 <arg><replaceable>TAG-NUMBER</replaceable></arg>
3311 </cmdsynopsis>
3312 <para>Set tag frames from the contents of the <command>copy</command> buffer
3313 in the selected files.
3314 </para>
3315 </sect2>
3316
3317 <sect2 id="cli-remove">
3318 <title>Remove</title>
3319 <cmdsynopsis>
3320 <command>remove</command>
3321 <arg><replaceable>TAG-NUMBER</replaceable></arg>
3322 </cmdsynopsis>
3323 <para>Remove a tag.
3324 </para>
3325 <para>It is possible to remove only a subset of the frames by selecting them
3326 as described in the <link linkend="cli-copy"><command>copy</command>
3327 command</link>.
3328 </para>
3329 </sect2>
3330
3331 <sect2 id="cli-config">
3332 <title>Configure Kid3</title>
3333 <cmdsynopsis>
3334 <command>config</command>
3335 <arg><replaceable>OPTION</replaceable></arg>
3336 <arg><replaceable>VALUE</replaceable></arg>
3337 </cmdsynopsis>
3338 <para>Query or set a configuration option.
3339 </para>
3340 <para>The <replaceable>OPTION</replaceable> consists of a group name and a
3341 property name separated by a dot. When no <replaceable>OPTION</replaceable> is
3342 given, all available groups are displayed. If only a group name is given, all
3343 available properties of the group are displayed. For a given group and property,
3344 the currently configured value is displayed. To change the setting, the new
3345 value can be passed as a second argument.
3346 </para>
3347 <para>If the value of a setting is a list, all list elements have to be given
3348 as arguments. This means that to append an element to an existing list of
3349 elements, all existing elements have to be passed followed by the new element.
3350 In such a situation, it is easier to use the JSON mode, where the current
3351 list can be copied with the new element appended.
3352 </para>
3353 </sect2>
3354
3355 <sect2 id="cli-execute">
3356 <title>Execute program or QML script</title>
3357 <cmdsynopsis>
3358 <command>execute</command>
3359 <arg choice="opt">@qml</arg>
3360 <arg choice="req"><replaceable>FILE</replaceable></arg>
3361 <arg choice="opt"><replaceable>ARGS</replaceable></arg>
3362 </cmdsynopsis>
3363 <para>Execute a QML script or an executable.
3364 </para>
3365 <para>
3366 Without <option>@qml</option> a program is executed with arguments.
3367 When <option>@qml</option> is given as the first argument, the following
3368 arguments are the QML script and its arguments. For example, the tags
3369 of a folder can be exported to the file <filename>export.csv</filename> with
3370 the following command.
3371 </para>
3372 <screen width="65"><userinput>kid3-cli -c "execute @qml
3373 /usr/share/kid3/qml/script/ExportCsv.qml export.csv"
3374 /path/to/folder/</userinput></screen>
3375 <para>
3376 Here <option>export.csv</option> is the argument for the
3377 <filename>ExportCsv.qml</filename> script, whereas
3378 <option>/path/to/folder/</option> is the
3379 <option><replaceable>FILE</replaceable></option> argument for
3380 <command>kid3-cli</command>.
3381 </para>
3382 </sect2>
3383
3384 </sect1>
3385
3386 <sect1 id="kid3-cli-examples">
3387 <title>Examples</title>
3388 <para>Set title containing an apostrophe. Commands passed to
3389 <command>kid3-cli</command> with <parameter>-c</parameter>
3390 have to be in quotes if they do not only consist of a single word. If such a
3391 command itself has an argument containing spaces, that argument has to be
3392 quoted too. In &UNIX; shells single or double quotes can be used, but on the
3393 Windows Command Prompt, it is important that the outer quoting is done using
3394 double quotes and inside these quotes, single quotes are used. If the text
3395 inside the single quotes contains a single quote, it has to be escaped using a
3396 backslash character, as shown in the following example:</para>
3397 <screen width="65"><userinput>kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder</userinput></screen>
3398
3399 <para>Set album cover in all files of a folder using the batch import
3400 function:</para>
3401 <screen width="65"><userinput>kid3-cli -c "autoimport 'Cover Art'" /path/to/folder</userinput></screen>
3402
3403 <para>Remove comment frames and apply the tag format in both tags of all MP3
3404 files of a folder:</para>
3405 <screen width="65"><userinput>kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
3406 -c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3</userinput></screen>
3407
3408 <para>Automatically import tag 2, synchronize to tag 1, set file names from
3409 tag 2 and finally create a playlist:</para>
3410 <screen width="65"><userinput>kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
3411 /path/to/folder/*.mp3</userinput></screen>
3412
3413 <para>For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
3414 the arranger frame:</para>
3415 <screen width="65"><userinput>kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
3416 -c "set arranger ''" /path/to/folder</userinput></screen>
3417
3418 <para>This Python script uses <command>kid3-cli</command> to generate iTunes
3419 Sound Check iTunNORM frames from replay gain information.</para>
3420 <programlisting>
3421 <![CDATA[
3422 #!/usr/bin/env python3
3423 # Generate iTunes Sound Check from ReplayGain.
3424 import os, sys, subprocess
3425
3426 def rg2sc(dirpath):
3427 for root, dirs, files in os.walk(dirpath):
3428 for name in files:
3429 if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
3430 fn = os.path.join(root, name)
3431 rg = subprocess.check_output([
3432 'kid3-cli', '-c', 'get "replaygain_track_gain"',
3433 fn]).strip()
3434 if rg.endswith(b' dB'):
3435 rg = rg[:-3]
3436 try:
3437 rg = float(rg)
3438 except ValueError:
3439 print('Value %s of %s in not a float' % (rg, fn))
3440 continue
3441 sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
3442 subprocess.call([
3443 'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
3444
3445 if __name__ == '__main__':
3446 rg2sc(sys.argv[1])
3447 ]]>
3448 </programlisting>
3449 </sect1>
3450
3451 <sect1 id="kid3-cli-json">
3452 <title>&JSON; Format</title>
3453 <para>
3454 In order to make it easier to parse results from <command>kid3-cli</command>,
3455 it is possible to get the output in &JSON; format. When the request is in &JSON;
3456 format, the response will also be &JSON;. A compact format of the request will
3457 also give a compact representation of the response. If the request contains an
3458 "id" field, it is assumed to be a &JSON;-RPC request and the response will
3459 contain a "jsonrpc" field and the "id" of the request. The request format uses
3460 the same commands as the standard CLI, the "method" field contains the command
3461 and the parameters (if any) are given in the "params" list. The response
3462 contains a "result" object, which can also be null if the corresponding
3463 <command>kid3-cli</command> command does not return a result. In case of an
3464 error, an "error" object is returned with "code" and "message" fields as used
3465 in &JSON;-RPC.
3466
3467 <screen width="80">
3468 <prompt>kid3-cli&gt; </prompt><userinput>{"method":"set","params":["artist","An Artist"]}</userinput>
3469 <computeroutput>{"result":null}</computeroutput>
3470 <prompt>kid3-cli&gt; </prompt><userinput>{"method":"get","params":["artist",2]}</userinput>
3471 <computeroutput>{"result":"An Artist"}</computeroutput>
3472 <prompt>kid3-cli&gt; </prompt><userinput>{"method": "get", "params": ["artist"]}</userinput>
3473 <computeroutput>{
3474 "result": "An Artist"
3475 }
3476 </computeroutput>
3477 <prompt>kid3-cli&gt; </prompt><userinput>{"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}</userinput>
3478 <computeroutput>{"id":"123","jsonrpc":"2.0","result":"An Artist"}</computeroutput>
3479 </screen>
3480
3481 </para>
3482 </sect1>
3483
3484 </chapter>
3485
3486 <chapter id="credits">
3487
3488 <title>Credits and License</title>
3489
3490 <para>
3491 &kid3;
3492 </para>
3493 <para>
3494 Program written by Urs Fleisch <email>[email protected]</email>
3495 </para>
3496
3497 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
3498
3499 &underFDL;
3500 &underGPL;
3501
3502 </chapter>
3503
3504 <appendix id="installation">
3505 <title>Installation</title>
3506
3507 <sect1 id="getting-kid3">
3508 <title>How to obtain &kid3;</title>
3509
3510 <para>
3511 &kid3; can be found at
3512 <ulink url="https://kid3.kde.org">https://kid3.kde.org</ulink>.
3513 </para>
3514 </sect1>
3515
3516 <sect1 id="requirements">
3517 <title>Requirements</title>
3518
3519 <para>
3520 &kid3; needs <ulink url="https://www.qt.io">&Qt;</ulink>. <ulink
3521 url="http://www.kde.org">&kde;</ulink> is recommended but not necessary, as
3522 &kid3; can also be compiled as a &Qt; application. &kid3; can be compiled for
3523 systems where these libraries are available, <abbrev>e.g.</abbrev> for GNU/&Linux;, &Windows;
3524 and &macOS;.
3525
3526 To tag Ogg/Vorbis
3527 files, <ulink url="http://xiph.org/ogg/">libogg</ulink>,
3528 <ulink url="http://xiph.org/vorbis/">libvorbis and libvorbisfile</ulink> are
3529 required, for FLAC files <ulink url="http://flac.sourceforge.net">libFLAC++
3530 and libFLAC</ulink>.
3531 <ulink url="http://id3lib.sourceforge.net">id3lib</ulink> is used for MP3
3532 files.
3533 These four formats are also supported by
3534 <ulink url="http://taglib.github.io/">TagLib</ulink>,
3535 which can also handle Opus, MPC, APE, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF
3536 files and tracker modules.
3537 To import from acoustic fingerprints,
3538 <ulink url="http://acoustid.org/chromaprint">Chromaprint</ulink>
3539 and <ulink url="http://libav.org/">libav</ulink> are used.
3540 </para>
3541 <para>
3542 &kid3; is available for most &Linux; distributions, &Windows; and &macOS;.
3543 Links can be found on <ulink url="https://kid3.kde.org">
3544 https://kid3.kde.org</ulink>.
3545 </para>
3546
3547 </sect1>
3548
3549 <sect1 id="compilation">
3550 <title>Compilation and Installation</title>
3551
3552 <para>
3553 You can compile &kid3; with or without &kde;. Without &kde;, &kid3; is a
3554 simple &Qt; application and lacks some configuration and session features.
3555 </para>
3556 <para>
3557 For a &kde; version, go into the top folder and type
3558 <screen width="40">
3559 <prompt>%</prompt> <userinput>cmake .</userinput>
3560 <prompt>%</prompt> <userinput>make</userinput>
3561 <prompt>%</prompt> <userinput>make install</userinput>
3562 </screen>
3563 </para>
3564 <para>
3565 To compile for different versions of &Qt; or &kde;, set the corresponding
3566 <userinput>cmake</userinput> options.
3567 </para>
3568 <para>
3569 If not all libraries are present, &kid3; is built with reduced functionality.
3570 So you should take care to have all desired development packages installed.
3571 On the other side, <userinput>cmake</userinput>-options control which
3572 libraries are compiled in. The default is
3573 <userinput>-DWITH_TAGLIB:BOOL=ON -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON
3574 -DWITH_CHROMAPRINT:BOOL=ON -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON
3575 </userinput>. These options can be disabled using
3576 <userinput>OFF</userinput>.
3577 </para>
3578 <para>
3579 To build &kid3; as a &Qt; application without &kde;, use the
3580 <userinput>cmake</userinput> option <userinput>-DWITH_APPS=Qt</userinput>.
3581 To build both a &kde; and a &Qt; application, set
3582 <userinput>-DWITH_APPS="Qt;KDE"</userinput>.
3583 </para>
3584 <para>
3585 To use a specific &Qt; installation, set
3586 <userinput>-DQT_QMAKE_EXECUTABLE=/path/to/qmake</userinput>.
3587 </para>
3588 <para>
3589 Generation of RPM-Packages is supported by the
3590 file <filename>kid3.spec</filename>, for &Debian; Packages,
3591 run <userinput>build.sh deb</userinput>.
3592 </para>
3593
3594 <para>
3595 The &Qt; application can also be compiled for &Windows; and &macOS;.
3596 The script <filename>build.sh</filename> can be used to download
3597 and build all required libraries and create a &kid3; package.
3598 </para>
3599
3600 </sect1>
3601
3602 <sect1 id="configuration">
3603 <title>Configuration</title>
3604
3605 <para>With &kde;, the settings are stored in
3606 <filename>.config/kid3rc</filename>,
3607 the application state in <filename>.local/share/kid3/kid3staterc</filename>.
3608 As a &Qt; application, this file is
3609 in <filename>.config/Kid3/Kid3.conf</filename>. On &Windows;,
3610 the configuration is stored in the registry. on &macOS; in a plist file.
3611 </para>
3612 <para>The environment variable <varname>KID3_CONFIG_FILE</varname> can be used
3613 to set the path of the configuration file.</para>
3614
3615 </sect1>
3616
3617 </appendix>
3618
3619 <appendix id="dbus-interface">
3620 <title>&DBus; Interface</title>
3621
3622 <sect1 id="dbus-examples">
3623 <title>&DBus; Examples</title>
3624
3625 <para>
3626 On &Linux; a &DBus;-interface can be used to control
3627 &kid3; by scripts. Scripts can be written in any language with &DBus;-bindings
3628 (<abbrev>e.g.</abbrev> in Python) and can be added to the <guilabel>User Actions</guilabel> to
3629 extend the functionality of &kid3;.
3630 </para>
3631
3632 <para>
3633 The artist in tag 2 of the current file can be set to the value "One Hit Wonder"
3634 with the following code:
3635 </para>
3636
3637 <variablelist>
3638 <varlistentry><term>Shell</term>
3639 <listitem>
3640 <programlisting>
3641 dbus-send --dest=org.kde.kid3 --print-reply=literal \
3642 /Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
3643 string:'One Hit Wonder'
3644 </programlisting>
3645 <para>
3646 or easier with &Qt;'s <command>qdbus</command> (<command>qdbusviewer</command>
3647 can be used to explore the interface in a &GUI;):
3648 </para>
3649 <programlisting>
3650 qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
3651 'One Hit Wonder'
3652 </programlisting>
3653 </listitem>
3654 </varlistentry>
3655 <varlistentry><term>Python</term>
3656 <listitem>
3657 <programlisting>
3658 import dbus
3659 kid3 = dbus.SessionBus().get_object(
3660 'org.kde.kid3', '/Kid3')
3661 kid3.setFrame(2, 'Artist', 'One Hit Wonder')
3662 </programlisting>
3663 </listitem>
3664 </varlistentry>
3665 <varlistentry><term>Perl</term>
3666 <listitem>
3667 <programlisting>
3668 use Net::DBus;
3669 $kid3 = Net::DBus->session->get_service(
3670 "org.kde.kid3")->get_object(
3671 "/Kid3", "org.kde.Kid3");
3672 $kid3->setFrame(2, "Artist", "One Hit Wonder");
3673 </programlisting>
3674 </listitem>
3675 </varlistentry>
3676 </variablelist>
3677 </sect1>
3678
3679 <sect1 id="dbus-api">
3680 <title>&DBus; API</title>
3681
3682 <para>
3683 The &DBus; API is specified
3684 in <filename>org.kde.Kid3.xml</filename>. The &kid3; interface has the
3685 following methods:
3686 </para>
3687
3688 <sect2 id="dbus-openDirectory">
3689 <title>Open file or folder</title>
3690 <funcsynopsis>
3691 <funcprototype>
3692 <funcdef>boolean <function>openDirectory</function></funcdef>
3693 <paramdef>string <parameter>path</parameter></paramdef>
3694 </funcprototype>
3695 </funcsynopsis>
3696 <variablelist>
3697 <varlistentry>
3698 <term><replaceable>path</replaceable></term>
3699 <listitem><para>path to file or folder</para></listitem>
3700 </varlistentry>
3701 </variablelist>
3702 <para>Returns true if OK.</para>
3703 </sect2>
3704
3705 <sect2 id="dbus-unloadAllTags">
3706 <title>Unload the tags of all files which are not modified or selected</title>
3707 <funcsynopsis>
3708 <funcprototype>
3709 <funcdef><function>unloadAllTags</function></funcdef>
3710 <void/>
3711 </funcprototype>
3712 </funcsynopsis>
3713 </sect2>
3714
3715 <sect2 id="dbus-save">
3716 <title>Save all modified files</title>
3717 <funcsynopsis>
3718 <funcprototype>
3719 <funcdef>boolean <function>save</function></funcdef>
3720 <void/>
3721 </funcprototype>
3722 </funcsynopsis>
3723 <para>Returns true if OK.</para>
3724 </sect2>
3725
3726 <sect2 id="dbus-getErrorMessage">
3727 <title>Get a detailed error message provided by some methods</title>
3728 <funcsynopsis>
3729 <funcprototype>
3730 <funcdef>string <function>getErrorMessage</function></funcdef>
3731 <void/>
3732 </funcprototype>
3733 </funcsynopsis>
3734 <para>Returns detailed error message.</para>
3735 </sect2>
3736
3737 <sect2 id="dbus-revert">
3738 <title>Revert changes in the selected files</title>
3739 <funcsynopsis>
3740 <funcprototype>
3741 <funcdef><function>revert</function></funcdef>
3742 <void/>
3743 </funcprototype>
3744 </funcsynopsis>
3745 </sect2>
3746
3747 <sect2 id="dbus-batchImport">
3748 <title>Start an automatic batch import</title>
3749 <funcsynopsis>
3750 <funcprototype>
3751 <funcdef>boolean <function>batchImport</function></funcdef>
3752 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
3753 <paramdef>string <parameter>profileName</parameter></paramdef>
3754 </funcprototype>
3755 </funcsynopsis>
3756 <variablelist>
3757 <varlistentry>
3758 <term><replaceable>tagMask</replaceable></term>
3759 <listitem><para>tag mask (bit 0 for tag 1, bit 1 for tag 2)</para></listitem>
3760 </varlistentry>
3761 <varlistentry>
3762 <term><replaceable>profileName</replaceable></term>
3763 <listitem><para>name of batch import profile to use</para></listitem>
3764 </varlistentry>
3765 </variablelist>
3766 </sect2>
3767
3768 <sect2 id="dbus-importFromFile">
3769 <title>Import tags from a file</title>
3770 <funcsynopsis>
3771 <funcprototype>
3772 <funcdef>boolean <function>importFromFile</function></funcdef>
3773 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
3774 <paramdef>string <parameter>path</parameter></paramdef>
3775 <paramdef>int32 <parameter>fmtIdx</parameter></paramdef>
3776 </funcprototype>
3777 </funcsynopsis>
3778 <variablelist>
3779 <varlistentry>
3780 <term><replaceable>tagMask</replaceable></term>
3781 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
3782 </varlistentry>
3783 <varlistentry>
3784 <term><replaceable>path</replaceable></term>
3785 <listitem><para>path of file</para></listitem>
3786 </varlistentry>
3787 <varlistentry>
3788 <term><replaceable>fmtIdx</replaceable></term>
3789 <listitem><para>index of format</para></listitem>
3790 </varlistentry>
3791 </variablelist>
3792 <para>Returns true if OK.</para>
3793 </sect2>
3794
3795 <sect2 id="dbus-importFromTags">
3796 <title>Import tags from other tags</title>
3797 <funcsynopsis>
3798 <funcprototype>
3799 <funcdef><function>importFromTags</function></funcdef>
3800 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
3801 <paramdef>string <parameter>source</parameter></paramdef>
3802 <paramdef>string <parameter>extraction</parameter></paramdef>
3803 </funcprototype>
3804 </funcsynopsis>
3805 <variablelist>
3806 <varlistentry>
3807 <term><replaceable>tagMask</replaceable></term>
3808 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
3809 </varlistentry>
3810 <varlistentry>
3811 <term><replaceable>source</replaceable></term>
3812 <listitem><para>format to get source text from tags</para></listitem>
3813 </varlistentry>
3814 <varlistentry>
3815 <term><replaceable>extraction</replaceable></term>
3816 <listitem><para>regular expression with frame names and captures to
3817 extract from source text</para></listitem>
3818 </varlistentry>
3819 </variablelist>
3820 </sect2>
3821
3822 <sect2 id="dbus-importFromTagsToSelection">
3823 <title>Import tags from other tags on selected files</title>
3824 <funcsynopsis>
3825 <funcprototype>
3826 <funcdef>array <function>importFromTagsToSelection</function></funcdef>
3827 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
3828 <paramdef>string <parameter>source</parameter></paramdef>
3829 <paramdef>string <parameter>extraction</parameter></paramdef>
3830 </funcprototype>
3831 </funcsynopsis>
3832 <variablelist>
3833 <varlistentry>
3834 <term><replaceable>tagMask</replaceable></term>
3835 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
3836 </varlistentry>
3837 <varlistentry>
3838 <term><replaceable>source</replaceable></term>
3839 <listitem><para>format to get source text from tags</para></listitem>
3840 </varlistentry>
3841 <varlistentry>
3842 <term><replaceable>extraction</replaceable></term>
3843 <listitem><para>regular expression with frame names and captures to
3844 extract from source text</para></listitem>
3845 </varlistentry>
3846 </variablelist>
3847 <variablelist>
3848 <varlistentry>
3849 <term><replaceable>returnValues</replaceable></term>
3850 <listitem><para>extracted value for "%{__return}(.+)"</para></listitem>
3851 </varlistentry>
3852 </variablelist>
3853 </sect2>
3854
3855 <sect2 id="dbus-downloadAlbumArt">
3856 <title>Download album cover art</title>
3857 <funcsynopsis>
3858 <funcprototype>
3859 <funcdef><function>downloadAlbumArt</function></funcdef>
3860 <paramdef>string <parameter>url</parameter></paramdef>
3861 <paramdef>boolean <parameter>allFilesInDir</parameter></paramdef>
3862 </funcprototype>
3863 </funcsynopsis>
3864 <variablelist>
3865 <varlistentry>
3866 <term><replaceable>url</replaceable></term>
3867 <listitem><para>&URL; of picture file or album art
3868 resource</para></listitem>
3869 </varlistentry>
3870 <varlistentry>
3871 <term><replaceable>allFilesInDir</replaceable></term>
3872 <listitem><para>true to add the image to all files in the
3873 folder</para></listitem>
3874 </varlistentry>
3875 </variablelist>
3876 </sect2>
3877
3878 <sect2 id="dbus-exportToFile">
3879 <title>Export tags to a file</title>
3880 <funcsynopsis>
3881 <funcprototype>
3882 <funcdef>boolean <function>exportToFile</function></funcdef>
3883 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
3884 <paramdef>string <parameter>path</parameter></paramdef>
3885 <paramdef>int32 <parameter>fmtIdx</parameter></paramdef>
3886 </funcprototype>
3887 </funcsynopsis>
3888 <variablelist>
3889 <varlistentry>
3890 <term><replaceable>tagMask</replaceable></term>
3891 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
3892 </varlistentry>
3893 <varlistentry>
3894 <term><replaceable>path</replaceable></term>
3895 <listitem><para>path of file</para></listitem>
3896 </varlistentry>
3897 <varlistentry>
3898 <term><replaceable>fmtIdx</replaceable></term>
3899 <listitem><para>index of format</para></listitem>
3900 </varlistentry>
3901 </variablelist>
3902 <para>Returns true if OK.</para>
3903 </sect2>
3904
3905 <sect2 id="dbus-createPlaylist">
3906 <title>Create a playlist</title>
3907 <funcsynopsis>
3908 <funcprototype>
3909 <funcdef>boolean <function>createPlaylist</function></funcdef>
3910 <void/>
3911 </funcprototype>
3912 </funcsynopsis>
3913 <para>Returns true if OK.</para>
3914 </sect2>
3915
3916 <sect2 id="dbus-getPlaylistItems">
3917 <title>Get items of a playlist</title>
3918 <funcsynopsis>
3919 <funcprototype>
3920 <funcdef>array <function>getPlaylistItems</function></funcdef>
3921 <paramdef>string <parameter>path</parameter></paramdef>
3922 </funcprototype>
3923 </funcsynopsis>
3924 <variablelist>
3925 <varlistentry>
3926 <term><replaceable>path</replaceable></term>
3927 <listitem><para>path to playlist file</para></listitem>
3928 </varlistentry>
3929 </variablelist>
3930 <para>Returns list of absolute paths to playlist items.</para>
3931 </sect2>
3932
3933 <sect2 id="dbus-setPlaylistItems">
3934 <title>Set items of a playlist</title>
3935 <funcsynopsis>
3936 <funcprototype>
3937 <funcdef>boolean <function>setPlaylistItems</function></funcdef>
3938 <paramdef>string <parameter>path</parameter></paramdef>
3939 <paramdef>array <parameter>items</parameter></paramdef>
3940 </funcprototype>
3941 </funcsynopsis>
3942 <variablelist>
3943 <varlistentry>
3944 <term><replaceable>path</replaceable></term>
3945 <listitem><para>path to playlist file</para></listitem>
3946 </varlistentry>
3947 <varlistentry>
3948 <term><replaceable>items</replaceable></term>
3949 <listitem><para>list of absolute paths to playlist items</para></listitem>
3950 </varlistentry>
3951 </variablelist>
3952 <para>Returns true if OK, false if not all items were found and added or
3953 saving failed.</para>
3954 </sect2>
3955
3956 <sect2 id="dbus-quit">
3957 <title>Quit the application</title>
3958 <funcsynopsis>
3959 <funcprototype>
3960 <funcdef><function>quit</function></funcdef>
3961 <void/>
3962 </funcprototype>
3963 </funcsynopsis>
3964 </sect2>
3965
3966 <sect2 id="dbus-selectAll">
3967 <title>Select all files</title>
3968 <funcsynopsis>
3969 <funcprototype>
3970 <funcdef><function>selectAll</function></funcdef>
3971 <void/>
3972 </funcprototype>
3973 </funcsynopsis>
3974 </sect2>
3975
3976 <sect2 id="dbus-deselectAll">
3977 <title>Deselect all files</title>
3978 <funcsynopsis>
3979 <funcprototype>
3980 <funcdef><function>deselectAll</function></funcdef>
3981 <void/>
3982 </funcprototype>
3983 </funcsynopsis>
3984 </sect2>
3985
3986 <sect2 id="dbus-firstFile">
3987 <title>Set the first file as the current file</title>
3988 <funcsynopsis>
3989 <funcprototype>
3990 <funcdef>boolean <function>firstFile</function></funcdef>
3991 <void/>
3992 </funcprototype>
3993 </funcsynopsis>
3994 <para>Returns true if there is a first file.</para>
3995 </sect2>
3996
3997 <sect2 id="dbus-previousFile">
3998 <title>Set the previous file as the current file</title>
3999 <funcsynopsis>
4000 <funcprototype>
4001 <funcdef>boolean <function>previousFile</function></funcdef>
4002 <void/>
4003 </funcprototype>
4004 </funcsynopsis>
4005 <para>Returns true if there is a previous file.</para>
4006 </sect2>
4007
4008 <sect2 id="dbus-nextFile">
4009 <title>Set the next file as the current file</title>
4010 <funcsynopsis>
4011 <funcprototype>
4012 <funcdef>boolean <function>nextFile</function></funcdef>
4013 <void/>
4014 </funcprototype>
4015 </funcsynopsis>
4016 <para>Returns true if there is a next file.</para>
4017 </sect2>
4018
4019 <sect2 id="dbus-selectFirstFile">
4020 <title>Select the first file</title>
4021 <funcsynopsis>
4022 <funcprototype>
4023 <funcdef>boolean <function>selectFirstFile</function></funcdef>
4024 <void/>
4025 </funcprototype>
4026 </funcsynopsis>
4027 <para>Returns true if there is a first file.</para>
4028 </sect2>
4029
4030 <sect2 id="dbus-selectPreviousFile">
4031 <title>Select the previous file</title>
4032 <funcsynopsis>
4033 <funcprototype>
4034 <funcdef>boolean <function>selectPreviousFile</function></funcdef>
4035 <void/>
4036 </funcprototype>
4037 </funcsynopsis>
4038 <para>Returns true if there is a previous file.</para>
4039 </sect2>
4040
4041 <sect2 id="dbus-selectNextFile">
4042 <title>Select the next file</title>
4043 <funcsynopsis>
4044 <funcprototype>
4045 <funcdef>boolean <function>selectNextFile</function></funcdef>
4046 <void/>
4047 </funcprototype>
4048 </funcsynopsis>
4049 <para>Returns true if there is a next file.</para>
4050 </sect2>
4051
4052 <sect2 id="dbus-selectCurrentFile">
4053 <title>Select the current file</title>
4054 <funcsynopsis>
4055 <funcprototype>
4056 <funcdef>boolean <function>selectCurrentFile</function></funcdef>
4057 <void/>
4058 </funcprototype>
4059 </funcsynopsis>
4060 <para>Returns true if there is a current file.</para>
4061 </sect2>
4062
4063 <sect2 id="dbus-expandDirectory">
4064 <title>Expand or collapse the current file item if it is a folder</title>
4065 <funcsynopsis>
4066 <funcprototype>
4067 <funcdef>boolean <function>expandDirectory</function></funcdef>
4068 <void/>
4069 </funcprototype>
4070 </funcsynopsis>
4071 <para>A file list item is a folder if getFileName() returns a name with
4072 '/' as the last character.</para>
4073 <para>Returns true if current file item is a folder.</para>
4074 </sect2>
4075
4076 <sect2 id="dbus-applyFilenameFormat">
4077 <title>Apply the file name format</title>
4078 <funcsynopsis>
4079 <funcprototype>
4080 <funcdef><function>applyFilenameFormat</function></funcdef>
4081 <void/>
4082 </funcprototype>
4083 </funcsynopsis>
4084 </sect2>
4085
4086 <sect2 id="dbus-applyTagFormat">
4087 <title>Apply the tag format</title>
4088 <funcsynopsis>
4089 <funcprototype>
4090 <funcdef><function>applyTagFormat</function></funcdef>
4091 <void/>
4092 </funcprototype>
4093 </funcsynopsis>
4094 </sect2>
4095
4096 <sect2 id="dbus-applyTextEncoding">
4097 <title>Apply text encoding</title>
4098 <funcsynopsis>
4099 <funcprototype>
4100 <funcdef><function>applyTextEncoding</function></funcdef>
4101 <void/>
4102 </funcprototype>
4103 </funcsynopsis>
4104 </sect2>
4105
4106 <sect2 id="dbus-setDirNameFromTag">
4107 <title>Set the folder name from the tags</title>
4108 <funcsynopsis>
4109 <funcprototype>
4110 <funcdef>boolean <function>setDirNameFromTag</function></funcdef>
4111 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4112 <paramdef>string <parameter>format</parameter></paramdef>
4113 <paramdef>boolean <parameter>create</parameter></paramdef>
4114 </funcprototype>
4115 </funcsynopsis>
4116 <variablelist>
4117 <varlistentry>
4118 <term><replaceable>tagMask</replaceable></term>
4119 <listitem><para>tag mask (bit 0 for tag 1, bit 1 for tag 2)</para></listitem>
4120 </varlistentry>
4121 <varlistentry>
4122 <term><replaceable>format</replaceable></term>
4123 <listitem><para>folder name format</para></listitem>
4124 </varlistentry>
4125 <varlistentry>
4126 <term><replaceable>create</replaceable></term>
4127 <listitem><para>true to create, false to rename</para></listitem>
4128 </varlistentry>
4129 </variablelist>
4130 <para>Returns true if OK, else the error message is available using getErrorMessage().</para>
4131 </sect2>
4132
4133 <sect2 id="dbus-numberTracks">
4134 <title>Set subsequent track numbers in the selected files</title>
4135 <funcsynopsis>
4136 <funcprototype>
4137 <funcdef><function>numberTracks</function></funcdef>
4138 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4139 <paramdef>int32 <parameter>firstTrackNr</parameter></paramdef>
4140 </funcprototype>
4141 </funcsynopsis>
4142 <variablelist>
4143 <varlistentry>
4144 <term><replaceable>tagMask</replaceable></term>
4145 <listitem><para>tag mask (bit 0 for tag 1, bit 1 for tag 2)</para></listitem>
4146 </varlistentry>
4147 <varlistentry>
4148 <term><replaceable>firstTrackNr</replaceable></term>
4149 <listitem><para>number to use for first file</para></listitem>
4150 </varlistentry>
4151 </variablelist>
4152 </sect2>
4153
4154 <sect2 id="dbus-filter">
4155 <title>Filter the files</title>
4156 <funcsynopsis>
4157 <funcprototype>
4158 <funcdef><function>filter</function></funcdef>
4159 <paramdef>string <parameter>expression</parameter></paramdef>
4160 </funcprototype>
4161 </funcsynopsis>
4162 <variablelist>
4163 <varlistentry>
4164 <term><replaceable>expression</replaceable></term>
4165 <listitem><para>filter expression</para></listitem>
4166 </varlistentry>
4167 </variablelist>
4168 </sect2>
4169
4170 <sect2 id="dbus-convertToId3v24">
4171 <title>Convert ID3v2.3 tags to ID3v2.4</title>
4172 <funcsynopsis>
4173 <funcprototype>
4174 <funcdef><function>convertToId3v24</function></funcdef>
4175 <void/>
4176 </funcprototype>
4177 </funcsynopsis>
4178 </sect2>
4179
4180 <sect2 id="dbus-convertToId3v23">
4181 <title>Convert ID3v2.4 tags to ID3v2.3</title>
4182 <funcsynopsis>
4183 <funcprototype>
4184 <funcdef><function>convertToId3v23</function></funcdef>
4185 <void/>
4186 </funcprototype>
4187 </funcsynopsis>
4188 <para>Returns true if OK.</para>
4189 </sect2>
4190
4191 <sect2 id="dbus-getDirectoryName">
4192 <title>Get path of folder</title>
4193 <funcsynopsis>
4194 <funcprototype>
4195 <funcdef>string <function>getDirectoryName</function></funcdef>
4196 <void/>
4197 </funcprototype>
4198 </funcsynopsis>
4199 <para>Returns absolute path of folder.</para>
4200 </sect2>
4201
4202 <sect2 id="dbus-getFileName">
4203 <title>Get name of current file</title>
4204 <funcsynopsis>
4205 <funcprototype>
4206 <funcdef>string <function>getFileName</function></funcdef>
4207 <void/>
4208 </funcprototype>
4209 </funcsynopsis>
4210 <para>Returns true absolute file name, ends with "/" if it is a folder.</para>
4211 </sect2>
4212
4213 <sect2 id="dbus-setFileName">
4214 <title>Set name of selected file</title>
4215 <funcsynopsis>
4216 <funcprototype>
4217 <funcdef><function>setFileName</function></funcdef>
4218 <paramdef>string <parameter>name</parameter></paramdef>
4219 </funcprototype>
4220 </funcsynopsis>
4221 <variablelist>
4222 <varlistentry>
4223 <term><replaceable>name</replaceable></term>
4224 <listitem><para>file name</para></listitem>
4225 </varlistentry>
4226 </variablelist>
4227 <para>The file will be renamed when the folder is saved.</para>
4228 </sect2>
4229
4230 <sect2 id="dbus-setFileNameFormat">
4231 <title>Set format to use when setting the filename from the tags</title>
4232 <funcsynopsis>
4233 <funcprototype>
4234 <funcdef><function>setFileNameFormat</function></funcdef>
4235 <paramdef>string <parameter>format</parameter></paramdef>
4236 </funcprototype>
4237 </funcsynopsis>
4238 <variablelist>
4239 <varlistentry>
4240 <term><replaceable>format</replaceable></term>
4241 <listitem><para>file name format</para></listitem>
4242 </varlistentry>
4243 </variablelist>
4244 </sect2>
4245
4246 <sect2 id="dbus-setFileNameFromTag">
4247 <title>Set the file names of the selected files from the tags</title>
4248 <funcsynopsis>
4249 <funcprototype>
4250 <funcdef><function>setFileNameFromTag</function></funcdef>
4251 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4252 </funcprototype>
4253 </funcsynopsis>
4254 <variablelist>
4255 <varlistentry>
4256 <term><replaceable>tagMask</replaceable></term>
4257 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4258 </varlistentry>
4259 </variablelist>
4260 </sect2>
4261
4262 <sect2 id="dbus-getFrame">
4263 <title>Get value of frame</title>
4264 <funcsynopsis>
4265 <funcprototype>
4266 <funcdef>string <function>getFrame</function></funcdef>
4267 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4268 <paramdef>string <parameter>name</parameter></paramdef>
4269 </funcprototype>
4270 </funcsynopsis>
4271 <variablelist>
4272 <varlistentry>
4273 <term><replaceable>tagMask</replaceable></term>
4274 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4275 </varlistentry>
4276 <varlistentry>
4277 <term><replaceable>name</replaceable></term>
4278 <listitem><para>name of frame (<abbrev>e.g.</abbrev> "artist")</para></listitem>
4279 </varlistentry>
4280 </variablelist>
4281 <para>To get binary data like a picture, the name of a file to write can be
4282 added after the <parameter>name</parameter>, <abbrev>e.g.</abbrev> "Picture:/path/to/file".
4283 In the same way, synchronized lyrics can be exported, <abbrev>e.g.</abbrev> "SYLT:/path/to/file".
4284 </para>
4285 <para>Returns value of frame.</para>
4286 </sect2>
4287
4288 <sect2 id="dbus-setFrame">
4289 <title>Set value of frame</title>
4290 <funcsynopsis>
4291 <funcprototype>
4292 <funcdef>boolean <function>setFrame</function></funcdef>
4293 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4294 <paramdef>string <parameter>name</parameter></paramdef>
4295 <paramdef>string <parameter>value</parameter></paramdef>
4296 </funcprototype>
4297 </funcsynopsis>
4298 <variablelist>
4299 <varlistentry>
4300 <term><replaceable>tagMask</replaceable></term>
4301 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4302 </varlistentry>
4303 <varlistentry>
4304 <term><replaceable>name</replaceable></term>
4305 <listitem><para>name of frame (<abbrev>e.g.</abbrev> "artist")</para></listitem>
4306 </varlistentry>
4307 <varlistentry>
4308 <term><replaceable>value</replaceable></term>
4309 <listitem><para>value of frame</para></listitem>
4310 </varlistentry>
4311 </variablelist>
4312 <para>For tag 2 (<parameter>tagMask</parameter> 2), if no frame with <parameter>name</parameter> exists, a new frame
4313 is added, if <parameter>value</parameter> is empty, the frame is deleted.
4314 To add binary data like a picture, a file can be added after the
4315 <parameter>name</parameter>, <abbrev>e.g.</abbrev> "Picture:/path/to/file".
4316 "SYLT:/path/to/file" can be used to import synchronized lyrics.</para>
4317 <para>Returns true if OK.</para>
4318 </sect2>
4319
4320 <sect2 id="dbus-getTag">
4321 <title>Get all frames of a tag</title>
4322 <funcsynopsis>
4323 <funcprototype>
4324 <funcdef>array of string <function>getTag</function></funcdef>
4325 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4326 </funcprototype>
4327 </funcsynopsis>
4328 <variablelist>
4329 <varlistentry>
4330 <term><replaceable>tagMask</replaceable></term>
4331 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4332 </varlistentry>
4333 </variablelist>
4334 <para>Returns list with alternating frame names and values.</para>
4335 </sect2>
4336
4337 <sect2 id="dbus-getInformation">
4338 <title>Get technical information about file</title>
4339 <funcsynopsis>
4340 <funcprototype>
4341 <funcdef>array of string <function>getInformation</function></funcdef>
4342 <void/>
4343 </funcprototype>
4344 </funcsynopsis>
4345 <para>Properties are Format, Bitrate, Samplerate, Channels, Duration,
4346 Channel Mode, VBR, Tag 1, Tag 2.
4347 Properties which are not available are omitted.</para>
4348 <para>Returns list with alternating property names and values.</para>
4349 </sect2>
4350
4351 <sect2 id="dbus-setTagFromFileName">
4352 <title>Set tag from file name</title>
4353 <funcsynopsis>
4354 <funcprototype>
4355 <funcdef><function>setTagFromFileName</function></funcdef>
4356 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4357 </funcprototype>
4358 </funcsynopsis>
4359 <variablelist>
4360 <varlistentry>
4361 <term><replaceable>tagMask</replaceable></term>
4362 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4363 </varlistentry>
4364 </variablelist>
4365 </sect2>
4366
4367 <sect2 id="dbus-setTagFromOtherTag">
4368 <title>Set tag from other tag</title>
4369 <funcsynopsis>
4370 <funcprototype>
4371 <funcdef><function>setTagFromOtherTag</function></funcdef>
4372 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4373 </funcprototype>
4374 </funcsynopsis>
4375 <variablelist>
4376 <varlistentry>
4377 <term><replaceable>tagMask</replaceable></term>
4378 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4379 </varlistentry>
4380 </variablelist>
4381 </sect2>
4382
4383 <sect2 id="dbus-copyTag">
4384 <title>Copy tag</title>
4385 <funcsynopsis>
4386 <funcprototype>
4387 <funcdef><function>copyTag</function></funcdef>
4388 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4389 </funcprototype>
4390 </funcsynopsis>
4391 <variablelist>
4392 <varlistentry>
4393 <term><replaceable>tagMask</replaceable></term>
4394 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4395 </varlistentry>
4396 </variablelist>
4397 </sect2>
4398
4399 <sect2 id="dbus-pasteTag">
4400 <title>Paste tag</title>
4401 <funcsynopsis>
4402 <funcprototype>
4403 <funcdef><function>pasteTag</function></funcdef>
4404 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4405 </funcprototype>
4406 </funcsynopsis>
4407 <variablelist>
4408 <varlistentry>
4409 <term><replaceable>tagMask</replaceable></term>
4410 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4411 </varlistentry>
4412 </variablelist>
4413 </sect2>
4414
4415 <sect2 id="dbus-removeTag">
4416 <title>Remove tag</title>
4417 <funcsynopsis>
4418 <funcprototype>
4419 <funcdef><function>removeTag</function></funcdef>
4420 <paramdef>int32 <parameter>tagMask</parameter></paramdef>
4421 </funcprototype>
4422 </funcsynopsis>
4423 <variablelist>
4424 <varlistentry>
4425 <term><replaceable>tagMask</replaceable></term>
4426 <listitem><para>tag bit (1 for tag 1, 2 for tag 2)</para></listitem>
4427 </varlistentry>
4428 </variablelist>
4429 </sect2>
4430
4431 <sect2 id="dbus-reparseConfiguration">
4432 <title>Reparse the configuration</title>
4433 <funcsynopsis>
4434 <funcprototype>
4435 <funcdef><function>reparseConfiguration</function></funcdef>
4436 <void/>
4437 </funcprototype>
4438 </funcsynopsis>
4439 <para>Automated configuration changes are possible by modifying
4440 the configuration file and then reparsing the configuration.</para>
4441 </sect2>
4442
4443 <sect2 id="dbus-playAudio">
4444 <title>Plays the selected files</title>
4445 <funcsynopsis>
4446 <funcprototype>
4447 <funcdef><function>playAudio</function></funcdef>
4448 <void/>
4449 </funcprototype>
4450 </funcsynopsis>
4451 </sect2>
4452
4453 </sect1>
4454
4455 </appendix>
4456
4457 <appendix id="qml-interface">
4458 <title>QML Interface</title>
4459
4460 <sect1 id="qml-examples">
4461 <title>QML Examples</title>
4462
4463 <para>
4464 QML scripts can be invoked via the context menu of the file list and can be
4465 set in the tab <link linkend="configure-user-actions-qml">User Actions</link>
4466 of the settings dialog. The scripts which are set there can be used as
4467 examples to program custom scripts. QML uses &javascript;, here is the
4468 obligatory "Hello World":
4469 </para>
4470
4471 <programlisting>
4472 import Kid3 1.0
4473
4474 Kid3Script {
4475 onRun: {
4476 console.log("Hello world, folder is", app.dirName)
4477 Qt.quit()
4478 }
4479 }
4480 </programlisting>
4481
4482 <para>
4483 If this script is saved as <filename>/path/to/Example.qml</filename>, the user
4484 command can be defined as <command>@qml
4485 /path/to/Example.qml</command> with name <userinput>QML Test</userinput> and
4486 <guilabel>Output</guilabel> checked. It can then be started using the
4487 <guilabel>QML Test</guilabel> item in the file list context menu, and the
4488 output will be visible in the window.
4489 </para>
4490
4491 <para>
4492 Unfortunately, starting the QML scripts using the <command>qml</command>
4493 (e.g. <command>qml -apptype widget -I /usr/lib/kid3/plugins/imports
4494 /path/to/Example.qml</command>) is broken in recent versions of Qt. But
4495 <command>kid3-cli</command> offers an alternative way to run a QML script from
4496 the command line using its
4497 <link linkend="cli-execute"><command>execute</command></link> command.
4498 <screen width="80">
4499 kid3-cli -c "execute @qml /path/to/Example.qml"
4500 </screen>
4501 </para>
4502
4503 <para>
4504 To list the titles in the tags 2 of all files in the current folder, the
4505 following script could be used:
4506 </para>
4507
4508 <programlisting>
4509 import Kid3 1.0
4510
4511 Kid3Script {
4512 onRun: {
4513 app.firstFile()
4514 do {
4515 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
4516 console.log(app.getFrame(tagv2, "title"))
4517 }
4518 } while (app.nextFile())
4519 }
4520 }
4521 </programlisting>
4522
4523 <para>
4524 If the folder contains many files, such a script might block the user
4525 interface for some time. For longer operations, it should therefore have a
4526 break from time to time. The alternative implementation below has the work for
4527 a single file moved out into a function. This function invokes itself with a
4528 timeout of 1 ms at the end, given that more files have to be processed. This
4529 will ensure that the &GUI; remains responsive while the script is running.
4530 </para>
4531
4532 <programlisting>
4533 import Kid3 1.0
4534
4535 Kid3Script {
4536 onRun: {
4537 function doWork() {
4538 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
4539 console.log(app.getFrame(tagv2, "title"))
4540 }
4541 if (!app.nextFile()) {
4542 Qt.quit()
4543 } else {
4544 setTimeout(doWork, 1)
4545 }
4546 }
4547
4548 app.firstFile()
4549 doWork()
4550 }
4551 }
4552 </programlisting>
4553
4554 <para>
4555 When using <command>app.firstFile()</command> with
4556 <command>app.nextFile()</command>, all files of the current folder will be
4557 processed. If only the selected files shall be affected, use
4558 <command>firstFile()</command> and <command>nextFile()</command> instead,
4559 these are convenience functions of the <classname>Kid3Script</classname>
4560 component. The following example is a script which copies only the disc number
4561 and copyright frames of the selected file.
4562 </para>
4563
4564 <programlisting>
4565 import Kid3 1.1
4566
4567 Kid3Script {
4568 onRun: {
4569 function doWork() {
4570 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
4571 app.setFrame(tagv2, "*.selected", false)
4572 app.setFrame(tagv2, "discnumber.selected", true)
4573 app.setFrame(tagv2, "copyright.selected", true)
4574 app.copyTags(tagv2)
4575 }
4576 if (!nextFile()) {
4577 Qt.quit()
4578 } else {
4579 setTimeout(doWork, 1)
4580 }
4581 }
4582
4583 firstFile()
4584 doWork()
4585 }
4586 }
4587 </programlisting>
4588
4589 <para>
4590 More example scripts come with &kid3; and are already registered as user commands.
4591
4592 <itemizedlist>
4593 <listitem><para>
4594 <guilabel>ReplayGain to SoundCheck</guilabel>
4595 (<filename>ReplayGain2SoundCheck.qml</filename>):
4596 Create iTunNORM SoundCheck information from replay gain frames.
4597 </para></listitem>
4598 <listitem><para>
4599 <guilabel>Resize Album Art</guilabel>
4600 (<filename>ResizeAlbumArt.qml</filename>):
4601 Resize embedded cover art images which are larger than 500x500 pixels.
4602 </para></listitem>
4603 <listitem><para>
4604 <guilabel>Extract Album Art</guilabel>
4605 (<filename>ExtractAlbumArt.qml</filename>):
4606 Extract all embedded cover art pictures avoiding duplicates.
4607 </para></listitem>
4608 <listitem><para>
4609 <guilabel>Embed Album Art</guilabel>
4610 (<filename>EmbedAlbumArt.qml</filename>):
4611 Embed cover art found in image files into audio files in the same folder.
4612 </para></listitem>
4613 <listitem><para>
4614 <guilabel>Embed Lyrics</guilabel>
4615 (<filename>EmbedLyrics.qml</filename>):
4616 Fetch unsynchronized lyrics from web service.
4617 </para></listitem>
4618 <listitem><para>
4619 <guilabel>Text Encoding ID3v1</guilabel>
4620 (<filename>ShowTextEncodingV1.qml</filename>):
4621 Helps to find the encoding of ID3v1 tags by showing the tags of the
4622 current file in all available character encodings.
4623 </para></listitem>
4624 <listitem><para>
4625 <guilabel>ID3v1 to ASCII</guilabel>
4626 (<filename>Tag1ToAscii.qml</filename>):
4627 Transliterate extended latin characters in the ID3v1 tag to ASCII.
4628 </para></listitem>
4629 <listitem><para>
4630 <guilabel>English Title Case</guilabel>
4631 (<filename>TitleCase.qml</filename>):
4632 Formats text in the tags to English title case.
4633 </para></listitem>
4634 <listitem><para>
4635 <guilabel>Rewrite Tags</guilabel>
4636 (<filename>RewriteTags.qml</filename>):
4637 Rewrite all tags in the selected files.
4638 </para></listitem>
4639 <listitem><para>
4640 <guilabel>Export CSV</guilabel>
4641 (<filename>ExportCsv.qml</filename>):
4642 Export recursively all tags of all files to a CSV file.
4643 </para></listitem>
4644 <listitem><para>
4645 <guilabel>Import CSV</guilabel>
4646 (<filename>ImportCsv.qml</filename>):
4647 Import recursively all tags of all files from a CSV file.
4648 </para></listitem>
4649 <listitem><para>
4650 <guilabel>Export JSON</guilabel>
4651 (<filename>ExportJson.qml</filename>):
4652 Export recursively all tags of all files to a JSON file.
4653 </para></listitem>
4654 <listitem><para>
4655 <guilabel>Import JSON</guilabel>
4656 (<filename>ImportJson.qml</filename>):
4657 Import recursively all tags of all files from a JSON file.
4658 </para></listitem>
4659 <listitem><para>
4660 <guilabel>Export Playlist Folder</guilabel>
4661 (<filename>ExportPlaylist.qml</filename>):
4662 Copy all files from a playlist into a folder and rename them according to
4663 their position.
4664 </para></listitem>
4665 <listitem><para>
4666 <guilabel>QML Console</guilabel>
4667 (<filename>QmlConsole.qml</filename>):
4668 Simple console to play with &kid3;'s QML API.
4669 </para></listitem>
4670 </itemizedlist>
4671 </para>
4672
4673 </sect1>
4674
4675 <sect1 id="qml-api">
4676 <title>QML API</title>
4677
4678 <para>
4679 The API can be easily explored using the QML Console, which is available as an
4680 example script with a user interface.
4681 </para>
4682
4683 <sect2 id="qml-kid3script">
4684 <title>Kid3Script</title>
4685
4686 <para>
4687 <classname>Kid3Script</classname> is a regular QML component located inside
4688 the plugin folder. You could use another QML component just as well. Using
4689 <classname>Kid3Script</classname> makes it easy to start the script function
4690 using the <function>onRun</function> signal handler.
4691 Moreover it offers some functions:
4692
4693 <programlisting>
4694 onRun: Signal handler which is invoked when the script is started
4695 tagv1, tagv2, tagv2v1: Constants for tag parameters
4696 script: Access to scripting functions
4697 configs: Access to configuration objects
4698 getArguments(): List of script arguments
4699 isStandalone(): true if the script was not started from within Kid3
4700 setTimeout(callback, delay): Starts callback after delay ms
4701 firstFile(): To first selected file
4702 nextFile(): To next selected file
4703 </programlisting>
4704
4705 </para>
4706 </sect2>
4707
4708 <sect2 id="qml-script">
4709 <title>Scripting Functions</title>
4710
4711 <para>
4712 As &javascript; and therefore QML too has only a limited set of functions for
4713 scripting, the <function>script</function> object has some additional methods,
4714 for instance:
4715 </para>
4716
4717 <programlisting>
4718 script.properties(obj): String with Qt properties
4719 script.writeFile(filePath, data): Write data to file, true if OK
4720 script.readFile(filePath): Read data from file
4721 script.removeFile(filePath): Delete file, true if OK
4722 script.fileExists(filePath): true if file exists
4723 script.fileIsWritable(filePath): true if file is writable
4724 script.getFilePermissions(filePath): Get file permission mode bits
4725 script.setFilePermissions(filePath, modeBits): Set file permission mode bits
4726 script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
4727 file " ")
4728 script.renameFile(oldName, newName): Rename file, true if OK
4729 script.copyFile(source, dest): Copy file, true if OK
4730 script.makeDir(path): Create folder, true if OK
4731 script.removeDir(path): Remove folder, true if OK
4732 script.tempPath(): Path to temporary folder
4733 script.musicPath(): Path to music folder
4734 script.listDir(path, [nameFilters], [classify]): List folder entries
4735 script.system(program, [args], [msecs]): Synchronously start a system command,
4736 [exit code, standard output, standard error] if not timeout
4737 script.systemAsync(program, [args], [callback]): Asynchronously start a system
4738 command, callback will be called with [exit code, standard output, standard
4739 error]
4740 script.getEnv(varName): Get value of environment variable
4741 script.setEnv(varName, value): Set value of environment variable
4742 script.getQtVersion(): Qt version string, <abbrev>e.g.</abbrev> "5.4.1"
4743 script.getDataMd5(data): Get hex string of the MD5 hash of data
4744 script.getDataSize(data): Get size of byte array
4745 script.dataToImage(data, [format]): Create an image from data bytes
4746 script.dataFromImage(img, [format]): Get data bytes from image
4747 script.loadImage(filePath): Load an image from a file
4748 script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
4749 script.imageProperties(img): Get properties of an image, map containing
4750 "width", "height", "depth" and "colorCount", empty if invalid image
4751 script.scaleImage(img, width, [height]): Scale an image, returns scaled image
4752 </programlisting>
4753
4754 </sect2>
4755
4756 <sect2 id="qml-app">
4757 <title>Application Context</title>
4758
4759 <para>
4760 Using QML, a large part of the &kid3; functions are accessible. The API is
4761 similar to the one used for <link linkend="dbus-api">&DBus;</link>. For
4762 details, refer to the respective notes.
4763 </para>
4764
4765 <programlisting>
4766 app.openDirectory(path): Open folder
4767 app.unloadAllTags(): Unload all tags
4768 app.saveDirectory(): Save folder
4769 app.revertFileModifications(): Revert
4770 app.importTags(tag, path, fmtIdx): Import file
4771 app.importFromTags(tag, source, extraction): Import from tags
4772 app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
4773 app.downloadImage(url, allFilesInDir): Download image
4774 app.exportTags(tag, path, fmtIdx): Export file
4775 app.writePlaylist(): Write playlist
4776 app.getPlaylistItems(path): Get items of a playlist
4777 app.setPlaylistItems(path, items): Set items of a playlist
4778 app.selectAllFiles(): Select all
4779 app.deselectAllFiles(): Deselect
4780 app.firstFile([select], [onlyTaggedFiles]): To first file
4781 app.nextFile([select], [onlyTaggedFiles]): To next file
4782 app.previousFile([select], [onlyTaggedFiles]): To previous file
4783 app.selectCurrentFile([select]): Select current file
4784 app.selectFile(path, [select]): Select a specific file
4785 app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
4786 app.requestExpandFileList(): Expand all
4787 app.applyFilenameFormat(): Apply filename format
4788 app.applyTagFormat(): Apply tag format
4789 app.applyTextEncoding(): Apply text encoding
4790 app.numberTracks(nr, total, tag, [options]): Number tracks
4791 app.applyFilter(expr): Filter
4792 app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
4793 app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
4794 app.getFilenameFromTags(tag): Filename from tags
4795 app.getTagsFromFilename(tag): Filename to tags
4796 app.getAllFrames(tag): Get object with all frames
4797 app.getFrame(tag, name): Get frame
4798 app.setFrame(tag, name, value): Set frame
4799 app.getPictureData(): Get data from picture frame
4800 app.setPictureData(data): Set data in picture frame
4801 app.copyToOtherTag(tag): Tags to other tags
4802 app.copyTags(tag): Copy
4803 app.pasteTags(tag): Paste
4804 app.removeTags(tag): Remove
4805 app.playAudio(): Play
4806 app.readConfig(): Read configuration
4807 app.applyChangedConfiguration(): Apply configuration
4808 app.dirName: Folder name
4809 app.selectionInfo.fileName: File name
4810 app.selectionInfo.filePath: Absolute file path
4811 app.selectionInfo.detailInfo: Format details
4812 app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
4813 app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
4814 app.selectionInfo.formatString(tag, format): Substitute codes in format string
4815 app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
4816 select a file
4817 app.selectDirName(caption, dir): Open file dialog to select a folder
4818 </programlisting>
4819
4820 <para>
4821 For asynchronous operations, callbacks can be connected to signals.
4822 </para>
4823
4824 <programlisting>
4825 function automaticImport(profile) {
4826 function onAutomaticImportFinished() {
4827 app.batchImporter.finished.disconnect(onAutomaticImportFinished)
4828 }
4829 app.batchImporter.finished.connect(onAutomaticImportFinished)
4830 app.batchImport(profile, tagv2)
4831 }
4832
4833 function renameDirectory(format) {
4834 function onRenameActionsScheduled() {
4835 app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
4836 app.performRenameActions()
4837 }
4838 app.renameActionsScheduled.connect(onRenameActionsScheduled)
4839 app.renameDirectory(tagv2v1, format, false)
4840 }
4841 </programlisting>
4842
4843 </sect2>
4844
4845 <sect2 id="qml-configs">
4846 <title>Configuration Objects</title>
4847
4848 <para>
4849 The different configuration sections are accessible via methods of
4850 <function>configs</function>. Their properties can be listed in the QML console.
4851
4852 <screen width="80">
4853 script.properties(configs.networkConfig())
4854 </screen>
4855
4856 Properties can be set:
4857 <screen width="80">
4858 configs.networkConfig().useProxy = false
4859 </screen>
4860 </para>
4861
4862 <programlisting>
4863 configs.batchImportConfig()
4864 configs.exportConfig()
4865 configs.fileConfig()
4866 configs.filenameFormatConfig()
4867 configs.filterConfig()
4868 configs.findReplaceConfig()
4869 configs.guiConfig()
4870 configs.importConfig()
4871 configs.mainWindowConfig()
4872 configs.networkConfig()
4873 configs.numberTracksConfig()
4874 configs.playlistConfig()
4875 configs.renDirConfig()
4876 configs.tagConfig()
4877 configs.tagFormatConfig()
4878 configs.userActionsConfig()
4879 </programlisting>
4880
4881 </sect2>
4882
4883 </sect1>
4884
4885 </appendix>
4886
4887 &documentation.index;
4888 </book>
4889 <!--
4890 Local Variables:
4891 mode: nxml
4892 End:
4893 -->