1KID3(1) The Kid3 Handbook KID3(1)
2
6 kid3, kid3-qt, kid3-cli - Kid3 ID3 Tagger
7
9 kid3 [--help | --author | --version | --license | --desktopfile FILE]
10 [FILE...]
11 kid3-qt [--portable] [Qt-options] [FILE...]
13 kid3-cli [--portable] [--dbus] [-h | --help] [-c COMMAND1]
15 [-c COMMAND2...] [FILE...]
16
18 --portable
19 Store configuration in file kid3.ini inside application folder.
20 FILE
22 If FILE is the path to a folder, it will be opened. If one or more
23 file paths are given, their common folder is opened and the files
24 are selected.
25 kid3
27 --help
28 Show help about options.
29 --author
31 Show author information.
32 --version
34 Show version information.
35 --license
37 Show license information.
38 --desktopfile FILE
40 The base file name of the desktop entry for this application.
41 kid3-qt
43 Qt-options
44 See qt5options(7).
45 kid3-cli
47 --dbus
48 Activate the D-Bus interface.
49 -c
51 Execute a command. Multiple -c options are possible, they are
52 executed in sequence. See the section about kid3-cli for a
53 description of the available commands.
54 -h|--help
56 Show help about options and commands.
57
59 Kid3 is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
60 an efficient way. These tags can be edited by most MP3 players, but not
61 in a very comfortable and efficient way. Moreover the tags in
62 Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio,
63 WavPack, WMA, WAV, AIFF files and tracker modules (MOD, S3M, IT, XM)
64 are supported too.
65 Kid3 does not grab nor encode MP3 files, but it is targeted to edit the
67 ID3 tags of all files of an album in an efficient way, i.e. with as
68 few mouse clicks and key strokes as possible. Where most other programs
69 can edit either ID3v1 or ID3v2 tags, Kid3 has full control over both
70 versions, can convert tags between the two formats and has access to
71 all ID3v2 tags. Tags of multiple files can be set to the same value,
72 e.g. the artist, album, year and genre of all files of an album
73 typically have the same values and can be set together. If the
74 information for the tags is contained in the file name, the tags can be
75 automatically set from the file name. It is also possible to set the
76 file name according to the tags found in the file in arbitrary formats.
77 The editing task is further supported by automatic replacement of
79 characters or substrings, for instance to remove illegal characters
80 from filenames. Automatic control of upper and lower case characters
81 makes it easy to use a consistent naming scheme in all tags.
82 The tag information for full albums can be taken from gnudb.org[1],
84 MusicBrainz[2], Discogs[3], Amazon[4] or other sources of track lists.
85 The import format is freely configurable by regular expressions.
86 Please report any problems or feature requests to the author.
88
90 Kid3 features
91 • Edit ID3v1.1 tags
92 • Edit all ID3v2.3 and ID3v2.4 frames
94 • Edit tags of multiple files
96 • Convert between ID3v1 and ID3v2 tags
98 • Edit MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2,
100 Speex, TrueAudio, WavPack, WMA, WAV and AIFF tags
101 • Generate tags from filename
103 • Generate tags from the contents of tag fields
105 • Generate filename from tags
107 • Generate and change folder names from tags
109 • Generate playlist file
111 • Automatic case conversion and string translation
113 • Import from gnudb.org[1], MusicBrainz[2], Discogs[3], Amazon[4] and
115 other data sources
116 • Export as CSV, HTML, playlist, Kover XML and other formats.
118 Exported CSV files can be imported again.
119 Example Usage
121 This section describes a typical session with Kid3. Let's assume we
122 have a folder containing MP3 files with the tracks from the album
123 "Let's Tag" from the band "One Hit Wonder". The folder is named in the
124 "artist - album" format, in our case One Hit Wonder - Let's Tag. The
125 folder contains the tracks in the "track title.mp3" format, which I
126 think is useful because the filenames are short (important when using
127 mobile MP3 players with small displays) and in the correct order when
128 sorted alphabetically (important when using hardware MP3 players which
129 play the tracks in alphabetical order or in the order in which they are
130 burnt on CD and that order is alphabetical when using mkisofs). Besides
131 this, the artist and album information is already in the folder name
132 and does not have to be repeated in the filename. But back to our
133 example, the folder listing looks like this:
134 01 Intro.mp3
136 02 We Only Got This One.mp3
138 03 Outro.mp3
140 These files have no tags yet and we want to generate them using Kid3.
142 We use File → Open menu item (or toolbar button) and select one of the
143 files in this folder. All files will be displayed in the file listbox.
144 Lazy as we are, we want to use the information in the folder and file
145 names to generate tags. Therefore we select all files, then click the
146 To: Tag 1 button in the File section. This will set the title, artist,
147 album and track values in all files. To set the year and genre values
148 of all files, we keep all files selected and type in "2002" for the
149 Date and select "Pop" from the Genre combobox. To set only these two
150 values, their check boxes are automatically checked and all other check
151 boxes are left unchecked. Now we change the selection by only selecting
152 the first file and we see that all tags contain the correct values. The
153 tags of the other files can be verified too by selecting them one by
154 one. When we are satisfied with the tags, we use File → Save menu item
155 (or toolbar button). Selecting File → Create Playlist menu item (or
156 toolbar button) will generate a file One Hit Wonder - Let's Tag.m3u in
157 the folder.
158
160 The GUI Elements
161 The Kid3 GUI is separated in six sections: At the left are the file and
162 folder listboxes, the right side contains the File, Tag 1, Tag 2 and
163 Tag 3 sections.
164 To navigate between the different sections using the keyboard, several
166 keyboard shortcuts are supported. In the tag sections, the shortcuts
167 are active while not editing text or when being in the first column.
168 • Alt+Left: Go to previous section (Command+[ on macOS®)
170 • Alt+Right: Go to next section (Command+] on macOS®)
172 • Ctrl+Shift+V: From other tag
174 • Ctrl+C: Copy
176 • Ctrl+V: Paste
178 • Shift+Delete: Remove
180 • F2: Edit
182 • Insert: Add
184 • Delete: Delete
186 File List
188 The file list contains the names of all the files in the opened
189 folder which match the selected file name filter (typically *.mp3
190 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2
191 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). A single or multiple
192 files can be selected. To select no file, click into the empty area
193 after the listbox entries. The selection determines the files which
194 are affected by the operations which are available by using the
195 buttons described below.
196 Besides Name, also other columns Size, Type, Date Modified with
198 file details can be displayed. Columns can be hidden by unchecking
199 their name in the context menu of the list header. The order of the
200 columns can be changed by drag and drop. The sort order can be
201 toggled by clicking on the column header.
202 The values of the standard tags can also be displayed and edited in
204 columns of the file list.
205 At the left of the names an icon can be displayed: a disc to show
207 that the file has been modified or information about which tags are
208 present (V1, V2, V1V2 or NO TAG, no icon is displayed if the file
209 has not been read in yet).
210 Folders are displayed with a folder icon. If a folder is opened,
212 its files are displayed in a hierarchical tree. By selecting files
213 from subfolders, operations can be executed on files in different
214 folders, which is useful if the music collection is organized with
215 a folder for each artist containing folders for albums of this
216 artist.
217 Clicking the right mouse button inside the file list opens a
219 context menu with the following commands:
220 • Expand all: Expands all folder trees (only the current tree if
222 the Shift key is pressed)
223 • Collapse all: Collapses all folder trees
225 • Rename: Changes the name of a file
227 • Move to Trash: Moves a file to the trash
229 • Play: Plays a file, see Play. If the selected file is a
231 playlist, the files of the playlist will be played.
232 • Edit: Edit a playlist, see Edit Playlist.
234 • The subsequent entries are user commands, which can be defined
236 in the User Actions tab of Configure Kid3. The playback on
237 double click can also be activated there.
238 Edit Playlist
241 A playlist can be created empty or containing the tracks of a
242 folder, see Create Playlist. The playlist file created in such a
243 way can be edited by double click or using Edit from the file list
244 context menu. A dialog with the entries of the playlist is shown.
245 It is possible to open multiple playlists simultaneously.
246 New entries can be added by drag and drop from the file list, a
248 file manager or another playlist. If an entry is dragged from
249 another playlist, it will be moved or copied depending on the
250 system. To invoke the other operation, respectively, the Shift,
251 Ctrl or Alt (to copy instead of move on macOS®) key has to be
252 pressed. Reordering entries within the playlist is also possible
253 via drag and drop. Alternatively, entries can be moved using the
254 keyboard shortcuts Ctrl+Shift+Up and Ctrl+Shift+Down (on macOS®
255 Command has to be pressed instead of Ctrl). An entry can be removed
256 using the Delete key.
257 Please note the following: To drag entries from the file list, they
259 have to be held at the left side (near the icons), the same gesture
260 at the right side will perform a multi selection, such an action is
261 hereby still easily possible.
262 When a playlist has been modified, the changes can be stored using
264 Save or discarded using Cancel. When the window is closed, a
265 confirmation prompt is shown if there are unsaved changes.
266 Tracks selected in a playlist will be automatically selected in the
268 file list, thereby making it possible to edit their tags.
269 To execute actions on a playlist, its file must be selected in the
271 file list. Edit from the context menu will lead to the dialog
272 described in this section, and Play will start the media player
273 with the tracks from the playlist. User actions can act on
274 playlists, for example Export Playlist Folder, which copies the
275 files from a playlist into a folder.
276 Folder List
278 The folder list contains the names of the folders in the opened
279 folder, as well as the current (.) and the parent (..) folder. It
280 allows one to quickly change the folder without using the Open
281 command or drag and drop.
282 Column visibility, order and sorting can be configured as described
284 in the section about the file list.
285 File
287 Shows information about the encoding (MP3, Ogg, Opus, DSF, FLAC,
288 MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV,
289 AIFF), bit rate, sample rate, channels and the length of the file.
290 The Name line edit contains the name of the file (if only a single
292 file is selected). If this name is changed, the file will be
293 renamed when the Save command is used.
294 The Format combo box and line edit contains the format to be used
296 when the filename is generated from the first or the second tag.
297 The filename can contain arbitrary characters, even a folder part
298 separated by a slash from the file name, but that folder must
299 already exist for the renaming to succeed. The following special
300 codes are used to insert tag values into the filename:
301 • %s %{title} Title (Song)
303 • %a %{artist} Artist
305 • %l %{album} Album
307 • %c %{comment} Comment
309 • %y %{year} Year
311 • %t %{track} Track (e.g. 01)
313 • %t %{track.n} Track with field width n (e.g. 001 for
315 %{track.3})
316 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
318 • %g %{genre} Genre
320 • %{ignore} Ignored when generating tags from the file name
322 The format codes are not restricted to the examples given above.
324 Any frame name can be used, for instance unified frame names like
325 %{albumartist}, %{discnumber.1}, %{bpm} or format specific names
326 like %{popm}.
327 It is possible to prepend and append strings to the replacement for
329 a format code by adding them in double quotes inside the curly
330 braces of a format code. These strings will only be put into the
331 resulting string if the format code yields a nonempty value. For
332 example, if the file name shall both contain the title and the
333 subtitle, one could use %{title} [%{subtitle}] in the format
334 string. But this would result in a string ending with [] if no
335 subtitle frame exists for a file. In order to omit the brackets if
336 no subtitle is present, %{title}%{" ["subtitle"]"} shall be used
337 instead. This will omit the brackets, the leading space and the
338 subtitle if not subtitle exists.
339 The list of available formats can be edited in the dialog which
341 appears when clicking the Filename from tag button in the File tab
342 of the settings.
343 A second Format combo box (with arrow down) is used to generate the
345 tags from the filename. If the format of the filename does not
346 match this pattern, a few other commonly used formats are tried.
347 Some commonly used filename formats are already available in the
349 combo box, but it is also possible to type in some special format
350 into the line edit.
351 The list of available formats can be edited in the dialog which
353 appears when clicking the Tag from filename button in the File tab
354 of the settings.
355 Internally, a regular expression is built from the format codes. If
357 advanced regular expressions are required, the format to generate
358 the tags from the filenames can be given as a complete regular
359 expression with captures which are preceded by the format codes,
360 e.g. to extract the track numbers without removal of leading
361 zeros, a format like "/%{track}(\d+) %{title}(.*)" could be used.
362 From: Tag 1, Tag 2: Sets the filename using the selected format and
364 the first tag or the second tag, respectively.
365 To: Tag 1, Tag 2: The tags are set from the filename. First, the
367 format specified in Format is used. If the existing filename does
368 not match this format, the following formats are tried:
369 • Artist - Album/Track Song
371 • Album/Track - Artist - Song
373 • /Artist - Album - Track - Song
375 • Album/Artist - Track - Song
377 • Album/Artist - Song
379 • Artist/Album/Track Song
381 If a single file is selected, the GUI controls are filled with the
383 values extracted from the filename. If multiple files are selected,
384 the tags of the files are directly set according to the filenames.
385 Tag 1
387 The line edit widgets for Title, Artist, Album, Comment, Date,
388 Track Number and Genre are used to edit the corresponding value in
389 the first tag of the selected files. The value will be changed when
390 the file selection is altered or before operations like Save and
391 Quit and when the corresponding check box at the left of the field
392 name is checked. This is useful to change only some values and
393 leave the other values unchanged.
394 If a single file is selected, all check boxes are checked and the
396 line edit widgets contain the values found in the tags of this
397 file. If a tag is not found in the file, the corresponding empty
398 value is displayed, which is an empty string for the Title, Artist,
399 Album and Comment line edits, 0 for the numerical Date and Track
400 Number edits and an empty selected value for the Genre combo box.
401 The values can be changed and if the corresponding check box is
402 checked, they will be set for the selected file after the selection
403 is changed. The file is then marked as modified by a disk symbol in
404 the file listbox but remains unchanged until the Save command is
405 used.
406 If multiple files are selected, only the values which are identical
408 in all selected files are displayed. In all other controls, the
409 empty values as described above are displayed. All check boxes are
410 unchecked to avoid unwanted changes. If a value has to be set for
411 all selected files, it can be edited and the check box has to be
412 set. The values will be set for all selected files when the
413 selection is changed and can be saved using the Save command.
414 The check boxes also control the operation of most commands
416 affecting the tags, such as copy, paste and transfer between tags 1
417 and 2. To make it easier to use with multiple files where all check
418 boxes are unchecked, these commands behave in the same way when all
419 check boxes are checked and when all check boxes are unchecked.
420 From Tag 2: The tag 1 fields are set from the corresponding values
422 in tag 2. If a single file is selected, the GUI controls are filled
423 with the values from tag 2. If multiple files are selected, the
424 tags of the files are directly set.
425 Copy: The copy buffer is filled with the Tag 1 values. Only values
427 with checked check box will be used in subsequent Paste commands.
428 Paste: Pastes the values from the copy buffer into the GUI
430 controls.
431 Remove: This will set all GUI controls to their empty values which
433 results in removing all values. The saved file will then contain no
434 tag 1.
435 Tag 2
437 The GUI controls function in the same way as described for the Tag
438 1 section, but the size of the strings is not limited.
439 For the tag 2 Genre you can also use your own names besides the
441 genres listed in the combo box, just type the name into the line
442 edit.
443 The tag 2 cannot only contain the same values as the tag 1, the
445 format is built in a flexible way from several frames which are
446 themselves composed of several fields. The tag 2 table shows all
447 the frames which are available in the selected file.
448 Edit: This will open a window which allows one to edit all fields
450 of the selected frame. If multiple files are selected, the edited
451 fields are applied to all selected files which contain such a
452 frame.
453 Add: A requester to select the frame type will appear and a frame
455 of the selected type can be edited and added to the file. This
456 works also to add a frame to multiple selected files.
457 Delete: Deletes the selected frame in the selected files.
459 Drag album artwork here is shown if the file does not contain
461 embedded cover art. A picture can be added using drag and drop from
462 a browser or file manager and will be displayed here. Picture
463 frames can be edited or added by double clicking on this control.
464 Tag 3
466 Some files can have more than two tags, and a third tag section is
467 visible. The following file types can have such a Tag 3 section:
468 • MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0)
470 tag and in the third section an APE tag. Such APE tags are used
471 for replay gain information. In the Tag 3 section, this
472 information is visible, and the APE tag can be removed with the
473 Remove button.
474 • The RIFF INFO chunk of WAV files is available in the Tag 3
476 section because the Tag 1 section is dedicated to ID3v1.1 tags
477 and handles their restrictions. The Tag 2 is still used for
478 ID3v2.4.0 tags, which are also supported for WAV files, but
479 RIFF INFO chunks seem to be supported better.
480 • FLAC files normally use a Vorbis comment for their meta data.
482 However, there are FLAC files which have ID3v1 and ID3v2 tags,
483 which can be found in the Tag 1 and Tag 3 sections. ID3 tags in
484 FLAC files are only supported by TagLib, therefore the
485 OggFlacMetadata plugin has to be disabled in the Plugins tab of
486 the settings.
487 The GUI controls work in the same way as in the Tag 2 section.
489 Synchronized Lyrics and Event Timing Codes
491 For information synchronized with the audio data, a specific editor
492 is available. These frames are supported for ID3v2.3.0 and
493 ID3v2.4.0 tags. To add such a frame, the specific frame name has to
494 be selected in the list which appears when the Add button is
495 clicked - Synchronized Lyrics or Event Timing Codes, respectively.
496 The editor is the same for both types, for the event timing codes,
497 only a predefined set of events is available whereas for the
498 synchronized lyrics, text has to be entered. In the following,
499 editing synchronized lyrics is explained.
500 A file having an ID3v2 tag is selected, the lyrics editor is
502 entered using Add and selecting Synchronized Lyrics. For an
503 existing Synchronized Lyrics frame, it is selected and Edit is
504 clicked. The player is automatically opened with the current file
505 so that the file can be played and paused to synchronize lyrics.
506 The settings at the top of the SYLT editor normally do not have to
508 be changed. If the lyrics contains characters which are not present
509 in the Latin 1 character set, changing the text encoding to UTF16
510 (or UTF8 for ID3v2.4.0) is advisable. For English lyrics and
511 maximum compatibility, ISO-8859-1 should be used.
512 The Lyrics section has five buttons at the top. Add will add a new
514 time event in the table. The time is taken from the position of the
515 player, thus adding an entry while playing the track will add a
516 line for the currently played position. The events in the table
517 have to be chronologically ordered, therefore the row will be
518 inserted accordingly. Entries with an invalid time are treated
519 specially: If the currently selected row has an invalid time, its
520 time stamp will be replaced by the current time instead of adding a
521 new row. If the current time is not invalid, the first row with an
522 invalid time will be used if present. This behavior should
523 facilitate adding time stamps if the lyrics text is already in the
524 table but the time stamps are missing (which is the case when
525 importing unsynchronized lyrics). Note that the invalid time is
526 represented as 00:00.00, i.e. the same as the time at the absolute
527 beginning of the track, which is not invalid. To make a time
528 invalid, press the Delete key, or use Clear from the context menu.
529 New rows inserted using Insert row from the context menu or created
530 when importing unsynchronized lyrics with From Clipboard or Import
531 also contain invalid time stamps. Rows in the table can be deleted
532 by clicking the Delete button or using Delete rows from the context
533 menu.
534 Synchronized lyrics can be imported from a file using Import. The
536 expected format is simple or enhanced LRC. If the selected file
537 does not contain a square bracket in the first line, it is supposed
538 to be a simple text file with unsynchronized lyrics. The lines from
539 such a file are then imported having invalid time stamps. The time
540 information can be added using the Add button or by manual entry.
541 It is also possible to import lyrics via copy-paste using From
542 Clipboard. Synchronized lyrics can be written to LRC files using
543 Export. Note that only entries with valid time stamps will be
544 exported and that the entries will be sorted by time. Entries with
545 invalid time won't be stored in the SYLT frame either, so make sure
546 to include all timing information before leaving the dialog.
547 The ID3 specification[5] suggests a time stamp for each syllable.
549 However most players only support the granularity of a line or
550 sentence. To support both use cases, Kid3 follows the same
551 conventions as SYLT Editor[6]. Text which is entered into the table
552 is assumed to start a new line unless it starts with a space or a
553 hyphen. Exceptions to this rule are possible by starting a line
554 with an underscore ('_') to force continuation or a hash mark ('#')
555 to force a new line. These escape characters are not stored inside
556 the SYLT frame. Inside the SYLT frame, new lines start with a line
557 feed character (hex 0A) whereas continuations do not. When reading
558 SYLT frames, Kid3 checks if the first entry starts with a line
559 feed. If this is not the case, it is assumed that all entries are
560 new lines and that no syllable continuations are used.
561 While the track is played, the row associated with the current
563 playing position is highlighted, so that the correctness of the
564 synchronization information can be verified. If an offset has to be
565 added to one or more time stamps, this can be accomplished with the
566 Add offset context menu. Negative values can be used to reduce the
567 time. Using Seek to position in the context menu, it is possible to
568 set the playing position to the time of the selected row.
569 Recommended procedure to add new synchronized lyrics
571 • Get the unsynchronized lyrics, e.g. using Lyrics → Embed
573 Lyrics from the file list context menu.
574 • Copy the unsynchronized lyrics to the clipboard, just go to the
576 Lyrics row in the frame table and press Ctrl+C.
577 • Add a synchronized lyrics frame (Add..., Synchronized Lyrics,
579 OK), click From Clipboard.
580 • Now all lines from the unsynchronized lyrics are in the table,
582 all time stamps are invalid (0:0:0.00). You can delete empty
583 entries beforehand.
584 • Start playing the song by clicking the play button ► in the
586 play toolbar at the bottom of the main window.
587 • When the next lyrics line with invalid timestamp comes, click
589 Add or press Alt+A, the timestamp will be updated.
590 • Continue like this until all timestamps are set. If you missed
592 something, stop playback and clear the timestamps using the
593 Delete key or by selecting them and using Clear from the
594 context menu. To restart playback from a given timestamp, use
595 Seek to position from the context menu.
596 The File Menu
599 File → Open... (Ctrl+O)
600 Opens a folder. All files matching the selected file name filter
601 will be displayed in the file listbox and the chosen file is
602 selected.
603 File → Open Recent
605 Opens a recently opened folder.
606 File → Open Folder... (Ctrl+D)
608 Opens a folder. All files matching the selected file name filter
609 will be displayed in the file listbox.
610 File → Reload (F5)
612 Reload folder. Modified files have to be saved before. Expanded
613 subfolders will be collapsed.
614 File → Save (Ctrl+S)
616 Saves all changed files in the folder. The changed files are
617 marked with a disk symbol in the file listbox. If any file names
618 have been changed, those files will be renamed.
619 File → Revert
621 Reverts the changes of one or multiple files. If no files are
622 selected in the file listbox, the changes of all files will be
623 reverted, else only the changes of the selected files are reverted.
624 File → Import...
626 The Import dialog can be used to import data directly from a
627 freedb.org server, from a MusicBrainz server, from Discogs, Amazon
628 or other sources of album track lists in textual format.
629 Import from a freedb.org server is possible using a dialog which
631 appears when From Server: gnudb.org is selected. The artist and
632 album name to search for can be entered in the two topmost fields,
633 the albums which match the query will be displayed when Find is
634 clicked and the results from www.gnudb.org[7] are received.
635 Importing the track data for an album is done by double-clicking
636 the album in the list. The freedb.org server to import from can be
637 selected as well as the CGI path. The imported data is displayed in
638 the preview table of the import dialog. When satisfied with the
639 displayed tracks, they can be imported by terminating the import
640 dialog with OK.
641 A search on the Discogs server can be performed using Discogs. As
643 in the gnudb.org dialog, you can enter artist and album and then
644 choose from a list of releases. A Token can be entered to use the
645 RESTful Discogs API instead of their web interface, which is often
646 changed, thereby breaking the import parser. You have to register
647 for an account on Discogs[8] and then generate a token on their web
648 site (Settings/Developers, Generate new token). Don't forget to
649 Save Settings after entering the token in order to use it in
650 subsequent requests too. If Standard Tags is marked, the standard
651 information is imported, e.g. artist, album, and title. If
652 Additional Tags is marked, more information is imported if
653 available, e.g. performers, arrangers, or the publisher. If Cover
654 Art is marked, cover art will be downloaded if available.
655 A search on Amazon can be performed using Amazon. As in the
657 gnudb.org dialog, you can enter artist and album and then choose
658 from a list of releases. If Additional Tags is marked, more
659 information is imported if available, e.g. performers, arrangers,
660 or the publisher. If Cover Art is marked, cover art will be
661 downloaded if available.
662 You can search in the same way in the release database of
664 MusicBrainz using From MusicBrainz Release. The workflow is the
665 same as described for From gnudb.org.
666 Import from a MusicBrainz server is possible using the dialog which
668 appears when From MusicBrainz Fingerprint is selected. The Server
669 can be selected as in the freedb import dialog. Below is a table
670 displaying the imported track data. The right column shows the
671 state of the MusicBrainz query, which starts with "Pending" when
672 the dialog is opened. Then the fingerprint is looked up and if it
673 does not yield a result, another lookup using the tags in the file
674 is tried. Thus it can be helpful for a successful MusicBrainz query
675 to store known information (e.g. artist and album) in the tags
676 before the import. If a result was found, the search ends in the
677 state "Recognized", otherwise nothing was found or multiple
678 ambiguous results and one of them has to be selected by the user.
679 OK and Apply use the imported data, Cancel closes the dialog. The
680 closing can take a while since the whole MusicBrainz machinery has
681 to be shut down.
682 For the import of textual data, From File/Clipboard opens a
684 subdialog, where several preconfigured import formats are
685 available. The first two, "CSV unquoted" and "CSV quoted" can be
686 used to import data which was exported by the Export dialog. The
687 CSV data can be edited with a spreadsheet, and shall be written
688 using tabs as delimiters. Import should then be possible using "CSV
689 quoted", which is more flexible than "CSV unquoted". However, its
690 fields cannot contain any double quotes. If you only export from
691 Kid3 and import later, "CSV unquoted" can be used as a simple
692 format for this purpose. Note that there are also "Export CSV" and
693 "Import CSV" commands in the context menu of the file list, which
694 use scripts to export and import CSV data in a more complete,
695 powerful and flexible way.
696 The next format, "freedb HTML text", can be used to copy
698 information from an HTML page of freedb.org[9]. Search an album in
699 freedb and if the desired information is displayed in the web
700 browser, copy the contents to the clipboard. Then click the From
701 Clipboard button and the imported tracks will be displayed in the
702 preview table at the top of the dialog. If you are satisfied with
703 the imported data, terminate the dialog with OK, which will insert
704 the data into the tags of the current folder. The destination (Tag
705 1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box. The
706 files in the current folder should be in the correct track order to
707 get their tags assigned. This is the case if they are numbered.
708 The next preconfigured import format, "freedb HTML source", can be
710 used, if the data is available as an HTML document. Import is
711 possible using the From File button, which opens a file selector,
712 or copying its contents from an editor and then importing from
713 clipboard. This format can be useful for offline import, although
714 the HTML document could also be opened in a browser and then be
715 imported in the first format via the clipboard.
716 More preconfigured formats, e.g. "Track Title Time", are
718 available. An empty custom format can be created with Add to be set
719 by the user. Two lines below the format name can be set with a
720 regular expression to capture the fields from the import text. The
721 first regular expression will be parsed once per document to gather
722 per-album data such as artist, album, year and genre. The second
723 line is tried to match from the start of the document to the end to
724 get track data, usually number and title. The regular expressions
725 include all the features offered by Qt(TM), which is most of the
726 what Perl offers. Bracketing constructs "(..)" create capture
727 buffers for the fields to import and are preceded by Kid3 specific
728 codes to specify which field to capture. The codes are the same as
729 used for the filename format, besides the codes listed below, any
730 frame name is possible:
731 • %s %{title} Title (Song)
733 • %a %{artist} Artist
735 • %l %{album} Album
737 • %c %{comment} Comment
739 • %y %{year} Year
741 • %t %{track} Track
743 • %g %{genre} Genre
745 • %d %{duration} Duration
747 For example, a track regular expression (second line) to import
749 from an .m3u playlist could be
750 "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]". All formats can
751 be changed by editing the regular expressions and the name and then
752 clicking Save Settings. They will be stored in the kid3rc file in
753 the configuration folder. This file can be directly edited to have
754 more import formats or it can be deleted to revert to the default
755 formats. Formats can be deleted using Remove.
756 Accuracy shows an estimation of how good the imported information
758 matches the given tracks. It uses track durations or file names to
759 calculate the level of similarity in percent. Cover Art shows the
760 URL of the album cover image which will be downloaded.
761 To check whether the imported tracks match the current set of
763 files, the duration of the imported tracks can be compared with the
764 duration of the files. This option can be enabled with the check
765 box Check maximum allowable time difference (sec): and the maximum
766 tolerated difference in time can be set in seconds. If a mismatch
767 in a length is detected, the length is displayed with a red
768 background in the preview table.
769 If the files are ordered differently than the imported tracks,
771 their assigned tracks have to be changed. This task can be
772 facilitated using the Match with option with the buttons Length,
773 Track, and Title, which will reorder the tracks according to the
774 corresponding field. To correct the assignments manually, a track
775 can be dragged with the left mouse button and the Ctrl key hold
776 down, and then dropped at the new location.
777 When the import dialog is opened, it contains the actual contents
779 of the tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be
780 selected using the Destination combo box. The button on the right
781 of this combo box can be used to revert the table to the current
782 contents of the tags. The check boxes in the first table column can
783 be used to select the tracks which are imported. This can be useful
784 if a folder contains the tracks of both CDs of a double CD and only
785 the tracks of the second CD have to be imported.
786 To identify the tracks which are imported, it is possible to
788 display the file names or the full paths to the files using the
789 context menu of the table header. The values in the import table
790 can be edited. The revert-button to the right of the Destination
791 combo box can be used to restore the contents of the tags, which
792 can also be useful after changing the Destination.
793 Almost all dialogs feature a Save Settings button, which can be
795 used to store the dialog specific settings and the window size
796 persistently.
797 From Tags leads to a subdialog to set tag frames from the contents
799 of other tag frames. This can be used to simply copy information
800 between tags or extract a part from one frame and insert it in
801 another.
802 As in the import from file/clipboard dialog, there are freely
804 configurable formats to perform different operations. Already
805 preconfigured are formats to copy the Album value to Album Artist,
806 Composer or Conductor, and to extract the Track Number from Title
807 fields which contain a number. There is also a format to extract a
808 Subtitle from a Title field.
809 The following example explains how to add a custom format, which
811 sets the information from the Subtitle field also in the Comment
812 field. Create a new format using Add button and set a new name,
813 e.g. "Subtitle to Comment". Then enter "%{subtitle}" in Source and
814 "%{comment}(.*)" for Extraction and click Save Settings.
815 The expression in Source can contain format codes for arbitrary tag
817 frames, multiple codes can be used to combine the contents from
818 different frames. For each track, a text is generated from its tags
819 using the Source format, and the regular expression from Extraction
820 is applied to this text to set new values for the tags. Format
821 codes are used before the capturing parentheses to specify the tag
822 frame where the captured text shall be stored. It works in the same
823 way as for the import from file/clipboard.
824 Import from Tags... is also directly available from the File menu.
826 The difference between these two functions is that the import
827 dialog subdialog operates on all files of the current folder
828 whereas the menu function operates on the selected files (which can
829 be in different folders). The menu function supports an additional
830 code "%{__return}" to return the extracted value, which can be
831 useful with the CLI and QML interfaces.
832 File → Import from gnudb.org...
834 Import from a freedb.org server using gnudb.org album search. This
835 menu item opens the same import dialog as Import..., but opens
836 directly the gnudb.org dialog.
837 File → Import from Discogs...
839 Import from the Discogs server. This menu item opens the same
840 import dialog as Import..., but opens directly the From Discogs
841 dialog.
842 File → Import from Amazon...
844 Import from Amazon. This menu item opens the same import dialog as
845 Import..., but opens directly the From Amazon dialog.
846 File → Import from MusicBrainz Release...
848 Import from the MusicBrainz release database. This menu item opens
849 the same import dialog as Import..., but opens directly the From
850 MusicBrainz Release dialog.
851 File → Import from MusicBrainz Fingerprint...
853 Import from a MusicBrainz server. This menu item opens the same
854 import dialog as Import..., but opens directly the From MusicBrainz
855 Fingerprint dialog.
856 File → Import from Tags...
858 Like From Tags, but the import is applied to the selected files.
859 File → Automatic Import...
861 Automatic Import allows one to import information for multiple
862 albums from various web services. If folders are selected in the
863 file list, track data for the selected folders will be imported. If
864 no folder is selected, all folders in the file list will be
865 imported.
866 The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using
868 the Destination combo box.
869 Profiles determine which servers will be contacted to fetch album
871 information. Some profiles are predefined (All, MusicBrainz,
872 Discogs, Cover Art), custom profiles can be added using the Add
873 button at the right of the Profile combo box.
874 The table below shows the servers which will be used when importing
876 album information using the selected profile. The import process
877 for an album is finished if all required information has been
878 found, so the order of the rows in the table is important. It can
879 be changed using the Move Up and Move Down buttons. Edit can be
880 used to change an existing entry. The Server selection offers the
881 same servers as can be used in the import functions. Standard
882 Tags, Additional Tags, Cover Art determine the information which
883 shall be fetched from the server. Finally, Accuracy is the minimum
884 accuracy which must be achieved to accept the imported data. If the
885 accuracy is insufficient, the next server in the list will be
886 tried. The same dialog containing the server properties appears
887 when Add is clicked to add a new server entry. Existing entries can
888 be deleted using Remove.
889 To launch an automatic batch import with the selected profile,
891 click Start. Details about the running import are displayed at the
892 top of the dialog. The process can be aborted with the Abort
893 button.
894 File → Browse Cover Art...
897 The Browse Cover Art dialog helps to find album cover art.
898 Artist/Album is filled from the tags if possible. Source offers a
899 variety of websites with album cover art. The URL with artist and
900 album as parameters can be found beneath the name. URL-encoded
901 values for artist and album can be inserted using "%u{artist}" and
902 "%u{album}", other values from the tags are possible too, as
903 described in Configure Kid3, User Actions. More sources can be
904 entered after the entry "Custom Source" by replacing "Custom
905 Source" with the source's name, pressing Enter, then inserting the
906 URL and finally pressing Save Settings. The resulting browser
907 command is displayed at the top of the dialog and can be started by
908 clicking Browse. The browser, which can be configured in the
909 settings, is started with the selected source. A cover image can
910 then be dragged from the browser into the Kid3 window and will be
911 set in the picture frame of the selected files.
912 Because not all browsers support drag and drop of images and the
914 pictures on websites often have a URL, in such cases Kid3 will
915 receive the URL and not the picture. If the URL points to a
916 picture, it will be downloaded. However, if the URL refers to some
917 other web resource, it has to be translated to the corresponding
918 picture. Such mappings are defined in the table URL extraction. The
919 left column Match contains a regular expression which is compared
920 with the URL. If it matches, the captured expressions in
921 parentheses are inserted into the pattern of the right Picture URL
922 column (at the positions marked with \1 etc.). The replaced regular
923 expression contains the URL of the picture. By this means cover art
924 can be imported from Amazon, Google Images, etc. using drag and
925 drop. It is also possible to define your own mappings.
926 File → Export...
928 The Export Dialog is used to store data from the tags in a file or
929 the clipboard. The editor at the top shows a preview of the data to
930 export. If the export data contain tabulator characters, the export
931 is displayed in a table. The data will be generated from the tags
932 in the current folder according to the configured format.
933 The format settings are similar as in the Import dialog: The
935 topmost field contains the title (e.g. "CSV unquoted"), followed
936 by the header, which will be generated at the begin of the file.
937 The track data follows; it is used for every track. Finally, the
938 trailer can be used to generate some finishing text.
939 The format fields do not contain regular expressions as in the
941 Import dialog, but only output format expressions with special
942 %-expressions, which will be replaced by values from the tags. The
943 whole thing works like the file name format, and the same codes are
944 used plus some additional codes. Not only the codes listed below
945 but all tag frame names can be used.
946 • %s %{title} Title (Song)
948 • %a %{artist} Artist
950 • %l %{album} Album
952 • %c %{comment} Comment
954 • %y %{year} Year
956 • %t %{track} Track (e.g. 01)
958 • %t %{track.n} Track with field width n (e.g. 001 for
960 %{track.3})
961 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
963 • %g %{genre} Genre
965 • %f %{file} File name
967 • %p %{filepath} Path
969 • %{modificationdate} Modification date
971 • %{creationdate} Creation date
973 • %u %{url} URL
975 • %{dirname} Folder name
977 • %d %{duration} Duration in minutes:seconds
979 • %D %{seconds} Duration in seconds
981 • %n %{tracks} Number of tracks of the album
983 • %e %{extension} File extension
985 • %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
987 existing)
988 • %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
990 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
991 existing)
992 • %b %{bitrate} Bit rate in kbit/s
994 • %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
996 • %r %{samplerate} Sample rate in Hz
998 • %m %{mode} Channel mode (Stereo or Joint Stereo)
1000 • %h %{channels} Number of channels (1 or 2)
1002 • %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1004 MPC, APE, ASF, AIFF, WAV)
1005 A few formats are predefined. "CSV unquoted" separates the fields
1007 by tabs. Data in this format can be imported again into Kid3 using
1008 the import format with the same name. "CSV quoted" additionally
1009 encloses the fields by double quotes, which eases the import into
1010 spreadsheet applications. However, the fields shall not contain any
1011 double quotes when this format is used. "Extended M3U" and
1012 "Extended PLS" generate playlists with extended attributes and
1013 absolute path names. "HTML" can be used to generate an HTML page
1014 with hyperlinks to the tracks. "Kover XML" creates a file which can
1015 be imported by the cover printing program Kover. "Technical
1016 Details" provides information about bit rate, sample rate,
1017 channels, etc. Finally, "Custom Format" is left empty for
1018 definition of a custom format. You can define more formats of your
1019 own by adding lines in the file kid3rc in the configuration folder.
1020 The other formats can be adapted to your needs.
1021 The Source of the tags to generate the export data (Tag 1 or Tag 2)
1023 can be selected with a combo box. Pushing To File or To Clipboard
1024 stores the data in a file or on the clipboard. OK and Cancel close
1025 the dialog, whereas OK accepts the current dialog settings.
1026 File → Create Playlist...
1028 Creates a playlist. The format and contents of the playlist can be
1029 set by various options.
1030 The name of the playlist can be the Same as folder name or use a
1032 Format with values from the tags, e.g. "%{artist} - %{album}" to
1033 have the artist and album name in the playlist file name. The
1034 format codes are the same as for Export. Create new empty playlist
1035 will make an empty playlist with the given name. The extension
1036 depends on the playlist format.
1037 The location of the generated playlist is determined by the
1039 selection of the Create in combo box.
1040 Current folder
1042 The playlist is created in the current folder and contains only
1043 files of the current folder. The current folder is the folder
1044 where the current file is located. If multiple files are
1045 selected, the current file is probably the last selected file.
1046 Every folder
1048 A playlist is created in every folder which contains listed
1049 files, and each playlist contains the files of that folder.
1050 Top-level folder
1052 Only one playlist is created in the top-level folder (i.e. the
1053 folder of the file list) and it contains the listed files of
1054 the top-level folder and all of its sub-folders.
1055 The Format of the playlist can be M3U, PLS or XSPF.
1057 If Include only the selected files is checked, only the selected
1059 files will be included in the playlist. If a folder is selected,
1060 all of its files are selected. If this check box is not activated,
1061 all audio files are included in the playlist.
1062 Sort by file name selects the usual case where the files are
1064 ordered by file name. With Sort by tag field, it is possible to
1065 sort by a format string with values from tag fields. For instance,
1066 "%{track.3}" can be used to sort by track number (the ".3" is used
1067 to get three digits with leading zeros because strings are used for
1068 sorting). It is also possible to use multiple fields, e.g.
1069 "%{genre}%{year}" to sort using a string composed of genre and
1070 year.
1071 The playlist entries will have relative or absolute file paths
1073 depending on whether Use relative path for files in playlist or Use
1074 full path for files in playlist is set.
1075 When Write only list of files is set, the playlist will only
1077 contain the paths to the files. To generate an extended playlist
1078 with additional information, a format string can be set using the
1079 Write info using control.
1080 File → Quit (Ctrl+Q)
1082 Quits the application.
1083 The Edit Menu
1085 Edit → Select All (Alt+A)
1086 Selects all files.
1087 Edit → Deselect (Ctrl+Shift+A)
1089 Deselects all files.
1090 Edit → Select All in Folder
1092 Selects all files of the current folder.
1093 Edit → Previous File (Alt+Up)
1095 Selects the previous file.
1096 Edit → Next File (Alt+Down)
1098 Selects the next file.
1099 Edit → Find... (Ctrl+F)
1101 Find strings in the file names and the tags. The Find dialog is a
1102 subset of the Replace dialog, which is described below.
1103 Edit → Replace... (Ctrl+R)
1105 This function opens a dialog to find and replace strings in the
1106 file names and the tags. The set of frames where the search is
1107 performed can be restricted by deactivating the Select all check
1108 box and selecting the frames which shall be searched. There are
1109 also search options available to search backwards, case
1110 sensitively, and to use regular expressions.
1111 Depending on the number of files, the search might take some time,
1113 therefore it can be aborted by closing the dialog.
1114 The Tools Menu
1116 Tools → Apply Filename Format
1117 When Automatically apply format is switched off for the filename
1118 format in the configuration dialog, this menu item can be used to
1119 apply the configured format to the names of the selected files.
1120 This can also be used to check whether the file names conform with
1121 the configured format by applying the format to all saved files and
1122 then checking if any files were changed (and therefore marked with
1123 a disk symbol in the file listbox).
1124 Tools → Apply Tag Format
1126 When Automatically apply format is switched off for the tag format
1127 in the configuration dialog, this menu item can be used to apply
1128 the configured format to the tags of the selected files. This can
1129 also be used to check whether the tags conform with the configured
1130 format by applying the format to all saved files and then checking
1131 if any files were changed (and therefore marked with a disk symbol
1132 in the file listbox).
1133 Tools → Apply Text Encoding
1135 Sets the Text encoding selected in Settings → Configure Kid3... →
1136 Tags section → Tag 2 tab for all selected files. If UTF8 is
1137 selected, UTF16 will be used for ID3v2.3.0 tags because UTF8 is not
1138 supported for this format.
1139 Tools → Rename Folder...
1141 This dialog offers the possibility to automatically rename the
1142 currently open folder according to the tags in the files. Several
1143 formats are preconfigured to include information about artist,
1144 album and year in the folder name. It is also possible to set a
1145 custom format and Edit the list of available formats. The following
1146 special codes are used to insert tag values into the folder name:
1147 • %s %{title} Title (Song)
1149 • %a %{artist} Artist
1151 • %l %{album} Album
1153 • %c %{comment} Comment
1155 • %y %{year} Year
1157 • %t %{track} Track (e.g. 01)
1159 • %t %{track.n} Track with field width n (e.g. 001 for
1161 %{track.3})
1162 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
1164 • %g %{genre} Genre
1166 • %{dirname} Folder name (e.g. %{year" "}%{dirname} will prepend
1168 the year to the current folder name)
1169 • %{max-year} The maximum year value found for this folder, can
1171 also be used with other codes than "year"
1172 • %{min-year} The minimum year value found for this folder
1174 • %{unq-year} The unique year value found for this folder or
1176 empty if not unique
1177 If a folder separator "/" is found in the format, multiple folders
1179 are created. If you want to create a new folder instead of renaming
1180 the current folder, in the Action combo box select Create Folder
1181 instead of Rename Folder. The Source of the tag information can be
1182 chosen between Tag 1 and Tag 2, Tag 1 and Tag 2. A preview for the
1183 rename operation performed on the first file can be seen in the
1184 From and To sections of the dialog.
1185 Multiple folders can be renamed by selecting them.
1187 Tools → Number Tracks...
1189 If the track numbers in the tags are not set or have the wrong
1190 values, this function can number the tracks automatically in
1191 ascending order. The start number can be set in the dialog. If only
1192 part of the tracks have to be numbered, they must be selected.
1193 When Total number of tracks is checked, the number of tracks will
1195 also be set in the tags.
1196 It is possible to number the tracks over multiple folders. The
1198 folders have to be expanded and selected.
1199 If Reset counter for each folder is checked, track numbering is
1201 restarted with the given number for each folder when multiple
1202 folders are selected.
1203 The number tracks dialog can also be used to format existing track
1205 numbers without changing the values when the check box left to
1206 Start number is deactivated. The total number of tracks will be
1207 added if the corresponding check box is active, which can be used
1208 to set the total for all selected tracks. If only formatting of the
1209 existing numbers is desired, this check box has to be deactivated
1210 too.
1211 Tools → Filter...
1213 The filter can be used to display only those files which match
1214 certain criteria. This is helpful if you want to organize a large
1215 collection and only edit those files which are not in the desired
1216 scheme. The expression defining which files to display uses the
1217 same format codes which are used in the file name format, import
1218 and export.
1219 • %s %{title} Title (Song)
1221 • %a %{artist} Artist
1223 • %l %{album} Album
1225 • %c %{comment} Comment
1227 • %y %{year} Year
1229 • %t %{track} Track (e.g. 01)
1231 • %t %{track.n} Track with field width n (e.g. 001 for
1233 %{track.3})
1234 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
1236 • %g %{genre} Genre
1238 • %f %{file} File name
1240 • %p %{filepath} Absolute path to file
1242 • %e %{extension} File extension
1244 • %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1246 existing)
1247 • %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1249 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
1250 existing)
1251 • %b %{bitrate} Bit rate in kbit/s
1253 • %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
1255 • %r %{samplerate} Sample rate in Hz
1257 • %m %{mode} Channel mode (Stereo or Joint Stereo)
1259 • %h %{channels} Number of channels (1 or 2)
1261 • %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1263 MPC, APE, ASF, AIFF, WAV)
1264 • %w %{marked} Marked, is 1 if the file is marked (e.g. because
1266 of truncation or standard violation), empty otherwise
1267 • %1a %1{artist}, ... Use the prefix 1 to get values of tag 1
1269 • %2a %2{artist}, ... Use the prefix 2 to get values of tag 2
1271 These codes are replaced with the values for the file, and the
1273 resulting strings can be compared with the following operations:
1274 • s1 equals s2: true if s1 and s2 are equal.
1276 • s1 contains s2: true if s1 contains s2, i.e. s2 is a substring
1278 of s1.
1279 • s matches re: true if s matches the regular expression re.
1281 True expressions are replaced by 1, false by 0. True values are
1283 represented by 1, true, on and yes, false values by 0, false, off
1284 and no. Boolean operations are not, and, or (in this order of
1285 precedence) and can be grouped by parentheses.
1286 Some filter rules are predefined and can serve as examples for your
1288 own expressions:
1289 All
1291 When the file list is filtered - this is shown by "[filtered]"
1292 in the window title - and all files shall be displayed again,
1293 the filtering can be reverted using this filter. It uses an
1294 empty expression, but a true value would have the same effect.
1295 Filename Tag Mismatch
1297 not (%{filepath} contains "%{artist} - %{album}/%{track}
1298 %{title}")
1299 Tests if the file path conforms with the file name format. This
1301 rule is automatically adapted if the file name format changes.
1302 No Tag 1
1304 %{tag1} equals ""
1305 Displays only files which do not have a tag 1.
1307 No Tag 2
1309 %{tag2} equals ""
1310 Displays only files which do not have a tag 2.
1312 ID3v2.3.0 Tag
1314 %{tag2} equals "ID3v2.3.0"
1315 Displays only files which have an ID3v2.3.0 tag.
1317 ID3v2.4.0 Tag
1319 %{tag2} equals "ID3v2.4.0"
1320 Displays only files which have an ID3v2.4.0 tag.
1322 Tag 1 != Tag 2
1324 not (%1{title} equals %2{title} and %1{album} equals %2{album}
1325 and %1{artist} equals %2{artist} and %1{comment} equals
1326 %2{comment} and %1{year} equals %2{year} and %1{track} equals
1327 %2{track} and %1{genre} equals %2{genre})
1328 Displays files with differences between tag 1 and tag2.
1330 Tag 1 == Tag 2
1332 %1{title} equals %2{title} and %1{album} equals %2{album} and
1333 %1{artist} equals %2{artist} and %1{comment} equals %2{comment}
1334 and %1{year} equals %2{year} and %1{track} equals %2{track} and
1335 %1{genre} equals %2{genre}
1336 Displays files with identical tag 1 and tag 2.
1338 Incomplete
1340 %{title} equals "" or %{artist} equals "" or %{album} equals
1341 "" or %{year} equals "" or %{tracknumber} equals "" or %{genre}
1342 equals ""
1343 Displays files with empty values in the standard tags (title,
1345 artist, album, date, track number, genre).
1346 No Picture
1348 %{picture} equals ""
1349 Displays only files which do not have a picture.
1351 Marked
1353 not (%{marked} equals "")
1354 Displays only files which are marked because they violate the
1356 ID3 standard, are truncated or the picture is too large.
1357 Custom Filter
1359 To add your own filter, select this entry. For instance, if you
1360 want to have a filter for artists starting with "The", replace
1361 "Custom Filter" with the name "The Bands" and press Enter. Then
1362 insert the following expression into the line edit:
1363 %{artist} matches "The.*"
1365 Then click Save Settings. Click Apply to filter the files. All
1367 files processed are displayed in the text view, with a "+" for
1368 those who match the filter and a "-" for the others. When
1369 finished, only the files with an artist starting with "The" are
1370 displayed, and the window title is marked with "[filtered]".
1371 Tools → Convert ID3v2.3 to ID3v2.4
1373 If there are any ID3v2.3 tags in the selected files, they will be
1374 converted to ID3v2.4 tags. Frames which are not supported by TagLib
1375 will be discarded. Only files without unsaved changes will be
1376 converted.
1377 Tools → Convert ID3v2.4 to ID3v2.3
1379 If there are any ID3v2.4 tags in the selected files, they will be
1380 converted to ID3v2.3 tags. Only files without unsaved changes will
1381 be converted.
1382 Tools → Play
1384 This opens a simple toolbar to play audio files. It contains
1385 buttons for the basic operations (Play/Pause, Stop playback,
1386 Previous Track, Next Track, Close), sliders for position and volume
1387 and a display of the current position. If multiple files are
1388 selected, the selected tracks are played, else all files will be
1389 played.
1390 The Settings Menu
1392 Settings → Show Toolbar
1393 Toggles displaying of the toolbar.
1394 Settings → Show Statusbar
1396 Toggles displaying of the statusbar, which displays longer actions
1397 such as opening or saving a folder.
1398 Settings → Show Picture
1400 Toggles displaying of the album cover art preview picture.
1401 Settings → Auto Hide Tags
1403 Empty tags are automatically hidden if this option is active. The
1404 File, Tag 1 and Tag 2 sections can be manually collapsed and
1405 expanded by clicking on the corresponding -/+ buttons.
1406 Settings → Configure Shortcut keys...
1408 Opens a dialog to assign keyboard shortcuts for most of the program
1409 functions. There are even functions without corresponding menu or
1410 button available, e.g. next file, previous file, select all.
1411 Settings → Configure Kid3...
1414 Opens the configuration dialog, which consists of pages for tags,
1415 files, user actions, and network settings.
1416 Tag specific options can be found on the Tags page, which is itself
1418 separated into four tabs for Tag 1, Tag 2, Tag 3, and All Tags.
1419 If Mark truncated fields is checked, truncated ID3v1.1 fields will
1421 be marked red. The text fields of ID3v1.1 tags can only have 30
1422 characters, the comment only 28 characters. Also the genre and
1423 track numbers are restricted, so that fields can be truncated when
1424 imported or transferred from ID3v2. Truncated fields and the file
1425 will be marked red, and the mark will be removed after the field
1426 has been edited.
1427 With Text encoding for ID3v1 it is possible to set the character
1429 set used in ID3v1 tags. This encoding is supposed to be ISO-8859-1,
1430 so it is recommended to keep this default value. However, there are
1431 tags around with different encoding, so it can be set here and the
1432 ID3v1 tags can then be copied to ID3v2 which supports Unicode.
1433 The check box Use track/total number of tracks format controls
1435 whether the track number field of ID3v2 tags contains simply the
1436 track number or additionally the total number of tracks in the
1437 folder.
1438 When Genre as text instead of numeric string is checked, all ID3v2
1440 genres will be stored as a text string even if there is a
1441 corresponding code for ID3v1 genres. If this option is not set,
1442 genres for which an ID3v1 code exists are stored as the number of
1443 the genre code (in parentheses for ID3v2.3). Thus the genre Metal
1444 is stored as "Metal" or "(9)" depending on this option. Genres
1445 which are not in the list of ID3v1 genres are always stored as a
1446 text string. The purpose of this option is improved compatibility
1447 with devices which do not correctly interpret genre codes.
1448 When WAV files with lowercase id3 chunk is checked, the RIFF chunk
1450 used to store ID3v2 tags in WAV files will be named "id3 " instead
1451 of "ID3 ". By default, Kid3 and other applications using TagLib
1452 accept both the lowercase and the uppercase variant when reading
1453 WAV files, but they use "ID3 " when writing ID3v2 tags to WAV
1454 files. As there exist other applications which only accept "id3 "
1455 (e.g. JRiver Media Center and foobar2000), this option can be used
1456 to create tags which can be read by such applications.
1457 When Mark standard violations is checked, ID3v2 fields which
1459 violate the standard will be marked red. Details about the
1460 violation are shown in a tooltip:
1461 • Must be unique
1463 • New line is forbidden
1465 • Carriage return is forbidden
1467 • Owner must be non-empty
1469 • Must be numeric
1471 • Must be numeric or number/total
1473 • Format is DDMM
1475 • Format is HHMM
1477 • Format is YYYY
1479 • Must begin with a year and a space character
1481 • Must be ISO 8601 date/time
1483 • Must be musical key, 3 characters, A-G, b, #, m, o
1485 • Must have ISO 639-2 language code, 3 lowercase characters
1487 • Must be ISRC code, 12 characters
1489 • Must be list of strings separated by '|'
1491 • Has excess white space
1493 The ID3 standard documents are available online:
1495 • ID3 tag version 2.3.0[10]
1497 • ID3 tag version 2.4.0 - Main Structure[11]
1499 • ID3 tag version 2.4.0 - Native Frames[5]
1501 Text encoding defines the default encoding used for ID3v2 frames
1503 and can be set to ISO-8859-1, UTF16, or UTF8. UTF8 is not valid
1504 for ID3v2.3.0 frames; if it is set, UTF16 will be used instead. For
1505 ID3v2.4.0 frames, all three encodings are possible.
1506 Version used for new tags determines whether new ID3v2 tags are
1508 created as version 2.3.0 or 2.4.0.
1509 Track number digits is the number of digits in Track Number fields.
1511 Leading zeros are used to pad. For instance, with a value of 2 the
1512 track number 5 is set as "05".
1513 The combo box Comment field name is only relevant for Ogg/Vorbis
1515 and FLAC files and sets the name of the field used for comments.
1516 Different applications seem to use different names, "COMMENT" for
1517 instance is used by XMMS, whereas Amarok uses "DESCRIPTION".
1518 The format of pictures in Ogg/Vorbis files is determined by Picture
1520 field name, which can be "METADATA_BLOCK_PICTURE" or "COVERART".
1521 The first is the official standard and uses the same format as
1522 pictures in FLAC tags. "COVERART" is an earlier unofficial way to
1523 include pictures in Vorbis comments. It can be used for
1524 compatibility with legacy players.
1525 If the Mark if larger than (bytes) check box is activated, files
1527 containing embedded album cover art exceeding the given size in
1528 bytes are marked red. This can be used to find files containing
1529 oversized pictures which are not accepted by some applications and
1530 players. The default value is 131072 bytes (128 KB).
1531 Custom Genres can be used to define genres which are not available
1533 in the standard genre list, e.g. "Gothic Metal". Such custom
1534 genres will appear in the Genre combo box of Tag 2. For ID3v1.1
1535 tags, only the predefined genres can be used.
1536 The list of custom genres can also be used to reduce the number of
1538 genres available in the Genre combo box to those typically used. If
1539 your collection mostly contains music in the genres Metal, Gothic
1540 Metal, Ancient and Hard Rock, you can enter those genres and mark
1541 Show only custom genres. The Tag 2 Genre combo box will then only
1542 contain those four genres and you will not have to search through
1543 the complete genres list for them. In this example, only Metal and
1544 Hard Rock will be listed in the tag 1 genres list, because those
1545 two custom genres entries are standard genres. If Show only custom
1546 genres is not active, the custom genres can be found at the end of
1547 the genres list.
1548 In Custom Frames, up to eight custom frame names can be defined,
1550 which can then be used like the unified frames, for example as
1551 quick access frames.
1552 Quick Access Frames defines which frame types are always shown in
1554 the Tag 2 section. Such frames can then be added without first
1555 using the Add button. The order of these quick access frames can be
1556 changed by dragging and dropping items.
1557 The combo box Track number field name is only relevant for RIFF
1559 INFO and sets the name of the field used for track numbers. Track
1560 numbers are not specified in the original RIFF standard, there are
1561 applications which use "ITRK", others use "IPRT".
1562 Tag Format contains options for the format of the tags. When
1564 Automatically apply format is checked, the format configuration is
1565 automatically used while editing text in the line edits.
1566 Validation enables validators in the controls with track/total and
1567 date/time values. The Case conversion can be set to No changes, All
1568 lowercase, All uppercase, First letter uppercase or All first
1569 letters uppercase. To use locale-aware conversion between lowercase
1570 and uppercase characters, a locale can be selected in the combobox
1571 below. The string replacement list can be set to arbitrary string
1572 mappings. To add a new mapping, select the From cell of a row and
1573 insert the text to replace, then go to the To column and enter the
1574 replacement text. When the text to replace starts and ends with a
1575 slash ("/"), a regular expression is used. For regular expressions
1576 containing capturing groups, occurrences of \1, \2, ... in To are
1577 replaced with the string captured by the corresponding capturing
1578 group. To remove a mapping set the From cell to an empty value
1579 (e.g. by first typing space and then backspace). Inserting and
1580 deleting rows is also possible using a context menu which appears
1581 when the right mouse button is clicked. Replacement is only active,
1582 if the String replacement check box is checked.
1583 The table in Rating contains the mapping of star ratings to the
1585 effective values stored in the tag. The frames with rating
1586 information are listed in the Rating row of the frame list. For
1587 these frames, the rating can be set by giving a number of stars out
1588 of five stars. Different tag formats and different applications use
1589 different values to map the star rating to the value stored in the
1590 tag. In order to display the correct number of stars, Kid3 will
1591 look up a map in this table. The key to look up the mapping is the
1592 frame name, for example "RATING" as used for Vorbis comments or
1593 "IRTD" for RIFF INFO. For ID3v2 tags, a combined key is used
1594 consisting of the frame ID "POPM" of the Popularimeter frame and
1595 its "Email" field, separated by a dot. Therefore, different keys
1596 for ID3v2 exist, e.g. "POPM.Windows Media Player 9 Series" for the
1597 mapping used by Windows Media Player and Explorer, and simply
1598 "POPM" for POPM frames with an empty "Email" field. As multiple
1599 entries for "POPM" can exist, their order is important. When Kid3
1600 adds a new Popularimeter frame, it will use the first "POPM" entry
1601 to determine the value to be written into the "Email" field. This
1602 value will then specify the mapping to be used for star ratings.
1603 The first entry is also used if no key was found, it is therefore
1604 the default entry.
1605 Besides the Name column containing the keys, the table has columns
1607 1 to 5 for the values to be stored when the corresponding number of
1608 stars is given. The other way round, the values determine the
1609 number of stars which are displayed for the value stored in the
1610 frame. For instance, the row in the table below contains the values
1611 1, 64, 128, 196, 255. The thresholds for the number of stars to be
1612 displayed lay between these values and are compatible with what the
1613 Windows® Explorer uses.
1614 Table 1. Entry in Rating Table
1616 ┌──────┬──────┬───────┬────────┬─────────┬─────────┐
1617 │Name │ 1 │ 2 │ 3 │ 4 │ 5 │
1618 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1619 │POPM │ 1 │ 64 │ 128 │ 196 │ 255 │
1620 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1621 │Range │ 1-31 │ 32-95 │ 96-159 │ 160-223 │ 224-255 │
1622 └──────┴──────┴───────┴────────┴─────────┴─────────┘
1623 On the page Files the check box Load last-opened files can be
1624 marked so that Kid3 will open and select the last selected file
1625 when it is started the next time. Preserve file timestamp can be
1626 checked to preserve the file modification time stamp. Filename for
1627 cover sets the name which is suggested when an embedded image is
1628 exported to a file. With Text encoding (Export, Playlist) the
1629 encoding used when writing files can be set. The default System can
1630 be changed for example if playlists have to be used on a different
1631 device.
1632 If Mark changes is active, changed fields are marked with a light
1634 gray label background.
1635 The section File List determines which files are displayed in the
1637 file list. A Filter can be used to restrict the items in this list
1638 to files with supported extensions. To explicitly specify which
1639 folders to display in the file list or exclude certain folders, the
1640 options Include folders and Exclude folders can be used. They can
1641 contain wildcard expressions, for instance */Music/* to include
1642 only the Music folder, or */iTunes/* to exclude the iTunes folder
1643 from the file list. If multiple such expressions have to be used,
1644 they can be separated by spaces or semicolons.
1645 The buttons Filename from tag and Tag from filename in section
1647 Format open dialogs to edit the formats which are available in the
1648 Format combo boxes (with arrows up and down), which can be found in
1649 the File section of the main window.
1650 Filename Format contains options for the format of the filenames.
1652 The same options as in Tag Format are available.
1653 Additionally, the Maximum length allowed for file names can be set.
1655 Most modern file systems have a limit of 255 characters, but if you
1656 want to burn the files to CD, you should set the limit to 64. If
1657 Use for playlist and folder names is checked, the file name format
1658 is also used when creating playlists and renaming folders.
1659 The User Actions page contains a table with the commands which are
1661 available in the context menu of the file list. For critical
1662 operations such as deleting files, it is advisable to mark Confirm
1663 to pop up a confirmation dialog before executing the command.
1664 Output can be marked to see the output written by console commands
1665 (standard output and standard error). Name is the name displayed
1666 in the context menu. Command is the command line to be executed.
1667 Arguments can be passed using the following codes:
1668 • %F %{files} File paths (a list if multiple files selected)
1670 • %f %{file} File path to single file
1672 • %uF %{urls} URLs (a list if multiple files selected)
1674 • %uf %{url} URL to single file
1676 • %d %{directory} Folder
1678 • %s %{title} Title (Song)
1680 • %a %{artist} Artist
1682 • %l %{album} Album
1684 • %c %{comment} Comment
1686 • %y %{year} Year
1688 • %t %{track} Track (e.g. 01)
1690 • %t %{track.n} Track with field width n (e.g. 001 for
1692 %{track.3})
1693 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
1695 • %g %{genre} Genre
1697 • %b %{browser} Command to start the web browser
1699 • %q %{qmlpath} Base folder of provided QML files
1701 The special code @separator can be set as a command to insert a
1703 separator into the user actions context menu. Menu items can be put
1704 into a submenu by enclosing them with @beginmenu and @endmenu
1705 commands. The name of the submenu is determined by the Name column
1706 of the @beginmenu command.
1707 To execute QML scripts, @qml is used as a command name. The path to
1709 the QML script is passed as a parameter. The provided scripts can
1710 be found in the folder %{qmlpath}/script/ (on Linux® typically
1711 /usr/share/kid3/qml/script/, on Windows qml/script/ inside the
1712 installation folder, and on macOS® in the app folder
1713 kid3.app/Contents/Resources/qml/script/). Custom scripts can be
1714 stored in any folder. If the QML code uses GUI components, @qmlview
1715 shall be used instead of @qml. Additional parameters are passed to
1716 the QML script where they will be available via the getArguments()
1717 function. An overview of some functions and properties which are
1718 available in QML can be found in the appendix QML Interface.
1719 The command which will be inserted with %{browser} can be defined
1721 in the Web browser line edit above. Commands starting with
1722 %{browser} can be used to fetch information about the audio files
1723 from the web, for instance
1724 %{browser} http://lyricwiki.org/%u{artist}:%u{title}
1726 will query the lyrics for the current song in LyricWiki[12]. The
1728 "u" in %u{artist} and %u{title} is used to URL-encode the artist
1729 %{artist} and song %{title} information. It is easy to define your
1730 own queries in the same way, e.g. an image search with Google[13]:
1731 %{browser} http://images.google.com/images?q=%u{artist}%20%u{album}
1733 To add album cover art to tag 2, you can search for images with
1735 Google or Amazon using the commands described above. The picture
1736 can be added to the tag with drag and drop. You can also add an
1737 image with Add, then select the Picture frame and import an image
1738 file or paste from the clipboard. Picture frames are supported for
1739 ID3v2, MP4, FLAC, Ogg and ASF tags.
1740 To add and delete entries in the table, a context menu can be used.
1742 The Network page contains only a field to insert the proxy address
1744 and optionally the port, separated by a colon. The proxy will be
1745 used when importing from an Internet server when the check box is
1746 checked.
1747 In the Plugins page, available plugins can be enabled or disabled.
1749 The plugins are separated into two sections. The Metadata Plugins &
1750 Priority list contains plugins which support audio file formats.
1751 The order of the plugins is important because they are tried from
1752 top to bottom. Some formats are supported by multiple plugins, so
1753 files will be opened with the first plugin supporting them. The
1754 TaglibMetadata supports most formats, if it is at the top of the
1755 list, it will open most of the files. If you want to use a
1756 different plugin for a file format, make sure that it is listed
1757 before the TaglibMetadata plugin. Details about the metadata plugin
1758 and why you may want to use them instead of TagLib are listed
1759 below.
1760 • Id3libMetadata: Uses id3lib[14] for ID3v1.1 and ID3v2.3 tags in
1762 MP3, MP2, AAC files. Supports a few more frame types than
1763 TagLib.
1764 • OggFlacMetadata: Uses libogg[15], libvorbis, libvorbisfile[16]
1766 for Ogg files, and additionally libFLAC++ and libFLAC[17] for
1767 FLAC files. These are the official libraries for these formats.
1768 • TaglibMetadata: Uses TagLib[18] which supports a lot of audio
1770 file formats. It can be used for all audio files supported by
1771 Kid3.
1772 • Mp4v2Metadata: mp4v2[19] was originally used by Kid3 to support
1774 M4A files. Can be used in case of problems with the M4A support
1775 of TagLib.
1776 The Available Plugins section lists the remaining plugins. Their
1778 order is not important, but they can be enabled or disabled using
1779 the check boxes.
1780 • AmazonImport: Used for the Import from Amazon... function.
1782 • DiscogsImport: Used for the Import from Discogs... function.
1784 • FreedbImport: Used for the Import from gnudb.org... function.
1786 • MusicBrainzImport: Used for the Import from MusicBrainz
1788 Release... function.
1789 • AcoustidImport: Used for the Import from MusicBrainz
1791 Fingerprint... function, which depends on the Chromaprint[20]
1792 and libav[21] libraries.
1793 Plugins which are disabled will not be loaded. This can be used to
1795 optimize resource usage and startup time. The settings on this page
1796 take only effect after a restart of Kid3.
1797 The Help Menu
1799 Help → Kid3 Handbook
1800 Opens this handbook.
1801 Help → About Kid3
1803 Displays a short information about Kid3.
1804
1806 Commands
1807 kid3-cli offers a command-line-interface for Kid3. If a folder path is
1808 used, the folder is opened. If one or more file paths are given, the
1809 common folder is opened and the files are selected. Subsequent commands
1810 will then work on these files. Commands are specified using -c options.
1811 If multiple commands are passed, they are executed in the given order.
1812 If files are modified by the commands, they will be saved at the end.
1813 If no command options are passed, kid3-cli starts in interactive mode.
1814 Commands can be entered and will operate on the current selection. The
1815 following sections list all available commands.
1816 Help
1818 help [COMMAND-NAME]
1819 Displays help about the parameters of COMMAND-NAME or about all
1821 commands if no command name is given.
1822 Timeout
1824 timeout [default | off | TIME]
1825 Overwrite the default command timeout. The CLI commands abort after
1827 a command specific timeout is expired. This timeout is 10 seconds
1828 for ls and albumart, 60 seconds for autoimport and filter, and 3
1829 seconds for all other commands. If a huge number of files has to be
1830 processed, these timeouts may be too restrictive, thus the timeout
1831 for all commands can be set to TIME ms, switched off altogether or
1832 be left at the default values.
1833 Quit application
1835 exit [force]
1836 Exit application. If there are modified unsaved files, the force
1838 parameter is required.
1839 Change folder
1841 cd [FOLDER]
1842 If no FOLDER is given, change to the home folder. If a folder is
1844 given, change into the folder. If one or more file paths are given,
1845 change to their common folder and select the files.
1846 Print the filename of the current folder
1848 pwd
1849 Print the filename of the current working folder.
1851 Folder list
1853 ls
1854 List the contents of the current folder. This corresponds to the
1856 file list in the Kid3 GUI. Five characters before the file names
1857 show the state of the file.
1858 • > File is selected.
1860 • * File is modified.
1862 • 1 File has a tag 1, otherwise '-' is displayed.
1864 • 2 File has a tag 2, otherwise '-' is displayed.
1866 • 3 File has a tag 3, otherwise '-' is displayed.
1868 kid3-cli> ls
1870 1-- 01 Intro.mp3
1871 > 12- 02 We Only Got This One.mp3
1872 *1-- 03 Outro.mp3
1873 In this example, all files have a tag 1, the second file also has a
1875 tag 2 and it is selected. The third file is modified.
1876 Save the changed files
1878 save
1879 Select file
1881 select [all | none | first | previous | next | FILE...]
1882 To select all files, enter select all, to deselect all files, enter
1884 select none. To traverse the files in the current folder start with
1885 select first, then go forward using select next or backward using
1886 select previous. Specific files can be added to the current
1887 selection by giving their file names. Wildcards are possible, so
1888 select *.mp3 will select all MP3 files in the current folder.
1889 kid3-cli> select first
1891 kid3-cli> ls
1892 > 1-- 01 Intro.mp3
1893 12- 02 We Only Got This One.mp3
1894 *1-- 03 Outro.mp3
1895 kid3-cli> select next
1896 kid3-cli> ls
1897 1-- 01 Intro.mp3
1898 > 12- 02 We Only Got This One.mp3
1899 *1-- 03 Outro.mp3
1900 kid3-cli> select *.mp3
1901 kid3-cli> ls
1902 > 1-- 01 Intro.mp3
1903 > 12- 02 We Only Got This One.mp3
1904 >*1-- 03 Outro.mp3
1905 Select tag
1907 tag [TAG-NUMBERS]
1908 Many commands have an optional TAG-NUMBERS parameter, which
1910 specifies whether the command operates on tag 1, 2, or 3. If this
1911 parameter is omitted, the default tag numbers are used, which can
1912 be set by this command. At startup, it is set to 12 which means
1913 that information is read from tag 2 if available, else from tag 1;
1914 modifications are done on tag 2. The TAG-NUMBERS can be set to 1,
1915 2, or 3 to operate only on the corresponding tag. If the parameter
1916 is omitted, the current setting is displayed.
1917 Get tag frame
1919 get [all | FRAME-NAME] [TAG-NUMBERS]
1920 This command can be used to read the value of a specific tag frame
1922 or get information about all tag frames (if the argument is omitted
1923 or all is used). Modified frames are marked with a '*'.
1924 kid3-cli> get
1926 File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
1927 Name: 01 Intro.mp3
1928 Tag 1: ID3v1.1
1929 Title Intro
1930 Artist One Hit Wonder
1931 Album Let's Tag
1932 Date 2013
1933 Track Number 1
1934 Genre Pop
1935 kid3-cli> get title
1936 Intro
1937 To save the contents of a picture frame to a file, use
1939 get picture:'/path/to/folder.jpg'
1941 To save synchronized lyrics to an LRC file, use
1943 get SYLT:'/path/to/lyrics.lrc'
1945 It is possible to get only a specific field from a frame, for
1947 example get POPM.Email for the Email field of a Popularimeter
1948 frame. If a file has multiple frames of the same kind, the
1949 different frames can be indexed with brackets, for example the
1950 first performer from a Vorbis comment can be retrieved using get
1951 performer[0], the second using get performer[1].
1952 The pseudo field name "selected" can be used to check if a frame is
1954 selected, for example get artist.selected will return 1 if the
1955 artist frame is selected, else 0.
1956 Set tag frame
1958 set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]
1959 This command sets the value of a specific tag frame. If FRAME-VALUE
1961 is empty, the frame is deleted.
1962 kid3-cli> set remixer 'O.H. Wonder'
1964 To set the contents of a picture frame from a file, use
1966 set picture:'/path/to/folder.jpg' 'Picture Description'
1968 To set synchronized lyrics from an LRC file, use
1970 set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'
1972 To set a specific field of a frame, the field name can be given
1974 after a dot, e.g. to set the Counter field of a Popularimeter
1975 frame, use
1976 set POPM.Counter 5
1978 An application for field specifications is the case where you want
1980 a custom TXXX frame with "rating" description instead of a standard
1981 Popularimeter frame (this seems to be used by some plugins). You
1982 can create such a TXXX rating frame with kid3-cli, however, you
1983 have to first create a TXXX frame with description "rating" and
1984 then set the value of this frame to the rating value.
1985 kid3-cli> set rating ""
1987 kid3-cli> set TXXX.Description rating
1988 kid3-cli> set rating 5
1989 The first command will delete an existing POPM frame, because if
1991 such a frame exists, set rating 5 would set the POPM frame and not
1992 the TXXX frame. Another possibility would be to use set TXXX.Text
1993 5, but this would only work if there is no other TXXX frame
1994 present.
1995 To set multiple frames of the same kind, an index can be given in
1997 brackets, e.g. to set multiple performers in a Vorbis comment, use
1998 kid3-cli> set performer[0] 'Liza don Getti (soprano)'
2000 kid3-cli> set performer[1] 'Joe Barr (piano)'
2001 To select certain frames before a copy, paste or remove action, the
2003 pseudo field name "selected" can be used. Normally, all frames are
2004 selected, to deselect all, use set '*.selected' 0, then for example
2005 set artist.selected 1 to select the artist frame.
2006 Revert
2008 revert
2009 Revert all modifications in the selected files (or all files if no
2011 files are selected).
2012 Import from file
2014 import {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2015 Tags are imported from the file FILE in the format with the name
2017 FORMAT-NAME (e.g. "CSV unquoted", see Import).
2018 If tags is given for FILE, tags are imported from other tags.
2020 Instead of FORMAT-NAME parameters SOURCE and EXTRACTION are
2021 required, see Import from Tags. To apply the import from tags on
2022 the selected files, use tagsel instead of tags. This function also
2023 supports output of the extracted value by using an EXTRACTION with
2024 the value %{__return}(.+).
2025 Automatic import
2027 autoimport [PROFILE-NAME] [TAG-NUMBERS]
2028 Batch import using profile PROFILE-NAME (see Automatic Import,
2030 "All" is used if omitted).
2031 Download album cover artwork
2033 albumart {URL} [all]
2034 Set the album artwork by downloading a picture from URL. The rules
2036 defined in the Browse Cover Art dialog are used to transform
2037 general URLs (e.g. from Amazon) to a picture URL. To set the album
2038 cover from a local picture file, use the set command.
2039 kid3-cli> albumart
2041 http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
2042 Export to file
2044 export {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2045 Tags are exported to file FILE in the format with the name
2047 FORMAT-NAME (e.g. "CSV unquoted", see Export).
2048 Create playlist
2050 playlist
2051 Create playlist in the format set in the configuration, see Create
2053 Playlist.
2054 Apply filename format
2056 filenameformat
2057 Apply file name format set in the configuration, see Apply Filename
2059 Format.
2060 Apply tag format
2062 tagformat
2063 Apply tag name format set in the configuration, see Apply Tag
2065 Format.
2066 Apply text encoding
2068 textencoding
2069 Apply text encoding set in the configuration, see Apply Text
2071 Encoding.
2072 Rename folder
2074 renamedir [FORMAT] [create | rename | dryrun] [TAG-NUMBERS]
2075 Rename or create folders from the values in the tags according to a
2077 given FORMAT (e.g. %{artist} - %{album}, see Rename Folder), if no
2078 format is given, the format defined in the Rename folder dialog is
2079 used. The default mode is rename; to create folders, create must be
2080 given explicitly. The rename actions will be performed immediately,
2081 to just see what would be done, use the dryrun option.
2082 Number tracks
2084 numbertracks [TRACK-NUMBER] [TAG-NUMBERS]
2085 Number the selected tracks starting with TRACK-NUMBER (1 if
2087 omitted).
2088 Filter
2090 filter [FILTER-NAME | FILTER-FORMAT]
2091 Filter the files so that only the files matching the FILTER-FORMAT
2093 are visible. The name of a predefined filter expression (e.g.
2094 "Filename Tag Mismatch") can be used instead of a filter
2095 expression, see Filter.
2096 kid3-cli> filter '%{title} contains "tro"'
2098 Started
2099 /home/urs/One Hit Wonder - Let's Tag
2100 + 01 Intro.mp3
2101 - 02 We Only Got This One.mp3
2102 + 03 Outro.mp3
2103 Finished
2104 kid3-cli> ls
2105 1-- 01 Intro.mp3
2106 1-- 03 Outro.mp3
2107 kid3-cli> filter All
2108 Started
2109 /home/urs/One Hit Wonder - Let's Tag
2110 + 01 Intro.mp3
2111 + 02 We Only Got This One.mp3
2112 + 03 Outro.mp3
2113 Finished
2114 kid3-cli> ls
2115 1-- 01 Intro.mp3
2116 12- 02 We Only Got This One.mp3
2117 1-- 03 Outro.mp3
2118 Convert ID3v2.3 to ID3v2.4
2120 to24
2121 Convert ID3v2.4 to ID3v2.3
2123 to23
2124 Filename from tag
2126 fromtag [FORMAT] [TAG-NUMBERS]
2127 Set the file names of the selected files from values in the tags,
2129 for example fromtag '%{track} - %{title}' 1. If no format is
2130 specified, the format set in the GUI is used.
2131 Tag from filename
2133 totag [FORMAT] [TAG-NUMBERS]
2134 Set the tag frames from the file names, for example totag
2136 '%{albumartist} - %{album}/%{track} %{title}' 2. If no format is
2137 specified, the format set in the GUI is used. If the format of the
2138 filename does not match this pattern, a few other commonly used
2139 formats are tried.
2140 Tag to other tag
2142 syncto {TAG-NUMBER}
2143 Copy the tag frames from one tag to the other tag, e.g. to set the
2145 ID3v2 tag from the ID3v1 tag, use syncto 2.
2146 Copy
2148 copy [TAG-NUMBER]
2149 Copy the tag frames of the selected file to the internal copy
2151 buffer. They can then be set on another file using the paste
2152 command.
2153 To copy only a subset of the frames, use the "selected" pseudo
2155 field with the set command. For example, to copy only the disc
2156 number and copyright frames, use
2157 set '*.selected' 0
2159 set discnumber.selected 1
2160 set copyright.selected 1
2161 copy
2162 Paste
2165 paste [TAG-NUMBER]
2166 Set tag frames from the contents of the copy buffer in the selected
2168 files.
2169 Remove
2171 remove [TAG-NUMBER]
2172 Remove a tag.
2174 It is possible to remove only a subset of the frames by selecting
2176 them as described in the copy command.
2177 Configure Kid3
2179 config [OPTION] [VALUE]
2180 Query or set a configuration option.
2182 The OPTION consists of a group name and a property name separated
2184 by a dot. When no OPTION is given, all available groups are
2185 displayed. If only a group name is given, all available properties
2186 of the group are displayed. For a given group and property, the
2187 currently configured value is displayed. To change the setting, the
2188 new value can be passed as a second argument.
2189 If the value of a setting is a list, all list elements have to be
2191 given as arguments. This means that to append an element to an
2192 existing list of elements, all existing elements have to be passed
2193 followed by the new element. In such a situation, it is easier to
2194 use the JSON mode, where the current list can be copied with the
2195 new element appended.
2196 Execute program or QML script
2198 execute [@qml] {FILE} [ARGS]
2199 Execute a QML script or an executable.
2201 Without @qml a program is executed with arguments. When @qml is
2203 given as the first argument, the following arguments are the QML
2204 script and its arguments. For example, the tags of a folder can be
2205 exported to the file export.csv with the following command.
2206 kid3-cli -c "execute @qml
2208 /usr/share/kid3/qml/script/ExportCsv.qml export.csv"
2209 /path/to/folder/
2210 Here export.csv is the argument for the ExportCsv.qml script,
2212 whereas /path/to/folder/ is the FILE argument for kid3-cli.
2213 Examples
2215 Set title containing an apostrophe. Commands passed to kid3-cli with -c
2216 have to be in quotes if they do not only consist of a single word. If
2217 such a command itself has an argument containing spaces, that argument
2218 has to be quoted too. In UNIX® shells single or double quotes can be
2219 used, but on the Windows Command Prompt, it is important that the outer
2220 quoting is done using double quotes and inside these quotes, single
2221 quotes are used. If the text inside the single quotes contains a single
2222 quote, it has to be escaped using a backslash character, as shown in
2223 the following example:
2224 kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder
2226 Set album cover in all files of a folder using the batch import
2228 function:
2229 kid3-cli -c "autoimport 'Cover Art'" /path/to/folder
2231 Remove comment frames and apply the tag format in both tags of all MP3
2233 files of a folder:
2234 kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
2236 -c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3
2237 Automatically import tag 2, synchronize to tag 1, set file names from
2239 tag 2 and finally create a playlist:
2240 kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
2242 /path/to/folder/*.mp3
2243 For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
2245 the arranger frame:
2246 kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
2248 -c "set arranger ''" /path/to/folder
2249 This Python script uses kid3-cli to generate iTunes Sound Check
2251 iTunNORM frames from replay gain information.
2252 #!/usr/bin/env python3
2255 # Generate iTunes Sound Check from ReplayGain.
2256 import os, sys, subprocess
2257 def rg2sc(dirpath):
2259 for root, dirs, files in os.walk(dirpath):
2260 for name in files:
2261 if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
2262 fn = os.path.join(root, name)
2263 rg = subprocess.check_output([
2264 'kid3-cli', '-c', 'get "replaygain_track_gain"',
2265 fn]).strip()
2266 if rg.endswith(b' dB'):
2267 rg = rg[:-3]
2268 try:
2269 rg = float(rg)
2270 except ValueError:
2271 print('Value %s of %s in not a float' % (rg, fn))
2272 continue
2273 sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
2274 subprocess.call([
2275 'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
2276 if __name__ == '__main__':
2278 rg2sc(sys.argv[1])
2279 JSON Format
2282 In order to make it easier to parse results from kid3-cli, it is
2283 possible to get the output in JSON format. When the request is in JSON
2284 format, the response will also be JSON. A compact format of the request
2285 will also give a compact representation of the response. If the request
2286 contains an "id" field, it is assumed to be a JSON-RPC request and the
2287 response will contain a "jsonrpc" field and the "id" of the request.
2288 The request format uses the same commands as the standard CLI, the
2289 "method" field contains the command and the parameters (if any) are
2290 given in the "params" list. The response contains a "result" object,
2291 which can also be null if the corresponding kid3-cli command does not
2292 return a result. In case of an error, an "error" object is returned
2293 with "code" and "message" fields as used in JSON-RPC.
2294 kid3-cli> {"method":"set","params":["artist","An Artist"]}
2296 {"result":null}
2297 kid3-cli> {"method":"get","params":["artist",2]}
2298 {"result":"An Artist"}
2299 kid3-cli> {"method": "get", "params": ["artist"]}
2300 {
2301 "result": "An Artist"
2302 }
2303 kid3-cli> {"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}
2305 {"id":"123","jsonrpc":"2.0","result":"An Artist"}
2306
2309 Kid3
2310 Program written by Urs Fleisch <ufleisch at users.sourceforge.net>
2312 FDL[22]
2314 GPL[23]
2316
2318 How to obtain Kid3
2319 Kid3 can be found at https://kid3.kde.org.
2320 Requirements
2322 Kid3 needs Qt(TM)[24]. KDE[25] is recommended but not necessary, as
2323 Kid3 can also be compiled as a Qt(TM) application. Kid3 can be
2324 compiled for systems where these libraries are available, e.g. for
2325 GNU/Linux®, Windows® and macOS®. To tag Ogg/Vorbis files, libogg[15],
2326 libvorbis and libvorbisfile[16] are required, for FLAC files libFLAC++
2327 and libFLAC[17]. id3lib[14] is used for MP3 files. These four formats
2328 are also supported by TagLib[18], which can also handle Opus, MPC, APE,
2329 MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker
2330 modules. To import from acoustic fingerprints, Chromaprint[20] and
2331 libav[21] are used.
2332 Kid3 is available for most Linux® distributions, Windows® and macOS®.
2334 Links can be found on https://kid3.kde.org.
2335 Compilation and Installation
2337 You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple
2338 Qt(TM) application and lacks some configuration and session features.
2339 For a KDE version, go into the top folder and type
2341 % cmake .
2343 % make
2344 % make install
2345 To compile for different versions of Qt(TM) or KDE, set the
2347 corresponding cmake options.
2348 If not all libraries are present, Kid3 is built with reduced
2350 functionality. So you should take care to have all desired development
2351 packages installed. On the other side, cmake-options control which
2352 libraries are compiled in. The default is -DWITH_TAGLIB:BOOL=ON
2353 -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON
2354 -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON . These options can be
2355 disabled using OFF.
2356 To build Kid3 as a Qt(TM) application without KDE, use the cmake option
2358 -DWITH_APPS=Qt. To build both a KDE and a Qt(TM) application, set
2359 -DWITH_APPS="Qt;KDE".
2360 To use a specific Qt(TM) installation, set
2362 -DQT_QMAKE_EXECUTABLE=/path/to/qmake.
2363 Generation of RPM-Packages is supported by the file kid3.spec, for
2365 Debian® Packages, run build.sh deb.
2366 The Qt(TM) application can also be compiled for Windows® and macOS®.
2368 The script build.sh can be used to download and build all required
2369 libraries and create a Kid3 package.
2370 Configuration
2372 With KDE, the settings are stored in .config/kid3rc, the application
2373 state in .local/share/kid3/kid3staterc. As a Qt(TM) application, this
2374 file is in .config/Kid3/Kid3.conf. On Windows®, the configuration is
2375 stored in the registry. on macOS® in a plist file.
2376 The environment variable KID3_CONFIG_FILE can be used to set the path
2378 of the configuration file.
2379
2381 D-Bus Examples
2382 On Linux® a D-Bus-interface can be used to control Kid3 by scripts.
2383 Scripts can be written in any language with D-Bus-bindings (e.g. in
2384 Python) and can be added to the User Actions to extend the
2385 functionality of Kid3.
2386 The artist in tag 2 of the current file can be set to the value "One
2388 Hit Wonder" with the following code:
2389 Shell
2391 dbus-send --dest=org.kde.kid3 --print-reply=literal \
2393 /Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
2394 string:'One Hit Wonder'
2395 or easier with Qt(TM)'s qdbus (qdbusviewer can be used to explore
2397 the interface in a GUI):
2398 qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
2400 'One Hit Wonder'
2401 Python
2403 import dbus
2405 kid3 = dbus.SessionBus().get_object(
2406 'org.kde.kid3', '/Kid3')
2407 kid3.setFrame(2, 'Artist', 'One Hit Wonder')
2408 Perl
2410 use Net::DBus;
2412 $kid3 = Net::DBus->session->get_service(
2413 "org.kde.kid3")->get_object(
2414 "/Kid3", "org.kde.Kid3");
2415 $kid3->setFrame(2, "Artist", "One Hit Wonder");
2416 D-Bus API
2418 The D-Bus API is specified in org.kde.Kid3.xml. The Kid3 interface has
2419 the following methods:
2420 Open file or folder
2422 boolean openDirectory(string path);
2423 path
2425 path to file or folder
2426 Returns true if OK.
2428 Unload the tags of all files which are not modified or selected
2430 unloadAllTags(void);
2431 Save all modified files
2433 boolean save(void);
2434 Returns true if OK.
2436 Get a detailed error message provided by some methods
2438 string getErrorMessage(void);
2439 Returns detailed error message.
2441 Revert changes in the selected files
2443 revert(void);
2444 Start an automatic batch import
2446 boolean batchImport(int32 tagMask, string profileName);
2447 tagMask
2449 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2450 profileName
2452 name of batch import profile to use
2453 Import tags from a file
2455 boolean importFromFile(int32 tagMask, string path, int32 fmtIdx);
2456 tagMask
2458 tag bit (1 for tag 1, 2 for tag 2)
2459 path
2461 path of file
2462 fmtIdx
2464 index of format
2465 Returns true if OK.
2467 Import tags from other tags
2469 importFromTags(int32 tagMask, string source, string extraction);
2470 tagMask
2472 tag bit (1 for tag 1, 2 for tag 2)
2473 source
2475 format to get source text from tags
2476 extraction
2478 regular expression with frame names and captures to extract
2479 from source text
2480 Import tags from other tags on selected files
2482 array importFromTagsToSelection(int32 tagMask, string source,
2483 string extraction);
2484 tagMask
2486 tag bit (1 for tag 1, 2 for tag 2)
2487 source
2489 format to get source text from tags
2490 extraction
2492 regular expression with frame names and captures to extract
2493 from source text
2494 returnValues
2496 extracted value for "%{__return}(.+)"
2497 Download album cover art
2499 downloadAlbumArt(string url, boolean allFilesInDir);
2500 url
2502 URL of picture file or album art resource
2503 allFilesInDir
2505 true to add the image to all files in the folder
2506 Export tags to a file
2508 boolean exportToFile(int32 tagMask, string path, int32 fmtIdx);
2509 tagMask
2511 tag bit (1 for tag 1, 2 for tag 2)
2512 path
2514 path of file
2515 fmtIdx
2517 index of format
2518 Returns true if OK.
2520 Create a playlist
2522 boolean createPlaylist(void);
2523 Returns true if OK.
2525 Get items of a playlist
2527 array getPlaylistItems(string path);
2528 path
2530 path to playlist file
2531 Returns list of absolute paths to playlist items.
2533 Set items of a playlist
2535 boolean setPlaylistItems(string path, array items);
2536 path
2538 path to playlist file
2539 items
2541 list of absolute paths to playlist items
2542 Returns true if OK, false if not all items were found and added or
2544 saving failed.
2545 Quit the application
2547 quit(void);
2548 Select all files
2550 selectAll(void);
2551 Deselect all files
2553 deselectAll(void);
2554 Set the first file as the current file
2556 boolean firstFile(void);
2557 Returns true if there is a first file.
2559 Set the previous file as the current file
2561 boolean previousFile(void);
2562 Returns true if there is a previous file.
2564 Set the next file as the current file
2566 boolean nextFile(void);
2567 Returns true if there is a next file.
2569 Select the first file
2571 boolean selectFirstFile(void);
2572 Returns true if there is a first file.
2574 Select the previous file
2576 boolean selectPreviousFile(void);
2577 Returns true if there is a previous file.
2579 Select the next file
2581 boolean selectNextFile(void);
2582 Returns true if there is a next file.
2584 Select the current file
2586 boolean selectCurrentFile(void);
2587 Returns true if there is a current file.
2589 Expand or collapse the current file item if it is a folder
2591 boolean expandDirectory(void);
2592 A file list item is a folder if getFileName() returns a name with
2594 '/' as the last character.
2595 Returns true if current file item is a folder.
2597 Apply the file name format
2599 applyFilenameFormat(void);
2600 Apply the tag format
2602 applyTagFormat(void);
2603 Apply text encoding
2605 applyTextEncoding(void);
2606 Set the folder name from the tags
2608 boolean setDirNameFromTag(int32 tagMask, string format,
2609 boolean create);
2610 tagMask
2612 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2613 format
2615 folder name format
2616 create
2618 true to create, false to rename
2619 Returns true if OK, else the error message is available using
2621 getErrorMessage().
2622 Set subsequent track numbers in the selected files
2624 numberTracks(int32 tagMask, int32 firstTrackNr);
2625 tagMask
2627 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2628 firstTrackNr
2630 number to use for first file
2631 Filter the files
2633 filter(string expression);
2634 expression
2636 filter expression
2637 Convert ID3v2.3 tags to ID3v2.4
2639 convertToId3v24(void);
2640 Convert ID3v2.4 tags to ID3v2.3
2642 convertToId3v23(void);
2643 Returns true if OK.
2645 Get path of folder
2647 string getDirectoryName(void);
2648 Returns absolute path of folder.
2650 Get name of current file
2652 string getFileName(void);
2653 Returns true absolute file name, ends with "/" if it is a folder.
2655 Set name of selected file
2657 setFileName(string name);
2658 name
2660 file name
2661 The file will be renamed when the folder is saved.
2663 Set format to use when setting the filename from the tags
2665 setFileNameFormat(string format);
2666 format
2668 file name format
2669 Set the file names of the selected files from the tags
2671 setFileNameFromTag(int32 tagMask);
2672 tagMask
2674 tag bit (1 for tag 1, 2 for tag 2)
2675 Get value of frame
2677 string getFrame(int32 tagMask, string name);
2678 tagMask
2680 tag bit (1 for tag 1, 2 for tag 2)
2681 name
2683 name of frame (e.g. "artist")
2684 To get binary data like a picture, the name of a file to write can
2686 be added after the name, e.g. "Picture:/path/to/file". In the same
2687 way, synchronized lyrics can be exported, e.g.
2688 "SYLT:/path/to/file".
2689 Returns value of frame.
2691 Set value of frame
2693 boolean setFrame(int32 tagMask, string name, string value);
2694 tagMask
2696 tag bit (1 for tag 1, 2 for tag 2)
2697 name
2699 name of frame (e.g. "artist")
2700 value
2702 value of frame
2703 For tag 2 (tagMask 2), if no frame with name exists, a new frame is
2705 added, if value is empty, the frame is deleted. To add binary data
2706 like a picture, a file can be added after the name, e.g.
2707 "Picture:/path/to/file". "SYLT:/path/to/file" can be used to import
2708 synchronized lyrics.
2709 Returns true if OK.
2711 Get all frames of a tag
2713 array of string getTag(int32 tagMask);
2714 tagMask
2716 tag bit (1 for tag 1, 2 for tag 2)
2717 Returns list with alternating frame names and values.
2719 Get technical information about file
2721 array of string getInformation(void);
2722 Properties are Format, Bitrate, Samplerate, Channels, Duration,
2724 Channel Mode, VBR, Tag 1, Tag 2. Properties which are not available
2725 are omitted.
2726 Returns list with alternating property names and values.
2728 Set tag from file name
2730 setTagFromFileName(int32 tagMask);
2731 tagMask
2733 tag bit (1 for tag 1, 2 for tag 2)
2734 Set tag from other tag
2736 setTagFromOtherTag(int32 tagMask);
2737 tagMask
2739 tag bit (1 for tag 1, 2 for tag 2)
2740 Copy tag
2742 copyTag(int32 tagMask);
2743 tagMask
2745 tag bit (1 for tag 1, 2 for tag 2)
2746 Paste tag
2748 pasteTag(int32 tagMask);
2749 tagMask
2751 tag bit (1 for tag 1, 2 for tag 2)
2752 Remove tag
2754 removeTag(int32 tagMask);
2755 tagMask
2757 tag bit (1 for tag 1, 2 for tag 2)
2758 Reparse the configuration
2760 reparseConfiguration(void);
2761 Automated configuration changes are possible by modifying the
2763 configuration file and then reparsing the configuration.
2764 Plays the selected files
2766 playAudio(void);
2767
2769 QML Examples
2770 QML scripts can be invoked via the context menu of the file list and
2771 can be set in the tab User Actions of the settings dialog. The scripts
2772 which are set there can be used as examples to program custom scripts.
2773 QML uses JavaScript, here is the obligatory "Hello World":
2774 import Kid3 1.0
2776 Kid3Script {
2778 onRun: {
2779 console.log("Hello world, folder is", app.dirName)
2780 Qt.quit()
2781 }
2782 }
2783 If this script is saved as /path/to/Example.qml, the user command can
2785 be defined as @qml /path/to/Example.qml with name QML Test and Output
2786 checked. It can then be started using the QML Test item in the file
2787 list context menu, and the output will be visible in the window.
2788 Unfortunately, starting the QML scripts using the qml (e.g. qml
2790 -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml)
2791 is broken in recent versions of Qt. But kid3-cli offers an alternative
2792 way to run a QML script from the command line using its execute
2793 command.
2794 kid3-cli -c "execute @qml /path/to/Example.qml"
2796 To list the titles in the tags 2 of all files in the current folder,
2798 the following script could be used:
2799 import Kid3 1.0
2801 Kid3Script {
2803 onRun: {
2804 app.firstFile()
2805 do {
2806 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2807 console.log(app.getFrame(tagv2, "title"))
2808 }
2809 } while (app.nextFile())
2810 }
2811 }
2812 If the folder contains many files, such a script might block the user
2814 interface for some time. For longer operations, it should therefore
2815 have a break from time to time. The alternative implementation below
2816 has the work for a single file moved out into a function. This function
2817 invokes itself with a timeout of 1 ms at the end, given that more files
2818 have to be processed. This will ensure that the GUI remains responsive
2819 while the script is running.
2820 import Kid3 1.0
2822 Kid3Script {
2824 onRun: {
2825 function doWork() {
2826 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2827 console.log(app.getFrame(tagv2, "title"))
2828 }
2829 if (!app.nextFile()) {
2830 Qt.quit()
2831 } else {
2832 setTimeout(doWork, 1)
2833 }
2834 }
2835 app.firstFile()
2837 doWork()
2838 }
2839 }
2840 When using app.firstFile() with app.nextFile(), all files of the
2842 current folder will be processed. If only the selected files shall be
2843 affected, use firstFile() and nextFile() instead, these are convenience
2844 functions of the Kid3Script component. The following example is a
2845 script which copies only the disc number and copyright frames of the
2846 selected file.
2847 import Kid3 1.1
2849 Kid3Script {
2851 onRun: {
2852 function doWork() {
2853 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2854 app.setFrame(tagv2, "*.selected", false)
2855 app.setFrame(tagv2, "discnumber.selected", true)
2856 app.setFrame(tagv2, "copyright.selected", true)
2857 app.copyTags(tagv2)
2858 }
2859 if (!nextFile()) {
2860 Qt.quit()
2861 } else {
2862 setTimeout(doWork, 1)
2863 }
2864 }
2865 firstFile()
2867 doWork()
2868 }
2869 }
2870 More example scripts come with Kid3 and are already registered as user
2872 commands.
2873 • ReplayGain to SoundCheck (ReplayGain2SoundCheck.qml): Create
2875 iTunNORM SoundCheck information from replay gain frames.
2876 • Resize Album Art (ResizeAlbumArt.qml): Resize embedded cover art
2878 images which are larger than 500x500 pixels.
2879 • Extract Album Art (ExtractAlbumArt.qml): Extract all embedded cover
2881 art pictures avoiding duplicates.
2882 • Embed Album Art (EmbedAlbumArt.qml): Embed cover art found in image
2884 files into audio files in the same folder.
2885 • Embed Lyrics (EmbedLyrics.qml): Fetch unsynchronized lyrics from
2887 web service.
2888 • Text Encoding ID3v1 (ShowTextEncodingV1.qml): Helps to find the
2890 encoding of ID3v1 tags by showing the tags of the current file in
2891 all available character encodings.
2892 • ID3v1 to ASCII (Tag1ToAscii.qml): Transliterate extended latin
2894 characters in the ID3v1 tag to ASCII.
2895 • English Title Case (TitleCase.qml): Formats text in the tags to
2897 English title case.
2898 • Rewrite Tags (RewriteTags.qml): Rewrite all tags in the selected
2900 files.
2901 • Export CSV (ExportCsv.qml): Export recursively all tags of all
2903 files to a CSV file.
2904 • Import CSV (ImportCsv.qml): Import recursively all tags of all
2906 files from a CSV file.
2907 • Export JSON (ExportJson.qml): Export recursively all tags of all
2909 files to a JSON file.
2910 • Import JSON (ImportJson.qml): Import recursively all tags of all
2912 files from a JSON file.
2913 • Export Playlist Folder (ExportPlaylist.qml): Copy all files from a
2915 playlist into a folder and rename them according to their position.
2916 • QML Console (QmlConsole.qml): Simple console to play with Kid3's
2918 QML API.
2919 QML API
2922 The API can be easily explored using the QML Console, which is
2923 available as an example script with a user interface.
2924 Kid3Script
2926 Kid3Script is a regular QML component located inside the plugin
2927 folder. You could use another QML component just as well. Using
2928 Kid3Script makes it easy to start the script function using the
2929 onRun signal handler. Moreover it offers some functions:
2930 onRun: Signal handler which is invoked when the script is started
2932 tagv1, tagv2, tagv2v1: Constants for tag parameters
2933 script: Access to scripting functions
2934 configs: Access to configuration objects
2935 getArguments(): List of script arguments
2936 isStandalone(): true if the script was not started from within Kid3
2937 setTimeout(callback, delay): Starts callback after delay ms
2938 firstFile(): To first selected file
2939 nextFile(): To next selected file
2940 Scripting Functions
2943 As JavaScript and therefore QML too has only a limited set of
2944 functions for scripting, the script object has some additional
2945 methods, for instance:
2946 script.properties(obj): String with Qt properties
2948 script.writeFile(filePath, data): Write data to file, true if OK
2949 script.readFile(filePath): Read data from file
2950 script.removeFile(filePath): Delete file, true if OK
2951 script.fileExists(filePath): true if file exists
2952 script.fileIsWritable(filePath): true if file is writable
2953 script.getFilePermissions(filePath): Get file permission mode bits
2954 script.setFilePermissions(filePath, modeBits): Set file permission mode bits
2955 script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
2956 file " ")
2957 script.renameFile(oldName, newName): Rename file, true if OK
2958 script.copyFile(source, dest): Copy file, true if OK
2959 script.makeDir(path): Create folder, true if OK
2960 script.removeDir(path): Remove folder, true if OK
2961 script.tempPath(): Path to temporary folder
2962 script.musicPath(): Path to music folder
2963 script.listDir(path, [nameFilters], [classify]): List folder entries
2964 script.system(program, [args], [msecs]): Synchronously start a system command,
2965 [exit code, standard output, standard error] if not timeout
2966 script.systemAsync(program, [args], [callback]): Asynchronously start a system
2967 command, callback will be called with [exit code, standard output, standard
2968 error]
2969 script.getEnv(varName): Get value of environment variable
2970 script.setEnv(varName, value): Set value of environment variable
2971 script.getQtVersion(): Qt version string, e.g. "5.4.1"
2972 script.getDataMd5(data): Get hex string of the MD5 hash of data
2973 script.getDataSize(data): Get size of byte array
2974 script.dataToImage(data, [format]): Create an image from data bytes
2975 script.dataFromImage(img, [format]): Get data bytes from image
2976 script.loadImage(filePath): Load an image from a file
2977 script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
2978 script.imageProperties(img): Get properties of an image, map containing
2979 "width", "height", "depth" and "colorCount", empty if invalid image
2980 script.scaleImage(img, width, [height]): Scale an image, returns scaled image
2981 Application Context
2983 Using QML, a large part of the Kid3 functions are accessible. The
2984 API is similar to the one used for D-Bus. For details, refer to the
2985 respective notes.
2986 app.openDirectory(path): Open folder
2988 app.unloadAllTags(): Unload all tags
2989 app.saveDirectory(): Save folder
2990 app.revertFileModifications(): Revert
2991 app.importTags(tag, path, fmtIdx): Import file
2992 app.importFromTags(tag, source, extraction): Import from tags
2993 app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
2994 app.downloadImage(url, allFilesInDir): Download image
2995 app.exportTags(tag, path, fmtIdx): Export file
2996 app.writePlaylist(): Write playlist
2997 app.getPlaylistItems(path): Get items of a playlist
2998 app.setPlaylistItems(path, items): Set items of a playlist
2999 app.selectAllFiles(): Select all
3000 app.deselectAllFiles(): Deselect
3001 app.firstFile([select], [onlyTaggedFiles]): To first file
3002 app.nextFile([select], [onlyTaggedFiles]): To next file
3003 app.previousFile([select], [onlyTaggedFiles]): To previous file
3004 app.selectCurrentFile([select]): Select current file
3005 app.selectFile(path, [select]): Select a specific file
3006 app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
3007 app.requestExpandFileList(): Expand all
3008 app.applyFilenameFormat(): Apply filename format
3009 app.applyTagFormat(): Apply tag format
3010 app.applyTextEncoding(): Apply text encoding
3011 app.numberTracks(nr, total, tag, [options]): Number tracks
3012 app.applyFilter(expr): Filter
3013 app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
3014 app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
3015 app.getFilenameFromTags(tag): Filename from tags
3016 app.getTagsFromFilename(tag): Filename to tags
3017 app.getAllFrames(tag): Get object with all frames
3018 app.getFrame(tag, name): Get frame
3019 app.setFrame(tag, name, value): Set frame
3020 app.getPictureData(): Get data from picture frame
3021 app.setPictureData(data): Set data in picture frame
3022 app.copyToOtherTag(tag): Tags to other tags
3023 app.copyTags(tag): Copy
3024 app.pasteTags(tag): Paste
3025 app.removeTags(tag): Remove
3026 app.playAudio(): Play
3027 app.readConfig(): Read configuration
3028 app.applyChangedConfiguration(): Apply configuration
3029 app.dirName: Folder name
3030 app.selectionInfo.fileName: File name
3031 app.selectionInfo.filePath: Absolute file path
3032 app.selectionInfo.detailInfo: Format details
3033 app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
3034 app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
3035 app.selectionInfo.formatString(tag, format): Substitute codes in format string
3036 app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
3037 select a file
3038 app.selectDirName(caption, dir): Open file dialog to select a folder
3039 For asynchronous operations, callbacks can be connected to signals.
3041 function automaticImport(profile) {
3043 function onAutomaticImportFinished() {
3044 app.batchImporter.finished.disconnect(onAutomaticImportFinished)
3045 }
3046 app.batchImporter.finished.connect(onAutomaticImportFinished)
3047 app.batchImport(profile, tagv2)
3048 }
3049 function renameDirectory(format) {
3051 function onRenameActionsScheduled() {
3052 app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
3053 app.performRenameActions()
3054 }
3055 app.renameActionsScheduled.connect(onRenameActionsScheduled)
3056 app.renameDirectory(tagv2v1, format, false)
3057 }
3058 Configuration Objects
3060 The different configuration sections are accessible via methods of
3061 configs. Their properties can be listed in the QML console.
3062 script.properties(configs.networkConfig())
3064 Properties can be set:
3066 configs.networkConfig().useProxy = false
3068 configs.batchImportConfig()
3072 configs.exportConfig()
3073 configs.fileConfig()
3074 configs.filenameFormatConfig()
3075 configs.filterConfig()
3076 configs.findReplaceConfig()
3077 configs.guiConfig()
3078 configs.importConfig()
3079 configs.mainWindowConfig()
3080 configs.networkConfig()
3081 configs.numberTracksConfig()
3082 configs.playlistConfig()
3083 configs.renDirConfig()
3084 configs.tagConfig()
3085 configs.tagFormatConfig()
3086 configs.userActionsConfig()
3087
3089 Urs Fleisch <ufleisch at users.sourceforge.net>
3090 Software development
3091
3093 Copyright © 2022 Urs Fleisch
3094 FDL
3096
3099 1. gnudb.org
3100 http://gnudb.org
3101 2. MusicBrainz
3103 http://musicbrainz.org
3104 3. Discogs
3106 http://discogs.com
3107 4. Amazon
3109 http://www.amazon.com
3110 5. ID3 specification
3112 http://id3.org/id3v2.4.0-frames
3113 6. SYLT Editor
3115 http://www.compuphase.com/software_sylteditor.htm
3116 7. www.gnudb.org
3118 http://www.gnudb.org
3119 8. Discogs
3121 https://www.discogs.com/
3122 9. freedb.org
3124 http://freedb.org
3125 10. ID3 tag version 2.3.0
3127 http://id3.org/id3v2.3.0
3128 11. ID3 tag version 2.4.0 - Main Structure
3130 http://id3.org/id3v2.4.0-structure
3131 12. LyricWiki
3133 http://www.lyricwiki.org
3134 13. Google
3136 http://www.google.com
3137 14. id3lib
3139 http://id3lib.sourceforge.net
3140 15. libogg
3142 http://xiph.org/ogg/
3143 16. libvorbis, libvorbisfile
3145 http://xiph.org/vorbis/
3146 17. libFLAC++ and libFLAC
3148 http://flac.sourceforge.net
3149 18. TagLib
3151 http://taglib.github.io/
3152 19. mp4v2
3154 http://code.google.com/p/mp4v2
3155 20. Chromaprint
3157 http://acoustid.org/chromaprint
3158 21. libav
3160 http://libav.org/
3161 22. FDL
3163 http://www.gnu.org/licenses/licenses.html#FDL
3164 23. GPL
3166 http://www.gnu.org/licenses/licenses.html#GPL
3167 24. Qt(TM)
3169 https://www.qt.io
3170 25. KDE
3172 http://www.kde.org
31733.9.1 2022-01-15 KID3(1)