The Kid3 Handbook

Urs Fleisch

0.5

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Abstract

Kid3 is an application to edit the ID3v1 and ID3v2 tags in MP3 files in an efficient way. It is easy to set tags of multiple files to the same values (e.g. album, artist, year and genre in all files of the same album) and generate the tags from the file name or vice versa.


Table of Contents

1. Introduction
2. Using Kid3
Kid3 features
Example Usage
3. Command Reference
The Kid3 Window
The GUI Elements
The File Menu
The Tools Menu
The Settings Menu
The Help Menu
4. Credits and License
A. Installation
How to obtain Kid3
Requirements
Compilation and Installation
Configuration

Chapter 1. Introduction

Kid3 is an application to edit the ID3v1 and ID3v2 tags in MP3 files in an efficient way. These tags can be edited by most MP3 players, but not in a very comfortable and efficient way.

Kid3 does not grab, encode nor play MP3 files, but it is targeted to edit the ID3 tags of all files of an album in an efficient way, i.e. with as few mouse clicks and key strokes as possible. Where most other programs can edit either ID3v1 or ID3v2 tags, Kid3 has full control over both versions, can convert tags between the two formats and has access to all ID3v2 tags. Tags of multiple files can be set to the same value, e.g. the artist, album, year and genre of all files of an album typically have the same values and can be set together. If the information for the tags is contained in the file name, the tags can be automatically set from the file name. It is also possible to set the file name according to the tags found in the file in arbitrary formats.

The editing task is further supported by automatic replacement of characters or substrings, for instance to remove illegal characters from filenames. Automatic control of upper and lower case characters makes it easy to use a consistent naming scheme in all tags.

The tag information for full albums can be taken from freedb.org or other sources of track lists. The import format is freely configurable by regular expressions.

Please report any problems or feature requests to the author.

Chapter 2. Using Kid3

Kid3 features

  • Edit ID3v1.1 tags

  • Edit all ID3v2.3 frames

  • Edit tags of multiple files

  • Convert between ID3v1.1 and ID3v2.3 tags

  • Generate tags from filename

  • Generate filename from tags

  • Generate and change directory names from tags

  • Generate playlist file

  • Automatic case conversion and string translation

  • Import from freedb.org and other data sources

Example Usage

This section describes a typical session with Kid3. Let's assume we have a directory containing MP3 files with the tracks from the album "Let's Tag" from the band "One Hit Wonder". The directory is named in the "artist - album" format, in our case One Hit Wonder - Let's Tag. The directory contains the tracks in the "track title.mp3" format, which I think is useful because the filenames are short (important when using mobile MP3 players with small displays) and in the correct order when sorted alphabetically (important when using hardware MP3 players which play the tracks in alphabetical order or in the order in which they are burnt on CD and that order is alphabetical when using mkisofs). Besides this, the artist and album information is already in the directory name and does not have to be repeated in the filename. But back to our example, the directory listing looks like this:

01 Intro.mp3

02 We Only Got This One.mp3

03 Outro.mp3

These files have no tags yet and we want to generate them using Kid3. We use Open (File menu or toolbar) and select one of the files in this directory. All files will be displayed in the file listbox. Lazy as we are, we want to use the information in the directory and file names to generate tags. Therefore we select all files, then click the From Filename button in the ID3v1.1 section. This will set the title, artist, album and track values in all files. To set the year and genre values of all files, we keep all files selected and type in "2002" for the Year and select "Pop" from the Genre combobox. To set only these two values, we check their checkboxes and leave all other checkboxes unchecked. Now we change the selection by only selecting the first file and we see that all tags contain the correct values. The tags of the other files can be verified too by selecting them one by one. When we are satisfied with the tags, we use Save (File menu or toolbar). Selecting Create Playlist from the File menu will generate a file One Hit Wonder - Let's Tag.m3u in the directory.

Chapter 3. Command Reference

The Kid3 Window

The GUI Elements

The Kid3 GUI is separated in four sections: At the left is the file listbox, the right side contains the Filename, ID3v1.1 and ID3v2.3 sections.

Filelist

The file list contains the names of all the files in the opened directory which match the selected file name filter (typically *.mp3). A single or multiple files can be selected. To select no file, click into the empty area after the listbox entries. The selection determines the files which are affected by the operations which are available by using the buttons described below.

The the left of the names two icons can be displayed: a disc to show that the file has been modified and information about which tags are present (V1, V2, V1V2 or NO TAG, no icon is displayed if the file has not been read in yet).

Filename

The Name line edit contains the name of the file (if only a single file is selected). If this name is changed, the file will be renamed when the Save command is used.

The Format combo box and line edit contains the format to be used when the filename is generated from the ID3v1.1 or ID3v2.3 tags. The filename can contain arbitrary characters, even a directory part separated by a slash from the file name, but that directory must already exist for the renaming to succeed. The following special codes are used to insert tag values into the filename:

  • %s Title (Song)

  • %a Artist

  • %l Album

  • %c Comment

  • %y Year

  • %t Track

  • %g Genre

Some commonly used filename formats are already available in the combo box, but it is also possible to type in some special format into the line edit.

From ID3v1: Sets the filename using the selected format and the ID3v1.1 tags.

From ID3v2: Sets the filename using the selected format and the ID3v2.3 tags.

Info: Shows information about MPEG version and layer, bitrate, sample rate, channels and the length of the file.

ID3v1.1

The line edit widgets for Title, Artist, Album, Comment, Year, Track and Genre are used to edit the corresponding value in the ID3v1.1 tags of the selected files. The value will be changed when the file selection is altered or before operations like Save and Quit and when the corresponding check box at the left of the field name is checked. This is useful to change only some values and leave the other values unchanged.

If a single file is selected, all check boxes are checked and the line edit widgets contain the values found in the tags of this file. If a tag is not found in the file, the corresponding empty value is displayed, which is an empty string for the Title, Artist, Album and Comment line edits, 0 for the numerical Year and Track edits and an empty selected value for the Genre combo box. The values can be changed and if the corresponding check box is checked, they will be set for the selected file after the selection is changed. The file is then marked as modified by an asterisk in the file listbox but remains unchanged until the Save command is used.

If multiple files are selected, only the values which are identical in all selected files are displayed. In all other controls, the empty values as described above are displayed. All check boxes are unchecked to avoid unwanted changes. If a value has to be set for all selected files, it can be edited and the checkbox has to be set. The values will be set for all selected files when the selection is changed and can be saved using the Save command.

From Filename: The tags are set from the filename. The filename should be in one of the supported formats:

  • Artist - Album/Track Song.mp3

  • Album/Track - Artist - Song.mp3

  • /Artist - Album - Track - Song.mp3

  • Album/Artist - Track - Song.mp3

  • Album/Artist - Song.mp3

If a single file is selected, the GUI controls are filled with the values extraced from the filename. If multiple files are selected, the tags of the files are directly set according to the filenames.

From ID3v2: The ID3v1.1 tags are set from the corresponding values in the ID3v2.3 tags. If a single file is selected, the GUI controls are filled with the values from the ID3v2.3 tags. If multiple files are selected, the tags of the files are directly set.

Copy: The copy buffer is filled with the ID3v1.1 values. Only values with checked checkbox will be used in subsequent Paste commands.

Paste: Pastes the values from the copy buffer into the GUI controls.

Remove: This will set all GUI controls to their empty values which results in removing all values. The saved file will then contain no ID3v1.1 tags.

ID3v2.3

The GUI controls function in the same way as described for the ID3v1.1 section, but the size of the strings is not limited.

Frames: The ID3v2.3 tags can not only contain the same values as the ID3v1.1 tags, the format is built in a flexible way from several frames which are themselves composed of several fields. The frames list box shows all the frames which are available in the selected file.

Edit: This will open a window which allows to edit all fields of the selected frame. This is equivalent to double clicking on the selected frame.

Add: A requester to select the frame type will appear and a frame of the selected type is added to the file.

Delete: Deletes the selected frame.

The File Menu

File->Open... (Ctrl-O)

Opens a directory. All files matching the selected file name filter will be displayed in the file listbox.

File->Open Recent

Opens a recently opened directory.

File->Save (Ctrl-S)

Saves all changed files in the directory. The changed files are marked with an asterisk in the file listbox. If any file names have been changed, those files will be renamed.

File->Revert

Reverts the changes of one or multiple files. If no files are selected in the file listbox, the changes of all files will be reverted, else only the changes of the selected files are reverted.

File->Import...

The Import dialog can be used to import data directly from a freedb.org server, from the Web-interface of freedb.org or other sources of album track lists in textual format.

Import from a freedb.org server is possible using a dialog which appears when From freedb.org is selected. The words to search for (e.g. artist and album name) can be entered there, the albums which match the query will be displayed when Find is clicked and the results from www.freedb.org are received. If multiple entries for one album are found, the second entry is displayed as 2, then 3 and so on. Importing the track data for an album is done by selecting the album in the list. The freedb.org server to import from can be selected as well as the CGI path and a proxy, if necessary. The imported data is displayed in the preview table of the import dialog. To work in that dialog again, the freedb.org dialog has to be closed - it can be reopened later by clicking From freedb.org again and its contents will be restored. When satisfied with the displayed tracks, they can be imported by terminating the import dialog with OK.

For the import of textual data, several preconfigured import formats are available. The first, "freedb HTML text", can be used to copy information from an HTML page of freedb.org. Search an album in freedb and if the desired information is displayed in the web browser, copy the contents to the clipboard. Then click the From Clipboard button and the imported tracks will be displayed in the preview table at the top of the dialog. If you are satisfied with the imported data, terminate the dialog with OK, which will insert the data into the tags of the current directory. The destination (ID3v1 or ID3v2) can be selected with a combo box. The files in the current directory should be in the correct track order to get their tags assigned. This is the case if they are numbered.

The second preconfigured import format, "freedb HTML source", can be used, if the data is available as an HTML document. Import is possible using the From File button, which opens a file selector, or copying its contents from an editor and then importing from clipboard. This format can be useful for offline import, although the HTML document could also be opened in a browser and then be imported in the first format via the clipboard.

More preconfigured formats, e.g. "Track Title Time", are available. A custom format is left empty to be set by the user. Two lines below the format name can be set with a regular expression to capture the fields from the import text. The first regular expression will be parsed once per document to gather per-album data such as artist, album, year and genre. The second line is tried to match from the start of the document to the end to get track data, usually number and title. The regular expressions include all the features offered by Qt, which is most of the what Perl offers. Bracketing constructs "(..)" create capture buffers for the fields to import and are preceeded by Kid3 specific codes to specify which field to capture. The codes are the same as used for the filename format:

  • %s Title (Song)

  • %a Artist

  • %l Album

  • %c Comment

  • %y Year

  • %t Track

  • %g Genre

  • %d Duration

For example, a track regular expression (second line) to import from an .m3u playlist could be "%t(\d+)\s+%s(\S[^\r\n]*)\.mp3[\r\n]". All formats can be changed by editing the regular expressions and the name and then clicking OK. They will be stored in the kid3rc file in the configuration directory. This file can be directly edited to have more import formats or it can be deleted to revert to the default formats.

To check whether the imported tracks match the current set of files, the duration of the imported tracks can be compared with the duration of the files. This option can be enabled with the checkbox Check maximum allowable time difference and the maximum tolerated difference in time can be set in seconds. If a mismatch in a length or in the number of tracks is detected, it will be reported and the import can be canceled.

File->Create Playlist

Creates an M3U playlist. The file will be stored in the opened directory and have the same name as the directory, followed by an .m3u extension. The file simly contains the names of the files displayed in the file listbox, no special EXTM3U or EXTINFO lines are generated. If all files of an album are stored in a separate directory, this function can be used to generate a playlist for an album.

File->Quit (Ctrl-Q)

Quits the application.

The Tools Menu

Tools->Apply Format

When Format while editing is switched off in the configuration dialog, this menu item can be used to apply the configured format to the selected files. This can also be used to check whether the file and tag names conform with the configured format by applying the format to all saved files and then checking if any files were changed (and therefore marked with an asterisk in the file listbox).

Tools->Rename Directory...

This dialog offers the possibility to automatically rename the currently open directory according to the tags in the files. Several formats are preconfigured to include information about artist, album and year in the directory name. It is also possible to set a custom format, the following special codes are used to insert tag values into the directory name:

  • %s Title (Song)

  • %a Artist

  • %l Album

  • %c Comment

  • %y Year

  • %t Track

  • %g Genre

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

The Settings Menu

Settings->Show Toolbar

Toggles displaying of the toolbar, which contains icons to open and save a directory.

Settings->Show Statusbar

Toggles displaying of the statusbar, which displays longer actions such as opening or saving a directory.

Settings->Configure Kid3...

Opens the configuration dialog, which is used to set the format for the strings in the tag fields and the filename.

When Format while editing is checked, the format configuration is automatically used while editing text in the line edits. The format can be set separately for filenames and ID3 tags. The Case Conversion can be set to No changes, All lowercase, All uppercase, First letter uppercase or All first letters uppercase. The string replacement list can be set to arbitrary string mappings. To add a new mapping, select the From cell of a row and insert the text to replace, then go to the To column and enter the replacement text. To remove a mapping set the From cell to an empty value (e.g. by first typing space and then backspace). Inserting and deleting rows is also possible using a context menu which appears when the right mouse button is clicked. Replacement is only active, if the String Replacement checkbox is checked.

Settings->Configure Shortcuts...

Opens a dialog to assign keyboard shortcuts for most of the program functions. There are even functions without corresponding menu or button available, e.g. next file, previous file, select all.

The Help Menu

Help->Kid3 Handbook

Opens this handbook.

Help->About Kid3

Displays a short information about Kid3.

Chapter 4. Credits and License

Kid3

Program written by Urs Fleisch <ufleisch at users.sourceforge.net>

This documentation is licensed under the terms of the GNU Free Documentation License.

This program is licensed under the terms of the GNU General Public License.

Appendix A. Installation

How to obtain Kid3

Kid3 can be found at http://kid3.sourceforge.net.

Requirements

Kid3 needs id3lib and Qt. KDE is recommended but not necessary, as Kid3 can also be compiled as a Qt application. Kid3 can be compiled for systems where these libraries are available, e.g. for Linux and Windows.

Kid3 was tested with

SuSE Linux 7.3: id3lib 3.8.0pre1, id3lib 3.8.0, id3lib 3.8.2, KDE 2.2.2, KDE 3.0.4, Qt 2.3.2, Qt 3.0.5

SuSE Linux 8.1: id3lib 3.8.0, KDE 3.0.5, KDE 3.1.1, Qt 2.3.2, Qt 3.0.5, Qt 3.1.2

SuSE Linux 8.2: id3lib 3.8.2, id3lib 3.8.3, KDE 3.1.x, KDE 3.2.x, Qt 3.1.x, Qt 3.2.x, Qt 3.3.2

Windows NT 4.0: id3lib 3.8.0, id3lib 3.8.2, id3lib 3.8.3, non-commercial Qt version 2.3.0.

Compilation and Installation

You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple Qt application and lacks some configuration and session features.

Go into the top directory and type

% ./configure
% make
% make install

To compile for different versions of Qt or KDE, set the corresponding configure options.

To speed up compilation, Kid3 can use precompiled headers with GCC 3.4. Start configure with the option --enable-gcc-pch (and setting CC and CXX to gcc and g++ of GCC 3.4 if it is not the default compiler). The create a precompiled system include file with make pch.

The Qt application can also be compiled for Windows. In the kid3 directory, type

> nmake /f kid3.mak

Configuration

With KDE, the file name filter and format, the import formats, the filename and ID3 formats, the toolbar and statusbar settings as well as the window size will be be saved in the standard location in file kid3rc. As a Qt application, this file is in the .qt directory, with older releases of Qt, a file kid3.cfg is created.