The Kid3 Handbook

Urs Fleisch

Software development 

3.9.6

Abstract

Kid3 is an application to edit the ID3v1 and ID3v2 tags in MP3 files in an efficient way. Also tags in Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker modules (MOD, S3M, IT, XM) are supported. It is easy to set tags of multiple files to the same values (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

Synopsis
Options
kid3
kid3-qt
kid3-cli
1. Introduction
2. Using Kid3
Kid3 features
Example Usage
3. Command Reference
The GUI Elements
File List
Edit Playlist
Folder List
File
Tag 1
Tag 2
Tag 3
Frame List
Synchronized Lyrics and Event Timing Codes
Chapters in MP4 Files
The File Menu
The Edit Menu
The Tools Menu
The Settings Menu
The Help Menu
4. kid3-cli
Commands
Help
Timeout
Quit application
Change folder
Print the filename of the current folder
Folder list
Save the changed files
Select file
Select tag
Get tag frame
Set tag frame
Revert
Import from file
Automatic import
Download album cover artwork
Export to file
Create playlist
Apply filename format
Apply tag format
Apply text encoding
Rename folder
Number tracks
Filter
Convert ID3v2.3 to ID3v2.4
Convert ID3v2.4 to ID3v2.3
Filename from tag
Tag from filename
Tag to other tag
Copy
Paste
Remove
Configure Kid3
Execute program or QML script
Examples
JSON Format
5. Credits and License
A. Installation
How to obtain Kid3
Requirements
Compilation and Installation
Configuration
B. D-Bus Interface
D-Bus Examples
D-Bus API
Open file or folder
Unload the tags of all files which are not modified or selected
Save all modified files
Get a detailed error message provided by some methods
Revert changes in the selected files
Start an automatic batch import
Import tags from a file
Import tags from other tags
Import tags from other tags on selected files
Download album cover art
Export tags to a file
Create a playlist
Get items of a playlist
Set items of a playlist
Quit the application
Select all files
Deselect all files
Set the first file as the current file
Set the previous file as the current file
Set the next file as the current file
Select the first file
Select the previous file
Select the next file
Select the current file
Expand or collapse the current file item if it is a folder
Apply the file name format
Apply the tag format
Apply text encoding
Set the folder name from the tags
Set subsequent track numbers in the selected files
Filter the files
Convert ID3v2.3 tags to ID3v2.4
Convert ID3v2.4 tags to ID3v2.3
Get path of folder
Get name of current file
Set name of selected file
Set format to use when setting the filename from the tags
Set the file names of the selected files from the tags
Get value of frame
Set value of frame
Get all frames of a tag
Get technical information about file
Set tag from file name
Set tag from other tag
Copy tag
Paste tag
Remove tag
Reparse the configuration
Plays the selected files
C. QML Interface
QML Examples
QML API
Kid3Script
Scripting Functions
Application Context
Configuration Objects

List of Tables

3.1. Mapping of Unified Frame Types to Various Formats
3.2. Entry in Rating Table

Synopsis

kid3 [ --help | --author | --version | --license | --desktopfile FILE ] [FILE...]

kid3-qt [--portable] [Qt-options] [FILE...]

kid3-cli [--portable] [--dbus] [ -h | --help ] [-c COMMAND1] [-c COMMAND2...] [FILE...]

Options

Table of Contents

kid3
kid3-qt
kid3-cli
--portable

Store configuration in file kid3.ini inside application folder.

FILE

If FILE is the path to a folder, it will be opened. If one or more file paths are given, their common folder is opened and the files are selected.

kid3

--help

Show help about options.

--author

Show author information.

--version

Show version information.

--license

Show license information.

--desktopfile FILE

The base file name of the desktop entry for this application.

kid3-qt

Qt-options

See qt5options(7).

kid3-cli

--dbus

Activate the D-Bus interface.

-c

Execute a command. Multiple -c options are possible, they are executed in sequence. See the section about kid3-cli for a description of the available commands.

-h|--help

Show help about options and commands.

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. Moreover the tags in Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker modules (MOD, S3M, IT, XM) are supported too.

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

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 gnudb.org, MusicBrainz, Discogs, Amazon 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 and ID3v2.4 frames

  • Edit tags of multiple files

  • Convert between ID3v1 and ID3v2 tags

  • Edit MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV and AIFF tags

  • Generate tags from filename

  • Generate tags from the contents of tag fields

  • Generate filename from tags

  • Generate and change folder names from tags

  • Generate playlist file

  • Automatic case conversion and string translation

  • Import from gnudb.org, MusicBrainz, Discogs, Amazon and other data sources

  • Export as CSV, HTML, playlist, Kover XML and other formats. Exported CSV files can be imported again.

Example Usage

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

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 FileOpen menu item (or toolbar button) and select one of the files in this folder. All files will be displayed in the file listbox. Lazy as we are, we want to use the information in the folder and file names to generate tags. Therefore we select all files, then click the To: Tag 1 button in the File 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 Date and select "Pop" from the Genre combobox. To set only these two values, their check boxes are automatically checked and all other check boxes are left unchecked. Now we change the selection by only selecting the first file and we see that all tags contain the correct values. The tags of the other files can be verified too by selecting them one by one. When we are satisfied with the tags, we use FileSave menu item (or toolbar button). Selecting File Create Playlist menu item (or toolbar button) will generate a file One Hit Wonder - Let's Tag.m3u in the folder.

Chapter 3. Command Reference

The GUI Elements

The Kid3 GUI is separated in six sections: At the left are the file and folder listboxes, the right side contains the File, Tag 1, Tag 2 and Tag 3 sections.

To navigate between the different sections using the keyboard, several keyboard shortcuts are supported. In the tag sections, the shortcuts are active while not editing text or when being in the first column.

  • Alt+Left: Go to previous section (Command+[ on macOS®)

  • Alt+Right: Go to next section (Command+] on macOS®)

  • Ctrl+Shift+V: From other tag

  • Ctrl+C: Copy

  • Ctrl+V: Paste

  • Shift+Delete: Remove

  • F2: Edit

  • Insert: Add

  • Delete: Delete

File List

The file list contains the names of all the files in the opened folder which match the selected file name filter (typically *.mp3 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). 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.

Besides Name, also other columns Size, Type, Date Modified with file details can be displayed. Columns can be hidden by unchecking their name in the context menu of the list header. The order of the columns can be changed by drag and drop. The sort order can be toggled by clicking on the column header.

The values of the standard tags can also be displayed and edited in columns of the file list.

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

Folders are displayed with a folder icon. If a folder is opened, its files are displayed in a hierarchical tree. By selecting files from subfolders, operations can be executed on files in different folders, which is useful if the music collection is organized with a folder for each artist containing folders for albums of this artist.

Clicking the right mouse button inside the file list opens a context menu with the following commands:

  • Expand all: Expands all folder trees (only the current tree if the Shift key is pressed)

  • Collapse all: Collapses all folder trees

  • Rename: Changes the name of a file

  • Move to Trash: Moves a file to the trash

  • Play: Plays a file, see Play. If the selected file is a playlist, the files of the playlist will be played.

  • Edit: Edit a playlist, see Edit Playlist.

  • The subsequent entries are user commands, which can be defined in the User Actions tab of Configure Kid3. The playback on double click can also be activated there.

    When Select file on play is activated, the currently played track is automatically selected in the file list.

Edit Playlist

A playlist can be created empty or containing the tracks of a folder, see Create Playlist. The playlist file created in such a way can be edited by double click or using Edit from the file list context menu. A dialog with the entries of the playlist is shown. It is possible to open multiple playlists simultaneously.

New entries can be added by drag and drop from the file list, a file manager or another playlist. If an entry is dragged from another playlist, it will be moved or copied depending on the system. To invoke the other operation, respectively, the Shift, Ctrl or Alt (to copy instead of move on macOS®) key has to be pressed. Reordering entries within the playlist is also possible via drag and drop. Alternatively, entries can be moved using the keyboard shortcuts Ctrl+Shift+Up and Ctrl+Shift+Down (on macOS® Command has to be pressed instead of Ctrl). An entry can be removed using the Delete key.

Please note the following: To drag entries from the file list, they have to be held at the left side (near the icons), the same gesture at the right side will perform a multi selection, such an action is hereby still easily possible.

When a playlist has been modified, the changes can be stored using Save or discarded using Cancel. When the window is closed, a confirmation prompt is shown if there are unsaved changes.

Tracks selected in a playlist will be automatically selected in the file list, thereby making it possible to edit their tags.

To execute actions on a playlist, its file must be selected in the file list. Edit from the context menu will lead to the dialog described in this section, and Play will start the media player with the tracks from the playlist. User actions can act on playlists, for example Export Playlist Folder, which copies the files from a playlist into a folder.

Folder List

The folder list contains the names of the folders in the opened folder, as well as the current (.) and the parent (..) folder. It allows one to quickly change the folder without using the Open command or drag and drop.

Column visibility, order and sorting can be configured as described in the section about the file list.

File

Shows information about the encoding (MP3, Ogg, Opus, DSF, FLAC, MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV, AIFF), bit rate, sample rate, channels and the length of the file.

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 first or the second tag. The filename can contain arbitrary characters, even a folder part separated by a slash from the file name, but that folder must already exist for the renaming to succeed. The following special codes are used to insert tag values into the filename:

  • %s %{title} Title (Song)

  • %a %{artist} Artist

  • %l %{album} Album

  • %c %{comment} Comment

  • %y %{year} Year

  • %t %{track} Track (e.g. 01)

  • %t %{track.n} Track with field width n (e.g. 001 for %{track.3})

  • %T %{tracknumber} Track (without leading zeros, e.g. 1)

  • %g %{genre} Genre

  • %{ignore} Ignored when generating tags from the file name

The format codes are not restricted to the examples given above. Any frame name can be used, for instance unified frame names like %{albumartist}, %{discnumber.1}, %{bpm} or format specific names like %{popm}.

It is possible to prepend and append strings to the replacement for a format code by adding them in double quotes inside the curly braces of a format code. These strings will only be put into the resulting string if the format code yields a nonempty value. For example, if the file name shall both contain the title and the subtitle, one could use %{title} [%{subtitle}] in the format string. But this would result in a string ending with [] if no subtitle frame exists for a file. In order to omit the brackets if no subtitle is present, %{title}%{" ["subtitle"]"} shall be used instead. This will omit the brackets, the leading space and the subtitle if not subtitle exists.

The list of available formats can be edited in the dialog which appears when clicking the Filename from tag button in the File tab of the settings.

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

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.

The list of available formats can be edited in the dialog which appears when clicking the Tag from filename button in the File tab of the settings.

Internally, a regular expression is built from the format codes. If advanced regular expressions are required, the format to generate the tags from the filenames can be given as a complete regular expression with captures which are preceded by the format codes, e.g. to extract the track numbers without removal of leading zeros, a format like "/%{track}(\d+) %{title}(.*)" could be used.

From: Tag 1, Tag 2: Sets the filename using the selected format and the first tag or the second tag, respectively.

To: Tag 1, Tag 2: The tags are set from the filename. First, the format specified in Format is used. If the existing filename does not match this format, the following formats are tried:

  • Artist - Album/Track Song

  • Album/Track - Artist - Song

  • /Artist - Album - Track - Song

  • Album/Artist - Track - Song

  • Album/Artist - Song

  • Artist/Album/Track Song

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

Tag 1

The line edit widgets for Title, Artist, Album, Comment, Date, Track Number and Genre are used to edit the corresponding value in the first tag of the selected files. The value will be changed when the file selection is altered or before operations like 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 Date and Track Number 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 a disk symbol 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 check box has to be set. The values will be set for all selected files when the selection is changed and can be saved using the Save command.

The check boxes also control the operation of most commands affecting the tags, such as copy, paste and transfer between tags 1 and 2. To make it easier to use with multiple files where all check boxes are unchecked, these commands behave in the same way when all check boxes are checked and when all check boxes are unchecked.

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

Copy: The copy buffer is filled with the Tag 1 values. Only values with checked check box 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 tag 1.

Tag 2

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

For the tag 2 Genre you can also use your own names besides the genres listed in the combo box, just type the name into the line edit.

The tag 2 cannot only contain the same values as the tag 1, the format is built in a flexible way from several frames which are themselves composed of several fields. The tag 2 table shows all the frames which are available in the selected file.

Edit: This will open a window which allows one to edit all fields of the selected frame. If multiple files are selected, the edited fields are applied to all selected files which contain such a frame.

Add: A requester to select the frame type will appear and a frame of the selected type can be edited and added to the file. This works also to add a frame to multiple selected files.

Delete: Deletes the selected frame in the selected files.

Drag album artwork here is shown if the file does not contain embedded cover art. A picture can be added using drag and drop from a browser or file manager and will be displayed here. Picture frames can be edited or added by double clicking on this control.

Tag 3

Some files can have more than two tags, and a third tag section is visible. The following file types can have such a Tag 3 section:

  • MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0) tag and in the third section an APE tag. Such APE tags are used for replay gain information. In the Tag 3 section, this information is visible, and the APE tag can be removed with the Remove button.

  • The RIFF INFO chunk of WAV files is available in the Tag 3 section because the Tag 1 section is dedicated to ID3v1.1 tags and handles their restrictions. The Tag 2 is still used for ID3v2.4.0 tags, which are also supported for WAV files, but RIFF INFO chunks seem to be supported better.

  • FLAC files normally use a Vorbis comment for their meta data. However, there are FLAC files which have ID3v1 and ID3v2 tags, which can be found in the Tag 1 and Tag 3 sections. ID3 tags in FLAC files are only supported by TagLib, therefore the OggFlacMetadata plugin has to be disabled in the Plugins tab of the settings.

The GUI controls work in the same way as in the Tag 2 section.

Frame List

Kid3 can edit most of the frames for all of the supported file types. Some frames are accessed using unified names, so that they can be exchanged between files with different formats. Frames which are not unified can be accessed as format specific frames.

Table 3.1. Mapping of Unified Frame Types to Various Formats

UnifiedID3v2.3ID3v2.4MP4ASFVorbisRIFF
TitleTIT2TIT2©namTitleTITLEINAM
ArtistTPE1TPE1©ARTAuthorARTISTIART
AlbumTALBTALB©albWM/AlbumTitleALBUMIPRD
CommentCOMMCOMM©cmtDescriptionCOMMENTICMT
DateTYERTDRC©dayWM/YearDATEICRD
Track NumberTRCKTRCKtrknWM/TrackNumberTRACKNUMBERIPRT or ITRK
GenreTCONTCON©genWM/GenreGENREIGNR
Album ArtistTPE2TPE2aARTWM/AlbumArtistALBUMARTIST 
ArrangerIPLSTIPLARRANGERWM/ProducerARRANGERIENG
AuthorTOLYTOLYAUTHOR AUTHOR 
BPMTBPMTBPMtmpoWM/BeatsPerMinuteBPMIBPM
Catalog NumberTXXX:CATALOGNUMBERTXXX:CATALOGNUMBER  CATALOGNUMBER 
CompilationTCMPTCMPcpil COMPILATION 
ComposerTCOMTCOM©wrtWM/ComposerCOMPOSERIMUS
ConductorTPE3TPE3CONDUCTORWM/ConductorCONDUCTOR 
CopyrightTCOPTCOPcprtCopyrightCOPYRIGHTICOP
DescriptionTIT3TIT3descWM/SubTitleDescriptionDESCRIPTION 
Disc NumberTPOSTPOSdiskWM/PartOfSetDISCNUMBER 
Encoded-byTENCTENC©encWM/EncodedByENCODED-BYITCH
Encoder SettingsTSSETSSE©tooWM/EncodingSettingsENCODERSETTINGSISFT
Encoding Time TDEN WM/EncodingTimeENCODINGTIMEIDIT
GroupingGRP1GRP1©grp GROUPING 
Initial KeyTKEYTKEY WM/InitialKeyINITIALKEY 
ISRCTSRCTSRCISRCWM/ISRCISRCISRC
LanguageTLANTLANLANGUAGEWM/LanguageLANGUAGEILN