Chapter 3. Command Reference

The GUI Elements

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

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

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

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

  • Ctrl+Shift+V: From other tag

  • Ctrl+C: Copy

  • Ctrl+V: Paste

  • Shift+Delete: Remove

  • F2: Edit

  • Insert: Add

  • Delete: Delete

File List

The file list contains the names of all the files in the opened folder which match the selected file name filter (typically *.mp3 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). A single or multiple files can be selected. To select no file, click into the empty area after the listbox entries. The selection determines the files which are affected by the operations which are available by using the buttons described below.

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

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

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

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

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

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

  • Collapse all: Collapses all folder trees

  • Rename: Changes the name of a file

  • Move to Trash: Moves a file to the trash

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

  • Edit: Edit a playlist, see Edit Playlist.

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

Edit Playlist

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

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

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

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

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

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

Folder List

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

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

File

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

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

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

  • %s %{title} Title (Song)

  • %a %{artist} Artist

  • %l %{album} Album

  • %c %{comment} Comment

  • %y %{year} Year

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

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

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

  • %g %{genre} Genre

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

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

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

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

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

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

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

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

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

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

  • Artist - Album/Track Song

  • Album/Track - Artist - Song

  • /Artist - Album - Track - Song

  • Album/Artist - Track - Song

  • Album/Artist - Song

  • Artist/Album/Track Song

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

Tag 1

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

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

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

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

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

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

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

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

Tag 2

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

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

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

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

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

Delete: Deletes the selected frame in the selected files.

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

Tag 3

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

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

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

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

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

Frame List

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

Table 3.1. Mapping of Unified Frame Types to Various Formats

UnifiedID3v2.3ID3v2.4MP4ASFVorbisRIFF
TitleTIT2TIT2©namTitleTITLEINAM
ArtistTPE1TPE1©ARTAuthorARTISTIART
AlbumTALBTALB©albWM/AlbumTitleALBUMIPRD
CommentCOMMCOMM©cmtDescriptionCOMMENTICMT
DateTYERTDRC©dayWM/YearDATEICRD
Track NumberTRCKTRCKtrknWM/TrackNumberTRACKNUMBERIPRT or ITRK
GenreTCONTCON©genWM/GenreGENREIGNR
Album ArtistTPE2TPE2aARTWM/AlbumArtistALBUMARTIST 
ArrangerIPLSTIPLARRANGERWM/ProducerARRANGERIENG
AuthorTOLYTOLYAUTHOR AUTHOR 
BPMTBPMTBPMtmpoWM/BeatsPerMinuteBPMIBPM
Catalog NumberTXXX:CATALOGNUMBERTXXX:CATALOGNUMBER  CATALOGNUMBER 
CompilationTCMPTCMPcpil COMPILATION 
ComposerTCOMTCOM©wrtWM/ComposerCOMPOSERIMUS
ConductorTPE3TPE3CONDUCTORWM/ConductorCONDUCTOR 
CopyrightTCOPTCOPcprtCopyrightCOPYRIGHTICOP
DescriptionTIT3TIT3descWM/SubTitleDescriptionDESCRIPTION 
Disc NumberTPOSTPOSdiskWM/PartOfSetDISCNUMBER 
Encoded-byTENCTENC©encWM/EncodedByENCODED-BYITCH
Encoder SettingsTSSETSSE©tooWM/EncodingSettingsENCODERSETTINGSISFT
Encoding Time TDEN WM/EncodingTimeENCODINGTIMEIDIT
GroupingGRP1GRP1©grp GROUPING 
Initial KeyTKEYTKEY WM/InitialKeyINITIALKEY 
ISRCTSRCTSRCISRCWM/ISRCISRCISRC
LanguageTLANTLANLANGUAGEWM/LanguageLANGUAGEILNG
LyricistTEXTTEXTLYRICISTWM/WriterLYRICISTIWRI
LyricsUSLTUSLT©lyrWM/LyricsLYRICS 
MediaTMEDTMEDSOURCEMEDIA SOURCEMEDIAIMED
Mood TMOO WM/MoodMOOD 
Original AlbumTOALTOALORIGINALALBUMWM/OriginalAlbumTitleORIGINALALBUM 
Original ArtistTOPETOPEORIGINALARTISTWM/OriginalArtistORIGINALARTIST 
Original DateTORYTDORORIGINALDATEWM/OriginalReleaseYearORIGINALDATE 
PerformerIPLSTMCLPERFORMER PERFORMERISTR
PictureAPICAPICcovrWM/PictureMETADATA_BLOCK_PICTURE 
PublisherTPUBTPUBPUBLISHERWM/PublisherPUBLISHERIPUB
RatingPOPMPOPMrateWM/SharedUserRatingRATINGIRTD
Release CountryTXXX:RELEASECOUNTRYTXXX:RELEASECOUNTRY  RELEASECOUNTRYICNT
Release Date TDRLRELEASEDATE RELEASEDATE 
RemixerTPE4TPE4REMIXERWM/ModifiedByREMIXERIEDT
Sort AlbumTSOATSOAsoalWM/AlbumSortOrderALBUMSORT 
Sort Album ArtistTSO2TSO2soaa ALBUMARTISTSORT 
Sort ArtistTSOPTSOPsoarWM/ArtistSortOrderARTISTSORT 
Sort ComposerTSOCTSOCsoco COMPOSERSORT 
Sort NameTSOTTSOTsonmWM/TitleSortOrderTITLESORT 
Subtitle TSSTSUBTITLEWM/SubTitleSUBTITLEPRT1
WebsiteWOARWOARWEBSITEWM/AuthorURLWEBSITEIBSU
WorkTIT1TIT1©wrkWM/ContentGroupDescriptionWORK 
WWW Audio FileWOAFWOAF WM/AudioFileURLWWWAUDIOFILE 
WWW Audio SourceWOASWOAS WM/AudioSourceURLWWWAUDIOSOURCE 

Remarks concerning the mappings to unified frame names:

  • The number of unified frame names is limited by the fact that a sensible mapping shall be possible for all supported file formats. Most tags support frames with arbitrary names; these will be used if no specific frame is available (e.g. the names in uppercase in the column MP4). If no such possibility exists, some frame types may not be supported for the format, e.g. Author and Performer for ASF (WMA).

  • The mappings are not chosen arbitrarily, they are geared to the usage of the frames in other applications and devices. Thus the ID3v2 frame "TPE2 - Band/orchestra/accompaniment" does not suggest its usage as Album Artist, but this is commonly used. The actual meaning for ID3v2 on the other hand is the reason why this frame is used for the orchestra when importing (e.g. from Discogs), although this may seem a bit strange for other tag formats.

  • The mappings are not always bijective. So ID3v2.3 uses an IPLS frame for both Arranger and Performer. When reading back, both frames are displayed as "Arranger".

  • The frames Arranger and Performer use a particular format for their contents: "involvement 1|involvee 1|involvement 2|involvee 2|...", for instance "Chorus Master|Ernst Dunshirn|Soprano Vocals|Anna Netrebko". This will create IPLS (ID3v2.3) or TIPL/TMCL (ID3v2.4) frames with a string list in the specified format (the "|" is used as a separator between the strings). Values in this format are also set when importing data from servers which offer this information.

  • To explicitly use a specific frame name which conflicts with a unified frame name, prepend an exclamation mark. For example, adding a frame of type "Media" to a Vorbis comment will create a frame with name "SOURCEMEDIA" because of the unified type mapping. In order to add a frame with name "MEDIA" and not "SOURCEMEDIA", use "!MEDIA" to force the explicit name.

  • If you need a frame which is not in this list, you still have the possibility to enter arbitrary names using the Add button. Often used frame names can be added to the Custom Frames in the Tags configuration, and will then be available in the Quick Access Frames.

Synchronized Lyrics and Event Timing Codes

For information synchronized with the audio data, a specific editor is 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.

A file having an ID3v2 tag is selected, the lyrics editor is entered using Add and selecting Synchronized Lyrics. For an existing Synchronized Lyrics frame, it is selected and Edit is clicked. The player is automatically opened with the current file so that the file can be played and paused to synchronize lyrics.

The settings at the top of the SYLT editor normally do not have to be changed. If the lyrics contains characters which are not present in the Latin 1 character set, changing the text encoding to UTF16 (or UTF8 for ID3v2.4.0) is advisable. For English lyrics and maximum compatibility, ISO-8859-1 should be used.

The Lyrics section has five buttons at the top. Add will add a new time event in the table. The time is taken from the position of the player, thus adding an entry while playing the track will add a line for the currently played position. The events in the table have to be chronologically ordered, therefore the row will be inserted accordingly. Entries with an invalid time are treated specially: If the currently selected row has an invalid time, its time stamp will be replaced by the current time instead of adding a new row. If the current time is not invalid, the first row with an invalid time will be used if present. This behavior should facilitate adding time stamps if the lyrics text is already in the table but the time stamps are missing (which is the case when importing unsynchronized lyrics). Note that the invalid time is represented as 00:00.00, i.e. the same as the time at the absolute beginning of the track, which is not invalid. To make a time invalid, press the Delete key, or use Clear from the context menu. New rows inserted using Insert row from the context menu or created when importing unsynchronized lyrics with From Clipboard or Import also contain invalid time stamps. Rows in the table can be deleted by clicking the Delete button or 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 does not contain a square bracket in the first line, it is supposed to be a simple text file with unsynchronized lyrics. The lines from such a file are then imported having invalid time stamps. The time information can be added using the Add button or by manual entry. It is also possible to import lyrics via copy-paste using From Clipboard. Synchronized lyrics can be written to LRC files using Export. Note that only entries with valid time stamps will be exported and that the entries will be sorted by time. Entries with invalid time won't be stored in the SYLT frame either, so make sure to include all timing information before leaving the dialog.

The ID3 specification suggests a time stamp for each syllable. However most players only support the granularity of a line or sentence. To support both use cases, Kid3 follows the same conventions as SYLT Editor. Text which is entered into the table is assumed to start a new line unless it starts with a space or a hyphen. Exceptions to this rule are possible by starting 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 if the first entry starts with a line feed. If this is not the case, it is assumed that all entries are new lines and that no syllable continuations are used.

While the track is played, the row associated with the current playing position is highlighted, so that the correctness of the synchronization information can be verified. If an offset has to be added to one or more time stamps, this can be accomplished with the Add offset context menu. Negative values can be used to reduce the time. Using Seek to position in the context menu, it is possible to 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 LyricsEmbed 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), click From Clipboard.

  • Now all lines from the unsynchronized lyrics are in the table, all time stamps are invalid (0:0:0.00). You can delete empty entries beforehand.

  • 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 invalid timestamp comes, click Add or press Alt+A, 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.