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 When Select file on play is activated, the currently played
240 track is automatically selected in the file list.
241 Edit Playlist
244 A playlist can be created empty or containing the tracks of a
245 folder, see Create Playlist. The playlist file created in such a
246 way can be edited by double click or using Edit from the file list
247 context menu. A dialog with the entries of the playlist is shown.
248 It is possible to open multiple playlists simultaneously.
249 New entries can be added by drag and drop from the file list, a
251 file manager or another playlist. If an entry is dragged from
252 another playlist, it will be moved or copied depending on the
253 system. To invoke the other operation, respectively, the Shift,
254 Ctrl or Alt (to copy instead of move on macOS®) key has to be
255 pressed. Reordering entries within the playlist is also possible
256 via drag and drop. Alternatively, entries can be moved using the
257 keyboard shortcuts Ctrl+Shift+Up and Ctrl+Shift+Down (on macOS®
258 Command has to be pressed instead of Ctrl). An entry can be removed
259 using the Delete key.
260 Please note the following: To drag entries from the file list, they
262 have to be held at the left side (near the icons), the same gesture
263 at the right side will perform a multi selection, such an action is
264 hereby still easily possible.
265 When a playlist has been modified, the changes can be stored using
267 Save or discarded using Cancel. When the window is closed, a
268 confirmation prompt is shown if there are unsaved changes.
269 Tracks selected in a playlist will be automatically selected in the
271 file list, thereby making it possible to edit their tags.
272 To execute actions on a playlist, its file must be selected in the
274 file list. Edit from the context menu will lead to the dialog
275 described in this section, and Play will start the media player
276 with the tracks from the playlist. User actions can act on
277 playlists, for example Export Playlist Folder, which copies the
278 files from a playlist into a folder.
279 Folder List
281 The folder list contains the names of the folders in the opened
282 folder, as well as the current (.) and the parent (..) folder. It
283 allows one to quickly change the folder without using the Open
284 command or drag and drop.
285 Column visibility, order and sorting can be configured as described
287 in the section about the file list.
288 File
290 Shows information about the encoding (MP3, Ogg, Opus, DSF, FLAC,
291 MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV,
292 AIFF), bit rate, sample rate, channels and the length of the file.
293 The Name line edit contains the name of the file (if only a single
295 file is selected). If this name is changed, the file will be
296 renamed when the Save command is used.
297 The Format combo box and line edit contains the format to be used
299 when the filename is generated from the first or the second tag.
300 The filename can contain arbitrary characters, even a folder part
301 separated by a slash from the file name, but that folder must
302 already exist for the renaming to succeed. The following special
303 codes are used to insert tag values into the filename:
304 • %s %{title} Title (Song)
306 • %a %{artist} Artist
308 • %l %{album} Album
310 • %c %{comment} Comment
312 • %y %{year} Year
314 • %t %{track} Track (e.g. 01)
316 • %t %{track.n} Track with field width n (e.g. 001 for
318 %{track.3})
319 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
321 • %g %{genre} Genre
323 • %{ignore} Ignored when generating tags from the file name
325 The format codes are not restricted to the examples given above.
327 Any frame name can be used, for instance unified frame names like
328 %{albumartist}, %{discnumber.1}, %{bpm} or format specific names
329 like %{popm}.
330 It is possible to prepend and append strings to the replacement for
332 a format code by adding them in double quotes inside the curly
333 braces of a format code. These strings will only be put into the
334 resulting string if the format code yields a nonempty value. For
335 example, if the file name shall both contain the title and the
336 subtitle, one could use %{title} [%{subtitle}] in the format
337 string. But this would result in a string ending with [] if no
338 subtitle frame exists for a file. In order to omit the brackets if
339 no subtitle is present, %{title}%{" ["subtitle"]"} shall be used
340 instead. This will omit the brackets, the leading space and the
341 subtitle if not subtitle exists.
342 The list of available formats can be edited in the dialog which
344 appears when clicking the Filename from tag button in the File tab
345 of the settings.
346 A second Format combo box (with arrow down) is used to generate the
348 tags from the filename. If the format of the filename does not
349 match this pattern, a few other commonly used formats are tried.
350 Some commonly used filename formats are already available in the
352 combo box, but it is also possible to type in some special format
353 into the line edit.
354 The list of available formats can be edited in the dialog which
356 appears when clicking the Tag from filename button in the File tab
357 of the settings.
358 Internally, a regular expression is built from the format codes. If
360 advanced regular expressions are required, the format to generate
361 the tags from the filenames can be given as a complete regular
362 expression with captures which are preceded by the format codes,
363 e.g. to extract the track numbers without removal of leading
364 zeros, a format like "/%{track}(\d+) %{title}(.*)" could be used.
365 From: Tag 1, Tag 2: Sets the filename using the selected format and
367 the first tag or the second tag, respectively.
368 To: Tag 1, Tag 2: The tags are set from the filename. First, the
370 format specified in Format is used. If the existing filename does
371 not match this format, the following formats are tried:
372 • Artist - Album/Track Song
374 • Album/Track - Artist - Song
376 • /Artist - Album - Track - Song
378 • Album/Artist - Track - Song
380 • Album/Artist - Song
382 • Artist/Album/Track Song
384 If a single file is selected, the GUI controls are filled with the
386 values extracted from the filename. If multiple files are selected,
387 the tags of the files are directly set according to the filenames.
388 Tag 1
390 The line edit widgets for Title, Artist, Album, Comment, Date,
391 Track Number and Genre are used to edit the corresponding value in
392 the first tag of the selected files. The value will be changed when
393 the file selection is altered or before operations like Save and
394 Quit and when the corresponding check box at the left of the field
395 name is checked. This is useful to change only some values and
396 leave the other values unchanged.
397 If a single file is selected, all check boxes are checked and the
399 line edit widgets contain the values found in the tags of this
400 file. If a tag is not found in the file, the corresponding empty
401 value is displayed, which is an empty string for the Title, Artist,
402 Album and Comment line edits, 0 for the numerical Date and Track
403 Number edits and an empty selected value for the Genre combo box.
404 The values can be changed and if the corresponding check box is
405 checked, they will be set for the selected file after the selection
406 is changed. The file is then marked as modified by a disk symbol in
407 the file listbox but remains unchanged until the Save command is
408 used.
409 If multiple files are selected, only the values which are identical
411 in all selected files are displayed. In all other controls, the
412 empty values as described above are displayed. All check boxes are
413 unchecked to avoid unwanted changes. If a value has to be set for
414 all selected files, it can be edited and the check box has to be
415 set. The values will be set for all selected files when the
416 selection is changed and can be saved using the Save command.
417 The check boxes also control the operation of most commands
419 affecting the tags, such as copy, paste and transfer between tags 1
420 and 2. To make it easier to use with multiple files where all check
421 boxes are unchecked, these commands behave in the same way when all
422 check boxes are checked and when all check boxes are unchecked.
423 From Tag 2: The tag 1 fields are set from the corresponding values
425 in tag 2. If a single file is selected, the GUI controls are filled
426 with the values from tag 2. If multiple files are selected, the
427 tags of the files are directly set.
428 Copy: The copy buffer is filled with the Tag 1 values. Only values
430 with checked check box will be used in subsequent Paste commands.
431 Paste: Pastes the values from the copy buffer into the GUI
433 controls.
434 Remove: This will set all GUI controls to their empty values which
436 results in removing all values. The saved file will then contain no
437 tag 1.
438 Tag 2
440 The GUI controls function in the same way as described for the Tag
441 1 section, but the size of the strings is not limited.
442 For the tag 2 Genre you can also use your own names besides the
444 genres listed in the combo box, just type the name into the line
445 edit.
446 The tag 2 cannot only contain the same values as the tag 1, the
448 format is built in a flexible way from several frames which are
449 themselves composed of several fields. The tag 2 table shows all
450 the frames which are available in the selected file.
451 Edit: This will open a window which allows one to edit all fields
453 of the selected frame. If multiple files are selected, the edited
454 fields are applied to all selected files which contain such a
455 frame.
456 Add: A requester to select the frame type will appear and a frame
458 of the selected type can be edited and added to the file. This
459 works also to add a frame to multiple selected files.
460 Delete: Deletes the selected frame in the selected files.
462 Drag album artwork here is shown if the file does not contain
464 embedded cover art. A picture can be added using drag and drop from
465 a browser or file manager and will be displayed here. Picture
466 frames can be edited or added by double clicking on this control.
467 Tag 3
469 Some files can have more than two tags, and a third tag section is
470 visible. The following file types can have such a Tag 3 section:
471 • MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0)
473 tag and in the third section an APE tag. Such APE tags are used
474 for replay gain information. In the Tag 3 section, this
475 information is visible, and the APE tag can be removed with the
476 Remove button.
477 • The RIFF INFO chunk of WAV files is available in the Tag 3
479 section because the Tag 1 section is dedicated to ID3v1.1 tags
480 and handles their restrictions. The Tag 2 is still used for
481 ID3v2.4.0 tags, which are also supported for WAV files, but
482 RIFF INFO chunks seem to be supported better.
483 • FLAC files normally use a Vorbis comment for their meta data.
485 However, there are FLAC files which have ID3v1 and ID3v2 tags,
486 which can be found in the Tag 1 and Tag 3 sections. ID3 tags in
487 FLAC files are only supported by TagLib, therefore the
488 OggFlacMetadata plugin has to be disabled in the Plugins tab of
489 the settings.
490 The GUI controls work in the same way as in the Tag 2 section.
492 Synchronized Lyrics and Event Timing Codes
494 For information synchronized with the audio data, a specific editor
495 is available. These frames are supported for ID3v2.3.0 and
496 ID3v2.4.0 tags. To add such a frame, the specific frame name has to
497 be selected in the list which appears when the Add button is
498 clicked - Synchronized Lyrics or Event Timing Codes, respectively.
499 The editor is the same for both types, for the event timing codes,
500 only a predefined set of events is available whereas for the
501 synchronized lyrics, text has to be entered. In the following,
502 editing synchronized lyrics is explained.
503 A file having an ID3v2 tag is selected, the lyrics editor is
505 entered using Add and selecting Synchronized Lyrics. For an
506 existing Synchronized Lyrics frame, it is selected and Edit is
507 clicked. The player is automatically opened with the current file
508 so that the file can be played and paused to synchronize lyrics.
509 The settings at the top of the SYLT editor normally do not have to
511 be changed. If the lyrics contains characters which are not present
512 in the Latin 1 character set, changing the text encoding to UTF16
513 (or UTF8 for ID3v2.4.0) is advisable. For English lyrics and
514 maximum compatibility, ISO-8859-1 should be used.
515 The Lyrics section has five buttons at the top. Add will add a new
517 time event in the table. The time is taken from the position of the
518 player, thus adding an entry while playing the track will add a
519 line for the currently played position. The events in the table
520 have to be chronologically ordered, therefore the row will be
521 inserted accordingly. Entries with an invalid time are treated
522 specially: If the currently selected row has an invalid time, its
523 time stamp will be replaced by the current time instead of adding a
524 new row. If the current time is not invalid, the first row with an
525 invalid time will be used if present. This behavior should
526 facilitate adding time stamps if the lyrics text is already in the
527 table but the time stamps are missing (which is the case when
528 importing unsynchronized lyrics). Note that the invalid time is
529 represented as 00:00.00, i.e. the same as the time at the absolute
530 beginning of the track, which is not invalid. To make a time
531 invalid, press the Delete key, or use Clear from the context menu.
532 New rows inserted using Insert row from the context menu or created
533 when importing unsynchronized lyrics with From Clipboard or Import
534 also contain invalid time stamps. Rows in the table can be deleted
535 by clicking the Delete button or using Delete rows from the context
536 menu.
537 Synchronized lyrics can be imported from a file using Import. The
539 expected format is simple or enhanced LRC. If the selected file
540 does not contain a square bracket in the first line, it is supposed
541 to be a simple text file with unsynchronized lyrics. The lines from
542 such a file are then imported having invalid time stamps. The time
543 information can be added using the Add button or by manual entry.
544 It is also possible to import lyrics via copy-paste using From
545 Clipboard. Synchronized lyrics can be written to LRC files using
546 Export. Note that only entries with valid time stamps will be
547 exported and that the entries will be sorted by time. Entries with
548 invalid time won't be stored in the SYLT frame either, so make sure
549 to include all timing information before leaving the dialog.
550 The ID3 specification[5] suggests a time stamp for each syllable.
552 However most players only support the granularity of a line or
553 sentence. To support both use cases, Kid3 follows the same
554 conventions as SYLT Editor[6]. Text which is entered into the table
555 is assumed to start a new line unless it starts with a space or a
556 hyphen. Exceptions to this rule are possible by starting a line
557 with an underscore ('_') to force continuation or a hash mark ('#')
558 to force a new line. These escape characters are not stored inside
559 the SYLT frame. Inside the SYLT frame, new lines start with a line
560 feed character (hex 0A) whereas continuations do not. When reading
561 SYLT frames, Kid3 checks if the first entry starts with a line
562 feed. If this is not the case, it is assumed that all entries are
563 new lines and that no syllable continuations are used.
564 While the track is played, the row associated with the current
566 playing position is highlighted, so that the correctness of the
567 synchronization information can be verified. If an offset has to be
568 added to one or more time stamps, this can be accomplished with the
569 Add offset context menu. Negative values can be used to reduce the
570 time. Using Seek to position in the context menu, it is possible to
571 set the playing position to the time of the selected row.
572 Recommended procedure to add new synchronized lyrics
574 • Get the unsynchronized lyrics, e.g. using Lyrics → Embed
576 Lyrics from the file list context menu.
577 • Copy the unsynchronized lyrics to the clipboard, just go to the
579 Lyrics row in the frame table and press Ctrl+C.
580 • Add a synchronized lyrics frame (Add..., Synchronized Lyrics,
582 OK), click From Clipboard.
583 • Now all lines from the unsynchronized lyrics are in the table,
585 all time stamps are invalid (0:0:0.00). You can delete empty
586 entries beforehand.
587 • Start playing the song by clicking the play button ► in the
589 play toolbar at the bottom of the main window.
590 • When the next lyrics line with invalid timestamp comes, click
592 Add or press Alt+A, the timestamp will be updated.
593 • Continue like this until all timestamps are set. If you missed
595 something, stop playback and clear the timestamps using the
596 Delete key or by selecting them and using Clear from the
597 context menu. To restart playback from a given timestamp, use
598 Seek to position from the context menu.
599 Chapters in MP4 Files
602 MP4 audiobooks typically have a .m4b extension and are rather large
603 because they contain all chapters in a single file. To navigate in
604 such files, they can contain chapter marks, which can be edited in
605 Kid3 in a pseudo "Chapters" frame using the same editor which is
606 used for synchronized lyrics. Note, however, that this feature is
607 only available with the Mp4v2Metadata plugin, so make sure that it
608 is activated and above the TaglibMetadata plugin in the Plugins tab
609 of the settings if you have to edit MP4 chapters.
610 The File Menu
612 File → Open... (Ctrl+O)
613 Opens a folder. All files matching the selected file name filter
614 will be displayed in the file listbox and the chosen file is
615 selected.
616 File → Open Recent
618 Opens a recently opened folder.
619 File → Open Folder... (Ctrl+D)
621 Opens a folder. All files matching the selected file name filter
622 will be displayed in the file listbox.
623 File → Reload (F5)
625 Reload folder. Modified files have to be saved before. Expanded
626 subfolders will be collapsed.
627 File → Save (Ctrl+S)
629 Saves all changed files in the folder. The changed files are
630 marked with a disk symbol in the file listbox. If any file names
631 have been changed, those files will be renamed.
632 File → Revert
634 Reverts the changes of one or multiple files. If no files are
635 selected in the file listbox, the changes of all files will be
636 reverted, else only the changes of the selected files are reverted.
637 File → Import...
639 The Import dialog can be used to import data directly from a
640 freedb.org server, from a MusicBrainz server, from Discogs, Amazon
641 or other sources of album track lists in textual format.
642 Import from a freedb.org server is possible using a dialog which
644 appears when From Server: gnudb.org is selected. The artist and
645 album name to search for can be entered in the two topmost fields,
646 the albums which match the query will be displayed when Find is
647 clicked and the results from www.gnudb.org[7] are received.
648 Importing the track data for an album is done by double-clicking
649 the album in the list. The freedb.org server to import from can be
650 selected as well as the CGI path. The imported data is displayed in
651 the preview table of the import dialog. When satisfied with the
652 displayed tracks, they can be imported by terminating the import
653 dialog with OK.
654 If you already have a search result open in the web browser, you
656 can enter the URL into the first search field. The result will then
657 appear in the album list and can be directly imported into Kid3.
658 A search on the Discogs server can be performed using Discogs. As
660 in the gnudb.org dialog, you can enter artist and album and then
661 choose from a list of releases. A Token can be entered to use the
662 RESTful Discogs API instead of their web interface, which is often
663 changed, thereby breaking the import parser. You have to register
664 for an account on Discogs[8] and then generate a token on their web
665 site (Settings/Developers, Generate new token). Don't forget to
666 Save Settings after entering the token in order to use it in
667 subsequent requests too. If Standard Tags is marked, the standard
668 information is imported, e.g. artist, album, and title. If
669 Additional Tags is marked, more information is imported if
670 available, e.g. performers, arrangers, or the publisher. If Cover
671 Art is marked, cover art will be downloaded if available.
672 A search on Amazon can be performed using Amazon. As in the
674 gnudb.org dialog, you can enter artist and album and then choose
675 from a list of releases. If Additional Tags is marked, more
676 information is imported if available, e.g. performers, arrangers,
677 or the publisher. If Cover Art is marked, cover art will be
678 downloaded if available.
679 You can search in the same way in the release database of
681 MusicBrainz using From MusicBrainz Release. The workflow is the
682 same as described for From gnudb.org.
683 Import from a MusicBrainz server is possible using the dialog which
685 appears when From MusicBrainz Fingerprint is selected. The Server
686 can be selected as in the freedb import dialog. Below is a table
687 displaying the imported track data. The right column shows the
688 state of the MusicBrainz query, which starts with "Pending" when
689 the dialog is opened. Then the fingerprint is looked up and if it
690 does not yield a result, another lookup using the tags in the file
691 is tried. Thus it can be helpful for a successful MusicBrainz query
692 to store known information (e.g. artist and album) in the tags
693 before the import. If a result was found, the search ends in the
694 state "Recognized", otherwise nothing was found or multiple
695 ambiguous results and one of them has to be selected by the user.
696 OK and Apply use the imported data, Cancel closes the dialog. The
697 closing can take a while since the whole MusicBrainz machinery has
698 to be shut down.
699 For the import of textual data, From File/Clipboard opens a
701 subdialog, where several preconfigured import formats are
702 available. The first two, "CSV unquoted" and "CSV quoted" can be
703 used to import data which was exported by the Export dialog. The
704 CSV data can be edited with a spreadsheet, and shall be written
705 using tabs as delimiters. Import should then be possible using "CSV
706 quoted", which is more flexible than "CSV unquoted". However, its
707 fields cannot contain any double quotes. If you only export from
708 Kid3 and import later, "CSV unquoted" can be used as a simple
709 format for this purpose. Note that there are also "Export CSV" and
710 "Import CSV" commands in the context menu of the file list, which
711 use scripts to export and import CSV data in a more complete,
712 powerful and flexible way.
713 The next format, "freedb HTML text", can be used to copy
715 information from an HTML page of freedb.org[9]. Search an album in
716 freedb and if the desired information is displayed in the web
717 browser, copy the contents to the clipboard. Then click the From
718 Clipboard button and the imported tracks will be displayed in the
719 preview table at the top of the dialog. If you are satisfied with
720 the imported data, terminate the dialog with OK, which will insert
721 the data into the tags of the current folder. The destination (Tag
722 1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box. The
723 files in the current folder should be in the correct track order to
724 get their tags assigned. This is the case if they are numbered.
725 The next preconfigured import format, "freedb HTML source", can be
727 used, if the data is available as an HTML document. Import is
728 possible using the From File button, which opens a file selector,
729 or copying its contents from an editor and then importing from
730 clipboard. This format can be useful for offline import, although
731 the HTML document could also be opened in a browser and then be
732 imported in the first format via the clipboard.
733 More preconfigured formats, e.g. "Track Title Time", are
735 available. An empty custom format can be created with Add to be set
736 by the user. Two lines below the format name can be set with a
737 regular expression to capture the fields from the import text. The
738 first regular expression will be parsed once per document to gather
739 per-album data such as artist, album, year and genre. The second
740 line is tried to match from the start of the document to the end to
741 get track data, usually number and title. The regular expressions
742 include all the features offered by Qt(TM), which is most of the
743 what Perl offers. Bracketing constructs "(..)" create capture
744 buffers for the fields to import and are preceded by Kid3 specific
745 codes to specify which field to capture. The codes are the same as
746 used for the filename format, besides the codes listed below, any
747 frame name is possible:
748 • %s %{title} Title (Song)
750 • %a %{artist} Artist
752 • %l %{album} Album
754 • %c %{comment} Comment
756 • %y %{year} Year
758 • %t %{track} Track
760 • %g %{genre} Genre
762 • %d %{duration} Duration
764 For example, a track regular expression (second line) to import
766 from an .m3u playlist could be
767 "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]". All formats can
768 be changed by editing the regular expressions and the name and then
769 clicking Save Settings. They will be stored in the kid3rc file in
770 the configuration folder. This file can be directly edited to have
771 more import formats or it can be deleted to revert to the default
772 formats. Formats can be deleted using Remove.
773 Accuracy shows an estimation of how good the imported information
775 matches the given tracks. It uses track durations or file names to
776 calculate the level of similarity in percent. Cover Art shows the
777 URL of the album cover image which will be downloaded.
778 To check whether the imported tracks match the current set of
780 files, the duration of the imported tracks can be compared with the
781 duration of the files. This option can be enabled with the check
782 box Check maximum allowable time difference (sec): and the maximum
783 tolerated difference in time can be set in seconds. If a mismatch
784 in a length is detected, the length is displayed with a red
785 background in the preview table.
786 If the files are ordered differently than the imported tracks,
788 their assigned tracks have to be changed. This task can be
789 facilitated using the Match with option with the buttons Length,
790 Track, and Title, which will reorder the tracks according to the
791 corresponding field. To correct the assignments manually, a track
792 can be dragged with the left mouse button and the Ctrl key hold
793 down, and then dropped at the new location.
794 When the import dialog is opened, it contains the actual contents
796 of the tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be
797 selected using the Destination combo box. The button on the right
798 of this combo box can be used to revert the table to the current
799 contents of the tags. The check boxes in the first table column can
800 be used to select the tracks which are imported. This can be useful
801 if a folder contains the tracks of both CDs of a double CD and only
802 the tracks of the second CD have to be imported.
803 To identify the tracks which are imported, it is possible to
805 display the file names or the full paths to the files using the
806 context menu of the table header. The values in the import table
807 can be edited. The revert-button to the right of the Destination
808 combo box can be used to restore the contents of the tags, which
809 can also be useful after changing the Destination.
810 Almost all dialogs feature a Save Settings button, which can be
812 used to store the dialog specific settings and the window size
813 persistently.
814 From Tags leads to a subdialog to set tag frames from the contents
816 of other tag frames. This can be used to simply copy information
817 between tags or extract a part from one frame and insert it in
818 another.
819 As in the import from file/clipboard dialog, there are freely
821 configurable formats to perform different operations. Already
822 preconfigured are formats to copy the Album value to Album Artist,
823 Composer or Conductor, and to extract the Track Number from Title
824 fields which contain a number. There is also a format to extract a
825 Subtitle from a Title field.
826 The following example explains how to add a custom format, which
828 sets the information from the Subtitle field also in the Comment
829 field. Create a new format using Add button and set a new name,
830 e.g. "Subtitle to Comment". Then enter "%{subtitle}" in Source and
831 "%{comment}(.*)" for Extraction and click Save Settings.
832 The expression in Source can contain format codes for arbitrary tag
834 frames, multiple codes can be used to combine the contents from
835 different frames. For each track, a text is generated from its tags
836 using the Source format, and the regular expression from Extraction
837 is applied to this text to set new values for the tags. Format
838 codes are used before the capturing parentheses to specify the tag
839 frame where the captured text shall be stored. It works in the same
840 way as for the import from file/clipboard.
841 Import from Tags... is also directly available from the File menu.
843 The difference between these two functions is that the import
844 dialog subdialog operates on all files of the current folder
845 whereas the menu function operates on the selected files (which can
846 be in different folders). The menu function supports an additional
847 code "%{__return}" to return the extracted value, which can be
848 useful with the CLI and QML interfaces.
849 File → Import from gnudb.org...
851 Import from a freedb.org server using gnudb.org album search. This
852 menu item opens the same import dialog as Import..., but opens
853 directly the gnudb.org dialog.
854 File → Import from Discogs...
856 Import from the Discogs server. This menu item opens the same
857 import dialog as Import..., but opens directly the From Discogs
858 dialog.
859 File → Import from Amazon...
861 Import from Amazon. This menu item opens the same import dialog as
862 Import..., but opens directly the From Amazon dialog.
863 File → Import from MusicBrainz Release...
865 Import from the MusicBrainz release database. This menu item opens
866 the same import dialog as Import..., but opens directly the From
867 MusicBrainz Release dialog.
868 File → Import from MusicBrainz Fingerprint...
870 Import from a MusicBrainz server. This menu item opens the same
871 import dialog as Import..., but opens directly the From MusicBrainz
872 Fingerprint dialog.
873 File → Import from Tags...
875 Like From Tags, but the import is applied to the selected files.
876 File → Automatic Import...
878 Automatic Import allows one to import information for multiple
879 albums from various web services. If folders are selected in the
880 file list, track data for the selected folders will be imported. If
881 no folder is selected, all folders in the file list will be
882 imported.
883 The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using
885 the Destination combo box.
886 Profiles determine which servers will be contacted to fetch album
888 information. Some profiles are predefined (All, MusicBrainz,
889 Discogs, Cover Art), custom profiles can be added using the Add
890 button at the right of the Profile combo box.
891 The table below shows the servers which will be used when importing
893 album information using the selected profile. The import process
894 for an album is finished if all required information has been
895 found, so the order of the rows in the table is important. It can
896 be changed using the Move Up and Move Down buttons. Edit can be
897 used to change an existing entry. The Server selection offers the
898 same servers as can be used in the import functions. Standard
899 Tags, Additional Tags, Cover Art determine the information which
900 shall be fetched from the server. Finally, Accuracy is the minimum
901 accuracy which must be achieved to accept the imported data. If the
902 accuracy is insufficient, the next server in the list will be
903 tried. The same dialog containing the server properties appears
904 when Add is clicked to add a new server entry. Existing entries can
905 be deleted using Remove.
906 To launch an automatic batch import with the selected profile,
908 click Start. Details about the running import are displayed at the
909 top of the dialog. The process can be aborted with the Abort
910 button.
911 File → Browse Cover Art...
914 The Browse Cover Art dialog helps to find album cover art.
915 Artist/Album is filled from the tags if possible. Source offers a
916 variety of websites with album cover art. The URL with artist and
917 album as parameters can be found beneath the name. URL-encoded
918 values for artist and album can be inserted using "%u{artist}" and
919 "%u{album}", other values from the tags are possible too, as
920 described in Configure Kid3, User Actions. More sources can be
921 entered after the entry "Custom Source" by replacing "Custom
922 Source" with the source's name, pressing Enter, then inserting the
923 URL and finally pressing Save Settings. The resulting browser
924 command is displayed at the top of the dialog and can be started by
925 clicking Browse. The browser, which can be configured in the
926 settings, is started with the selected source. A cover image can
927 then be dragged from the browser into the Kid3 window and will be
928 set in the picture frame of the selected files.
929 Because not all browsers support drag and drop of images and the
931 pictures on websites often have a URL, in such cases Kid3 will
932 receive the URL and not the picture. If the URL points to a
933 picture, it will be downloaded. However, if the URL refers to some
934 other web resource, it has to be translated to the corresponding
935 picture. Such mappings are defined in the table URL extraction. The
936 left column Match contains a regular expression which is compared
937 with the URL. If it matches, the captured expressions in
938 parentheses are inserted into the pattern of the right Picture URL
939 column (at the positions marked with \1 etc.). The replaced regular
940 expression contains the URL of the picture. By this means cover art
941 can be imported from Amazon, Google Images, etc. using drag and
942 drop. It is also possible to define your own mappings.
943 File → Export...
945 The Export Dialog is used to store data from the tags in a file or
946 the clipboard. The editor at the top shows a preview of the data to
947 export. If the export data contain tabulator characters, the export
948 is displayed in a table. The data will be generated from the tags
949 in the current folder according to the configured format.
950 The format settings are similar as in the Import dialog: The
952 topmost field contains the title (e.g. "CSV unquoted"), followed
953 by the header, which will be generated at the begin of the file.
954 The track data follows; it is used for every track. Finally, the
955 trailer can be used to generate some finishing text.
956 The format fields do not contain regular expressions as in the
958 Import dialog, but only output format expressions with special
959 %-expressions, which will be replaced by values from the tags. The
960 whole thing works like the file name format, and the same codes are
961 used plus some additional codes. Not only the codes listed below
962 but all tag frame names can be used.
963 • %s %{title} Title (Song)
965 • %a %{artist} Artist
967 • %l %{album} Album
969 • %c %{comment} Comment
971 • %y %{year} Year
973 • %t %{track} Track (e.g. 01)
975 • %t %{track.n} Track with field width n (e.g. 001 for
977 %{track.3})
978 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
980 • %g %{genre} Genre
982 • %f %{file} File name
984 • %p %{filepath} Path
986 • %{modificationdate} Modification date
988 • %{creationdate} Creation date
990 • %u %{url} URL
992 • %{dirname} Folder name
994 • %d %{duration} Duration in minutes:seconds
996 • %D %{seconds} Duration in seconds
998 • %n %{tracks} Number of tracks of the album
1000 • %e %{extension} File extension
1002 • %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1004 existing)
1005 • %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1007 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
1008 existing)
1009 • %b %{bitrate} Bit rate in kbit/s
1011 • %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
1013 • %r %{samplerate} Sample rate in Hz
1015 • %m %{mode} Channel mode (Stereo or Joint Stereo)
1017 • %h %{channels} Number of channels (1 or 2)
1019 • %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1021 MPC, APE, ASF, AIFF, WAV)
1022 A few formats are predefined. "CSV unquoted" separates the fields
1024 by tabs. Data in this format can be imported again into Kid3 using
1025 the import format with the same name. "CSV quoted" additionally
1026 encloses the fields by double quotes, which eases the import into
1027 spreadsheet applications. However, the fields shall not contain any
1028 double quotes when this format is used. "Extended M3U" and
1029 "Extended PLS" generate playlists with extended attributes and
1030 absolute path names. "HTML" can be used to generate an HTML page
1031 with hyperlinks to the tracks. "Kover XML" creates a file which can
1032 be imported by the cover printing program Kover. "Technical
1033 Details" provides information about bit rate, sample rate,
1034 channels, etc. Finally, "Custom Format" is left empty for
1035 definition of a custom format. You can define more formats of your
1036 own by adding lines in the file kid3rc in the configuration folder.
1037 The other formats can be adapted to your needs.
1038 The Source of the tags to generate the export data (Tag 1 or Tag 2)
1040 can be selected with a combo box. Pushing To File or To Clipboard
1041 stores the data in a file or on the clipboard. OK and Cancel close
1042 the dialog, whereas OK accepts the current dialog settings.
1043 File → Create Playlist...
1045 Creates a playlist. The format and contents of the playlist can be
1046 set by various options.
1047 The name of the playlist can be the Same as folder name or use a
1049 Format with values from the tags, e.g. "%{artist} - %{album}" to
1050 have the artist and album name in the playlist file name. The
1051 format codes are the same as for Export. The list of available
1052 formats can be edited in the Format section of the Files tab in the
1053 settings. Create new empty playlist will make an empty playlist
1054 with the given name. The extension depends on the playlist format.
1055 The location of the generated playlist is determined by the
1057 selection of the Create in combo box.
1058 Current folder
1060 The playlist is created in the current folder and contains only
1061 files of the current folder. The current folder is the folder
1062 where the current file is located. If multiple files are
1063 selected, the current file is probably the last selected file.
1064 Every folder
1066 A playlist is created in every folder which contains listed
1067 files, and each playlist contains the files of that folder.
1068 Top-level folder
1070 Only one playlist is created in the top-level folder (i.e. the
1071 folder of the file list) and it contains the listed files of
1072 the top-level folder and all of its sub-folders.
1073 The Format of the playlist can be M3U, PLS or XSPF.
1075 If Include only the selected files is checked, only the selected
1077 files will be included in the playlist. If a folder is selected,
1078 all of its files are selected. If this check box is not activated,
1079 all audio files are included in the playlist.
1080 Sort by file name selects the usual case where the files are
1082 ordered by file name. With Sort by tag field, it is possible to
1083 sort by a format string with values from tag fields. For instance,
1084 "%{track.3}" can be used to sort by track number (the ".3" is used
1085 to get three digits with leading zeros because strings are used for
1086 sorting). It is also possible to use multiple fields, e.g.
1087 "%{genre}%{year}" to sort using a string composed of genre and
1088 year.
1089 The playlist entries will have relative or absolute file paths
1091 depending on whether Use relative path for files in playlist or Use
1092 full path for files in playlist is set.
1093 When Write only list of files is set, the playlist will only
1095 contain the paths to the files. To generate an extended playlist
1096 with additional information, a format string can be set using the
1097 Write info using control.
1098 File → Quit (Ctrl+Q)
1100 Quits the application.
1101 The Edit Menu
1103 Edit → Select All (Alt+A)
1104 Selects all files.
1105 Edit → Deselect (Ctrl+Shift+A)
1107 Deselects all files.
1108 Edit → Select All in Folder
1110 Selects all files of the current folder.
1111 Edit → Previous File (Alt+Up)
1113 Selects the previous file.
1114 Edit → Next File (Alt+Down)
1116 Selects the next file.
1117 Edit → Find... (Ctrl+F)
1119 Find strings in the file names and the tags. The Find dialog is a
1120 subset of the Replace dialog, which is described below.
1121 Edit → Replace... (Ctrl+R)
1123 This function opens a dialog to find and replace strings in the
1124 file names and the tags. The set of frames where the search is
1125 performed can be restricted by deactivating the Select all check
1126 box and selecting the frames which shall be searched. There are
1127 also search options available to search backwards, case
1128 sensitively, and to use regular expressions.
1129 Depending on the number of files, the search might take some time,
1131 therefore it can be aborted by closing the dialog.
1132 The Tools Menu
1134 Tools → Apply Filename Format
1135 When Automatically apply format is switched off for the filename
1136 format in the configuration dialog, this menu item can be used to
1137 apply the configured format to the names of the selected files.
1138 This can also be used to check whether the file names conform with
1139 the configured format by applying the format to all saved files and
1140 then checking if any files were changed (and therefore marked with
1141 a disk symbol in the file listbox).
1142 Tools → Apply Tag Format
1144 When Automatically apply format is switched off for the tag format
1145 in the configuration dialog, this menu item can be used to apply
1146 the configured format to the tags of the selected files. This can
1147 also be used to check whether the tags conform with the configured
1148 format by applying the format to all saved files and then checking
1149 if any files were changed (and therefore marked with a disk symbol
1150 in the file listbox).
1151 Tools → Apply Text Encoding
1153 Sets the Text encoding selected in Settings → Configure Kid3... →
1154 Tags section → Tag 2 tab for all selected files. If UTF8 is
1155 selected, UTF16 will be used for ID3v2.3.0 tags because UTF8 is not
1156 supported for this format.
1157 Tools → Rename Folder...
1159 This dialog offers the possibility to automatically rename the
1160 currently open folder according to the tags in the files. Several
1161 formats are preconfigured to include information about artist,
1162 album and year in the folder name. It is also possible to set a
1163 custom format and Edit the list of available formats. The following
1164 special codes are used to insert tag values into the folder name:
1165 • %s %{title} Title (Song)
1167 • %a %{artist} Artist
1169 • %l %{album} Album
1171 • %c %{comment} Comment
1173 • %y %{year} Year
1175 • %t %{track} Track (e.g. 01)
1177 • %t %{track.n} Track with field width n (e.g. 001 for
1179 %{track.3})
1180 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
1182 • %g %{genre} Genre
1184 • %{dirname} Folder name (e.g. %{year" "}%{dirname} will prepend
1186 the year to the current folder name)
1187 • %{max-year} The maximum year value found for this folder, can
1189 also be used with other codes than "year"
1190 • %{min-year} The minimum year value found for this folder
1192 • %{unq-year} The unique year value found for this folder or
1194 empty if not unique
1195 If a folder separator "/" is found in the format, multiple folders
1197 are created. If you want to create a new folder instead of renaming
1198 the current folder, in the Action combo box select Create Folder
1199 instead of Rename Folder. The Source of the tag information can be
1200 chosen between Tag 1 and Tag 2, Tag 1 and Tag 2. A preview for the
1201 rename operation performed on the first file can be seen in the
1202 From and To sections of the dialog.
1203 Multiple folders can be renamed by selecting them.
1205 Tools → Number Tracks...
1207 If the track numbers in the tags are not set or have the wrong
1208 values, this function can number the tracks automatically in
1209 ascending order. The start number can be set in the dialog. If only
1210 part of the tracks have to be numbered, they must be selected.
1211 When Total number of tracks is checked, the number of tracks will
1213 also be set in the tags.
1214 It is possible to number the tracks over multiple folders. The
1216 folders have to be expanded and selected.
1217 If Reset counter for each folder is checked, track numbering is
1219 restarted with the given number for each folder when multiple
1220 folders are selected.
1221 The number tracks dialog can also be used to format existing track
1223 numbers without changing the values when the check box left to
1224 Start number is deactivated. The total number of tracks will be
1225 added if the corresponding check box is active, which can be used
1226 to set the total for all selected tracks. If only formatting of the
1227 existing numbers is desired, this check box has to be deactivated
1228 too.
1229 Tools → Filter...
1231 The filter can be used to display only those files which match
1232 certain criteria. This is helpful if you want to organize a large
1233 collection and only edit those files which are not in the desired
1234 scheme. The expression defining which files to display uses the
1235 same format codes which are used in the file name format, import
1236 and export.
1237 • %s %{title} Title (Song)
1239 • %a %{artist} Artist
1241 • %l %{album} Album
1243 • %c %{comment} Comment
1245 • %y %{year} Year
1247 • %t %{track} Track (e.g. 01)
1249 • %t %{track.n} Track with field width n (e.g. 001 for
1251 %{track.3})
1252 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
1254 • %g %{genre} Genre
1256 • %f %{file} File name
1258 • %p %{filepath} Absolute path to file
1260 • %e %{extension} File extension
1262 • %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1264 existing)
1265 • %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1267 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
1268 existing)
1269 • %b %{bitrate} Bit rate in kbit/s
1271 • %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
1273 • %r %{samplerate} Sample rate in Hz
1275 • %m %{mode} Channel mode (Stereo or Joint Stereo)
1277 • %h %{channels} Number of channels (1 or 2)
1279 • %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1281 MPC, APE, ASF, AIFF, WAV)
1282 • %w %{marked} Marked, is 1 if the file is marked (e.g. because
1284 of truncation or standard violation), empty otherwise
1285 • %1a %1{artist}, ... Use the prefix 1 to get values of tag 1
1287 • %2a %2{artist}, ... Use the prefix 2 to get values of tag 2
1289 These codes are replaced with the values for the file, and the
1291 resulting strings can be compared with the following operations:
1292 • s1 equals s2: true if s1 and s2 are equal.
1294 • s1 contains s2: true if s1 contains s2, i.e. s2 is a substring
1296 of s1.
1297 • s matches re: true if s matches the regular expression re.
1299 True expressions are replaced by 1, false by 0. True values are
1301 represented by 1, true, on and yes, false values by 0, false, off
1302 and no. Boolean operations are not, and, or (in this order of
1303 precedence) and can be grouped by parentheses.
1304 Some filter rules are predefined and can serve as examples for your
1306 own expressions:
1307 All
1309 When the file list is filtered - this is shown by "[filtered]"
1310 in the window title - and all files shall be displayed again,
1311 the filtering can be reverted using this filter. It uses an
1312 empty expression, but a true value would have the same effect.
1313 Filename Tag Mismatch
1315 not (%{filepath} contains "%{artist} - %{album}/%{track}
1316 %{title}")
1317 Tests if the file path conforms with the file name format. This
1319 rule is automatically adapted if the file name format changes.
1320 No Tag 1
1322 %{tag1} equals ""
1323 Displays only files which do not have a tag 1.
1325 No Tag 2
1327 %{tag2} equals ""
1328 Displays only files which do not have a tag 2.
1330 ID3v2.3.0 Tag
1332 %{tag2} equals "ID3v2.3.0"
1333 Displays only files which have an ID3v2.3.0 tag.
1335 ID3v2.4.0 Tag
1337 %{tag2} equals "ID3v2.4.0"
1338 Displays only files which have an ID3v2.4.0 tag.
1340 Tag 1 != Tag 2
1342 not (%1{title} equals %2{title} and %1{album} equals %2{album}
1343 and %1{artist} equals %2{artist} and %1{comment} equals
1344 %2{comment} and %1{year} equals %2{year} and %1{track} equals
1345 %2{track} and %1{genre} equals %2{genre})
1346 Displays files with differences between tag 1 and tag2.
1348 Tag 1 == Tag 2
1350 %1{title} equals %2{title} and %1{album} equals %2{album} and
1351 %1{artist} equals %2{artist} and %1{comment} equals %2{comment}
1352 and %1{year} equals %2{year} and %1{track} equals %2{track} and
1353 %1{genre} equals %2{genre}
1354 Displays files with identical tag 1 and tag 2.
1356 Incomplete
1358 %{title} equals "" or %{artist} equals "" or %{album} equals
1359 "" or %{year} equals "" or %{tracknumber} equals "" or %{genre}
1360 equals ""
1361 Displays files with empty values in the standard tags (title,
1363 artist, album, date, track number, genre).
1364 No Picture
1366 %{picture} equals ""
1367 Displays only files which do not have a picture.
1369 Marked
1371 not (%{marked} equals "")
1372 Displays only files which are marked because they violate the
1374 ID3 standard, are truncated or the picture is too large.
1375 Custom Filter
1377 To add your own filter, select this entry. For instance, if you
1378 want to have a filter for artists starting with "The", replace
1379 "Custom Filter" with the name "The Bands" and press Enter. Then
1380 insert the following expression into the line edit:
1381 %{artist} matches "The.*"
1383 Then click Save Settings. Click Apply to filter the files. All
1385 files processed are displayed in the text view, with a "+" for
1386 those who match the filter and a "-" for the others. When
1387 finished, only the files with an artist starting with "The" are
1388 displayed, and the window title is marked with "[filtered]".
1389 Tools → Convert ID3v2.3 to ID3v2.4
1391 If there are any ID3v2.3 tags in the selected files, they will be
1392 converted to ID3v2.4 tags. Frames which are not supported by TagLib
1393 will be discarded. Only files without unsaved changes will be
1394 converted.
1395 Tools → Convert ID3v2.4 to ID3v2.3
1397 If there are any ID3v2.4 tags in the selected files, they will be
1398 converted to ID3v2.3 tags. Only files without unsaved changes will
1399 be converted.
1400 Tools → Play
1402 This opens a simple toolbar to play audio files. It contains
1403 buttons for the basic operations (Play/Pause, Stop playback,
1404 Previous Track, Next Track, Close), sliders for position and volume
1405 and a display of the current position. If multiple files are
1406 selected, the selected tracks are played, else all files will be
1407 played.
1408 The time displayed can be toggled between elapsed and remaining
1410 time by clicking on the display.
1411 The Settings Menu
1413 Settings → Show Toolbar
1414 Toggles displaying of the toolbar.
1415 Settings → Show Statusbar
1417 Toggles displaying of the statusbar, which displays longer actions
1418 such as opening or saving a folder.
1419 Settings → Show Picture
1421 Toggles displaying of the album cover art preview picture.
1422 Settings → Auto Hide Tags
1424 Empty tags are automatically hidden if this option is active. The
1425 File, Tag 1 and Tag 2 sections can be manually collapsed and
1426 expanded by clicking on the corresponding -/+ buttons.
1427 Settings → Configure Shortcut keys...
1429 Opens a dialog to assign keyboard shortcuts for most of the program
1430 functions. There are even functions without corresponding menu or
1431 button available, e.g. next file, previous file, select all.
1432 Settings → Configure Kid3...
1435 Opens the configuration dialog, which consists of pages for tags,
1436 files, user actions, and network settings.
1437 Tag specific options can be found on the Tags page, which is itself
1439 separated into four tabs for Tag 1, Tag 2, Tag 3, and All Tags.
1440 If Mark truncated fields is checked, truncated ID3v1.1 fields will
1442 be marked red. The text fields of ID3v1.1 tags can only have 30
1443 characters, the comment only 28 characters. Also the genre and
1444 track numbers are restricted, so that fields can be truncated when
1445 imported or transferred from ID3v2. Truncated fields and the file
1446 will be marked red, and the mark will be removed after the field
1447 has been edited.
1448 With Text encoding for ID3v1 it is possible to set the character
1450 set used in ID3v1 tags. This encoding is supposed to be ISO-8859-1,
1451 so it is recommended to keep this default value. However, there are
1452 tags around with different encoding, so it can be set here and the
1453 ID3v1 tags can then be copied to ID3v2 which supports Unicode.
1454 The check box Use track/total number of tracks format controls
1456 whether the track number field of ID3v2 tags contains simply the
1457 track number or additionally the total number of tracks in the
1458 folder.
1459 When Genre as text instead of numeric string is checked, all ID3v2
1461 genres will be stored as a text string even if there is a
1462 corresponding code for ID3v1 genres. If this option is not set,
1463 genres for which an ID3v1 code exists are stored as the number of
1464 the genre code (in parentheses for ID3v2.3). Thus the genre Metal
1465 is stored as "Metal" or "(9)" depending on this option. Genres
1466 which are not in the list of ID3v1 genres are always stored as a
1467 text string. The purpose of this option is improved compatibility
1468 with devices which do not correctly interpret genre codes.
1469 When WAV files with lowercase id3 chunk is checked, the RIFF chunk
1471 used to store ID3v2 tags in WAV files will be named "id3 " instead
1472 of "ID3 ". By default, Kid3 and other applications using TagLib
1473 accept both the lowercase and the uppercase variant when reading
1474 WAV files, but they use "ID3 " when writing ID3v2 tags to WAV
1475 files. As there exist other applications which only accept "id3 "
1476 (e.g. JRiver Media Center and foobar2000), this option can be used
1477 to create tags which can be read by such applications.
1478 When Mark standard violations is checked, ID3v2 fields which
1480 violate the standard will be marked red. Details about the
1481 violation are shown in a tooltip:
1482 • Must be unique
1484 • New line is forbidden
1486 • Carriage return is forbidden
1488 • Owner must be non-empty
1490 • Must be numeric
1492 • Must be numeric or number/total
1494 • Format is DDMM
1496 • Format is HHMM
1498 • Format is YYYY
1500 • Must begin with a year and a space character
1502 • Must be ISO 8601 date/time
1504 • Must be musical key, 3 characters, A-G, b, #, m, o
1506 • Must have ISO 639-2 language code, 3 lowercase characters
1508 • Must be ISRC code, 12 characters
1510 • Must be list of strings separated by '|'
1512 • Has excess white space
1514 The ID3 standard documents are available online:
1516 • ID3 tag version 2.3.0[10]
1518 • ID3 tag version 2.4.0 - Main Structure[11]
1520 • ID3 tag version 2.4.0 - Native Frames[5]
1522 Text encoding defines the default encoding used for ID3v2 frames
1524 and can be set to ISO-8859-1, UTF16, or UTF8. UTF8 is not valid
1525 for ID3v2.3.0 frames; if it is set, UTF16 will be used instead. For
1526 ID3v2.4.0 frames, all three encodings are possible.
1527 Version used for new tags determines whether new ID3v2 tags are
1529 created as version 2.3.0 or 2.4.0.
1530 Track number digits is the number of digits in Track Number fields.
1532 Leading zeros are used to pad. For instance, with a value of 2 the
1533 track number 5 is set as "05".
1534 The combo box Comment field name is only relevant for Ogg/Vorbis
1536 and FLAC files and sets the name of the field used for comments.
1537 Different applications seem to use different names, "COMMENT" for
1538 instance is used by XMMS, whereas Amarok uses "DESCRIPTION".
1539 The format of pictures in Ogg/Vorbis files is determined by Picture
1541 field name, which can be "METADATA_BLOCK_PICTURE" or "COVERART".
1542 The first is the official standard and uses the same format as
1543 pictures in FLAC tags. "COVERART" is an earlier unofficial way to
1544 include pictures in Vorbis comments. It can be used for
1545 compatibility with legacy players.
1546 If the Mark if larger than (bytes) check box is activated, files
1548 containing embedded album cover art exceeding the given size in
1549 bytes are marked red. This can be used to find files containing
1550 oversized pictures which are not accepted by some applications and
1551 players. The default value is 131072 bytes (128 KB).
1552 Custom Genres can be used to define genres which are not available
1554 in the standard genre list, e.g. "Gothic Metal". Such custom
1555 genres will appear in the Genre combo box of Tag 2. For ID3v1.1
1556 tags, only the predefined genres can be used.
1557 The list of custom genres can also be used to reduce the number of
1559 genres available in the Genre combo box to those typically used. If
1560 your collection mostly contains music in the genres Metal, Gothic
1561 Metal, Ancient and Hard Rock, you can enter those genres and mark
1562 Show only custom genres. The Tag 2 Genre combo box will then only
1563 contain those four genres and you will not have to search through
1564 the complete genres list for them. In this example, only Metal and
1565 Hard Rock will be listed in the tag 1 genres list, because those
1566 two custom genres entries are standard genres. If Show only custom
1567 genres is not active, the custom genres can be found at the end of
1568 the genres list.
1569 In Custom Frames, up to eight custom frame names can be defined,
1571 which can then be used like the unified frames, for example as
1572 quick access frames.
1573 Quick Access Frames defines which frame types are always shown in
1575 the Tag 2 section. Such frames can then be added without first
1576 using the Add button. The order of these quick access frames can be
1577 changed by dragging and dropping items.
1578 The combo box Track number field name is only relevant for RIFF
1580 INFO and sets the name of the field used for track numbers. Track
1581 numbers are not specified in the original RIFF standard, there are
1582 applications which use "ITRK", others use "IPRT".
1583 Tag Format contains options for the format of the tags. When
1585 Automatically apply format is checked, the format configuration is
1586 automatically used while editing text in the line edits.
1587 Validation enables validators in the controls with track/total and
1588 date/time values. The Case conversion can be set to No changes, All
1589 lowercase, All uppercase, First letter uppercase or All first
1590 letters uppercase. To use locale-aware conversion between lowercase
1591 and uppercase characters, a locale can be selected in the combobox
1592 below. The string replacement list can be set to arbitrary string
1593 mappings. To add a new mapping, select the From cell of a row and
1594 insert the text to replace, then go to the To column and enter the
1595 replacement text. When the text to replace starts and ends with a
1596 slash ("/"), a regular expression is used. For regular expressions
1597 containing capturing groups, occurrences of \1, \2, ... in To are
1598 replaced with the string captured by the corresponding capturing
1599 group. To remove a mapping set the From cell to an empty value
1600 (e.g. by first typing space and then backspace). Inserting and
1601 deleting rows is also possible using a context menu which appears
1602 when the right mouse button is clicked. Replacement is only active,
1603 if the String replacement check box is checked.
1604 The table in Rating contains the mapping of star ratings to the
1606 effective values stored in the tag. The frames with rating
1607 information are listed in the Rating row of the frame list. For
1608 these frames, the rating can be set by giving a number of stars out
1609 of five stars. Different tag formats and different applications use
1610 different values to map the star rating to the value stored in the
1611 tag. In order to display the correct number of stars, Kid3 will
1612 look up a map in this table. The key to look up the mapping is the
1613 frame name, for example "RATING" as used for Vorbis comments or
1614 "IRTD" for RIFF INFO. For ID3v2 tags, a combined key is used
1615 consisting of the frame ID "POPM" of the Popularimeter frame and
1616 its "Email" field, separated by a dot. Therefore, different keys
1617 for ID3v2 exist, e.g. "POPM.Windows Media Player 9 Series" for the
1618 mapping used by Windows Media Player and Explorer, and simply
1619 "POPM" for POPM frames with an empty "Email" field. As multiple
1620 entries for "POPM" can exist, their order is important. When Kid3
1621 adds a new Popularimeter frame, it will use the first "POPM" entry
1622 to determine the value to be written into the "Email" field. This
1623 value will then specify the mapping to be used for star ratings.
1624 The first entry is also used if no key was found, it is therefore
1625 the default entry.
1626 Besides the Name column containing the keys, the table has columns
1628 1 to 5 for the values to be stored when the corresponding number of
1629 stars is given. The other way round, the values determine the
1630 number of stars which are displayed for the value stored in the
1631 frame. For instance, the row in the table below contains the values
1632 1, 64, 128, 196, 255. The thresholds for the number of stars to be
1633 displayed lay between these values and are compatible with what the
1634 Windows® Explorer uses.
1635 Table 1. Entry in Rating Table
1637 ┌──────┬──────┬───────┬────────┬─────────┬─────────┐
1638 │Name │ 1 │ 2 │ 3 │ 4 │ 5 │
1639 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1640 │POPM │ 1 │ 64 │ 128 │ 196 │ 255 │
1641 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1642 │Range │ 1-31 │ 32-95 │ 96-159 │ 160-223 │ 224-255 │
1643 └──────┴──────┴───────┴────────┴─────────┴─────────┘
1644 On the page Files the check box Load last-opened files can be
1645 marked so that Kid3 will open and select the last selected file
1646 when it is started the next time. Preserve file timestamp can be
1647 checked to preserve the file modification time stamp. Filename for
1648 cover sets the name which is suggested when an embedded image is
1649 exported to a file. With Text encoding (Export, Playlist) the
1650 encoding used when writing files can be set. The default System can
1651 be changed for example if playlists have to be used on a different
1652 device.
1653 If Mark changes is active, changed fields are marked with a light
1655 gray label background.
1656 The section File List determines which files are displayed in the
1658 file list. A Filter can be used to restrict the items in this list
1659 to files with supported extensions. To explicitly specify which
1660 folders to display in the file list or exclude certain folders, the
1661 options Include folders and Exclude folders can be used. They can
1662 contain wildcard expressions, for instance */Music/* to include
1663 only the Music folder, or */iTunes/* to exclude the iTunes folder
1664 from the file list. If multiple such expressions have to be used,
1665 they can be separated by spaces or semicolons.
1666 The buttons Filename from tag and Tag from filename in section
1668 Format open dialogs to edit the formats which are available in the
1669 Format combo boxes (with arrows up and down), which can be found in
1670 the File section of the main window.
1671 The Playlist button can be used to edit the file name formats
1673 available in the Create Playlist dialog.
1674 Filename Format contains options for the format of the filenames.
1676 The same options as in Tag Format are available.
1677 Additionally, the Maximum length allowed for file names can be set.
1679 Most modern file systems have a limit of 255 characters, but if you
1680 want to burn the files to CD, you should set the limit to 64. If
1681 Use for playlist and folder names is checked, the file name format
1682 is also used when creating playlists and renaming folders.
1683 The User Actions page contains a table with the commands which are
1685 available in the context menu of the file list. For critical
1686 operations such as deleting files, it is advisable to mark Confirm
1687 to pop up a confirmation dialog before executing the command.
1688 Output can be marked to see the output written by console commands
1689 (standard output and standard error). Name is the name displayed
1690 in the context menu. Command is the command line to be executed.
1691 Arguments can be passed using the following codes:
1692 • %F %{files} File paths (a list if multiple files selected)
1694 • %f %{file} File path to single file
1696 • %uF %{urls} URLs (a list if multiple files selected)
1698 • %uf %{url} URL to single file
1700 • %d %{directory} Folder
1702 • %s %{title} Title (Song)
1704 • %a %{artist} Artist
1706 • %l %{album} Album
1708 • %c %{comment} Comment
1710 • %y %{year} Year
1712 • %t %{track} Track (e.g. 01)
1714 • %t %{track.n} Track with field width n (e.g. 001 for
1716 %{track.3})
1717 • %T %{tracknumber} Track (without leading zeros, e.g. 1)
1719 • %g %{genre} Genre
1721 • %b %{browser} Command to start the web browser
1723 • %q %{qmlpath} Base folder of provided QML files
1725 The special code @separator can be set as a command to insert a
1727 separator into the user actions context menu. Menu items can be put
1728 into a submenu by enclosing them with @beginmenu and @endmenu
1729 commands. The name of the submenu is determined by the Name column
1730 of the @beginmenu command.
1731 To execute QML scripts, @qml is used as a command name. The path to
1733 the QML script is passed as a parameter. The provided scripts can
1734 be found in the folder %{qmlpath}/script/ (on Linux® typically
1735 /usr/share/kid3/qml/script/, on Windows qml/script/ inside the
1736 installation folder, and on macOS® in the app folder
1737 kid3.app/Contents/Resources/qml/script/). Custom scripts can be
1738 stored in any folder. If the QML code uses GUI components, @qmlview
1739 shall be used instead of @qml. Additional parameters are passed to
1740 the QML script where they will be available via the getArguments()
1741 function. An overview of some functions and properties which are
1742 available in QML can be found in the appendix QML Interface.
1743 The command which will be inserted with %{browser} can be defined
1745 in the Web browser line edit above. Commands starting with
1746 %{browser} can be used to fetch information about the audio files
1747 from the web, for instance
1748 %{browser} http://lyricwiki.org/%u{artist}:%u{title}
1750 will query the lyrics for the current song in LyricWiki[12]. The
1752 "u" in %u{artist} and %u{title} is used to URL-encode the artist
1753 %{artist} and song %{title} information. It is easy to define your
1754 own queries in the same way, e.g. an image search with Google[13]:
1755 %{browser} http://images.google.com/images?q=%u{artist}%20%u{album}
1757 To add album cover art to tag 2, you can search for images with
1759 Google or Amazon using the commands described above. The picture
1760 can be added to the tag with drag and drop. You can also add an
1761 image with Add, then select the Picture frame and import an image
1762 file or paste from the clipboard. Picture frames are supported for
1763 ID3v2, MP4, FLAC, Ogg and ASF tags.
1764 To add and delete entries in the table, a context menu can be used.
1766 The Network page contains only a field to insert the proxy address
1768 and optionally the port, separated by a colon. The proxy will be
1769 used when importing from an Internet server when the check box is
1770 checked.
1771 In the Plugins page, available plugins can be enabled or disabled.
1773 The plugins are separated into two sections. The Metadata Plugins &
1774 Priority list contains plugins which support audio file formats.
1775 The order of the plugins is important because they are tried from
1776 top to bottom. Some formats are supported by multiple plugins, so
1777 files will be opened with the first plugin supporting them. The
1778 TaglibMetadata supports most formats, if it is at the top of the
1779 list, it will open most of the files. If you want to use a
1780 different plugin for a file format, make sure that it is listed
1781 before the TaglibMetadata plugin. Details about the metadata plugin
1782 and why you may want to use them instead of TagLib are listed
1783 below.
1784 • Id3libMetadata: Uses id3lib[14] for ID3v1.1 and ID3v2.3 tags in
1786 MP3, MP2, AAC files. Supports a few more frame types than
1787 TagLib.
1788 • OggFlacMetadata: Uses libogg[15], libvorbis, libvorbisfile[16]
1790 for Ogg files, and additionally libFLAC++ and libFLAC[17] for
1791 FLAC files. These are the official libraries for these formats.
1792 • TaglibMetadata: Uses TagLib[18] which supports a lot of audio
1794 file formats. It can be used for all audio files supported by
1795 Kid3.
1796 • Mp4v2Metadata: mp4v2[19] was originally used by Kid3 to support
1798 M4A files. Can be used in case of problems with the M4A support
1799 of TagLib.
1800 The Available Plugins section lists the remaining plugins. Their
1802 order is not important, but they can be enabled or disabled using
1803 the check boxes.
1804 • AmazonImport: Used for the Import from Amazon... function.
1806 • DiscogsImport: Used for the Import from Discogs... function.
1808 • FreedbImport: Used for the Import from gnudb.org... function.
1810 • MusicBrainzImport: Used for the Import from MusicBrainz
1812 Release... function.
1813 • AcoustidImport: Used for the Import from MusicBrainz
1815 Fingerprint... function, which depends on the Chromaprint[20]
1816 and libav[21] libraries.
1817 Plugins which are disabled will not be loaded. This can be used to
1819 optimize resource usage and startup time. The settings on this page
1820 take only effect after a restart of Kid3.
1821 The Help Menu
1823 Help → Kid3 Handbook
1824 Opens this handbook.
1825 Help → About Kid3
1827 Displays a short information about Kid3.
1828
1830 Commands
1831 kid3-cli offers a command-line-interface for Kid3. If a folder path is
1832 used, the folder is opened. If one or more file paths are given, the
1833 common folder is opened and the files are selected. Subsequent commands
1834 will then work on these files. Commands are specified using -c options.
1835 If multiple commands are passed, they are executed in the given order.
1836 If files are modified by the commands, they will be saved at the end.
1837 If no command options are passed, kid3-cli starts in interactive mode.
1838 Commands can be entered and will operate on the current selection. The
1839 following sections list all available commands.
1840 Help
1842 help [COMMAND-NAME]
1843 Displays help about the parameters of COMMAND-NAME or about all
1845 commands if no command name is given.
1846 Timeout
1848 timeout [default | off | TIME]
1849 Overwrite the default command timeout. The CLI commands abort after
1851 a command specific timeout is expired. This timeout is 10 seconds
1852 for ls and albumart, 60 seconds for autoimport and filter, and 3
1853 seconds for all other commands. If a huge number of files has to be
1854 processed, these timeouts may be too restrictive, thus the timeout
1855 for all commands can be set to TIME ms, switched off altogether or
1856 be left at the default values.
1857 Quit application
1859 exit [force]
1860 Exit application. If there are modified unsaved files, the force
1862 parameter is required.
1863 Change folder
1865 cd [FOLDER]
1866 If no FOLDER is given, change to the home folder. If a folder is
1868 given, change into the folder. If one or more file paths are given,
1869 change to their common folder and select the files.
1870 Print the filename of the current folder
1872 pwd
1873 Print the filename of the current working folder.
1875 Folder list
1877 ls
1878 List the contents of the current folder. This corresponds to the
1880 file list in the Kid3 GUI. Five characters before the file names
1881 show the state of the file.
1882 • > File is selected.
1884 • * File is modified.
1886 • 1 File has a tag 1, otherwise '-' is displayed.
1888 • 2 File has a tag 2, otherwise '-' is displayed.
1890 • 3 File has a tag 3, otherwise '-' is displayed.
1892 kid3-cli> ls
1894 1-- 01 Intro.mp3
1895 > 12- 02 We Only Got This One.mp3
1896 *1-- 03 Outro.mp3
1897 In this example, all files have a tag 1, the second file also has a
1899 tag 2 and it is selected. The third file is modified.
1900 Save the changed files
1902 save
1903 Select file
1905 select [all | none | first | previous | next | FILE...]
1906 To select all files, enter select all, to deselect all files, enter
1908 select none. To traverse the files in the current folder start with
1909 select first, then go forward using select next or backward using
1910 select previous. Specific files can be added to the current
1911 selection by giving their file names. Wildcards are possible, so
1912 select *.mp3 will select all MP3 files in the current folder.
1913 kid3-cli> select first
1915 kid3-cli> ls
1916 > 1-- 01 Intro.mp3
1917 12- 02 We Only Got This One.mp3
1918 *1-- 03 Outro.mp3
1919 kid3-cli> select next
1920 kid3-cli> ls
1921 1-- 01 Intro.mp3
1922 > 12- 02 We Only Got This One.mp3
1923 *1-- 03 Outro.mp3
1924 kid3-cli> select *.mp3
1925 kid3-cli> ls
1926 > 1-- 01 Intro.mp3
1927 > 12- 02 We Only Got This One.mp3
1928 >*1-- 03 Outro.mp3
1929 Select tag
1931 tag [TAG-NUMBERS]
1932 Many commands have an optional TAG-NUMBERS parameter, which
1934 specifies whether the command operates on tag 1, 2, or 3. If this
1935 parameter is omitted, the default tag numbers are used, which can
1936 be set by this command. At startup, it is set to 12 which means
1937 that information is read from tag 2 if available, else from tag 1;
1938 modifications are done on tag 2. The TAG-NUMBERS can be set to 1,
1939 2, or 3 to operate only on the corresponding tag. If the parameter
1940 is omitted, the current setting is displayed.
1941 Get tag frame
1943 get [all | FRAME-NAME] [TAG-NUMBERS]
1944 This command can be used to read the value of a specific tag frame
1946 or get information about all tag frames (if the argument is omitted
1947 or all is used). Modified frames are marked with a '*'.
1948 kid3-cli> get
1950 File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
1951 Name: 01 Intro.mp3
1952 Tag 1: ID3v1.1
1953 Title Intro
1954 Artist One Hit Wonder
1955 Album Let's Tag
1956 Date 2013
1957 Track Number 1
1958 Genre Pop
1959 kid3-cli> get title
1960 Intro
1961 To save the contents of a picture frame to a file, use
1963 get picture:'/path/to/folder.jpg'
1965 To save synchronized lyrics to an LRC file, use
1967 get SYLT:'/path/to/lyrics.lrc'
1969 It is possible to get only a specific field from a frame, for
1971 example get POPM.Email for the Email field of a Popularimeter
1972 frame. If a file has multiple frames of the same kind, the
1973 different frames can be indexed with brackets, for example the
1974 first performer from a Vorbis comment can be retrieved using get
1975 performer[0], the second using get performer[1].
1976 The pseudo field name "selected" can be used to check if a frame is
1978 selected, for example get artist.selected will return 1 if the
1979 artist frame is selected, else 0.
1980 The pseudo frame name "ratingstars" can be used to get the value of
1982 the "rating" frame as the format specific value corresponding to
1983 the number of stars (0 to 5). When using "rating", the internal
1984 value is returned.
1985 Set tag frame
1987 set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]
1988 This command sets the value of a specific tag frame. If FRAME-VALUE
1990 is empty, the frame is deleted.
1991 kid3-cli> set remixer 'O.H. Wonder'
1993 To set the contents of a picture frame from a file, use
1995 set picture:'/path/to/folder.jpg' 'Picture Description'
1997 To set synchronized lyrics from an LRC file, use
1999 set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'
2001 To set a specific field of a frame, the field name can be given
2003 after a dot, e.g. to set the Counter field of a Popularimeter
2004 frame, use
2005 set POPM.Counter 5
2007 An application for field specifications is the case where you want
2009 a custom TXXX frame with "rating" description instead of a standard
2010 Popularimeter frame (this seems to be used by some plugins). You
2011 can create such a TXXX rating frame with kid3-cli, however, you
2012 have to first create a TXXX frame with description "rating" and
2013 then set the value of this frame to the rating value.
2014 kid3-cli> set rating ""
2016 kid3-cli> set TXXX.Description rating
2017 kid3-cli> set rating 5
2018 The first command will delete an existing POPM frame, because if
2020 such a frame exists, set rating 5 would set the POPM frame and not
2021 the TXXX frame. Another possibility would be to use set TXXX.Text
2022 5, but this would only work if there is no other TXXX frame
2023 present.
2024 To set multiple frames of the same kind, an index can be given in
2026 brackets, e.g. to set multiple performers in a Vorbis comment, use
2027 kid3-cli> set performer[0] 'Liza don Getti (soprano)'
2029 kid3-cli> set performer[1] 'Joe Barr (piano)'
2030 To select certain frames before a copy, paste or remove action, the
2032 pseudo field name "selected" can be used. Normally, all frames are
2033 selected, to deselect all, use set '*.selected' 0, then for example
2034 set artist.selected 1 to select the artist frame.
2035 The pseudo frame name "ratingstars" can be used to set the value of
2037 the "rating" frame to the format specific value corresponding to
2038 the number of stars (0 to 5). The frame name "rating" can be used
2039 to set the internal value.
2040 Setting "ratingstars" on multiple files having different tag
2042 formats will not work because the frame with the value mapped from
2043 the star count is created for the first file and then used for all
2044 files. So instead of kid3-cli -c "set ratingstars 2" * you should
2045 rather use for f in *; do kid3-cli -c "set ratingstars 2" "$f";
2046 done.
2047 Revert
2049 revert
2050 Revert all modifications in the selected files (or all files if no
2052 files are selected).
2053 Import from file
2055 import {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2056 Tags are imported from the file FILE in the format with the name
2058 FORMAT-NAME (e.g. "CSV unquoted", see Import).
2059 If tags is given for FILE, tags are imported from other tags.
2061 Instead of FORMAT-NAME parameters SOURCE and EXTRACTION are
2062 required, see Import from Tags. To apply the import from tags on
2063 the selected files, use tagsel instead of tags. This function also
2064 supports output of the extracted value by using an EXTRACTION with
2065 the value %{__return}(.+).
2066 Automatic import
2068 autoimport [PROFILE-NAME] [TAG-NUMBERS]
2069 Batch import using profile PROFILE-NAME (see Automatic Import,
2071 "All" is used if omitted).
2072 Download album cover artwork
2074 albumart {URL} [all]
2075 Set the album artwork by downloading a picture from URL. The rules
2077 defined in the Browse Cover Art dialog are used to transform
2078 general URLs (e.g. from Amazon) to a picture URL. To set the album
2079 cover from a local picture file, use the set command.
2080 kid3-cli> albumart
2082 http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
2083 Export to file
2085 export {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2086 Tags are exported to file FILE in the format with the name
2088 FORMAT-NAME (e.g. "CSV unquoted", see Export).
2089 Create playlist
2091 playlist
2092 Create playlist in the format set in the configuration, see Create
2094 Playlist.
2095 Apply filename format
2097 filenameformat
2098 Apply file name format set in the configuration, see Apply Filename
2100 Format.
2101 Apply tag format
2103 tagformat
2104 Apply tag name format set in the configuration, see Apply Tag
2106 Format.
2107 Apply text encoding
2109 textencoding
2110 Apply text encoding set in the configuration, see Apply Text
2112 Encoding.
2113 Rename folder
2115 renamedir [FORMAT] [create | rename | dryrun] [TAG-NUMBERS]
2116 Rename or create folders from the values in the tags according to a
2118 given FORMAT (e.g. %{artist} - %{album}, see Rename Folder), if no
2119 format is given, the format defined in the Rename folder dialog is
2120 used. The default mode is rename; to create folders, create must be
2121 given explicitly. The rename actions will be performed immediately,
2122 to just see what would be done, use the dryrun option.
2123 Number tracks
2125 numbertracks [TRACK-NUMBER] [TAG-NUMBERS]
2126 Number the selected tracks starting with TRACK-NUMBER (1 if
2128 omitted).
2129 Filter
2131 filter [FILTER-NAME | FILTER-FORMAT]
2132 Filter the files so that only the files matching the FILTER-FORMAT
2134 are visible. The name of a predefined filter expression (e.g.
2135 "Filename Tag Mismatch") can be used instead of a filter
2136 expression, see Filter.
2137 kid3-cli> filter '%{title} contains "tro"'
2139 Started
2140 /home/urs/One Hit Wonder - Let's Tag
2141 + 01 Intro.mp3
2142 - 02 We Only Got This One.mp3
2143 + 03 Outro.mp3
2144 Finished
2145 kid3-cli> ls
2146 1-- 01 Intro.mp3
2147 1-- 03 Outro.mp3
2148 kid3-cli> filter All
2149 Started
2150 /home/urs/One Hit Wonder - Let's Tag
2151 + 01 Intro.mp3
2152 + 02 We Only Got This One.mp3
2153 + 03 Outro.mp3
2154 Finished
2155 kid3-cli> ls
2156 1-- 01 Intro.mp3
2157 12- 02 We Only Got This One.mp3
2158 1-- 03 Outro.mp3
2159 Convert ID3v2.3 to ID3v2.4
2161 to24
2162 Convert ID3v2.4 to ID3v2.3
2164 to23
2165 Filename from tag
2167 fromtag [FORMAT] [TAG-NUMBERS]
2168 Set the file names of the selected files from values in the tags,
2170 for example fromtag '%{track} - %{title}' 1. If no format is
2171 specified, the format set in the GUI is used.
2172 Tag from filename
2174 totag [FORMAT] [TAG-NUMBERS]
2175 Set the tag frames from the file names, for example totag
2177 '%{albumartist} - %{album}/%{track} %{title}' 2. If no format is
2178 specified, the format set in the GUI is used. If the format of the
2179 filename does not match this pattern, a few other commonly used
2180 formats are tried.
2181 Tag to other tag
2183 syncto {TAG-NUMBER}
2184 Copy the tag frames from one tag to the other tag, e.g. to set the
2186 ID3v2 tag from the ID3v1 tag, use syncto 2.
2187 Copy
2189 copy [TAG-NUMBER]
2190 Copy the tag frames of the selected file to the internal copy
2192 buffer. They can then be set on another file using the paste
2193 command.
2194 To copy only a subset of the frames, use the "selected" pseudo
2196 field with the set command. For example, to copy only the disc
2197 number and copyright frames, use
2198 set '*.selected' 0
2200 set discnumber.selected 1
2201 set copyright.selected 1
2202 copy
2203 Paste
2206 paste [TAG-NUMBER]
2207 Set tag frames from the contents of the copy buffer in the selected
2209 files.
2210 Remove
2212 remove [TAG-NUMBER]
2213 Remove a tag.
2215 It is possible to remove only a subset of the frames by selecting
2217 them as described in the copy command.
2218 Configure Kid3
2220 config [OPTION] [VALUE]
2221 Query or set a configuration option.
2223 The OPTION consists of a group name and a property name separated
2225 by a dot. When no OPTION is given, all available groups are
2226 displayed. If only a group name is given, all available properties
2227 of the group are displayed. For a given group and property, the
2228 currently configured value is displayed. To change the setting, the
2229 new value can be passed as a second argument.
2230 If the value of a setting is a list, all list elements have to be
2232 given as arguments. This means that to append an element to an
2233 existing list of elements, all existing elements have to be passed
2234 followed by the new element. In such a situation, it is easier to
2235 use the JSON mode, where the current list can be copied with the
2236 new element appended.
2237 Execute program or QML script
2239 execute [@qml] {FILE} [ARGS]
2240 Execute a QML script or an executable.
2242 Without @qml a program is executed with arguments. When @qml is
2244 given as the first argument, the following arguments are the QML
2245 script and its arguments. For example, the tags of a folder can be
2246 exported to the file export.csv with the following command.
2247 kid3-cli -c "execute @qml
2249 /usr/share/kid3/qml/script/ExportCsv.qml export.csv"
2250 /path/to/folder/
2251 Here export.csv is the argument for the ExportCsv.qml script,
2253 whereas /path/to/folder/ is the FILE argument for kid3-cli.
2254 Examples
2256 Set title containing an apostrophe. Commands passed to kid3-cli with -c
2257 have to be in quotes if they do not only consist of a single word. If
2258 such a command itself has an argument containing spaces, that argument
2259 has to be quoted too. In UNIX® shells single or double quotes can be
2260 used, but on the Windows Command Prompt, it is important that the outer
2261 quoting is done using double quotes and inside these quotes, single
2262 quotes are used. If the text inside the single quotes contains a single
2263 quote, it has to be escaped using a backslash character, as shown in
2264 the following example:
2265 kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder
2267 Set album cover in all files of a folder using the batch import
2269 function:
2270 kid3-cli -c "autoimport 'Cover Art'" /path/to/folder
2272 Remove comment frames and apply the tag format in both tags of all MP3
2274 files of a folder:
2275 kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
2277 -c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3
2278 Automatically import tag 2, synchronize to tag 1, set file names from
2280 tag 2 and finally create a playlist:
2281 kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
2283 /path/to/folder/*.mp3
2284 For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
2286 the arranger frame:
2287 kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
2289 -c "set arranger ''" /path/to/folder
2290 This Python script uses kid3-cli to generate iTunes Sound Check
2292 iTunNORM frames from replay gain information.
2293 #!/usr/bin/env python3
2296 # Generate iTunes Sound Check from ReplayGain.
2297 import os, sys, subprocess
2298 def rg2sc(dirpath):
2300 for root, dirs, files in os.walk(dirpath):
2301 for name in files:
2302 if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
2303 fn = os.path.join(root, name)
2304 rg = subprocess.check_output([
2305 'kid3-cli', '-c', 'get "replaygain_track_gain"',
2306 fn]).strip()
2307 if rg.endswith(b' dB'):
2308 rg = rg[:-3]
2309 try:
2310 rg = float(rg)
2311 except ValueError:
2312 print('Value %s of %s in not a float' % (rg, fn))
2313 continue
2314 sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
2315 subprocess.call([
2316 'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
2317 if __name__ == '__main__':
2319 rg2sc(sys.argv[1])
2320 JSON Format
2323 In order to make it easier to parse results from kid3-cli, it is
2324 possible to get the output in JSON format. When the request is in JSON
2325 format, the response will also be JSON. A compact format of the request
2326 will also give a compact representation of the response. If the request
2327 contains an "id" field, it is assumed to be a JSON-RPC request and the
2328 response will contain a "jsonrpc" field and the "id" of the request.
2329 The request format uses the same commands as the standard CLI, the
2330 "method" field contains the command and the parameters (if any) are
2331 given in the "params" list. The response contains a "result" object,
2332 which can also be null if the corresponding kid3-cli command does not
2333 return a result. In case of an error, an "error" object is returned
2334 with "code" and "message" fields as used in JSON-RPC.
2335 kid3-cli> {"method":"set","params":["artist","An Artist"]}
2337 {"result":null}
2338 kid3-cli> {"method":"get","params":["artist",2]}
2339 {"result":"An Artist"}
2340 kid3-cli> {"method": "get", "params": ["artist"]}
2341 {
2342 "result": "An Artist"
2343 }
2344 kid3-cli> {"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}
2346 {"id":"123","jsonrpc":"2.0","result":"An Artist"}
2347
2350 Kid3
2351 Program written by Urs Fleisch <ufleisch at users.sourceforge.net>
2353 FDL[22]
2355 GPL[23]
2357
2359 How to obtain Kid3
2360 Kid3 can be found at https://kid3.kde.org.
2361 Requirements
2363 Kid3 needs Qt(TM)[24]. KDE[25] is recommended but not necessary, as
2364 Kid3 can also be compiled as a Qt(TM) application. Kid3 can be
2365 compiled for systems where these libraries are available, e.g. for
2366 GNU/Linux®, Windows® and macOS®. To tag Ogg/Vorbis files, libogg[15],
2367 libvorbis and libvorbisfile[16] are required, for FLAC files libFLAC++
2368 and libFLAC[17]. id3lib[14] is used for MP3 files. These four formats
2369 are also supported by TagLib[18], which can also handle Opus, MPC, APE,
2370 MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker
2371 modules. To import from acoustic fingerprints, Chromaprint[20] and
2372 libav[21] are used.
2373 Kid3 is available for most Linux® distributions, Windows® and macOS®.
2375 Links can be found on https://kid3.kde.org.
2376 Compilation and Installation
2378 You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple
2379 Qt(TM) application and lacks some configuration and session features.
2380 For a KDE version, go into the top folder and type
2382 % cmake .
2384 % make
2385 % make install
2386 To compile for different versions of Qt(TM) or KDE, set the
2388 corresponding cmake options.
2389 If not all libraries are present, Kid3 is built with reduced
2391 functionality. So you should take care to have all desired development
2392 packages installed. On the other side, cmake-options control which
2393 libraries are compiled in. The default is -DWITH_TAGLIB:BOOL=ON
2394 -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON
2395 -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON . These options can be
2396 disabled using OFF.
2397 To build Kid3 as a Qt(TM) application without KDE, use the cmake option
2399 -DWITH_APPS=Qt. To build both a KDE and a Qt(TM) application, set
2400 -DWITH_APPS="Qt;KDE".
2401 To use a specific Qt(TM) installation, set
2403 -DQT_QMAKE_EXECUTABLE=/path/to/qmake.
2404 Generation of RPM-Packages is supported by the file kid3.spec, for
2406 Debian® Packages, run build.sh deb.
2407 The Qt(TM) application can also be compiled for Windows® and macOS®.
2409 The script build.sh can be used to download and build all required
2410 libraries and create a Kid3 package.
2411 Configuration
2413 With KDE, the settings are stored in .config/kid3rc, the application
2414 state in .local/share/kid3/kid3staterc. As a Qt(TM) application, this
2415 file is in .config/Kid3/Kid3.conf. On Windows®, the configuration is
2416 stored in the registry. on macOS® in a plist file.
2417 The environment variable KID3_CONFIG_FILE can be used to set the path
2419 of the configuration file.
2420
2422 D-Bus Examples
2423 On Linux® a D-Bus-interface can be used to control Kid3 by scripts.
2424 Scripts can be written in any language with D-Bus-bindings (e.g. in
2425 Python) and can be added to the User Actions to extend the
2426 functionality of Kid3.
2427 The artist in tag 2 of the current file can be set to the value "One
2429 Hit Wonder" with the following code:
2430 Shell
2432 dbus-send --dest=org.kde.kid3 --print-reply=literal \
2434 /Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
2435 string:'One Hit Wonder'
2436 or easier with Qt(TM)'s qdbus (qdbusviewer can be used to explore
2438 the interface in a GUI):
2439 qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
2441 'One Hit Wonder'
2442 Python
2444 import dbus
2446 kid3 = dbus.SessionBus().get_object(
2447 'org.kde.kid3', '/Kid3')
2448 kid3.setFrame(2, 'Artist', 'One Hit Wonder')
2449 Perl
2451 use Net::DBus;
2453 $kid3 = Net::DBus->session->get_service(
2454 "org.kde.kid3")->get_object(
2455 "/Kid3", "org.kde.Kid3");
2456 $kid3->setFrame(2, "Artist", "One Hit Wonder");
2457 D-Bus API
2459 The D-Bus API is specified in org.kde.Kid3.xml. The Kid3 interface has
2460 the following methods:
2461 Open file or folder
2463 boolean openDirectory(string path);
2464 path
2466 path to file or folder
2467 Returns true if OK.
2469 Unload the tags of all files which are not modified or selected
2471 unloadAllTags(void);
2472 Save all modified files
2474 boolean save(void);
2475 Returns true if OK.
2477 Get a detailed error message provided by some methods
2479 string getErrorMessage(void);
2480 Returns detailed error message.
2482 Revert changes in the selected files
2484 revert(void);
2485 Start an automatic batch import
2487 boolean batchImport(int32 tagMask, string profileName);
2488 tagMask
2490 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2491 profileName
2493 name of batch import profile to use
2494 Import tags from a file
2496 boolean importFromFile(int32 tagMask, string path, int32 fmtIdx);
2497 tagMask
2499 tag bit (1 for tag 1, 2 for tag 2)
2500 path
2502 path of file
2503 fmtIdx
2505 index of format
2506 Returns true if OK.
2508 Import tags from other tags
2510 importFromTags(int32 tagMask, string source, string extraction);
2511 tagMask
2513 tag bit (1 for tag 1, 2 for tag 2)
2514 source
2516 format to get source text from tags
2517 extraction
2519 regular expression with frame names and captures to extract
2520 from source text
2521 Import tags from other tags on selected files
2523 array importFromTagsToSelection(int32 tagMask, string source,
2524 string extraction);
2525 tagMask
2527 tag bit (1 for tag 1, 2 for tag 2)
2528 source
2530 format to get source text from tags
2531 extraction
2533 regular expression with frame names and captures to extract
2534 from source text
2535 returnValues
2537 extracted value for "%{__return}(.+)"
2538 Download album cover art
2540 downloadAlbumArt(string url, boolean allFilesInDir);
2541 url
2543 URL of picture file or album art resource
2544 allFilesInDir
2546 true to add the image to all files in the folder
2547 Export tags to a file
2549 boolean exportToFile(int32 tagMask, string path, int32 fmtIdx);
2550 tagMask
2552 tag bit (1 for tag 1, 2 for tag 2)
2553 path
2555 path of file
2556 fmtIdx
2558 index of format
2559 Returns true if OK.
2561 Create a playlist
2563 boolean createPlaylist(void);
2564 Returns true if OK.
2566 Get items of a playlist
2568 array getPlaylistItems(string path);
2569 path
2571 path to playlist file
2572 Returns list of absolute paths to playlist items.
2574 Set items of a playlist
2576 boolean setPlaylistItems(string path, array items);
2577 path
2579 path to playlist file
2580 items
2582 list of absolute paths to playlist items
2583 Returns true if OK, false if not all items were found and added or
2585 saving failed.
2586 Quit the application
2588 quit(void);
2589 Select all files
2591 selectAll(void);
2592 Deselect all files
2594 deselectAll(void);
2595 Set the first file as the current file
2597 boolean firstFile(void);
2598 Returns true if there is a first file.
2600 Set the previous file as the current file
2602 boolean previousFile(void);
2603 Returns true if there is a previous file.
2605 Set the next file as the current file
2607 boolean nextFile(void);
2608 Returns true if there is a next file.
2610 Select the first file
2612 boolean selectFirstFile(void);
2613 Returns true if there is a first file.
2615 Select the previous file
2617 boolean selectPreviousFile(void);
2618 Returns true if there is a previous file.
2620 Select the next file
2622 boolean selectNextFile(void);
2623 Returns true if there is a next file.
2625 Select the current file
2627 boolean selectCurrentFile(void);
2628 Returns true if there is a current file.
2630 Expand or collapse the current file item if it is a folder
2632 boolean expandDirectory(void);
2633 A file list item is a folder if getFileName() returns a name with
2635 '/' as the last character.
2636 Returns true if current file item is a folder.
2638 Apply the file name format
2640 applyFilenameFormat(void);
2641 Apply the tag format
2643 applyTagFormat(void);
2644 Apply text encoding
2646 applyTextEncoding(void);
2647 Set the folder name from the tags
2649 boolean setDirNameFromTag(int32 tagMask, string format,
2650 boolean create);
2651 tagMask
2653 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2654 format
2656 folder name format
2657 create
2659 true to create, false to rename
2660 Returns true if OK, else the error message is available using
2662 getErrorMessage().
2663 Set subsequent track numbers in the selected files
2665 numberTracks(int32 tagMask, int32 firstTrackNr);
2666 tagMask
2668 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2669 firstTrackNr
2671 number to use for first file
2672 Filter the files
2674 filter(string expression);
2675 expression
2677 filter expression
2678 Convert ID3v2.3 tags to ID3v2.4
2680 convertToId3v24(void);
2681 Convert ID3v2.4 tags to ID3v2.3
2683 convertToId3v23(void);
2684 Returns true if OK.
2686 Get path of folder
2688 string getDirectoryName(void);
2689 Returns absolute path of folder.
2691 Get name of current file
2693 string getFileName(void);
2694 Returns true absolute file name, ends with "/" if it is a folder.
2696 Set name of selected file
2698 setFileName(string name);
2699 name
2701 file name
2702 The file will be renamed when the folder is saved.
2704 Set format to use when setting the filename from the tags
2706 setFileNameFormat(string format);
2707 format
2709 file name format
2710 Set the file names of the selected files from the tags
2712 setFileNameFromTag(int32 tagMask);
2713 tagMask
2715 tag bit (1 for tag 1, 2 for tag 2)
2716 Get value of frame
2718 string getFrame(int32 tagMask, string name);
2719 tagMask
2721 tag bit (1 for tag 1, 2 for tag 2)
2722 name
2724 name of frame (e.g. "artist")
2725 To get binary data like a picture, the name of a file to write can
2727 be added after the name, e.g. "Picture:/path/to/file". In the same
2728 way, synchronized lyrics can be exported, e.g.
2729 "SYLT:/path/to/file".
2730 Returns value of frame.
2732 Set value of frame
2734 boolean setFrame(int32 tagMask, string name, string value);
2735 tagMask
2737 tag bit (1 for tag 1, 2 for tag 2)
2738 name
2740 name of frame (e.g. "artist")
2741 value
2743 value of frame
2744 For tag 2 (tagMask 2), if no frame with name exists, a new frame is
2746 added, if value is empty, the frame is deleted. To add binary data
2747 like a picture, a file can be added after the name, e.g.
2748 "Picture:/path/to/file". "SYLT:/path/to/file" can be used to import
2749 synchronized lyrics.
2750 Returns true if OK.
2752 Get all frames of a tag
2754 array of string getTag(int32 tagMask);
2755 tagMask
2757 tag bit (1 for tag 1, 2 for tag 2)
2758 Returns list with alternating frame names and values.
2760 Get technical information about file
2762 array of string getInformation(void);
2763 Properties are Format, Bitrate, Samplerate, Channels, Duration,
2765 Channel Mode, VBR, Tag 1, Tag 2. Properties which are not available
2766 are omitted.
2767 Returns list with alternating property names and values.
2769 Set tag from file name
2771 setTagFromFileName(int32 tagMask);
2772 tagMask
2774 tag bit (1 for tag 1, 2 for tag 2)
2775 Set tag from other tag
2777 setTagFromOtherTag(int32 tagMask);
2778 tagMask
2780 tag bit (1 for tag 1, 2 for tag 2)
2781 Copy tag
2783 copyTag(int32 tagMask);
2784 tagMask
2786 tag bit (1 for tag 1, 2 for tag 2)
2787 Paste tag
2789 pasteTag(int32 tagMask);
2790 tagMask
2792 tag bit (1 for tag 1, 2 for tag 2)
2793 Remove tag
2795 removeTag(int32 tagMask);
2796 tagMask
2798 tag bit (1 for tag 1, 2 for tag 2)
2799 Reparse the configuration
2801 reparseConfiguration(void);
2802 Automated configuration changes are possible by modifying the
2804 configuration file and then reparsing the configuration.
2805 Plays the selected files
2807 playAudio(void);
2808
2810 QML Examples
2811 QML scripts can be invoked via the context menu of the file list and
2812 can be set in the tab User Actions of the settings dialog. The scripts
2813 which are set there can be used as examples to program custom scripts.
2814 QML uses JavaScript, here is the obligatory "Hello World":
2815 import Kid3 1.0
2817 Kid3Script {
2819 onRun: {
2820 console.log("Hello world, folder is", app.dirName)
2821 Qt.quit()
2822 }
2823 }
2824 If this script is saved as /path/to/Example.qml, the user command can
2826 be defined as @qml /path/to/Example.qml with name QML Test and Output
2827 checked. It can then be started using the QML Test item in the file
2828 list context menu, and the output will be visible in the window.
2829 Unfortunately, starting the QML scripts using the qml (e.g. qml
2831 -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml)
2832 is broken in recent versions of Qt. But kid3-cli offers an alternative
2833 way to run a QML script from the command line using its execute
2834 command.
2835 kid3-cli -c "execute @qml /path/to/Example.qml"
2837 To list the titles in the tags 2 of all files in the current folder,
2839 the following script could be used:
2840 import Kid3 1.0
2842 Kid3Script {
2844 onRun: {
2845 app.firstFile()
2846 do {
2847 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2848 console.log(app.getFrame(tagv2, "title"))
2849 }
2850 } while (app.nextFile())
2851 }
2852 }
2853 If the folder contains many files, such a script might block the user
2855 interface for some time. For longer operations, it should therefore
2856 have a break from time to time. The alternative implementation below
2857 has the work for a single file moved out into a function. This function
2858 invokes itself with a timeout of 1 ms at the end, given that more files
2859 have to be processed. This will ensure that the GUI remains responsive
2860 while the script is running.
2861 import Kid3 1.0
2863 Kid3Script {
2865 onRun: {
2866 function doWork() {
2867 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2868 console.log(app.getFrame(tagv2, "title"))
2869 }
2870 if (!app.nextFile()) {
2871 Qt.quit()
2872 } else {
2873 setTimeout(doWork, 1)
2874 }
2875 }
2876 app.firstFile()
2878 doWork()
2879 }
2880 }
2881 When using app.firstFile() with app.nextFile(), all files of the
2883 current folder will be processed. If only the selected files shall be
2884 affected, use firstFile() and nextFile() instead, these are convenience
2885 functions of the Kid3Script component. The following example is a
2886 script which copies only the disc number and copyright frames of the
2887 selected file.
2888 import Kid3 1.1
2890 Kid3Script {
2892 onRun: {
2893 function doWork() {
2894 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2895 app.setFrame(tagv2, "*.selected", false)
2896 app.setFrame(tagv2, "discnumber.selected", true)
2897 app.setFrame(tagv2, "copyright.selected", true)
2898 app.copyTags(tagv2)
2899 }
2900 if (!nextFile()) {
2901 Qt.quit()
2902 } else {
2903 setTimeout(doWork, 1)
2904 }
2905 }
2906 firstFile()
2908 doWork()
2909 }
2910 }
2911 More example scripts come with Kid3 and are already registered as user
2913 commands.
2914 • ReplayGain to SoundCheck (ReplayGain2SoundCheck.qml): Create
2916 iTunNORM SoundCheck information from replay gain frames.
2917 • Resize Album Art (ResizeAlbumArt.qml): Resize embedded cover art
2919 images which are larger than 500x500 pixels.
2920 • Extract Album Art (ExtractAlbumArt.qml): Extract all embedded cover
2922 art pictures avoiding duplicates.
2923 • Embed Album Art (EmbedAlbumArt.qml): Embed cover art found in image
2925 files into audio files in the same folder.
2926 • Embed Lyrics (EmbedLyrics.qml): Fetch unsynchronized lyrics from
2928 web service.
2929 • Text Encoding ID3v1 (ShowTextEncodingV1.qml): Helps to find the
2931 encoding of ID3v1 tags by showing the tags of the current file in
2932 all available character encodings.
2933 • ID3v1 to ASCII (Tag1ToAscii.qml): Transliterate extended latin
2935 characters in the ID3v1 tag to ASCII.
2936 • English Title Case (TitleCase.qml): Formats text in the tags to
2938 English title case.
2939 • Rewrite Tags (RewriteTags.qml): Rewrite all tags in the selected
2941 files.
2942 • Export CSV (ExportCsv.qml): Export recursively all tags of all
2944 files to a CSV file.
2945 • Import CSV (ImportCsv.qml): Import recursively all tags of all
2947 files from a CSV file.
2948 • Export JSON (ExportJson.qml): Export recursively all tags of all
2950 files to a JSON file.
2951 • Import JSON (ImportJson.qml): Import recursively all tags of all
2953 files from a JSON file.
2954 • Export Playlist Folder (ExportPlaylist.qml): Copy all files from a
2956 playlist into a folder and rename them according to their position.
2957 • QML Console (QmlConsole.qml): Simple console to play with Kid3's
2959 QML API.
2960 QML API
2963 The API can be easily explored using the QML Console, which is
2964 available as an example script with a user interface.
2965 Kid3Script
2967 Kid3Script is a regular QML component located inside the plugin
2968 folder. You could use another QML component just as well. Using
2969 Kid3Script makes it easy to start the script function using the
2970 onRun signal handler. Moreover it offers some functions:
2971 onRun: Signal handler which is invoked when the script is started
2973 tagv1, tagv2, tagv2v1: Constants for tag parameters
2974 script: Access to scripting functions
2975 configs: Access to configuration objects
2976 getArguments(): List of script arguments
2977 isStandalone(): true if the script was not started from within Kid3
2978 setTimeout(callback, delay): Starts callback after delay ms
2979 firstFile(): To first selected file
2980 nextFile(): To next selected file
2981 Scripting Functions
2984 As JavaScript and therefore QML too has only a limited set of
2985 functions for scripting, the script object has some additional
2986 methods, for instance:
2987 script.properties(obj): String with Qt properties
2989 script.writeFile(filePath, data): Write data to file, true if OK
2990 script.readFile(filePath): Read data from file
2991 script.removeFile(filePath): Delete file, true if OK
2992 script.fileExists(filePath): true if file exists
2993 script.fileIsWritable(filePath): true if file is writable
2994 script.getFilePermissions(filePath): Get file permission mode bits
2995 script.setFilePermissions(filePath, modeBits): Set file permission mode bits
2996 script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
2997 file " ")
2998 script.renameFile(oldName, newName): Rename file, true if OK
2999 script.copyFile(source, dest): Copy file, true if OK
3000 script.makeDir(path): Create folder, true if OK
3001 script.removeDir(path): Remove folder, true if OK
3002 script.tempPath(): Path to temporary folder
3003 script.musicPath(): Path to music folder
3004 script.listDir(path, [nameFilters], [classify]): List folder entries
3005 script.system(program, [args], [msecs]): Synchronously start a system command,
3006 [exit code, standard output, standard error] if not timeout
3007 script.systemAsync(program, [args], [callback]): Asynchronously start a system
3008 command, callback will be called with [exit code, standard output, standard
3009 error]
3010 script.getEnv(varName): Get value of environment variable
3011 script.setEnv(varName, value): Set value of environment variable
3012 script.getQtVersion(): Qt version string, e.g. "5.4.1"
3013 script.getDataMd5(data): Get hex string of the MD5 hash of data
3014 script.getDataSize(data): Get size of byte array
3015 script.dataToImage(data, [format]): Create an image from data bytes
3016 script.dataFromImage(img, [format]): Get data bytes from image
3017 script.loadImage(filePath): Load an image from a file
3018 script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
3019 script.imageProperties(img): Get properties of an image, map containing
3020 "width", "height", "depth" and "colorCount", empty if invalid image
3021 script.scaleImage(img, width, [height]): Scale an image, returns scaled image
3022 Application Context
3024 Using QML, a large part of the Kid3 functions are accessible. The
3025 API is similar to the one used for D-Bus. For details, refer to the
3026 respective notes.
3027 app.openDirectory(path): Open folder
3029 app.unloadAllTags(): Unload all tags
3030 app.saveDirectory(): Save folder
3031 app.revertFileModifications(): Revert
3032 app.importTags(tag, path, fmtIdx): Import file
3033 app.importFromTags(tag, source, extraction): Import from tags
3034 app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
3035 app.downloadImage(url, allFilesInDir): Download image
3036 app.exportTags(tag, path, fmtIdx): Export file
3037 app.writePlaylist(): Write playlist
3038 app.getPlaylistItems(path): Get items of a playlist
3039 app.setPlaylistItems(path, items): Set items of a playlist
3040 app.selectAllFiles(): Select all
3041 app.deselectAllFiles(): Deselect
3042 app.firstFile([select], [onlyTaggedFiles]): To first file
3043 app.nextFile([select], [onlyTaggedFiles]): To next file
3044 app.previousFile([select], [onlyTaggedFiles]): To previous file
3045 app.selectCurrentFile([select]): Select current file
3046 app.selectFile(path, [select]): Select a specific file
3047 app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
3048 app.requestExpandFileList(): Expand all
3049 app.applyFilenameFormat(): Apply filename format
3050 app.applyTagFormat(): Apply tag format
3051 app.applyTextEncoding(): Apply text encoding
3052 app.numberTracks(nr, total, tag, [options]): Number tracks
3053 app.applyFilter(expr): Filter
3054 app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
3055 app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
3056 app.getFilenameFromTags(tag): Filename from tags
3057 app.getTagsFromFilename(tag): Filename to tags
3058 app.getAllFrames(tag): Get object with all frames
3059 app.getFrame(tag, name): Get frame
3060 app.setFrame(tag, name, value): Set frame
3061 app.getPictureData(): Get data from picture frame
3062 app.setPictureData(data): Set data in picture frame
3063 app.copyToOtherTag(tag): Tags to other tags
3064 app.copyTags(tag): Copy
3065 app.pasteTags(tag): Paste
3066 app.removeTags(tag): Remove
3067 app.playAudio(): Play
3068 app.readConfig(): Read configuration
3069 app.applyChangedConfiguration(): Apply configuration
3070 app.dirName: Folder name
3071 app.selectionInfo.fileName: File name
3072 app.selectionInfo.filePath: Absolute file path
3073 app.selectionInfo.detailInfo: Format details
3074 app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
3075 app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
3076 app.selectionInfo.formatString(tag, format): Substitute codes in format string
3077 app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
3078 select a file
3079 app.selectDirName(caption, dir): Open file dialog to select a folder
3080 For asynchronous operations, callbacks can be connected to signals.
3082 function automaticImport(profile) {
3084 function onAutomaticImportFinished() {
3085 app.batchImporter.finished.disconnect(onAutomaticImportFinished)
3086 }
3087 app.batchImporter.finished.connect(onAutomaticImportFinished)
3088 app.batchImport(profile, tagv2)
3089 }
3090 function renameDirectory(format) {
3092 function onRenameActionsScheduled() {
3093 app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
3094 app.performRenameActions()
3095 }
3096 app.renameActionsScheduled.connect(onRenameActionsScheduled)
3097 app.renameDirectory(tagv2v1, format, false)
3098 }
3099 Configuration Objects
3101 The different configuration sections are accessible via methods of
3102 configs. Their properties can be listed in the QML console.
3103 script.properties(configs.networkConfig())
3105 Properties can be set:
3107 configs.networkConfig().useProxy = false
3109 configs.batchImportConfig()
3113 configs.exportConfig()
3114 configs.fileConfig()
3115 configs.filenameFormatConfig()
3116 configs.filterConfig()
3117 configs.findReplaceConfig()
3118 configs.guiConfig()
3119 configs.importConfig()
3120 configs.mainWindowConfig()
3121 configs.networkConfig()
3122 configs.numberTracksConfig()
3123 configs.playlistConfig()
3124 configs.renDirConfig()
3125 configs.tagConfig()
3126 configs.tagFormatConfig()
3127 configs.userActionsConfig()
3128
3130 Urs Fleisch <ufleisch at users.sourceforge.net>
3131 Software development
3132
3134 Copyright © 2023 Urs Fleisch
3135 FDL
3137
3140 1. gnudb.org
3141 http://gnudb.org
3142 2. MusicBrainz
3144 http://musicbrainz.org
3145 3. Discogs
3147 http://discogs.com
3148 4. Amazon
3150 http://www.amazon.com
3151 5. ID3 specification
3153 http://id3.org/id3v2.4.0-frames
3154 6. SYLT Editor
3156 http://www.compuphase.com/software_sylteditor.htm
3157 7. www.gnudb.org
3159 http://www.gnudb.org
3160 8. Discogs
3162 https://www.discogs.com/
3163 9. freedb.org
3165 http://freedb.org
3166 10. ID3 tag version 2.3.0
3168 http://id3.org/id3v2.3.0
3169 11. ID3 tag version 2.4.0 - Main Structure
3171 http://id3.org/id3v2.4.0-structure
3172 12. LyricWiki
3174 http://www.lyricwiki.org
3175 13. Google
3177 http://www.google.com
3178 14. id3lib
3180 http://id3lib.sourceforge.net
3181 15. libogg
3183 http://xiph.org/ogg/
3184 16. libvorbis, libvorbisfile
3186 http://xiph.org/vorbis/
3187 17. libFLAC++ and libFLAC
3189 http://flac.sourceforge.net
3190 18. TagLib
3192 http://taglib.github.io/
3193 19. mp4v2
3195 https://mp4v2.org/
3196 20. Chromaprint
3198 http://acoustid.org/chromaprint
3199 21. libav
3201 http://libav.org/
3202 22. FDL
3204 http://www.gnu.org/licenses/licenses.html#FDL
3205 23. GPL
3207 http://www.gnu.org/licenses/licenses.html#GPL
3208 24. Qt(TM)
3210 https://www.qt.io
3211 25. KDE
3213 http://www.kde.org
32143.9.4 2023-07-09 KID3(1)