1KID3(1) The Kid3 Handbook KID3(1)
2
6 kid3, kid3-qt, kid3-cli - Kid3 ID3 Tagger
7
9 kid3 [--help | --author | --version | --license | --desktopfile FILE]
10 [FILE...]
11 kid3-qt [--portable] [Qt-options] [FILE...]
13 kid3-cli [--portable] [--dbus] [-h | --help] [-c COMMAND1]
15 [-c COMMAND2...] [FILE...]
16
18 --portable
19 Store configuration in file kid3.ini inside application folder.
20 FILE
22 If FILE is the path to a folder, it will be opened. If one or more
23 file paths are given, their common folder is opened and the files
24 are selected.
25 kid3
27 --help
28 Show help about options.
29 --author
31 Show author information.
32 --version
34 Show version information.
35 --license
37 Show license information.
38 --desktopfile FILE
40 The base file name of the desktop entry for this application.
41 kid3-qt
43 Qt-options
44 See qt5options(7).
45 kid3-cli
47 --dbus
48 Activate the D-Bus interface.
49 -c
51 Execute a command. Multiple -c options are possible, they are
52 executed in sequence. See the section about kid3-cli for a
53 description of the available commands.
54 -h|--help
56 Show help about options and commands.
57
59 Kid3 is an application to edit the ID3v1 and ID3v2 tags in MP3 files in
60 an efficient way. These tags can be edited by most MP3 players, but not
61 in a very comfortable and efficient way. Moreover the tags in
62 Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio,
63 WavPack, WMA, WAV, AIFF files and tracker modules (MOD, S3M, IT, XM)
64 are supported too.
65 Kid3 does not grab nor encode MP3 files, but it is targeted to edit the
67 ID3 tags of all files of an album in an efficient way, i.e. with as
68 few mouse clicks and key strokes as possible. Where most other programs
69 can edit either ID3v1 or ID3v2 tags, Kid3 has full control over both
70 versions, can convert tags between the two formats and has access to
71 all ID3v2 tags. Tags of multiple files can be set to the same value,
72 e.g. the artist, album, year and genre of all files of an album
73 typically have the same values and can be set together. If the
74 information for the tags is contained in the file name, the tags can be
75 automatically set from the file name. It is also possible to set the
76 file name according to the tags found in the file in arbitrary formats.
77 The editing task is further supported by automatic replacement of
79 characters or substrings, for instance to remove illegal characters
80 from filenames. Automatic control of upper and lower case characters
81 makes it easy to use a consistent naming scheme in all tags.
82 The tag information for full albums can be taken from gnudb.org[1],
84 MusicBrainz[2], Discogs[3], Amazon[4] or other sources of track lists.
85 The import format is freely configurable by regular expressions.
86 Please report any problems or feature requests to the author.
88
90 Kid3 features
91 • Edit ID3v1.1 tags
92 • Edit all ID3v2.3 and ID3v2.4 frames
94 • Edit tags of multiple files
96 • Convert between ID3v1 and ID3v2 tags
98 • Edit MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2,
100 Speex, TrueAudio, WavPack, WMA, WAV and AIFF tags
101 • Generate tags from filename
103 • Generate tags from the contents of tag fields
105 • Generate filename from tags
107 • Generate and change folder names from tags
109 • Generate playlist file
111 • Automatic case conversion and string translation
113 • Import from gnudb.org[1], MusicBrainz[2], Discogs[3], Amazon[4] and
115 other data sources
116 • Export as CSV, HTML, playlist, Kover XML and other formats.
118 Exported CSV files can be imported again.
119 Example Usage
121 This section describes a typical session with Kid3. Let's assume we
122 have a folder containing MP3 files with the tracks from the album
123 "Let's Tag" from the band "One Hit Wonder". The folder is named in the
124 "artist - album" format, in our case One Hit Wonder - Let's Tag. The
125 folder contains the tracks in the "track title.mp3" format, which I
126 think is useful because the filenames are short (important when using
127 mobile MP3 players with small displays) and in the correct order when
128 sorted alphabetically (important when using hardware MP3 players which
129 play the tracks in alphabetical order or in the order in which they are
130 burnt on CD and that order is alphabetical when using mkisofs). Besides
131 this, the artist and album information is already in the folder name
132 and does not have to be repeated in the filename. But back to our
133 example, the folder listing looks like this:
134 01 Intro.mp3
136 02 We Only Got This One.mp3
138 03 Outro.mp3
140 These files have no tags yet and we want to generate them using Kid3.
142 We use File → Open menu item (or toolbar button) and select one of the
143 files in this folder. All files will be displayed in the file listbox.
144 Lazy as we are, we want to use the information in the folder and file
145 names to generate tags. Therefore we select all files, then click the
146 To: Tag 1 button in the File section. This will set the title, artist,
147 album and track values in all files. To set the year and genre values
148 of all files, we keep all files selected and type in "2002" for the
149 Date and select "Pop" from the Genre combobox. To set only these two
150 values, their check boxes are automatically checked and all other check
151 boxes are left unchecked. Now we change the selection by only selecting
152 the first file and we see that all tags contain the correct values. The
153 tags of the other files can be verified too by selecting them one by
154 one. When we are satisfied with the tags, we use File → Save menu item
155 (or toolbar button). Selecting File → Create Playlist menu item (or
156 toolbar button) will generate a file One Hit Wonder - Let's Tag.m3u in
157 the folder.
158
160 The GUI Elements
161 The Kid3 GUI is separated in six sections: At the left are the file and
162 folder listboxes, the right side contains the File, Tag 1, Tag 2 and
163 Tag 3 sections.
164 To navigate between the different sections using the keyboard, several
166 keyboard shortcuts are supported. In the tag sections, the shortcuts
167 are active while not editing text or when being in the first column.
168 • Alt+Left: Go to previous section (Command+[ on macOS®)
170 • Alt+Right: Go to next section (Command+] on macOS®)
172 • Ctrl+Shift+V: From other tag
174 • Ctrl+C: Copy
176 • Ctrl+V: Paste
178 • Shift+Delete: Remove
180 • F2: Edit
182 • Insert: Add
184 • Delete: Delete
186 File List
188 The file list contains the names of all the files in the opened
189 folder which match the selected file name filter (typically *.mp3
190 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2
191 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). A single or multiple
192 files can be selected. To select no file, click into the empty area
193 after the listbox entries. The selection determines the files which
194 are affected by the operations which are available by using the
195 buttons described below.
196 Besides Name, also other columns Size, Type, Date Modified with
198 file details can be displayed. Columns can be hidden by unchecking
199 their name in the context menu of the list header. The order of the
200 columns can be changed by drag and drop. The sort order can be
201 toggled by clicking on the column header.
202 At the left of the names an icon can be displayed: a disc to show
204 that the file has been modified or information about which tags are
205 present (V1, V2, V1V2 or NO TAG, no icon is displayed if the file
206 has not been read in yet).
207 Folders are displayed with a folder icon. If a folder is opened,
209 its files are displayed in a hierarchical tree. By selecting files
210 from subfolders, operations can be executed on files in different
211 folders, which is useful if the music collection is organized with
212 a folder for each artist containing folders for albums of this
213 artist.
214 Clicking the right mouse button inside the file list opens a
216 context menu with the following commands:
217 • Expand all: Expands all folder trees (only the current tree if
219 the Shift key is pressed)
220 • Collapse all: Collapses all folder trees
222 • Rename: Changes the name of a file
224 • Move to Trash: Moves a file to the trash
226 • Play: Plays a file, see Play. If the selected file is a
228 playlist, the files of the playlist will be played.
229 • Edit: Edit a playlist, see Edit Playlist.
231 • The subsequent entries are user commands, which can be defined
233 in the User Actions tab of Configure Kid3. The playback on
234 double click can also be activated there.
235 Edit Playlist
238 A playlist can be created empty or containing the tracks of a
239 folder, see Create Playlist. The playlist file created in such a
240 way can be edited by double click or using Edit from the file list
241 context menu. A dialog with the entries of the playlist is shown.
242 It is possible to open multiple playlists simultaneously.
243 New entries can be added by drag and drop from the file list, a
245 file manager or another playlist. If an entry is dragged from
246 another playlist, it will be moved or copied depending on the
247 system. To invoke the other operation, respectively, the Shift,
248 Ctrl or Alt (to copy instead of move on macOS®) key has to be
249 pressed. Reordering entries within the playlist is also possible
250 via drag and drop. Alternatively, entries can be moved using the
251 keyboard shortcuts Ctrl+Shift+Up and Ctrl+Shift+Down (on macOS®
252 Command has to be pressed instead of Ctrl). An entry can be removed
253 using the Delete key.
254 Please note the following: To drag entries from the file list, they
256 have to be held at the left side (near the icons), the same gesture
257 at the right side will perform a multi selection, such an action is
258 hereby still easily possible.
259 When a playlist has been modified, the changes can be stored using
261 Save or discarded using Cancel. When the window is closed, a
262 confirmation prompt is shown if there are unsaved changes.
263 Tracks selected in a playlist will be automatically selected in the
265 file list, thereby making it possible to edit their tags.
266 To execute actions on a playlist, its file must be selected in the
268 file list. Edit from the context menu will lead to the dialog
269 described in this section, and Play will start the media player
270 with the tracks from the playlist. User actions can act on
271 playlists, for example Export Playlist Folder, which copies the
272 files from a playlist into a folder.
273 Folder List
275 The folder list contains the names of the folders in the opened
276 folder, as well as the current (.) and the parent (..) folder. It
277 allows one to quickly change the folder without using the Open
278 command or drag and drop.
279 Column visibility, order and sorting can be configured as described
281 in the section about the file list.
282 File
284 Shows information about the encoding (MP3, Ogg, Opus, DSF, FLAC,
285 MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV,
286 AIFF), bit rate, sample rate, channels and the length of the file.
287 The Name line edit contains the name of the file (if only a single
289 file is selected). If this name is changed, the file will be
290 renamed when the Save command is used.
291 The Format combo box and line edit contains the format to be used
293 when the filename is generated from the first or the second tag.
294 The filename can contain arbitrary characters, even a folder part
295 separated by a slash from the file name, but that folder must
296 already exist for the renaming to succeed. The following special
297 codes are used to insert tag values into the filename:
298 • %s %{title} Title (Song)
300 • %a %{artist} Artist
302 • %l %{album} Album
304 • %c %{comment} Comment
306 • %y %{year} Year
308 • %t %{track} Track (e.g. 01)
310 • %t %{track.n} Track with field width n (e.g. 001 for
312 %{track.3})
313 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
315 • %g %{genre} Genre
317 • %{ignore} Ignored when generating tags from the file name
319 The format codes are not restricted to the examples given above.
321 Any frame name can be used, for instance unified frame names like
322 %{albumartist}, %{discnumber.1}, %{bpm} or format specific names
323 like %{popm}.
324 It is possible to prepend and append strings to the replacement for
326 a format code by adding them in double quotes inside the curly
327 braces of a format code. These strings will only be put into the
328 resulting string if the format code yields a nonempty value. For
329 example, if the file name shall both contain the title and the
330 subtitle, one could use %{title} [%{subtitle}] in the format
331 string. But this would result in a string ending with [] if no
332 subtitle frame exists for a file. In order to omit the brackets if
333 no subtitle is present, %{title}%{" ["subtitle"]"} shall be used
334 instead. This will omit the brackets, the leading space and the
335 subtitle if not subtitle exists.
336 The list of available formats can be edited in the dialog which
338 appears when clicking the Filename from tag button in the File tab
339 of the settings.
340 A second Format combo box (with arrow down) is used to generate the
342 tags from the filename. If the format of the filename does not
343 match this pattern, a few other commonly used formats are tried.
344 Some commonly used filename formats are already available in the
346 combo box, but it is also possible to type in some special format
347 into the line edit.
348 The list of available formats can be edited in the dialog which
350 appears when clicking the Tag from filename button in the File tab
351 of the settings.
352 Internally, a regular expression is built from the format codes. If
354 advanced regular expressions are required, the format to generate
355 the tags from the filenames can be given as a complete regular
356 expression with captures which are preceded by the format codes,
357 e.g. to extract the track numbers without removal of leading
358 zeros, a format like "/%{track}(\d+) %{title}(.*)" could be used.
359 From: Tag 1, Tag 2: Sets the filename using the selected format and
361 the first tag or the second tag, respectively.
362 To: Tag 1, Tag 2: The tags are set from the filename. First, the
364 format specified in Format is used. If the existing filename does
365 not match this format, the following formats are tried:
366 • Artist - Album/Track Song
368 • Album/Track - Artist - Song
370 • /Artist - Album - Track - Song
372 • Album/Artist - Track - Song
374 • Album/Artist - Song
376 • Artist/Album/Track Song
378 If a single file is selected, the GUI controls are filled with the
380 values extracted from the filename. If multiple files are selected,
381 the tags of the files are directly set according to the filenames.
382 Tag 1
384 The line edit widgets for Title, Artist, Album, Comment, Date,
385 Track Number and Genre are used to edit the corresponding value in
386 the first tag of the selected files. The value will be changed when
387 the file selection is altered or before operations like Save and
388 Quit and when the corresponding check box at the left of the field
389 name is checked. This is useful to change only some values and
390 leave the other values unchanged.
391 If a single file is selected, all check boxes are checked and the
393 line edit widgets contain the values found in the tags of this
394 file. If a tag is not found in the file, the corresponding empty
395 value is displayed, which is an empty string for the Title, Artist,
396 Album and Comment line edits, 0 for the numerical Date and Track
397 Number edits and an empty selected value for the Genre combo box.
398 The values can be changed and if the corresponding check box is
399 checked, they will be set for the selected file after the selection
400 is changed. The file is then marked as modified by a disk symbol in
401 the file listbox but remains unchanged until the Save command is
402 used.
403 If multiple files are selected, only the values which are identical
405 in all selected files are displayed. In all other controls, the
406 empty values as described above are displayed. All check boxes are
407 unchecked to avoid unwanted changes. If a value has to be set for
408 all selected files, it can be edited and the check box has to be
409 set. The values will be set for all selected files when the
410 selection is changed and can be saved using the Save command.
411 The check boxes also control the operation of most commands
413 affecting the tags, such as copy, paste and transfer between tags 1
414 and 2. To make it easier to use with multiple files where all check
415 boxes are unchecked, these commands behave in the same way when all
416 check boxes are checked and when all check boxes are unchecked.
417 From Tag 2: The tag 1 fields are set from the corresponding values
419 in tag 2. If a single file is selected, the GUI controls are filled
420 with the values from tag 2. If multiple files are selected, the
421 tags of the files are directly set.
422 Copy: The copy buffer is filled with the Tag 1 values. Only values
424 with checked check box will be used in subsequent Paste commands.
425 Paste: Pastes the values from the copy buffer into the GUI
427 controls.
428 Remove: This will set all GUI controls to their empty values which
430 results in removing all values. The saved file will then contain no
431 tag 1.
432 Tag 2
434 The GUI controls function in the same way as described for the Tag
435 1 section, but the size of the strings is not limited.
436 For the tag 2 Genre you can also use your own names besides the
438 genres listed in the combo box, just type the name into the line
439 edit.
440 The tag 2 cannot only contain the same values as the tag 1, the
442 format is built in a flexible way from several frames which are
443 themselves composed of several fields. The tag 2 table shows all
444 the frames which are available in the selected file.
445 Edit: This will open a window which allows one to edit all fields
447 of the selected frame. If multiple files are selected, the edited
448 fields are applied to all selected files which contain such a
449 frame.
450 Add: A requester to select the frame type will appear and a frame
452 of the selected type can be edited and added to the file. This
453 works also to add a frame to multiple selected files.
454 Delete: Deletes the selected frame in the selected files.
456 Drag album artwork here is shown if the file does not contain
458 embedded cover art. A picture can be added using drag and drop from
459 a browser or file manager and will be displayed here. Picture
460 frames can be edited or added by double clicking on this control.
461 Tag 3
463 Some files can have more than two tags, and a third tag section is
464 visible. The following file types can have such a Tag 3 section:
465 • MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0)
467 tag and in the third section an APE tag. Such APE tags are used
468 for replay gain information. In the Tag 3 section, this
469 information is visible, and the APE tag can be removed with the
470 Remove button.
471 • The RIFF INFO chunk of WAV files is available in the Tag 3
473 section because the Tag 1 section is dedicated to ID3v1.1 tags
474 and handles their restrictions. The Tag 2 is still used for
475 ID3v2.4.0 tags, which are also supported for WAV files, but
476 RIFF INFO chunks seem to be supported better.
477 • FLAC files normally use a Vorbis comment for their meta data.
479 However, there are FLAC files which have ID3v1 and ID3v2 tags,
480 which can be found in the Tag 1 and Tag 3 sections. ID3 tags in
481 FLAC files are only supported by TagLib, therefore the
482 OggFlacMetadata plugin has to be disabled in the Plugins tab of
483 the settings.
484 The GUI controls work in the same way as in the Tag 2 section.
486 Synchronized Lyrics and Event Timing Codes
488 For information synchronized with the audio data, a specific editor
489 is available. These frames are supported for ID3v2.3.0 and
490 ID3v2.4.0 tags. To add such a frame, the specific frame name has to
491 be selected in the list which appears when the Add button is
492 clicked - Synchronized Lyrics or Event Timing Codes, respectively.
493 The editor is the same for both types, for the event timing codes,
494 only a predefined set of events is available whereas for the
495 synchronized lyrics, text has to be entered. In the following,
496 editing synchronized lyrics is explained.
497 A file having an ID3v2 tag is selected, the lyrics editor is
499 entered using Add and selecting Synchronized Lyrics. For an
500 existing Synchronized Lyrics frame, it is selected and Edit is
501 clicked. The player is automatically opened with the current file
502 so that the file can be played and paused to synchronize lyrics.
503 The settings at the top of the SYLT editor normally do not have to
505 be changed. If the lyrics contains characters which are not present
506 in the Latin 1 character set, changing the text encoding to UTF16
507 (or UTF8 for ID3v2.4.0) is advisable. For English lyrics and
508 maximum compatibility, ISO-8859-1 should be used.
509 The Lyrics section has five buttons at the top. Add will add a new
511 time event in the table. The time is taken from the position of the
512 player, thus adding an entry while playing the track will add a
513 line for the currently played position. The events in the table
514 have to be chronologically ordered, therefore the row will be
515 inserted accordingly. Entries with an invalid time are treated
516 specially: If the currently selected row has an invalid time, its
517 time stamp will be replaced by the current time instead of adding a
518 new row. If the current time is not invalid, the first row with an
519 invalid time will be used if present. This behavior should
520 facilitate adding time stamps if the lyrics text is already in the
521 table but the time stamps are missing (which is the case when
522 importing unsynchronized lyrics). Note that the invalid time is
523 represented as 00:00.00, i.e. the same as the time at the absolute
524 beginning of the track, which is not invalid. To make a time
525 invalid, press the Delete key, or use Clear from the context menu.
526 New rows inserted using Insert row from the context menu or created
527 when importing unsynchronized lyrics with From Clipboard or Import
528 also contain invalid time stamps. Rows in the table can be deleted
529 by clicking the Delete button or using Delete rows from the context
530 menu.
531 Synchronized lyrics can be imported from a file using Import. The
533 expected format is simple or enhanced LRC. If the selected file
534 does not contain a square bracket in the first line, it is supposed
535 to be a simple text file with unsynchronized lyrics. The lines from
536 such a file are then imported having invalid time stamps. The time
537 information can be added using the Add button or by manual entry.
538 It is also possible to import lyrics via copy-paste using From
539 Clipboard. Synchronized lyrics can be written to LRC files using
540 Export. Note that only entries with valid time stamps will be
541 exported and that the entries will be sorted by time. Entries with
542 invalid time won't be stored in the SYLT frame either, so make sure
543 to include all timing information before leaving the dialog.
544 The ID3 specification[5] suggests a time stamp for each syllable.
546 However most players only support the granularity of a line or
547 sentence. To support both use cases, Kid3 follows the same
548 conventions as SYLT Editor[6]. Text which is entered into the table
549 is assumed to start a new line unless it starts with a space or a
550 hyphen. Exceptions to this rule are possible by starting a line
551 with an underscore ('_') to force continuation or a hash mark ('#')
552 to force a new line. These escape characters are not stored inside
553 the SYLT frame. Inside the SYLT frame, new lines start with a line
554 feed character (hex 0A) whereas continuations do not. When reading
555 SYLT frames, Kid3 checks if the first entry starts with a line
556 feed. If this is not the case, it is assumed that all entries are
557 new lines and that no syllable continuations are used.
558 While the track is played, the row associated with the current
560 playing position is highlighted, so that the correctness of the
561 synchronization information can be verified. If an offset has to be
562 added to one or more time stamps, this can be accomplished with the
563 Add offset context menu. Negative values can be used to reduce the
564 time. Using Seek to position in the context menu, it is possible to
565 set the playing position to the time of the selected row.
566 Recommended procedure to add new synchronized lyrics
568 • Get the unsynchronized lyrics, e.g. using Lyrics → Embed
570 Lyrics from the file list context menu.
571 • Copy the unsynchronized lyrics to the clipboard, just go to the
573 Lyrics row in the frame table and press Ctrl+C.
574 • Add a synchronized lyrics frame (Add..., Synchronized Lyrics,
576 OK), click From Clipboard.
577 • Now all lines from the unsynchronized lyrics are in the table,
579 all time stamps are invalid (0:0:0.00). You can delete empty
580 entries beforehand.
581 • Start playing the song by clicking the play button ► in the
583 play toolbar at the bottom of the main window.
584 • When the next lyrics line with invalid timestamp comes, click
586 Add or press Alt+A, the timestamp will be updated.
587 • Continue like this until all timestamps are set. If you missed
589 something, stop playback and clear the timestamps using the
590 Delete key or by selecting them and using Clear from the
591 context menu. To restart playback from a given timestamp, use
592 Seek to position from the context menu.
593 The File Menu
596 File → Open... (Ctrl+O)
597 Opens a folder. All files matching the selected file name filter
598 will be displayed in the file listbox and the chosen file is
599 selected.
600 File → Open Recent
602 Opens a recently opened folder.
603 File → Open Folder... (Ctrl+D)
605 Opens a folder. All files matching the selected file name filter
606 will be displayed in the file listbox.
607 File → Reload (F5)
609 Reload folder. Modified files have to be saved before. Expanded
610 subfolders will be collapsed.
611 File → Save (Ctrl+S)
613 Saves all changed files in the folder. The changed files are
614 marked with a disk symbol in the file listbox. If any file names
615 have been changed, those files will be renamed.
616 File → Revert
618 Reverts the changes of one or multiple files. If no files are
619 selected in the file listbox, the changes of all files will be
620 reverted, else only the changes of the selected files are reverted.
621 File → Import...
623 The Import dialog can be used to import data directly from a
624 freedb.org server, from a MusicBrainz server, from Discogs, Amazon
625 or other sources of album track lists in textual format.
626 Import from a freedb.org server is possible using a dialog which
628 appears when From Server: gnudb.org is selected. The artist and
629 album name to search for can be entered in the two topmost fields,
630 the albums which match the query will be displayed when Find is
631 clicked and the results from www.gnudb.org[7] are received.
632 Importing the track data for an album is done by double-clicking
633 the album in the list. The freedb.org server to import from can be
634 selected as well as the CGI path. The imported data is displayed in
635 the preview table of the import dialog. When satisfied with the
636 displayed tracks, they can be imported by terminating the import
637 dialog with OK.
638 A search on the Discogs server can be performed using Discogs. As
640 in the gnudb.org dialog, you can enter artist and album and then
641 choose from a list of releases. A Token can be entered to use the
642 RESTful Discogs API instead of their web interface, which is often
643 changed, thereby breaking the import parser. You have to register
644 for an account on Discogs[8] and then generate a token on their web
645 site (Settings/Developers, Generate new token). Don't forget to
646 Save Settings after entering the token in order to use it in
647 subsequent requests too. If Standard Tags is marked, the standard
648 information is imported, e.g. artist, album, and title. If
649 Additional Tags is marked, more information is imported if
650 available, e.g. performers, arrangers, or the publisher. If Cover
651 Art is marked, cover art will be downloaded if available.
652 A search on Amazon can be performed using Amazon. As in the
654 gnudb.org dialog, you can enter artist and album and then choose
655 from a list of releases. If Additional Tags is marked, more
656 information is imported if available, e.g. performers, arrangers,
657 or the publisher. If Cover Art is marked, cover art will be
658 downloaded if available.
659 You can search in the same way in the release database of
661 MusicBrainz using From MusicBrainz Release. The workflow is the
662 same as described for From gnudb.org.
663 Import from a MusicBrainz server is possible using the dialog which
665 appears when From MusicBrainz Fingerprint is selected. The Server
666 can be selected as in the freedb import dialog. Below is a table
667 displaying the imported track data. The right column shows the
668 state of the MusicBrainz query, which starts with "Pending" when
669 the dialog is opened. Then the fingerprint is looked up and if it
670 does not yield a result, another lookup using the tags in the file
671 is tried. Thus it can be helpful for a successful MusicBrainz query
672 to store known information (e.g. artist and album) in the tags
673 before the import. If a result was found, the search ends in the
674 state "Recognized", otherwise nothing was found or multiple
675 ambiguous results and one of them has to be selected by the user.
676 OK and Apply use the imported data, Cancel closes the dialog. The
677 closing can take a while since the whole MusicBrainz machinery has
678 to be shut down.
679 For the import of textual data, From File/Clipboard opens a
681 subdialog, where several preconfigured import formats are
682 available. The first two, "CSV unquoted" and "CSV quoted" can be
683 used to import data which was exported by the Export dialog. The
684 CSV data can be edited with a spreadsheet, and shall be written
685 using tabs as delimiters. Import should then be possible using "CSV
686 quoted", which is more flexible than "CSV unquoted". However, its
687 fields cannot contain any double quotes. If you only export from
688 Kid3 and import later, "CSV unquoted" can be used as a simple
689 format for this purpose. Note that there are also "Export CSV" and
690 "Import CSV" commands in the context menu of the file list, which
691 use scripts to export and import CSV data in a more complete,
692 powerful and flexible way.
693 The next format, "freedb HTML text", can be used to copy
695 information from an HTML page of freedb.org[9]. Search an album in
696 freedb and if the desired information is displayed in the web
697 browser, copy the contents to the clipboard. Then click the From
698 Clipboard button and the imported tracks will be displayed in the
699 preview table at the top of the dialog. If you are satisfied with
700 the imported data, terminate the dialog with OK, which will insert
701 the data into the tags of the current folder. The destination (Tag
702 1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box. The
703 files in the current folder should be in the correct track order to
704 get their tags assigned. This is the case if they are numbered.
705 The next preconfigured import format, "freedb HTML source", can be
707 used, if the data is available as an HTML document. Import is
708 possible using the From File button, which opens a file selector,
709 or copying its contents from an editor and then importing from
710 clipboard. This format can be useful for offline import, although
711 the HTML document could also be opened in a browser and then be
712 imported in the first format via the clipboard.
713 More preconfigured formats, e.g. "Track Title Time", are
715 available. An empty custom format can be created with Add to be set
716 by the user. Two lines below the format name can be set with a
717 regular expression to capture the fields from the import text. The
718 first regular expression will be parsed once per document to gather
719 per-album data such as artist, album, year and genre. The second
720 line is tried to match from the start of the document to the end to
721 get track data, usually number and title. The regular expressions
722 include all the features offered by Qt(TM), which is most of the
723 what Perl offers. Bracketing constructs "(..)" create capture
724 buffers for the fields to import and are preceded by Kid3 specific
725 codes to specify which field to capture. The codes are the same as
726 used for the filename format, besides the codes listed below, any
727 frame name is possible:
728 • %s %{title} Title (Song)
730 • %a %{artist} Artist
732 • %l %{album} Album
734 • %c %{comment} Comment
736 • %y %{year} Year
738 • %t %{track} Track
740 • %g %{genre} Genre
742 • %d %{duration} Duration
744 For example, a track regular expression (second line) to import
746 from an .m3u playlist could be
747 "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]". All formats can
748 be changed by editing the regular expressions and the name and then
749 clicking Save Settings. They will be stored in the kid3rc file in
750 the configuration folder. This file can be directly edited to have
751 more import formats or it can be deleted to revert to the default
752 formats. Formats can be deleted using Remove.
753 Accuracy shows an estimation of how good the imported information
755 matches the given tracks. It uses track durations or file names to
756 calculate the level of similarity in percent. Cover Art shows the
757 URL of the album cover image which will be downloaded.
758 To check whether the imported tracks match the current set of
760 files, the duration of the imported tracks can be compared with the
761 duration of the files. This option can be enabled with the check
762 box Check maximum allowable time difference (sec): and the maximum
763 tolerated difference in time can be set in seconds. If a mismatch
764 in a length is detected, the length is displayed with a red
765 background in the preview table.
766 If the files are ordered differently than the imported tracks,
768 their assigned tracks have to be changed. This task can be
769 facilitated using the Match with option with the buttons Length,
770 Track, and Title, which will reorder the tracks according to the
771 corresponding field. To correct the assignments manually, a track
772 can be dragged with the left mouse button and the Ctrl key hold
773 down, and then dropped at the new location.
774 When the import dialog is opened, it contains the actual contents
776 of the tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be
777 selected using the Destination combo box. The button on the right
778 of this combo box can be used to revert the table to the current
779 contents of the tags. The check boxes in the first table column can
780 be used to select the tracks which are imported. This can be useful
781 if a folder contains the tracks of both CDs of a double CD and only
782 the tracks of the second CD have to be imported.
783 To identify the tracks which are imported, it is possible to
785 display the file names or the full paths to the files using the
786 context menu of the table header. The values in the import table
787 can be edited. The revert-button to the right of the Destination
788 combo box can be used to restore the contents of the tags, which
789 can also be useful after changing the Destination.
790 Almost all dialogs feature a Save Settings button, which can be
792 used to store the dialog specific settings and the window size
793 persistently.
794 From Tags leads to a subdialog to set tag frames from the contents
796 of other tag frames. This can be used to simply copy information
797 between tags or extract a part from one frame and insert it in
798 another.
799 As in the import from file/clipboard dialog, there are freely
801 configurable formats to perform different operations. Already
802 preconfigured are formats to copy the Album value to Album Artist,
803 Composer or Conductor, and to extract the Track Number from Title
804 fields which contain a number. There is also a format to extract a
805 Subtitle from a Title field.
806 The following example explains how to add a custom format, which
808 sets the information from the Subtitle field also in the Comment
809 field. Create a new format using Add button and set a new name,
810 e.g. "Subtitle to Comment". Then enter "%{subtitle}" in Source and
811 "%{comment}(.*)" for Extraction and click Save Settings.
812 The expression in Source can contain format codes for arbitrary tag
814 frames, multiple codes can be used to combine the contents from
815 different frames. For each track, a text is generated from its tags
816 using the Source format, and the regular expression from Extraction
817 is applied to this text to set new values for the tags. Format
818 codes are used before the capturing parentheses to specify the tag
819 frame where the captured text shall be stored. It works in the same
820 way as for the import from file/clipboard.
821 Import from Tags... is also directly available from the File menu.
823 The difference between these two functions is that the import
824 dialog subdialog operates on all files of the current folder
825 whereas the menu function operates on the selected files (which can
826 be in different folders). The menu function supports an additional
827 code "%{__return}" to return the extracted value, which can be
828 useful with the CLI and QML interfaces.
829 File → Import from gnudb.org...
831 Import from a freedb.org server using gnudb.org album search. This
832 menu item opens the same import dialog as Import..., but opens
833 directly the gnudb.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[5]
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... function.
1773 • MusicBrainzImport: Used for the Import from MusicBrainz
1775 Release... function.
1776 • AcoustidImport: Used for the Import from MusicBrainz
1778 Fingerprint... function, which depends on the Chromaprint[20]
1779 and libav[21] libraries.
1780 Plugins which are disabled will not be loaded. This can be used to
1782 optimize resource usage and startup time. The settings on this page
1783 take only effect after a restart of Kid3.
1784 The Help Menu
1786 Help → Kid3 Handbook
1787 Opens this handbook.
1788 Help → About Kid3
1790 Displays a short information about Kid3.
1791
1793 Commands
1794 kid3-cli offers a command-line-interface for Kid3. If a folder path is
1795 used, the folder is opened. If one or more file paths are given, the
1796 common folder is opened and the files are selected. Subsequent commands
1797 will then work on these files. Commands are specified using -c options.
1798 If multiple commands are passed, they are executed in the given order.
1799 If files are modified by the commands, they will be saved at the end.
1800 If no command options are passed, kid3-cli starts in interactive mode.
1801 Commands can be entered and will operate on the current selection. The
1802 following sections list all available commands.
1803 Help
1805 help [COMMAND-NAME]
1806 Displays help about the parameters of COMMAND-NAME or about all
1808 commands if no command name is given.
1809 Timeout
1811 timeout [default | off | TIME]
1812 Overwrite the default command timeout. The CLI commands abort after
1814 a command specific timeout is expired. This timeout is 10 seconds
1815 for ls and albumart, 60 seconds for autoimport and filter, and 3
1816 seconds for all other commands. If a huge number of files has to be
1817 processed, these timeouts may be too restrictive, thus the timeout
1818 for all commands can be set to TIME ms, switched off altogether or
1819 be left at the default values.
1820 Quit application
1822 exit [force]
1823 Exit application. If there are modified unsaved files, the force
1825 parameter is required.
1826 Change folder
1828 cd [FOLDER]
1829 If no FOLDER is given, change to the home folder. If a folder is
1831 given, change into the folder. If one or more file paths are given,
1832 change to their common folder and select the files.
1833 Print the filename of the current folder
1835 pwd
1836 Print the filename of the current working folder.
1838 Folder list
1840 ls
1841 List the contents of the current folder. This corresponds to the
1843 file list in the Kid3 GUI. Five characters before the file names
1844 show the state of the file.
1845 • > File is selected.
1847 • * File is modified.
1849 • 1 File has a tag 1, otherwise '-' is displayed.
1851 • 2 File has a tag 2, otherwise '-' is displayed.
1853 • 3 File has a tag 3, otherwise '-' is displayed.
1855 kid3-cli> ls
1857 1-- 01 Intro.mp3
1858 > 12- 02 We Only Got This One.mp3
1859 *1-- 03 Outro.mp3
1860 In this example, all files have a tag 1, the second file also has a
1862 tag 2 and it is selected. The third file is modified.
1863 Save the changed files
1865 save
1866 Select file
1868 select [all | none | first | previous | next | FILE...]
1869 To select all files, enter select all, to deselect all files, enter
1871 select none. To traverse the files in the current folder start with
1872 select first, then go forward using select next or backward using
1873 select previous. Specific files can be added to the current
1874 selection by giving their file names. Wildcards are possible, so
1875 select *.mp3 will select all MP3 files in the current folder.
1876 kid3-cli> select first
1878 kid3-cli> ls
1879 > 1-- 01 Intro.mp3
1880 12- 02 We Only Got This One.mp3
1881 *1-- 03 Outro.mp3
1882 kid3-cli> select next
1883 kid3-cli> ls
1884 1-- 01 Intro.mp3
1885 > 12- 02 We Only Got This One.mp3
1886 *1-- 03 Outro.mp3
1887 kid3-cli> select *.mp3
1888 kid3-cli> ls
1889 > 1-- 01 Intro.mp3
1890 > 12- 02 We Only Got This One.mp3
1891 >*1-- 03 Outro.mp3
1892 Select tag
1894 tag [TAG-NUMBERS]
1895 Many commands have an optional TAG-NUMBERS parameter, which
1897 specifies whether the command operates on tag 1, 2, or 3. If this
1898 parameter is omitted, the default tag numbers are used, which can
1899 be set by this command. At startup, it is set to 12 which means
1900 that information is read from tag 2 if available, else from tag 1;
1901 modifications are done on tag 2. The TAG-NUMBERS can be set to 1,
1902 2, or 3 to operate only on the corresponding tag. If the parameter
1903 is omitted, the current setting is displayed.
1904 Get tag frame
1906 get [all | FRAME-NAME] [TAG-NUMBERS]
1907 This command can be used to read the value of a specific tag frame
1909 or get information about all tag frames (if the argument is omitted
1910 or all is used). Modified frames are marked with a '*'.
1911 kid3-cli> get
1913 File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
1914 Name: 01 Intro.mp3
1915 Tag 1: ID3v1.1
1916 Title Intro
1917 Artist One Hit Wonder
1918 Album Let's Tag
1919 Date 2013
1920 Track Number 1
1921 Genre Pop
1922 kid3-cli> get title
1923 Intro
1924 To save the contents of a picture frame to a file, use
1926 get picture:'/path/to/folder.jpg'
1928 To save synchronized lyrics to an LRC file, use
1930 get SYLT:'/path/to/lyrics.lrc'
1932 It is possible to get only a specific field from a frame, for
1934 example get POPM.Email for the Email field of a Popularimeter
1935 frame. If a file has multiple frames of the same kind, the
1936 different frames can be indexed with brackets, for example the
1937 first performer from a Vorbis comment can be retrieved using get
1938 performer[0], the second using get performer[1].
1939 The pseudo field name "selected" can be used to check if a frame is
1941 selected, for example get artist.selected will return 1 if the
1942 artist frame is selected, else 0.
1943 Set tag frame
1945 set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]
1946 This command sets the value of a specific tag frame. If FRAME-VALUE
1948 is empty, the frame is deleted.
1949 kid3-cli> set remixer 'O.H. Wonder'
1951 To set the contents of a picture frame from a file, use
1953 set picture:'/path/to/folder.jpg' 'Picture Description'
1955 To set synchronized lyrics from an LRC file, use
1957 set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'
1959 To set a specific field of a frame, the field name can be given
1961 after a dot, e.g. to set the Counter field of a Popularimeter
1962 frame, use
1963 set POPM.Counter 5
1965 An application for field specifications is the case where you want
1967 a custom TXXX frame with "rating" description instead of a standard
1968 Popularimeter frame (this seems to be used by some plugins). You
1969 can create such a TXXX rating frame with kid3-cli, however, you
1970 have to first create a TXXX frame with description "rating" and
1971 then set the value of this frame to the rating value.
1972 kid3-cli> set rating ""
1974 kid3-cli> set TXXX.Description rating
1975 kid3-cli> set rating 5
1976 The first command will delete an existing POPM frame, because if
1978 such a frame exists, set rating 5 would set the POPM frame and not
1979 the TXXX frame. Another possibility would be to use set TXXX.Text
1980 5, but this would only work if there is no other TXXX frame
1981 present.
1982 To set multiple frames of the same kind, an index can be given in
1984 brackets, e.g. to set multiple performers in a Vorbis comment, use
1985 kid3-cli> set performer[0] 'Liza don Getti (soprano)'
1987 kid3-cli> set performer[1] 'Joe Barr (piano)'
1988 To select certain frames before a copy, paste or remove action, the
1990 pseudo field name "selected" can be used. Normally, all frames are
1991 selected, to deselect all, use set '*.selected' 0, then for example
1992 set artist.selected 1 to select the artist frame.
1993 Revert
1995 revert
1996 Revert all modifications in the selected files (or all files if no
1998 files are selected).
1999 Import from file
2001 import {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2002 Tags are imported from the file FILE in the format with the name
2004 FORMAT-NAME (e.g. "CSV unquoted", see Import).
2005 If tags is given for FILE, tags are imported from other tags.
2007 Instead of FORMAT-NAME parameters SOURCE and EXTRACTION are
2008 required, see Import from Tags. To apply the import from tags on
2009 the selected files, use tagsel instead of tags. This function also
2010 supports output of the extracted value by using an EXTRACTION with
2011 the value %{__return}(.+).
2012 Automatic import
2014 autoimport [PROFILE-NAME] [TAG-NUMBERS]
2015 Batch import using profile PROFILE-NAME (see Automatic Import,
2017 "All" is used if omitted).
2018 Download album cover artwork
2020 albumart {URL} [all]
2021 Set the album artwork by downloading a picture from URL. The rules
2023 defined in the Browse Cover Art dialog are used to transform
2024 general URLs (e.g. from Amazon) to a picture URL. To set the album
2025 cover from a local picture file, use the set command.
2026 kid3-cli> albumart
2028 http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
2029 Export to file
2031 export {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2032 Tags are exported to file FILE in the format with the name
2034 FORMAT-NAME (e.g. "CSV unquoted", see Export).
2035 Create playlist
2037 playlist
2038 Create playlist in the format set in the configuration, see Create
2040 Playlist.
2041 Apply filename format
2043 filenameformat
2044 Apply file name format set in the configuration, see Apply Filename
2046 Format.
2047 Apply tag format
2049 tagformat
2050 Apply tag name format set in the configuration, see Apply Tag
2052 Format.
2053 Apply text encoding
2055 textencoding
2056 Apply text encoding set in the configuration, see Apply Text
2058 Encoding.
2059 Rename folder
2061 renamedir [FORMAT] [create | rename | dryrun] [TAG-NUMBERS]
2062 Rename or create folders from the values in the tags according to a
2064 given FORMAT (e.g. %{artist} - %{album}, see Rename Folder), if no
2065 format is given, the format defined in the Rename folder dialog is
2066 used. The default mode is rename; to create folders, create must be
2067 given explicitly. The rename actions will be performed immediately,
2068 to just see what would be done, use the dryrun option.
2069 Number tracks
2071 numbertracks [TRACK-NUMBER] [TAG-NUMBERS]
2072 Number the selected tracks starting with TRACK-NUMBER (1 if
2074 omitted).
2075 Filter
2077 filter [FILTER-NAME | FILTER-FORMAT]
2078 Filter the files so that only the files matching the FILTER-FORMAT
2080 are visible. The name of a predefined filter expression (e.g.
2081 "Filename Tag Mismatch") can be used instead of a filter
2082 expression, see Filter.
2083 kid3-cli> filter '%{title} contains "tro"'
2085 Started
2086 /home/urs/One Hit Wonder - Let's Tag
2087 + 01 Intro.mp3
2088 - 02 We Only Got This One.mp3
2089 + 03 Outro.mp3
2090 Finished
2091 kid3-cli> ls
2092 1-- 01 Intro.mp3
2093 1-- 03 Outro.mp3
2094 kid3-cli> filter All
2095 Started
2096 /home/urs/One Hit Wonder - Let's Tag
2097 + 01 Intro.mp3
2098 + 02 We Only Got This One.mp3
2099 + 03 Outro.mp3
2100 Finished
2101 kid3-cli> ls
2102 1-- 01 Intro.mp3
2103 12- 02 We Only Got This One.mp3
2104 1-- 03 Outro.mp3
2105 Convert ID3v2.3 to ID3v2.4
2107 to24
2108 Convert ID3v2.4 to ID3v2.3
2110 to23
2111 Filename from tag
2113 fromtag [FORMAT] [TAG-NUMBERS]
2114 Set the file names of the selected files from values in the tags,
2116 for example fromtag '%{track} - %{title}' 1. If no format is
2117 specified, the format set in the GUI is used.
2118 Tag from filename
2120 totag [FORMAT] [TAG-NUMBERS]
2121 Set the tag frames from the file names, for example totag
2123 '%{albumartist} - %{album}/%{track} %{title}' 2. If no format is
2124 specified, the format set in the GUI is used. If the format of the
2125 filename does not match this pattern, a few other commonly used
2126 formats are tried.
2127 Tag to other tag
2129 syncto {TAG-NUMBER}
2130 Copy the tag frames from one tag to the other tag, e.g. to set the
2132 ID3v2 tag from the ID3v1 tag, use syncto 2.
2133 Copy
2135 copy [TAG-NUMBER]
2136 Copy the tag frames of the selected file to the internal copy
2138 buffer. They can then be set on another file using the paste
2139 command.
2140 To copy only a subset of the frames, use the "selected" pseudo
2142 field with the set command. For example, to copy only the disc
2143 number and copyright frames, use
2144 set '*.selected' 0
2146 set discnumber.selected 1
2147 set copyright.selected 1
2148 copy
2149 Paste
2152 paste [TAG-NUMBER]
2153 Set tag frames from the contents of the copy buffer in the selected
2155 files.
2156 Remove
2158 remove [TAG-NUMBER]
2159 Remove a tag.
2161 It is possible to remove only a subset of the frames by selecting
2163 them as described in the copy command.
2164 Configure Kid3
2166 config [OPTION] [VALUE]
2167 Query or set a configuration option.
2169 The OPTION consists of a group name and a property name separated
2171 by a dot. When no OPTION is given, all available groups are
2172 displayed. If only a group name is given, all available properties
2173 of the group are displayed. For a given group and property, the
2174 currently configured value is displayed. To change the setting, the
2175 new value can be passed as a second argument.
2176 If the value of a setting is a list, all list elements have to be
2178 given as arguments. This means that to append an element to an
2179 existing list of elements, all existing elements have to be passed
2180 followed by the new element. In such a situation, it is easier to
2181 use the JSON mode, where the current list can be copied with the
2182 new element appended.
2183 Examples
2185 Set title containing an apostrophe. Commands passed to kid3-cli with -c
2186 have to be in quotes if they do not only consist of a single word. If
2187 such a command itself has an argument containing spaces, that argument
2188 has to be quoted too. In UNIX® shells single or double quotes can be
2189 used, but on the Windows Command Prompt, it is important that the outer
2190 quoting is done using double quotes and inside these quotes, single
2191 quotes are used. If the text inside the single quotes contains a single
2192 quote, it has to be escaped using a backslash character, as shown in
2193 the following example:
2194 kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder
2196 Set album cover in all files of a folder using the batch import
2198 function:
2199 kid3-cli -c "autoimport 'Cover Art'" /path/to/folder
2201 Remove comment frames and apply the tag format in both tags of all MP3
2203 files of a folder:
2204 kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
2206 -c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3
2207 Automatically import tag 2, synchronize to tag 1, set file names from
2209 tag 2 and finally create a playlist:
2210 kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
2212 /path/to/folder/*.mp3
2213 For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
2215 the arranger frame:
2216 kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
2218 -c "set arranger ''" /path/to/folder
2219 This Python script uses kid3-cli to generate iTunes Sound Check
2221 iTunNORM frames from replay gain information.
2222 #!/usr/bin/env python3
2225 # Generate iTunes Sound Check from ReplayGain.
2226 import os, sys, subprocess
2227 def rg2sc(dirpath):
2229 for root, dirs, files in os.walk(dirpath):
2230 for name in files:
2231 if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
2232 fn = os.path.join(root, name)
2233 rg = subprocess.check_output([
2234 'kid3-cli', '-c', 'get "replaygain_track_gain"',
2235 fn]).strip()
2236 if rg.endswith(b' dB'):
2237 rg = rg[:-3]
2238 try:
2239 rg = float(rg)
2240 except ValueError:
2241 print('Value %s of %s in not a float' % (rg, fn))
2242 continue
2243 sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
2244 subprocess.call([
2245 'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
2246 if __name__ == '__main__':
2248 rg2sc(sys.argv[1])
2249 JSON Format
2252 In order to make it easier to parse results from kid3-cli, it is
2253 possible to get the output in JSON format. When the request is in JSON
2254 format, the response will also be JSON. A compact format of the request
2255 will also give a compact representation of the response. If the request
2256 contains an "id" field, it is assumed to be a JSON-RPC request and the
2257 response will contain a "jsonrpc" field and the "id" of the request.
2258 The request format uses the same commands as the standard CLI, the
2259 "method" field contains the command and the parameters (if any) are
2260 given in the "params" list. The response contains a "result" object,
2261 which can also be null if the corresponding kid3-cli command does not
2262 return a result. In case of an error, an "error" object is returned
2263 with "code" and "message" fields as used in JSON-RPC.
2264 kid3-cli> {"method":"set","params":["artist","An Artist"]}
2266 {"result":null}
2267 kid3-cli> {"method":"get","params":["artist",2]}
2268 {"result":"An Artist"}
2269 kid3-cli> {"method": "get", "params": ["artist"]}
2270 {
2271 "result": "An Artist"
2272 }
2273 kid3-cli> {"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}
2275 {"id":"123","jsonrpc":"2.0","result":"An Artist"}
2276
2279 Kid3
2280 Program written by Urs Fleisch <ufleisch at users.sourceforge.net>
2282 FDL[22]
2284 GPL[23]
2286
2288 How to obtain Kid3
2289 Kid3 can be found at https://kid3.kde.org.
2290 Requirements
2292 Kid3 needs Qt(TM)[24]. KDE[25] is recommended but not necessary, as
2293 Kid3 can also be compiled as a Qt(TM) application. Kid3 can be
2294 compiled for systems where these libraries are available, e.g. for
2295 GNU/Linux®, Windows® and macOS®. To tag Ogg/Vorbis files, libogg[15],
2296 libvorbis and libvorbisfile[16] are required, for FLAC files libFLAC++
2297 and libFLAC[17]. id3lib[14] is used for MP3 files. These four formats
2298 are also supported by TagLib[18], which can also handle Opus, MPC, APE,
2299 MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker
2300 modules. To import from acoustic fingerprints, Chromaprint[20] and
2301 libav[21] are used.
2302 Kid3 is available for most Linux® distributions, Windows® and macOS®.
2304 Links can be found on https://kid3.kde.org.
2305 Compilation and Installation
2307 You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple
2308 Qt(TM) application and lacks some configuration and session features.
2309 For a KDE version, go into the top folder and type
2311 % cmake .
2313 % make
2314 % make install
2315 To compile for different versions of Qt(TM) or KDE, set the
2317 corresponding cmake options.
2318 If not all libraries are present, Kid3 is built with reduced
2320 functionality. So you should take care to have all desired development
2321 packages installed. On the other side, cmake-options control which
2322 libraries are compiled in. The default is -DWITH_TAGLIB:BOOL=ON
2323 -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON
2324 -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON . These options can be
2325 disabled using OFF.
2326 To build Kid3 as a Qt(TM) application without KDE, use the cmake option
2328 -DWITH_APPS=Qt. To build both a KDE and a Qt(TM) application, set
2329 -DWITH_APPS="Qt;KDE".
2330 To use a specific Qt(TM) installation, set
2332 -DQT_QMAKE_EXECUTABLE=/path/to/qmake.
2333 Generation of RPM-Packages is supported by the file kid3.spec, for
2335 Debian® Packages, the script build-deb.sh is available.
2336 The Qt(TM) application can also be compiled for Windows® and macOS®.
2338 The script buildlibs.sh can be used to download and build all required
2339 libraries and create a Kid3 package.
2340 Configuration
2342 With KDE, the settings are stored in .config/kid3rc. As a Qt(TM)
2343 application, this file is in .config/Kid3/Kid3.conf. On Windows®, the
2344 configuration is stored in the registry. on macOS® in a plist file.
2345 The environment variable KID3_CONFIG_FILE can be used to set the path
2347 of the configuration file.
2348
2350 D-Bus Examples
2351 On Linux® a D-Bus-interface can be used to control Kid3 by scripts.
2352 Scripts can be written in any language with D-Bus-bindings (e.g. in
2353 Python) and can be added to the User Actions to extend the
2354 functionality of Kid3.
2355 The artist in tag 2 of the current file can be set to the value "One
2357 Hit Wonder" with the following code:
2358 Shell
2360 dbus-send --dest=org.kde.kid3 --print-reply=literal \
2362 /Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
2363 string:'One Hit Wonder'
2364 or easier with Qt(TM)'s qdbus (qdbusviewer can be used to explore
2366 the interface in a GUI):
2367 qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
2369 'One Hit Wonder'
2370 Python
2372 import dbus
2374 kid3 = dbus.SessionBus().get_object(
2375 'org.kde.kid3', '/Kid3')
2376 kid3.setFrame(2, 'Artist', 'One Hit Wonder')
2377 Perl
2379 use Net::DBus;
2381 $kid3 = Net::DBus->session->get_service(
2382 "org.kde.kid3")->get_object(
2383 "/Kid3", "org.kde.Kid3");
2384 $kid3->setFrame(2, "Artist", "One Hit Wonder");
2385 D-Bus API
2387 The D-Bus API is specified in org.kde.Kid3.xml. The Kid3 interface has
2388 the following methods:
2389 Open file or folder
2391 boolean openDirectory(string path);
2392 path
2394 path to file or folder
2395 Returns true if OK.
2397 Unload the tags of all files which are not modified or selected
2399 unloadAllTags(void);
2400 Save all modified files
2402 boolean save(void);
2403 Returns true if OK.
2405 Get a detailed error message provided by some methods
2407 string getErrorMessage(void);
2408 Returns detailed error message.
2410 Revert changes in the selected files
2412 revert(void);
2413 Start an automatic batch import
2415 boolean batchImport(int32 tagMask, string profileName);
2416 tagMask
2418 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2419 profileName
2421 name of batch import profile to use
2422 Import tags from a file
2424 boolean importFromFile(int32 tagMask, string path, int32 fmtIdx);
2425 tagMask
2427 tag bit (1 for tag 1, 2 for tag 2)
2428 path
2430 path of file
2431 fmtIdx
2433 index of format
2434 Returns true if OK.
2436 Import tags from other tags
2438 importFromTags(int32 tagMask, string source, string extraction);
2439 tagMask
2441 tag bit (1 for tag 1, 2 for tag 2)
2442 source
2444 format to get source text from tags
2445 extraction
2447 regular expression with frame names and captures to extract
2448 from source text
2449 Import tags from other tags on selected files
2451 array importFromTagsToSelection(int32 tagMask, string source,
2452 string extraction);
2453 tagMask
2455 tag bit (1 for tag 1, 2 for tag 2)
2456 source
2458 format to get source text from tags
2459 extraction
2461 regular expression with frame names and captures to extract
2462 from source text
2463 returnValues
2465 extracted value for "%{__return}(.+)"
2466 Download album cover art
2468 downloadAlbumArt(string url, boolean allFilesInDir);
2469 url
2471 URL of picture file or album art resource
2472 allFilesInDir
2474 true to add the image to all files in the folder
2475 Export tags to a file
2477 boolean exportToFile(int32 tagMask, string path, int32 fmtIdx);
2478 tagMask
2480 tag bit (1 for tag 1, 2 for tag 2)
2481 path
2483 path of file
2484 fmtIdx
2486 index of format
2487 Returns true if OK.
2489 Create a playlist
2491 boolean createPlaylist(void);
2492 Returns true if OK.
2494 Get items of a playlist
2496 array getPlaylistItems(string path);
2497 path
2499 path to playlist file
2500 Returns list of absolute paths to playlist items.
2502 Set items of a playlist
2504 boolean setPlaylistItems(string path, array items);
2505 path
2507 path to playlist file
2508 items
2510 list of absolute paths to playlist items
2511 Returns true if OK, false if not all items were found and added or
2513 saving failed.
2514 Quit the application
2516 quit(void);
2517 Select all files
2519 selectAll(void);
2520 Deselect all files
2522 deselectAll(void);
2523 Set the first file as the current file
2525 boolean firstFile(void);
2526 Returns true if there is a first file.
2528 Set the previous file as the current file
2530 boolean previousFile(void);
2531 Returns true if there is a previous file.
2533 Set the next file as the current file
2535 boolean nextFile(void);
2536 Returns true if there is a next file.
2538 Select the first file
2540 boolean selectFirstFile(void);
2541 Returns true if there is a first file.
2543 Select the previous file
2545 boolean selectPreviousFile(void);
2546 Returns true if there is a previous file.
2548 Select the next file
2550 boolean selectNextFile(void);
2551 Returns true if there is a next file.
2553 Select the current file
2555 boolean selectCurrentFile(void);
2556 Returns true if there is a current file.
2558 Expand or collapse the current file item if it is a folder
2560 boolean expandDirectory(void);
2561 A file list item is a folder if getFileName() returns a name with
2563 '/' as the last character.
2564 Returns true if current file item is a folder.
2566 Apply the file name format
2568 applyFilenameFormat(void);
2569 Apply the tag format
2571 applyTagFormat(void);
2572 Apply text encoding
2574 applyTextEncoding(void);
2575 Set the folder name from the tags
2577 boolean setDirNameFromTag(int32 tagMask, string format,
2578 boolean create);
2579 tagMask
2581 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2582 format
2584 folder name format
2585 create
2587 true to create, false to rename
2588 Returns true if OK, else the error message is available using
2590 getErrorMessage().
2591 Set subsequent track numbers in the selected files
2593 numberTracks(int32 tagMask, int32 firstTrackNr);
2594 tagMask
2596 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2597 firstTrackNr
2599 number to use for first file
2600 Filter the files
2602 filter(string expression);
2603 expression
2605 filter expression
2606 Convert ID3v2.3 tags to ID3v2.4
2608 convertToId3v24(void);
2609 Convert ID3v2.4 tags to ID3v2.3
2611 convertToId3v23(void);
2612 Returns true if OK.
2614 Get path of folder
2616 string getDirectoryName(void);
2617 Returns absolute path of folder.
2619 Get name of current file
2621 string getFileName(void);
2622 Returns true absolute file name, ends with "/" if it is a folder.
2624 Set name of selected file
2626 setFileName(string name);
2627 name
2629 file name
2630 The file will be renamed when the folder is saved.
2632 Set format to use when setting the filename from the tags
2634 setFileNameFormat(string format);
2635 format
2637 file name format
2638 Set the file names of the selected files from the tags
2640 setFileNameFromTag(int32 tagMask);
2641 tagMask
2643 tag bit (1 for tag 1, 2 for tag 2)
2644 Get value of frame
2646 string getFrame(int32 tagMask, string name);
2647 tagMask
2649 tag bit (1 for tag 1, 2 for tag 2)
2650 name
2652 name of frame (e.g. "artist")
2653 To get binary data like a picture, the name of a file to write can
2655 be added after the name, e.g. "Picture:/path/to/file". In the same
2656 way, synchronized lyrics can be exported, e.g.
2657 "SYLT:/path/to/file".
2658 Returns value of frame.
2660 Set value of frame
2662 boolean setFrame(int32 tagMask, string name, string value);
2663 tagMask
2665 tag bit (1 for tag 1, 2 for tag 2)
2666 name
2668 name of frame (e.g. "artist")
2669 value
2671 value of frame
2672 For tag 2 (tagMask 2), if no frame with name exists, a new frame is
2674 added, if value is empty, the frame is deleted. To add binary data
2675 like a picture, a file can be added after the name, e.g.
2676 "Picture:/path/to/file". "SYLT:/path/to/file" can be used to import
2677 synchronized lyrics.
2678 Returns true if OK.
2680 Get all frames of a tag
2682 array of string getTag(int32 tagMask);
2683 tagMask
2685 tag bit (1 for tag 1, 2 for tag 2)
2686 Returns list with alternating frame names and values.
2688 Get technical information about file
2690 array of string getInformation(void);
2691 Properties are Format, Bitrate, Samplerate, Channels, Duration,
2693 Channel Mode, VBR, Tag 1, Tag 2. Properties which are not available
2694 are omitted.
2695 Returns list with alternating property names and values.
2697 Set tag from file name
2699 setTagFromFileName(int32 tagMask);
2700 tagMask
2702 tag bit (1 for tag 1, 2 for tag 2)
2703 Set tag from other tag
2705 setTagFromOtherTag(int32 tagMask);
2706 tagMask
2708 tag bit (1 for tag 1, 2 for tag 2)
2709 Copy tag
2711 copyTag(int32 tagMask);
2712 tagMask
2714 tag bit (1 for tag 1, 2 for tag 2)
2715 Paste tag
2717 pasteTag(int32 tagMask);
2718 tagMask
2720 tag bit (1 for tag 1, 2 for tag 2)
2721 Remove tag
2723 removeTag(int32 tagMask);
2724 tagMask
2726 tag bit (1 for tag 1, 2 for tag 2)
2727 Reparse the configuration
2729 reparseConfiguration(void);
2730 Automated configuration changes are possible by modifying the
2732 configuration file and then reparsing the configuration.
2733 Plays the selected files
2735 playAudio(void);
2736
2738 QML Examples
2739 QML scripts can be invoked via the context menu of the file list and
2740 can be set in the tab User Actions of the settings dialog. The scripts
2741 which are set there can be used as examples to program custom scripts.
2742 QML uses JavaScript, here is the obligatory "Hello World":
2743 import Kid3 1.0
2745 Kid3Script {
2747 onRun: {
2748 console.log("Hello world, folder is", app.dirName)
2749 Qt.quit()
2750 }
2751 }
2752 If this script is saved as /path/to/Example.qml, the user command can
2754 be defined as @qml /path/to/Example.qml with name QML Test and Output
2755 checked. It can then be started using the QML Test item in the file
2756 list context menu, and the output will be visible in the window.
2757 Alternatively, the script could also be started independent of Kid3
2759 using the QML tools.
2760 qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2762 or
2764 qmlscene -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2766 On Windows® and macOS®, the import path must be adapted to the imports
2768 folder inside the installation folder. Scripts started outside of Kid3
2769 will use the current folder, so it should be changed beforehand.
2770 To list the titles in the tags 2 of all files in the current folder,
2772 the following script could be used:
2773 import Kid3 1.0
2775 Kid3Script {
2777 onRun: {
2778 app.firstFile()
2779 do {
2780 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2781 console.log(app.getFrame(tagv2, "title"))
2782 }
2783 } while (app.nextFile())
2784 }
2785 }
2786 If the folder contains many files, such a script might block the user
2788 interface for some time. For longer operations, it should therefore
2789 have a break from time to time. The alternative implementation below
2790 has the work for a single file moved out into a function. This function
2791 invokes itself with a timeout of 1 ms at the end, given that more files
2792 have to be processed. This will ensure that the GUI remains responsive
2793 while the script is running.
2794 import Kid3 1.0
2796 Kid3Script {
2798 onRun: {
2799 function doWork() {
2800 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2801 console.log(app.getFrame(tagv2, "title"))
2802 }
2803 if (!app.nextFile()) {
2804 Qt.quit()
2805 } else {
2806 setTimeout(doWork, 1)
2807 }
2808 }
2809 app.firstFile()
2811 doWork()
2812 }
2813 }
2814 When using app.firstFile() with app.nextFile(), all files of the
2816 current folder will be processed. If only the selected files shall be
2817 affected, use firstFile() and nextFile() instead, these are convenience
2818 functions of the Kid3Script component. The following example is a
2819 script which copies only the disc number and copyright frames of the
2820 selected file.
2821 import Kid3 1.1
2823 Kid3Script {
2825 onRun: {
2826 function doWork() {
2827 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2828 app.setFrame(tagv2, "*.selected", false)
2829 app.setFrame(tagv2, "discnumber.selected", true)
2830 app.setFrame(tagv2, "copyright.selected", true)
2831 app.copyTags(tagv2)
2832 }
2833 if (!nextFile()) {
2834 Qt.quit()
2835 } else {
2836 setTimeout(doWork, 1)
2837 }
2838 }
2839 firstFile()
2841 doWork()
2842 }
2843 }
2844 More example scripts come with Kid3 and are already registered as user
2846 commands.
2847 • ReplayGain to SoundCheck (ReplayGain2SoundCheck.qml): Create
2849 iTunNORM SoundCheck information from replay gain frames.
2850 • Resize Album Art (ResizeAlbumArt.qml): Resize embedded cover art
2852 images which are larger than 500x500 pixels.
2853 • Extract Album Art (ExtractAlbumArt.qml): Extract all embedded cover
2855 art pictures avoiding duplicates.
2856 • Embed Album Art (EmbedAlbumArt.qml): Embed cover art found in image
2858 files into audio files in the same folder.
2859 • Embed Lyrics (EmbedLyrics.qml): Fetch unsynchronized lyrics from
2861 web service.
2862 • Text Encoding ID3v1 (ShowTextEncodingV1.qml): Helps to find the
2864 encoding of ID3v1 tags by showing the tags of the current file in
2865 all available character encodings.
2866 • ID3v1 to ASCII (Tag1ToAscii.qml): Transliterate extended latin
2868 characters in the ID3v1 tag to ASCII.
2869 • English Title Case (TitleCase.qml): Formats text in the tags to
2871 English title case.
2872 • Rewrite Tags (RewriteTags.qml): Rewrite all tags in the selected
2874 files.
2875 • Export CSV (ExportCsv.qml): Export recursively all tags of all
2877 files to a CSV file.
2878 • Export Playlist Folder (ExportPlaylist.qml): Copy all files from a
2880 playlist into a folder and rename them according to their position.
2881 • QML Console (QmlConsole.qml): Simple console to play with Kid3's
2883 QML API.
2884 QML API
2887 The API can be easily explored using the QML Console, which is
2888 available as an example script with a user interface.
2889 Kid3Script
2891 Kid3Script is a regular QML component located inside the plugin
2892 folder. You could use another QML component just as well. Using
2893 Kid3Script makes it easy to start the script function using the
2894 onRun signal handler. Moreover it offers some functions:
2895 onRun: Signal handler which is invoked when the script is started
2897 tagv1, tagv2, tagv2v1: Constants for tag parameters
2898 script: Access to scripting functions
2899 configs: Access to configuration objects
2900 getArguments(): List of script arguments
2901 isStandalone(): true if the script was not started from within Kid3
2902 setTimeout(callback, delay): Starts callback after delay ms
2903 firstFile(): To first selected file
2904 nextFile(): To next selected file
2905 Scripting Functions
2908 As JavaScript and therefore QML too has only a limited set of
2909 functions for scripting, the script object has some additional
2910 methods, for instance:
2911 script.properties(obj): String with Qt properties
2913 script.writeFile(filePath, data): Write data to file, true if OK
2914 script.readFile(filePath): Read data from file
2915 script.removeFile(filePath): Delete file, true if OK
2916 script.fileExists(filePath): true if file exists
2917 script.fileIsWritable(filePath): true if file is writable
2918 script.getFilePermissions(filePath): Get file permission mode bits
2919 script.setFilePermissions(filePath, modeBits): Set file permission mode bits
2920 script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
2921 file " ")
2922 script.renameFile(oldName, newName): Rename file, true if OK
2923 script.copyFile(source, dest): Copy file, true if OK
2924 script.makeDir(path): Create folder, true if OK
2925 script.removeDir(path): Remove folder, true if OK
2926 script.tempPath(): Path to temporary folder
2927 script.musicPath(): Path to music folder
2928 script.listDir(path, [nameFilters], [classify]): List folder entries
2929 script.system(program, [args], [msecs]): Synchronously start a system command,
2930 [exit code, standard output, standard error] if not timeout
2931 script.systemAsync(program, [args], [callback]): Asynchronously start a system
2932 command, callback will be called with [exit code, standard output, standard
2933 error]
2934 script.getEnv(varName): Get value of environment variable
2935 script.setEnv(varName, value): Set value of environment variable
2936 script.getQtVersion(): Qt version string, e.g. "5.4.1"
2937 script.getDataMd5(data): Get hex string of the MD5 hash of data
2938 script.getDataSize(data): Get size of byte array
2939 script.dataToImage(data, [format]): Create an image from data bytes
2940 script.dataFromImage(img, [format]): Get data bytes from image
2941 script.loadImage(filePath): Load an image from a file
2942 script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
2943 script.imageProperties(img): Get properties of an image, map containing
2944 "width", "height", "depth" and "colorCount", empty if invalid image
2945 script.scaleImage(img, width, [height]): Scale an image, returns scaled image
2946 Application Context
2948 Using QML, a large part of the Kid3 functions are accessible. The
2949 API is similar to the one used for D-Bus. For details, refer to the
2950 respective notes.
2951 app.openDirectory(path): Open folder
2953 app.unloadAllTags(): Unload all tags
2954 app.saveDirectory(): Save folder
2955 app.revertFileModifications(): Revert
2956 app.importTags(tag, path, fmtIdx): Import file
2957 app.importFromTags(tag, source, extraction): Import from tags
2958 app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
2959 app.downloadImage(url, allFilesInDir): Download image
2960 app.exportTags(tag, path, fmtIdx): Export file
2961 app.writePlaylist(): Write playlist
2962 app.getPlaylistItems(path): Get items of a playlist
2963 app.setPlaylistItems(path, items): Set items of a playlist
2964 app.selectAllFiles(): Select all
2965 app.deselectAllFiles(): Deselect
2966 app.firstFile([select], [onlyTaggedFiles]): To first file
2967 app.nextFile([select], [onlyTaggedFiles]): To next file
2968 app.previousFile([select], [onlyTaggedFiles]): To previous file
2969 app.selectCurrentFile([select]): Select current file
2970 app.selectFile(path, [select]): Select a specific file
2971 app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
2972 app.requestExpandFileList(): Expand all
2973 app.applyFilenameFormat(): Apply filename format
2974 app.applyTagFormat(): Apply tag format
2975 app.applyTextEncoding(): Apply text encoding
2976 app.numberTracks(nr, total, tag, [options]): Number tracks
2977 app.applyFilter(expr): Filter
2978 app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
2979 app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
2980 app.getFilenameFromTags(tag): Filename from tags
2981 app.getTagsFromFilename(tag): Filename to tags
2982 app.getAllFrames(tag): Get object with all frames
2983 app.getFrame(tag, name): Get frame
2984 app.setFrame(tag, name, value): Set frame
2985 app.getPictureData(): Get data from picture frame
2986 app.setPictureData(data): Set data in picture frame
2987 app.copyToOtherTag(tag): Tags to other tags
2988 app.copyTags(tag): Copy
2989 app.pasteTags(tag): Paste
2990 app.removeTags(tag): Remove
2991 app.playAudio(): Play
2992 app.readConfig(): Read configuration
2993 app.applyChangedConfiguration(): Apply configuration
2994 app.dirName: Folder name
2995 app.selectionInfo.fileName: File name
2996 app.selectionInfo.filePath: Absolute file path
2997 app.selectionInfo.detailInfo: Format details
2998 app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
2999 app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
3000 app.selectionInfo.formatString(tag, format): Substitute codes in format string
3001 app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
3002 select a file
3003 app.selectDirName(caption, dir): Open file dialog to select a folder
3004 For asynchronous operations, callbacks can be connected to signals.
3006 function automaticImport(profile) {
3008 function onAutomaticImportFinished() {
3009 app.batchImporter.finished.disconnect(onAutomaticImportFinished)
3010 }
3011 app.batchImporter.finished.connect(onAutomaticImportFinished)
3012 app.batchImport(profile, tagv2)
3013 }
3014 function renameDirectory(format) {
3016 function onRenameActionsScheduled() {
3017 app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
3018 app.performRenameActions()
3019 }
3020 app.renameActionsScheduled.connect(onRenameActionsScheduled)
3021 app.renameDirectory(tagv2v1, format, false)
3022 }
3023 Configuration Objects
3025 The different configuration sections are accessible via methods of
3026 configs. Their properties can be listed in the QML console.
3027 script.properties(configs.networkConfig())
3029 Properties can be set:
3031 configs.networkConfig().useProxy = false
3033 configs.batchImportConfig()
3037 configs.exportConfig()
3038 configs.fileConfig()
3039 configs.filenameFormatConfig()
3040 configs.filterConfig()
3041 configs.findReplaceConfig()
3042 configs.guiConfig()
3043 configs.importConfig()
3044 configs.mainWindowConfig()
3045 configs.networkConfig()
3046 configs.numberTracksConfig()
3047 configs.playlistConfig()
3048 configs.renDirConfig()
3049 configs.tagConfig()
3050 configs.tagFormatConfig()
3051 configs.userActionsConfig()
3052
3054 Urs Fleisch <ufleisch at users.sourceforge.net>
3055 Software development
3056
3058 Copyright © 2021 Urs Fleisch
3059 FDL
3061
3064 1. gnudb.org
3065 http://gnudb.org
3066 2. MusicBrainz
3068 http://musicbrainz.org
3069 3. Discogs
3071 http://discogs.com
3072 4. Amazon
3074 http://www.amazon.com
3075 5. ID3 specification
3077 http://id3.org/id3v2.4.0-frames
3078 6. SYLT Editor
3080 http://www.compuphase.com/software_sylteditor.htm
3081 7. www.gnudb.org
3083 http://www.gnudb.org
3084 8. Discogs
3086 https://www.discogs.com/
3087 9. freedb.org
3089 http://freedb.org
3090 10. ID3 tag version 2.3.0
3092 http://id3.org/id3v2.3.0
3093 11. ID3 tag version 2.4.0 - Main Structure
3095 http://id3.org/id3v2.4.0-structure
3096 12. LyricWiki
3098 http://www.lyricwiki.org
3099 13. Google
3101 http://www.google.com
3102 14. id3lib
3104 http://id3lib.sourceforge.net
3105 15. libogg
3107 http://xiph.org/ogg/
3108 16. libvorbis, libvorbisfile
3110 http://xiph.org/vorbis/
3111 17. libFLAC++ and libFLAC
3113 http://flac.sourceforge.net
3114 18. TagLib
3116 http://taglib.github.io/
3117 19. mp4v2
3119 http://code.google.com/p/mp4v2
3120 20. Chromaprint
3122 http://acoustid.org/chromaprint
3123 21. libav
3125 http://libav.org/
3126 22. FDL
3128 http://www.gnu.org/licenses/licenses.html#FDL
3129 23. GPL
3131 http://www.gnu.org/licenses/licenses.html#GPL
3132 24. Qt(TM)
3134 https://www.qt.io
3135 25. KDE
3137 http://www.kde.org
31383.8.6 2021-03-18 KID3(1)