2
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
3
<!ENTITY kid3 '<application>Kid3</application>'>
4
<!ENTITY % addindex "IGNORE">
5
<!ENTITY % English "INCLUDE"><!-- change language only here -->
7
<book lang="&language;">
10
<title>The Kid3 Handbook</title>
14
<firstname>Urs</firstname>
15
<surname>Fleisch</surname>
17
<address><email>ufleisch@users.sourceforge.net</email></address>
24
<holder>Urs Fleisch</holder>
26
<legalnotice>&FDLNotice;</legalnotice>
28
<date>24/01/2004</date>
29
<releaseinfo>0.4</releaseinfo>
33
&kid3; is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
34
an efficient way. It is easy to set tags of multiple files to the same
35
values (e.g. album, artist, year and genre in all files of the same album) and
36
generate the tags from the file name or vice versa.
41
<keyword>KDE</keyword>
42
<keyword>kdemultimedia</keyword>
43
<keyword>MP3</keyword>
44
<keyword>ID3</keyword>
45
<keyword>ID3v1</keyword>
46
<keyword>ID3v2</keyword>
51
<chapter id="introduction">
52
<title>Introduction</title>
55
&kid3; is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
56
an efficient way. These tags can be edited by most MP3 players, but not in
57
a very comfortable and efficient way.
60
&kid3; does not grab, encode nor play
61
MP3 files, but it is targeted to edit the ID3 tags of all files of an album
62
in an efficient way, i.e. with as few mouse clicks and key strokes as
63
possible. Where most other programs can edit either ID3v1 or ID3v2 tags,
64
&kid3; has full control over both versions, can convert tags between the
65
two formats and has access to all ID3v2 tags. Tags of multiple files can be
66
set to the same value, e.g. the artist, album, year and genre of all files
67
of an album typically have the same values and can be set together. If the
68
information for the tags is contained in the file name, the tags can be
69
automatically set from the file name. It is also possible to set the file
70
name according to the tags found in the file in arbitrary formats.
73
The editing task is further supported by automatic replacement of characters
74
or substrings, for instance to remove illegal characters from
75
filenames. Automatic control of upper and lower case characters makes it easy
76
to use a consistent naming scheme in all tags.
79
The tag information for full albums can be taken from
80
<ulink url="http://freedb.org">freedb.org</ulink> or other sources of
81
track lists. The import format is freely configurable by regular expressions.
84
Please report any problems or feature requests to the author.
88
<chapter id="using-kid3">
89
<title>Using Kid3</title>
91
<sect1 id="kid3-features">
92
<title>Kid3 features</title>
94
<listitem><para>Edit ID3v1.1 tags</para></listitem>
95
<listitem><para>Edit all ID3v2.3 frames</para></listitem>
96
<listitem><para>Edit tags of multiple files</para></listitem>
97
<listitem><para>Convert between ID3v1.1 and ID3v2.3 tags</para></listitem>
98
<listitem><para>Generate tags from filename</para></listitem>
99
<listitem><para>Generate filename from tags</para></listitem>
100
<listitem><para>Generate playlist file</para></listitem>
101
<listitem><para>Automatic case conversion and string translation</para></listitem>
102
<listitem><para>Import from <ulink url="http://freedb.org">freedb.org</ulink>
103
and other data sources</para></listitem>
107
<sect1 id="example-usage">
108
<title>Example Usage</title>
110
This section describes a typical session with &kid3;.
111
Let's assume we have a directory containing MP3 files with the tracks from
112
the album "Let's Tag" from the band "One Hit Wonder". The directory is
113
named in the "artist - album" format, in our case <filename>One Hit Wonder - Let's
114
Tag</filename>. The directory contains the tracks in the "track title.mp3"
115
format, which I think is useful because the filenames are short
116
(important when using mobile MP3 players with small displays) and in the
117
correct order when sorted alphabetically (important when using hardware MP3
118
players which play the tracks in alphabetical order or in the order in
119
which they are burnt on CD and that order is alphabetical when using
120
<command>mkisofs</command>). Besides this, the artist and album information
121
is already in the directory name and does not have to be repeated in the filename.
122
But back to our example, the directory listing looks like this:
124
<para><filename>01 Intro.mp3</filename></para>
125
<para><filename>02 We Only Got This One.mp3</filename></para>
126
<para><filename>03 Outro.mp3</filename></para>
128
These files have no tags yet and we want to generate them using &kid3;. We use
129
<guimenuitem>Open</guimenuitem> (<guimenu>File</guimenu> menu or toolbar) and
130
select one of the files in this directory. All files will be displayed in the
131
file listbox. Lazy as we are, we want to use the information in the directory
132
and file names to generate tags. Therefore we select all files, then click the
133
<guibutton>From Filename</guibutton> button in the <guilabel>ID3v1.1</guilabel>
134
section. This will set the title, artist, album and track values in all files.
135
To set the year and genre values of all files, we keep all files selected and
136
type in "2002" for the <guilabel>Year</guilabel> and select "Pop" from the
137
<guilabel>Genre</guilabel> combobox. To set only these two values, we check their
138
checkboxes and leave all other checkboxes unchecked. Now we change the
139
selection by only selecting the first file and we see that all tags contain
140
the correct values. The tags of the other files can be verified too by
141
selecting them one by one. When we are satisfied with the tags, we use
142
<guimenuitem>Save</guimenuitem> (<guimenu>File</guimenu> menu or toolbar).
143
Selecting <guimenuitem>Create Playlist</guimenuitem> from the
144
<guimenu>File</guimenu> menu will generate a file
145
<filename>One Hit Wonder - Let's Tag.m3u</filename> in the directory.
151
<chapter id="commands">
152
<title>Command Reference</title>
154
<sect1 id="kid3-window">
155
<title>The Kid3 Window</title>
158
<title>The GUI Elements</title>
160
The &kid3; GUI is separated in four sections: At the left is the file
161
listbox, the right side contains the <guilabel>Filename</guilabel>,
162
<guilabel>ID3v1.1</guilabel> and <guilabel>ID3v2.3</guilabel> sections.
167
<varlistentry><term>Filelist</term>
170
The file list contains the names of all the files in the opened
171
directory which match the selected file name filter (typically
172
<filename>*.mp3</filename>). A single or multiple files can be selected. To
173
select no file, click into the empty area after the listbox entries. The
174
selection determines the files which are affected by the operations which
175
are available by using the buttons described below.
181
<term><guilabel>Filename</guilabel></term>
183
<listitem><para>The <guilabel>Name</guilabel> line edit contains the name of the file
184
(if only a single file is selected). If this name is changed, the file will
185
be renamed when the Save command is used.
188
The <guilabel>Format</guilabel> combo box and line edit contains the format
189
to be used when the filename is generated from the ID3v1.1 or ID3v2.3 tags.
190
The filename can contain arbitrary characters, even a directory part separated
191
by a slash from the file name, but that directory must already exist for the
192
renaming to succeed. The following special codes are used to insert tag values
197
<listitem><para>%s Title (Song)</para></listitem>
198
<listitem><para>%a Artist</para></listitem>
199
<listitem><para>%l Album</para></listitem>
200
<listitem><para>%c Comment</para></listitem>
201
<listitem><para>%y Year</para></listitem>
202
<listitem><para>%t Track</para></listitem>
203
<listitem><para>%g Genre</para></listitem>
207
Some commonly used filename formats are already available in the combo box,
208
but it is also possible to type in some special format into the line edit.
211
<guibutton>From ID3v1</guibutton>: Sets the filename using the selected format
216
<guibutton>From ID3v2</guibutton>: Sets the filename using the selected format
223
<varlistentry><term><guilabel>ID3v1.1</guilabel></term>
226
The line edit widgets for <guilabel>Title</guilabel>,
227
<guilabel>Artist</guilabel>,
228
<guilabel>Album</guilabel>, <guilabel>Comment</guilabel>,
229
<guilabel>Year</guilabel>, <guilabel>Track</guilabel> and
230
<guilabel>Genre</guilabel> are used to edit the corresponding value in the
231
ID3v1.1 tags of the selected files. The value will be changed when the file
232
selection is altered or before operations like <guimenuitem>Save</guimenuitem>
233
and <guimenuitem>Quit</guimenuitem> and when the corresponding
234
check box at the left of the field name is checked. This is useful to
235
change only some values and leave the other values unchanged.
238
If a single file is selected, all check boxes are checked and the line edit
239
widgets contain the values found in the tags of this file. If a tag is not
240
found in the file, the corresponding empty value is displayed, which is an
241
empty string for the <guilabel>Title</guilabel>, <guilabel>Artist</guilabel>,
242
<guilabel>Album</guilabel> and <guilabel>Comment</guilabel> line edits, 0 for the
243
numerical <guilabel>Year</guilabel> and <guilabel>Track</guilabel> edits and
244
an empty selected value for the <guilabel>Genre</guilabel>
245
combo box. The values can be changed and if the corresponding check box is
246
checked, they will be set for the selected file after the selection is
247
changed. The file is then marked as modified by an asterisk in the file
248
listbox but remains unchanged until the <guimenuitem>Save</guimenuitem>
252
If multiple files are selected, only the values which are identical in all
253
selected files are displayed. In all other controls, the empty values as
254
described above are displayed. All check boxes are unchecked to avoid
255
unwanted changes. If a value has to be set for all selected files, it can
256
be edited and the checkbox has to be set. The values will be set for all
257
selected files when the selection is changed and can be saved using the
258
<guimenuitem>Save</guimenuitem> command.
261
<guibutton>From Filename</guibutton>: The tags are set from the filename.
262
The filename should be in one of the supported formats:
264
<listitem><para><filename>Artist - Album/Track Song.mp3</filename></para></listitem>
265
<listitem><para><filename>Album/Track - Artist - Song.mp3</filename></para></listitem>
266
<listitem><para><filename>/Artist - Album - Track - Song.mp3</filename></para></listitem>
267
<listitem><para><filename>Album/Artist - Track - Song.mp3</filename></para></listitem>
268
<listitem><para><filename>Album/Artist - Song.mp3</filename></para></listitem>
270
If a single file is selected, the GUI controls are filled with the values
271
extraced from the filename. If multiple files are selected, the tags of the
272
files are directly set according to the filenames.
275
<guibutton>From ID3v2</guibutton>: The ID3v1.1 tags are set from the
276
corresponding values in the ID3v2.3 tags.
277
If a single file is selected, the GUI controls are filled with the values
278
from the ID3v2.3 tags. If multiple files are selected, the tags of the
279
files are directly set.
282
<guibutton>Copy</guibutton>: The copy buffer is filled with the ID3v1.1 values.
283
Only values with checked checkbox will be used in subsequent Paste commands.
286
<guibutton>Paste</guibutton>: Pastes the values from the copy buffer into the
290
<guibutton>Remove</guibutton>: This will set all GUI controls to their empty
291
values which results in removing all values. The saved file will then contain
297
<varlistentry><term><guilabel>ID3v2.3</guilabel></term>
300
The GUI controls function in the same way as described for the
301
<guilabel>ID3v1.1</guilabel> section, but the size of the strings is not limited.
304
<guilabel>Frames</guilabel>: The ID3v2.3 tags can not only contain the same values
305
as the ID3v1.1 tags, the format is built in a flexible way from several frames
306
which are themselves composed of several fields. The frames list box shows
307
all the frames which are available in the selected file.
310
<guibutton>Edit</guibutton>: This will open a window which allows to edit all fields
311
of the selected frame. This is equivalent to double clicking on the selected frame.
314
<guibutton>Add</guibutton>: A requester to select the frame type will appear
315
and a frame of the selected type is added to the file.
318
<guibutton>Delete</guibutton>: Deletes the selected frame.
327
<title>The File Menu</title>
334
<keycombo><keycap>Ctrl</keycap><keycap>O</keycap></keycombo>
336
<guimenu>File</guimenu>
337
<guimenuitem>Open...</guimenuitem>
339
<listitem><para><action>Opens a directory.</action> All files matching the selected
340
file name filter will be displayed in the file listbox.</para></listitem>
345
<guimenu>File</guimenu>
346
<guimenuitem>Open Recent</guimenuitem>
348
<listitem><para><action>Opens a recently opened directory.</action></para></listitem>
354
<keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
356
<guimenu>File</guimenu>
357
<guimenuitem>Save</guimenuitem>
359
<listitem><para><action>Saves all changed files in the directory.</action> The
360
changed files are marked with an asterisk in the file listbox. If any file
361
names have been changed, those files will be renamed.</para></listitem>
366
<guimenu>File</guimenu>
367
<guimenuitem>Revert</guimenuitem>
369
<listitem><para><action>Reverts the changes of one or multiple files.</action> If no
370
files are selected in the file listbox, the changes of all files will be
371
reverted, else only the changes of the selected files are reverted.
377
<guimenu>File</guimenu>
378
<guimenuitem>Import...</guimenuitem>
380
<listitem><para>The <action>Import dialog</action> can be used to import data
381
directly from a freedb.org server, from the
382
Web-interface of <ulink url="http://freedb.org">freedb.org</ulink> or other
383
sources of album track lists in textual format.
386
Import from a freedb.org server is possible using a dialog which appears when
387
<guibutton>From freedb.org</guibutton> is selected. The words to search for
388
(e.g. artist and album name) can be entered there, the albums which match the
389
query will be displayed when <guibutton>Find</guibutton> is clicked and the
390
results from <ulink url="http://www.freedb.org">www.freedb.org</ulink> are
391
received. If multiple entries for one album are found, the second entry is
392
displayed as 2, then 3 and so on. Importing the track data for an album is
393
done by selecting the album in the list. The freedb.org server to import from
394
can be selected as well as the CGI path and a proxy, if necessary. The
395
imported data is displayed in the preview table of the import dialog. To work
396
in that dialog again, the freedb.org dialog has to be closed - it can be
397
reopened later by clicking <guibutton>From freedb.org</guibutton> again and
398
its contents will be restored. When satisfied with the displayed tracks, they
399
can be imported by terminating the import dialog with
400
<guibutton>OK</guibutton>.
403
For the import of textual data, several preconfigured import formats are
404
available. The first, "freedb HTML
405
text", can be used to copy information from an HTML page of
406
<ulink url="http://freedb.org">freedb.org</ulink>. Search an album in freedb
407
and if the desired information is displayed in the web browser, copy the
408
contents to the clipboard. Then click the <guibutton>From
409
Clipboard</guibutton> button and the imported tracks will be displayed in the
410
preview table at the top of the dialog. If you are satisfied with the imported
411
data, terminate the dialog with <guibutton>OK</guibutton>, which will insert
412
the data into the tags of the current directory. The destination
413
(<guilabel>ID3v1</guilabel> or <guilabel>ID3v2</guilabel>) can be selected
414
with a combo box. The files in the current directory should be in the correct
415
track order to get their tags assigned. This is the case if they are numbered.
418
The second preconfigured import format, "freedb HTML source", can be used, if
419
the data is available as an HTML document. Import is possible using the
420
<guibutton>From File</guibutton> button, which opens a file selector, or
421
copying its contents from an editor and then importing from clipboard. This
422
format can be useful for offline import, although the HTML document could also
423
be opened in a browser and then be imported in the first format via the clipboard.
426
More preconfigured formats, e.g. "Track Title Time", are available. A custom format
427
is left empty to be set by the user. Two lines below the format name can be
428
set with a regular expression to capture the fields from the import text. The
429
first regular expression will be parsed once per document to gather per-album
430
data such as artist, album, year and genre. The second line is tried to match
431
from the start of the document to the end to get track data, usually number
432
and title. The regular expressions include all the features offered by Qt,
433
which is most of the what Perl offers. Bracketing constructs "(..)" create
434
capture buffers for the fields to import and are preceeded by &kid3; specific
435
codes to specify which field to capture. The codes are the same as used for
440
<listitem><para>%s Title (Song)</para></listitem>
441
<listitem><para>%a Artist</para></listitem>
442
<listitem><para>%l Album</para></listitem>
443
<listitem><para>%c Comment</para></listitem>
444
<listitem><para>%y Year</para></listitem>
445
<listitem><para>%t Track</para></listitem>
446
<listitem><para>%g Genre</para></listitem>
450
For example, a track regular expression (second line) to import from an
451
.m3u playlist could be "%t(\d+)\s+%s(\S[^\r\n]*)\.mp3[\r\n]". All formats can
452
be changed by editing the regular expressions and the name and then clicking
453
<guibutton>OK</guibutton>. They will be stored in the
454
<filename>kid3rc</filename> file in the configuration directory. This file can
455
be directly edited to have more import formats or it can be deleted to revert
456
to the default formats.
463
<guimenu>File</guimenu>
464
<guimenuitem>Create Playlist</guimenuitem>
466
<listitem><para><action>Creates an M3U playlist.</action> The file will be stored in
467
the opened directory and have the same name as the directory, followed by
468
an .m3u extension. The file simly contains the names of the files displayed
469
in the file listbox, no special EXTM3U or EXTINFO lines are generated.
470
If all files of an album are stored in a separate directory, this function
471
can be used to generate a playlist for an album.</para></listitem>
477
<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
479
<guimenu>File</guimenu>
480
<guimenuitem>Quit</guimenuitem>
482
<listitem><para><action>Quits the application.</action></para></listitem>
491
<title>The Tools Menu</title>
497
<guimenu>Tools</guimenu>
498
<guimenuitem>Apply Format</guimenuitem>
500
<listitem><para>When <guilabel>Format while editing</guilabel> is switched off
501
in the configuration dialog, this menu item can be used to <action>apply
502
the configured format to the selected files</action>. This can also be used
503
to check whether the file and tag names conform with the configured format
504
by applying the format to all saved files and then checking if any files were
505
changed (and therefore marked with an asterisk in the file listbox).
514
<title>The Settings Menu</title>
520
<guimenu>Settings</guimenu>
521
<guimenuitem>Show Toolbar</guimenuitem>
523
<listitem><para><action>Toggles displaying of the toolbar</action>, which contains
524
icons to open and save a directory.</para></listitem>
529
<guimenu>Settings</guimenu>
530
<guimenuitem>Show Statusbar</guimenuitem>
532
<listitem><para><action>Toggles displaying of the statusbar</action>, which displays
533
longer actions such as opening or saving a directory.</para></listitem>
538
<guimenu>Settings</guimenu>
539
<guimenuitem>Configure Kid3...</guimenuitem>
541
<listitem><para>Opens the <action>configuration dialog</action>, which is used
542
to set the format for the strings in the tag fields and the filename.
545
When <guilabel>Format while editing</guilabel> is checked, the format
546
configuration is automatically used while editing text in the line edits. The
547
format can be set separately for filenames and ID3 tags.
548
The <guilabel>Case Conversion</guilabel> can be set to <guilabel>No
549
changes</guilabel>, <guilabel>All lowercase</guilabel>, <guilabel>All
550
uppercase</guilabel>, <guilabel>First letter uppercase</guilabel> or
551
<guilabel>All first letters uppercase</guilabel>.
552
The string replacement list can be set to arbitrary string mappings. To add a
553
new mapping, select the <guilabel>From</guilabel> cell of a row and insert the
554
text to replace, then go to the <guilabel>To</guilabel> column and enter the
555
replacement text. To remove a mapping set the <guilabel>From</guilabel> cell
556
to an empty value (e.g. by first typing space and then backspace). Inserting
557
and deleting rows is also possible using a context menu which appears when the
558
right mouse button is clicked. Replacement is only active, if the
559
<guilabel>String Replacement</guilabel> checkbox is checked.
570
<title>The Help Menu</title>
576
<guimenu>Help</guimenu>
577
<guimenuitem>Kid3 Handbook</guimenuitem>
579
<listitem><para><action>Opens this handbook.</action></para></listitem>
584
<guimenu>Help</guimenu>
585
<guimenuitem>About Kid3</guimenuitem>
587
<listitem><para><action>Displays a short information about &kid3;.
588
</action></para></listitem>
601
<chapter id="credits">
603
<title>Credits and License</title>
609
Program written by Urs Fleisch <email>ufleisch@users.sourceforge.net</email>
618
<appendix id="installation">
619
<title>Installation</title>
621
<sect1 id="getting-kid3">
622
<title>How to obtain Kid3</title>
625
&kid3; can be found at
626
<ulink url="http://kid3.sourceforge.net">http://kid3.sourceforge.net</ulink>.
630
<sect1 id="requirements">
631
<title>Requirements</title>
634
&kid3; needs <ulink url="http://id3lib.sourceforge.net">id3lib</ulink> and
635
<ulink url="http://www.trolltech.com/qt/">Qt</ulink>. <ulink
636
url="http://www.kde.org">KDE</ulink> is recommended but not necessary, as
637
&kid3; can also be compiled as a Qt application. &kid3; can be compiled for
638
systems where these libraries are available, e.g. for Linux and Windows.
641
&kid3; was tested with
644
SuSE Linux 7.3: id3lib 3.8.0pre1, id3lib 3.8.0, id3lib 3.8.2, KDE 2.2.2,
645
KDE 3.0.4, Qt 2.3.2, Qt 3.0.5
648
SuSE Linux 8.1: id3lib 3.8.0, KDE 3.0.5, KDE 3.1.1, Qt 2.3.2, Qt
652
SuSE Linux 8.2: id3lib 3.8.2, id3lib 3.8.3, KDE 3.1.1, KDE 3.1.3, KDE 3.1.4,
653
Qt 3.1.1, Qt 3.1.2, Qt 3.2.1
656
Windows NT 4.0: id3lib 3.8.0, id3lib 3.8.2, id3lib 3.8.3, non-commercial Qt version 2.3.0.
661
<sect1 id="compilation">
662
<title>Compilation and Installation</title>
665
You can compile &kid3; with or without KDE. Without KDE, &kid3; is a
666
simple Qt application and lacks some configuration and session features.
669
Go into the top directory and type
671
<prompt>%</prompt> <userinput>./configure</userinput>
672
<prompt>%</prompt> <userinput>make</userinput>
673
<prompt>%</prompt> <userinput>make install</userinput>
677
To compile for different versions of Qt or KDE, set the corresponding
681
The Qt application can also be compiled for Windows.
682
In the kid3 directory, type
684
<prompt>></prompt> <userinput>nmake /f kid3.mak</userinput>
690
<sect1 id="configuration">
691
<title>Configuration</title>
693
<para>With KDE, the file name filter and format, the import formats, the
694
filename and ID3 formats, the toolbar and statusbar
695
settings as well as the window size will be be saved in the standard
696
location in file <filename>kid3rc</filename>.
697
As a Qt application, this file is in the <filename>.qt</filename> directory,
698
with older releases of Qt, a file <filename>kid3.cfg</filename> is created.
705
&documentation.index;
710
sgml-minimize-attributes:nil
711
sgml-general-insert-case:lower