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 directory.
20 FILE
22 If FILE is the path to a directory, it will be opened. If one or
23 more file paths are given, their common directory is opened and the
24 files 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 few
68 mouse clicks and key strokes as possible. Where most other programs can
69 edit either ID3v1 or ID3v2 tags, Kid3 has full control over both
70 versions, can convert tags between the two formats and has access to
71 all ID3v2 tags. Tags of multiple files can be set to the same value,
72 e.g. the artist, album, year and genre of all files of an album
73 typically have the same values and can be set together. If the
74 information for the tags is contained in the file name, the tags can be
75 automatically set from the file name. It is also possible to set the
76 file name according to the tags found in the file in arbitrary formats.
77 The editing task is further supported by automatic replacement of
79 characters or substrings, for instance to remove illegal characters
80 from filenames. Automatic control of upper and lower case characters
81 makes it easy to use a consistent naming scheme in all tags.
82 The tag information for full albums can be taken from gnudb.org[1],
84 TrackType.org[2], MusicBrainz[3], Discogs[4], Amazon[5] or other
85 sources of track lists. The import format is freely configurable by
86 regular expressions.
87 Please report any problems or feature requests to the author.
89
91 Kid3 features
92 · Edit ID3v1.1 tags
93 · Edit all ID3v2.3 and ID3v2.4 frames
95 · Edit tags of multiple files
97 · Convert between ID3v1 and ID3v2 tags
99 · Edit MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2,
101 Speex, TrueAudio, WavPack, WMA, WAV and AIFF tags
102 · Generate tags from filename
104 · Generate tags from the contents of tag fields
106 · Generate filename from tags
108 · Generate and change directory names from tags
110 · Generate playlist file
112 · Automatic case conversion and string translation
114 · Import from gnudb.org[1], TrackType.org[2], MusicBrainz[3],
116 Discogs[4], Amazon[5] and other data sources
117 · Export as CSV, HTML, playlist, Kover XML and other formats.
119 Exported CSV files can be imported again.
120 Example Usage
122 This section describes a typical session with Kid3. Let's assume we
123 have a directory containing MP3 files with the tracks from the album
124 "Let's Tag" from the band "One Hit Wonder". The directory is named in
125 the "artist - album" format, in our case One Hit Wonder - Let's Tag.
126 The directory contains the tracks in the "track title.mp3" format,
127 which I think is useful because the filenames are short (important when
128 using mobile MP3 players with small displays) and in the correct order
129 when sorted alphabetically (important when using hardware MP3 players
130 which play the tracks in alphabetical order or in the order in which
131 they are burnt on CD and that order is alphabetical when using
132 mkisofs). Besides this, the artist and album information is already in
133 the directory name and does not have to be repeated in the filename.
134 But back to our example, the directory listing looks like this:
135 01 Intro.mp3
137 02 We Only Got This One.mp3
139 03 Outro.mp3
141 These files have no tags yet and we want to generate them using Kid3.
143 We use Open (File menu or toolbar) and select one of the files in this
144 directory. All files will be displayed in the file listbox. Lazy as we
145 are, we want to use the information in the directory and file names to
146 generate tags. Therefore we select all files, then click the To: Tag 1
147 button in the File section. This will set the title, artist, album and
148 track values in all files. To set the year and genre values of all
149 files, we keep all files selected and type in "2002" for the Date and
150 select "Pop" from the Genre combobox. To set only these two values,
151 their checkboxes are automatically checked and all other checkboxes are
152 left unchecked. Now we change the selection by only selecting the first
153 file and we see that all tags contain the correct values. The tags of
154 the other files can be verified too by selecting them one by one. When
155 we are satisfied with the tags, we use Save (File menu or toolbar).
156 Selecting Create Playlist from the File menu will generate a file One
157 Hit Wonder - Let's Tag.m3u in the directory.
158
160 The GUI Elements
161 The Kid3 GUI is separated in six sections: At the left are the file and
162 directory listboxes, the right side contains the File, Tag 1, Tag 2 and
163 Tag 3 sections.
164 File List
166 The file list contains the names of all the files in the opened
167 directory which match the selected file name filter (typically
168 *.mp3 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4
169 *.mp2 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). A single or
170 multiple files can be selected. To select no file, click into the
171 empty area after the listbox entries. The selection determines the
172 files which are affected by the operations which are available by
173 using the buttons described below.
174 Besides Name, also other columns Size, Type, Date Modified with
176 file details can be displayed. Columns can be hidden by unchecking
177 their name in the context menu of the list header. The order of the
178 columns can be changed by drag and drop. The sort order can be
179 toggled by clicking on the column header.
180 At the left of the names an icon can be displayed: a disc to show
182 that the file has been modified or information about which tags are
183 present (V1, V2, V1V2 or NO TAG, no icon is displayed if the file
184 has not been read in yet).
185 Directories are displayed with a folder icon. If a directory is
187 opened, its files are displayed in a hierarchical tree. By
188 selecting files from subdirectories, operations can be executed on
189 files in different directories, which is useful if the music
190 collection is organized with a folder for each artist containing
191 folders for albums of this artist.
192 Clicking the right mouse button inside the file list opens a
194 context menu with the following commands:
195 · Expand all: Expands all folder trees (only the current tree if
197 the shift key is pressed)
198 · Collapse all: Collapses all folder trees
200 · Rename: Changes the name of a file
202 · Move to Trash: Moves a file to the trash
204 · Play: Plays a file, see Play. If the selected file is a
206 playlist, the files of the playlist will be played.
207 · Edit: Edit a playlist, see Edit Playlist.
209 · The subsequent entries are user commands, which can be defined
211 in the User Actions tab of Configure Kid3. The playback on
212 double click can also be activated there.
213 Edit Playlist
216 A playlist can be created empty or containing the tracks of a
217 folder, see Create Playlist. The playlist file created in such a
218 way can be edited by double click or using Edit from the file list
219 context menu. A dialog with the entries of the playlist is shown.
220 It is possible to open multiple playlists simultaneously.
221 New entries can be added by drag and drop from the file list, a
223 file manager or another playlist. If an entry is dragged from
224 another playlist, it will be moved or copied depending on the
225 system. To invoke the other operation, respectively, the Shift,
226 Ctrl or Alt (to copy instead of move on macOS) key has to be
227 pressed. Reordering entries within the playlist is also possible
228 via drag and drop. Alternatively, entries can be moved using the
229 keyboard shortcuts Ctrl+Shift+Up and Ctrl+Shift+Down (on macOS
230 Command has to be pressed instead of Ctrl). An entry can be removed
231 using the Delete key.
232 Please note the following: To drag entries from the file list, they
234 have to be held at the left side (near the icons), the same gesture
235 at the right side will perform a multi selection, such an action is
236 hereby still easily possible.
237 When a playlist has been modified, the changes can be stored using
239 Save or discarded using Cancel. When the window is closed, a
240 confirmation prompt is shown if there are unsaved changes.
241 Tracks selected in a playlist will be automatically selected in the
243 file list, thereby making it possible to edit their tags.
244 To execute actions on a playlist, its file must be selected in the
246 file list. Edit from the context menu will lead to the dialog
247 described in this section, and Play will start the media player
248 with the tracks from the playlist. User actions can act on
249 playlists, for example Export Playlist Folder, which copies the
250 files from a playlist into a folder.
251 Directory List
253 The directory list contains the names of the directories in the
254 opened directory, as well as the current (.) and the parent (..)
255 directory. It allows one to quickly change the directory without
256 using the Open... command or drag and drop.
257 Column visibility, order and sorting can be configured as described
259 in the section about the file list.
260 File
262 Shows information about the encoding (MP3, Ogg, Opus, DSF, FLAC,
263 MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV,
264 AIFF), bit rate, sample rate, channels and the length of the file.
265 The Name line edit contains the name of the file (if only a single
267 file is selected). If this name is changed, the file will be
268 renamed when the Save command is used.
269 The Format combo box and line edit contains the format to be used
271 when the filename is generated from the first or the second tag.
272 The filename can contain arbitrary characters, even a directory
273 part separated by a slash from the file name, but that directory
274 must already exist for the renaming to succeed. The following
275 special codes are used to insert tag values into the filename:
276 · %s %{title} Title (Song)
278 · %a %{artist} Artist
280 · %l %{album} Album
282 · %c %{comment} Comment
284 · %y %{year} Year
286 · %t %{track} Track (e.g. 01)
288 · %t %{track.n} Track with field width n (e.g. 001 for
290 %{track.3})
291 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
293 · %g %{genre} Genre
295 · %{ignore} Ignored when generating tags from the file name
297 The format codes are not restricted to the examples given above.
299 Any frame name can be used, for instance unified frame names like
300 %{albumartist}, %{discnumber.1}, %{bpm} or format specific names
301 like %{popm}.
302 It is possible to prepend and append strings to the replacement for
304 a format code by adding them in double quotes inside the curly
305 braces of a format code. These strings will only be put into the
306 resulting string if the format code yields a nonempty value. For
307 example, if the file name shall both contain the title and the
308 subtitle, one could use %{title} [%{subtitle}] in the format
309 string. But this would result in a string ending with [] if no
310 subtitle frame exists for a file. In order to omit the brackets if
311 no subtitle is present, %{title}%{" ["subtitle"]"} shall be used
312 instead. This will omit the brackets, the leading space and the
313 subtitle if not subtitle exists.
314 The list of available formats can be edited in the dialog which
316 appears when clicking the Filename from tag button in the File tab
317 of the settings.
318 A second Format combo box (with arrow down) is used to generate the
320 tags from the filename. If the format of the filename does not
321 match this pattern, a few other commonly used formats are tried.
322 Some commonly used filename formats are already available in the
324 combo box, but it is also possible to type in some special format
325 into the line edit.
326 The list of available formats can be edited in the dialog which
328 appears when clicking the Tag from filename button in the File tab
329 of the settings.
330 Internally, a regular expression is built from the format codes. If
332 advanced regular expressions are required, the format to generate
333 the tags from the filenames can be given as a complete regular
334 expression with captures which are preceded by the format codes,
335 e.g. to extract the track numbers without removal of leading zeros,
336 a format like "/%{track}(\d+) %{title}(.*)" could be used.
337 From: Tag 1, Tag 2: Sets the filename using the selected format and
339 the first tag or the second tag, respectively.
340 To: Tag 1, Tag 2: The tags are set from the filename. First, the
342 format specified in Format is used. If the existing filename does
343 not match this format, the following formats are tried:
344 · Artist - Album/Track Song
346 · Album/Track - Artist - Song
348 · /Artist - Album - Track - Song
350 · Album/Artist - Track - Song
352 · Album/Artist - Song
354 · Artist/Album/Track Song
356 If a single file is selected, the GUI controls are filled with the
358 values extracted from the filename. If multiple files are selected,
359 the tags of the files are directly set according to the filenames.
360 Tag 1
362 The line edit widgets for Title, Artist, Album, Comment, Date,
363 Track Number and Genre are used to edit the corresponding value in
364 the first tag of the selected files. The value will be changed when
365 the file selection is altered or before operations like Save and
366 Quit and when the corresponding check box at the left of the field
367 name is checked. This is useful to change only some values and
368 leave the other values unchanged.
369 If a single file is selected, all check boxes are checked and the
371 line edit widgets contain the values found in the tags of this
372 file. If a tag is not found in the file, the corresponding empty
373 value is displayed, which is an empty string for the Title, Artist,
374 Album and Comment line edits, 0 for the numerical Date and Track
375 Number edits and an empty selected value for the Genre combo box.
376 The values can be changed and if the corresponding check box is
377 checked, they will be set for the selected file after the selection
378 is changed. The file is then marked as modified by a disk symbol in
379 the file listbox but remains unchanged until the Save command is
380 used.
381 If multiple files are selected, only the values which are identical
383 in all selected files are displayed. In all other controls, the
384 empty values as described above are displayed. All check boxes are
385 unchecked to avoid unwanted changes. If a value has to be set for
386 all selected files, it can be edited and the checkbox has to be
387 set. The values will be set for all selected files when the
388 selection is changed and can be saved using the Save command.
389 The check boxes also control the operation of most commands
391 affecting the tags, such as copy, paste and transfer between tags 1
392 and 2. To make it easier to use with multiple files where all check
393 boxes are unchecked, these commands behave in the same way when all
394 check boxes are checked and when all check boxes are unchecked.
395 From Tag 2: The tag 1 fields are set from the corresponding values
397 in tag 2. If a single file is selected, the GUI controls are filled
398 with the values from tag 2. If multiple files are selected, the
399 tags of the files are directly set.
400 Copy: The copy buffer is filled with the Tag 1 values. Only values
402 with checked checkbox will be used in subsequent Paste commands.
403 Paste: Pastes the values from the copy buffer into the GUI
405 controls.
406 Remove: This will set all GUI controls to their empty values which
408 results in removing all values. The saved file will then contain no
409 tag 1.
410 Tag 2
412 The GUI controls function in the same way as described for the Tag
413 1 section, but the size of the strings is not limited.
414 For the tag 2 Genre you can also use your own names besides the
416 genres listed in the combo box, just type the name into the line
417 edit.
418 The tag 2 can not only contain the same values as the tag 1, the
420 format is built in a flexible way from several frames which are
421 themselves composed of several fields. The tag 2 table shows all
422 the frames which are available in the selected file.
423 Edit: This will open a window which allows one to edit all fields
425 of the selected frame. If multiple files are selected, the edited
426 fields are applied to all selected files which contain such a
427 frame.
428 Add: A requester to select the frame type will appear and a frame
430 of the selected type can be edited and added to the file. This
431 works also to add a frame to multiple selected files.
432 Delete: Deletes the selected frame in the selected files.
434 Drag album artwork here is shown if the file does not contain
436 embedded cover art. A picture can be added using drag and drop from
437 a browser or file manager and will be displayed here. Picture
438 frames can be edited or added by double clicking on this control.
439 Tag 3
441 Some files can have more than two tags, and a third tag section is
442 visible. The following file types can have such a Tag 3 section:
443 · MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0)
445 tag and in the third section an APE tag. Such APE tags are used
446 for replay gain information. In the Tag 3 section, this
447 information is visible, and the APE tag can be removed with the
448 Remove button.
449 · The RIFF INFO chunk of WAV files is available in the Tag 3
451 section because the Tag 1 section is dedicated to ID3v1.1 tags
452 and handles their restrictions. The Tag 2 is still used for
453 ID3v2.4.0 tags, which are also supported for WAV files, but
454 RIFF INFO chunks seem to be supported better.
455 · FLAC files normally use a Vorbis comment for their meta data.
457 However, there are FLAC files which have IDv1 and ID3v2 tags,
458 which can be found in the Tag 1 and Tag 3 sections. ID3 tags in
459 FLAC files are only supported by TagLib, therefore the
460 OggFlacMetadata plugin has to be disabled in the Plugins tab of
461 the settings.
462 The GUI controls work in the same way as in the Tag 2 section.
464 Synchronized Lyrics and Event Timing Codes
466 For information synchronized with the audio data, a specific editor
467 is available. These frames are supported for ID3v2.3.0 and
468 ID3v2.4.0 tags. To add such a frame, the specific frame name has to
469 be selected in the list which appears when the Add button is
470 clicked - Synchronized Lyrics or Event Timing Codes, respectively.
471 The editor is the same for both types, for the event timing codes,
472 only a predefined set of events is available whereas for the
473 synchronized lyrics, text has to be entered. In the following,
474 editing synchronized lyrics is explained.
475 A file having an ID3v2 tag is selected, the lyrics editor is
477 entered using Add and selecting Synchronized Lyrics. For an
478 existing Synchronized Lyrics frame, it is selected and Edit is
479 clicked. The player is automatically opened with the current file
480 so that the file can be played and paused to synchronize lyrics.
481 The settings at the top of the SYLT editor normally do not have to
483 be changed. If the lyrics contains characters which are not present
484 in the Latin 1 character set, changing the text encoding to UTF16
485 (or UTF8 for ID3v2.4.0) is advisable. For English lyrics and
486 maximum compatibility, ISO-8859-1 should be used.
487 The Lyrics section has five buttons at the top. Add will add a new
489 time event in the table. The time is taken from the position of the
490 player, thus adding an entry while playing the track will add a
491 line for the currently played position. The events in the table
492 have to be chronologically ordered, therefore the row will be
493 inserted accordingly. Entries with an invalid time are treated
494 specially: If the currently selected row has an invalid time, its
495 time stamp will be replaced by the current time instead of adding a
496 new row. If the current time is not invalid, the first row with an
497 invalid time will be used if present. This behavior should
498 facilitate adding time stamps if the lyrics text is already in the
499 table but the time stamps are missing (which is the case when
500 importing unsynchronized lyrics). Note that the invalid time is
501 represented as 00:00.00, i.e. the same as the time at the absolute
502 beginning of the track, which is not invalid. To make a time
503 invalid, press the Delete key, or use Clear from the context menu.
504 New rows inserted using Insert row from the context menu or created
505 when importing unsynchronized lyrics with From Clipboard or Import
506 also contain invalid time stamps. Rows in the table can be deleted
507 by clicking the Delete button or using Delete rows from the context
508 menu.
509 Synchronized lyrics can be imported from a file using Import. The
511 expected format is simple or enhanced LRC. If the selected file
512 does not contain a square bracket in the first line, it is supposed
513 to be a simple text file with unsynchronized lyrics. The lines from
514 such a file are then imported having invalid time stamps. The time
515 information can be added using the Add button or by manual entry.
516 It is also possible to import lyrics via copy-paste using From
517 Clipboard. Synchronized lyrics can be written to LRC files using
518 Export. Note that only entries with valid time stamps will be
519 exported and that the entries will be sorted by time. Entries with
520 invalid time won't be stored in the SYLT frame either, so make sure
521 to include all timing information before leaving the dialog.
522 The ID3 specification[6] suggests a time stamp for each syllable.
524 However most players only support the granularity of a line or
525 sentence. To support both use cases, Kid3 follows the same
526 conventions as SYLT Editor[7]. Text which is entered into the table
527 is assumed to start a new line unless it starts with a space or a
528 hyphen. Exceptions to this rule are possible by starting a line
529 with an underscore ('_') to force continuation or a hash mark ('#')
530 to force a new line. These escape characters are not stored inside
531 the SYLT frame. Inside the SYLT frame, new lines start with a line
532 feed character (hex 0A) whereas continuations do not. When reading
533 SYLT frames, Kid3 checks if the first entry starts with a line
534 feed. If this is not the case, it is assumed that all entries are
535 new lines and that no syllable continuations are used.
536 While the track is played, the row associated with the current
538 playing position is highlighted, so that the correctness of the
539 synchronization information can be verified. If an offset has to be
540 added to one or more time stamps, this can be accomplished with the
541 Add offset context menu. Negative values can be used to reduce the
542 time. Using Seek to position in the context menu, it is possible to
543 set the playing position to the time of the selected row.
544 Recommended procedure to add new synchronized lyrics
546 · Get the unsynchronized lyrics, e.g. using Lyrics → Embed Lyrics
548 from the file list context menu.
549 · Copy the unsynchronized lyrics to the clipboard, just go to the
551 Lyrics row in the frame table and press Ctrl+C.
552 · Add a synchronized lyrics frame (Add..., Synchronized Lyrics,
554 OK), click From Clipboard.
555 · Now all lines from the unsynchronized lyrics are in the table,
557 all time stamps are invalid (0:0:0.00). You can delete empty
558 entries beforehand.
559 · Start playing the song by clicking the play button ► in the
561 play toolbar at the bottom of the main window.
562 · When the next lyrics line with invalid timestamp comes, click
564 Add or press Alt+A, the timestamp will be updated.
565 · Continue like this until all timestamps are set. If you missed
567 something, stop playback and clear the timestamps using the
568 Delete key or by selecting them and using Clear from the
569 context menu. To restart playback from a given timestamp, use
570 Seek to position from the context menu.
571 The File Menu
574 File → Open... (Ctrl+O)
575 Opens a directory. All files matching the selected file name
576 filter will be displayed in the file listbox and the chosen file is
577 selected.
578 File → Open Recent
580 Opens a recently opened directory.
581 File → Open Directory... (Ctrl+D)
583 Opens a directory. All files matching the selected file name
584 filter will be displayed in the file listbox.
585 File → Reload (F5)
587 Reload directory. Modified files have to be saved before. Expanded
588 subfolders will be collapsed.
589 File → Save (Ctrl+S)
591 Saves all changed files in the directory. The changed files are
592 marked with a disk symbol in the file listbox. If any file names
593 have been changed, those files will be renamed.
594 File → Revert
596 Reverts the changes of one or multiple files. If no files are
597 selected in the file listbox, the changes of all files will be
598 reverted, else only the changes of the selected files are reverted.
599 File → Import...
601 The Import dialog can be used to import data directly from a
602 freedb.org server, from a MusicBrainz server, from Discogs, Amazon
603 or other sources of album track lists in textual format.
604 Import from a freedb.org server is possible using a dialog which
606 appears when From Server: gnudb.org or TrackType.org is selected.
607 The artist and album name to search for can be entered in the two
608 topmost fields, the albums which match the query will be displayed
609 when Find is clicked and the results from www.gnudb.org[8] are
610 received. Importing the track data for an album is done by
611 double-clicking the album in the list. The freedb.org server to
612 import from can be selected as well as the CGI path. The imported
613 data is displayed in the preview table of the import dialog. When
614 satisfied with the displayed tracks, they can be imported by
615 terminating the import dialog with OK.
616 A search on the Discogs server can be performed using Discogs. As
618 in the gnudb.org dialog, you can enter artist and album and then
619 choose from a list of releases. If Standard Tags is marked, the
620 standard information is imported, e.g. artist, album, and title. If
621 Additional Tags is marked, more information is imported if
622 available, e.g. performers, arrangers, or the publisher. If Cover
623 Art is marked, cover art will be downloaded if available.
624 A search on Amazon can be performed using Amazon. As in the
626 gnudb.org dialog, you can enter artist and album and then choose
627 from a list of releases. If Additional Tags is marked, more
628 information is imported if available, e.g. performers, arrangers,
629 or the publisher. If Cover Art is marked, cover art will be
630 downloaded if available.
631 You can search in the same way in the release database of
633 MusicBrainz using From MusicBrainz Release. The workflow is the
634 same as described for From gnudb.org.
635 Import from a MusicBrainz server is possible using the dialog which
637 appears when From MusicBrainz Fingerprint is selected. The Server
638 can be selected as in the freedb import dialog. Below is a table
639 displaying the imported track data. The right column shows the
640 state of the MusicBrainz query, which starts with "Pending" when
641 the dialog is opened. Then the fingerprint is looked up and if it
642 does not yield a result, another lookup using the tags in the file
643 is tried. Thus it can be helpful for a successful MusicBrainz query
644 to store known information (e.g. artist and album) in the tags
645 before the import. If a result was found, the search ends in the
646 state "Recognized", otherwise nothing was found or multiple
647 ambiguous results and one of them has to be selected by the user.
648 OK and Apply use the imported data, Cancel closes the dialog. The
649 closing can take a while since the whole MusicBrainz machinery has
650 to be shut down.
651 For the import of textual data, From File/Clipboard opens a
653 subdialog, where several preconfigured import formats are
654 available. The first two, "CSV unquoted" and "CSV quoted" can be
655 used to import data which was exported by the Export dialog. The
656 CSV data can be edited with a spreadsheet, and shall be written
657 using tabs as delimiters. Import should then be possible using "CSV
658 quoted", which is more flexible than "CSV unquoted". However, its
659 fields cannot contain any double quotes. If you only export from
660 Kid3 and import later, "CSV unquoted" can be used as a simple
661 format for this purpose. Note that there are also "Export CSV" and
662 "Import CSV" commands in the context menu of the file list, which
663 use scripts to export and import CSV data in a more complete,
664 powerful and flexible way.
665 The next format, "freedb HTML text", can be used to copy
667 information from an HTML page of freedb.org[9]. Search an album in
668 freedb and if the desired information is displayed in the web
669 browser, copy the contents to the clipboard. Then click the From
670 Clipboard button and the imported tracks will be displayed in the
671 preview table at the top of the dialog. If you are satisfied with
672 the imported data, terminate the dialog with OK, which will insert
673 the data into the tags of the current directory. The destination
674 (Tag 1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box.
675 The files in the current directory should be in the correct track
676 order to get their tags assigned. This is the case if they are
677 numbered.
678 The next preconfigured import format, "freedb HTML source", can be
680 used, if the data is available as an HTML document. Import is
681 possible using the From File button, which opens a file selector,
682 or copying its contents from an editor and then importing from
683 clipboard. This format can be useful for offline import, although
684 the HTML document could also be opened in a browser and then be
685 imported in the first format via the clipboard.
686 More preconfigured formats, e.g. "Track Title Time", are available.
688 An empty custom format can be created with Add to be set by the
689 user. Two lines below the format name can be set with a regular
690 expression to capture the fields from the import text. The first
691 regular expression will be parsed once per document to gather
692 per-album data such as artist, album, year and genre. The second
693 line is tried to match from the start of the document to the end to
694 get track data, usually number and title. The regular expressions
695 include all the features offered by Qt, which is most of the what
696 Perl offers. Bracketing constructs "(..)" create capture buffers
697 for the fields to import and are preceded by Kid3 specific codes to
698 specify which field to capture. The codes are the same as used for
699 the filename format, besides the codes listed below, any frame name
700 is possible:
701 · %s %{title} Title (Song)
703 · %a %{artist} Artist
705 · %l %{album} Album
707 · %c %{comment} Comment
709 · %y %{year} Year
711 · %t %{track} Track
713 · %g %{genre} Genre
715 · %d %{duration} Duration
717 For example, a track regular expression (second line) to import
719 from an .m3u playlist could be
720 "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]". All formats can
721 be changed by editing the regular expressions and the name and then
722 clicking Save Settings. They will be stored in the kid3rc file in
723 the configuration directory. This file can be directly edited to
724 have more import formats or it can be deleted to revert to the
725 default formats. Formats can be deleted using Remove.
726 Accuracy shows an estimation of how good the imported information
728 matches the given tracks. It uses track durations or file names to
729 calculate the level of similarity in percent. Cover Art shows the
730 URL of the album cover image which will be downloaded.
731 To check whether the imported tracks match the current set of
733 files, the duration of the imported tracks can be compared with the
734 duration of the files. This option can be enabled with the checkbox
735 Check maximum allowable time difference and the maximum tolerated
736 difference in time can be set in seconds. If a mismatch in a length
737 is detected, the length is displayed with a red background in the
738 preview table.
739 If the files are ordered differently than the imported tracks,
741 their assigned tracks have to be changed. This task can be
742 facilitated using the Match with buttons Length, Track, and Title,
743 which will reorder the tracks according to the corresponding field.
744 To correct the assignments manually, a track can be dragged with
745 the left mouse button and the Ctrl key hold down, and then dropped
746 at the new location.
747 When the import dialog is opened, it contains the actual contents
749 of the tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be
750 selected using the Destination combo box. The button on the right
751 of this combo box can be used to revert the table to the current
752 contents of the tags. The checkboxes in the first table column can
753 be used to select the tracks which are imported. This can be useful
754 if a folder contains the tracks of both CDs of a double CD and only
755 the tracks of the second CD have to be imported.
756 To identify the tracks which are imported, it is possible to
758 display the file names or the full paths to the files using the
759 context menu of the table header. The values in the import table
760 can be edited. The revert-button to the right of the Destination
761 combo box can be used to restore the contents of the tags, which
762 can also be useful after changing the Destination.
763 Almost all dialogs feature a Save Settings button, which can be
765 used to store the dialog specific settings and the window size
766 persistently.
767 From Tags leads to a subdialog to set tag frames from the contents
769 of other tag frames. This can be used to simply copy information
770 between tags or extract a part from one frame and insert it in
771 another.
772 As in the import from file/clipboard dialog, there are freely
774 configurable formats to perform different operations. Already
775 preconfigured are formats to copy the Album value to Album Artist,
776 Composer or Conductor, and to extract the Track Number from Title
777 fields which contain a number. There is also a format to extract a
778 Subtitle from a Title field.
779 The following example explains how to add a custom format, which
781 sets the information from the Subtitle field also in the Comment
782 field. Create a new format using Add and set a new name, e.g.
783 "Subtitle to Comment". Then enter "%{subtitle}" in Source and
784 "%{comment}(.*)" for Extraction and click Save Settings.
785 The expression in Source can contain format codes for arbitrary tag
787 frames, multiple codes can be used to combine the contents from
788 different frames. For each track, a text is generated from its tags
789 using the Source format, and the regular expression from Extraction
790 is applied to this text to set new values for the tags. Format
791 codes are used before the capturing parentheses to specify the tag
792 frame where the captured text shall be stored. It works in the same
793 way as for the import from file/clipboard.
794 File → Import from gnudb.org...
796 Import from a freedb.org server using gnudb.org album search. This
797 menu item opens the same import dialog as Import..., but opens
798 directly the gnudb.org dialog.
799 File → Import from TrackType.org...
801 Import from the TrackType.org server. This menu item opens the
802 same import dialog as Import..., but opens directly the
803 TrackType.org dialog.
804 File → Import from Discogs...
806 Import from the Discogs server. This menu item opens the same
807 import dialog as Import..., but opens directly the From Discogs
808 dialog.
809 File → Import from Amazon...
811 Import from Amazon. This menu item opens the same import dialog as
812 Import..., but opens directly the From Amazon dialog.
813 File → Import from MusicBrainz Release...
815 Import from the MusicBrainz release database. This menu item opens
816 the same import dialog as Import..., but opens directly the From
817 MusicBrainz Release dialog.
818 File → Import from MusicBrainz Fingerprint...
820 Import from a MusicBrainz server. This menu item opens the same
821 import dialog as Import..., but opens directly the From MusicBrainz
822 Fingerprint dialog.
823 File → Automatic Import...
825 Automatic Import allows one to import information for multiple
826 albums from various web services. If directories are selected in
827 the file list, track data for the selected directories will be
828 imported. If no directory is selected, all directories in the file
829 list will be imported.
830 The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using
832 the Destination combo box.
833 Profiles determine which servers will be contacted to fetch album
835 information. Some profiles are predefined (All, MusicBrainz,
836 Discogs, Cover Art), custom profiles can be added using the Add
837 button at the right of the Profile combo box.
838 The table below shows the servers which will be used when importing
840 album information using the selected profile. The import process
841 for an album is finished if all required information has been
842 found, so the order of the rows in the table is important. It can
843 be changed using the Move Up and Move Down buttons. Edit can be
844 used to change an existing entry. The Server selection offers the
845 same servers as can be used in the import functions. Standard
846 Tags, Additional Tags, Cover Art determine the information which
847 shall be fetched from the server. Finally, Accuracy is the minimum
848 accuracy which must be achieved to accept the imported data. If the
849 accuracy is insufficient, the next server in the list will be
850 tried. The same dialog containing the server properties appears
851 when Add is clicked to add a new server entry. Existing entries can
852 be deleted using Remove.
853 To launch an automatic batch import with the selected profile,
855 click Start. Details about the running import are displayed at the
856 top of the dialog. The process can be aborted with the Abort
857 button.
858 File → Browse Cover Art...
861 The Browse Cover Art dialog helps to find album cover art.
862 Artist/Album is filled from the tags if possible. Source offers a
863 variety of websites with album cover art. The URL with artist and
864 album as parameters can be found beneath the name. URL-encoded
865 values for artist and album can be inserted using %u{artist} and
866 %u{album}, other values from the tags are possible too, as
867 described in Configure Kid3, User Actions. More sources can be
868 entered after the entry "Custom Source" by replacing "Custom
869 Source" with the source's name, pressing Enter, then inserting the
870 URL and finally pressing Save Settings. The resulting browser
871 command is displayed at the top of the dialog and can be started by
872 clicking Browse. The browser, which can be configured in the
873 settings, is started with the selected source. A cover image can
874 then be dragged from the browser into the Kid3 window and will be
875 set in the picture frame of the selected files.
876 Because not all browsers support drag and drop of images and the
878 pictures on websites often have a URL, in such cases Kid3 will
879 receive the URL and not the picture. If the URL points to a
880 picture, it will be downloaded. However, if the URL refers to some
881 other web resource, it has to be translated to the corresponding
882 picture. Such mappings are defined in the table URL extraction. The
883 left column Match contains a regular expression which is compared
884 with the URL. If it matches, the captured expressions in
885 parentheses are inserted into the pattern of the right Picture URL
886 column (at the positions marked with \1 etc.). The replaced regular
887 expression contains the URL of the picture. By this means cover art
888 can be imported from Amazon, Google Images, etc. using drag and
889 drop. It is also possible to define your own mappings.
890 File → Export...
892 The Export Dialog is used to store data from the tags in a file or
893 the clipboard. The editor at the top shows a preview of the data to
894 export. If the export data contain tabulator characters, the export
895 is displayed in a table. The data will be generated from the tags
896 in the current directory according to the configured format.
897 The format settings are similar as in the Import dialog: The
899 topmost field contains the title (e.g. "CSV unquoted"), followed by
900 the header, which will be generated at the begin of the file. The
901 track data follows; it is used for every track. Finally, the
902 trailer can be used to generate some finishing text.
903 The format fields do not contain regular expressions as in the
905 Import dialog, but only output format expressions with special
906 %-expressions, which will be replaced by values from the tags. The
907 whole thing works like the file name format, and the same codes are
908 used plus some additional codes. Not only the codes listed below
909 but all tag frame names can be used.
910 · %s %{title} Title (Song)
912 · %a %{artist} Artist
914 · %l %{album} Album
916 · %c %{comment} Comment
918 · %y %{year} Year
920 · %t %{track} Track (e.g. 01)
922 · %t %{track.n} Track with field width n (e.g. 001 for
924 %{track.3})
925 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
927 · %g %{genre} Genre
929 · %f %{file} File name
931 · %p %{filepath} Path
933 · %u %{url} URL
935 · %{dirname} Directory name
937 · %d %{duration} Duration in minutes:seconds
939 · %D %{seconds} Duration in seconds
941 · %n %{tracks} Number of tracks of the album
943 · %e %{extension} File extension
945 · %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
947 existing)
948 · %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
950 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
951 existing)
952 · %b %{bitrate} Bit rate in kbit/s
954 · %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
956 · %r %{samplerate} Sample rate in Hz
958 · %m %{mode} Channel mode (Stereo or Joint Stereo)
960 · %h %{channels} Number of channels (1 or 2)
962 · %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
964 MPC, APE, ASF, AIFF, WAV)
965 A few formats are predefined. "CSV unquoted" separates the fields
967 by tabs. Data in this format can be imported again into Kid3 using
968 the import format with the same name. "CSV quoted" additionally
969 encloses the fields by double quotes, which eases the import into
970 spreadsheet applications. However, the fields shall not contain any
971 double quotes when this format is used. "Extended M3U" and
972 "Extended PLS" generate playlists with extended attributes and
973 absolute path names. "HTML" can be used to generate an HTML page
974 with hyperlinks to the tracks. "Kover XML" creates a file which can
975 be imported by the cover printing program Kover. "Technical
976 Details" provides information about bit rate, sample rate,
977 channels, etc. Finally, "Custom Format" is left empty for
978 definition of a custom format. You can define more formats of your
979 own by adding lines in the file kid3rc in the configuration
980 directory. The other formats can be adapted to your needs.
981 The source of the tags to generate the export data (Tag 1 or Tag 2)
983 can be selected with a combo box. Pushing To File or To Clipboard
984 stores the data in a file or on the clipboard. OK and Cancel close
985 the dialog, whereas OK accepts the current dialog settings.
986 File → Create Playlist
988 Creates a playlist. The format and contents of the playlist can be
989 set by various options.
990 The name of the playlist can be the Same as directory name or use a
992 Format with values from the tags, e.g. "%{artist} - %{album}" to
993 have the artist and album name in the playlist file name. The
994 format codes are the same as for Export. Create new empty playlist
995 will make an empty playlist with the given name. The extension
996 depends on the playlist format.
997 The location of the generated playlist is determined by the
999 selection of the Create in combo box.
1000 Current directory
1002 The playlist is created in the current directory and contains
1003 only files of the current directory. The current directory is
1004 the directory where the current file is located. If multiple
1005 files are selected, the current file is probably the last
1006 selected file.
1007 Every directory
1009 A playlist is created in every directory which contains listed
1010 files, and each playlist contains the files of that directory.
1011 Top-level directory
1013 Only one playlist is created in the top-level directory (i.e.
1014 the directory of the file list) and it contains the listed
1015 files of the top-level directory and all of its
1016 sub-directories.
1017 The Format of the playlist can be M3U, PLS or XSPF.
1019 If Include only the selected files is checked, only the selected
1021 files will be included in the playlist. If a directory is selected,
1022 all of its files are selected. If this check box is not activated,
1023 all audio files are included in the playlist.
1024 Sort by file name selects the usual case where the files are
1026 ordered by file name. With Sort by tag field, it is possible to
1027 sort by a format string with values from tag fields. For instance,
1028 "%{track.3}" can be used to sort by track number (the ".3" is used
1029 to get three digits with leading zeros because strings are used for
1030 sorting). It is also possible to use multiple fields, e.g.
1031 "%{genre}%{year}" to sort using a string composed of genre and
1032 year.
1033 The playlist entries will have relative or absolute file paths
1035 depending on whether Use relative path for files in playlist or Use
1036 full path for files in playlist is set.
1037 When Write only list of files is set, the playlist will only
1039 contain the paths to the files. To generate an extended playlist
1040 with additional information, a format string can be set using the
1041 Write info using control.
1042 File → Quit (Ctrl+Q)
1044 Quits the application.
1045 The Edit Menu
1047 Edit → Select All (Alt+A)
1048 Selects all files.
1049 Edit → Deselect (Ctrl+Shift+A)
1051 Deselects all files.
1052 Edit → Select All in Directory
1054 Selects all files of the current directory.
1055 Edit → Previous File (Alt+Up)
1057 Selects the previous file.
1058 Edit → Next File (Alt+Down)
1060 Selects the next file.
1061 Edit → Find... (Ctrl+F)
1063 Find strings in the file names and the tags. The Find dialog is a
1064 subset of the Replace dialog, which is described below.
1065 Edit → Replace... (Ctrl+R)
1067 This function opens a dialog to find and replace strings in the
1068 file names and the tags. The set of frames where the search is
1069 performed can be restricted by deactivating the Select all checkbox
1070 and selecting the frames which shall be searched. There are also
1071 search options available to search backwards, case sensitively, and
1072 to use regular expressions.
1073 Depending on the number of files, the search might take some time,
1075 therefore it can be aborted by closing the dialog.
1076 The Tools Menu
1078 Tools → Apply Filename Format
1079 When Automatically apply format is switched off for the filename
1080 format in the configuration dialog, this menu item can be used to
1081 apply the configured format to the names of the selected files.
1082 This can also be used to check whether the file names conform with
1083 the configured format by applying the format to all saved files and
1084 then checking if any files were changed (and therefore marked with
1085 a disk symbol in the file listbox).
1086 Tools → Apply Tag Format
1088 When Automatically apply format is switched off for the tag format
1089 in the configuration dialog, this menu item can be used to apply
1090 the configured format to the tags of the selected files. This can
1091 also be used to check whether the tags conform with the configured
1092 format by applying the format to all saved files and then checking
1093 if any files were changed (and therefore marked with a disk symbol
1094 in the file listbox).
1095 Tools → Apply Text Encoding
1097 Sets the Text encoding selected in Settings/Configure
1098 Kid3.../Tags/Tag 2 for all selected files. If UTF8 is selected,
1099 UTF16 will be used for ID3v2.3.0 tags because UTF8 is not supported
1100 for this format.
1101 Tools → Rename Directory...
1103 This dialog offers the possibility to automatically rename the
1104 currently open directory according to the tags in the files.
1105 Several formats are preconfigured to include information about
1106 artist, album and year in the directory name. It is also possible
1107 to set a custom format and Edit the list of available formats. The
1108 following special codes are used to insert tag values into the
1109 directory name:
1110 · %s %{title} Title (Song)
1112 · %a %{artist} Artist
1114 · %l %{album} Album
1116 · %c %{comment} Comment
1118 · %y %{year} Year
1120 · %t %{track} Track (e.g. 01)
1122 · %t %{track.n} Track with field width n (e.g. 001 for
1124 %{track.3})
1125 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
1127 · %g %{genre} Genre
1129 · %{dirname} Directory name (e.g. %{year" "}%{dirname} will
1131 prepend the year to the current directory name)
1132 If a directory separator "/" is found in the format, multiple
1134 directories are created. If you want to create a new directory
1135 instead of renaming the current directory, select Create Directory
1136 instead of Rename Directory. The source of the tag information can
1137 be chosen between From Tag 1 and Tag 2, From Tag 1 and From Tag 2.
1138 A preview for the rename operation performed on the first file can
1139 be seen in the From and To sections of the dialog.
1140 Multiple directories can be renamed by selecting them.
1142 Tools → Number Tracks...
1144 If the track numbers in the tags are not set or have the wrong
1145 values, this function can number the tracks automatically in
1146 ascending order. The start number can be set in the dialog. If only
1147 part of the tracks have to be numbered, they must be selected.
1148 When Total number of tracks is checked, the number of tracks will
1150 also be set in the tags.
1151 It is possible to number the tracks over multiple directories. The
1153 folders have to be expanded and selected.
1154 If Reset counter for each directory is checked, track numbering is
1156 restarted with the given number for each directory when multiple
1157 folders are selected.
1158 The number tracks dialog can also be used to format existing track
1160 numbers without changing the values when the check box left to
1161 Start number is deactivated. The total number of tracks will be
1162 added if the corresponding check box is active, which can be used
1163 to set the total for all selected tracks. If only formatting of the
1164 existing numbers is desired, this check box has to be deactivated
1165 too.
1166 Tools → Filter...
1168 The filter can be used to display only those files which match
1169 certain criteria. This is helpful if you want to organize a large
1170 collection and only edit those files which are not in the desired
1171 scheme. The expression defining which files to display uses the
1172 same format codes which are used in the file name format, import
1173 and export.
1174 · %s %{title} Title (Song)
1176 · %a %{artist} Artist
1178 · %l %{album} Album
1180 · %c %{comment} Comment
1182 · %y %{year} Year
1184 · %t %{track} Track (e.g. 01)
1186 · %t %{track.n} Track with field width n (e.g. 001 for
1188 %{track.3})
1189 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
1191 · %g %{genre} Genre
1193 · %f %{file} File name
1195 · %p %{filepath} Absolute path to file
1197 · %e %{extension} File extension
1199 · %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1201 existing)
1202 · %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1204 ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
1205 existing)
1206 · %b %{bitrate} Bit rate in kbit/s
1208 · %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
1210 · %r %{samplerate} Sample rate in Hz
1212 · %m %{mode} Channel mode (Stereo or Joint Stereo)
1214 · %h %{channels} Number of channels (1 or 2)
1216 · %k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1218 MPC, APE, ASF, AIFF, WAV)
1219 · %w %{marked} Marked, is 1 if the file is marked (e.g. because
1221 of truncation or standard violation), empty otherwise
1222 · %1a %1{artist}, ... Use the prefix 1 to get values of tag 1
1224 · %2a %2{artist}, ... Use the prefix 2 to get values of tag 2
1226 These codes are replaced with the values for the file, and the
1228 resulting strings can be compared with the following operations:
1229 · s1 equals s2: true if s1 and s2 are equal.
1231 · s1 contains s2: true if s1 contains s2, i.e. s2 is a substring
1233 of s1.
1234 · s matches re: true if s matches the regular expression re.
1236 True expressions are replaced by 1, false by 0. True values are
1238 represented by 1, true, on and yes, false values by 0, false, off
1239 and no. Boolean operations are not, and, or (in this order of
1240 precedence) and can be grouped by parentheses.
1241 Some filter rules are predefined and can serve as examples for your
1243 own expressions:
1244 All
1246 When the file list is filtered - this is shown by "[filtered]"
1247 in the window title - and all files shall be displayed again,
1248 the filtering can be reverted using this filter. It uses an
1249 empty expression, but a true value would have the same effect.
1250 Filename Tag Mismatch
1252 not (%{filepath} contains "%{artist} - %{album}/%{track}
1253 %{title}")
1254 Tests if the file path conforms with the file name format. This
1256 rule is automatically adapted if the file name format changes.
1257 No Tag 1
1259 %{tag1} equals ""
1260 Displays only files which do not have a tag 1.
1262 No Tag 2
1264 %{tag2} equals ""
1265 Displays only files which do not have a tag 2.
1267 ID3v2.3.0 Tag
1269 %{tag2} equals "ID3v2.3.0"
1270 Displays only files which have an ID3v2.3.0 tag.
1272 ID3v2.4.0 Tag
1274 %{tag2} equals "ID3v2.4.0"
1275 Displays only files which have an ID3v2.4.0 tag.
1277 Tag 1 != Tag 2
1279 not (%1{title} equals %2{title} and %1{album} equals %2{album}
1280 and %1{artist} equals %2{artist} and %1{comment} equals
1281 %2{comment} and %1{year} equals %2{year} and %1{track} equals
1282 %2{track} and %1{genre} equals %2{genre})
1283 Displays files with differences between tag 1 and tag2.
1285 Tag 1 == Tag 2
1287 %1{title} equals %2{title} and %1{album} equals %2{album} and
1288 %1{artist} equals %2{artist} and %1{comment} equals %2{comment}
1289 and %1{year} equals %2{year} and %1{track} equals %2{track} and
1290 %1{genre} equals %2{genre}
1291 Displays files with identical tag 1 and tag 2.
1293 Incomplete
1295 %{title} equals "" or %{artist} equals "" or %{album} equals
1296 "" or %{year} equals "" or %{tracknumber} equals "" or %{genre}
1297 equals ""
1298 Displays files with empty values in the standard tags (title,
1300 artist, album, date, track number, genre).
1301 No Picture
1303 %{picture} equals ""
1304 Displays only files which do not have a picture.
1306 Marked
1308 not (%{marked} equals "")
1309 Displays only files which are marked because they violate the
1311 ID3 standard, are truncated or the picture is too large.
1312 Custom Filter
1314 To add your own filter, select this entry. For instance, if you
1315 want to have a filter for artists starting with "The", replace
1316 "Custom Filter" with the name "The Bands" and press Enter. Then
1317 insert the following expression into the line edit:
1318 %{artist} matches "The.*"
1320 Then click Save Settings. Click Apply to filter the files. All
1322 files processed are displayed in the text view, with a "+" for
1323 those who match the filter and a "-" for the others. When
1324 finished, only the files with an artist starting with "The" are
1325 displayed, and the window title is marked with "[filtered]".
1326 Tools → Convert ID3v2.3 to ID3v2.4
1328 If there are any ID3v2.3 tags in the selected files, they will be
1329 converted to ID3v2.4 tags. Frames which are not supported by TagLib
1330 will be discarded. Only files without unsaved changes will be
1331 converted.
1332 Tools → Convert ID3v2.4 to ID3v2.3
1334 If there are any ID3v2.4 tags in the selected files, they will be
1335 converted to ID3v2.3 tags. Only files without unsaved changes will
1336 be converted.
1337 Tools → Play
1339 This opens a simple toolbar to play audio files. It contains
1340 buttons for the basic operations (Play/Pause, Stop playback,
1341 Previous Track, Next Track, Close), sliders for position and volume
1342 and a display of the current position. If multiple files are
1343 selected, the selected tracks are played, else all files will be
1344 played.
1345 The Settings Menu
1347 Settings → Show Toolbar
1348 Toggles displaying of the toolbar.
1349 Settings → Show Statusbar
1351 Toggles displaying of the statusbar, which displays longer actions
1352 such as opening or saving a directory.
1353 Settings → Show Picture
1355 Toggles displaying of the album cover art preview picture.
1356 Settings → Auto Hide Tags
1358 Empty tags are automatically hidden if this option is active. The
1359 File, Tag 1 and Tag 2 sections can be manually collapsed and
1360 expanded by clicking on the corresponding -/+ buttons.
1361 Settings → Configure Kid3...
1363 Opens the configuration dialog, which consists of pages for tags,
1364 files, user actions, and network settings.
1365 Tag specific options can be found on the Tags page, which is itself
1367 separated into four tabs for Tag 1, Tag 2, Tag 3, and All Tags.
1368 If Mark truncated fields is checked, truncated ID3v1.1 fields will
1370 be marked red. The text fields of ID3v1.1 tags can only have 30
1371 characters, the comment only 28 characters. Also the genre and
1372 track numbers are restricted, so that fields can be truncated when
1373 imported or transferred from ID3v2. Truncated fields and the file
1374 will be marked red, and the mark will be removed after the field
1375 has been edited.
1376 With Text encoding for ID3v1 it is possible to set the character
1378 set used in ID3v1 tags. This encoding is supposed to be ISO-8859-1,
1379 so it is recommended to keep this default value. However, there are
1380 tags around with different encoding, so it can be set here and the
1381 ID3v1 tags can then be copied to ID3v2 which supports Unicode.
1382 The check box Use track/total number of tracks format controls
1384 whether the track number field of ID3v2 tags contains simply the
1385 track number or additionally the total number of tracks in the
1386 directory.
1387 When Genre as text instead of numeric string is checked, all ID3v2
1389 genres will be stored as a text string even if there is a
1390 corresponding code for ID3v1 genres. If this option is not set,
1391 genres for which an ID3v1 code exists are stored as the number of
1392 the genre code (in parentheses for ID3v2.3). Thus the genre Metal
1393 is stored as "Metal" or "(9)" depending on this option. Genres
1394 which are not in the list of ID3v1 genres are always stored as a
1395 text string. The purpose of this option is improved compatibility
1396 with devices which do not correctly interpret genre codes.
1397 When WAV files with lowercase id3 chunk is checked, the RIFF chunk
1399 used to store ID3v2 tags in WAV files will be named "id3 " instead
1400 of "ID3 ". By default, Kid3 and other applications using TagLib
1401 accept both the lowercase and the uppercase variant when reading
1402 WAV files, but they use "ID3 " when writing ID3v2 tags to WAV
1403 files. As there exist other applications which only accept "id3 "
1404 (e.g. JRiver Media Center and foobar2000), this option can be used
1405 to create tags which can be read by such applications.
1406 When Mark standard violations is checked, ID3v2 fields which
1408 violate the standard will be marked red. Details about the
1409 violation are shown in a tooltip:
1410 · Must be unique
1412 · New line is forbidden
1414 · Carriage return is forbidden
1416 · Owner must be non-empty
1418 · Must be numeric
1420 · Must be numeric or number/total
1422 · Format is DDMM
1424 · Format is HHMM
1426 · Format is YYYY
1428 · Must begin with a year and a space character
1430 · Must be ISO 8601 date/time
1432 · Must be musical key, 3 characters, A-G, b, #, m, o
1434 · Must have ISO 639-2 language code, 3 lowercase characters
1436 · Must be ISRC code, 12 characters
1438 · Must be list of strings separated by '|'
1440 · Has excess white space
1442 The ID3 standard documents are available online:
1444 · ID3 tag version 2.3.0[10]
1446 · ID3 tag version 2.4.0 - Main Structure[11]
1448 · ID3 tag version 2.4.0 - Native Frames[6]
1450 Text encoding defines the default encoding used for ID3v2 frames
1452 and can be set to ISO-8859-1, UTF16, or UTF8. UTF8 is not valid
1453 for ID3v2.3.0 frames; if it is set, UTF16 will be used instead. For
1454 ID3v2.4.0 frames, all three encodings are possible.
1455 Version used for new tags determines whether new ID3v2 tags are
1457 created as version 2.3.0 or 2.4.0.
1458 Track number digits is the number of digits in Track Number fields.
1460 Leading zeros are used to pad. For instance, with a value of 2 the
1461 track number 5 is set as "05".
1462 The combo box Comment field name is only relevant for Ogg/Vorbis
1464 and FLAC files and sets the name of the field used for comments.
1465 Different applications seem to use different names, "COMMENT" for
1466 instance is used by xmms, whereas amaroK uses "DESCRIPTION".
1467 The format of pictures in Ogg/Vorbis files is determined by Picture
1469 field name, which can be METADATA_BLOCK_PICTURE or COVERART. The
1470 first is the official standard and uses the same format as pictures
1471 in FLAC tags. COVERART is an earlier unofficial way to include
1472 pictures in Vorbis comments. It can be used for compatibility with
1473 legacy players.
1474 If the Mark if larger than check box is activated, files containing
1476 embedded album cover art exceeding the given size in bytes are
1477 marked red. This can be used to find files containing oversized
1478 pictures which are not accepted by some applications and players.
1479 The default value is 131072 bytes (128 KB).
1480 Custom Genres can be used to define genres which are not available
1482 in the standard genre list, e.g. "Gothic Metal". Such custom genres
1483 will appear in the Genre combo box of Tag 2. For ID3v1.1 tags, only
1484 the predefined genres can be used.
1485 The list of custom genres can also be used to reduce the number of
1487 genres available in the Genre combo box to those typically used. If
1488 your collection mostly contains music in the genres Metal, Gothic
1489 Metal, Ancient and Hard Rock, you can enter those genres and mark
1490 Show only custom genres. The Tag 2 Genre combo box will then only
1491 contain those four genres and you will not have to search through
1492 the complete genres list for them. In this example, only Metal and
1493 Hard Rock will be listed in the tag 1 genres list, because those
1494 two custom genres entries are standard genres. If Show only custom
1495 genres is not active, the custom genres can be found at the end of
1496 the genres list.
1497 Quick Access Frames defines which frame types are always shown in
1499 the Tag 2 section. Such frames can then be added without first
1500 using the Add button. The order of these quick access frames can be
1501 changed by dragging and dropping items.
1502 The combo box Track number field name is only relevant for RIFF
1504 INFO and sets the name of the field used for track numbers. Track
1505 numbers are not specified in the original RIFF standard, there are
1506 applications which use "ITRK", others use "IPRT".
1507 Tag Format contains options for the format of the tags. When
1509 Automatically apply format is checked, the format configuration is
1510 automatically used while editing text in the line edits. The Case
1511 conversion can be set to No changes, All lowercase, All uppercase,
1512 First letter uppercase or All first letters uppercase. To use
1513 locale-aware conversion between lowercase and uppercase characters,
1514 a locale can be selected in the combobox below. The string
1515 replacement list can be set to arbitrary string mappings. To add a
1516 new mapping, select the From cell of a row and insert the text to
1517 replace, then go to the To column and enter the replacement text.
1518 To remove a mapping set the From cell to an empty value (e.g. by
1519 first typing space and then backspace). Inserting and deleting rows
1520 is also possible using a context menu which appears when the right
1521 mouse button is clicked. Replacement is only active, if the String
1522 replacement checkbox is checked.
1523 The table in Rating contains the mapping of star ratings to the
1525 effective values stored in the tag. The frames with rating
1526 information are listed in the Rating row of the frame list. For
1527 these frames, the rating can be set by giving a number of stars out
1528 of five stars. Different tag formats and different applications use
1529 different values to map the star rating to the value stored in the
1530 tag. In order to display the correct number of stars, Kid3 will
1531 look up a map in this table. The key to look up the mapping is the
1532 frame name, for example "RATING" as used for Vorbis comments or
1533 "IRTD" for RIFF INFO. For ID3v2 tags, a combined key is used
1534 consisting of the frame ID "POPM" of the Popularimeter frame and
1535 its "Email" field, separated by a dot. Therefore, different keys
1536 for ID3v2 exist, e.g. "POPM.Windows Media Player 9 Series" for the
1537 mapping used by Windows Media Player and Explorer, and simply
1538 "POPM" for POPM frames with an empty "Email" field. As multiple
1539 entries for "POPM" can exist, their order is important. When Kid3
1540 adds a new Popularimeter frame, it will use the first "POPM" entry
1541 to determine the value to be written into the "Email" field. This
1542 value will then specify the mapping to be used for star ratings.
1543 The first entry is also used if no key was found, it is therefore
1544 the default entry.
1545 Besides the Name column containing the keys, the table has columns
1547 1 to 5 for the values to be stored when the corresponding number of
1548 stars is given. The other way round, the values determine the
1549 number of stars which are displayed for the value stored in the
1550 frame. For instance, the row in the table below contains the values
1551 1, 64, 128, 196, 255. The thresholds for the number of stars to be
1552 displayed lay between these values and are compatible with what the
1553 Windows Explorer uses.
1554 Table 1. Entry in Rating Table
1556 ┌──────┬──────┬───────┬────────┬─────────┬─────────┐
1557 │Name │ 1 │ 2 │ 3 │ 4 │ 5 │
1558 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1559 │POPM │ 1 │ 64 │ 128 │ 196 │ 255 │
1560 ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1561 │Range │ 1-31 │ 32-95 │ 96-159 │ 160-223 │ 224-255 │
1562 └──────┴──────┴───────┴────────┴─────────┴─────────┘
1563 On the page Files the check box Load last-opened files can be
1564 marked so that Kid3 will open and select the last selected file
1565 when it is started the next time. Preserve file timestamp can be
1566 checked to preserve the file modification time stamp. Filename for
1567 cover sets the name which is suggested when an embedded image is
1568 exported to a file. With Text encoding (Export, Playlist) the
1569 encoding used when writing files can be set. The default System can
1570 be changed for example if playlists have to be used on a different
1571 device.
1572 If Mark changes is active, changed fields are marked with a light
1574 gray label background.
1575 The section File List determines which files are displayed in the
1577 file list. A Filter can be used to restrict the items in this list
1578 to files with supported extensions. To explicitly specify which
1579 directories to display in the file list or exclude certain
1580 directories, the options Include folders and Exclude folders can be
1581 used. They can contain wildcard expressions, for instance */Music/*
1582 to include only the Music folder, or */iTunes/* to exclude the
1583 iTunes folder from the file list. If multiple such expressions have
1584 to be used, they can be separated by spaces or semicolons.
1585 The buttons Filename from tag and Tag from filename in section
1587 Format open dialogs to edit the formats which are available in the
1588 Format combo boxes (with arrows up and down), which can be found in
1589 the File section of the main window.
1590 Filename Format contains options for the format of the filenames.
1592 The same options as in Tag Format are available.
1593 The User Actions page contains a table with the commands which are
1595 available in the context menu of the file list. For critical
1596 operations such as deleting files, it is advisable to mark Confirm
1597 to pop up a confirmation dialog before executing the command.
1598 Output can be marked to see the output written by console commands
1599 (standard output and standard error). Name is the name displayed
1600 in the context menu. Command is the command line to be executed.
1601 Arguments can be passed using the following codes:
1602 · %F %{files} File paths (a list if multiple files selected)
1604 · %f %{file} File path to single file
1606 · %uF %{urls} URLs (a list if multiple files selected)
1608 · %uf %{url} URL to single file
1610 · %d %{directory} Directory
1612 · %s %{title} Title (Song)
1614 · %a %{artist} Artist
1616 · %l %{album} Album
1618 · %c %{comment} Comment
1620 · %y %{year} Year
1622 · %t %{track} Track (e.g. 01)
1624 · %t %{track.n} Track with field width n (e.g. 001 for
1626 %{track.3})
1627 · %T %{tracknumber} Track (without leading zeros, e.g. 1)
1629 · %g %{genre} Genre
1631 · %b %{browser} Command to start the web browser
1633 · %q %{qmlpath} Base directory of provided QML files
1635 The special code @separator can be set as a command to insert a
1637 separator into the user actions context menu. Menu items can be put
1638 into a submenu by enclosing them with @beginmenu and @endmenu
1639 commands. The name of the submenu is determined by the Name column
1640 of the @beginmenu command.
1641 To execute QML scripts, @qml is used as a command name. The path to
1643 the QML script is passed as a parameter. The provided scripts can
1644 be found in the folder %{qmlpath}/script/ (on Linux typically
1645 /usr/share/kid3/qml/script/, on Windows qml/script/ inside the
1646 installation directory, and on macOS in the app folder
1647 kid3.app/Contents/Resources/qml/script/). Custom scripts can be
1648 stored in any directory. If the QML code uses GUI components,
1649 @qmlview shall be used instead of @qml. Additional parameters are
1650 passed to the QML script where they will be available via the
1651 getArguments() function. An overview of some functions and
1652 properties which are available in QML can be found in the appendix
1653 QML Interface.
1654 The command which will be inserted with %{browser} can be defined
1656 in the Web browser line edit above. Commands starting with
1657 %{browser} can be used to fetch information about the audio files
1658 from the web, for instance
1659 %{browser} http://lyricwiki.org/%u{artist}:%u{title}
1661 will query the lyrics for the current song in LyricWiki[12]. The
1663 "u" in %u{artist} and %u{title} is used to URL-encode the artist
1664 %{artist} and song %{title} information. It is easy to define your
1665 own queries in the same way, e.g. an image search with Google[13]:
1666 %{browser} http://images.google.com/images?q=%u{artist}%20%u{album}
1668 To add album cover art to tag 2, you can search for images with
1670 Google or Amazon using the commands described above. The picture
1671 can be added to the tag with drag and drop. You can also add an
1672 image with Add, then select the Picture frame and import an image
1673 file or paste from the clipboard. Picture frames are supported for
1674 ID3v2, MP4, FLAC, Ogg and ASF tags.
1675 To add and delete entries in the table, a context menu can be used.
1677 The Network page contains only a field to insert the proxy address
1679 and optionally the port, separated by a colon. The proxy will be
1680 used when importing from an Internet server when the checkbox is
1681 checked.
1682 In the Plugins page, available plugins can be enabled or disabled.
1684 The plugins are separated into two sections. The Metadata Plugins &
1685 Priority list contains plugins which support audio file formats.
1686 The order of the plugins is important because they are tried from
1687 top to bottom. Some formats are supported by multiple plugins, so
1688 files will be opened with the first plugin supporting them. The
1689 TaglibMetadata supports most formats, if it is at the top of the
1690 list, it will open most of the files. If you want to use a
1691 different plugin for a file format, make sure that it is listed
1692 before the TaglibMetadata plugin. Details about the metadata plugin
1693 and why you may want to use them instead of TagLib are listed
1694 below.
1695 · Id3libMetadata: Uses id3lib[14] for ID3v1.1 and ID3v2.3 tags in
1697 MP3, MP2, AAC files. Supports a few more frame types than
1698 TagLib.
1699 · OggFlacMetadata: Uses libogg[15], libvorbis, libvorbisfile[16]
1701 for Ogg files, and additionally libFLAC++ and libFLAC[17] for
1702 FLAC files. These are the official libraries for these formats.
1703 · TaglibMetadata: Uses TagLib[18] which supports a lot of audio
1705 file formats. It can be used for all audio files supported by
1706 Kid3.
1707 · Mp4v2Metadata: mp4v2[19] was originally used by Kid3 to support
1709 M4A files. Can be used in case of problems with the M4A support
1710 of TagLib.
1711 The Available Plugins section lists the remaining plugins. Their
1713 order is not important, but they can be enabled or disabled using
1714 the check boxes.
1715 · AmazonImport: Used for the Import from Amazon... function.
1717 · DiscogsImport: Used for the Import from Discogs... function.
1719 · FreedbImport: Used for the Import from gnudb.org... and Import
1721 from TrackType.org... functions.
1722 · MusicBrainzImport: Used for the Import from MusicBrainz
1724 Release... function.
1725 · AcoustidImport: Used for the Import from MusicBrainz
1727 Fingerprint... function, which depends on the Chromaprint[20]
1728 and libav[21] libraries.
1729 Plugins which are disabled will not be loaded. This can be used to
1731 optimize resource usage and startup time. The settings on this page
1732 take only effect after a restart of Kid3.
1733 Settings → Configure Shortcuts...
1735 Opens a dialog to assign keyboard shortcuts for most of the program
1736 functions. There are even functions without corresponding menu or
1737 button available, e.g. next file, previous file, select all.
1738 The Help Menu
1741 Help → Kid3 Handbook
1742 Opens this handbook.
1743 Help → About Kid3
1745 Displays a short information about Kid3.
1746
1748 Commands
1749 kid3-cli offers a command-line-interface for Kid3. If a directory path
1750 is used, the directory is opened. If one or more file paths are given,
1751 the common directory is opened and the files are selected. Subsequent
1752 commands will then work on these files. Commands are specified using -c
1753 options. If multiple commands are passed, they are executed in the
1754 given order. If files are modified by the commands, they will be saved
1755 at the end. If no command options are passed, kid3-cli starts in
1756 interactive mode. Commands can be entered and will operate on the
1757 current selection. The following sections list all available commands.
1758 Help
1760 help [COMMAND-NAME]
1761 Displays help about the parameters of COMMAND-NAME or about all
1763 commands if no command name is given.
1764 Timeout
1766 timeout [default | off | TIME]
1767 Overwrite the default command timeout. The CLI commands abort after
1769 a command specific timeout is expired. This timeout is 10 seconds
1770 for ls and albumart, 60 seconds for autoimport and filter, and 3
1771 seconds for all other commands. If a huge number of files has to be
1772 processed, this timeouts may be too restrictive, thus the timeout
1773 for all commands can be set to TIME ms, switched off altogether or
1774 be left at the default values.
1775 Quit application
1777 exit [force]
1778 Exit application. If there are modified unsaved files, the force
1780 parameter is required.
1781 Change directory
1783 cd [DIRECTORY]
1784 If no DIRECTORY is given, change to the home directory. If a
1786 directory is given, change into the directory. If one or more file
1787 paths are given, change to their common directory and select the
1788 files.
1789 Print the current working directory
1791 pwd
1792 Print the filename of the current working directory.
1794 Directory list
1796 ls
1797 List the contents of the current directory. This corresponds to the
1799 file list in the Kid3 GUI. Five characters before the file names
1800 show the state of the file.
1801 · > File is selected.
1803 · * File is modified.
1805 · 1 File has a tag 1, otherwise '-' is displayed.
1807 · 2 File has a tag 2, otherwise '-' is displayed.
1809 · 3 File has a tag 3, otherwise '-' is displayed.
1811 kid3-cli> ls
1813 1-- 01 Intro.mp3
1814 > 12- 02 We Only Got This One.mp3
1815 *1-- 03 Outro.mp3
1816 In this example, all files have a tag 1, the second file also has a
1818 tag 2 and it is selected. The third file is modified.
1819 Save the changed files
1821 save
1822 Select file
1824 select [all | none | first | previous | next | FILE...]
1825 To select all files, enter select all, to deselect all files, enter
1827 select none. To traverse the files in the current directory start
1828 with select first, then go forward using select next or backward
1829 using select previous. Specific files can be added to the current
1830 selection by giving their file names. Wildcards are possible, so
1831 select *.mp3 will select all MP3 files in the current directory.
1832 kid3-cli> select first
1834 kid3-cli> ls
1835 > 1-- 01 Intro.mp3
1836 12- 02 We Only Got This One.mp3
1837 *1-- 03 Outro.mp3
1838 kid3-cli> select next
1839 kid3-cli> ls
1840 1-- 01 Intro.mp3
1841 > 12- 02 We Only Got This One.mp3
1842 *1-- 03 Outro.mp3
1843 kid3-cli> select *.mp3
1844 kid3-cli> ls
1845 > 1-- 01 Intro.mp3
1846 > 12- 02 We Only Got This One.mp3
1847 >*1-- 03 Outro.mp3
1848 Select tag
1850 tag [TAG-NUMBERS]
1851 Many commands have an optional TAG-NUMBERS parameter, which
1853 specifies whether the command operates on tag 1, 2, or 3. If this
1854 parameter is omitted, the default tag numbers are used, which can
1855 be set by this command. At startup, it is set to 12 which means
1856 that information is read from tag 2 if available, else from tag 1;
1857 modifications are done on tag 2. The TAG-NUMBERS can be set to 1,
1858 2, or 3 to operate only on the corresponding tag. If the parameter
1859 is omitted, the current setting is displayed.
1860 Get tag frame
1862 get [all | FRAME-NAME] [TAG-NUMBERS]
1863 This command can be used to read the value of a specific tag frame
1865 or get information about all tag frames (if the argument is omitted
1866 or all is used). Modified frames are marked with a '*'.
1867 kid3-cli> get
1869 File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
1870 Name: 01 Intro.mp3
1871 Tag 1: ID3v1.1
1872 Title Intro
1873 Artist One Hit Wonder
1874 Album Let's Tag
1875 Date 2013
1876 Track Number 1
1877 Genre Pop
1878 kid3-cli> get title
1879 Intro
1880 To save the contents of a picture frame to a file, use
1882 get picture:'/path/to/folder.jpg'
1884 To save synchronized lyrics to an LRC file, use
1886 get SYLT:'/path/to/lyrics.lrc'
1888 It is possible to get only a specific field from a frame, for
1890 example get POPM.Email for the Email field of a Popularimeter
1891 frame. If a file has multiple frames of the same kind, the
1892 different frames can be indexed with brackets, for example the
1893 first performer from a Vorbis comment can be retrieved using get
1894 performer[0], the second using get performer[1].
1895 The pseudo field name "selected" can be used to check if a frame is
1897 selected, for example get artist.selected will return 1 if the
1898 artist frame is selected, else 0.
1899 Set tag frame
1901 set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]
1902 This command sets the value of a specific tag frame. If FRAME-VALUE
1904 is empty, the frame is deleted.
1905 kid3-cli> set remixer 'O.H. Wonder'
1907 To set the contents of a picture frame from a file, use
1909 set picture:'/path/to/folder.jpg' 'Picture Description'
1911 To set synchronized lyrics from an LRC file, use
1913 set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'
1915 To set a specific field of a frame, the field name can be given
1917 after a dot, e.g. to set the Counter field of a Popularimeter
1918 frame, use
1919 set POPM.Counter 5
1921 To set multiple frames of the same kind, an index can be given in
1923 brackets, e.g. to set multiple performers in a Vorbis comment, use
1924 kid3-cli> set performer[0] 'Liza don Getti (soprano)'
1926 kid3-cli> set performer[1] 'Joe Barr (piano)'
1927 To select certain frames before a copy, paste or remove action, the
1929 pseudo field name "selected" can be used. Normally, all frames are
1930 selected, to deselect all, use set '*.selected' 0, then for example
1931 set artist.selected 1 to select the artist frame.
1932 Revert
1934 revert
1935 Revert all modifications in the selected files (or all files if no
1937 files are selected).
1938 Import from file or clipboard
1940 import {FILE} {FORMAT-NAME} [TAG-NUMBERS]
1941 Tags are imported from the file FILE (or from the clipboard if
1943 clipboard is used for FILE) in the format with the name FORMAT-NAME
1944 (e.g. "CSV unquoted", see Import).
1945 If tags is given for FILE, tags are imported from other tags.
1947 Instead of FORMAT-NAME parameters SOURCE and EXTRACTION are
1948 required, see Import from Tags.
1949 Automatic import
1951 autoimport [PROFILE-NAME] [TAG-NUMBERS]
1952 Batch import using profile PROFILE-NAME (see Automatic Import,
1954 "All" is used if omitted).
1955 Download album cover artwork
1957 albumart {URL} [all]
1958 Set the album artwork by downloading a picture from URL. The rules
1960 defined in the Browse Cover Art dialog are used to transform
1961 general URLs (e.g. from Amazon) to a picture URL. To set the album
1962 cover from a local picture file, use the set command.
1963 kid3-cli> albumart
1965 http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
1966 Export to file or clipboard
1968 export {FILE} {FORMAT-NAME} [TAG-NUMBERS]
1969 Tags are exported to file FILE (or to the clipboard if clipboard is
1971 used for FILE) in the format with the name FORMAT-NAME (e.g. "CSV
1972 unquoted", see Export).
1973 Create playlist
1975 playlist
1976 Create playlist in the format set in the configuration, see Create
1978 Playlist.
1979 Apply filename format
1981 filenameformat
1982 Apply file name format set in the configuration, see Apply Filename
1984 Format.
1985 Apply tag format
1987 tagformat
1988 Apply tag name format set in the configuration, see Apply Tag
1990 Format.
1991 Apply text encoding
1993 textencoding
1994 Apply text encoding set in the configuration, see Apply Text
1996 Encoding.
1997 Rename directory
1999 renamedir [FORMAT] [create | rename | dryrun] [TAG-NUMBERS]
2000 Rename or create directories from the values in the tags according
2002 to a given FORMAT (e.g. %{artist} - %{album}, see Rename
2003 Directory), if no format is given, the format defined in the Rename
2004 directory dialog is used. The default mode is rename; to create
2005 directories, create must be given explicitly. The rename actions
2006 will be performed immediately, to just see what would be done, use
2007 the dryrun option.
2008 Number tracks
2010 numbertracks [TRACK-NUMBER] [TAG-NUMBERS]
2011 Number the selected tracks starting with TRACK-NUMBER (1 if
2013 omitted).
2014 Filter
2016 filter [FILTER-NAME | FILTER-FORMAT]
2017 Filter the files so that only the files matching the FILTER-FORMAT
2019 are visible. The name of a predefined filter expression (e.g.
2020 "Filename Tag Mismatch") can be used instead of a filter
2021 expression, see Filter.
2022 kid3-cli> filter '%{title} contains "tro"'
2024 Started
2025 /home/urs/One Hit Wonder - Let's Tag
2026 + 01 Intro.mp3
2027 - 02 We Only Got This One.mp3
2028 + 03 Outro.mp3
2029 Finished
2030 kid3-cli> ls
2031 1-- 01 Intro.mp3
2032 1-- 03 Outro.mp3
2033 kid3-cli> filter All
2034 Started
2035 /home/urs/One Hit Wonder - Let's Tag
2036 + 01 Intro.mp3
2037 + 02 We Only Got This One.mp3
2038 + 03 Outro.mp3
2039 Finished
2040 kid3-cli> ls
2041 1-- 01 Intro.mp3
2042 12- 02 We Only Got This One.mp3
2043 1-- 03 Outro.mp3
2044 Convert ID3v2.3 to ID3v2.4
2046 to24
2047 Convert ID3v2.4 to ID3v2.3
2049 to23
2050 Filename from tag
2052 fromtag [FORMAT] [TAG-NUMBERS]
2053 Set the file names of the selected files from values in the tags,
2055 for example fromtag '%{track} - %{title}' 1. If no format is
2056 specified, the format set in the GUI is used.
2057 Tag from filename
2059 totag [FORMAT] [TAG-NUMBERS]
2060 Set the tag frames from the file names, for example totag
2062 '%{albumartist} - %{album}/%{track} %{title}' 2. If no format is
2063 specified, the format set in the GUI is used. If the format of the
2064 filename does not match this pattern, a few other commonly used
2065 formats are tried.
2066 Tag to other tag
2068 syncto {TAG-NUMBER}
2069 Copy the tag frames from one tag to the other tag, e.g. to set the
2071 ID3v2 tag from the ID3v1 tag, use syncto 2.
2072 Copy
2074 copy [TAG-NUMBER]
2075 Copy the tag frames of the selected file to the internal copy
2077 buffer. They can then be set on another file using the paste
2078 command.
2079 To copy only a subset of the frames, use the "selected" pseudo
2081 field with the set command. For example, to copy only the disc
2082 number and copyright frames, use
2083 set '*.selected' 0
2085 set discnumber.selected 1
2086 set copyright.selected 1
2087 copy
2088 Paste
2091 paste [TAG-NUMBER]
2092 Set tag frames from the contents of the copy buffer in the selected
2094 files.
2095 Remove
2097 remove [TAG-NUMBER]
2098 Remove a tag.
2100 It is possible to remove only a subset of the frames by selecting
2102 them as described in the copy command.
2103 Play
2105 play [pause | stop | previous | next]
2106 Start audio playback. Once it has been started, it can be
2108 controlled with the pause (to pause and resume), stop, previous and
2109 next options.
2110 Examples
2112 Set title containing an apostrophe. Commands passed to kid3-cli with -c
2113 have to be in quotes if they do not only consist of a single word. If
2114 such a command itself has an argument containing spaces, that argument
2115 has to be quoted too. In UNIX shells single or double quotes can be
2116 used, but on the Windows Command Prompt, it is important that the outer
2117 quoting is done using double quotes and inside these quotes, single
2118 quotes are used. If the text inside the single quotes contains a single
2119 quote, it has to be escaped using a backslash character, as shown in
2120 the following example:
2121 kid3-cli -c "set title 'I\'ll be there for you'" /path/to/dir
2123 Set album cover in all files of a directory using the batch import
2125 function:
2126 kid3-cli -c "autoimport 'Cover Art'" /path/to/dir
2128 Remove comment frames and apply the tag format in both tags of all MP3
2130 files of a directory:
2131 kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
2133 -c "tagformat 1" -c "tagformat 2" /path/to/dir/*.mp3
2134 Automatically import tag 2, synchronize to tag 1, set file names from
2136 tag 2 and finally create a playlist:
2137 kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
2139 /path/to/dir/*.mp3
2140 For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
2142 the arranger frame:
2143 kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
2145 -c "set arranger ''" /path/to/dir
2146 This Python script uses kid3-cli to generate iTunes Sound Check
2148 iTunNORM frames from replay gain information.
2149 #!/usr/bin/env python3
2152 # Generate iTunes Sound Check from ReplayGain.
2153 import os, sys, subprocess
2154 def rg2sc(dirpath):
2156 for root, dirs, files in os.walk(dirpath):
2157 for name in files:
2158 if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
2159 fn = os.path.join(root, name)
2160 rg = subprocess.check_output([
2161 'kid3-cli', '-c', 'get "replaygain_track_gain"',
2162 fn]).strip()
2163 if rg.endswith(b' dB'):
2164 rg = rg[:-3]
2165 try:
2166 rg = float(rg)
2167 except ValueError:
2168 print('Value %s of %s in not a float' % (rg, fn))
2169 continue
2170 sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
2171 subprocess.call([
2172 'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
2173 if __name__ == '__main__':
2175 rg2sc(sys.argv[1])
2176
2179 Kid3
2180 Program written by Urs Fleisch <ufleisch at users.sourceforge.net>
2182 FDL[22]
2184 GPL[23]
2186
2188 How to obtain Kid3
2189 Kid3 can be found at https://kid3.sourceforge.io.
2190 Requirements
2192 Kid3 needs Qt[24]. KDE[25] is recommended but not necessary, as Kid3
2193 can also be compiled as a Qt application. Kid3 can be compiled for
2194 systems where these libraries are available, e.g. for GNU/Linux,
2195 Windows and macOS. To tag Ogg/Vorbis files, libogg[15], libvorbis and
2196 libvorbisfile[16] are required, for FLAC files libFLAC++ and
2197 libFLAC[17]. id3lib[14] is used for MP3 files. These four formats are
2198 also supported by TagLib[18], which can also handle Opus, MPC, APE,
2199 MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker
2200 modules. To import from acoustic fingerprints, Chromaprint[20] and
2201 libav[21] are used.
2202 Kid3 is available for most Linux distributions, Windows and macOS.
2204 Links can be found on https://kid3.sourceforge.io.
2205 Compilation and Installation
2207 You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple
2208 Qt application and lacks some configuration and session features.
2209 For a KDE version, go into the top directory and type
2211 % cmake .
2213 % make
2214 % make install
2215 To compile for different versions of Qt or KDE, set the corresponding
2217 cmake options.
2218 If not all libraries are present, Kid3 is built with reduced
2220 functionality. So you should take care to have all desired development
2221 packages installed. On the other side, cmake-options control which
2222 libraries are compiled in. The default is -DWITH_TAGLIB:BOOL=ON
2223 -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON
2224 -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON . These options can be
2225 disabled using OFF.
2226 To build Kid3 as a Qt application without KDE, use the cmake option
2228 -DWITH_APPS=Qt. To build both a KDE and a Qt application, set
2229 -DWITH_APPS="Qt;KDE".
2230 To use a specific Qt installation, set
2232 -DQT_QMAKE_EXECUTABLE=/path/to/qmake.
2233 Generation of RPM-Packages is supported by the file kid3.spec, for
2235 Debian-Packages, the script build-deb.sh is available.
2236 The Qt application can also be compiled for Windows and macOS. The
2238 script buildlibs.sh can be used to download and build all required
2239 libraries and create a Kid3 package.
2240 Configuration
2242 With KDE, the settings are stored in .config/kid3rc. As a Qt
2243 application, this file is in .config/Kid3/Kid3.conf. On Windows, the
2244 configuration is stored in the registry. on macOS in a plist file.
2245 The environment variable KID3_CONFIG_FILE can be used to set the path
2247 of the configuration file.
2248
2250 D-Bus Examples
2251 On Linux a D-Bus-interface can be used to control Kid3 by scripts.
2252 Scripts can be written in any language with D-Bus-bindings (e.g. in
2253 Python) and can be added to the User Actions to extend the
2254 functionality of Kid3.
2255 The artist in tag 2 of the current file can be set to the value "One
2257 Hit Wonder" with the following code:
2258 Shell
2260 dbus-send --dest=net.sourceforge.kid3 --print-reply=literal \
2262 /Kid3 net.sourceforge.Kid3.setFrame int32:2 string:'Artist' \
2263 string:'One Hit Wonder'
2264 or easier with Qt's qdbus (qdbusviewer can be used to explore the
2266 interface in a GUI):
2267 qdbus net.sourceforge.kid3 /Kid3 setFrame 2 Artist \
2269 'One Hit Wonder'
2270 Python
2272 import dbus
2274 kid3 = dbus.SessionBus().get_object(
2275 'net.sourceforge.kid3', '/Kid3')
2276 kid3.setFrame(2, 'Artist', 'One Hit Wonder')
2277 Perl
2279 use Net::DBus;
2281 $kid3 = Net::DBus->session->get_service(
2282 "net.sourceforge.kid3")->get_object(
2283 "/Kid3", "net.sourceforge.Kid3");
2284 $kid3->setFrame(2, "Artist", "One Hit Wonder");
2285 D-Bus API
2287 The D-Bus API is specified in net.sourceforge.Kid3.xml. The Kid3
2288 interface has the following methods:
2289 Open file or directory
2291 boolean openDirectory(string path);
2292 path
2294 path to file or directory
2295 Returns true if OK.
2297 Unload the tags of all files which are not modified or selected
2299 unloadAllTags(void);
2300 Save all modified files
2302 boolean save(void);
2303 Returns true if OK.
2305 Get a detailed error message provided by some methods
2307 string getErrorMessage(void);
2308 Returns detailed error message.
2310 Revert changes in the selected files
2312 revert(void);
2313 Start an automatic batch import
2315 boolean batchImport(int32 tagMask, string profileName);
2316 tagMask
2318 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2319 profileName
2321 name of batch import profile to use
2322 Import tags from a file
2324 boolean importFromFile(int32 tagMask, string path, int32 fmtIdx);
2325 tagMask
2327 tag bit (1 for tag 1, 2 for tag 2)
2328 path
2330 path of file
2331 fmtIdx
2333 index of format
2334 Returns true if OK.
2336 Import tags from other tags
2338 importFromTags(int32 tagMask, string source, string extraction);
2339 tagMask
2341 tag bit (1 for tag 1, 2 for tag 2)
2342 source
2344 format to get source text from tags
2345 extraction
2347 regular expression with frame names and captures to extract
2348 from source text
2349 Download album cover art
2351 downloadAlbumArt(string url, boolean allFilesInDir);
2352 url
2354 URL of picture file or album art resource
2355 allFilesInDir
2357 true to add the image to all files in the directory
2358 Export tags to a file
2360 boolean exportToFile(int32 tagMask, string path, int32 fmtIdx);
2361 tagMask
2363 tag bit (1 for tag 1, 2 for tag 2)
2364 path
2366 path of file
2367 fmtIdx
2369 index of format
2370 Returns true if OK.
2372 Create a playlist
2374 boolean createPlaylist(void);
2375 Returns true if OK.
2377 Get items of a playlist
2379 boolean getPlaylistItems(string path);
2380 path
2382 path to playlist file
2383 Returns list of absolute paths to playlist items.
2385 Set items of a playlist
2387 boolean setPlaylistItems(string path, array items);
2388 path
2390 path to playlist file
2391 items
2393 list of absolute paths to playlist items
2394 Returns true if OK, false if not all items were found and added or
2396 saving failed.
2397 Quit the application
2399 quit(void);
2400 Select all files
2402 selectAll(void);
2403 Deselect all files
2405 deselectAll(void);
2406 Set the first file as the current file
2408 boolean firstFile(void);
2409 Returns true if there is a first file.
2411 Set the previous file as the current file
2413 boolean previousFile(void);
2414 Returns true if there is a previous file.
2416 Set the next file as the current file
2418 boolean nextFile(void);
2419 Returns true if there is a next file.
2421 Select the first file
2423 boolean selectFirstFile(void);
2424 Returns true if there is a first file.
2426 Select the previous file
2428 boolean selectPreviousFile(void);
2429 Returns true if there is a previous file.
2431 Select the next file
2433 boolean selectNextFile(void);
2434 Returns true if there is a next file.
2436 Select the current file
2438 boolean selectCurrentFile(void);
2439 Returns true if there is a current file.
2441 Expand or collapse the current file item if it is a directory
2443 boolean expandDirectory(void);
2444 A file list item is a directory if getFileName() returns a name
2446 with '/' as the last character.
2447 Returns true if current file item is a directory.
2449 Apply the file name format
2451 applyFilenameFormat(void);
2452 Apply the tag format
2454 applyTagFormat(void);
2455 Apply text encoding
2457 applyTextEncoding(void);
2458 Set the directory name from the tags
2460 boolean setDirNameFromTag(int32 tagMask, string format,
2461 boolean create);
2462 tagMask
2464 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2465 format
2467 directory name format
2468 create
2470 true to create, false to rename
2471 Returns true if OK, else the error message is available using
2473 getErrorMessage().
2474 Set subsequent track numbers in the selected files
2476 numberTracks(int32 tagMask, int32 firstTrackNr);
2477 tagMask
2479 tag mask (bit 0 for tag 1, bit 1 for tag 2)
2480 firstTrackNr
2482 number to use for first file
2483 Filter the files
2485 filter(string expression);
2486 expression
2488 filter expression
2489 Convert ID3v2.3 tags to ID3v2.4
2491 convertToId3v24(void);
2492 Convert ID3v2.4 tags to ID3v2.3
2494 convertToId3v23(void);
2495 Returns true if OK.
2497 Get path of directory
2499 string getDirectoryName(void);
2500 Returns absolute path of directory.
2502 Get name of current file
2504 string getFileName(void);
2505 Returns true absolute file name, ends with "/" if it is a
2507 directory.
2508 Set name of selected file
2510 setFileName(string name);
2511 name
2513 file name
2514 The file will be renamed when the directory is saved.
2516 Set format to use when setting the filename from the tags
2518 setFileNameFormat(string format);
2519 format
2521 file name format
2522 Set the file names of the selected files from the tags
2524 setFileNameFromTag(int32 tagMask);
2525 tagMask
2527 tag bit (1 for tag 1, 2 for tag 2)
2528 Get value of frame
2530 string getFrame(int32 tagMask, string name);
2531 tagMask
2533 tag bit (1 for tag 1, 2 for tag 2)
2534 name
2536 name of frame (e.g. "artist")
2537 To get binary data like a picture, the name of a file to write can
2539 be added after the name, e.g. "Picture:/path/to/file". In the same
2540 way, synchronized lyrics can be exported, e.g.
2541 "SYLT:/path/to/file".
2542 Returns value of frame.
2544 Set value of frame
2546 boolean setFrame(int32 tagMask, string name, string value);
2547 tagMask
2549 tag bit (1 for tag 1, 2 for tag 2)
2550 name
2552 name of frame (e.g. "artist")
2553 value
2555 value of frame
2556 For tag 2 (tagMask 2), if no frame with name exists, a new frame is
2558 added, if value is empty, the frame is deleted. To add binary data
2559 like a picture, a file can be added after the name, e.g.
2560 "Picture:/path/to/file". "SYLT:/path/to/file" can be used to import
2561 synchronized lyrics.
2562 Returns true if OK.
2564 Get all frames of a tag
2566 array of string getTag(int32 tagMask);
2567 tagMask
2569 tag bit (1 for tag 1, 2 for tag 2)
2570 Returns list with alternating frame names and values.
2572 Get technical information about file
2574 array of string getInformation(void);
2575 Properties are Format, Bitrate, Samplerate, Channels, Duration,
2577 Channel Mode, VBR, Tag 1, Tag 2. Properties which are not available
2578 are omitted.
2579 Returns list with alternating property names and values.
2581 Set tag from file name
2583 setTagFromFileName(int32 tagMask);
2584 tagMask
2586 tag bit (1 for tag 1, 2 for tag 2)
2587 Set tag from other tag
2589 setTagFromOtherTag(int32 tagMask);
2590 tagMask
2592 tag bit (1 for tag 1, 2 for tag 2)
2593 Copy tag
2595 copyTag(int32 tagMask);
2596 tagMask
2598 tag bit (1 for tag 1, 2 for tag 2)
2599 Paste tag
2601 pasteTag(int32 tagMask);
2602 tagMask
2604 tag bit (1 for tag 1, 2 for tag 2)
2605 Remove tag
2607 removeTag(int32 tagMask);
2608 tagMask
2610 tag bit (1 for tag 1, 2 for tag 2)
2611 Reparse the configuration
2613 reparseConfiguration(void);
2614 Automated configuration changes are possible by modifying the
2616 configuration file and then reparsing the configuration.
2617 Plays the selected files
2619 playAudio(void);
2620
2622 QML Examples
2623 QML scripts can be invoked via the context menu of the file list and
2624 can be set in the tab User Actions of the settings dialog. The scripts
2625 which are set there can be used as examples to program custom scripts.
2626 QML uses JavaScript, here is the obligatory "Hello World":
2627 import Kid3 1.0
2629 Kid3Script {
2631 onRun: {
2632 console.log("Hello world, directory is", app.dirName)
2633 Qt.quit()
2634 }
2635 }
2636 If this script is saved as /path/to/Example.qml, the user command can
2638 be defined as @qml /path/to/Example.qml with name QML Test and Output
2639 checked. It can then be started using the QML Test item in the file
2640 list context menu, and the output will be visible in the window.
2641 Alternatively, the script could also be started independent of Kid3
2643 using the QML tools.
2644 qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2646 or
2648 qmlscene -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2650 On Windows and macOS, the import path must be adapted to the imports
2652 folder inside the installation directory. Scripts started outside of
2653 Kid3 will use the current directory, so it should be changed
2654 beforehand.
2655 To list the titles in the tags 2 of all files in the current directory,
2657 the following script could be used:
2658 import Kid3 1.0
2660 Kid3Script {
2662 onRun: {
2663 app.firstFile()
2664 do {
2665 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2666 console.log(app.getFrame(tagv2, "title"))
2667 }
2668 } while (app.nextFile())
2669 }
2670 }
2671 If the directory contains many files, such a script might block the
2673 user interface for some time. For longer operations, it should
2674 therefore have a break from time to time. The alternative
2675 implementation below has the work for a single file moved out into a
2676 function. This function invokes itself with a timeout of 1 ms at the
2677 end, given that more files have to be processed. This will ensure that
2678 the GUI remains responsive while the script is running.
2679 import Kid3 1.0
2681 Kid3Script {
2683 onRun: {
2684 function doWork() {
2685 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2686 console.log(app.getFrame(tagv2, "title"))
2687 }
2688 if (!app.nextFile()) {
2689 Qt.quit()
2690 } else {
2691 setTimeout(doWork, 1)
2692 }
2693 }
2694 app.firstFile()
2696 doWork()
2697 }
2698 }
2699 When using app.firstFile() with app.nextFile(), all files of the
2701 current directory will be processed. If only the selected files shall
2702 be affected, use firstFile() and nextFile() instead, these are
2703 convenience functions of the Kid3Script component. The following
2704 example is a script which copies only the disc number and copyright
2705 frames of the selected file.
2706 import Kid3 1.1
2708 Kid3Script {
2710 onRun: {
2711 function doWork() {
2712 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2713 app.setFrame(tagv2, "*.selected", false)
2714 app.setFrame(tagv2, "discnumber.selected", true)
2715 app.setFrame(tagv2, "copyright.selected", true)
2716 app.copyTags(tagv2)
2717 }
2718 if (!nextFile()) {
2719 Qt.quit()
2720 } else {
2721 setTimeout(doWork, 1)
2722 }
2723 }
2724 firstFile()
2726 doWork()
2727 }
2728 }
2729 More example scripts come with Kid3 and are already registered as user
2731 commands.
2732 · ReplayGain to SoundCheck (ReplayGain2SoundCheck.qml): Create
2734 iTunNORM SoundCheck information from replay gain frames.
2735 · Resize Album Art (ResizeAlbumArt.qml): Resize embedded cover art
2737 images which are larger than 500x500 pixels.
2738 · Extract Album Art (ExtractAlbumArt.qml): Extract all embedded cover
2740 art pictures avoiding duplicates.
2741 · Embed Album Art (EmbedAlbumArt.qml): Embed cover art found in image
2743 files into audio files in the same folder.
2744 · Embed Lyrics (EmbedLyrics.qml): Fetch unsynchronized lyrics from
2746 web service.
2747 · Text Encoding ID3v1 (ShowTextEncodingV1.qml): Helps to find the
2749 encoding of ID3v1 tags by showing the tags of the current file in
2750 all available character encodings.
2751 · Export CSV (ExportCsv.qml): Export recursively all tags of all
2753 files to a CSV file.
2754 · Export Playlist Folder (ExportPlaylist.qml): Copy all files from a
2756 playlist into a directory and rename them according to their
2757 position.
2758 · QML Console (QmlConsole.qml): Simple console to play with Kid3's
2760 QML API.
2761 QML API
2764 The API can be easily explored using the QML Console, which is
2765 available as an example script with a user interface.
2766 Kid3Script
2768 Kid3Script is a regular QML component located inside the plugin
2769 directory. You could use another QML component just as well. Using
2770 Kid3Script makes it easy to start the script function using the
2771 onRun signal handler. Moreover it offers some functions:
2772 onRun: Signal handler which is invoked when the script is started
2774 tagv1, tagv2, tagv2v1: Constants for tag parameters
2775 script: Access to scripting functions
2776 configs: Access to configuration objects
2777 getArguments(): List of script arguments
2778 isStandalone(): true if the script was not started from within Kid3
2779 setTimeout(callback, delay): Starts callback after delay ms
2780 firstFile(): To first selected file
2781 nextFile(): To next selected file
2782 Scripting Functions
2785 As JavaScript and therefore QML too has only a limited set of
2786 functions for scripting, the script object has some additional
2787 methods, for instance:
2788 script.properties(obj): String with Qt properties
2790 script.writeFile(filePath, data): Write data to file, true if OK
2791 script.readFile(filePath): Read data from file
2792 script.removeFile(filePath): Delete file, true if OK
2793 script.fileExists(filePath): true if file exists
2794 script.renameFile(oldName, newName): Rename file, true if OK
2795 script.copyFile(source, dest): Copy file, true if OK
2796 script.makeDir(path): Create directory, true if OK
2797 script.removeDir(path): Remove directory, true if OK
2798 script.tempPath(): Path to temporary directory
2799 script.listDir(path, [nameFilters], [classify]): List directory entries
2800 script.system(program, [args], [msecs]): Synchronously start a system command,
2801 [exit code, standard output, standard error] if not timeout
2802 script.systemAsync(program, [args], [callback]): Asynchronously start a system
2803 command, callback will be called with [exit code, standard output, standard
2804 error]
2805 script.getEnv(varName): Get value of environment variable
2806 script.setEnv(varName, value): Set value of environment variable
2807 script.getQtVersion(): Qt version string, e.g. "5.4.1"
2808 script.getDataMd5(data): Get hex string of the MD5 hash of data
2809 script.getDataSize(data): Get size of byte array
2810 script.dataToImage(data, [format]): Create an image from data bytes
2811 script.dataFromImage(img, [format]): Get data bytes from image
2812 script.loadImage(filePath): Load an image from a file
2813 script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
2814 script.imageProperties(img): Get properties of an image, map containing
2815 "width", "height", "depth" and "colorCount", empty if invalid image
2816 script.scaleImage(img, width, [height]): Scale an image, returns scaled image
2817 Application Context
2819 Using QML, a large part of the Kid3 functions are accessible. The
2820 API is similar to the one used for D-Bus. For details, refer to the
2821 respective notes.
2822 app.openDirectory(path): Open directory
2824 app.unloadAllTags(): Unload all tags
2825 app.saveDirectory(): Save directory
2826 app.revertFileModifications(): Revert
2827 app.importTags(tag, path, fmtIdx): Import file
2828 app.importFromTags(tag, source, extraction): Import from tags
2829 app.downloadImage(url, allFilesInDir): Download image
2830 app.exportTags(tag, path, fmtIdx): Export file
2831 app.writePlaylist(): Write playlist
2832 app.getPlaylistItems(path): Get items of a playlist
2833 app.setPlaylistItems(path, items): Set items of a playlist
2834 app.selectAllFiles(): Select all
2835 app.deselectAllFiles(): Deselect
2836 app.firstFile([select], [onlyTaggedFiles]): To first file
2837 app.nextFile([select], [onlyTaggedFiles]): To next file
2838 app.previousFile([select], [onlyTaggedFiles]): To previous file
2839 app.selectCurrentFile([select]): Select current file
2840 app.selectFile(path, [select]): Select a specific file
2841 app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
2842 app.requestExpandFileList(): Expand all
2843 app.applyFilenameFormat(): Apply filename format
2844 app.applyTagFormat(): Apply tag format
2845 app.applyTextEncoding(): Apply text encoding
2846 app.numberTracks(nr, total, tag, [options]): Number tracks
2847 app.applyFilter(expr): Filter
2848 app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
2849 app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
2850 app.getFilenameFromTags(tag): Filename from tags
2851 app.getTagsFromFilename(tag): Filename to tags
2852 app.getAllFrames(tag): Get object with all frames
2853 app.getFrame(tag, name): Get frame
2854 app.setFrame(tag, name, value): Set frame
2855 app.getPictureData(): Get data from picture frame
2856 app.setPictureData(data): Set data in picture frame
2857 app.copyToOtherTag(tag): Tags to other tags
2858 app.copyTags(tag): Copy
2859 app.pasteTags(tag): Paste
2860 app.removeTags(tag): Remove
2861 app.playAudio(): Play
2862 app.readConfig(): Read configuration
2863 app.applyChangedConfiguration(): Apply configuration
2864 app.dirName: Directory name
2865 app.selectionInfo.fileName: File name
2866 app.selectionInfo.filePath: Absolute file path
2867 app.selectionInfo.detailInfo: Format details
2868 app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
2869 app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
2870 app.selectionInfo.formatString(tag, format): Substitute codes in format string
2871 app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
2872 select a file
2873 app.selectDirName(caption, dir): Open file dialog to select a directory
2874 For asynchronous operations, callbacks can be connected to signals.
2876 function automaticImport(profile) {
2878 function onAutomaticImportFinished() {
2879 app.batchImporter.finished.disconnect(onAutomaticImportFinished)
2880 }
2881 app.batchImporter.finished.connect(onAutomaticImportFinished)
2882 app.batchImport(profile, tagv2)
2883 }
2884 function renameDirectory(format) {
2886 function onRenameActionsScheduled() {
2887 app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
2888 app.performRenameActions()
2889 }
2890 app.renameActionsScheduled.connect(onRenameActionsScheduled)
2891 app.renameDirectory(tagv2v1, format, false)
2892 }
2893 Configuration Objects
2895 The different configuration sections are accessible via methods of
2896 configs. Their properties can be listed in the QML console.
2897 script.properties(configs.networkConfig())
2899 Properties can be set:
2901 configs.networkConfig().useProxy = false
2903 configs.batchImportConfig()
2907 configs.exportConfig()
2908 configs.fileConfig()
2909 configs.filenameFormatConfig()
2910 configs.filterConfig()
2911 configs.findReplaceConfig()
2912 configs.guiConfig()
2913 configs.importConfig()
2914 configs.mainWindowConfig()
2915 configs.networkConfig()
2916 configs.numberTracksConfig()
2917 configs.playlistConfig()
2918 configs.renDirConfig()
2919 configs.tagConfig()
2920 configs.tagFormatConfig()
2921 configs.userActionsConfig()
2922
2924 Urs Fleisch <ufleisch at users.sourceforge.net>
2925 Software development
2926
2928 Copyright © 2018 Urs Fleisch
2929 FDL
2931
2934 1. gnudb.org
2935 http://gnudb.org
2936 2. TrackType.org
2938 http://tracktype.org
2939 3. MusicBrainz
2941 http://musicbrainz.org
2942 4. Discogs
2944 http://discogs.com
2945 5. Amazon
2947 http://www.amazon.com
2948 6. ID3 specification
2950 http://id3.org/id3v2.4.0-frames
2951 7. SYLT Editor
2953 http://www.compuphase.com/software_sylteditor.htm
2954 8. www.gnudb.org
2956 http://www.gnudb.org
2957 9. freedb.org
2959 http://freedb.org
2960 10. ID3 tag version 2.3.0
2962 http://id3.org/id3v2.3.0
2963 11. ID3 tag version 2.4.0 - Main Structure
2965 http://id3.org/id3v2.4.0-structure
2966 12. LyricWiki
2968 http://www.lyricwiki.org
2969 13. Google
2971 http://www.google.com
2972 14. id3lib
2974 http://id3lib.sourceforge.net
2975 15. libogg
2977 http://xiph.org/ogg/
2978 16. libvorbis, libvorbisfile
2980 http://xiph.org/vorbis/
2981 17. libFLAC++ and libFLAC
2983 http://flac.sourceforge.net
2984 18. TagLib
2986 http://taglib.github.io/
2987 19. mp4v2
2989 http://code.google.com/p/mp4v2
2990 20. Chromaprint
2992 http://acoustid.org/chromaprint
2993 21. libav
2995 http://libav.org/
2996 22. FDL
2998 http://www.gnu.org/licenses/licenses.html#FDL
2999 23. GPL
3001 http://www.gnu.org/licenses/licenses.html#GPL
3002 24. Qt
3004 http://qt-project.org/
3005 25. KDE
3007 http://www.kde.org
30083.7.0 2018-12-23 KID3(1)