KID3(1)

📦

version 3.10.1 · 9 versions

3.10.1 · ubuntu stonking (latest)
3.10.2 · nixos 26.05, nixpkgs unstable
3.9.7 · alpine 3.24
3.10.2 · arch rolling
3.9.1 · ubuntu jammy
3.9.5 · fedora 43, ubuntu noble
3.9.3 · debian bookworm
3.9.7 · fedora 44, ubuntu resolute
3.9.6 · debian trixie, opensuse-leap 16.0, ubuntu questing

, in ubuntu stonking

KID3(1) — The Kid3 Handbook 📚✨

Okay bestie, manual name: kid3, kid3-qt, kid3-cli. It's the Kid3 ID3 Tagger. No cap.

💖 NAME 💖

kid3, kid3-qt, kid3-cli — Kid3 ID3 Tagger

✨ 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 👑

--portable — Stores your config in the file kid3.ini inside the application folder. It's giving portable bestie energy.
FILE — If FILE is the path to a folder, that folder gets opened. If you pass one or more file paths, their common folder gets opened and those files get selected. Slay.

kid3

--help — Shows help about options.
--author — Shows author information.
--version — Shows version information.
--license — Shows 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 — Activates the D-Bus interface.
-c — Executes a command. You can use multiple -c options, they run in sequence. See the section about kid3-cli for the available commands.
-h|--help — Shows help about options and commands.

🌸 INTRODUCTION 🌸

Kid3 is an app for editing ID3v1 and ID3v2 tags in MP3 files, and it does it efficiently. Most MP3 players can edit these tags, but not in a very comfortable and efficient way. Kid3 also supports 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). Obsessed.

Kid3 does not grab nor encode MP3 files. It's targeted at editing ID3 tags of all files of an album efficiently, 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.

Editing 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[1], MusicBrainz[2], Discogs[3], Amazon[4] 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.

🦋 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[1], MusicBrainz[2], Discogs[3], Amazon[4] and other data sources
Export as CSV, HTML, playlist, Kover XML and other formats. Exported CSV files can be imported again.

Example Usage

Okay so imagine a folder with MP3 files from the album "Let's Tag" by the band "One Hit Wonder". The folder is named in the "artist - album" format, so here it's One Hit Wonder - Let's Tag. The folder has the tracks in the "track title.mp3" format. I think that's useful because 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, artist and album info is already in the folder name and does not have to be repeated in the filename. But back to the 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 File → Open 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 File → Save 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.

💅 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.

okay bestie, so to actually do stuff to a playlist, its file has to be selected in the file list first — no selection, no service. Edit from the context menu is what drops you into the dialog we're about to yap about all the way down below 👇, and Play is gonna fire up the media player with the tracks from that playlist. and it's not just those two: user actions can act on playlists as well, like Export Playlist Folder, which copies the files from a playlist straight into a folder. so handy 🫶

🗂️ Folder List 🗂️

this list holds the names of the folders inside the opened folder, plus the current (.) and the parent (..) folder. it's the fast lane, fr — you can hop to another folder without ever touching the Open command or doing drag and drop. 💅

and yes, column visibility, order and sorting can all be configured exactly as described in the section about the file list. ✨

🎧 File 🎧

this panel shows you the info about the encoding (MP3, Ogg, Opus, DSF, FLAC, MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV, AIFF), the bit rate, the sample rate, the channels, and the length of the file. the whole vibe check of your audio, basically 📊

the Name line edit holds the name of the file (when only a single file is selected). change that name and the file gets renamed the moment you use the Save command. iconic little rename pipeline ✨

the Format combo box + line edit is the format that gets 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 heads up 🚨 that folder has to already exist for the renaming to succeed. the following special codes 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

and no, the format codes are not restricted to the examples above. any frame name can be used — unified frame names like %{albumartist}, %{discnumber.1}, %{bpm}, or format specific names like %{popm}. go wild 💫

you can also prepend and append strings to a format code's replacement by putting them in double quotes inside the curly braces of that format code. these strings only land in the resulting string if the format code spits out a nonempty value. example time 🍓: if the file name should contain both the title and the subtitle, you could use %{title} [%{subtitle}] in the format string — but that would give you a string ending with [] if no subtitle frame exists for a file. to omit the brackets when there's no subtitle, use %{title}%{" ["subtitle"]"} instead. that version drops the brackets, the leading space and the subtitle if no subtitle exists. chef's kiss 👑

the list of available formats can be edited in the dialog that shows up when you click the Filename from tag button in the File tab of the settings.

a second Format combo box (with arrow down ⬇️) is the one that generates the tags from the filename. if the format of the filename doesn't match that pattern, a few other commonly used formats get tried. real ones, we don't leave you hanging 💜

some commonly used filename formats are already sitting in the combo box, but you can absolutely type some special format of your own into the line edit. main character behaviour 💅

that list of available formats gets edited in the dialog that appears when you click the Tag from filename button in the File tab of the settings.

internally, a regular expression is built from the format codes. so if you need advanced regular expressions, the format used to generate the tags from the filenames can be given as a complete regular expression with captures preceded by the format codes. e.g. to extract the track numbers without removal of leading zeros, a format like this works:

/%{track}(\d+) %{title}(.*)

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 doesn't match that 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 get 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. no middleman 🧚

🏷️ Tag 1 🏷️

the line edit widgets for Title, Artist, Album, Comment, Date, Track Number and Genre are what edit the corresponding value in the first tag of the selected files. the value gets changed when the file selection is altered, or before operations like Save and Quit, and only when the corresponding check box at the left of the field name is checked. this is lowkey so good for changing just some values and leaving the rest untouched 🎀

if a single file is selected, all check boxes are checked and the line edit widgets contain the values found in the tags of that file. if a tag isn't found in the file, the corresponding empty value is displayed — that's 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'll be set for the selected file after the selection is changed. the file then gets marked as modified by a disk symbol 💾 in the file listbox but stays untouched until the Save command is used.

if multiple files are selected, only the values which are identical in all selected files get displayed. in all other controls, those empty values described above show up instead. all check boxes are unchecked, to avoid unwanted changes — very "we're not touching anything you didn't ask for" of it 🙈. if a value has to be set for all selected files, edit it and set the check box. the values get set for all selected files when the selection changes and can be saved with 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. and 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. yes, symmetrical like that 🤝

From Tag 2 — the tag 1 fields get set from the corresponding values in tag 2. if a single file is selected, the GUI controls get filled with the values from tag 2. if multiple files are selected, the tags of the files are directly set.
Copy — fills the copy buffer with the Tag 1 values. only values with a checked check box will be used in subsequent Paste commands.
Paste — pastes the values from the copy buffer into the GUI controls.
Remove — sets all GUI controls to their empty values, which results in removing all values. the saved file will then contain no tag 1. poof, gone 💀

🎀 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. freedom fr 🦋

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. your genres, your rules 💅

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. it's giving ✨organized✨

Edit — opens a window which lets you 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 also works to add a frame to multiple selected files.
Delete — deletes the selected frame in the selected files.
Drag album artwork here — 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 right here. picture frames can be edited or added by double clicking on this control. album art slay 🖼️

🌈 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. ⚠️ note that one, it's a whole thing.

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

🎤 Synchronized Lyrics and Event Timing Codes 🎤

for information synchronized with the audio data, there's a specific editor available. these frames are supported for ID3v2.3.0 and ID3v2.4.0 tags. to add such a frame, the specific frame name has to be selected in the list which appears when the Add button is clicked — Synchronized Lyrics or Event Timing Codes, respectively. the editor is the same for both types: for the event timing codes, only a predefined set of events is available, whereas for the synchronized lyrics, text has to be entered. in the following, editing synchronized lyrics is explained.

So picture this, bestie: you've got a file with an ID3v2 tag selected, and to get into the lyrics editor you hit Add and pick Synchronized Lyrics. 💖 Already got a Synchronized Lyrics frame? Then just select it and click Edit. Kid3 will open the player for you automatically with the current file, so you can play and pause your way through getting those lyrics synced. ✨

The settings up at the top of the SYLT editor usually do not need to be touched, ngl. The one case where you do want to change something: if your lyrics have characters that aren't in the Latin 1 character set, it's advisable to switch the text encoding to UTF16 (or UTF8 for ID3v2.4.0). If your lyrics are English and you want maximum compatibility? Use ISO-8859-1, periodt.

The Lyrics section 💅

There are five buttons at the top:

Add — drops a new time event into the table. The time is taken from the position of the player, so if you add an entry while the track is playing, you'll get a line for the currently played position. The events in the table have to be chronologically ordered, so the row gets inserted in the right spot accordingly.
Entries with an invalid time are handled in their own special little way: if the currently selected row has an invalid time, its time stamp gets replaced with the current time instead of adding a new row. And if the current time isn't invalid, the first row with an invalid time gets used, if one is present. This is the behavior that makes adding time stamps actually bearable when the lyrics text is already sitting in the table but the time stamps are missing — which is exactly the situation you're in when you import unsynchronized lyrics. ⭐

Heads up: the invalid time is represented as 00:00.00 — which, yes, is the same as the time at the absolute beginning of the track, and that one is not invalid. To actually make a time invalid, press the Delete key, or use Clear from the context menu.

New rows you insert using Insert row from the context menu, or rows created when importing unsynchronized lyrics with From Clipboard or Import, also come with invalid time stamps. And you can delete rows in the table by clicking the Delete button or by using Delete rows from the context menu. 🗑️

Synchronized lyrics can be imported from a file using Import. The expected format is simple or enhanced LRC. If the selected file doesn't contain a square bracket in its first line, Kid3 assumes it's a simple text file with unsynchronized lyrics — and the lines from that file get imported with invalid time stamps, so you'll have to add the time information yourself with the Add button or by typing it in manually. You can also bring lyrics in via copy-paste using From Clipboard. 🫶

Synchronized lyrics can be written out to LRC files using Export. But note: only entries with valid time stamps get exported, and the entries will be sorted by time. Entries with invalid time won't be stored in the SYLT frame either, so make sure you've got all your timing information in there before you leave the dialog, okay??

The ID3 specification[5] suggests a time stamp for each syllable. But most players only support the granularity of a line or a sentence. To support both use cases, Kid3 follows the same conventions as SYLT Editor[6]:

Text entered into the table is assumed to start a new line — unless it starts with a space or a hyphen.
There are exceptions to this rule: start a line with an underscore (_) to force continuation, or a hash mark (#) to force a new line.
These escape characters are not stored inside the SYLT frame.
Inside the SYLT frame, new lines start with a line feed character (hex 0A), whereas continuations do not.
When reading SYLT frames, Kid3 checks whether the first entry starts with a line feed. If it doesn't, it assumes that all entries are new lines and that no syllable continuations are used.

While the track is playing, the row associated with the current playing position gets highlighted, so you can verify that your synchronization info is actually correct. 🌸 If you need to add an offset to one or more time stamps, do it with Add offset in the context menu — and yes, negative values work, they reduce the time. And with Seek to position in the context menu, you can set the playing position to the time of the selected row. 👑

Recommended procedure to add new synchronized lyrics

Get the unsynchronized lyrics, e.g. using Lyrics → Embed Lyrics from the file list context menu.
Copy the unsynchronized lyrics to the clipboard — just go to the Lyrics row in the frame table and press Ctrl+C.
Add a synchronized lyrics frame (Add..., Synchronized Lyrics, OK), then click From Clipboard.
Now all the lines from the unsynchronized lyrics are in the table, and all the time stamps are invalid (0:0:0.00). You can delete empty entries beforehand if you want.
Start playing the song by clicking the play button ► in the play toolbar at the bottom of the main window.
When the next lyrics line with an invalid timestamp comes up, click Add or press Alt+A — and the timestamp will be updated.
Continue like this until all timestamps are set. If you missed something, stop playback and clear the timestamps using the Delete key, or by selecting them and using Clear from the context menu. To restart playback from a given timestamp, use Seek to position from the context menu.

Chapters in MP4 Files

MP4 audiobooks typically have a .m4b extension and are rather large, because they cram all the chapters into a single file. 😭 To navigate around in files like that, they can contain chapter marks — and you can edit those in Kid3 using a pseudo "Chapters" frame with the exact same editor that's used for synchronized lyrics. There are two types of chapters in MP4 files: "Nero" and "QuickTime (QT)".

The chapter information in MP3 audiobooks is stored in multiple "Chapter" (CHAP) frames, which are referenced by a "Table of Contents" (CTOC) frame — and these frames have embedded subframes. To edit all of that in a single place, a pseudo "Chapters" frame can also be used for ID3v2 tags. Its contents are used to create the real chapter, table of contents and embedded frames:

The Description is used as the table of contents title.
The Text column contains the chapter titles.
The corresponding Time value will be the chapter start time and the end time of the preceding chapter.
The end time of last chapter is determined by the Time of the last row if its Text is empty.

`File → Open... (Ctrl+O)`

Opens a folder. All files matching the selected file name filter will be displayed in the file listbox, and the chosen file is selected.

`File → Open Recent`

Opens a recently opened folder. ✨

`File → Open Folder... (Ctrl+D)`

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

`File → Reload (F5)`

Reload folder. Modified files have to be saved before you do this. Expanded subfolders will be collapsed.

`File → Save (Ctrl+S)`

Saves all changed files in the folder. The changed files are marked with a disk symbol 💾 in the file listbox. If any file names have been changed, those files will be renamed.

`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 — otherwise 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 a MusicBrainz server, from Discogs, Amazon 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 Server: gnudb.org is selected. The artist and album name to search for can be entered in the two topmost fields; the albums which match the query will be displayed when Find is clicked and the results from www.gnudb.org[7] are received. Importing the track data for an album is done by double-clicking the album in the list. The freedb.org server to import from can be selected as well as the CGI path. The imported data is displayed in the preview table of the import dialog. When you're satisfied with the displayed tracks, they can be imported by terminating the import dialog with OK.

If you already have a search result open in the web browser, you can enter the URL into the first search field. The result will then appear in the album list and can be directly imported into Kid3. 🦋

An e-mail address registered at gnudb.org[8] can be entered into the Token field.

A search on the Discogs server can be performed using Discogs. As in the gnudb.org dialog, you can enter artist and album and then choose from a list of releases. A Token can be entered to use the RESTful Discogs API instead of their web interface — which is often changed, thereby breaking the import parser. 💀 You have to register for an account on Discogs[9] and then generate a token on their web site (Settings/Developers, Generate new token). Don't forget to Save Settings after entering the token in order to use it in subsequent requests too. If Standard Tags is marked, the standard information is imported, e.g. artist, album, and title. If Additional Tags is marked, more information is imported if available, e.g. performers, arrangers, or the publisher. If Cover Art is marked, cover art will be downloaded if available. 🎨

A search on Amazon can be performed using Amazon. As in the gnudb.org dialog, you can enter artist and album and then choose from a list of releases. If Additional Tags is marked, more information is imported if available, e.g. performers, arrangers, or the publisher. If Cover Art is marked, cover art will be downloaded if available.

You can search in the same way in the release database of MusicBrainz using From MusicBrainz Release. The workflow is the same as described for From gnudb.org. 💜

Import from a MusicBrainz server? Yes bestie, absolutely possible ✨ it uses the dialog that pops up when you pick From MusicBrainz Fingerprint. You pick the Server just like in the freedb import dialog, no biggie. Underneath there's a table showing the imported track data, and the right column is the state of the MusicBrainz query. When the dialog opens it starts at "Pending" — then the fingerprint gets looked up, and if that gives you nothing back, it tries another lookup using the tags already in the file. So lowkey, if you want a successful MusicBrainz query, it helps to store known info (like artist and album) in the tags before the import. If it found something, the search ends in the state "Recognized" 🎉 otherwise nothing was found, or there were multiple ambiguous results and you have to pick one yourself. OK and Apply use the imported data, Cancel closes the dialog. Heads up though — the closing can take a while, because the whole MusicBrainz machinery has to shut down 😭 it's giving dramatic exit.

For importing textual data, From File/Clipboard opens a subdialog with several preconfigured import formats ready to go 🎀

The first two, "CSV unquoted" and "CSV quoted", are for importing data that was exported by the Export dialog. You can edit that CSV data in a spreadsheet, and it shall be written using tabs as delimiters. Import should then be possible using "CSV quoted", which is more flexible than "CSV unquoted". That said, its fields cannot contain any double quotes 🚫. And if you only export from Kid3 and import later, "CSV unquoted" can be used as a simple format for exactly that purpose. Oh and also — there are "Export CSV" and "Import CSV" commands in the context menu of the file list, which use scripts to export and import CSV data in a more complete, powerful and flexible way 💅 iykyk.

Next up: "freedb HTML text" 🦋 you can use it to copy information from an HTML page of freedb.org[10]. Search an album in freedb, and if the info you want is displayed in the web browser, copy the contents to the clipboard. Then click the From Clipboard button and the imported tracks will show up in the preview table at the top of the dialog. If you're happy with the imported data, close the dialog with OK and it'll insert the data into the tags of the current folder. The destination (Tag 1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box. Your files in the current folder should be in the correct track order so their tags get assigned properly — which is the case if they're numbered 🔢.

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

More preconfigured formats are available, e.g. "Track Title Time". An empty custom format can be created with Add for the user to set up. 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(TM), which is most of what Perl offers 💅. Bracketing constructs (..) create capture buffers for the fields to import and are preceded by Kid3 specific codes to specify which field to capture. The codes are the same as used for the filename format, and besides the codes listed below, any frame name is possible:

%s %{title} — Title (Song)
%a %{artist} — Artist
%l %{album} — Album
%c %{comment} — Comment
%y %{year} — Year
%t %{track} — Track
%g %{genre} — Genre
%d %{duration} — Duration

For example, a track regular expression (second line) to import from an .m3u playlist could be:

"%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]"

All formats can be changed by editing the regular expressions and the name, then clicking Save Settings. They get stored in the kid3rc file in the configuration folder 🗂️. You can edit that file directly if you want more import formats, or delete it to revert to the default formats. Formats can be deleted using Remove.

Accuracy shows an estimation of how good the imported information matches the given tracks — it uses track durations or file names to calculate the level of similarity in percent 📊. Cover Art shows the URL of the album cover image which will be downloaded 🖼️.

To check whether the imported tracks match the current set of files, the duration of the imported tracks can be compared with the duration of the files. This option can be enabled with the check box Check maximum allowable time difference (sec): and the maximum tolerated difference in time can be set in seconds. If a mismatch in a length is detected, the length is displayed with a red background in the preview table 🚨.

If the files are ordered differently than the imported tracks, their assigned tracks have to be changed. This task can be facilitated using the Match with option with the buttons Length, Track and Title, which will reorder the tracks according to the corresponding field. To correct the assignments manually, a track can be dragged with the left mouse button while holding down the Ctrl key, and then dropped at the new location 🖱️.

If there are more imported tracks than files — for example if the current folder contains only the second disc of a two disc album but the tracks of both discs were imported — you can delete the tracks of the first disc like this:

Select them by clicking on the row label of the first track.
Then click on the row label of the last track of the first disc while holding down Shift.
Finally remove the tracks by pressing the Delete key.

When the import dialog is opened, it contains the actual contents of the tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using the Destination combo box. The button on the right of this combo box can be used to revert the table to the current contents of the tags. The check boxes in the first table column select which tracks are imported — super handy if a folder contains the tracks of both CDs of a double CD and you only want the tracks of the second CD 💿.

To identify the tracks which are imported, you can display the file names or the full paths to the files using the context menu of the table header. The values in the import table can be edited. That revert-button to the right of the Destination combo box can be used to restore the contents of the tags, which is also useful after changing the Destination ♻️.

Almost all dialogs feature a Save Settings button, which can be used to store the dialog specific settings and the window size persistently 💾 iconic.

From Tags leads to a subdialog to set tag frames from the contents of other tag frames. You can use it to simply copy information between tags, or extract a part from one frame and insert it in another 🧚.

Just like in the import from file/clipboard dialog, there are freely configurable formats to perform different operations. Already preconfigured are formats to:

copy the Album value to Album Artist, Composer or Conductor
extract the Track Number from Title fields which contain a number
extract a Subtitle from a Title field

Here's a little example explaining how to add a custom format which sets the information from the Subtitle field also in the Comment field 👑:

Create a new format using the Add button and set a new name, e.g. "Subtitle to Comment".
Then enter "%{subtitle}" in Source and "%{comment}(.*)" for Extraction.
Click Save Settings.

The expression in Source can contain format codes for arbitrary tag frames — multiple codes can be used to combine the contents from different frames. For each track, a text is generated from its tags using the Source format, and the regular expression from Extraction is applied to this text to set new values for the tags. Format codes are used before the capturing parentheses to specify the tag frame where the captured text shall be stored. It works in the same way as for the import from file/clipboard 💅.

Import from Tags... is also directly available from the File menu. The difference between these two functions is that the import dialog subdialog operates on all files of the current folder, whereas the menu function operates on the selected files (which can be in different folders). The menu function supports an additional code "%{__return}" to return the extracted value, which can be useful with the CLI and QML interfaces ✨.

File → Import from gnudb.org... — import from a freedb.org server using gnudb.org album search. This menu item opens the same import dialog as Import..., but opens directly the gnudb.org dialog 🌐
File → Import from Discogs... — import from the Discogs server. This menu item opens the same import dialog as Import..., but opens directly the From Discogs dialog 💿
File → Import from Amazon... — import from Amazon. This menu item opens the same import dialog as Import..., but opens directly the From Amazon dialog 📦
File → Import from MusicBrainz Release... — import from the MusicBrainz release database. This menu item opens the same import dialog as Import..., but opens directly the From MusicBrainz Release dialog 🎶
File → Import from MusicBrainz Fingerprint... — import from a MusicBrainz server. This menu item opens the same import dialog as Import..., but opens directly the From MusicBrainz Fingerprint dialog 🫆
File → Import from Tags... — like From Tags, but the import is applied to the selected files 🎯

File → Automatic Import... ✨

okay so Automatic Import is the one that lets you pull info for multiple albums at once from a whole bunch of web services 💖. If you've got folders selected in the file list, then the track data for those folders gets imported. If nothing's selected? Then it just goes and imports every folder in the file list. no cap.

The tag type — Tag 1, Tag 2, or Tag 1 and Tag 2 — is picked with the Destination combo box 🎀.

Profiles decide which servers get contacted to fetch album info. Some are already there for you: All, MusicBrainz, Discogs, Cover Art 🦋. Wanna make your own? Hit the Add button on the right of the Profile combo box, bestie.

The table underneath shows which servers get used when you import album info with the selected profile. Here's the tea ☕: the import process for an album is finished once all the required info has been found — so the order of the rows in the table actually matters. Change it with Move Up and Move Down. Edit lets you change an existing entry. The Server selection offers the same servers you can use in the import functions. Standard Tags, Additional Tags, and Cover Art decide what info shall be fetched from the server. And finally, Accuracy is the minimum accuracy that must be achieved to accept the imported data — if the accuracy isn't good enough, the next server in the list gets tried 🔥. The same dialog with the server properties pops up when you click Add to add a new server entry. Existing entries can be deleted with Remove.

To launch an automatic batch import with the selected profile, click Start. Details about the running import show up at the top of the dialog, and you can Abort the whole thing with the Abort button 💅.

File → Browse Cover Art... 🎨

The Browse Cover Art dialog is your bestie for finding album cover art 🫶. Artist/Album gets filled from the tags if possible. Source offers a whole variety of websites with album cover art — and the URL with artist and album as parameters is right there beneath the name. URL-encoded values for artist and album can be inserted using "%u{artist}" and "%u{album}", and other values from the tags work too, just like described in Configure Kid3, User Actions ✨.

Wanna add more sources? After the entry "Custom Source", replace "Custom Source" with the source's name, press Enter, then insert the URL, and finally press Save Settings. So iconic. The resulting browser command shows at the top of the dialog and can be started by clicking Browse. The browser (which you configure in the settings) launches with the selected source. Then you just drag a cover image from the browser into the Kid3 window and boom 💥 — it's set in the picture frame of the selected files.

Now, the messy part 😭: not all browsers support drag and drop of images, and pictures on websites often have a URL. In those cases Kid3 receives the URL, not the picture. If that URL points to a picture, it gets downloaded, easy. But if the URL refers to some other web resource, it has to be translated into the corresponding picture. Those mappings live in the table URL extraction. The left column Match holds a regular expression which gets compared with the URL — if it matches, the captured expressions in parentheses are inserted into the pattern of the right Picture URL column (at the positions marked with \1 etc.). That replaced regular expression contains the URL of the picture 🌈. So by this means, cover art can be imported from Amazon, Google Images, etc. using drag and drop. And yes, you can define your own mappings too. main character energy fr fr.

File → Export... 📤

The Export Dialog stores data from the tags into a file or onto the clipboard 💖. The editor at the top shows a preview of the data you're about to export. If the export data contain tabulator characters, the export is displayed in a table (cute). The data gets generated from the tags in the current folder according to the configured format.

The format settings are similar to the Import dialog: the topmost field contains the title (e.g. "CSV unquoted"), followed by the header, which is generated at the begin of the file. Then comes the track data — it's used for every track. Finally the trailer can be used to generate some finishing text 🎀.

Heads up tho: the format fields do not contain regular expressions like in the Import dialog. They only contain output format expressions with special %-expressions, which get replaced by values from the tags. The whole thing works like the file name format, and the same codes are used plus some additional codes 👑. And not only the codes listed below — all tag frame names can be used.

%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
%f %{file} — File name
%p %{filepath} — Path
%{modificationdate} — Modification date
%{creationdate} — Creation date
%u %{url} — URL
%{dirname} — Folder name
%d %{duration} — Duration in minutes:seconds
%D %{seconds} — Duration in seconds
%n %{tracks} — Number of tracks of the album
%e %{extension} — File extension
%O %{tag1} — The format of tag 1 (ID3v1.1 or empty if not existing)
%o %{tag2} — The format of tag 2 (ID3v2.3.0, ID3v2.4.0, ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not existing)
%b %{bitrate} — Bit rate in kbit/s
%v %{vbr} — VBR or empty (only for ID3v2.3 with id3lib)
%r %{samplerate} — Sample rate in Hz
%m %{mode} — Channel mode (Stereo or Joint Stereo)
%h %{channels} — Number of channels (1 or 2)
%k %{codec} — Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC, MPC, APE, ASF, AIFF, WAV)

A few formats are already predefined, like the little icons they are 🌟:

"CSV unquoted" separates the fields by tabs. Data in this format can be imported again into Kid3 using the import format with the same name 💅
"CSV quoted" additionally encloses the fields by double quotes, which eases the import into spreadsheet applications. > However, the fields shall not contain any double quotes when this format is used.
"Extended M3U" and "Extended PLS" generate playlists with extended attributes and absolute path names.
"HTML" can be used to generate an HTML page with hyperlinks to the tracks.
"Kover XML" creates a file which can be imported by the cover printing program Kover.
"Technical Details" provides information about bit rate, sample rate, channels, etc.
"Custom Format" is left empty for definition of a custom format.

You can define more formats of your own by adding lines in the file kid3rc in the configuration folder 💖. The other formats can be adapted to your needs.

The Source of the tags to generate the export data (Tag 1 or Tag 2) is selected with a combo box. Pushing To File or To Clipboard stores the data in a file or on the clipboard 📋. OK and Cancel close the dialog, whereas OK accepts the current dialog settings. slay.

File → Create Playlist... 🎵

Creates a playlist 💖. The format and contents of the playlist can be set by various options.

The name of the playlist can be the Same as folder name or use a Format with values from the tags, e.g. "%{artist} - %{album}" to have the artist and album name in the playlist file name 🎀. The format codes are the same as for Export. The list of available formats can be edited in the Format section of the Files tab in the settings. Create new empty playlist will make an empty playlist with the given name. The extension depends on the playlist format.

The location of the generated playlist is determined by the selection of the Create in combo box.

Current folder — The playlist is created in the current folder and contains only files of the current folder. The current folder is the folder where the current file is located. If multiple files are selected, the current file is probably the last selected file.
Every folder — A playlist is created in every folder which contains listed files, and each playlist contains the files of that folder.
Top-level folder — Only one playlist is created in the top-level folder (i.e. the folder of the file list) and it contains the listed files of the top-level folder and all of its sub-folders.

The Format of the playlist can be M3U, PLS or XSPF ✨.

If Include only the selected files is checked, only the selected files will be included in the playlist. If a folder is selected, all of its files are selected. If this check box is not activated, all audio files are included in the playlist 👑

Sort by file name selects the usual case where the files are ordered by file name. With Sort by tag field, it's possible to sort by a format string with values from tag fields 🔥. For instance, "%{track.3}" can be used to sort by track number (the .3 is used to get three digits with leading zeros because strings are used for sorting). It's also possible to use multiple fields, e.g. "%{genre}%{year}" to sort using a string composed of genre and year.

The playlist entries will have relative or absolute file paths depending on whether Use relative path for files in playlist or Use full path for files in playlist is set.

When Write only list of files is set, the playlist will only contain the paths to the files. To generate an extended playlist with additional information, a format string can be set using the Write info using control 💜.

File → Quit (Ctrl+Q)

Quits the application. bye bestie 😭💅

Edit → Select All (Alt+A)

Selects all files. all of them. every single one 💖

Edit → Deselect (Ctrl+Shift+A)

Deselects all files. (yes it's the anti-Select-All, we love a symmetrical queen 🫶)

Edit → Select All in Folder

Selects all files of the current folder 📁✨

Edit → Previous File (Alt+Up)

Selects the previous file ⬆️

Edit → Next File (Alt+Down)

Selects the next file ⬇️

Edit → Find... (Ctrl+F)

Find strings in the file names and the tags 🔍🌸. The Find dialog is a subset of the Replace dialog, which is described below. iykyk.

Edit → Replace... (`Ctrl`+`R`)

okay so this one opens a whole dialog that finds and replaces strings — and not just in the file names, bestie, in the tags too 💅. Double threat behavior.

Wanna keep it focused? The set of frames where the search is performed can be restricted — just deactivate the Select all check box and select the frames which shall be searched. There are also search options available: search backwards, search case sensitively, and use regular expressions ✨.

Real talk 🫶 depending on the number of files, the search might take some time. If it's giving loading screen forever, it can be aborted by closing the dialog. no cap.

Tools → Apply Filename Format

When Automatically apply format is switched off for the filename format over in the configuration dialog, this menu item can be used to apply the configured format to the names of the selected files. And plot twist — it's also a vibe check 👀: you can use it to check whether the file names conform with the configured format by applying the format to all saved files and then checking if any files were changed (they'd be marked with a disk symbol in the file listbox, iykyk).

Tools → Apply Tag Format

Same energy, but for the tags 💖. When Automatically apply format is switched off for the tag format in the configuration dialog, this menu item can be used to apply the configured format to the tags of the selected files. And yep, same check trick: you can use it to check whether the tags conform with the configured format by applying the format to all saved files and then checking if any files were changed (and therefore marked with a disk symbol in the file listbox).

Tools → Apply Text Encoding

Sets the Text encoding selected in Settings → Configure Kid3... → Tags section → Tag 2 tab for all selected files. Tiny caveat, don't @ me: if UTF8 is selected, UTF16 will be used for ID3v2.3.0 tags, because UTF8 is not supported for this format. periodt.

Tools → Rename Folder...

This dialog offers the possibility to automatically rename the currently open folder according to the tags in the files 🌸. Several formats are preconfigured to include information about artist, album and year in the folder name. You can also set a custom format and Edit the list of available formats. These special codes are the ones that insert tag values into the folder name:

%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
%{dirname} — Folder name (e.g. %{year" "}%{dirname} will prepend the year to the current folder name)
%{max-year} — The maximum year value found for this folder, can also be used with other codes than "year"
%{min-year} — The minimum year value found for this folder
%{unq-year} — The unique year value found for this folder or empty if not unique

If a folder separator "/" is found in the format, multiple folders are created ✨. And if what you actually want is to create a new folder instead of renaming the current folder, in the Action combo box select Create Folder instead of Rename Folder. The Source of the tag information can be chosen between Tag 1 and Tag 2, Tag 1 and Tag 2. A preview for the rename operation performed on the first file can be seen in the From and To sections of the dialog. Obsessed 🎀.

Multiple folders can be renamed by selecting them.

Tools → Number Tracks...

If the track numbers in the tags are not set or have the wrong values, this function can number the tracks automatically in ascending order. The start number can be set in the dialog. And if only part of the tracks have to be numbered, they must be selected first — selective queen behavior 👑.

When Total number of tracks is checked, the number of tracks will also be set in the tags.

It is possible to number the tracks over multiple folders. The folders have to be expanded and selected.

If Reset counter for each folder is checked, track numbering is restarted with the given number for each folder when multiple folders are selected.

The number tracks dialog can also be used to format existing track numbers without changing the values when the check box left to Start number is deactivated. The total number of tracks will be added if the corresponding check box is active, which can be used to set the total for all selected tracks. And if only formatting of the existing numbers is desired, this check box has to be deactivated too.

Tools → Filter...

The filter can be used to display only those files which match certain criteria 🦋. This is helpful if you want to organize a large collection and only edit those files which are not in the desired scheme. The expression defining which files to display uses the same format codes which are used in the file name format, import and export. So yes, same language, different font.

%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
%f, %{file} — File name
%p, %{filepath} — Absolute path to file
%e, %{extension} — File extension
%O, %{tag1} — The format of tag 1 (ID3v1.1 or empty if not existing)
%o, %{tag2} — The format of tag 2 (ID3v2.3.0, ID3v2.4.0, ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not existing)
%b, %{bitrate} — Bit rate in kbit/s
%v, %{vbr} — VBR or empty (only for ID3v2.3 with id3lib)
%r, %{samplerate} — Sample rate in Hz
%m, %{mode} — Channel mode (Stereo or Joint Stereo)
%h, %{channels} — Number of channels (1 or 2)
%k, %{codec} — Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC, MPC, APE, ASF, AIFF, WAV)
%w, %{marked} — Marked, is 1 if the file is marked (e.g. because of truncation or standard violation), empty otherwise
%1a, %1{artist}, ... — Use the prefix 1 to get values of tag 1
%2a, %2{artist}, ... — Use the prefix 2 to get values of tag 2

These codes are replaced with the values for the file, and the resulting strings can be compared with the following operations:

s1 equals s2 — true if s1 and s2 are equal.
s1 contains s2 — true if s1 contains s2, i.e. s2 is a substring of s1.
s matches re — true if s matches the regular expression re.

True expressions are replaced by 1, false by 0. True values are represented by 1, true, on and yes, false values by 0, false, off and no. Boolean operations are not, and, or (in this order of precedence) and can be grouped by parentheses. Genuinely such a clean little grammar, ngl 💅.

Some filter rules are predefined and can serve as examples for your own expressions 🌈:

All

When the file list is filtered — this is shown by "[filtered]" in the window title — and all files shall be displayed again, the filtering can be reverted using this filter. It uses an empty expression, but a true value would have the same effect.

Filename Tag Mismatch

not (%{filepath} contains "%{artist} - %{album}/%{track} %{title}")

Tests if the file path conforms with the file name format. This rule is automatically adapted if the file name format changes.

No Tag 1

%{tag1} equals ""

Displays only files which do not have a tag 1.

No Tag 2

%{tag2} equals ""

Displays only files which do not have a tag 2.

ID3v2.3.0 Tag

%{tag2} equals "ID3v2.3.0"

Displays only files which have an ID3v2.3.0 tag.

ID3v2.4.0 Tag

%{tag2} equals "ID3v2.4.0"

Displays only files which have an ID3v2.4.0 tag.

Tag 1 != Tag 2

not (%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist} equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals %2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre})

Displays files with differences between tag 1 and tag2.

Tag 1 == Tag 2

%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist} equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals %2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre}

Displays files with identical tag 1 and tag 2.

Incomplete

%{title} equals "" or %{artist} equals "" or %{album} equals "" or %{year} equals "" or %{tracknumber} equals "" or %{genre} equals ""

Displays files with empty values in the standard tags (title, artist, album, date, track number, genre).

No Picture

%{picture} equals ""

Displays only files which do not have a picture.

Marked

not (%{marked} equals "")

Displays only files which are marked because they violate the ID3 standard, are truncated or the picture is too large.

Custom Filter

To add your own filter, select this entry. For instance, if you want to have a filter for artists starting with "The", replace "Custom Filter" with the name "The Bands" and press Enter. Then insert the following expression into the line edit:

%{artist} matches "The.*"

Then click Save Settings. Click Apply to filter the files. All files processed are displayed in the text view, with a "+" for those who match the filter and a "-" for the others. When finished, only the files with an artist starting with "The" are displayed, and the window title is marked with "[filtered]". Main character filtering fr fr 💜.

Tools → Convert ID3v2.3 to ID3v2.4

If there are any ID3v2.3 tags in the selected files, they will be converted to ID3v2.4 tags. Quick warning bestie: frames which are not supported by TagLib will be discarded 💀. Only files without unsaved changes will be converted.

Tools → Convert ID3v2.4 to ID3v2.3

If there are any ID3v2.4 tags in the selected files, they will be converted to ID3v2.3 tags. Only files without unsaved changes will be converted.

🎧 Tools → Play

okay so this one opens a simple little toolbar whose entire job is playing audio files — it's giving mini media player energy ✨. What's in it:

buttons for the basic operations: Play/Pause, Stop playback, Previous Track, Next Track, Close
sliders for position and volume
a display of the current position

If multiple files are selected, the selected tracks are played. Else, all files will be played. That's the whole rule, no cap 🌈

Also cute detail: the time displayed can be toggled between elapsed and remaining time by clicking on the display. Obsessed 💅

Toggles displaying of the toolbar. On, off, your call bestie ✨

Settings → Show Statusbar

Toggles displaying of the statusbar — and that bar is the one displaying longer actions such as opening or saving a folder. So if you like knowing what's going on, keep it 🫶

Settings → Show Picture

Toggles displaying of the album cover art preview picture. Your lil cover art moment 🎀

Settings → Auto Hide Tags

Empty tags are automatically hidden if this option is active. The clutter? Gone 💅 And heads up: the File, Tag 1 and Tag 2 sections can be manually collapsed and expanded by clicking on the corresponding -/+ buttons. So you still have the wheel, you're just not forced to hold it.

Settings → Configure Shortcut keys...

Opens a dialog to assign keyboard shortcuts for most of the program functions ⌨️ And the slay part: there are even functions without corresponding menu or button available, e.g. next file, previous file, select all. iykyk — keyboard girlies stay winning ⭐

Settings → Configure Kid3...

Opens the configuration dialog, which consists of pages for tags, files, user actions, and network settings. Four whole areas of vibes.

Tag specific options can be found on the Tags page, which is itself separated into four tabs for Tag 1, Tag 2, Tag 3, and All Tags. Four tabs, four moods ✨

If Mark truncated fields is checked, truncated ID3v1.1 fields will be marked red 🚨 Here's the tea: the text fields of ID3v1.1 tags can only have 30 characters, the comment only 28 characters. Also the genre and track numbers are restricted, so that fields can be truncated when imported or transferred from ID3v2. Truncated fields and the file will be marked red, and the mark will be removed after the field has been edited. So it's a temporary scarlet letter, not a forever one 🫶

With Text encoding for ID3v1 it is possible to set the character set used in ID3v1 tags. This encoding is supposed to be ISO-8859-1, so it is recommended to keep this default value. However, there are tags around with different encoding, so it can be set here — and the ID3v1 tags can then be copied to ID3v2 which supports Unicode. Glow-up pipeline, we love to see it 💖

The check box Use track/total number of tracks format controls whether the track number field of ID3v2 tags contains simply the track number or additionally the total number of tracks in the folder.

When Genre as text instead of numeric string is checked, all ID3v2 genres will be stored as a text string even if there is a corresponding code for ID3v1 genres. If this option is not set, genres for which an ID3v1 code exists are stored as the number of the genre code (in parentheses for ID3v2.3). Thus the genre Metal is stored as "Metal" or "(9)" depending on this option. Genres which are not in the list of ID3v1 genres are always stored as a text string. The purpose of this option is improved compatibility with devices which do not correctly interpret genre codes 🔥

When WAV files with lowercase id3 chunk is checked, the RIFF chunk used to store ID3v2 tags in WAV files will be named "id3 " instead of "ID3 ". (yes bestie, the trailing space is literally part of the name 💀) By default, Kid3 and other applications using TagLib accept both the lowercase and the uppercase variant when reading WAV files, but they use "ID3 " when writing ID3v2 tags to WAV files. As there exist other applications which only accept "id3 " (e.g. JRiver Media Center and foobar2000), this option can be used to create tags which can be read by such applications.

When Mark standard violations is checked, ID3v2 fields which violate the standard will be marked red. Details about the violation are shown in a tooltip:

Must be unique
New line is forbidden
Carriage return is forbidden
Owner must be non-empty
Must be numeric
Must be numeric or number/total
Format is DDMM
Format is HHMM
Format is YYYY
Must begin with a year and a space character
Must be ISO 8601 date/time
Must be musical key, 3 characters, A-G, b, #, m, o
Must have ISO 639-2 language code, 3 lowercase characters
Must be ISRC code, 12 characters
Must be list of strings separated by '|'
Has excess white space

The ID3 standard documents are available online:

ID3 tag version 2.3.0[11]
ID3 tag version 2.4.0 - Main Structure[12]
ID3 tag version 2.4.0 - Native Frames[5]

Text encoding defines the default encoding used for ID3v2 frames and can be set to ISO-8859-1, UTF16, or UTF8. Careful though 🚨 UTF8 is not valid for ID3v2.3.0 frames; if it is set, UTF16 will be used instead. For ID3v2.4.0 frames, all three encodings are possible 💜

Version used for new tags determines whether new ID3v2 tags are created as version 2.3.0 or 2.4.0.

Track number digits is the number of digits in Track Number fields. Leading zeros are used to pad. For instance, with a value of 2 the track number 5 is set as "05" ✨

The combo box Comment field name is only relevant for Ogg/Vorbis and FLAC files and sets the name of the field used for comments. Different applications seem to use different names — "COMMENT" for instance is used by XMMS, whereas Amarok uses "DESCRIPTION". The chaos of it all 😭

The format of pictures in Ogg/Vorbis files is determined by Picture field name, which can be "METADATA_BLOCK_PICTURE" or "COVERART". The first is the official standard and uses the same format as pictures in FLAC tags. "COVERART" is an earlier unofficial way to include pictures in Vorbis comments. It can be used for compatibility with legacy players 🎀

The mode used when saving Matroska files can be selected with Write mode. It controls the trade-off between file size and write speed when saving tags, attachments and chapters to the file. For very large files and/or slow (network) filesystems, using Avoid insert will reduce write time significantly. There are three possible modes:

Compact — Write tags, attachments and chapters as compact as possible. This is the default mode.
Do not shrink — Do not shrink blocks when writing, add padding when content gets smaller. Allow inserts when content gets larger.
Avoid insert — Like Do not shrink but also avoid inserts for blocks which are not at the end of the file: Replace a growing non-last block with padding of the old size and append a new block at the end of the file.

If the Mark if larger than (bytes) check box is activated, files containing embedded album cover art exceeding the given size in bytes are marked red 🚨 This can be used to find files containing oversized pictures which are not accepted by some applications and players. The default value is 131072 bytes (128 KB).

Custom Genres can be used to define genres which are not available in the standard genre list, e.g. "Gothic Metal". Such custom genres will appear in the Genre combo box of Tag 2. For ID3v1.1 tags, only the predefined genres can be used. Sorry ID3v1.1 girlies 🙈

The list of custom genres can also be used to reduce the number of genres available in the Genre combo box to those typically used. So if your collection mostly contains music in the genres Metal, Gothic Metal, Ancient and Hard Rock, you can enter those genres and mark Show only custom genres. The Tag 2 Genre combo box will then only contain those four genres and you will not have to search through the complete genres list for them. In this example, only Metal and Hard Rock will be listed in the tag 1 genres list, because those two custom genres entries are standard genres. If Show only custom genres is not active, the custom genres can be found at the end of the genres list 💅

In Custom Frames, up to eight custom frame names can be defined, which can then be used like the unified frames, for example as quick access frames. Eight of them!! Count them ⭐

Quick Access Frames defines which frame types are always shown in the Tag 2 section. Such frames can then be added without first using the Add button. The order of these quick access frames can be changed by dragging and dropping items. Drag and drop is very main character behavior, honestly 👑

The combo box Track number field name is only relevant for RIFF INFO and sets the name of the field used for track numbers. Track numbers are not specified in the original RIFF standard, there are applications which use "ITRK", others use "IPRT". Pick your fighter 😭

Tag Format contains options for the format of the tags. Let me break it down bestie:

When Automatically apply format is checked, the format configuration is automatically used while editing text in the line edits.
Validation enables validators in the controls with track/total and date/time values.
The Case conversion can be set to No changes, All lowercase, All uppercase, First letter uppercase or All first letters uppercase.
To use locale-aware conversion between lowercase and uppercase characters, a locale can be selected in the combobox below.
The string replacement list can be set to arbitrary string mappings.
To add a new mapping, select the From cell of a row and insert the text to replace, then go to the To column and enter the replacement text.
When the text to replace starts and ends with a slash ("/"), a regular expression is used.
For regular expressions containing capturing groups, occurrences of \1, \2, ... in To are replaced with the string captured by the corresponding capturing group.
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 check box is checked. Periodt 💅

The Rating table holds the mapping from star ratings → the actual values that get stored in the tag, bestie. The frames that carry rating info are listed in the Rating row of the frame list. For those frames, you set the rating by picking a number of stars out of five. 🌟 Different tag formats and different apps use different values to map stars → the value stored in the tag, and to show the right number of stars, Kid3 looks up a map in this table. The lookup key is the frame name — like "RATING" for Vorbis comments, or "IRTD" for RIFF INFO. For ID3v2 tags, the key is a combo of the frame ID "POPM" of the Popularimeter frame plus its "Email" field, separated by a dot. So yeah, multiple keys exist for ID3v2, e.g. "POPM.Windows Media Player 9 Series" for the mapping Windows Media Player and Explorer use, and just plain "POPM" for POPM frames with an empty "Email" field. Since multiple entries for "POPM" can exist, their order matters. When Kid3 adds a new Popularimeter frame, it uses the first "POPM" entry to figure out what to write into the "Email" field. That value then decides which mapping gets used for star ratings. The first entry is also the fallback when no key was found — so it's the default entry. 👑

Besides the Name column holding the keys, the table has columns 1 through 5 for the values to store when you give that many stars. Flip it around and those values determine how many stars get displayed for a value stored in the frame. For instance, the row below has the values 1, 64, 128, 196, 255. The thresholds for how many stars get displayed sit between those values, and they're compatible with what Windows® Explorer does.

Table 1. Entry in Rating Table

POPM — 1 star: 1, 2 stars: 64, 3 stars: 128, 4 stars: 196, 5 stars: 255
Range — 1 star: 1-31, 2 stars: 32-95, 3 stars: 96-159, 4 stars: 160-223, 5 stars: 224-255

Over on the Files page you can tick the Load last-opened files check box so Kid3 opens and selects the last-selected file when it starts up next time. 🌈 Preserve file timestamp can be checked to keep the file modification time stamp. Filename for cover sets the name that gets suggested when an embedded image is exported to a file. With Text encoding (Export, Playlist) you set the encoding used when writing files. The default System can be changed, for example if playlists have to be used on a different device.

If Mark changes is active, changed fields get marked with a light gray label background. 💅

The File List section decides which files show up in the file list. A Filter can restrict the items in this list to files with supported extensions. To explicitly say which folders to show in the file list, or to exclude certain folders, use the Include folders and Exclude folders options. They can hold wildcard expressions — for instance */Music/* to include only the Music folder, or */iTunes/* to exclude the iTunes folder from the file list. If you need multiple such expressions, separate them with spaces or semicolons. ✨

The buttons Filename from tag and Tag from filename in the Format section open dialogs to edit the formats available in the Format combo boxes (with arrows up and down), which you'll find in the File section of the main window.

The Playlist button lets you edit the file name formats available in the Create Playlist dialog. 🎀

Filename Format contains options for the format of the filenames. The same options as in Tag Format are available.

On top of that, you can set the Maximum length allowed for file names. Most modern file systems cap out at 255 characters, but if you want to burn the files to CD, you should set the limit to 64. If Use for playlist and folder names is checked, the file name format also gets used when creating playlists and renaming folders.

The User Actions page has a table of the commands available in the context menu of the file list. For critical operations like deleting files, it's advisable to tick Confirm to pop up a confirmation dialog before running the command. 👀 Output can be ticked to see the output written by console commands (standard output and standard error). Name is the name displayed in the context menu. Command is the command line to execute. Arguments can be passed using these codes:

%F %{files} — File paths (a list if multiple files selected)
%f %{file} — File path to single file
%uF %{urls} — URLs (a list if multiple files selected)
%uf %{url} — URL to single file
%d %{directory} — Folder
%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
%b %{browser} — Command to start the web browser
%q %{qmlpath} — Base folder of provided QML files

The special code @separator can be set as a command to insert a separator into the user actions context menu. Menu items can be put into a submenu by wrapping them with @beginmenu and @endmenu commands. The submenu's name comes from the Name column of the @beginmenu command. 🗂️

To run QML scripts, @qml is used as the command name. The path to the QML script gets passed as a parameter. The provided scripts live in the folder %{qmlpath}/script/ (on Linux® typically /usr/share/kid3/qml/script/, on Windows qml/script/ inside the installation folder, and on macOS® in the app folder kid3.app/Contents/Resources/qml/script/). Custom scripts can be stored in any folder. If the QML code uses GUI components, @qmlview shall be used instead of @qml. Extra parameters are passed to the QML script where they'll be available through the getArguments() function. An overview of some functions and properties available in QML can be found in the appendix QML Interface. 🧚

The command inserted with %{browser} can be defined in the Web browser line edit above. Commands starting with %{browser} can be used to fetch info about the audio files from the web, for instance

%{browser} http://lyricwiki.org/%u{artist}:%u{title}

will query the lyrics for the current song in LyricWiki[13]. The "u" in %u{artist} and %u{title} is used to URL-encode the artist %{artist} and song %{title} information. It's easy to define your own queries the same way, e.g. an image search with Google[14]:

%{browser} http://images.google.com/images?q=%u{artist}%20%u{album}

To add album cover art to tag 2, you can search for images with Google or Amazon using the commands described above. The picture can be added to the tag with drag and drop. You can also add an image with Add, then select the Picture frame and import an image file or paste from the clipboard. Picture frames are supported for ID3v2, MP4, FLAC, Ogg and ASF tags. 🖼️

To add and delete entries in the table, a context menu can be used.

The Network page contains only a field to insert the proxy address and optionally the port, separated by a colon. The proxy gets used when importing from an Internet server, when the check box is checked. 🌐

In the Plugins page, available plugins can be enabled or disabled. The plugins are split into two sections. The Metadata Plugins & Priority list contains plugins that support audio file formats. The order of the plugins matters, because they're tried from top to bottom. Some formats are supported by multiple plugins, so files get opened with the first plugin that supports them. TaglibMetadata supports most formats, so if it's at the top of the list, it'll open most of the files. If you want a different plugin for a file format, make sure it's listed before the TaglibMetadata plugin. Details about the metadata plugins and why you might want them instead of TagLib are listed below. 💖

Id3libMetadata: Uses id3lib[15] for ID3v1.1 and ID3v2.3 tags in MP3, MP2, AAC files. Supports a few more frame types than TagLib.
OggFlacMetadata: Uses libogg[16], libvorbis, libvorbisfile[17] for Ogg files, and additionally libFLAC++ and libFLAC[18] for FLAC files. These are the official libraries for these formats.
TaglibMetadata: Uses TagLib[19] which supports a lot of audio file formats. It can be used for all audio files supported by Kid3.
Mp4v2Metadata: mp4v2[20] was originally used by Kid3 to support M4A files. Can be used in case of problems with the M4A support of TagLib.

The Available Plugins section lists the remaining plugins. Their order doesn't matter, but they can be enabled or disabled with the check boxes. ✨

AmazonImport: Used for the Import from Amazon... function.
DiscogsImport: Used for the Import from Discogs... function.
FreedbImport: Used for the Import from gnudb.org... function.
MusicBrainzImport: Used for the Import from MusicBrainz Release... function.
AcoustidImport: Used for the Import from MusicBrainz Fingerprint... function, which depends on the Chromaprint[21] and libav[22] libraries.

Plugins that are turned off just… don't load, bestie. That's the whole point — it saves your resources and makes startup zippier. ✨ Heads up though: everything on this page only kicks in after you restart Kid3. No restart, no vibe. 💅

Help → Kid3 Handbook — opens this very handbook. yes, the one you're reading. meta. 🦋
Help → About Kid3 — pops up a lil' bit of info about Kid3. short and sweet, like a story post.

🎧 KID3-CLI 🎧

💻 Commands 💻

kid3-cli is literally the command-line-interface for Kid3 — same energy, terminal edition. 🖤

Here's the tea on how it opens stuff:

give it a folder path → that folder gets opened.
give it one or more file paths → the common folder gets opened and those files get selected.
after that, every command you send works on those files.
commands come in through the -c option. 🫰
pass multiple commands and they run in the order you gave them, no cap.
if the commands change files, they get saved at the end. 💾
pass no command options at all? Then kid3-cli starts in interactive mode, where you type commands and they act on the current selection. yes bestie, you just chill in there and type.

The next sections list every command available. all of them. we're not skipping any. 👑

Help

help [COMMAND-NAME]

Shows you help for the parameters of COMMAND-NAME — or, if you don't name a command, help about all the commands. it's giving built-in tutor. 📚

Timeout

timeout [default | off | TIME]

Overwrites the default command timeout. The CLI commands bail out once their command-specific timeout expires. Here's the breakdown (write these down 📝):

10 seconds for ls and albumart
60 seconds for autoimport and filter
3 seconds for everything else

If you've got a huge number of files to process, those timeouts might be way too restrictive for you. So this command lets you set the timeout for all commands to TIME ms, switch it off entirely, or leave it at the default values. your call, bestie. 🕰️

Quit application

exit [force]

Exits the application. If you've got modified, unsaved files hanging around, you need the force parameter. otherwise it's not going anywhere. 😤

Change folder

cd [FOLDER]

no FOLDER? → changes to your home folder. 🏠
give it a folder? → changes into that folder.
give it one or more file paths? → changes to their common folder and selects those files.

Print the filename of the current folder

pwd

Prints the filename of the current working folder. classic. iconic. required. 💖

Folder list

ls

Lists what's inside the current folder — same as the file list in the Kid3 GUI. The five characters before each file name are the state report, so let's decode them:

> — the file is selected.
* — the file is modified.
1 — the file has a tag 1; otherwise a - shows up.
2 — the file has a tag 2; otherwise a - shows up.
3 — the file has a tag 3; otherwise a - shows up.

kid3-cli> ls
  1-- 01 Intro.mp3
> 12- 02 We Only Got This One.mp3
 *1-- 03 Outro.mp3

So in this example: every file has a tag 1, the second file also has a tag 2 and it's selected, and the third file is modified. see? the little characters are telling a whole story. 🕵️‍♀️

Save the changed files

save

that's it. that's the command. it saves the changed files. 🫡

Select file

select [all | none | first | previous | next | FILE...]

select everything → select all
deselect everything → select none
walk through the files in the current folder: start with select first, then go forward with select next or backward with select previous
wanna add specific files to the current selection? just hand over their file names. Wildcards work, so select *.mp3 selects every MP3 in the current folder. 🎯

kid3-cli> select first
kid3-cli> ls
> 1-- 01 Intro.mp3
  12- 02 We Only Got This One.mp3
 *1-- 03 Outro.mp3
kid3-cli> select next
kid3-cli> ls
  1-- 01 Intro.mp3
> 12- 02 We Only Got This One.mp3
 *1-- 03 Outro.mp3
kid3-cli> select *.mp3
kid3-cli> ls
> 1-- 01 Intro.mp3
> 12- 02 We Only Got This One.mp3
>*1-- 03 Outro.mp3

watch the > hop down the list. so satisfying. 😌

Select tag

tag [TAG-NUMBERS]

Lots of commands have an optional TAG-NUMBERS parameter that says whether the command works on tag 1, 2, or 3. Skip that parameter and the default tag numbers get used — and this command is how you set those defaults. 🙌

At startup it's set to 12, which means:

information is read from tag 2 if it's available, otherwise from tag 1
modifications are done on tag 2

TAG-NUMBERS can be set to 1, 2, or 3 to work only on that matching tag. And if you omit the parameter entirely? The current setting gets displayed. peek-a-boo. 👀

Get tag frame

get [all | FRAME-NAME] [TAG-NUMBERS]

Reads the value of one specific tag frame, or gives you info about all the tag frames (if you omit the argument or use all). Modified frames get marked with a *. ✨

kid3-cli> get
File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
  Name: 01 Intro.mp3
Tag 1: ID3v1.1
  Title         Intro
  Artist        One Hit Wonder
  Album         Let's Tag
  Date          2013
  Track Number  1
  Genre         Pop
kid3-cli> get title
Intro

Wanna save the contents of a picture frame to a file? bestie, use:

get picture:'/path/to/folder.jpg'

Wanna save synchronized lyrics to an LRC file? that's:

get SYLT:'/path/to/lyrics.lrc'

You can also grab just a specific field from a frame — for example get POPM.Email for the Email field of a Popularimeter frame. 👛

Got multiple frames of the same kind in one file? Index them with brackets. So the first performer from a Vorbis comment is get performer[0], the second is get performer[1]. numbering starts at zero, as is tradition.

There's a pseudo field name "selected" you can use to check whether a frame is selected — get artist.selected returns 1 if the artist frame is selected, otherwise 0. ✅

And there's a pseudo frame name "ratingstars" that gets you the value of the "rating" frame as the format specific value matching the number of stars (0 to 5). If you use "rating" instead, you get the internal value back. ⭐

Set tag frame

set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]

Sets the value of one specific tag frame. And if FRAME-VALUE is empty, the frame gets deleted. gone. poof. 💨

kid3-cli> set remixer 'O.H. Wonder'

Setting a picture frame from a file? literally:

set picture:'/path/to/folder.jpg' 'Picture Description'

Setting synchronized lyrics from an LRC file? go off:

set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'

Wanna set a specific field of a frame? put the field name after a dot. e.g. to set the Counter field of a Popularimeter frame, you'd use

set POPM.Counter 5

One real-world use for field specifications: you want a custom TXXX frame with the "rating" description instead of a standard Popularimeter frame (some plugins seem to roll that way). You can make that TXXX rating frame with kid3-cli, but here's the trick — you have to create a TXXX frame with the description "rating" first, and only then set the value of that frame to the rating value. order matters, bestie. 🧠

kid3-cli> set rating ""
kid3-cli> set TXXX.Description rating
kid3-cli> set rating 5

That first command deletes any existing POPM frame, because if a POPM frame is sitting there, set rating 5 would set the POPM frame and not the TXXX frame. 😭 Another route would be set TXXX.Text 5, but that one only works if there's no other TXXX frame present.

To set multiple frames of the same kind, drop an index in brackets. e.g. to set multiple performers in a Vorbis comment:

kid3-cli> set performer[0] 'Liza don Getti (soprano)'
kid3-cli> set performer[1] 'Joe Barr (piano)'

Wanna select certain frames before a copy, paste or remove action? use the pseudo field name "selected". Normally all frames are selected, so to deselect everything you'd do set '*.selected' 0, and then e.g. set artist.selected 1 to select the artist frame. checkbox queen. ☑️

Want the pseudo frame name "ratingstars"? That sets the value of the "rating" frame to the format specific value matching the number of stars (0 to 5). The frame name "rating" sets the internal value instead.

⚠️ BIG WARNING: setting "ratingstars" on multiple files that have different tag formats will not work, because the frame with the value mapped from the star count gets created for the first file and then reused for all the files. So instead of kid3-cli -c "set ratingstars 2" * you should really do for f in *; do kid3-cli -c "set ratingstars 2" "$f"; done. one by one, bestie. no shortcuts. 🙈

Revert

revert

Reverts all modifications in the selected files — or in all files if nothing is selected. undo button energy. ↩️

Import from file

import {FILE} {FORMAT-NAME} [TAG-NUMBERS]

Tags get imported from the file FILE in the format named FORMAT-NAME (e.g. "CSV unquoted", see Import). 📥

If tags is given for FILE, tags are imported from other tags. In that case you need SOURCE and EXTRACTION instead of the FORMAT-NAME parameters — see Import from Tags. And to apply the import from tags to the selected files, use tagsel instead of tags. This function also supports outputting the extracted value by using an EXTRACTION with the value %{__return}(.+). fancy. 🎀

Automatic import

autoimport [PROFILE-NAME] [TAG-NUMBERS]

Batch import using the profile PROFILE-NAME (see Automatic Import — "All" is used if you omit it). 🗂️

Download album cover artwork

albumart {URL} [all]

Sets the album artwork by downloading a picture from URL. The rules defined in the Browse Cover Art dialog are used to transform general URLs (like ones from Amazon) into a picture URL. 🌈

Wanna set the album cover from a local picture file instead? that's the set command's job, bestie.

kid3-cli> albumart
http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC

Export to file

export {FILE} {FORMAT-NAME} [TAG-NUMBERS]

Tags get exported to the file FILE in the format named FORMAT-NAME (e.g. "CSV unquoted", see Export). 📤

Create playlist

playlist

Creates a playlist in the format set in the configuration — see Create Playlist. 🎵

Apply filename format

filenameformat

Applies the file name format set in the configuration — see Apply Filename Format. 🏷️

Apply tag format

tagformat

Applies the tag name format set in the configuration — see Apply Tag Format. 💫

Apply text encoding

textencoding

Applies the text encoding set in the configuration — see Apply Text Encoding. 🔤

Rename folder

renamedir [FORMAT] [create | rename | dryrun] [TAG-NUMBERS]

(bestie, this one's mid-explanation — the rest is coming up next, don't go anywhere) 💖

Bestie, this command renames or creates folders straight from the values chillin' in your tags, shaped by whatever FORMAT you hand it — like %{artist} - %{album} (peep Rename Folder for the whole vibe). If you don't pass a format, it just uses whatever format is already set in the Rename folder dialog. Default mode is rename; to actually create folders you have to say create out loud, explicitly. And heads up: the rename actions happen immediately — so if you just wanna see what it would do without touching anything, use the dryrun option. 🫶

Number tracks

numbertracks [TRACK-NUMBER] [TAG-NUMBERS]

Numbers your selected tracks, starting at TRACK-NUMBER (and if you omit it, it starts at 1). Simple as that. ✨

Filter

filter [FILTER-NAME | FILTER-FORMAT]

Filters the files so only the ones matching FILTER-FORMAT are visible. You can also drop in the name of a predefined filter expression instead of writing an expression yourself — like "Filename Tag Mismatch" — see Filter for the full menu of those.

kid3-cli> filter '%{title} contains "tro"'
Started
  /home/urs/One Hit Wonder - Let's Tag
+ 01 Intro.mp3
- 02 We Only Got This One.mp3
+ 03 Outro.mp3
Finished
kid3-cli> ls
  1-- 01 Intro.mp3
  1-- 03 Outro.mp3
kid3-cli> filter All
Started
  /home/urs/One Hit Wonder - Let's Tag
+ 01 Intro.mp3
+ 02 We Only Got This One.mp3
+ 03 Outro.mp3
Finished
kid3-cli> ls
  1-- 01 Intro.mp3
  12- 02 We Only Got This One.mp3
  1-- 03 Outro.mp3

Convert ID3v2.3 to ID3v2.4

to24

Convert ID3v2.4 to ID3v2.3

to23

Filename from tag

fromtag [FORMAT] [TAG-NUMBERS]

Sets the file names of the selected files from values in the tags. Example: fromtag '%{track} - %{title}' 1. If you don't specify a format, it uses the one set in the GUI. 🎀

Tag from filename

totag [FORMAT] [TAG-NUMBERS]

Sets the tag frames from the file names. Example: totag '%{albumartist} - %{album}/%{track} %{title}' 2. No format specified? It uses the GUI one. And if your filename doesn't match that pattern, it'll try a few other commonly used formats too, so don't panic. 🦋

Tag to other tag

syncto {TAG-NUMBER}

Copies tag frames from one tag over to the other tag. Like, if you wanna set the ID3v2 tag from the ID3v1 tag, you'd go syncto 2. 💅

Copy

copy [TAG-NUMBER]

Copies the tag frames of the selected file into the internal copy buffer. Then you can slap them onto another file with the paste command. Iconic little duo, honestly.

And if you only wanna copy a subset of the frames? Use the "selected" pseudo field with the set command. For example, to copy just the disc number and copyright frames:

set '*.selected' 0
set discnumber.selected 1
set copyright.selected 1
copy

Paste

paste [TAG-NUMBER]

Sets tag frames from whatever's sitting in the copy buffer onto your selected files. 🍓

Remove

remove [TAG-NUMBER]

Removes a tag. Bye bestie. 👋

You can also remove just a subset of the frames by selecting them the same way described up in the copy command.

Configure Kid3

config [OPTION] [VALUE]

Query or set a configuration option. 👑

The OPTION is a group name and a property name glued together with a dot. Here's the tea:

No OPTION at all? All available groups get displayed.
Just a group name? All available properties of that group get shown.
Group name and property? The currently configured value pops up.
Wanna change the setting? Pass the new value as the second argument.

One thing to watch: if a setting's value is a list, every single list element has to be passed as an argument. Which means to append an element to an existing list, you have to pass all the existing elements followed by your new one. In that situation it's way easier to use the JSON mode, where you can just copy the current list and tack the new element onto the end. 🌈

Execute program or QML script

execute [@qml] {FILE} [ARGS]

Runs a QML script or an executable. ✨

Without @qml, a program gets executed with arguments. But when @qml is the first argument, the stuff after it is the QML script and its arguments. For example, you can export a folder's tags to the file export.csv like this:

kid3-cli -c "execute @qml
/usr/share/kid3/qml/script/ExportCsv.qml export.csv"
/path/to/folder/

Here export.csv is the argument for the ExportCsv.qml script, while /path/to/folder/ is the FILE argument for kid3-cli. Two different jobs, don't mix 'em up. 💖

Examples

Set a title containing an apostrophe. Commands passed to kid3-cli with -c have to be in quotes if they don't consist of just a single word. And if that command itself has an argument containing spaces, that argument has to be quoted too. In UNIX® shells you can use single or double quotes, but on the Windows Command Prompt it's important that the outer quoting uses double quotes, and inside those quotes you use single quotes. If the text inside the single quotes contains a single quote, it has to be escaped with a backslash character, like in this example:

kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder

Set the album cover in all files of a folder using the batch import function:

kid3-cli -c "autoimport 'Cover Art'" /path/to/folder

Remove comment frames and apply the tag format in both tags of all MP3 files of a folder:

kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
-c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3

Automatically import tag 2, synchronize to tag 1, set file names from tag 2 and finally create a playlist:

kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
  /path/to/folder/*.mp3

For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove the arranger frame:

kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
  -c "set arranger ''" /path/to/folder

This Python script uses kid3-cli to generate iTunes Sound Check iTunNORM frames from replay gain information. 🧚

#!/usr/bin/env python3
# Generate iTunes Sound Check from ReplayGain.
import os, sys, subprocess

def rg2sc(dirpath):
  for root, dirs, files in os.walk(dirpath):
    for name in files:
      if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
        fn = os.path.join(root, name)
        rg = subprocess.check_output([
          'kid3-cli', '-c', 'get "replaygain_track_gain"',
           fn]).strip()
        if rg.endswith(b' dB'):
          rg = rg[:-3]
        try:
          rg = float(rg)
        except ValueError:
          print('Value %s of %s in not a float' % (rg, fn))
          continue
        sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
        subprocess.call([
          'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])

if __name__ == '__main__':
  rg2sc(sys.argv[1])

JSON Format

So that parsing results from kid3-cli is less of a struggle, you can get the output in JSON format. 🎉

The rules, bestie:

When the request is in JSON format, the response will also be JSON.
A compact format of the request gives you a compact representation of the response.
If the request contains an "id" field, it's assumed to be a JSON-RPC request — so the response will contain a "jsonrpc" field and the "id" of the request.
The request format uses the same commands as the standard CLI; the "method" field holds the command, and the parameters (if any) go in the "params" list.
The response contains a "result" object, which can also be null if the corresponding kid3-cli command doesn't return a result.
If something goes wrong, an "error" object is returned with "code" and "message" fields, as used in JSON-RPC.

kid3-cli> {"method":"set","params":["artist","An Artist"]}
{"result":null}
kid3-cli> {"method":"get","params":["artist",2]}
{"result":"An Artist"}
kid3-cli> {"method": "get", "params": ["artist"]}
{
    "result": "An Artist"
}

kid3-cli> {"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}
{"id":"123","jsonrpc":"2.0","result":"An Artist"}

🌟 CREDITS AND LICENSE 🌟

Kid3

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

FDL[23]

GPL[24]

💾 INSTALLATION 💾

okay bestie, here's how you actually get this thing onto your machine. it's giving "slightly involved but so worth it" 💖

🌐 How to obtain Kid3

Kid3 can be found at https://kid3.kde.org. that's the link, that's the vibe, go get it 🦋

🧸 Requirements

Kid3 needs Qt(TM)[25]. KDE[26] is recommended but not necessary, because Kid3 can also be compiled as a Qt(TM) application. Kid3 can be compiled for systems where these libraries are available — e.g. for GNU/Linux®, Windows® and macOS®.

now here's the format-specific tea ☕:

🎵 to tag Ogg/Vorbis files you need libogg[16], libvorbis and libvorbisfile[17]
💿 for FLAC files: libFLAC++ and libFLAC[18]
🎧 id3lib[15] is used for MP3 files

These four formats are also supported by TagLib[19], which can also handle Opus, MPC, APE, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker modules. no cap, TagLib is the moment 👑

To import from acoustic fingerprints, Chromaprint[21] and libav[22] are used.

Kid3 is available for most Linux® distributions, Windows® and macOS®. Links can be found on https://kid3.kde.org. 🫶

🛠️ Compilation and Installation

You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple Qt(TM) application and lacks some configuration and session features. so like, know what you're signing up for 💅

For a KDE version, go into the top folder and type

% cmake .
% make
% make install

periodt. that's the whole build 🎀

To compile for different versions of Qt(TM) or KDE, set the corresponding cmake options.

⚠️ If not all libraries are present, Kid3 is built with reduced functionality. So you should take care to have all desired development packages installed, bestie.

On the other side, cmake-options control which libraries are compiled in. The default is:

-DWITH_TAGLIB:BOOL=ON -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON

These options can be disabled using OFF.

To build Kid3 as a Qt(TM) application without KDE, use the cmake option -DWITH_APPS=Qt. To build both a KDE and a Qt(TM) application, set -DWITH_APPS="Qt;KDE".

To use a specific Qt(TM) installation, set -DQT_QMAKE_EXECUTABLE=/path/to/qmake.

Generation of RPM-Packages is supported by the file kid3.spec. For Debian® Packages, run build.sh deb. 🔥

The Qt(TM) application can also be compiled for Windows® and macOS®. The script build.sh can be used to download and build all required libraries and create a Kid3 package. 🌈

⚙️ Configuration

With KDE, the settings are stored in .config/kid3rc, and the application state in .local/share/kid3/kid3staterc.

As a Qt(TM) application, this file is in .config/Kid3/Kid3.conf.

where stuff hides on other platforms, cause she's portable like that:

🪟 On Windows®, the configuration is stored in the registry.
🍎 on macOS®, in a plist file.

The environment variable KID3_CONFIG_FILE can be used to set the path of the configuration file. iykyk 💜

💖 D-BUS INTERFACE 💖

okay bestie, plot twist: on Linux® you can drive Kid3 with a D-Bus interface and run the whole thing from scripts. you can write those scripts in literally any language that has D-Bus bindings (Python says hi 👋), and — this is the cute part — you can drop them into User Actions to extend Kid3 itself. iconic behavior fr fr 🎀

✨ D-Bus Examples ✨

🐚 Shell

so let's say you want the artist in tag 2 of the current file to be "One Hit Wonder". here's the whole vibe:

dbus-send --dest=org.kde.kid3 --print-reply=literal \
/Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
string:'One Hit Wonder'

or, easier (and lowkey nicer), with Qt(TM)'s qdbus — and btw qdbusviewer lets you poke around the whole interface in a GUI like the little explorer it is 🫶:

qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
'One Hit Wonder'

🐍 Python

import dbus
kid3 = dbus.SessionBus().get_object(
  'org.kde.kid3', '/Kid3')
kid3.setFrame(2, 'Artist', 'One Hit Wonder')

🐪 Perl

use Net::DBus;
$kid3 = Net::DBus->session->get_service(
  "org.kde.kid3")->get_object(
  "/Kid3", "org.kde.Kid3");
$kid3->setFrame(2, "Artist", "One Hit Wonder");

🌈 D-Bus API 🌈

the whole D-Bus API lives in org.kde.Kid3.xml, and the Kid3 interface comes with the following methods. buckle up, there's a lot, but every single one is a slay 💅

📂 Open file or folder

boolean openDirectory(string path);

path — path to file or folder

Returns true if OK.

🧹 Unload the tags of all files which are not modified or selected

unloadAllTags(void);

💾 Save all modified files

boolean save(void);

Returns true if OK.

🚨 Get a detailed error message provided by some methods

string getErrorMessage(void);

Returns detailed error message.

↩️ Revert changes in the selected files

revert(void);

📥 Start an automatic batch import

boolean batchImport(int32 tagMask, string profileName);

tagMask — tag mask (bit 0 for tag 1, bit 1 for tag 2)
profileName — name of batch import profile to use

📁 Import tags from a file

boolean importFromFile(int32 tagMask, string path, int32 fmtIdx);

tagMask — tag bit (1 for tag 1, 2 for tag 2)
path — path of file
fmtIdx — index of format

Returns true if OK.

🔁 Import tags from other tags

importFromTags(int32 tagMask, string source, string extraction);

tagMask — tag bit (1 for tag 1, 2 for tag 2)
source — format to get source text from tags
extraction — regular expression with frame names and captures to extract from source text

🔂 Import tags from other tags on selected files

array importFromTagsToSelection(int32 tagMask, string source,
                                string extraction);

tagMask — tag bit (1 for tag 1, 2 for tag 2)
source — format to get source text from tags
extraction — regular expression with frame names and captures to extract from source text
returnValues — extracted value for "%{__return}(.+)"

🖼️ Download album cover art

downloadAlbumArt(string url, boolean allFilesInDir);

url — URL of picture file or album art resource
allFilesInDir — true to add the image to all files in the folder

📤 Export tags to a file

boolean exportToFile(int32 tagMask, string path, int32 fmtIdx);

tagMask — tag bit (1 for tag 1, 2 for tag 2)
path — path of file
fmtIdx — index of format

Returns true if OK.

🎧 Create a playlist

boolean createPlaylist(void);

Returns true if OK.

📜 Get items of a playlist

array getPlaylistItems(string path);

path — path to playlist file

Returns list of absolute paths to playlist items.

✍️ Set items of a playlist

boolean setPlaylistItems(string path, array items);

path — path to playlist file
items — list of absolute paths to playlist items

Returns true if OK, false if not all items were found and added or saving failed.

👋 Quit the application

quit(void);

✅ Select all files

selectAll(void);

❌ Deselect all files

deselectAll(void);

⏮️ Set the first file as the current file

boolean firstFile(void);

Returns true if there is a first file.

⏪ Set the previous file as the current file

boolean previousFile(void);

Returns true if there is a previous file.

⏩ Set the next file as the current file

boolean nextFile(void);

Returns true if there is a next file.

🥇 Select the first file

boolean selectFirstFile(void);

Returns true if there is a first file.

👈 Select the previous file

boolean selectPreviousFile(void);

Returns true if there is a previous file.

👉 Select the next file

boolean selectNextFile(void);

Returns true if there is a next file.

🎯 Select the current file

boolean selectCurrentFile(void);

Returns true if there is a current file.

🌲 Expand or collapse the current file item if it is a folder

boolean expandDirectory(void);

a file list item counts as a folder if getFileName() returns a name with '/' as the last character, iykyk.

Returns true if current file item is a folder.

🏷️ Apply the file name format

applyFilenameFormat(void);

🏷️ Apply the tag format

applyTagFormat(void);

🔤 Apply text encoding

applyTextEncoding(void);

📛 Set the folder name from the tags

boolean setDirNameFromTag(int32 tagMask, string format,
                          boolean create);

tagMask — tag mask (bit 0 for tag 1, bit 1 for tag 2)
format — folder name format
create — true to create, false to rename

Returns true if OK, else the error message is available using getErrorMessage().

🔢 Set subsequent track numbers in the selected files

numberTracks(int32 tagMask, int32 firstTrackNr);

tagMask — tag mask (bit 0 for tag 1, bit 1 for tag 2)
firstTrackNr — number to use for first file

🔍 Filter the files

filter(string expression);

expression — filter expression

🆙 Convert ID3v2.3 tags to ID3v2.4

convertToId3v24(void);

🆒 Convert ID3v2.4 tags to ID3v2.3

convertToId3v23(void);

Returns true if OK.

📍 Get path of folder

string getDirectoryName(void);

Returns absolute path of folder.

🗂️ Get name of current file

string getFileName(void);

Returns true absolute file name, ends with "/" if it is a folder.

✏️ Set name of selected file

setFileName(string name);

name — file name

The file will be renamed when the folder is saved.

🧩 Set format to use when setting the filename from the tags

setFileNameFormat(string format);

format — file name format

🎼 Set the file names of the selected files from the tags

setFileNameFromTag(int32 tagMask);

tagMask — tag bit (1 for tag 1, 2 for tag 2)

🔎 Get value of frame

string getFrame(int32 tagMask, string name);

tagMask — tag bit (1 for tag 1, 2 for tag 2)
name — name of frame (e.g. "artist")

to grab binary data like a picture, you can add the name of a file to write after the name, e.g. "Picture:/path/to/file". same deal for synchronized lyrics, e.g. "SYLT:/path/to/file" ✨

Returns value of frame.

🖊️ Set value of frame

boolean setFrame(int32 tagMask, string name, string value);

tagMask — tag bit (1 for tag 1, 2 for tag 2)
name — name of frame (e.g. "artist")
value — value of frame

for tag 2 (tagMask 2), if no frame with name exists, a new frame is added; if value is empty, the frame is deleted. to add binary data like a picture, a file can be added after the name, e.g. "Picture:/path/to/file". "SYLT:/path/to/file" can be used to import synchronized lyrics.

Returns true if OK.

📚 Get all frames of a tag

array of string getTag(int32 tagMask);

tagMask — tag bit (1 for tag 1, 2 for tag 2)

Returns list with alternating frame names and values.

ℹ️ Get technical information about file

array of string getInformation(void);

properties are Format, Bitrate, Samplerate, Channels, Duration, Channel Mode, VBR, Tag 1, Tag 2. properties which are not available are omitted.

Returns list with alternating property names and values.

📝 Set tag from file name

setTagFromFileName(int32 tagMask);

tagMask — tag bit (1 for tag 1, 2 for tag 2)

🔄 Set tag from other tag

setTagFromOtherTag(int32 tagMask);

tagMask — tag bit (1 for tag 1, 2 for tag 2)

📋 Copy tag

copyTag(int32 tagMask);

tagMask — tag bit (1 for tag 1, 2 for tag 2)

📌 Paste tag

pasteTag(int32 tagMask);

tagMask — tag bit (1 for tag 1, 2 for tag 2)

🗑️ Remove tag

removeTag(int32 tagMask);

tagMask — tag bit (1 for tag 1, 2 for tag 2)

🔃 Reparse the configuration

reparseConfiguration(void);

automated configuration changes are possible by modifying the configuration file and then reparsing the configuration. glow-up for your config, no cap 💅

▶️ Plays the selected files

playAudio(void);

🦋 QML INTERFACE 🦋

✨ QML Examples ✨

QML scripts can be invoked via the context menu of the file list and can be set in the tab User Actions of the settings dialog. the scripts sitting there? they're literally your built-in example library for writing custom ones, use them 🫶

QML uses JavaScript, so here's the obligatory "Hello World" — every coder's origin story:

import Kid3 1.0

Kid3Script {
  onRun: {
    console.log("Hello world, folder is", app.dirName)
    Qt.quit()
  }
}

so if you save this script as /path/to/Example.qml, the user command can be defined as @qml /path/to/Example.qml with name QML Test and Output checked. then you can start it with the QML Test item in the file list context menu, and the output shows up in the window. main character energy tbh 👑

unfortunate news bestie 😭 starting QML scripts with the qml command (like qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml) is broken in recent versions of Qt. not your fault. not mine either.

but!! kid3-cli offers an alternative way to run a QML script from the command line using its execute command, and it works:

kid3-cli -c "execute @qml /path/to/Example.qml"

Heads up bestie, we're still deep in QML land here 💖 — this is the rest of the QML stuff, so buckle up.

To list the titles in the tags 2 of all files in the current folder, the following script could be used:

import Kid3 1.0

Kid3Script {
  onRun: {
    app.firstFile()
    do {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        console.log(app.getFrame(tagv2, "title"))
      }
    } while (app.nextFile())
  }
}

If the folder contains many files, such a script might block the user interface for some time 😭 — for longer operations it should therefore take a little break from time to time, like, hydrate bestie. The alternative implementation below has the work for a single file moved out into a function. That function invokes itself with a timeout of 1 ms at the end, given that more files still have to be processed. This will ensure that the GUI remains responsive while the script is running. Iconic behaviour, honestly.

import Kid3 1.0

Kid3Script {
  onRun: {
    function doWork() {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        console.log(app.getFrame(tagv2, "title"))
      }
      if (!app.nextFile()) {
        Qt.quit()
      } else {
        setTimeout(doWork, 1)
      }
    }

    app.firstFile()
    doWork()
  }
}

When using app.firstFile() with app.nextFile(), all files of the current folder will be processed. If only the selected files shall be affected, use firstFile() and nextFile() instead — these are convenience functions of the Kid3Script component. The following example is a script which copies only the disc number and copyright frames of the selected file. Surgical. Precise. Ate.

import Kid3 1.1

Kid3Script {
  onRun: {
    function doWork() {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        app.setFrame(tagv2, "*.selected", false)
        app.setFrame(tagv2, "discnumber.selected", true)
        app.setFrame(tagv2, "copyright.selected", true)
        app.copyTags(tagv2)
      }
      if (!nextFile()) {
        Qt.quit()
      } else {
        setTimeout(doWork, 1)
      }
    }

    firstFile()
    doWork()
  }
}

More example scripts come with Kid3 and are already registered as user commands 🎀 so you literally don't have to do anything but click:

ReplayGain to SoundCheck (ReplayGain2SoundCheck.qml) — Create iTunNORM SoundCheck information from replay gain frames.
Resize Album Art (ResizeAlbumArt.qml) — Resize embedded cover art images which are larger than 500x500 pixels.
Extract Album Art (ExtractAlbumArt.qml) — Extract all embedded cover art pictures avoiding duplicates.
Embed Album Art (EmbedAlbumArt.qml) — Embed cover art found in image files into audio files in the same folder.
Embed Lyrics (EmbedLyrics.qml) — Fetch unsynchronized lyrics from web service.
Text Encoding ID3v1 (ShowTextEncodingV1.qml) — Helps to find the encoding of ID3v1 tags by showing the tags of the current file in all available character encodings.
ID3v1 to ASCII (Tag1ToAscii.qml) — Transliterate extended latin characters in the ID3v1 tag to ASCII.
English Title Case (TitleCase.qml) — Formats text in the tags to English title case.
Rewrite Tags (RewriteTags.qml) — Rewrite all tags in the selected files.
Export CSV (ExportCsv.qml) — Export recursively all tags of all files to a CSV file.
Import CSV (ImportCsv.qml) — Import recursively all tags of all files from a CSV file.
Export JSON (ExportJson.qml) — Export recursively all tags of all files to a JSON file.
Import JSON (ImportJson.qml) — Import recursively all tags of all files from a JSON file.
Export Playlist Folder (ExportPlaylist.qml) — Copy all files from a playlist into a folder and rename them according to their position.
QML Console (QmlConsole.qml) — Simple console to play with Kid3's QML API.

🦋 QML API 🦋

The API can be easily explored using the QML Console, which is available as an example script with a user interface. Go poke at it, it's genuinely the fun way to learn this.

🌸 Kid3Script 🌸

Kid3Script is a regular QML component located inside the plugin folder. You could use another QML component just as well. Using Kid3Script makes it easy to start the script function using the onRun signal handler. Moreover it offers some functions:

onRun — Signal handler which is invoked when the script is started
tagv1, tagv2, tagv2v1 — Constants for tag parameters
script — Access to scripting functions
configs — Access to configuration objects
getArguments() — List of script arguments
isStandalone() — true if the script was not started from within Kid3
setTimeout(callback, delay) — Starts callback after delay ms
firstFile() — To first selected file
nextFile() — To next selected file

💜 Scripting Functions 💜

As JavaScript and therefore QML too has only a limited set of functions for scripting, the script object has some additional methods, for instance:

script.properties(obj) — String with Qt properties
script.writeFile(filePath, data) — Write data to file, true if OK
script.readFile(filePath) — Read data from file
script.removeFile(filePath) — Delete file, true if OK
script.fileExists(filePath) — true if file exists
script.fileIsWritable(filePath) — true if file is writable
script.getFilePermissions(filePath) — Get file permission mode bits
script.setFilePermissions(filePath, modeBits) — Set file permission mode bits
script.classifyFile(filePath) — Get class of file (folder "/", symlink "@", exe "*", file " ")
script.renameFile(oldName, newName) — Rename file, true if OK
script.copyFile(source, dest) — Copy file, true if OK
script.makeDir(path) — Create folder, true if OK
script.removeDir(path) — Remove folder, true if OK
script.tempPath() — Path to temporary folder
script.musicPath() — Path to music folder
script.listDir(path, [nameFilters], [classify]) — List folder entries
script.system(program, [args], [msecs]) — Synchronously start a system command, [exit code, standard output, standard error] if not timeout
script.systemAsync(program, [args], [callback]) — Asynchronously start a system command, callback will be called with [exit code, standard output, standard error]
script.getEnv(varName) — Get value of environment variable
script.setEnv(varName, value) — Set value of environment variable
script.getQtVersion() — Qt version string, e.g. "5.4.1"
script.getDataMd5(data) — Get hex string of the MD5 hash of data
script.getDataSize(data) — Get size of byte array
script.dataToImage(data, [format]) — Create an image from data bytes
script.dataFromImage(img, [format]) — Get data bytes from image
script.loadImage(filePath) — Load an image from a file
script.saveImage(img, filePath, [format]) — Save an image to a file, true if OK
script.imageProperties(img) — Get properties of an image, map containing "width", "height", "depth" and "colorCount", empty if invalid image
script.scaleImage(img, width, [height]) — Scale an image, returns scaled image

✨ Application Context ✨

Using QML, a large part of the Kid3 functions are accessible. The API is similar to the one used for D-Bus. For details, refer to the respective notes. iykyk 💅

app.openDirectory(path) — Open folder
app.unloadAllTags() — Unload all tags
app.saveDirectory() — Save folder
app.revertFileModifications() — Revert
app.importTags(tag, path, fmtIdx) — Import file
app.importFromTags(tag, source, extraction) — Import from tags
app.importFromTagsToSelection(tag, source, extraction) — Import from tags of selected files
app.downloadImage(url, allFilesInDir) — Download image
app.exportTags(tag, path, fmtIdx) — Export file
app.writePlaylist() — Write playlist
app.getPlaylistItems(path) — Get items of a playlist
app.setPlaylistItems(path, items) — Set items of a playlist
app.selectAllFiles() — Select all
app.deselectAllFiles() — Deselect
app.firstFile([select], [onlyTaggedFiles]) — To first file
app.nextFile([select], [onlyTaggedFiles]) — To next file
app.previousFile([select], [onlyTaggedFiles]) — To previous file
app.selectCurrentFile([select]) — Select current file
app.selectFile(path, [select]) — Select a specific file
app.getSelectedFilePaths([onlyTaggedFiles]) — Get paths of selected files
app.requestExpandFileList() — Expand all
app.applyFilenameFormat() — Apply filename format
app.applyTagFormat() — Apply tag format
app.applyTextEncoding() — Apply text encoding
app.numberTracks(nr, total, tag, [options]) — Number tracks
app.applyFilter(expr) — Filter
app.convertToId3v23() — Convert ID3v2.4.0 to ID3v2.3.0
app.convertToId3v24() — Convert ID3v2.3.0 to ID3v2.4.0
app.getFilenameFromTags(tag) — Filename from tags
app.getTagsFromFilename(tag) — Filename to tags
app.getAllFrames(tag) — Get object with all frames
app.getFrame(tag, name) — Get frame
app.setFrame(tag, name, value) — Set frame
app.getPictureData() — Get data from picture frame
app.setPictureData(data) — Set data in picture frame
app.copyToOtherTag(tag) — Tags to other tags
app.copyTags(tag) — Copy
app.pasteTags(tag) — Paste
app.removeTags(tag) — Remove
app.playAudio() — Play
app.readConfig() — Read configuration
app.applyChangedConfiguration() — Apply configuration
app.dirName — Folder name
app.selectionInfo.fileName — File name
app.selectionInfo.filePath — Absolute file path
app.selectionInfo.detailInfo — Format details
app.selectionInfo.tag(Frame.Tag_1).tagFormat — Tag 1 format
app.selectionInfo.tag(Frame.Tag_2).tagFormat — Tag 2 format
app.selectionInfo.formatString(tag, format) — Substitute codes in format string
app.selectFileName(caption, dir, filter, saveFile) — Open file dialog to select a file
app.selectDirName(caption, dir) — Open file dialog to select a folder

For asynchronous operations, callbacks can be connected to signals 🫶

function automaticImport(profile) {
  function onAutomaticImportFinished() {
    app.batchImporter.finished.disconnect(onAutomaticImportFinished)
  }
  app.batchImporter.finished.connect(onAutomaticImportFinished)
  app.batchImport(profile, tagv2)
}

function renameDirectory(format) {
  function onRenameActionsScheduled() {
    app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
    app.performRenameActions()
  }
  app.renameActionsScheduled.connect(onRenameActionsScheduled)
  app.renameDirectory(tagv2v1, format, false)
}

✨ Configuration Objects ✨

okay so every different config section lives behind a method of configs 💅 you can literally just peek at what properties any of them has by listing them in the QML console like this:

script.properties(configs.networkConfig())

and bestie, you can set them too:

configs.networkConfig().useProxy = false

here's the whole roster of config sections, no gatekeeping 🫶:

configs.batchImportConfig()
configs.exportConfig()
configs.fileConfig()
configs.filenameFormatConfig()
configs.filterConfig()
configs.findReplaceConfig()
configs.guiConfig()
configs.importConfig()
configs.mainWindowConfig()
configs.networkConfig()
configs.numberTracksConfig()
configs.playlistConfig()
configs.renDirConfig()
configs.tagConfig()
configs.tagFormatConfig()
configs.userActionsConfig()

👑 AUTHOR 👑

Urs Fleisch <ufleisch at users.sourceforge.net>

Software development

🎀 COPYRIGHT 🎀

FDL

🌸 NOTES 🌸

okay so this is the citation list, aka the receipts ✨ every single one of these is linked in the text above, and yes you can absolutely go read them all, i believe in you:

gnudb.org — http://gnudb.org
MusicBrainz — http://musicbrainz.org
Discogs — http://discogs.com
Amazon — http://www.amazon.com
ID3 specification — http://id3.org/id3v2.4.0-frames
SYLT Editor — http://www.compuphase.com/software_sylteditor.htm
www.gnudb.org — http://www.gnudb.org
gnudb.org — https://gnudb.org/info.php
Discogs — https://www.discogs.com/
freedb.org — http://freedb.org
ID3 tag version 2.3.0 — http://id3.org/id3v2.3.0
ID3 tag version 2.4.0 - Main Structure — http://id3.org/id3v2.4.0-structure
LyricWiki — http://www.lyricwiki.org
Google — http://www.google.com
id3lib — http://id3lib.sourceforge.net
libogg — http://xiph.org/ogg/
libvorbis, libvorbisfile — http://xiph.org/vorbis/
libFLAC++ and libFLAC — http://flac.sourceforge.net
TagLib — http://taglib.github.io/
mp4v2 — https://mp4v2.org/
Chromaprint — http://acoustid.org/chromaprint
libav — http://libav.org/
FDL — http://www.gnu.org/licenses/licenses.html#FDL
GPL — http://www.gnu.org/licenses/licenses.html#GPL
Qt(TM) — https://www.qt.io
KDE — http://www.kde.org

and that's the whole page, bestie 😭🫶 you made it to the very end of the Kid3 3.10.1 manual, dated 2026-07-24, page KID3(1) — go tag something, mwah 💖✨

📦 where this page comes from

ubuntu stonking: kid3-core 3.10.1-3 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms

KID3(1)

KID3(1) — The Kid3 Handbook 📚✨

💖 NAME 💖

✨ SYNOPSIS ✨

👑 OPTIONS 👑

kid3

kid3-qt

kid3-cli

🌸 INTRODUCTION 🌸

🦋 USING KID3 🦋

Kid3 features

Example Usage

💅 COMMAND REFERENCE 💅

The GUI Elements

File List

Edit Playlist

🗂️ Folder List 🗂️

🎧 File 🎧

🏷️ Tag 1 🏷️

🎀 Tag 2 🎀

🌈 Tag 3 🌈

🎤 Synchronized Lyrics and Event Timing Codes 🎤

The Lyrics section 💅

Recommended procedure to add new synchronized lyrics

Chapters in MP4 Files

The File Menu 🎀

File → Open... (Ctrl+O)

File → Open Recent

File → Open Folder... (Ctrl+D)

File → Reload (F5)

File → Save (Ctrl+S)

File → Revert

File → Import...

File → Automatic Import... ✨

File → Browse Cover Art... 🎨

File → Export... 📤

File → Create Playlist... 🎵

File → Quit (Ctrl+Q)

The Edit Menu ✂️

Edit → Select All (Alt+A)

Edit → Deselect (Ctrl+Shift+A)

Edit → Select All in Folder

Edit → Previous File (Alt+Up)

Edit → Next File (Alt+Down)

Edit → Find... (Ctrl+F)

Edit → Replace... (Ctrl+R)

🛠 The Tools Menu

Tools → Apply Filename Format

Tools → Apply Tag Format

Tools → Apply Text Encoding

Tools → Rename Folder...

Tools → Number Tracks...

Tools → Filter...

Tools → Convert ID3v2.3 to ID3v2.4

Tools → Convert ID3v2.4 to ID3v2.3

🎧 Tools → Play

🎀 The Settings Menu 🎀

Settings → Show Toolbar

Settings → Show Statusbar

Settings → Show Picture

Settings → Auto Hide Tags

Settings → Configure Shortcut keys...

Settings → Configure Kid3...

🫶 The Help Menu 🫶

🎧 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

`File → Open... (Ctrl+O)`

`File → Open Recent`

`File → Open Folder... (Ctrl+D)`

`File → Reload (F5)`

`File → Save (Ctrl+S)`

`File → Revert`

`File → Import...`

Edit → Replace... (`Ctrl`+`R`)