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 TrackType.org[2], MusicBrainz[3], Discogs[4], Amazon[5] or other
85 sources of track lists. The import format is freely configurable by
86 regular expressions.
87 Please report any problems or feature requests to the author.
89
91 Kid3 features
92 · Edit ID3v1.1 tags
93 · Edit all ID3v2.3 and ID3v2.4 frames
95 · Edit tags of multiple files
97 · Convert between ID3v1 and ID3v2 tags
99 · Edit MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2,
101 Speex, TrueAudio, WavPack, WMA, WAV and AIFF tags
102 · Generate tags from filename
104 · Generate tags from the contents of tag fields
106 · Generate filename from tags
108 · Generate and change folder names from tags
110 · Generate playlist file
112 · Automatic case conversion and string translation
114 · Import from gnudb.org[1], TrackType.org[2], MusicBrainz[3],
116 Discogs[4], Amazon[5] and other data sources
117 · Export as CSV, HTML, playlist, Kover XML and other formats.
119 Exported CSV files can be imported again.
120 Example Usage
122 This section describes a typical session with Kid3. Let's assume we
123 have a folder containing MP3 files with the tracks from the album
124 "Let's Tag" from the band "One Hit Wonder". The folder is named in the
125 "artist - album" format, in our case One Hit Wonder - Let's Tag. The
126 folder contains the tracks in the "track title.mp3" format, which I
127 think is useful because the filenames are short (important when using
128 mobile MP3 players with small displays) and in the correct order when
129 sorted alphabetically (important when using hardware MP3 players which
130 play the tracks in alphabetical order or in the order in which they are
131 burnt on CD and that order is alphabetical when using mkisofs). Besides
132 this, the artist and album information is already in the folder name
133 and does not have to be repeated in the filename. But back to our
134 example, the folder listing looks like this:
135 01 Intro.mp3
137 02 We Only Got This One.mp3
139 03 Outro.mp3
141 These files have no tags yet and we want to generate them using Kid3.
143 We use File → Open menu item (or toolbar button) and select one of the
144 files in this folder. All files will be displayed in the file listbox.
145 Lazy as we are, we want to use the information in the folder and file
146 names to generate tags. Therefore we select all files, then click the
147 To: Tag 1 button in the File section. This will set the title, artist,
148 album and track values in all files. To set the year and genre values
149 of all files, we keep all files selected and type in "2002" for the
150 Date and select "Pop" from the Genre combobox. To set only these two
151 values, their check boxes are automatically checked and all other check
152 boxes are left unchecked. Now we change the selection by only selecting
153 the first file and we see that all tags contain the correct values. The
154 tags of the other files can be verified too by selecting them one by
155 one. When we are satisfied with the tags, we use File → Save menu item
156 (or toolbar button). Selecting File → Create Playlist menu item (or
157 toolbar button) will generate a file One Hit Wonder - Let's Tag.m3u in
158 the folder.
159
161 The GUI Elements
162 The Kid3 GUI is separated in six sections: At the left are the file and
163 folder listboxes, the right side contains the File, Tag 1, Tag 2 and
164 Tag 3 sections.
165 To navigate between the different sections using the keyboard, several
167 keyboard shortcuts are supported. In the tag sections, the shortcuts
168 are active while not editing text or when being in the first column.
169 · Alt+Left: Go to previous section (Command+[ on macOS®)
171 · Alt+Right: Go to next section (Command+] on macOS®)
173 · Ctrl+Shift+V: From other tag
175 · Ctrl+C: Copy
177 · Ctrl+V: Paste
179 · Shift+Delete: Remove
181 · F2: Edit
183 · Insert: Add
185 · Delete: Delete
187 File List
189 The file list contains the names of all the files in the opened
190 folder which match the selected file name filter (typically *.mp3
191 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2
192 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). A single or multiple
193 files can be selected. To select no file, click into the empty area
194 after the listbox entries. The selection determines the files which
195 are affected by the operations which are available by using the
196 buttons described below.
197 Besides Name, also other columns Size, Type, Date Modified with
199 file details can be displayed. Columns can be hidden by unchecking
200 their name in the context menu of the list header. The order of the
201 columns can be changed by drag and drop. The sort order can be
202 toggled by clicking on the column header.
203 At the left of the names an icon can be displayed: a disc to show
205 that the file has been modified or information about which tags are
206 present (V1, V2, V1V2 or NO TAG, no icon is displayed if the file
207 has not been read in yet).
208 Folders are displayed with a folder icon. If a folder is opened,
210 its files are displayed in a hierarchical tree. By selecting files
211 from subfolders, operations can be executed on files in different
212 folders, which is useful if the music collection is organized with
213 a folder for each artist containing folders for albums of this
214 artist.
215 Clicking the right mouse button inside the file list opens a
217 context menu with the following commands:
218 · Expand all: Expands all folder trees (only the current tree if
220 the Shift key is pressed)
221 · Collapse all: Collapses all folder trees
223 · Rename: Changes the name of a file
225 · Move to Trash: Moves a file to the trash
227 · Play: Plays a file, see Play. If the selected file is a
229 playlist, the files of the playlist will be played.
230 · Edit: Edit a playlist, see Edit Playlist.
232 · The subsequent entries are user commands, which can be defined
234 in the User Actions tab of Configure Kid3. The playback on
235 double click can also be activated there.
236 Edit Playlist
239 A playlist can be created empty or containing the tracks of a
240 folder, see Create Playlist. The playlist file created in such a
241 way can be edited by double click or using Edit from the file list
242 context menu. A dialog with the entries of the playlist is shown.
243 It is possible to open multiple playlists simultaneously.
244 New entries can be added by drag and drop from the file list, a
246 file manager or another playlist. If an entry is dragged from
247 another playlist, it will be moved or copied depending on the
248 system. To invoke the other operation, respectively, the Shift,
249 Ctrl or Alt (to copy instead of move on macOS®) key has to be
250 pressed. Reordering entries within the playlist is also possible
251 via drag and drop. Alternatively, entries can be moved using the
252 keyboard shortcuts Ctrl+Shift+Up and Ctrl+Shift+Down (on macOS®
253 Command has to be pressed instead of Ctrl). An entry can be removed
254 using the Delete key.
255 Please note the following: To drag entries from the file list, they
257 have to be held at the left side (near the icons), the same gesture
258 at the right side will perform a multi selection, such an action is
259 hereby still easily possible.
260 When a playlist has been modified, the changes can be stored using
262 Save or discarded using Cancel. When the window is closed, a
263 confirmation prompt is shown if there are unsaved changes.
264 Tracks selected in a playlist will be automatically selected in the
266 file list, thereby making it possible to edit their tags.
267 To execute actions on a playlist, its file must be selected in the
269 file list. Edit from the context menu will lead to the dialog
270 described in this section, and Play will start the media player
271 with the tracks from the playlist. User actions can act on
272 playlists, for example Export Playlist Folder, which copies the
273 files from a playlist into a folder.
274 Folder List
276 The folder list contains the names of the folders in the opened
277 folder, as well as the current (.) and the parent (..) folder. It
278 allows one to quickly change the folder without using the Open
279 command or drag and drop.
280 Column visibility, order and sorting can be configured as described
282 in the section about the file list.
283 File
285 Shows information about the encoding (MP3, Ogg, Opus, DSF, FLAC,
286 MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV,
287 AIFF), bit rate, sample rate, channels and the length of the file.
288 The Name line edit contains the name of the file (if only a single
290 file is selected). If this name is changed, the file will be
291 renamed when the Save command is used.
292 The Format combo box and line edit contains the format to be used
294 when the filename is generated from the first or the second tag.
295 The filename can contain arbitrary characters, even a folder part
296 separated by a slash from the file name, but that folder must
297 already exist for the renaming to succeed. The following special
298 codes are used to insert tag values into the filename:
299 · %s %{title} Title (Song)
301 · %a %{artist} Artist
303 · %l %{album} Album
305 · %c %{comment} Comment
307 · %y %{year} Year
309 · %t %{track} Track (e.g. 01)
311 · %t %{track.n} Track with field width n (e.g. 001 for
313 %{track.3})
314 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
316 · %g %{genre} Genre
318 · %{ignore} Ignored when generating tags from the file name
320 The format codes are not restricted to the examples given above.
322 Any frame name can be used, for instance unified frame names like
323 %{albumartist}, %{discnumber.1}, %{bpm} or format specific names
324 like %{popm}.
325 It is possible to prepend and append strings to the replacement for
327 a format code by adding them in double quotes inside the curly
328 braces of a format code. These strings will only be put into the
329 resulting string if the format code yields a nonempty value. For
330 example, if the file name shall both contain the title and the
331 subtitle, one could use %{title} [%{subtitle}] in the format
332 string. But this would result in a string ending with [] if no
333 subtitle frame exists for a file. In order to omit the brackets if
334 no subtitle is present, %{title}%{" ["subtitle"]"} shall be used
335 instead. This will omit the brackets, the leading space and the
336 subtitle if not subtitle exists.
337 The list of available formats can be edited in the dialog which
339 appears when clicking the Filename from tag button in the File tab
340 of the settings.
341 A second Format combo box (with arrow down) is used to generate the
343 tags from the filename. If the format of the filename does not
344 match this pattern, a few other commonly used formats are tried.
345 Some commonly used filename formats are already available in the
347 combo box, but it is also possible to type in some special format
348 into the line edit.
349 The list of available formats can be edited in the dialog which
351 appears when clicking the Tag from filename button in the File tab
352 of the settings.
353 Internally, a regular expression is built from the format codes. If
355 advanced regular expressions are required, the format to generate
356 the tags from the filenames can be given as a complete regular
357 expression with captures which are preceded by the format codes,
358 e.g. to extract the track numbers without removal of leading
359 zeros, a format like "/%{track}(\d+) %{title}(.*)" could be used.
360 From: Tag 1, Tag 2: Sets the filename using the selected format and
362 the first tag or the second tag, respectively.
363 To: Tag 1, Tag 2: The tags are set from the filename. First, the
365 format specified in Format is used. If the existing filename does
366 not match this format, the following formats are tried:
367 · Artist - Album/Track Song
369 · Album/Track - Artist - Song
371 · /Artist - Album - Track - Song
373 · Album/Artist - Track - Song
375 · Album/Artist - Song
377 · Artist/Album/Track Song
379 If a single file is selected, the GUI controls are filled with the
381 values extracted from the filename. If multiple files are selected,
382 the tags of the files are directly set according to the filenames.
383 Tag 1
385 The line edit widgets for Title, Artist, Album, Comment, Date,
386 Track Number and Genre are used to edit the corresponding value in
387 the first tag of the selected files. The value will be changed when
388 the file selection is altered or before operations like Save and
389 Quit and when the corresponding check box at the left of the field
390 name is checked. This is useful to change only some values and
391 leave the other values unchanged.
392 If a single file is selected, all check boxes are checked and the
394 line edit widgets contain the values found in the tags of this
395 file. If a tag is not found in the file, the corresponding empty
396 value is displayed, which is an empty string for the Title, Artist,
397 Album and Comment line edits, 0 for the numerical Date and Track
398 Number edits and an empty selected value for the Genre combo box.
399 The values can be changed and if the corresponding check box is
400 checked, they will be set for the selected file after the selection
401 is changed. The file is then marked as modified by a disk symbol in
402 the file listbox but remains unchanged until the Save command is
403 used.
404 If multiple files are selected, only the values which are identical
406 in all selected files are displayed. In all other controls, the
407 empty values as described above are displayed. All check boxes are
408 unchecked to avoid unwanted changes. If a value has to be set for
409 all selected files, it can be edited and the check box has to be
410 set. The values will be set for all selected files when the
411 selection is changed and can be saved using the Save command.
412 The check boxes also control the operation of most commands
414 affecting the tags, such as copy, paste and transfer between tags 1
415 and 2. To make it easier to use with multiple files where all check
416 boxes are unchecked, these commands behave in the same way when all
417 check boxes are checked and when all check boxes are unchecked.
418 From Tag 2: The tag 1 fields are set from the corresponding values
420 in tag 2. If a single file is selected, the GUI controls are filled
421 with the values from tag 2. If multiple files are selected, the
422 tags of the files are directly set.
423 Copy: The copy buffer is filled with the Tag 1 values. Only values
425 with checked check box will be used in subsequent Paste commands.
426 Paste: Pastes the values from the copy buffer into the GUI
428 controls.
429 Remove: This will set all GUI controls to their empty values which
431 results in removing all values. The saved file will then contain no
432 tag 1.
433 Tag 2
435 The GUI controls function in the same way as described for the Tag
436 1 section, but the size of the strings is not limited.
437 For the tag 2 Genre you can also use your own names besides the
439 genres listed in the combo box, just type the name into the line
440 edit.
441 The tag 2 cannot only contain the same values as the tag 1, the
443 format is built in a flexible way from several frames which are
444 themselves composed of several fields. The tag 2 table shows all
445 the frames which are available in the selected file.
446 Edit: This will open a window which allows one to edit all fields
448 of the selected frame. If multiple files are selected, the edited
449 fields are applied to all selected files which contain such a
450 frame.
451 Add: A requester to select the frame type will appear and a frame
453 of the selected type can be edited and added to the file. This
454 works also to add a frame to multiple selected files.
455 Delete: Deletes the selected frame in the selected files.
457 Drag album artwork here is shown if the file does not contain
459 embedded cover art. A picture can be added using drag and drop from
460 a browser or file manager and will be displayed here. Picture
461 frames can be edited or added by double clicking on this control.
462 Tag 3
464 Some files can have more than two tags, and a third tag section is
465 visible. The following file types can have such a Tag 3 section:
466 · MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0)
468 tag and in the third section an APE tag. Such APE tags are used
469 for replay gain information. In the Tag 3 section, this
470 information is visible, and the APE tag can be removed with the
471 Remove button.
472 · The RIFF INFO chunk of WAV files is available in the Tag 3
474 section because the Tag 1 section is dedicated to ID3v1.1 tags
475 and handles their restrictions. The Tag 2 is still used for
476 ID3v2.4.0 tags, which are also supported for WAV files, but
477 RIFF INFO chunks seem to be supported better.
478 · FLAC files normally use a Vorbis comment for their meta data.
480 However, there are FLAC files which have ID3v1 and ID3v2 tags,
481 which can be found in the Tag 1 and Tag 3 sections. ID3 tags in
482 FLAC files are only supported by TagLib, therefore the
483 OggFlacMetadata plugin has to be disabled in the Plugins tab of
484 the settings.
485 The GUI controls work in the same way as in the Tag 2 section.
487 Synchronized Lyrics and Event Timing Codes
489 For information synchronized with the audio data, a specific editor
490 is available. These frames are supported for ID3v2.3.0 and
491 ID3v2.4.0 tags. To add such a frame, the specific frame name has to
492 be selected in the list which appears when the Add button is
493 clicked - Synchronized Lyrics or Event Timing Codes, respectively.
494 The editor is the same for both types, for the event timing codes,
495 only a predefined set of events is available whereas for the
496 synchronized lyrics, text has to be entered. In the following,
497 editing synchronized lyrics is explained.
498 A file having an ID3v2 tag is selected, the lyrics editor is
500 entered using Add and selecting Synchronized Lyrics. For an
501 existing Synchronized Lyrics frame, it is selected and Edit is
502 clicked. The player is automatically opened with the current file
503 so that the file can be played and paused to synchronize lyrics.
504 The settings at the top of the SYLT editor normally do not have to
506 be changed. If the lyrics contains characters which are not present
507 in the Latin 1 character set, changing the text encoding to UTF16
508 (or UTF8 for ID3v2.4.0) is advisable. For English lyrics and
509 maximum compatibility, ISO-8859-1 should be used.
510 The Lyrics section has five buttons at the top. Add will add a new
512 time event in the table. The time is taken from the position of the
513 player, thus adding an entry while playing the track will add a
514 line for the currently played position. The events in the table
515 have to be chronologically ordered, therefore the row will be
516 inserted accordingly. Entries with an invalid time are treated
517 specially: If the currently selected row has an invalid time, its
518 time stamp will be replaced by the current time instead of adding a
519 new row. If the current time is not invalid, the first row with an
520 invalid time will be used if present. This behavior should
521 facilitate adding time stamps if the lyrics text is already in the
522 table but the time stamps are missing (which is the case when
523 importing unsynchronized lyrics). Note that the invalid time is
524 represented as 00:00.00, i.e. the same as the time at the absolute
525 beginning of the track, which is not invalid. To make a time
526 invalid, press the Delete key, or use Clear from the context menu.
527 New rows inserted using Insert row from the context menu or created
528 when importing unsynchronized lyrics with From Clipboard or Import
529 also contain invalid time stamps. Rows in the table can be deleted
530 by clicking the Delete button or using Delete rows from the context
531 menu.
532 Synchronized lyrics can be imported from a file using Import. The
534 expected format is simple or enhanced LRC. If the selected file
535 does not contain a square bracket in the first line, it is supposed
536 to be a simple text file with unsynchronized lyrics. The lines from
537 such a file are then imported having invalid time stamps. The time
538 information can be added using the Add button or by manual entry.
539 It is also possible to import lyrics via copy-paste using From
540 Clipboard. Synchronized lyrics can be written to LRC files using
541 Export. Note that only entries with valid time stamps will be
542 exported and that the entries will be sorted by time. Entries with
543 invalid time won't be stored in the SYLT frame either, so make sure
544 to include all timing information before leaving the dialog.
545 The ID3 specification[6] suggests a time stamp for each syllable.
547 However most players only support the granularity of a line or
548 sentence. To support both use cases, Kid3 follows the same
549 conventions as SYLT Editor[7]. Text which is entered into the table
550 is assumed to start a new line unless it starts with a space or a
551 hyphen. Exceptions to this rule are possible by starting a line
552 with an underscore ('_') to force continuation or a hash mark ('#')
553 to force a new line. These escape characters are not stored inside
554 the SYLT frame. Inside the SYLT frame, new lines start with a line
555 feed character (hex 0A) whereas continuations do not. When reading
556 SYLT frames, Kid3 checks if the first entry starts with a line
557 feed. If this is not the case, it is assumed that all entries are
558 new lines and that no syllable continuations are used.
559 While the track is played, the row associated with the current
561 playing position is highlighted, so that the correctness of the
562 synchronization information can be verified. If an offset has to be
563 added to one or more time stamps, this can be accomplished with the
564 Add offset context menu. Negative values can be used to reduce the
565 time. Using Seek to position in the context menu, it is possible to
566 set the playing position to the time of the selected row.
567 Recommended procedure to add new synchronized lyrics
569 · Get the unsynchronized lyrics, e.g. using Lyrics → Embed
571 Lyrics from the file list context menu.
572 · Copy the unsynchronized lyrics to the clipboard, just go to the
574 Lyrics row in the frame table and press Ctrl+C.
575 · Add a synchronized lyrics frame (Add..., Synchronized Lyrics,
577 OK), click From Clipboard.
578 · Now all lines from the unsynchronized lyrics are in the table,
580 all time stamps are invalid (0:0:0.00). You can delete empty
581 entries beforehand.
582 · Start playing the song by clicking the play button ► in the
584 play toolbar at the bottom of the main window.
585 · When the next lyrics line with invalid timestamp comes, click
587 Add or press Alt+A, the timestamp will be updated.
588 · Continue like this until all timestamps are set. If you missed
590 something, stop playback and clear the timestamps using the
591 Delete key or by selecting them and using Clear from the
592 context menu. To restart playback from a given timestamp, use
593 Seek to position from the context menu.
594 The File Menu
597 File → Open... (Ctrl+O)
598 Opens a folder. All files matching the selected file name filter
599 will be displayed in the file listbox and the chosen file is
600 selected.
601 File → Open Recent
603 Opens a recently opened folder.
604 File → Open Folder... (Ctrl+D)
606 Opens a folder. All files matching the selected file name filter
607 will be displayed in the file listbox.
608 File → Reload (F5)
610 Reload folder. Modified files have to be saved before. Expanded
611 subfolders will be collapsed.
612 File → Save (Ctrl+S)
614 Saves all changed files in the folder. The changed files are
615 marked with a disk symbol in the file listbox. If any file names
616 have been changed, those files will be renamed.
617 File → Revert
619 Reverts the changes of one or multiple files. If no files are
620 selected in the file listbox, the changes of all files will be
621 reverted, else only the changes of the selected files are reverted.
622 File → Import...
624 The Import dialog can be used to import data directly from a
625 freedb.org server, from a MusicBrainz server, from Discogs, Amazon
626 or other sources of album track lists in textual format.
627 Import from a freedb.org server is possible using a dialog which
629 appears when From Server: gnudb.org or TrackType.org is selected.
630 The artist and album name to search for can be entered in the two
631 topmost fields, the albums which match the query will be displayed
632 when Find is clicked and the results from www.gnudb.org[8] are
633 received. Importing the track data for an album is done by
634 double-clicking the album in the list. The freedb.org server to
635 import from can be selected as well as the CGI path. The imported
636 data is displayed in the preview table of the import dialog. When
637 satisfied with the displayed tracks, they can be imported by
638 terminating the import dialog with OK.
639 A search on the Discogs server can be performed using Discogs. As
641 in the gnudb.org dialog, you can enter artist and album and then
642 choose from a list of releases. If Standard Tags is marked, the
643 standard information is imported, e.g. artist, album, and title.
644 If Additional Tags is marked, more information is imported if
645 available, e.g. performers, arrangers, or the publisher. If Cover
646 Art is marked, cover art will be downloaded if available.
647 A search on Amazon can be performed using Amazon. As in the
649 gnudb.org dialog, you can enter artist and album and then choose
650 from a list of releases. If Additional Tags is marked, more
651 information is imported if available, e.g. performers, arrangers,
652 or the publisher. If Cover Art is marked, cover art will be
653 downloaded if available.
654 You can search in the same way in the release database of
656 MusicBrainz using From MusicBrainz Release. The workflow is the
657 same as described for From gnudb.org.
658 Import from a MusicBrainz server is possible using the dialog which
660 appears when From MusicBrainz Fingerprint is selected. The Server
661 can be selected as in the freedb import dialog. Below is a table
662 displaying the imported track data. The right column shows the
663 state of the MusicBrainz query, which starts with "Pending" when
664 the dialog is opened. Then the fingerprint is looked up and if it
665 does not yield a result, another lookup using the tags in the file
666 is tried. Thus it can be helpful for a successful MusicBrainz query
667 to store known information (e.g. artist and album) in the tags
668 before the import. If a result was found, the search ends in the
669 state "Recognized", otherwise nothing was found or multiple
670 ambiguous results and one of them has to be selected by the user.
671 OK and Apply use the imported data, Cancel closes the dialog. The
672 closing can take a while since the whole MusicBrainz machinery has
673 to be shut down.
674 For the import of textual data, From File/Clipboard opens a
676 subdialog, where several preconfigured import formats are
677 available. The first two, "CSV unquoted" and "CSV quoted" can be
678 used to import data which was exported by the Export dialog. The
679 CSV data can be edited with a spreadsheet, and shall be written
680 using tabs as delimiters. Import should then be possible using "CSV
681 quoted", which is more flexible than "CSV unquoted". However, its
682 fields cannot contain any double quotes. If you only export from
683 Kid3 and import later, "CSV unquoted" can be used as a simple
684 format for this purpose. Note that there are also "Export CSV" and
685 "Import CSV" commands in the context menu of the file list, which
686 use scripts to export and import CSV data in a more complete,
687 powerful and flexible way.
688 The next format, "freedb HTML text", can be used to copy
690 information from an HTML page of freedb.org[9]. Search an album in
691 freedb and if the desired information is displayed in the web
692 browser, copy the contents to the clipboard. Then click the From
693 Clipboard button and the imported tracks will be displayed in the
694 preview table at the top of the dialog. If you are satisfied with
695 the imported data, terminate the dialog with OK, which will insert
696 the data into the tags of the current folder. The destination (Tag
697 1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box. The
698 files in the current folder should be in the correct track order to
699 get their tags assigned. This is the case if they are numbered.
700 The next preconfigured import format, "freedb HTML source", can be
702 used, if the data is available as an HTML document. Import is
703 possible using the From File button, which opens a file selector,
704 or copying its contents from an editor and then importing from
705 clipboard. This format can be useful for offline import, although
706 the HTML document could also be opened in a browser and then be
707 imported in the first format via the clipboard.
708 More preconfigured formats, e.g. "Track Title Time", are
710 available. An empty custom format can be created with Add to be set
711 by the user. Two lines below the format name can be set with a
712 regular expression to capture the fields from the import text. The
713 first regular expression will be parsed once per document to gather
714 per-album data such as artist, album, year and genre. The second
715 line is tried to match from the start of the document to the end to
716 get track data, usually number and title. The regular expressions
717 include all the features offered by Qt(TM), which is most of the
718 what Perl offers. Bracketing constructs "(..)" create capture
719 buffers for the fields to import and are preceded by Kid3 specific
720 codes to specify which field to capture. The codes are the same as
721 used for the filename format, besides the codes listed below, any
722 frame name is possible:
723 · %s %{title} Title (Song)
725 · %a %{artist} Artist
727 · %l %{album} Album
729 · %c %{comment} Comment
731 · %y %{year} Year
733 · %t %{track} Track
735 · %g %{genre} Genre
737 · %d %{duration} Duration
739 For example, a track regular expression (second line) to import
741 from an .m3u playlist could be
742 "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]". All formats can
743 be changed by editing the regular expressions and the name and then
744 clicking Save Settings. They will be stored in the kid3rc file in
745 the configuration folder. This file can be directly edited to have
746 more import formats or it can be deleted to revert to the default
747 formats. Formats can be deleted using Remove.
748 Accuracy shows an estimation of how good the imported information
750 matches the given tracks. It uses track durations or file names to
751 calculate the level of similarity in percent. Cover Art shows the
752 URL of the album cover image which will be downloaded.
753 To check whether the imported tracks match the current set of
755 files, the duration of the imported tracks can be compared with the
756 duration of the files. This option can be enabled with the check
757 box Check maximum allowable time difference (sec): and the maximum
758 tolerated difference in time can be set in seconds. If a mismatch
759 in a length is detected, the length is displayed with a red
760 background in the preview table.
761 If the files are ordered differently than the imported tracks,
763 their assigned tracks have to be changed. This task can be
764 facilitated using the Match with option with the buttons Length,
765 Track, and Title, which will reorder the tracks according to the
766 corresponding field. To correct the assignments manually, a track
767 can be dragged with the left mouse button and the Ctrl key hold
768 down, and then dropped at the new location.
769 When the import dialog is opened, it contains the actual contents
771 of the tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be
772 selected using the Destination combo box. The button on the right
773 of this combo box can be used to revert the table to the current
774 contents of the tags. The check boxes in the first table column can
775 be used to select the tracks which are imported. This can be useful
776 if a folder contains the tracks of both CDs of a double CD and only
777 the tracks of the second CD have to be imported.
778 To identify the tracks which are imported, it is possible to
780 display the file names or the full paths to the files using the
781 context menu of the table header. The values in the import table
782 can be edited. The revert-button to the right of the Destination
783 combo box can be used to restore the contents of the tags, which
784 can also be useful after changing the Destination.
785 Almost all dialogs feature a Save Settings button, which can be
787 used to store the dialog specific settings and the window size
788 persistently.
789 From Tags leads to a subdialog to set tag frames from the contents
791 of other tag frames. This can be used to simply copy information
792 between tags or extract a part from one frame and insert it in
793 another.
794 As in the import from file/clipboard dialog, there are freely
796 configurable formats to perform different operations. Already
797 preconfigured are formats to copy the Album value to Album Artist,
798 Composer or Conductor, and to extract the Track Number from Title
799 fields which contain a number. There is also a format to extract a
800 Subtitle from a Title field.
801 The following example explains how to add a custom format, which
803 sets the information from the Subtitle field also in the Comment
804 field. Create a new format using Add button and set a new name,
805 e.g. "Subtitle to Comment". Then enter "%{subtitle}" in Source and
806 "%{comment}(.*)" for Extraction and click Save Settings.
807 The expression in Source can contain format codes for arbitrary tag
809 frames, multiple codes can be used to combine the contents from
810 different frames. For each track, a text is generated from its tags
811 using the Source format, and the regular expression from Extraction
812 is applied to this text to set new values for the tags. Format
813 codes are used before the capturing parentheses to specify the tag
814 frame where the captured text shall be stored. It works in the same
815 way as for the import from file/clipboard.
816 Import from Tags... is also directly available from the File menu.
818 The difference between these two functions is that the import
819 dialog subdialog operates on all files of the current folder
820 whereas the menu function operates on the selected files (which can
821 be in different folders). The menu function supports an additional
822 code "%{__return}" to return the extracted value, which can be
823 useful with the CLI and QML interfaces.
824 File → Import from gnudb.org...
826 Import from a freedb.org server using gnudb.org album search. This
827 menu item opens the same import dialog as Import..., but opens
828 directly the gnudb.org dialog.
829 File → Import from TrackType.org...
831 Import from the TrackType.org server. This menu item opens the
832 same import dialog as Import..., but opens directly the
833 TrackType.org dialog.
834 File → Import from Discogs...
836 Import from the Discogs server. This menu item opens the same
837 import dialog as Import..., but opens directly the From Discogs
838 dialog.
839 File → Import from Amazon...
841 Import from Amazon. This menu item opens the same import dialog as
842 Import..., but opens directly the From Amazon dialog.
843 File → Import from MusicBrainz Release...
845 Import from the MusicBrainz release database. This menu item opens
846 the same import dialog as Import..., but opens directly the From
847 MusicBrainz Release dialog.
848 File → Import from MusicBrainz Fingerprint...
850 Import from a MusicBrainz server. This menu item opens the same
851 import dialog as Import..., but opens directly the From MusicBrainz
852 Fingerprint dialog.
853 File → Import from Tags...
855 Like From Tags, but the import is applied to the selected files.
856 File → Automatic Import...
858 Automatic Import allows one to import information for multiple
859 albums from various web services. If folders are selected in the
860 file list, track data for the selected folders will be imported. If
861 no folder is selected, all folders in the file list will be
862 imported.
863 The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using
865 the Destination combo box.
866 Profiles determine which servers will be contacted to fetch album
868 information. Some profiles are predefined (All, MusicBrainz,
869 Discogs, Cover Art), custom profiles can be added using the Add
870 button at the right of the Profile combo box.
871 The table below shows the servers which will be used when importing
873 album information using the selected profile. The import process
874 for an album is finished if all required information has been
875 found, so the order of the rows in the table is important. It can
876 be changed using the Move Up and Move Down buttons. Edit can be
877 used to change an existing entry. The Server selection offers the
878 same servers as can be used in the import functions. Standard
879 Tags, Additional Tags, Cover Art determine the information which
880 shall be fetched from the server. Finally, Accuracy is the minimum
881 accuracy which must be achieved to accept the imported data. If the
882 accuracy is insufficient, the next server in the list will be
883 tried. The same dialog containing the server properties appears
884 when Add is clicked to add a new server entry. Existing entries can
885 be deleted using Remove.
886 To launch an automatic batch import with the selected profile,
888 click Start. Details about the running import are displayed at the
889 top of the dialog. The process can be aborted with the Abort
890 button.
891 File → Browse Cover Art...
894 The Browse Cover Art dialog helps to find album cover art.
895 Artist/Album is filled from the tags if possible. Source offers a
896 variety of websites with album cover art. The URL with artist and
897 album as parameters can be found beneath the name. URL-encoded
898 values for artist and album can be inserted using "%u{artist}" and
899 "%u{album}", other values from the tags are possible too, as
900 described in Configure Kid3, User Actions. More sources can be
901 entered after the entry "Custom Source" by replacing "Custom
902 Source" with the source's name, pressing Enter, then inserting the
903 URL and finally pressing Save Settings. The resulting browser
904 command is displayed at the top of the dialog and can be started by
905 clicking Browse. The browser, which can be configured in the
906 settings, is started with the selected source. A cover image can
907 then be dragged from the browser into the Kid3 window and will be
908 set in the picture frame of the selected files.
909 Because not all browsers support drag and drop of images and the
911 pictures on websites often have a URL, in such cases Kid3 will
912 receive the URL and not the picture. If the URL points to a
913 picture, it will be downloaded. However, if the URL refers to some
914 other web resource, it has to be translated to the corresponding
915 picture. Such mappings are defined in the table URL extraction. The
916 left column Match contains a regular expression which is compared
917 with the URL. If it matches, the captured expressions in
918 parentheses are inserted into the pattern of the right Picture URL
919 column (at the positions marked with \1 etc.). The replaced regular
920 expression contains the URL of the picture. By this means cover art
921 can be imported from Amazon, Google Images, etc. using drag and
922 drop. It is also possible to define your own mappings.
923 File → Export...
925 The Export Dialog is used to store data from the tags in a file or
926 the clipboard. The editor at the top shows a preview of the data to
927 export. If the export data contain tabulator characters, the export
928 is displayed in a table. The data will be generated from the tags
929 in the current folder according to the configured format.
930 The format settings are similar as in the Import dialog: The
932 topmost field contains the title (e.g. "CSV unquoted"), followed
933 by the header, which will be generated at the begin of the file.
934 The track data follows; it is used for every track. Finally, the
935 trailer can be used to generate some finishing text.
936 The format fields do not contain regular expressions as in the
938 Import dialog, but only output format expressions with special
939 %-expressions, which will be replaced by values from the tags. The
940 whole thing works like the file name format, and the same codes are
941 used plus some additional codes. Not only the codes listed below
942 but all tag frame names can be used.
943 · %s %{title} Title (Song)
945 · %a %{artist} Artist
947 · %l %{album} Album
949 · %c %{comment} Comment
951 · %y %{year} Year
953 · %t %{track} Track (e.g. 01)
955 · %t %{track.n} Track with field width n (e.g. 001 for
957 %{track.3})
958 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
960 · %g %{genre} Genre
962 · %f %{file} File name
964 · %p %{filepath} Path
966 · %{modificationdate} Modification date
968 · %{creationdate} Creation date
970 · %u %{url} URL
972 · %{dirname} Folder name
974 · %d %{duration} Duration in minutes:seconds
976 · %D %{seconds} Duration in seconds
978 · %n %{tracks} Number of tracks of the album
980 · %e %{extension} File extension
982 · %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
984 existing)
985 · %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
987 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
988 existing)
989 · %b %{bitrate} Bit rate in kbit/s
991 · %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
993 · %r %{samplerate} Sample rate in Hz
995 · %m %{mode} Channel mode (Stereo or Joint Stereo)
997 · %h %{channels} Number of channels (1 or 2)
999 · %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1001 MPC, APE, ASF, AIFF, WAV)
1002 A few formats are predefined. "CSV unquoted" separates the fields
1004 by tabs. Data in this format can be imported again into Kid3 using
1005 the import format with the same name. "CSV quoted" additionally
1006 encloses the fields by double quotes, which eases the import into
1007 spreadsheet applications. However, the fields shall not contain any
1008 double quotes when this format is used. "Extended M3U" and
1009 "Extended PLS" generate playlists with extended attributes and
1010 absolute path names. "HTML" can be used to generate an HTML page
1011 with hyperlinks to the tracks. "Kover XML" creates a file which can
1012 be imported by the cover printing program Kover. "Technical
1013 Details" provides information about bit rate, sample rate,
1014 channels, etc. Finally, "Custom Format" is left empty for
1015 definition of a custom format. You can define more formats of your
1016 own by adding lines in the file kid3rc in the configuration folder.
1017 The other formats can be adapted to your needs.
1018 The Source of the tags to generate the export data (Tag 1 or Tag 2)
1020 can be selected with a combo box. Pushing To File or To Clipboard
1021 stores the data in a file or on the clipboard. OK and Cancel close
1022 the dialog, whereas OK accepts the current dialog settings.
1023 File → Create Playlist...
1025 Creates a playlist. The format and contents of the playlist can be
1026 set by various options.
1027 The name of the playlist can be the Same as folder name or use a
1029 Format with values from the tags, e.g. "%{artist} - %{album}" to
1030 have the artist and album name in the playlist file name. The
1031 format codes are the same as for Export. Create new empty playlist
1032 will make an empty playlist with the given name. The extension
1033 depends on the playlist format.
1034 The location of the generated playlist is determined by the
1036 selection of the Create in combo box.
1037 Current folder
1039 The playlist is created in the current folder and contains only
1040 files of the current folder. The current folder is the folder
1041 where the current file is located. If multiple files are
1042 selected, the current file is probably the last selected file.
1043 Every folder
1045 A playlist is created in every folder which contains listed
1046 files, and each playlist contains the files of that folder.
1047 Top-level folder
1049 Only one playlist is created in the top-level folder (i.e. the
1050 folder of the file list) and it contains the listed files of
1051 the top-level folder and all of its sub-folders.
1052 The Format of the playlist can be M3U, PLS or XSPF.
1054 If Include only the selected files is checked, only the selected
1056 files will be included in the playlist. If a folder is selected,
1057 all of its files are selected. If this check box is not activated,
1058 all audio files are included in the playlist.
1059 Sort by file name selects the usual case where the files are
1061 ordered by file name. With Sort by tag field, it is possible to
1062 sort by a format string with values from tag fields. For instance,
1063 "%{track.3}" can be used to sort by track number (the ".3" is used
1064 to get three digits with leading zeros because strings are used for
1065 sorting). It is also possible to use multiple fields, e.g.
1066 "%{genre}%{year}" to sort using a string composed of genre and
1067 year.
1068 The playlist entries will have relative or absolute file paths
1070 depending on whether Use relative path for files in playlist or Use
1071 full path for files in playlist is set.
1072 When Write only list of files is set, the playlist will only
1074 contain the paths to the files. To generate an extended playlist
1075 with additional information, a format string can be set using the
1076 Write info using control.
1077 File → Quit (Ctrl+Q)
1079 Quits the application.
1080 The Edit Menu
1082 Edit → Select All (Alt+A)
1083 Selects all files.
1084 Edit → Deselect (Ctrl+Shift+A)
1086 Deselects all files.
1087 Edit → Select All in Folder
1089 Selects all files of the current folder.
1090 Edit → Previous File (Alt+Up)
1092 Selects the previous file.
1093 Edit → Next File (Alt+Down)
1095 Selects the next file.
1096 Edit → Find... (Ctrl+F)
1098 Find strings in the file names and the tags. The Find dialog is a
1099 subset of the Replace dialog, which is described below.
1100 Edit → Replace... (Ctrl+R)
1102 This function opens a dialog to find and replace strings in the
1103 file names and the tags. The set of frames where the search is
1104 performed can be restricted by deactivating the Select all check
1105 box and selecting the frames which shall be searched. There are
1106 also search options available to search backwards, case
1107 sensitively, and to use regular expressions.
1108 Depending on the number of files, the search might take some time,
1110 therefore it can be aborted by closing the dialog.
1111 The Tools Menu
1113 Tools → Apply Filename Format
1114 When Automatically apply format is switched off for the filename
1115 format in the configuration dialog, this menu item can be used to
1116 apply the configured format to the names of the selected files.
1117 This can also be used to check whether the file names conform with
1118 the configured format by applying the format to all saved files and
1119 then checking if any files were changed (and therefore marked with
1120 a disk symbol in the file listbox).
1121 Tools → Apply Tag Format
1123 When Automatically apply format is switched off for the tag format
1124 in the configuration dialog, this menu item can be used to apply
1125 the configured format to the tags of the selected files. This can
1126 also be used to check whether the tags conform with the configured
1127 format by applying the format to all saved files and then checking
1128 if any files were changed (and therefore marked with a disk symbol
1129 in the file listbox).
1130 Tools → Apply Text Encoding
1132 Sets the Text encoding selected in Settings → Configure Kid3... →
1133 Tags section → Tag 2 tab for all selected files. If UTF8 is
1134 selected, UTF16 will be used for ID3v2.3.0 tags because UTF8 is not
1135 supported for this format.
1136 Tools → Rename Folder...
1138 This dialog offers the possibility to automatically rename the
1139 currently open folder according to the tags in the files. Several
1140 formats are preconfigured to include information about artist,
1141 album and year in the folder name. It is also possible to set a
1142 custom format and Edit the list of available formats. The following
1143 special codes are used to insert tag values into the folder name:
1144 · %s %{title} Title (Song)
1146 · %a %{artist} Artist
1148 · %l %{album} Album
1150 · %c %{comment} Comment
1152 · %y %{year} Year
1154 · %t %{track} Track (e.g. 01)
1156 · %t %{track.n} Track with field width n (e.g. 001 for
1158 %{track.3})
1159 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
1161 · %g %{genre} Genre
1163 · %{dirname} Folder name (e.g. %{year" "}%{dirname} will prepend
1165 the year to the current folder name)
1166 · %{max-year} The maximum year value found for this folder, can
1168 also be used with other codes than "year"
1169 · %{min-year} The minimum year value found for this folder
1171 · %{unq-year} The unique year value found for this folder or
1173 empty if not unique
1174 If a folder separator "/" is found in the format, multiple folders
1176 are created. If you want to create a new folder instead of renaming
1177 the current folder, in the Action combo box select Create Folder
1178 instead of Rename Folder. The Source of the tag information can be
1179 chosen between Tag 1 and Tag 2, Tag 1 and Tag 2. A preview for the
1180 rename operation performed on the first file can be seen in the
1181 From and To sections of the dialog.
1182 Multiple folders can be renamed by selecting them.
1184 Tools → Number Tracks...
1186 If the track numbers in the tags are not set or have the wrong
1187 values, this function can number the tracks automatically in
1188 ascending order. The start number can be set in the dialog. If only
1189 part of the tracks have to be numbered, they must be selected.
1190 When Total number of tracks is checked, the number of tracks will
1192 also be set in the tags.
1193 It is possible to number the tracks over multiple folders. The
1195 folders have to be expanded and selected.
1196 If Reset counter for each folder is checked, track numbering is
1198 restarted with the given number for each folder when multiple
1199 folders are selected.
1200 The number tracks dialog can also be used to format existing track
1202 numbers without changing the values when the check box left to
1203 Start number is deactivated. The total number of tracks will be
1204 added if the corresponding check box is active, which can be used
1205 to set the total for all selected tracks. If only formatting of the
1206 existing numbers is desired, this check box has to be deactivated
1207 too.
1208 Tools → Filter...
1210 The filter can be used to display only those files which match
1211 certain criteria. This is helpful if you want to organize a large
1212 collection and only edit those files which are not in the desired
1213 scheme. The expression defining which files to display uses the
1214 same format codes which are used in the file name format, import
1215 and export.
1216 · %s %{title} Title (Song)
1218 · %a %{artist} Artist
1220 · %l %{album} Album
1222 · %c %{comment} Comment
1224 · %y %{year} Year
1226 · %t %{track} Track (e.g. 01)
1228 · %t %{track.n} Track with field width n (e.g. 001 for
1230 %{track.3})
1231 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
1233 · %g %{genre} Genre
1235 · %f %{file} File name
1237 · %p %{filepath} Absolute path to file
1239 · %e %{extension} File extension
1241 · %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1243 existing)
1244 · %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1246 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
1247 existing)
1248 · %b %{bitrate} Bit rate in kbit/s
1250 · %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
1252 · %r %{samplerate} Sample rate in Hz
1254 · %m %{mode} Channel mode (Stereo or Joint Stereo)
1256 · %h %{channels} Number of channels (1 or 2)
1258 · %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1260 MPC, APE, ASF, AIFF, WAV)
1261 · %w %{marked} Marked, is 1 if the file is marked (e.g. because
1263 of truncation or standard violation), empty otherwise
1264 · %1a %1{artist}, ... Use the prefix 1 to get values of tag 1
1266 · %2a %2{artist}, ... Use the prefix 2 to get values of tag 2
1268 These codes are replaced with the values for the file, and the
1270 resulting strings can be compared with the following operations:
1271 · s1 equals s2: true if s1 and s2 are equal.
1273 · s1 contains s2: true if s1 contains s2, i.e. s2 is a substring
1275 of s1.
1276 · s matches re: true if s matches the regular expression re.
1278 True expressions are replaced by 1, false by 0. True values are
1280 represented by 1, true, on and yes, false values by 0, false, off
1281 and no. Boolean operations are not, and, or (in this order of
1282 precedence) and can be grouped by parentheses.
1283 Some filter rules are predefined and can serve as examples for your
1285 own expressions:
1286 All
1288 When the file list is filtered - this is shown by "[filtered]"
1289 in the window title - and all files shall be displayed again,
1290 the filtering can be reverted using this filter. It uses an
1291 empty expression, but a true value would have the same effect.
1292 Filename Tag Mismatch
1294 not (%{filepath} contains "%{artist} - %{album}/%{track}
1295 %{title}")
1296 Tests if the file path conforms with the file name format. This
1298 rule is automatically adapted if the file name format changes.
1299 No Tag 1
1301 %{tag1} equals ""
1302 Displays only files which do not have a tag 1.
1304 No Tag 2
1306 %{tag2} equals ""
1307 Displays only files which do not have a tag 2.
1309 ID3v2.3.0 Tag
1311 %{tag2} equals "ID3v2.3.0"
1312 Displays only files which have an ID3v2.3.0 tag.
1314 ID3v2.4.0 Tag
1316 %{tag2} equals "ID3v2.4.0"
1317 Displays only files which have an ID3v2.4.0 tag.
1319 Tag 1 != Tag 2
1321 not (%1{title} equals %2{title} and %1{album} equals %2{album}
1322 and %1{artist} equals %2{artist} and %1{comment} equals
1323 %2{comment} and %1{year} equals %2{year} and %1{track} equals
1324 %2{track} and %1{genre} equals %2{genre})
1325 Displays files with differences between tag 1 and tag2.
1327 Tag 1 == Tag 2
1329 %1{title} equals %2{title} and %1{album} equals %2{album} and
1330 %1{artist} equals %2{artist} and %1{comment} equals %2{comment}
1331 and %1{year} equals %2{year} and %1{track} equals %2{track} and
1332 %1{genre} equals %2{genre}
1333 Displays files with identical tag 1 and tag 2.
1335 Incomplete
1337 %{title} equals "" or %{artist} equals "" or %{album} equals
1338 "" or %{year} equals "" or %{tracknumber} equals "" or %{genre}
1339 equals ""
1340 Displays files with empty values in the standard tags (title,
1342 artist, album, date, track number, genre).
1343 No Picture
1345 %{picture} equals ""
1346 Displays only files which do not have a picture.
1348 Marked
1350 not (%{marked} equals "")
1351 Displays only files which are marked because they violate the
1353 ID3 standard, are truncated or the picture is too large.
1354 Custom Filter
1356 To add your own filter, select this entry. For instance, if you
1357 want to have a filter for artists starting with "The", replace
1358 "Custom Filter" with the name "The Bands" and press Enter. Then
1359 insert the following expression into the line edit:
1360 %{artist} matches "The.*"
1362 Then click Save Settings. Click Apply to filter the files. All
1364 files processed are displayed in the text view, with a "+" for
1365 those who match the filter and a "-" for the others. When
1366 finished, only the files with an artist starting with "The" are
1367 displayed, and the window title is marked with "[filtered]".
1368 Tools → Convert ID3v2.3 to ID3v2.4
1370 If there are any ID3v2.3 tags in the selected files, they will be
1371 converted to ID3v2.4 tags. Frames which are not supported by TagLib
1372 will be discarded. Only files without unsaved changes will be
1373 converted.
1374 Tools → Convert ID3v2.4 to ID3v2.3
1376 If there are any ID3v2.4 tags in the selected files, they will be
1377 converted to ID3v2.3 tags. Only files without unsaved changes will
1378 be converted.
1379 Tools → Play
1381 This opens a simple toolbar to play audio files. It contains
1382 buttons for the basic operations (Play/Pause, Stop playback,
1383 Previous Track, Next Track, Close), sliders for position and volume
1384 and a display of the current position. If multiple files are
1385 selected, the selected tracks are played, else all files will be
1386 played.
1387 The Settings Menu
1389 Settings → Show Toolbar
1390 Toggles displaying of the toolbar.
1391 Settings → Show Statusbar
1393 Toggles displaying of the statusbar, which displays longer actions
1394 such as opening or saving a folder.
1395 Settings → Show Picture
1397 Toggles displaying of the album cover art preview picture.
1398 Settings → Auto Hide Tags
1400 Empty tags are automatically hidden if this option is active. The
1401 File, Tag 1 and Tag 2 sections can be manually collapsed and
1402 expanded by clicking on the corresponding -/+ buttons.
1403 Settings → Configure Shortcut keys...
1405 Opens a dialog to assign keyboard shortcuts for most of the program
1406 functions. There are even functions without corresponding menu or
1407 button available, e.g. next file, previous file, select all.
1408 Settings → Configure Kid3...
1411 Opens the configuration dialog, which consists of pages for tags,
1412 files, user actions, and network settings.
1413 Tag specific options can be found on the Tags page, which is itself
1415 separated into four tabs for Tag 1, Tag 2, Tag 3, and All Tags.
1416 If Mark truncated fields is checked, truncated ID3v1.1 fields will
1418 be marked red. The text fields of ID3v1.1 tags can only have 30
1419 characters, the comment only 28 characters. Also the genre and
1420 track numbers are restricted, so that fields can be truncated when
1421 imported or transferred from ID3v2. Truncated fields and the file
1422 will be marked red, and the mark will be removed after the field
1423 has been edited.
1424 With Text encoding for ID3v1 it is possible to set the character
1426 set used in ID3v1 tags. This encoding is supposed to be ISO-8859-1,
1427 so it is recommended to keep this default value. However, there are
1428 tags around with different encoding, so it can be set here and the
1429 ID3v1 tags can then be copied to ID3v2 which supports Unicode.
1430 The check box Use track/total number of tracks format controls
1432 whether the track number field of ID3v2 tags contains simply the
1433 track number or additionally the total number of tracks in the
1434 folder.
1435 When Genre as text instead of numeric string is checked, all ID3v2
1437 genres will be stored as a text string even if there is a
1438 corresponding code for ID3v1 genres. If this option is not set,
1439 genres for which an ID3v1 code exists are stored as the number of
1440 the genre code (in parentheses for ID3v2.3). Thus the genre Metal
1441 is stored as "Metal" or "(9)" depending on this option. Genres
1442 which are not in the list of ID3v1 genres are always stored as a
1443 text string. The purpose of this option is improved compatibility
1444 with devices which do not correctly interpret genre codes.
1445 When WAV files with lowercase id3 chunk is checked, the RIFF chunk
1447 used to store ID3v2 tags in WAV files will be named "id3 " instead
1448 of "ID3 ". By default, Kid3 and other applications using TagLib
1449 accept both the lowercase and the uppercase variant when reading
1450 WAV files, but they use "ID3 " when writing ID3v2 tags to WAV
1451 files. As there exist other applications which only accept "id3 "
1452 (e.g. JRiver Media Center and foobar2000), this option can be used
1453 to create tags which can be read by such applications.
1454 When Mark standard violations is checked, ID3v2 fields which
1456 violate the standard will be marked red. Details about the
1457 violation are shown in a tooltip:
1458 · Must be unique
1460 · New line is forbidden
1462 · Carriage return is forbidden
1464 · Owner must be non-empty
1466 · Must be numeric
1468 · Must be numeric or number/total
1470 · Format is DDMM
1472 · Format is HHMM
1474 · Format is YYYY
1476 · Must begin with a year and a space character
1478 · Must be ISO 8601 date/time
1480 · Must be musical key, 3 characters, A-G, b, #, m, o
1482 · Must have ISO 639-2 language code, 3 lowercase characters
1484 · Must be ISRC code, 12 characters
1486 · Must be list of strings separated by '|'
1488 · Has excess white space
1490 The ID3 standard documents are available online:
1492 · ID3 tag version 2.3.0[10]
1494 · ID3 tag version 2.4.0 - Main Structure[11]
1496 · ID3 tag version 2.4.0 - Native Frames[6]
1498 Text encoding defines the default encoding used for ID3v2 frames
1500 and can be set to ISO-8859-1, UTF16, or UTF8. UTF8 is not valid
1501 for ID3v2.3.0 frames; if it is set, UTF16 will be used instead. For
1502 ID3v2.4.0 frames, all three encodings are possible.
1503 Version used for new tags determines whether new ID3v2 tags are
1505 created as version 2.3.0 or 2.4.0.
1506 Track number digits is the number of digits in Track Number fields.
1508 Leading zeros are used to pad. For instance, with a value of 2 the
1509 track number 5 is set as "05".
1510 The combo box Comment field name is only relevant for Ogg/Vorbis
1512 and FLAC files and sets the name of the field used for comments.
1513 Different applications seem to use different names, "COMMENT" for
1514 instance is used by XMMS, whereas Amarok uses "DESCRIPTION".
1515 The format of pictures in Ogg/Vorbis files is determined by Picture
1517 field name, which can be "METADATA_BLOCK_PICTURE" or "COVERART".
1518 The first is the official standard and uses the same format as
1519 pictures in FLAC tags. "COVERART" is an earlier unofficial way to
1520 include pictures in Vorbis comments. It can be used for
1521 compatibility with legacy players.
1522 If the Mark if larger than (bytes) check box is activated, files
1524 containing embedded album cover art exceeding the given size in
1525 bytes are marked red. This can be used to find files containing
1526 oversized pictures which are not accepted by some applications and
1527 players. The default value is 131072 bytes (128 KB).
1528 Custom Genres can be used to define genres which are not available
1530 in the standard genre list, e.g. "Gothic Metal". Such custom
1531 genres will appear in the Genre combo box of Tag 2. For ID3v1.1
1532 tags, only the predefined genres can be used.
1533 The list of custom genres can also be used to reduce the number of
1535 genres available in the Genre combo box to those typically used. If
1536 your collection mostly contains music in the genres Metal, Gothic
1537 Metal, Ancient and Hard Rock, you can enter those genres and mark
1538 Show only custom genres. The Tag 2 Genre combo box will then only
1539 contain those four genres and you will not have to search through
1540 the complete genres list for them. In this example, only Metal and
1541 Hard Rock will be listed in the tag 1 genres list, because those
1542 two custom genres entries are standard genres. If Show only custom
1543 genres is not active, the custom genres can be found at the end of
1544 the genres list.
1545 Quick Access Frames defines which frame types are always shown in
1547 the Tag 2 section. Such frames can then be added without first
1548 using the Add button. The order of these quick access frames can be
1549 changed by dragging and dropping items.
1550 The combo box Track number field name is only relevant for RIFF
1552 INFO and sets the name of the field used for track numbers. Track
1553 numbers are not specified in the original RIFF standard, there are
1554 applications which use "ITRK", others use "IPRT".
1555 Tag Format contains options for the format of the tags. When
1557 Automatically apply format is checked, the format configuration is
1558 automatically used while editing text in the line edits.
1559 Validation enables validators in the controls with track/total and
1560 date/time values. The Case conversion can be set to No changes, All
1561 lowercase, All uppercase, First letter uppercase or All first
1562 letters uppercase. To use locale-aware conversion between lowercase
1563 and uppercase characters, a locale can be selected in the combobox
1564 below. The string replacement list can be set to arbitrary string
1565 mappings. To add a new mapping, select the From cell of a row and
1566 insert the text to replace, then go to the To column and enter the
1567 replacement text. When the text to replace starts and ends with a
1568 slash ("/"), a regular expression is used. For regular expressions
1569 containing capturing groups, occurrences of \1, \2, ... in To are
1570 replaced with the string captured by the corresponding capturing
1571 group. To remove a mapping set the From cell to an empty value
1572 (e.g. by first typing space and then backspace). Inserting and
1573 deleting rows is also possible using a context menu which appears
1574 when the right mouse button is clicked. Replacement is only active,
1575 if the String replacement check box is checked.
1576 The table in Rating contains the mapping of star ratings to the
1578 effective values stored in the tag. The frames with rating
1579 information are listed in the Rating row of the frame list. For
1580 these frames, the rating can be set by giving a number of stars out
1581 of five stars. Different tag formats and different applications use
1582 different values to map the star rating to the value stored in the
1583 tag. In order to display the correct number of stars, Kid3 will
1584 look up a map in this table. The key to look up the mapping is the
1585 frame name, for example "RATING" as used for Vorbis comments or
1586 "IRTD" for RIFF INFO. For ID3v2 tags, a combined key is used
1587 consisting of the frame ID "POPM" of the Popularimeter frame and
1588 its "Email" field, separated by a dot. Therefore, different keys
1589 for ID3v2 exist, e.g. "POPM.Windows Media Player 9 Series" for the
1590 mapping used by Windows Media Player and Explorer, and simply
1591 "POPM" for POPM frames with an empty "Email" field. As multiple
1592 entries for "POPM" can exist, their order is important. When Kid3
1593 adds a new Popularimeter frame, it will use the first "POPM" entry
1594 to determine the value to be written into the "Email" field. This
1595 value will then specify the mapping to be used for star ratings.
1596 The first entry is also used if no key was found, it is therefore
1597 the default entry.
1598 Besides the Name column containing the keys, the table has columns
1600 1 to 5 for the values to be stored when the corresponding number of
1601 stars is given. The other way round, the values determine the
1602 number of stars which are displayed for the value stored in the
1603 frame. For instance, the row in the table below contains the values
1604 1, 64, 128, 196, 255. The thresholds for the number of stars to be
1605 displayed lay between these values and are compatible with what the
1606 Windows® Explorer uses.
1607 Table 1. Entry in Rating Table
1609 ┌──────┬──────┬───────┬────────┬─────────┬─────────┐
1610 │Name │ 1 │ 2 │ 3 │ 4 │ 5 │
1611 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1612 │POPM │ 1 │ 64 │ 128 │ 196 │ 255 │
1613 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1614 │Range │ 1-31 │ 32-95 │ 96-159 │ 160-223 │ 224-255 │
1615 └──────┴──────┴───────┴────────┴─────────┴─────────┘
1616 On the page Files the check box Load last-opened files can be
1617 marked so that Kid3 will open and select the last selected file
1618 when it is started the next time. Preserve file timestamp can be
1619 checked to preserve the file modification time stamp. Filename for
1620 cover sets the name which is suggested when an embedded image is
1621 exported to a file. With Text encoding (Export, Playlist) the
1622 encoding used when writing files can be set. The default System can
1623 be changed for example if playlists have to be used on a different
1624 device.
1625 If Mark changes is active, changed fields are marked with a light
1627 gray label background.
1628 The section File List determines which files are displayed in the
1630 file list. A Filter can be used to restrict the items in this list
1631 to files with supported extensions. To explicitly specify which
1632 folders to display in the file list or exclude certain folders, the
1633 options Include folders and Exclude folders can be used. They can
1634 contain wildcard expressions, for instance */Music/* to include
1635 only the Music folder, or */iTunes/* to exclude the iTunes folder
1636 from the file list. If multiple such expressions have to be used,
1637 they can be separated by spaces or semicolons.
1638 The buttons Filename from tag and Tag from filename in section
1640 Format open dialogs to edit the formats which are available in the
1641 Format combo boxes (with arrows up and down), which can be found in
1642 the File section of the main window.
1643 Filename Format contains options for the format of the filenames.
1645 The same options as in Tag Format are available.
1646 The User Actions page contains a table with the commands which are
1648 available in the context menu of the file list. For critical
1649 operations such as deleting files, it is advisable to mark Confirm
1650 to pop up a confirmation dialog before executing the command.
1651 Output can be marked to see the output written by console commands
1652 (standard output and standard error). Name is the name displayed
1653 in the context menu. Command is the command line to be executed.
1654 Arguments can be passed using the following codes:
1655 · %F %{files} File paths (a list if multiple files selected)
1657 · %f %{file} File path to single file
1659 · %uF %{urls} URLs (a list if multiple files selected)
1661 · %uf %{url} URL to single file
1663 · %d %{directory} Folder
1665 · %s %{title} Title (Song)
1667 · %a %{artist} Artist
1669 · %l %{album} Album
1671 · %c %{comment} Comment
1673 · %y %{year} Year
1675 · %t %{track} Track (e.g. 01)
1677 · %t %{track.n} Track with field width n (e.g. 001 for
1679 %{track.3})
1680 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
1682 · %g %{genre} Genre
1684 · %b %{browser} Command to start the web browser
1686 · %q %{qmlpath} Base folder of provided QML files
1688 The special code @separator can be set as a command to insert a
1690 separator into the user actions context menu. Menu items can be put
1691 into a submenu by enclosing them with @beginmenu and @endmenu
1692 commands. The name of the submenu is determined by the Name column
1693 of the @beginmenu command.
1694 To execute QML scripts, @qml is used as a command name. The path to
1696 the QML script is passed as a parameter. The provided scripts can
1697 be found in the folder %{qmlpath}/script/ (on Linux® typically
1698 /usr/share/kid3/qml/script/, on Windows qml/script/ inside the
1699 installation folder, and on macOS® in the app folder
1700 kid3.app/Contents/Resources/qml/script/). Custom scripts can be
1701 stored in any folder. If the QML code uses GUI components, @qmlview
1702 shall be used instead of @qml. Additional parameters are passed to
1703 the QML script where they will be available via the getArguments()
1704 function. An overview of some functions and properties which are
1705 available in QML can be found in the appendix QML Interface.
1706 The command which will be inserted with %{browser} can be defined
1708 in the Web browser line edit above. Commands starting with
1709 %{browser} can be used to fetch information about the audio files
1710 from the web, for instance
1711 %{browser} http://lyricwiki.org/%u{artist}:%u{title}
1713 will query the lyrics for the current song in LyricWiki[12]. The
1715 "u" in %u{artist} and %u{title} is used to URL-encode the artist
1716 %{artist} and song %{title} information. It is easy to define your
1717 own queries in the same way, e.g. an image search with Google[13]:
1718 %{browser} http://images.google.com/images?q=%u{artist}%20%u{album}
1720 To add album cover art to tag 2, you can search for images with
1722 Google or Amazon using the commands described above. The picture
1723 can be added to the tag with drag and drop. You can also add an
1724 image with Add, then select the Picture frame and import an image
1725 file or paste from the clipboard. Picture frames are supported for
1726 ID3v2, MP4, FLAC, Ogg and ASF tags.
1727 To add and delete entries in the table, a context menu can be used.
1729 The Network page contains only a field to insert the proxy address
1731 and optionally the port, separated by a colon. The proxy will be
1732 used when importing from an Internet server when the check box is
1733 checked.
1734 In the Plugins page, available plugins can be enabled or disabled.
1736 The plugins are separated into two sections. The Metadata Plugins &
1737 Priority list contains plugins which support audio file formats.
1738 The order of the plugins is important because they are tried from
1739 top to bottom. Some formats are supported by multiple plugins, so
1740 files will be opened with the first plugin supporting them. The
1741 TaglibMetadata supports most formats, if it is at the top of the
1742 list, it will open most of the files. If you want to use a
1743 different plugin for a file format, make sure that it is listed
1744 before the TaglibMetadata plugin. Details about the metadata plugin
1745 and why you may want to use them instead of TagLib are listed
1746 below.
1747 · Id3libMetadata: Uses id3lib[14] for ID3v1.1 and ID3v2.3 tags in
1749 MP3, MP2, AAC files. Supports a few more frame types than
1750 TagLib.
1751 · OggFlacMetadata: Uses libogg[15], libvorbis, libvorbisfile[16]
1753 for Ogg files, and additionally libFLAC++ and libFLAC[17] for
1754 FLAC files. These are the official libraries for these formats.
1755 · TaglibMetadata: Uses TagLib[18] which supports a lot of audio
1757 file formats. It can be used for all audio files supported by
1758 Kid3.
1759 · Mp4v2Metadata: mp4v2[19] was originally used by Kid3 to support
1761 M4A files. Can be used in case of problems with the M4A support
1762 of TagLib.
1763 The Available Plugins section lists the remaining plugins. Their
1765 order is not important, but they can be enabled or disabled using
1766 the check boxes.
1767 · AmazonImport: Used for the Import from Amazon... function.
1769 · DiscogsImport: Used for the Import from Discogs... function.
1771 · FreedbImport: Used for the Import from gnudb.org... and Import
1773 from TrackType.org... functions.
1774 · MusicBrainzImport: Used for the Import from MusicBrainz
1776 Release... function.
1777 · AcoustidImport: Used for the Import from MusicBrainz
1779 Fingerprint... function, which depends on the Chromaprint[20]
1780 and libav[21] libraries.
1781 Plugins which are disabled will not be loaded. This can be used to
1783 optimize resource usage and startup time. The settings on this page
1784 take only effect after a restart of Kid3.
1785 The Help Menu
1787 Help → Kid3 Handbook
1788 Opens this handbook.
1789 Help → About Kid3
1791 Displays a short information about Kid3.
1792
1794 Commands
1795 kid3-cli offers a command-line-interface for Kid3. If a folder path is
1796 used, the folder is opened. If one or more file paths are given, the
1797 common folder is opened and the files are selected. Subsequent commands
1798 will then work on these files. Commands are specified using -c options.
1799 If multiple commands are passed, they are executed in the given order.
1800 If files are modified by the commands, they will be saved at the end.
1801 If no command options are passed, kid3-cli starts in interactive mode.
1802 Commands can be entered and will operate on the current selection. The
1803 following sections list all available commands.
1804 Help
1806 help [COMMAND-NAME]
1807 Displays help about the parameters of COMMAND-NAME or about all
1809 commands if no command name is given.
1810 Timeout
1812 timeout [default | off | TIME]
1813 Overwrite the default command timeout. The CLI commands abort after
1815 a command specific timeout is expired. This timeout is 10 seconds
1816 for ls and albumart, 60 seconds for autoimport and filter, and 3
1817 seconds for all other commands. If a huge number of files has to be
1818 processed, these timeouts may be too restrictive, thus the timeout
1819 for all commands can be set to TIME ms, switched off altogether or
1820 be left at the default values.
1821 Quit application
1823 exit [force]
1824 Exit application. If there are modified unsaved files, the force
1826 parameter is required.
1827 Change folder
1829 cd [FOLDER]
1830 If no FOLDER is given, change to the home folder. If a folder is
1832 given, change into the folder. If one or more file paths are given,
1833 change to their common folder and select the files.
1834 Print the filename of the current folder
1836 pwd
1837 Print the filename of the current working folder.
1839 Folder list
1841 ls
1842 List the contents of the current folder. This corresponds to the
1844 file list in the Kid3 GUI. Five characters before the file names
1845 show the state of the file.
1846 · > File is selected.
1848 · * File is modified.
1850 · 1 File has a tag 1, otherwise '-' is displayed.
1852 · 2 File has a tag 2, otherwise '-' is displayed.
1854 · 3 File has a tag 3, otherwise '-' is displayed.
1856 kid3-cli> ls
1858 1-- 01 Intro.mp3
1859 > 12- 02 We Only Got This One.mp3
1860 *1-- 03 Outro.mp3
1861 In this example, all files have a tag 1, the second file also has a
1863 tag 2 and it is selected. The third file is modified.
1864 Save the changed files
1866 save
1867 Select file
1869 select [all | none | first | previous | next | FILE...]
1870 To select all files, enter select all, to deselect all files, enter
1872 select none. To traverse the files in the current folder start with
1873 select first, then go forward using select next or backward using
1874 select previous. Specific files can be added to the current
1875 selection by giving their file names. Wildcards are possible, so
1876 select *.mp3 will select all MP3 files in the current folder.
1877 kid3-cli> select first
1879 kid3-cli> ls
1880 > 1-- 01 Intro.mp3
1881 12- 02 We Only Got This One.mp3
1882 *1-- 03 Outro.mp3
1883 kid3-cli> select next
1884 kid3-cli> ls
1885 1-- 01 Intro.mp3
1886 > 12- 02 We Only Got This One.mp3
1887 *1-- 03 Outro.mp3
1888 kid3-cli> select *.mp3
1889 kid3-cli> ls
1890 > 1-- 01 Intro.mp3
1891 > 12- 02 We Only Got This One.mp3
1892 >*1-- 03 Outro.mp3
1893 Select tag
1895 tag [TAG-NUMBERS]
1896 Many commands have an optional TAG-NUMBERS parameter, which
1898 specifies whether the command operates on tag 1, 2, or 3. If this
1899 parameter is omitted, the default tag numbers are used, which can
1900 be set by this command. At startup, it is set to 12 which means
1901 that information is read from tag 2 if available, else from tag 1;
1902 modifications are done on tag 2. The TAG-NUMBERS can be set to 1,
1903 2, or 3 to operate only on the corresponding tag. If the parameter
1904 is omitted, the current setting is displayed.
1905 Get tag frame
1907 get [all | FRAME-NAME] [TAG-NUMBERS]
1908 This command can be used to read the value of a specific tag frame
1910 or get information about all tag frames (if the argument is omitted
1911 or all is used). Modified frames are marked with a '*'.
1912 kid3-cli> get
1914 File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
1915 Name: 01 Intro.mp3
1916 Tag 1: ID3v1.1
1917 Title Intro
1918 Artist One Hit Wonder
1919 Album Let's Tag
1920 Date 2013
1921 Track Number 1
1922 Genre Pop
1923 kid3-cli> get title
1924 Intro
1925 To save the contents of a picture frame to a file, use
1927 get picture:'/path/to/folder.jpg'
1929 To save synchronized lyrics to an LRC file, use
1931 get SYLT:'/path/to/lyrics.lrc'
1933 It is possible to get only a specific field from a frame, for
1935 example get POPM.Email for the Email field of a Popularimeter
1936 frame. If a file has multiple frames of the same kind, the
1937 different frames can be indexed with brackets, for example the
1938 first performer from a Vorbis comment can be retrieved using get
1939 performer[0], the second using get performer[1].
1940 The pseudo field name "selected" can be used to check if a frame is
1942 selected, for example get artist.selected will return 1 if the
1943 artist frame is selected, else 0.
1944 Set tag frame
1946 set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]
1947 This command sets the value of a specific tag frame. If FRAME-VALUE
1949 is empty, the frame is deleted.
1950 kid3-cli> set remixer 'O.H. Wonder'
1952 To set the contents of a picture frame from a file, use
1954 set picture:'/path/to/folder.jpg' 'Picture Description'
1956 To set synchronized lyrics from an LRC file, use
1958 set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'
1960 To set a specific field of a frame, the field name can be given
1962 after a dot, e.g. to set the Counter field of a Popularimeter
1963 frame, use
1964 set POPM.Counter 5
1966 An application for field specifications is the case where you want
1968 a custom TXXX frame with "rating" description instead of a standard
1969 Popularimeter frame (this seems to be used by some plugins). You
1970 can create such a TXXX rating frame with kid3-cli, however, you
1971 have to first create a TXXX frame with description "rating" and
1972 then set the value of this frame to the rating value.
1973 kid3-cli> set rating ""
1975 kid3-cli> set TXXX.Description rating
1976 kid3-cli> set rating 5
1977 The first command will delete an existing POPM frame, because if
1979 such a frame exists, set rating 5 would set the POPM frame and not
1980 the TXXX frame. Another possibility would be to use set TXXX.Text
1981 5, but this would only work if there is no other TXXX frame
1982 present.
1983 To set multiple frames of the same kind, an index can be given in
1985 brackets, e.g. to set multiple performers in a Vorbis comment, use
1986 kid3-cli> set performer[0] 'Liza don Getti (soprano)'
1988 kid3-cli> set performer[1] 'Joe Barr (piano)'
1989 To select certain frames before a copy, paste or remove action, the
1991 pseudo field name "selected" can be used. Normally, all frames are
1992 selected, to deselect all, use set '*.selected' 0, then for example
1993 set artist.selected 1 to select the artist frame.
1994 Revert
1996 revert
1997 Revert all modifications in the selected files (or all files if no
1999 files are selected).
2000 Import from file
2002 import {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2003 Tags are imported from the file FILE in the format with the name
2005 FORMAT-NAME (e.g. "CSV unquoted", see Import).
2006 If tags is given for FILE, tags are imported from other tags.
2008 Instead of FORMAT-NAME parameters SOURCE and EXTRACTION are
2009 required, see Import from Tags. To apply the import from tags on
2010 the selected files, use tagsel instead of tags. This function also
2011 supports output of the extracted value by using an EXTRACTION with
2012 the value %{__return}(.+).
2013 Automatic import
2015 autoimport [PROFILE-NAME] [TAG-NUMBERS]
2016 Batch import using profile PROFILE-NAME (see Automatic Import,
2018 "All" is used if omitted).
2019 Download album cover artwork
2021 albumart {URL} [all]
2022 Set the album artwork by downloading a picture from URL. The rules
2024 defined in the Browse Cover Art dialog are used to transform
2025 general URLs (e.g. from Amazon) to a picture URL. To set the album
2026 cover from a local picture file, use the set command.
2027 kid3-cli> albumart
2029 http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
2030 Export to file
2032 export {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2033 Tags are exported to file FILE in the format with the name
2035 FORMAT-NAME (e.g. "CSV unquoted", see Export).
2036 Create playlist
2038 playlist
2039 Create playlist in the format set in the configuration, see Create
2041 Playlist.
2042 Apply filename format
2044 filenameformat
2045 Apply file name format set in the configuration, see Apply Filename
2047 Format.
2048 Apply tag format
2050 tagformat
2051 Apply tag name format set in the configuration, see Apply Tag
2053 Format.
2054 Apply text encoding
2056 textencoding
2057 Apply text encoding set in the configuration, see Apply Text
2059 Encoding.
2060 Rename folder
2062 renamedir [FORMAT] [create | rename | dryrun] [TAG-NUMBERS]
2063 Rename or create folders from the values in the tags according to a
2065 given FORMAT (e.g. %{artist} - %{album}, see Rename Folder), if no
2066 format is given, the format defined in the Rename folder dialog is
2067 used. The default mode is rename; to create folders, create must be
2068 given explicitly. The rename actions will be performed immediately,
2069 to just see what would be done, use the dryrun option.
2070 Number tracks
2072 numbertracks [TRACK-NUMBER] [TAG-NUMBERS]
2073 Number the selected tracks starting with TRACK-NUMBER (1 if
2075 omitted).
2076 Filter
2078 filter [FILTER-NAME | FILTER-FORMAT]
2079 Filter the files so that only the files matching the FILTER-FORMAT
2081 are visible. The name of a predefined filter expression (e.g.
2082 "Filename Tag Mismatch") can be used instead of a filter
2083 expression, see Filter.
2084 kid3-cli> filter '%{title} contains "tro"'
2086 Started
2087 /home/urs/One Hit Wonder - Let's Tag
2088 + 01 Intro.mp3
2089 - 02 We Only Got This One.mp3
2090 + 03 Outro.mp3
2091 Finished
2092 kid3-cli> ls
2093 1-- 01 Intro.mp3
2094 1-- 03 Outro.mp3
2095 kid3-cli> filter All
2096 Started
2097 /home/urs/One Hit Wonder - Let's Tag
2098 + 01 Intro.mp3
2099 + 02 We Only Got This One.mp3
2100 + 03 Outro.mp3
2101 Finished
2102 kid3-cli> ls
2103 1-- 01 Intro.mp3
2104 12- 02 We Only Got This One.mp3
2105 1-- 03 Outro.mp3
2106 Convert ID3v2.3 to ID3v2.4
2108 to24
2109 Convert ID3v2.4 to ID3v2.3
2111 to23
2112 Filename from tag
2114 fromtag [FORMAT] [TAG-NUMBERS]
2115 Set the file names of the selected files from values in the tags,
2117 for example fromtag '%{track} - %{title}' 1. If no format is
2118 specified, the format set in the GUI is used.
2119 Tag from filename
2121 totag [FORMAT] [TAG-NUMBERS]
2122 Set the tag frames from the file names, for example totag
2124 '%{albumartist} - %{album}/%{track} %{title}' 2. If no format is
2125 specified, the format set in the GUI is used. If the format of the
2126 filename does not match this pattern, a few other commonly used
2127 formats are tried.
2128 Tag to other tag
2130 syncto {TAG-NUMBER}
2131 Copy the tag frames from one tag to the other tag, e.g. to set the
2133 ID3v2 tag from the ID3v1 tag, use syncto 2.
2134 Copy
2136 copy [TAG-NUMBER]
2137 Copy the tag frames of the selected file to the internal copy
2139 buffer. They can then be set on another file using the paste
2140 command.
2141 To copy only a subset of the frames, use the "selected" pseudo
2143 field with the set command. For example, to copy only the disc
2144 number and copyright frames, use
2145 set '*.selected' 0
2147 set discnumber.selected 1
2148 set copyright.selected 1
2149 copy
2150 Paste
2153 paste [TAG-NUMBER]
2154 Set tag frames from the contents of the copy buffer in the selected
2156 files.
2157 Remove
2159 remove [TAG-NUMBER]
2160 Remove a tag.
2162 It is possible to remove only a subset of the frames by selecting
2164 them as described in the copy command.
2165 Examples
2167 Set title containing an apostrophe. Commands passed to kid3-cli with -c
2168 have to be in quotes if they do not only consist of a single word. If
2169 such a command itself has an argument containing spaces, that argument
2170 has to be quoted too. In UNIX® shells single or double quotes can be
2171 used, but on the Windows Command Prompt, it is important that the outer
2172 quoting is done using double quotes and inside these quotes, single
2173 quotes are used. If the text inside the single quotes contains a single
2174 quote, it has to be escaped using a backslash character, as shown in
2175 the following example:
2176 kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder
2178 Set album cover in all files of a folder using the batch import
2180 function:
2181 kid3-cli -c "autoimport 'Cover Art'" /path/to/folder
2183 Remove comment frames and apply the tag format in both tags of all MP3
2185 files of a folder:
2186 kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
2188 -c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3
2189 Automatically import tag 2, synchronize to tag 1, set file names from
2191 tag 2 and finally create a playlist:
2192 kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
2194 /path/to/folder/*.mp3
2195 For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
2197 the arranger frame:
2198 kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
2200 -c "set arranger ''" /path/to/folder
2201 This Python script uses kid3-cli to generate iTunes Sound Check
2203 iTunNORM frames from replay gain information.
2204 #!/usr/bin/env python3
2207 # Generate iTunes Sound Check from ReplayGain.
2208 import os, sys, subprocess
2209 def rg2sc(dirpath):
2211 for root, dirs, files in os.walk(dirpath):
2212 for name in files:
2213 if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
2214 fn = os.path.join(root, name)
2215 rg = subprocess.check_output([
2216 'kid3-cli', '-c', 'get "replaygain_track_gain"',
2217 fn]).strip()
2218 if rg.endswith(b' dB'):
2219 rg = rg[:-3]
2220 try:
2221 rg = float(rg)
2222 except ValueError:
2223 print('Value %s of %s in not a float' % (rg, fn))
2224 continue
2225 sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
2226 subprocess.call([
2227 'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
2228 if __name__ == '__main__':
2230 rg2sc(sys.argv[1])
2231 JSON Format
2234 In order to make it easier to parse results from kid3-cli, it is
2235 possible to get the output in JSON format. When the request is in JSON
2236 format, the response will also be JSON. A compact format of the request
2237 will also give a compact representation of the response. If the request
2238 contains an "id" field, it is assumed to be a JSON-RPC request and the
2239 response will contain a "jsonrpc" field and the "id" of the request.
2240 The request format uses the same commands as the standard CLI, the
2241 "method" field contains the command and the parameters (if any) are
2242 given in the "params" list. The response contains a "result" object,
2243 which can also be null if the corresponding kid3-cli command does not
2244 return a result. In case of an error, an "error" object is returned
2245 with "code" and "message" fields as used in JSON-RPC.
2246 kid3-cli> {"method":"set","params":["artist","An Artist"]}
2248 {"result":null}
2249 kid3-cli> {"method":"get","params":["artist",2]}
2250 {"result":"An Artist"}
2251 kid3-cli> {"method": "get", "params": ["artist"]}
2252 {
2253 "result": "An Artist"
2254 }
2255 kid3-cli> {"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}
2257 {"id":"123","jsonrpc":"2.0","result":"An Artist"}
2258
2261 Kid3
2262 Program written by Urs Fleisch <ufleisch at users.sourceforge.net>
2264 FDL[22]
2266 GPL[23]
2268
2270 How to obtain Kid3
2271 Kid3 can be found at https://kid3.kde.org.
2272 Requirements
2274 Kid3 needs Qt(TM)[24]. KDE[25] is recommended but not necessary, as
2275 Kid3 can also be compiled as a Qt(TM) application. Kid3 can be
2276 compiled for systems where these libraries are available, e.g. for
2277 GNU/Linux®, Windows® and macOS®. To tag Ogg/Vorbis files, libogg[15],
2278 libvorbis and libvorbisfile[16] are required, for FLAC files libFLAC++
2279 and libFLAC[17]. id3lib[14] is used for MP3 files. These four formats
2280 are also supported by TagLib[18], which can also handle Opus, MPC, APE,
2281 MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker
2282 modules. To import from acoustic fingerprints, Chromaprint[20] and
2283 libav[21] are used.
2284 Kid3 is available for most Linux® distributions, Windows® and macOS®.
2286 Links can be found on https://kid3.kde.org.
2287 Compilation and Installation
2289 You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple
2290 Qt(TM) application and lacks some configuration and session features.
2291 For a KDE version, go into the top folder and type
2293 % cmake .
2295 % make
2296 % make install
2297 To compile for different versions of Qt(TM) or KDE, set the
2299 corresponding cmake options.
2300 If not all libraries are present, Kid3 is built with reduced
2302 functionality. So you should take care to have all desired development
2303 packages installed. On the other side, cmake-options control which
2304 libraries are compiled in. The default is -DWITH_TAGLIB:BOOL=ON
2305 -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON
2306 -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON . These options can be
2307 disabled using OFF.
2308 To build Kid3 as a Qt(TM) application without KDE, use the cmake option
2310 -DWITH_APPS=Qt. To build both a KDE and a Qt(TM) application, set
2311 -DWITH_APPS="Qt;KDE".
2312 To use a specific Qt(TM) installation, set
2314 -DQT_QMAKE_EXECUTABLE=/path/to/qmake.
2315 Generation of RPM-Packages is supported by the file kid3.spec, for
2317 Debian® Packages, the script build-deb.sh is available.
2318 The Qt(TM) application can also be compiled for Windows® and macOS®.
2320 The script buildlibs.sh can be used to download and build all required
2321 libraries and create a Kid3 package.
2322 Configuration
2324 With KDE, the settings are stored in .config/kid3rc. As a Qt(TM)
2325 application, this file is in .config/Kid3/Kid3.conf. On Windows®, the
2326 configuration is stored in the registry. on macOS® in a plist file.
2327 The environment variable KID3_CONFIG_FILE can be used to set the path
2329 of the configuration file.
2330
2332 D-Bus Examples
2333 On Linux® a D-Bus-interface can be used to control Kid3 by scripts.
2334 Scripts can be written in any language with D-Bus-bindings (e.g. in
2335 Python) and can be added to the User Actions to extend the
2336 functionality of Kid3.
2337 The artist in tag 2 of the current file can be set to the value "One
2339 Hit Wonder" with the following code:
2340 Shell
2342 dbus-send --dest=org.kde.kid3 --print-reply=literal \
2344 /Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
2345 string:'One Hit Wonder'
2346 or easier with Qt(TM)'s qdbus (qdbusviewer can be used to explore
2348 the interface in a GUI):
2349 qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
2351 'One Hit Wonder'
2352 Python
2354 import dbus
2356 kid3 = dbus.SessionBus().get_object(
2357 'org.kde.kid3', '/Kid3')
2358 kid3.setFrame(2, 'Artist', 'One Hit Wonder')
2359 Perl
2361 use Net::DBus;
2363 $kid3 = Net::DBus->session->get_service(
2364 "org.kde.kid3")->get_object(
2365 "/Kid3", "org.kde.Kid3");
2366 $kid3->setFrame(2, "Artist", "One Hit Wonder");
2367 D-Bus API
2369 The D-Bus API is specified in org.kde.Kid3.xml. The Kid3 interface has
2370 the following methods:
2371 Open file or folder
2373 boolean openDirectory(string path);
2374 path
2376 path to file or folder
2377 Returns true if OK.
2379 Unload the tags of all files which are not modified or selected
2381 unloadAllTags(void);
2382 Save all modified files
2384 boolean save(void);
2385 Returns true if OK.
2387 Get a detailed error message provided by some methods
2389 string getErrorMessage(void);
2390 Returns detailed error message.
2392 Revert changes in the selected files
2394 revert(void);
2395 Start an automatic batch import
2397 boolean batchImport(int32 tagMask, string profileName);
2398 tagMask
2400 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2401 profileName
2403 name of batch import profile to use
2404 Import tags from a file
2406 boolean importFromFile(int32 tagMask, string path, int32 fmtIdx);
2407 tagMask
2409 tag bit (1 for tag 1, 2 for tag 2)
2410 path
2412 path of file
2413 fmtIdx
2415 index of format
2416 Returns true if OK.
2418 Import tags from other tags
2420 importFromTags(int32 tagMask, string source, string extraction);
2421 tagMask
2423 tag bit (1 for tag 1, 2 for tag 2)
2424 source
2426 format to get source text from tags
2427 extraction
2429 regular expression with frame names and captures to extract
2430 from source text
2431 Import tags from other tags on selected files
2433 array importFromTagsToSelection(int32 tagMask, string source,
2434 string extraction);
2435 tagMask
2437 tag bit (1 for tag 1, 2 for tag 2)
2438 source
2440 format to get source text from tags
2441 extraction
2443 regular expression with frame names and captures to extract
2444 from source text
2445 returnValues
2447 extracted value for "%{__return}(.+)"
2448 Download album cover art
2450 downloadAlbumArt(string url, boolean allFilesInDir);
2451 url
2453 URL of picture file or album art resource
2454 allFilesInDir
2456 true to add the image to all files in the folder
2457 Export tags to a file
2459 boolean exportToFile(int32 tagMask, string path, int32 fmtIdx);
2460 tagMask
2462 tag bit (1 for tag 1, 2 for tag 2)
2463 path
2465 path of file
2466 fmtIdx
2468 index of format
2469 Returns true if OK.
2471 Create a playlist
2473 boolean createPlaylist(void);
2474 Returns true if OK.
2476 Get items of a playlist
2478 array getPlaylistItems(string path);
2479 path
2481 path to playlist file
2482 Returns list of absolute paths to playlist items.
2484 Set items of a playlist
2486 boolean setPlaylistItems(string path, array items);
2487 path
2489 path to playlist file
2490 items
2492 list of absolute paths to playlist items
2493 Returns true if OK, false if not all items were found and added or
2495 saving failed.
2496 Quit the application
2498 quit(void);
2499 Select all files
2501 selectAll(void);
2502 Deselect all files
2504 deselectAll(void);
2505 Set the first file as the current file
2507 boolean firstFile(void);
2508 Returns true if there is a first file.
2510 Set the previous file as the current file
2512 boolean previousFile(void);
2513 Returns true if there is a previous file.
2515 Set the next file as the current file
2517 boolean nextFile(void);
2518 Returns true if there is a next file.
2520 Select the first file
2522 boolean selectFirstFile(void);
2523 Returns true if there is a first file.
2525 Select the previous file
2527 boolean selectPreviousFile(void);
2528 Returns true if there is a previous file.
2530 Select the next file
2532 boolean selectNextFile(void);
2533 Returns true if there is a next file.
2535 Select the current file
2537 boolean selectCurrentFile(void);
2538 Returns true if there is a current file.
2540 Expand or collapse the current file item if it is a folder
2542 boolean expandDirectory(void);
2543 A file list item is a folder if getFileName() returns a name with
2545 '/' as the last character.
2546 Returns true if current file item is a folder.
2548 Apply the file name format
2550 applyFilenameFormat(void);
2551 Apply the tag format
2553 applyTagFormat(void);
2554 Apply text encoding
2556 applyTextEncoding(void);
2557 Set the folder name from the tags
2559 boolean setDirNameFromTag(int32 tagMask, string format,
2560 boolean create);
2561 tagMask
2563 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2564 format
2566 folder name format
2567 create
2569 true to create, false to rename
2570 Returns true if OK, else the error message is available using
2572 getErrorMessage().
2573 Set subsequent track numbers in the selected files
2575 numberTracks(int32 tagMask, int32 firstTrackNr);
2576 tagMask
2578 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2579 firstTrackNr
2581 number to use for first file
2582 Filter the files
2584 filter(string expression);
2585 expression
2587 filter expression
2588 Convert ID3v2.3 tags to ID3v2.4
2590 convertToId3v24(void);
2591 Convert ID3v2.4 tags to ID3v2.3
2593 convertToId3v23(void);
2594 Returns true if OK.
2596 Get path of folder
2598 string getDirectoryName(void);
2599 Returns absolute path of folder.
2601 Get name of current file
2603 string getFileName(void);
2604 Returns true absolute file name, ends with "/" if it is a folder.
2606 Set name of selected file
2608 setFileName(string name);
2609 name
2611 file name
2612 The file will be renamed when the folder is saved.
2614 Set format to use when setting the filename from the tags
2616 setFileNameFormat(string format);
2617 format
2619 file name format
2620 Set the file names of the selected files from the tags
2622 setFileNameFromTag(int32 tagMask);
2623 tagMask
2625 tag bit (1 for tag 1, 2 for tag 2)
2626 Get value of frame
2628 string getFrame(int32 tagMask, string name);
2629 tagMask
2631 tag bit (1 for tag 1, 2 for tag 2)
2632 name
2634 name of frame (e.g. "artist")
2635 To get binary data like a picture, the name of a file to write can
2637 be added after the name, e.g. "Picture:/path/to/file". In the same
2638 way, synchronized lyrics can be exported, e.g.
2639 "SYLT:/path/to/file".
2640 Returns value of frame.
2642 Set value of frame
2644 boolean setFrame(int32 tagMask, string name, string value);
2645 tagMask
2647 tag bit (1 for tag 1, 2 for tag 2)
2648 name
2650 name of frame (e.g. "artist")
2651 value
2653 value of frame
2654 For tag 2 (tagMask 2), if no frame with name exists, a new frame is
2656 added, if value is empty, the frame is deleted. To add binary data
2657 like a picture, a file can be added after the name, e.g.
2658 "Picture:/path/to/file". "SYLT:/path/to/file" can be used to import
2659 synchronized lyrics.
2660 Returns true if OK.
2662 Get all frames of a tag
2664 array of string getTag(int32 tagMask);
2665 tagMask
2667 tag bit (1 for tag 1, 2 for tag 2)
2668 Returns list with alternating frame names and values.
2670 Get technical information about file
2672 array of string getInformation(void);
2673 Properties are Format, Bitrate, Samplerate, Channels, Duration,
2675 Channel Mode, VBR, Tag 1, Tag 2. Properties which are not available
2676 are omitted.
2677 Returns list with alternating property names and values.
2679 Set tag from file name
2681 setTagFromFileName(int32 tagMask);
2682 tagMask
2684 tag bit (1 for tag 1, 2 for tag 2)
2685 Set tag from other tag
2687 setTagFromOtherTag(int32 tagMask);
2688 tagMask
2690 tag bit (1 for tag 1, 2 for tag 2)
2691 Copy tag
2693 copyTag(int32 tagMask);
2694 tagMask
2696 tag bit (1 for tag 1, 2 for tag 2)
2697 Paste tag
2699 pasteTag(int32 tagMask);
2700 tagMask
2702 tag bit (1 for tag 1, 2 for tag 2)
2703 Remove tag
2705 removeTag(int32 tagMask);
2706 tagMask
2708 tag bit (1 for tag 1, 2 for tag 2)
2709 Reparse the configuration
2711 reparseConfiguration(void);
2712 Automated configuration changes are possible by modifying the
2714 configuration file and then reparsing the configuration.
2715 Plays the selected files
2717 playAudio(void);
2718
2720 QML Examples
2721 QML scripts can be invoked via the context menu of the file list and
2722 can be set in the tab User Actions of the settings dialog. The scripts
2723 which are set there can be used as examples to program custom scripts.
2724 QML uses JavaScript, here is the obligatory "Hello World":
2725 import Kid3 1.0
2727 Kid3Script {
2729 onRun: {
2730 console.log("Hello world, folder is", app.dirName)
2731 Qt.quit()
2732 }
2733 }
2734 If this script is saved as /path/to/Example.qml, the user command can
2736 be defined as @qml /path/to/Example.qml with name QML Test and Output
2737 checked. It can then be started using the QML Test item in the file
2738 list context menu, and the output will be visible in the window.
2739 Alternatively, the script could also be started independent of Kid3
2741 using the QML tools.
2742 qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2744 or
2746 qmlscene -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2748 On Windows® and macOS®, the import path must be adapted to the imports
2750 folder inside the installation folder. Scripts started outside of Kid3
2751 will use the current folder, so it should be changed beforehand.
2752 To list the titles in the tags 2 of all files in the current folder,
2754 the following script could be used:
2755 import Kid3 1.0
2757 Kid3Script {
2759 onRun: {
2760 app.firstFile()
2761 do {
2762 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2763 console.log(app.getFrame(tagv2, "title"))
2764 }
2765 } while (app.nextFile())
2766 }
2767 }
2768 If the folder contains many files, such a script might block the user
2770 interface for some time. For longer operations, it should therefore
2771 have a break from time to time. The alternative implementation below
2772 has the work for a single file moved out into a function. This function
2773 invokes itself with a timeout of 1 ms at the end, given that more files
2774 have to be processed. This will ensure that the GUI remains responsive
2775 while the script is running.
2776 import Kid3 1.0
2778 Kid3Script {
2780 onRun: {
2781 function doWork() {
2782 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2783 console.log(app.getFrame(tagv2, "title"))
2784 }
2785 if (!app.nextFile()) {
2786 Qt.quit()
2787 } else {
2788 setTimeout(doWork, 1)
2789 }
2790 }
2791 app.firstFile()
2793 doWork()
2794 }
2795 }
2796 When using app.firstFile() with app.nextFile(), all files of the
2798 current folder will be processed. If only the selected files shall be
2799 affected, use firstFile() and nextFile() instead, these are convenience
2800 functions of the Kid3Script component. The following example is a
2801 script which copies only the disc number and copyright frames of the
2802 selected file.
2803 import Kid3 1.1
2805 Kid3Script {
2807 onRun: {
2808 function doWork() {
2809 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2810 app.setFrame(tagv2, "*.selected", false)
2811 app.setFrame(tagv2, "discnumber.selected", true)
2812 app.setFrame(tagv2, "copyright.selected", true)
2813 app.copyTags(tagv2)
2814 }
2815 if (!nextFile()) {
2816 Qt.quit()
2817 } else {
2818 setTimeout(doWork, 1)
2819 }
2820 }
2821 firstFile()
2823 doWork()
2824 }
2825 }
2826 More example scripts come with Kid3 and are already registered as user
2828 commands.
2829 · ReplayGain to SoundCheck (ReplayGain2SoundCheck.qml): Create
2831 iTunNORM SoundCheck information from replay gain frames.
2832 · Resize Album Art (ResizeAlbumArt.qml): Resize embedded cover art
2834 images which are larger than 500x500 pixels.
2835 · Extract Album Art (ExtractAlbumArt.qml): Extract all embedded cover
2837 art pictures avoiding duplicates.
2838 · Embed Album Art (EmbedAlbumArt.qml): Embed cover art found in image
2840 files into audio files in the same folder.
2841 · Embed Lyrics (EmbedLyrics.qml): Fetch unsynchronized lyrics from
2843 web service.
2844 · Text Encoding ID3v1 (ShowTextEncodingV1.qml): Helps to find the
2846 encoding of ID3v1 tags by showing the tags of the current file in
2847 all available character encodings.
2848 · ID3v1 to ASCII (Tag1ToAscii.qml): Transliterate extended latin
2850 characters in the ID3v1 tag to ASCII.
2851 · English Title Case (TitleCase.qml): Formats text in the tags to
2853 English title case.
2854 · Export CSV (ExportCsv.qml): Export recursively all tags of all
2856 files to a CSV file.
2857 · Export Playlist Folder (ExportPlaylist.qml): Copy all files from a
2859 playlist into a folder and rename them according to their position.
2860 · QML Console (QmlConsole.qml): Simple console to play with Kid3's
2862 QML API.
2863 QML API
2866 The API can be easily explored using the QML Console, which is
2867 available as an example script with a user interface.
2868 Kid3Script
2870 Kid3Script is a regular QML component located inside the plugin
2871 folder. You could use another QML component just as well. Using
2872 Kid3Script makes it easy to start the script function using the
2873 onRun signal handler. Moreover it offers some functions:
2874 onRun: Signal handler which is invoked when the script is started
2876 tagv1, tagv2, tagv2v1: Constants for tag parameters
2877 script: Access to scripting functions
2878 configs: Access to configuration objects
2879 getArguments(): List of script arguments
2880 isStandalone(): true if the script was not started from within Kid3
2881 setTimeout(callback, delay): Starts callback after delay ms
2882 firstFile(): To first selected file
2883 nextFile(): To next selected file
2884 Scripting Functions
2887 As JavaScript and therefore QML too has only a limited set of
2888 functions for scripting, the script object has some additional
2889 methods, for instance:
2890 script.properties(obj): String with Qt properties
2892 script.writeFile(filePath, data): Write data to file, true if OK
2893 script.readFile(filePath): Read data from file
2894 script.removeFile(filePath): Delete file, true if OK
2895 script.fileExists(filePath): true if file exists
2896 script.fileIsWritable(filePath): true if file is writable
2897 script.getFilePermissions(filePath): Get file permission mode bits
2898 script.setFilePermissions(filePath, modeBits): Set file permission mode bits
2899 script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
2900 file " ")
2901 script.renameFile(oldName, newName): Rename file, true if OK
2902 script.copyFile(source, dest): Copy file, true if OK
2903 script.makeDir(path): Create folder, true if OK
2904 script.removeDir(path): Remove folder, true if OK
2905 script.tempPath(): Path to temporary folder
2906 script.musicPath(): Path to music folder
2907 script.listDir(path, [nameFilters], [classify]): List folder entries
2908 script.system(program, [args], [msecs]): Synchronously start a system command,
2909 [exit code, standard output, standard error] if not timeout
2910 script.systemAsync(program, [args], [callback]): Asynchronously start a system
2911 command, callback will be called with [exit code, standard output, standard
2912 error]
2913 script.getEnv(varName): Get value of environment variable
2914 script.setEnv(varName, value): Set value of environment variable
2915 script.getQtVersion(): Qt version string, e.g. "5.4.1"
2916 script.getDataMd5(data): Get hex string of the MD5 hash of data
2917 script.getDataSize(data): Get size of byte array
2918 script.dataToImage(data, [format]): Create an image from data bytes
2919 script.dataFromImage(img, [format]): Get data bytes from image
2920 script.loadImage(filePath): Load an image from a file
2921 script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
2922 script.imageProperties(img): Get properties of an image, map containing
2923 "width", "height", "depth" and "colorCount", empty if invalid image
2924 script.scaleImage(img, width, [height]): Scale an image, returns scaled image
2925 Application Context
2927 Using QML, a large part of the Kid3 functions are accessible. The
2928 API is similar to the one used for D-Bus. For details, refer to the
2929 respective notes.
2930 app.openDirectory(path): Open folder
2932 app.unloadAllTags(): Unload all tags
2933 app.saveDirectory(): Save folder
2934 app.revertFileModifications(): Revert
2935 app.importTags(tag, path, fmtIdx): Import file
2936 app.importFromTags(tag, source, extraction): Import from tags
2937 app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
2938 app.downloadImage(url, allFilesInDir): Download image
2939 app.exportTags(tag, path, fmtIdx): Export file
2940 app.writePlaylist(): Write playlist
2941 app.getPlaylistItems(path): Get items of a playlist
2942 app.setPlaylistItems(path, items): Set items of a playlist
2943 app.selectAllFiles(): Select all
2944 app.deselectAllFiles(): Deselect
2945 app.firstFile([select], [onlyTaggedFiles]): To first file
2946 app.nextFile([select], [onlyTaggedFiles]): To next file
2947 app.previousFile([select], [onlyTaggedFiles]): To previous file
2948 app.selectCurrentFile([select]): Select current file
2949 app.selectFile(path, [select]): Select a specific file
2950 app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
2951 app.requestExpandFileList(): Expand all
2952 app.applyFilenameFormat(): Apply filename format
2953 app.applyTagFormat(): Apply tag format
2954 app.applyTextEncoding(): Apply text encoding
2955 app.numberTracks(nr, total, tag, [options]): Number tracks
2956 app.applyFilter(expr): Filter
2957 app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
2958 app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
2959 app.getFilenameFromTags(tag): Filename from tags
2960 app.getTagsFromFilename(tag): Filename to tags
2961 app.getAllFrames(tag): Get object with all frames
2962 app.getFrame(tag, name): Get frame
2963 app.setFrame(tag, name, value): Set frame
2964 app.getPictureData(): Get data from picture frame
2965 app.setPictureData(data): Set data in picture frame
2966 app.copyToOtherTag(tag): Tags to other tags
2967 app.copyTags(tag): Copy
2968 app.pasteTags(tag): Paste
2969 app.removeTags(tag): Remove
2970 app.playAudio(): Play
2971 app.readConfig(): Read configuration
2972 app.applyChangedConfiguration(): Apply configuration
2973 app.dirName: Folder name
2974 app.selectionInfo.fileName: File name
2975 app.selectionInfo.filePath: Absolute file path
2976 app.selectionInfo.detailInfo: Format details
2977 app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
2978 app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
2979 app.selectionInfo.formatString(tag, format): Substitute codes in format string
2980 app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
2981 select a file
2982 app.selectDirName(caption, dir): Open file dialog to select a folder
2983 For asynchronous operations, callbacks can be connected to signals.
2985 function automaticImport(profile) {
2987 function onAutomaticImportFinished() {
2988 app.batchImporter.finished.disconnect(onAutomaticImportFinished)
2989 }
2990 app.batchImporter.finished.connect(onAutomaticImportFinished)
2991 app.batchImport(profile, tagv2)
2992 }
2993 function renameDirectory(format) {
2995 function onRenameActionsScheduled() {
2996 app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
2997 app.performRenameActions()
2998 }
2999 app.renameActionsScheduled.connect(onRenameActionsScheduled)
3000 app.renameDirectory(tagv2v1, format, false)
3001 }
3002 Configuration Objects
3004 The different configuration sections are accessible via methods of
3005 configs. Their properties can be listed in the QML console.
3006 script.properties(configs.networkConfig())
3008 Properties can be set:
3010 configs.networkConfig().useProxy = false
3012 configs.batchImportConfig()
3016 configs.exportConfig()
3017 configs.fileConfig()
3018 configs.filenameFormatConfig()
3019 configs.filterConfig()
3020 configs.findReplaceConfig()
3021 configs.guiConfig()
3022 configs.importConfig()
3023 configs.mainWindowConfig()
3024 configs.networkConfig()
3025 configs.numberTracksConfig()
3026 configs.playlistConfig()
3027 configs.renDirConfig()
3028 configs.tagConfig()
3029 configs.tagFormatConfig()
3030 configs.userActionsConfig()
3031
3033 Urs Fleisch <ufleisch at users.sourceforge.net>
3034 Software development
3035
3037 Copyright © 2020 Urs Fleisch
3038 FDL
3040
3043 1. gnudb.org
3044 http://gnudb.org
3045 2. TrackType.org
3047 http://tracktype.org
3048 3. MusicBrainz
3050 http://musicbrainz.org
3051 4. Discogs
3053 http://discogs.com
3054 5. Amazon
3056 http://www.amazon.com
3057 6. ID3 specification
3059 http://id3.org/id3v2.4.0-frames
3060 7. SYLT Editor
3062 http://www.compuphase.com/software_sylteditor.htm
3063 8. www.gnudb.org
3065 http://www.gnudb.org
3066 9. freedb.org
3068 http://freedb.org
3069 10. ID3 tag version 2.3.0
3071 http://id3.org/id3v2.3.0
3072 11. ID3 tag version 2.4.0 - Main Structure
3074 http://id3.org/id3v2.4.0-structure
3075 12. LyricWiki
3077 http://www.lyricwiki.org
3078 13. Google
3080 http://www.google.com
3081 14. id3lib
3083 http://id3lib.sourceforge.net
3084 15. libogg
3086 http://xiph.org/ogg/
3087 16. libvorbis, libvorbisfile
3089 http://xiph.org/vorbis/
3090 17. libFLAC++ and libFLAC
3092 http://flac.sourceforge.net
3093 18. TagLib
3095 http://taglib.github.io/
3096 19. mp4v2
3098 http://code.google.com/p/mp4v2
3099 20. Chromaprint
3101 http://acoustid.org/chromaprint
3102 21. libav
3104 http://libav.org/
3105 22. FDL
3107 http://www.gnu.org/licenses/licenses.html#FDL
3108 23. GPL
3110 http://www.gnu.org/licenses/licenses.html#GPL
3111 24. Qt(TM)
3113 https://www.qt.io
3114 25. KDE
3116 http://www.kde.org
31173.8.4 2020-09-26 KID3(1)