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