1KID3(1)                        The Kid3 Handbook                       KID3(1)
2
3
4

NAME

6       kid3, kid3-qt, kid3-cli - Kid3 ID3 Tagger
7

SYNOPSIS

9       kid3 [--help | --author | --version | --license | --desktopfile FILE]
10            [FILE...]
11
12       kid3-qt [--portable] [Qt-options] [FILE...]
13
14       kid3-cli [--portable] [--dbus] [-h | --help] [-c COMMAND1]
15                [-c COMMAND2...] [FILE...]
16

OPTIONS

18       --portable
19           Store configuration in file kid3.ini inside application folder.
20
21       FILE
22           If FILE is the path to a folder, it will be opened. If one or more
23           file paths are given, their common folder is opened and the files
24           are selected.
25
26   kid3
27       --help
28           Show help about options.
29
30       --author
31           Show author information.
32
33       --version
34           Show version information.
35
36       --license
37           Show license information.
38
39       --desktopfile FILE
40           The base file name of the desktop entry for this application.
41
42   kid3-qt
43       Qt-options
44           See qt5options(7).
45
46   kid3-cli
47       --dbus
48           Activate the D-Bus interface.
49
50       -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
55       -h|--help
56           Show help about options and commands.
57

INTRODUCTION

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
66       Kid3 does not grab nor encode MP3 files, but it is targeted to edit the
67       ID3 tags of all files of an album in an efficient way, i.e.  with as
68       few mouse clicks and key strokes as possible. Where most other programs
69       can edit either ID3v1 or ID3v2 tags, Kid3 has full control over both
70       versions, can convert tags between the two formats and has access to
71       all ID3v2 tags. Tags of multiple files can be set to the same value,
72       e.g.  the artist, album, year and genre of all files of an album
73       typically have the same values and can be set together. If the
74       information for the tags is contained in the file name, the tags can be
75       automatically set from the file name. It is also possible to set the
76       file name according to the tags found in the file in arbitrary formats.
77
78       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
83       The tag information for full albums can be taken from gnudb.org[1],
84       MusicBrainz[2], Discogs[3], Amazon[4] or other sources of track lists.
85       The import format is freely configurable by regular expressions.
86
87       Please report any problems or feature requests to the author.
88

USING KID3

90   Kid3 features
91       •   Edit ID3v1.1 tags
92
93       •   Edit all ID3v2.3 and ID3v2.4 frames
94
95       •   Edit tags of multiple files
96
97       •   Convert between ID3v1 and ID3v2 tags
98
99       •   Edit MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2,
100           Speex, TrueAudio, WavPack, WMA, WAV and AIFF tags
101
102       •   Generate tags from filename
103
104       •   Generate tags from the contents of tag fields
105
106       •   Generate filename from tags
107
108       •   Generate and change folder names from tags
109
110       •   Generate playlist file
111
112       •   Automatic case conversion and string translation
113
114       •   Import from gnudb.org[1], MusicBrainz[2], Discogs[3], Amazon[4] and
115           other data sources
116
117       •   Export as CSV, HTML, playlist, Kover XML and other formats.
118           Exported CSV files can be imported again.
119
120   Example Usage
121       This section describes a typical session with Kid3. Let's assume we
122       have a folder containing MP3 files with the tracks from the album
123       "Let's Tag" from the band "One Hit Wonder". The folder is named in the
124       "artist - album" format, in our case One Hit Wonder - Let's Tag. The
125       folder contains the tracks in the "track title.mp3" format, which I
126       think is useful because the filenames are short (important when using
127       mobile MP3 players with small displays) and in the correct order when
128       sorted alphabetically (important when using hardware MP3 players which
129       play the tracks in alphabetical order or in the order in which they are
130       burnt on CD and that order is alphabetical when using mkisofs). Besides
131       this, the artist and album information is already in the folder name
132       and does not have to be repeated in the filename. But back to our
133       example, the folder listing looks like this:
134
135       01 Intro.mp3
136
137       02 We Only Got This One.mp3
138
139       03 Outro.mp3
140
141       These files have no tags yet and we want to generate them using Kid3.
142       We use File → Open menu item (or toolbar button) and select one of the
143       files in this folder. All files will be displayed in the file listbox.
144       Lazy as we are, we want to use the information in the folder and file
145       names to generate tags. Therefore we select all files, then click the
146       To: Tag 1 button in the File section. This will set the title, artist,
147       album and track values in all files. To set the year and genre values
148       of all files, we keep all files selected and type in "2002" for the
149       Date and select "Pop" from the Genre combobox. To set only these two
150       values, their check boxes are automatically checked and all other check
151       boxes are left unchecked. Now we change the selection by only selecting
152       the first file and we see that all tags contain the correct values. The
153       tags of the other files can be verified too by selecting them one by
154       one. When we are satisfied with the tags, we use File → Save menu item
155       (or toolbar button). Selecting File → Create Playlist menu item (or
156       toolbar button) will generate a file One Hit Wonder - Let's Tag.m3u in
157       the folder.
158

COMMAND REFERENCE

160   The GUI Elements
161       The Kid3 GUI is separated in six sections: At the left are the file and
162       folder listboxes, the right side contains the File, Tag 1, Tag 2 and
163       Tag 3 sections.
164
165       To navigate between the different sections using the keyboard, several
166       keyboard shortcuts are supported. In the tag sections, the shortcuts
167       are active while not editing text or when being in the first column.
168
169       •   Alt+Left: Go to previous section (Command+[ on macOS®)
170
171       •   Alt+Right: Go to next section (Command+] on macOS®)
172
173       •   Ctrl+Shift+V: From other tag
174
175       •   Ctrl+C: Copy
176
177       •   Ctrl+V: Paste
178
179       •   Shift+Delete: Remove
180
181       •   F2: Edit
182
183       •   Insert: Add
184
185       •   Delete: Delete
186
187       File List
188           The file list contains the names of all the files in the opened
189           folder which match the selected file name filter (typically *.mp3
190           *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2
191           *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). A single or multiple
192           files can be selected. To select no file, click into the empty area
193           after the listbox entries. The selection determines the files which
194           are affected by the operations which are available by using the
195           buttons described below.
196
197           Besides Name, also other columns Size, Type, Date Modified with
198           file details can be displayed. Columns can be hidden by unchecking
199           their name in the context menu of the list header. The order of the
200           columns can be changed by drag and drop. The sort order can be
201           toggled by clicking on the column header.
202
203           At the left of the names an icon can be displayed: a disc to show
204           that the file has been modified or information about which tags are
205           present (V1, V2, V1V2 or NO TAG, no icon is displayed if the file
206           has not been read in yet).
207
208           Folders are displayed with a folder icon. If a folder is opened,
209           its files are displayed in a hierarchical tree. By selecting files
210           from subfolders, operations can be executed on files in different
211           folders, which is useful if the music collection is organized with
212           a folder for each artist containing folders for albums of this
213           artist.
214
215           Clicking the right mouse button inside the file list opens a
216           context menu with the following commands:
217
218           •   Expand all: Expands all folder trees (only the current tree if
219               the Shift key is pressed)
220
221           •   Collapse all: Collapses all folder trees
222
223           •   Rename: Changes the name of a file
224
225           •   Move to Trash: Moves a file to the trash
226
227           •   Play: Plays a file, see Play. If the selected file is a
228               playlist, the files of the playlist will be played.
229
230           •   Edit: Edit a playlist, see Edit Playlist.
231
232           •   The subsequent entries are user commands, which can be defined
233               in the User Actions tab of Configure Kid3. The playback on
234               double click can also be activated there.
235
236
237       Edit Playlist
238           A playlist can be created empty or containing the tracks of a
239           folder, see Create Playlist. The playlist file created in such a
240           way can be edited by double click or using Edit from the file list
241           context menu. A dialog with the entries of the playlist is shown.
242           It is possible to open multiple playlists simultaneously.
243
244           New entries can be added by drag and drop from the file list, a
245           file manager or another playlist. If an entry is dragged from
246           another playlist, it will be moved or copied depending on the
247           system. To invoke the other operation, respectively, the Shift,
248           Ctrl or Alt (to copy instead of move on macOS®) key has to be
249           pressed. Reordering entries within the playlist is also possible
250           via drag and drop. Alternatively, entries can be moved using the
251           keyboard shortcuts Ctrl+Shift+Up and Ctrl+Shift+Down (on macOS®
252           Command has to be pressed instead of Ctrl). An entry can be removed
253           using the Delete key.
254
255           Please note the following: To drag entries from the file list, they
256           have to be held at the left side (near the icons), the same gesture
257           at the right side will perform a multi selection, such an action is
258           hereby still easily possible.
259
260           When a playlist has been modified, the changes can be stored using
261           Save or discarded using Cancel. When the window is closed, a
262           confirmation prompt is shown if there are unsaved changes.
263
264           Tracks selected in a playlist will be automatically selected in the
265           file list, thereby making it possible to edit their tags.
266
267           To execute actions on a playlist, its file must be selected in the
268           file list.  Edit from the context menu will lead to the dialog
269           described in this section, and Play will start the media player
270           with the tracks from the playlist. User actions can act on
271           playlists, for example Export Playlist Folder, which copies the
272           files from a playlist into a folder.
273
274       Folder List
275           The folder list contains the names of the folders in the opened
276           folder, as well as the current (.) and the parent (..) folder. It
277           allows one to quickly change the folder without using the Open
278           command or drag and drop.
279
280           Column visibility, order and sorting can be configured as described
281           in the section about the file list.
282
283       File
284           Shows information about the encoding (MP3, Ogg, Opus, DSF, FLAC,
285           MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV,
286           AIFF), bit rate, sample rate, channels and the length of the file.
287
288           The Name line edit contains the name of the file (if only a single
289           file is selected). If this name is changed, the file will be
290           renamed when the Save command is used.
291
292           The Format combo box and line edit contains the format to be used
293           when the filename is generated from the first or the second tag.
294           The filename can contain arbitrary characters, even a folder part
295           separated by a slash from the file name, but that folder must
296           already exist for the renaming to succeed. The following special
297           codes are used to insert tag values into the filename:
298
299           •   %s %{title} Title (Song)
300
301           •   %a %{artist} Artist
302
303           •   %l %{album} Album
304
305           •   %c %{comment} Comment
306
307           •   %y %{year} Year
308
309           •   %t %{track} Track (e.g.  01)
310
311           •   %t %{track.n} Track with field width n (e.g.  001 for
312               %{track.3})
313
314           •   %T %{tracknumber} Track (without leading zeros, e.g.  1)
315
316           •   %g %{genre} Genre
317
318           •   %{ignore} Ignored when generating tags from the file name
319
320           The format codes are not restricted to the examples given above.
321           Any frame name can be used, for instance unified frame names like
322           %{albumartist}, %{discnumber.1}, %{bpm} or format specific names
323           like %{popm}.
324
325           It is possible to prepend and append strings to the replacement for
326           a format code by adding them in double quotes inside the curly
327           braces of a format code. These strings will only be put into the
328           resulting string if the format code yields a nonempty value. For
329           example, if the file name shall both contain the title and the
330           subtitle, one could use %{title} [%{subtitle}] in the format
331           string. But this would result in a string ending with [] if no
332           subtitle frame exists for a file. In order to omit the brackets if
333           no subtitle is present, %{title}%{" ["subtitle"]"} shall be used
334           instead. This will omit the brackets, the leading space and the
335           subtitle if not subtitle exists.
336
337           The list of available formats can be edited in the dialog which
338           appears when clicking the Filename from tag button in the File tab
339           of the settings.
340
341           A second Format combo box (with arrow down) is used to generate the
342           tags from the filename. If the format of the filename does not
343           match this pattern, a few other commonly used formats are tried.
344
345           Some commonly used filename formats are already available in the
346           combo box, but it is also possible to type in some special format
347           into the line edit.
348
349           The list of available formats can be edited in the dialog which
350           appears when clicking the Tag from filename button in the File tab
351           of the settings.
352
353           Internally, a regular expression is built from the format codes. If
354           advanced regular expressions are required, the format to generate
355           the tags from the filenames can be given as a complete regular
356           expression with captures which are preceded by the format codes,
357           e.g.  to extract the track numbers without removal of leading
358           zeros, a format like "/%{track}(\d+) %{title}(.*)" could be used.
359
360           From: Tag 1, Tag 2: Sets the filename using the selected format and
361           the first tag or the second tag, respectively.
362
363           To: Tag 1, Tag 2: The tags are set from the filename. First, the
364           format specified in Format is used. If the existing filename does
365           not match this format, the following formats are tried:
366
367           •   Artist - Album/Track Song
368
369           •   Album/Track - Artist - Song
370
371           •   /Artist - Album - Track - Song
372
373           •   Album/Artist - Track - Song
374
375           •   Album/Artist - Song
376
377           •   Artist/Album/Track Song
378
379           If a single file is selected, the GUI controls are filled with the
380           values extracted from the filename. If multiple files are selected,
381           the tags of the files are directly set according to the filenames.
382
383       Tag 1
384           The line edit widgets for Title, Artist, Album, Comment, Date,
385           Track Number and Genre are used to edit the corresponding value in
386           the first tag of the selected files. The value will be changed when
387           the file selection is altered or before operations like Save and
388           Quit and when the corresponding check box at the left of the field
389           name is checked. This is useful to change only some values and
390           leave the other values unchanged.
391
392           If a single file is selected, all check boxes are checked and the
393           line edit widgets contain the values found in the tags of this
394           file. If a tag is not found in the file, the corresponding empty
395           value is displayed, which is an empty string for the Title, Artist,
396           Album and Comment line edits, 0 for the numerical Date and Track
397           Number edits and an empty selected value for the Genre combo box.
398           The values can be changed and if the corresponding check box is
399           checked, they will be set for the selected file after the selection
400           is changed. The file is then marked as modified by a disk symbol in
401           the file listbox but remains unchanged until the Save command is
402           used.
403
404           If multiple files are selected, only the values which are identical
405           in all selected files are displayed. In all other controls, the
406           empty values as described above are displayed. All check boxes are
407           unchecked to avoid unwanted changes. If a value has to be set for
408           all selected files, it can be edited and the check box has to be
409           set. The values will be set for all selected files when the
410           selection is changed and can be saved using the Save command.
411
412           The check boxes also control the operation of most commands
413           affecting the tags, such as copy, paste and transfer between tags 1
414           and 2. To make it easier to use with multiple files where all check
415           boxes are unchecked, these commands behave in the same way when all
416           check boxes are checked and when all check boxes are unchecked.
417
418           From Tag 2: The tag 1 fields are set from the corresponding values
419           in tag 2. If a single file is selected, the GUI controls are filled
420           with the values from tag 2. If multiple files are selected, the
421           tags of the files are directly set.
422
423           Copy: The copy buffer is filled with the Tag 1 values. Only values
424           with checked check box will be used in subsequent Paste commands.
425
426           Paste: Pastes the values from the copy buffer into the GUI
427           controls.
428
429           Remove: This will set all GUI controls to their empty values which
430           results in removing all values. The saved file will then contain no
431           tag 1.
432
433       Tag 2
434           The GUI controls function in the same way as described for the Tag
435           1 section, but the size of the strings is not limited.
436
437           For the tag 2 Genre you can also use your own names besides the
438           genres listed in the combo box, just type the name into the line
439           edit.
440
441           The tag 2 cannot only contain the same values as the tag 1, the
442           format is built in a flexible way from several frames which are
443           themselves composed of several fields. The tag 2 table shows all
444           the frames which are available in the selected file.
445
446           Edit: This will open a window which allows one to edit all fields
447           of the selected frame. If multiple files are selected, the edited
448           fields are applied to all selected files which contain such a
449           frame.
450
451           Add: A requester to select the frame type will appear and a frame
452           of the selected type can be edited and added to the file. This
453           works also to add a frame to multiple selected files.
454
455           Delete: Deletes the selected frame in the selected files.
456
457           Drag album artwork here is shown if the file does not contain
458           embedded cover art. A picture can be added using drag and drop from
459           a browser or file manager and will be displayed here. Picture
460           frames can be edited or added by double clicking on this control.
461
462       Tag 3
463           Some files can have more than two tags, and a third tag section is
464           visible. The following file types can have such a Tag 3 section:
465
466           •   MP3 files can have an ID3v1.1 tag, an ID3v2 (2.3.0 or 2.4.0)
467               tag and in the third section an APE tag. Such APE tags are used
468               for replay gain information. In the Tag 3 section, this
469               information is visible, and the APE tag can be removed with the
470               Remove button.
471
472           •   The RIFF INFO chunk of WAV files is available in the Tag 3
473               section because the Tag 1 section is dedicated to ID3v1.1 tags
474               and handles their restrictions. The Tag 2 is still used for
475               ID3v2.4.0 tags, which are also supported for WAV files, but
476               RIFF INFO chunks seem to be supported better.
477
478           •   FLAC files normally use a Vorbis comment for their meta data.
479               However, there are FLAC files which have ID3v1 and ID3v2 tags,
480               which can be found in the Tag 1 and Tag 3 sections. ID3 tags in
481               FLAC files are only supported by TagLib, therefore the
482               OggFlacMetadata plugin has to be disabled in the Plugins tab of
483               the settings.
484
485           The GUI controls work in the same way as in the Tag 2 section.
486
487       Synchronized Lyrics and Event Timing Codes
488           For information synchronized with the audio data, a specific editor
489           is available. These frames are supported for ID3v2.3.0 and
490           ID3v2.4.0 tags. To add such a frame, the specific frame name has to
491           be selected in the list which appears when the Add button is
492           clicked - Synchronized Lyrics or Event Timing Codes, respectively.
493           The editor is the same for both types, for the event timing codes,
494           only a predefined set of events is available whereas for the
495           synchronized lyrics, text has to be entered. In the following,
496           editing synchronized lyrics is explained.
497
498           A file having an ID3v2 tag is selected, the lyrics editor is
499           entered using Add and selecting Synchronized Lyrics. For an
500           existing Synchronized Lyrics frame, it is selected and Edit is
501           clicked. The player is automatically opened with the current file
502           so that the file can be played and paused to synchronize lyrics.
503
504           The settings at the top of the SYLT editor normally do not have to
505           be changed. If the lyrics contains characters which are not present
506           in the Latin 1 character set, changing the text encoding to UTF16
507           (or UTF8 for ID3v2.4.0) is advisable. For English lyrics and
508           maximum compatibility, ISO-8859-1 should be used.
509
510           The Lyrics section has five buttons at the top.  Add will add a new
511           time event in the table. The time is taken from the position of the
512           player, thus adding an entry while playing the track will add a
513           line for the currently played position. The events in the table
514           have to be chronologically ordered, therefore the row will be
515           inserted accordingly. Entries with an invalid time are treated
516           specially: If the currently selected row has an invalid time, its
517           time stamp will be replaced by the current time instead of adding a
518           new row. If the current time is not invalid, the first row with an
519           invalid time will be used if present. This behavior should
520           facilitate adding time stamps if the lyrics text is already in the
521           table but the time stamps are missing (which is the case when
522           importing unsynchronized lyrics). Note that the invalid time is
523           represented as 00:00.00, i.e.  the same as the time at the absolute
524           beginning of the track, which is not invalid. To make a time
525           invalid, press the Delete key, or use Clear from the context menu.
526           New rows inserted using Insert row from the context menu or created
527           when importing unsynchronized lyrics with From Clipboard or Import
528           also contain invalid time stamps. Rows in the table can be deleted
529           by clicking the Delete button or using Delete rows from the context
530           menu.
531
532           Synchronized lyrics can be imported from a file using Import. The
533           expected format is simple or enhanced LRC. If the selected file
534           does not contain a square bracket in the first line, it is supposed
535           to be a simple text file with unsynchronized lyrics. The lines from
536           such a file are then imported having invalid time stamps. The time
537           information can be added using the Add button or by manual entry.
538           It is also possible to import lyrics via copy-paste using From
539           Clipboard. Synchronized lyrics can be written to LRC files using
540           Export. Note that only entries with valid time stamps will be
541           exported and that the entries will be sorted by time. Entries with
542           invalid time won't be stored in the SYLT frame either, so make sure
543           to include all timing information before leaving the dialog.
544
545           The ID3 specification[5] suggests a time stamp for each syllable.
546           However most players only support the granularity of a line or
547           sentence. To support both use cases, Kid3 follows the same
548           conventions as SYLT Editor[6]. Text which is entered into the table
549           is assumed to start a new line unless it starts with a space or a
550           hyphen. Exceptions to this rule are possible by starting a line
551           with an underscore ('_') to force continuation or a hash mark ('#')
552           to force a new line. These escape characters are not stored inside
553           the SYLT frame. Inside the SYLT frame, new lines start with a line
554           feed character (hex 0A) whereas continuations do not. When reading
555           SYLT frames, Kid3 checks if the first entry starts with a line
556           feed. If this is not the case, it is assumed that all entries are
557           new lines and that no syllable continuations are used.
558
559           While the track is played, the row associated with the current
560           playing position is highlighted, so that the correctness of the
561           synchronization information can be verified. If an offset has to be
562           added to one or more time stamps, this can be accomplished with the
563           Add offset context menu. Negative values can be used to reduce the
564           time. Using Seek to position in the context menu, it is possible to
565           set the playing position to the time of the selected row.
566
567           Recommended procedure to add new synchronized lyrics
568
569           •   Get the unsynchronized lyrics, e.g.  using Lyrics → Embed
570               Lyrics from the file list context menu.
571
572           •   Copy the unsynchronized lyrics to the clipboard, just go to the
573               Lyrics row in the frame table and press Ctrl+C.
574
575           •   Add a synchronized lyrics frame (Add..., Synchronized Lyrics,
576               OK), click From Clipboard.
577
578           •   Now all lines from the unsynchronized lyrics are in the table,
579               all time stamps are invalid (0:0:0.00). You can delete empty
580               entries beforehand.
581
582           •   Start playing the song by clicking the play button ► in the
583               play toolbar at the bottom of the main window.
584
585           •   When the next lyrics line with invalid timestamp comes, click
586               Add or press Alt+A, the timestamp will be updated.
587
588           •   Continue like this until all timestamps are set. If you missed
589               something, stop playback and clear the timestamps using the
590               Delete key or by selecting them and using Clear from the
591               context menu. To restart playback from a given timestamp, use
592               Seek to position from the context menu.
593
594
595   The File Menu
596       File → Open... (Ctrl+O)
597           Opens a folder.  All files matching the selected file name filter
598           will be displayed in the file listbox and the chosen file is
599           selected.
600
601       File → Open Recent
602           Opens a recently opened folder.
603
604       File → Open Folder... (Ctrl+D)
605           Opens a folder.  All files matching the selected file name filter
606           will be displayed in the file listbox.
607
608       File → Reload (F5)
609           Reload folder.  Modified files have to be saved before. Expanded
610           subfolders will be collapsed.
611
612       File → Save (Ctrl+S)
613           Saves all changed files in the folder.  The changed files are
614           marked with a disk symbol in the file listbox. If any file names
615           have been changed, those files will be renamed.
616
617       File → Revert
618           Reverts the changes of one or multiple files.  If no files are
619           selected in the file listbox, the changes of all files will be
620           reverted, else only the changes of the selected files are reverted.
621
622       File → Import...
623           The Import dialog can be used to import data directly from a
624           freedb.org server, from a MusicBrainz server, from Discogs, Amazon
625           or other sources of album track lists in textual format.
626
627           Import from a freedb.org server is possible using a dialog which
628           appears when From Server: gnudb.org is selected. The artist and
629           album name to search for can be entered in the two topmost fields,
630           the albums which match the query will be displayed when Find is
631           clicked and the results from www.gnudb.org[7] are received.
632           Importing the track data for an album is done by double-clicking
633           the album in the list. The freedb.org server to import from can be
634           selected as well as the CGI path. The imported data is displayed in
635           the preview table of the import dialog. When satisfied with the
636           displayed tracks, they can be imported by terminating the import
637           dialog with OK.
638
639           A search on the Discogs server can be performed using Discogs. As
640           in the gnudb.org dialog, you can enter artist and album and then
641           choose from a list of releases. A Token can be entered to use the
642           RESTful Discogs API instead of their web interface, which is often
643           changed, thereby breaking the import parser. You have to register
644           for an account on Discogs[8] and then generate a token on their web
645           site (Settings/Developers, Generate new token). Don't forget to
646           Save Settings after entering the token in order to use it in
647           subsequent requests too. If Standard Tags is marked, the standard
648           information is imported, e.g.  artist, album, and title. If
649           Additional Tags is marked, more information is imported if
650           available, e.g.  performers, arrangers, or the publisher. If Cover
651           Art is marked, cover art will be downloaded if available.
652
653           A search on Amazon can be performed using Amazon. As in the
654           gnudb.org dialog, you can enter artist and album and then choose
655           from a list of releases. If Additional Tags is marked, more
656           information is imported if available, e.g.  performers, arrangers,
657           or the publisher. If Cover Art is marked, cover art will be
658           downloaded if available.
659
660           You can search in the same way in the release database of
661           MusicBrainz using From MusicBrainz Release. The workflow is the
662           same as described for From gnudb.org.
663
664           Import from a MusicBrainz server is possible using the dialog which
665           appears when From MusicBrainz Fingerprint is selected. The Server
666           can be selected as in the freedb import dialog. Below is a table
667           displaying the imported track data. The right column shows the
668           state of the MusicBrainz query, which starts with "Pending" when
669           the dialog is opened. Then the fingerprint is looked up and if it
670           does not yield a result, another lookup using the tags in the file
671           is tried. Thus it can be helpful for a successful MusicBrainz query
672           to store known information (e.g.  artist and album) in the tags
673           before the import. If a result was found, the search ends in the
674           state "Recognized", otherwise nothing was found or multiple
675           ambiguous results and one of them has to be selected by the user.
676           OK and Apply use the imported data, Cancel closes the dialog. The
677           closing can take a while since the whole MusicBrainz machinery has
678           to be shut down.
679
680           For the import of textual data, From File/Clipboard opens a
681           subdialog, where several preconfigured import formats are
682           available. The first two, "CSV unquoted" and "CSV quoted" can be
683           used to import data which was exported by the Export dialog. The
684           CSV data can be edited with a spreadsheet, and shall be written
685           using tabs as delimiters. Import should then be possible using "CSV
686           quoted", which is more flexible than "CSV unquoted". However, its
687           fields cannot contain any double quotes. If you only export from
688           Kid3 and import later, "CSV unquoted" can be used as a simple
689           format for this purpose. Note that there are also "Export CSV" and
690           "Import CSV" commands in the context menu of the file list, which
691           use scripts to export and import CSV data in a more complete,
692           powerful and flexible way.
693
694           The next format, "freedb HTML text", can be used to copy
695           information from an HTML page of freedb.org[9]. Search an album in
696           freedb and if the desired information is displayed in the web
697           browser, copy the contents to the clipboard. Then click the From
698           Clipboard button and the imported tracks will be displayed in the
699           preview table at the top of the dialog. If you are satisfied with
700           the imported data, terminate the dialog with OK, which will insert
701           the data into the tags of the current folder. The destination (Tag
702           1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box. The
703           files in the current folder should be in the correct track order to
704           get their tags assigned. This is the case if they are numbered.
705
706           The next preconfigured import format, "freedb HTML source", can be
707           used, if the data is available as an HTML document. Import is
708           possible using the From File button, which opens a file selector,
709           or copying its contents from an editor and then importing from
710           clipboard. This format can be useful for offline import, although
711           the HTML document could also be opened in a browser and then be
712           imported in the first format via the clipboard.
713
714           More preconfigured formats, e.g.  "Track Title Time", are
715           available. An empty custom format can be created with Add to be set
716           by the user. Two lines below the format name can be set with a
717           regular expression to capture the fields from the import text. The
718           first regular expression will be parsed once per document to gather
719           per-album data such as artist, album, year and genre. The second
720           line is tried to match from the start of the document to the end to
721           get track data, usually number and title. The regular expressions
722           include all the features offered by Qt(TM), which is most of the
723           what Perl offers. Bracketing constructs "(..)" create capture
724           buffers for the fields to import and are preceded by Kid3 specific
725           codes to specify which field to capture. The codes are the same as
726           used for the filename format, besides the codes listed below, any
727           frame name is possible:
728
729           •   %s %{title} Title (Song)
730
731           •   %a %{artist} Artist
732
733           •   %l %{album} Album
734
735           •   %c %{comment} Comment
736
737           •   %y %{year} Year
738
739           •   %t %{track} Track
740
741           •   %g %{genre} Genre
742
743           •   %d %{duration} Duration
744
745           For example, a track regular expression (second line) to import
746           from an .m3u playlist could be
747           "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]". All formats can
748           be changed by editing the regular expressions and the name and then
749           clicking Save Settings. They will be stored in the kid3rc file in
750           the configuration folder. This file can be directly edited to have
751           more import formats or it can be deleted to revert to the default
752           formats. Formats can be deleted using Remove.
753
754           Accuracy shows an estimation of how good the imported information
755           matches the given tracks. It uses track durations or file names to
756           calculate the level of similarity in percent.  Cover Art shows the
757           URL of the album cover image which will be downloaded.
758
759           To check whether the imported tracks match the current set of
760           files, the duration of the imported tracks can be compared with the
761           duration of the files. This option can be enabled with the check
762           box Check maximum allowable time difference (sec): and the maximum
763           tolerated difference in time can be set in seconds. If a mismatch
764           in a length is detected, the length is displayed with a red
765           background in the preview table.
766
767           If the files are ordered differently than the imported tracks,
768           their assigned tracks have to be changed. This task can be
769           facilitated using the Match with option with the buttons Length,
770           Track, and Title, which will reorder the tracks according to the
771           corresponding field. To correct the assignments manually, a track
772           can be dragged with the left mouse button and the Ctrl key hold
773           down, and then dropped at the new location.
774
775           When the import dialog is opened, it contains the actual contents
776           of the tags. The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be
777           selected using the Destination combo box. The button on the right
778           of this combo box can be used to revert the table to the current
779           contents of the tags. The check boxes in the first table column can
780           be used to select the tracks which are imported. This can be useful
781           if a folder contains the tracks of both CDs of a double CD and only
782           the tracks of the second CD have to be imported.
783
784           To identify the tracks which are imported, it is possible to
785           display the file names or the full paths to the files using the
786           context menu of the table header. The values in the import table
787           can be edited. The revert-button to the right of the Destination
788           combo box can be used to restore the contents of the tags, which
789           can also be useful after changing the Destination.
790
791           Almost all dialogs feature a Save Settings button, which can be
792           used to store the dialog specific settings and the window size
793           persistently.
794
795           From Tags leads to a subdialog to set tag frames from the contents
796           of other tag frames. This can be used to simply copy information
797           between tags or extract a part from one frame and insert it in
798           another.
799
800           As in the import from file/clipboard dialog, there are freely
801           configurable formats to perform different operations. Already
802           preconfigured are formats to copy the Album value to Album Artist,
803           Composer or Conductor, and to extract the Track Number from Title
804           fields which contain a number. There is also a format to extract a
805           Subtitle from a Title field.
806
807           The following example explains how to add a custom format, which
808           sets the information from the Subtitle field also in the Comment
809           field. Create a new format using Add button and set a new name,
810           e.g.  "Subtitle to Comment". Then enter "%{subtitle}" in Source and
811           "%{comment}(.*)" for Extraction and click Save Settings.
812
813           The expression in Source can contain format codes for arbitrary tag
814           frames, multiple codes can be used to combine the contents from
815           different frames. For each track, a text is generated from its tags
816           using the Source format, and the regular expression from Extraction
817           is applied to this text to set new values for the tags. Format
818           codes are used before the capturing parentheses to specify the tag
819           frame where the captured text shall be stored. It works in the same
820           way as for the import from file/clipboard.
821
822           Import from Tags...  is also directly available from the File menu.
823           The difference between these two functions is that the import
824           dialog subdialog operates on all files of the current folder
825           whereas the menu function operates on the selected files (which can
826           be in different folders). The menu function supports an additional
827           code "%{__return}" to return the extracted value, which can be
828           useful with the CLI and QML interfaces.
829
830       File → Import from gnudb.org...
831           Import from a freedb.org server using gnudb.org album search.  This
832           menu item opens the same import dialog as Import..., but opens
833           directly the gnudb.org dialog.
834
835       File → Import from Discogs...
836           Import from the Discogs server.  This menu item opens the same
837           import dialog as Import..., but opens directly the From Discogs
838           dialog.
839
840       File → Import from Amazon...
841           Import from Amazon.  This menu item opens the same import dialog as
842           Import..., but opens directly the From Amazon dialog.
843
844       File → Import from MusicBrainz Release...
845           Import from the MusicBrainz release database.  This menu item opens
846           the same import dialog as Import..., but opens directly the From
847           MusicBrainz Release dialog.
848
849       File → Import from MusicBrainz Fingerprint...
850           Import from a MusicBrainz server.  This menu item opens the same
851           import dialog as Import..., but opens directly the From MusicBrainz
852           Fingerprint dialog.
853
854       File → Import from Tags...
855           Like From Tags, but the import is applied to the selected files.
856
857       File → Automatic Import...
858           Automatic Import allows one to import information for multiple
859           albums from various web services. If folders are selected in the
860           file list, track data for the selected folders will be imported. If
861           no folder is selected, all folders in the file list will be
862           imported.
863
864           The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using
865           the Destination combo box.
866
867           Profiles determine which servers will be contacted to fetch album
868           information. Some profiles are predefined (All, MusicBrainz,
869           Discogs, Cover Art), custom profiles can be added using the Add
870           button at the right of the Profile combo box.
871
872           The table below shows the servers which will be used when importing
873           album information using the selected profile. The import process
874           for an album is finished if all required information has been
875           found, so the order of the rows in the table is important. It can
876           be changed using the Move Up and Move Down buttons.  Edit can be
877           used to change an existing entry. The Server selection offers the
878           same servers as can be used in the import functions.  Standard
879           Tags, Additional Tags, Cover Art determine the information which
880           shall be fetched from the server. Finally, Accuracy is the minimum
881           accuracy which must be achieved to accept the imported data. If the
882           accuracy is insufficient, the next server in the list will be
883           tried. The same dialog containing the server properties appears
884           when Add is clicked to add a new server entry. Existing entries can
885           be deleted using Remove.
886
887           To launch an automatic batch import with the selected profile,
888           click Start. Details about the running import are displayed at the
889           top of the dialog. The process can be aborted with the Abort
890           button.
891
892
893       File → Browse Cover Art...
894           The Browse Cover Art dialog helps to find album cover art.
895           Artist/Album is filled from the tags if possible.  Source offers a
896           variety of websites with album cover art. The URL with artist and
897           album as parameters can be found beneath the name.  URL-encoded
898           values for artist and album can be inserted using "%u{artist}" and
899           "%u{album}", other values from the tags are possible too, as
900           described in Configure Kid3, User Actions. More sources can be
901           entered after the entry "Custom Source" by replacing "Custom
902           Source" with the source's name, pressing Enter, then inserting the
903           URL and finally pressing Save Settings. The resulting browser
904           command is displayed at the top of the dialog and can be started by
905           clicking Browse. The browser, which can be configured in the
906           settings, is started with the selected source. A cover image can
907           then be dragged from the browser into the Kid3 window and will be
908           set in the picture frame of the selected files.
909
910           Because not all browsers support drag and drop of images and the
911           pictures on websites often have a URL, in such cases Kid3 will
912           receive the URL and not the picture. If the URL points to a
913           picture, it will be downloaded. However, if the URL refers to some
914           other web resource, it has to be translated to the corresponding
915           picture. Such mappings are defined in the table URL extraction. The
916           left column Match contains a regular expression which is compared
917           with the URL. If it matches, the captured expressions in
918           parentheses are inserted into the pattern of the right Picture URL
919           column (at the positions marked with \1 etc.). The replaced regular
920           expression contains the URL of the picture. By this means cover art
921           can be imported from Amazon, Google Images, etc.  using drag and
922           drop. It is also possible to define your own mappings.
923
924       File → Export...
925           The Export Dialog is used to store data from the tags in a file or
926           the clipboard. The editor at the top shows a preview of the data to
927           export. If the export data contain tabulator characters, the export
928           is displayed in a table. The data will be generated from the tags
929           in the current folder according to the configured format.
930
931           The format settings are similar as in the Import dialog: The
932           topmost field contains the title (e.g.  "CSV unquoted"), followed
933           by the header, which will be generated at the begin of the file.
934           The track data follows; it is used for every track. Finally, the
935           trailer can be used to generate some finishing text.
936
937           The format fields do not contain regular expressions as in the
938           Import dialog, but only output format expressions with special
939           %-expressions, which will be replaced by values from the tags. The
940           whole thing works like the file name format, and the same codes are
941           used plus some additional codes. Not only the codes listed below
942           but all tag frame names can be used.
943
944           •   %s %{title} Title (Song)
945
946           •   %a %{artist} Artist
947
948           •   %l %{album} Album
949
950           •   %c %{comment} Comment
951
952           •   %y %{year} Year
953
954           •   %t %{track} Track (e.g.  01)
955
956           •   %t %{track.n} Track with field width n (e.g.  001 for
957               %{track.3})
958
959           •   %T %{tracknumber} Track (without leading zeros, e.g.  1)
960
961           •   %g %{genre} Genre
962
963           •   %f %{file} File name
964
965           •   %p %{filepath} Path
966
967           •   %{modificationdate} Modification date
968
969           •   %{creationdate} Creation date
970
971           •   %u %{url} URL
972
973           •   %{dirname} Folder name
974
975           •   %d %{duration} Duration in minutes:seconds
976
977           •   %D %{seconds} Duration in seconds
978
979           •   %n %{tracks} Number of tracks of the album
980
981           •   %e %{extension} File extension
982
983           •   %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
984               existing)
985
986           •   %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
987               ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
988               existing)
989
990           •   %b %{bitrate} Bit rate in kbit/s
991
992           •   %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
993
994           •   %r %{samplerate} Sample rate in Hz
995
996           •   %m %{mode} Channel mode (Stereo or Joint Stereo)
997
998           •   %h %{channels} Number of channels (1 or 2)
999
1000           •   %k %{codec} Codec (e.g.  MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1001               MPC, APE, ASF, AIFF, WAV)
1002
1003           A few formats are predefined. "CSV unquoted" separates the fields
1004           by tabs. Data in this format can be imported again into Kid3 using
1005           the import format with the same name. "CSV quoted" additionally
1006           encloses the fields by double quotes, which eases the import into
1007           spreadsheet applications. However, the fields shall not contain any
1008           double quotes when this format is used. "Extended M3U" and
1009           "Extended PLS" generate playlists with extended attributes and
1010           absolute path names. "HTML" can be used to generate an HTML page
1011           with hyperlinks to the tracks. "Kover XML" creates a file which can
1012           be imported by the cover printing program Kover. "Technical
1013           Details" provides information about bit rate, sample rate,
1014           channels, etc.  Finally, "Custom Format" is left empty for
1015           definition of a custom format. You can define more formats of your
1016           own by adding lines in the file kid3rc in the configuration folder.
1017           The other formats can be adapted to your needs.
1018
1019           The Source of the tags to generate the export data (Tag 1 or Tag 2)
1020           can be selected with a combo box. Pushing To File or To Clipboard
1021           stores the data in a file or on the clipboard.  OK and Cancel close
1022           the dialog, whereas OK accepts the current dialog settings.
1023
1024       File → Create Playlist...
1025           Creates a playlist.  The format and contents of the playlist can be
1026           set by various options.
1027
1028           The name of the playlist can be the Same as folder name or use a
1029           Format with values from the tags, e.g.  "%{artist} - %{album}" to
1030           have the artist and album name in the playlist file name. The
1031           format codes are the same as for Export.  Create new empty playlist
1032           will make an empty playlist with the given name. The extension
1033           depends on the playlist format.
1034
1035           The location of the generated playlist is determined by the
1036           selection of the Create in combo box.
1037
1038           Current folder
1039               The playlist is created in the current folder and contains only
1040               files of the current folder. The current folder is the folder
1041               where the current file is located. If multiple files are
1042               selected, the current file is probably the last selected file.
1043
1044           Every folder
1045               A playlist is created in every folder which contains listed
1046               files, and each playlist contains the files of that folder.
1047
1048           Top-level folder
1049               Only one playlist is created in the top-level folder (i.e.  the
1050               folder of the file list) and it contains the listed files of
1051               the top-level folder and all of its sub-folders.
1052
1053           The Format of the playlist can be M3U, PLS or XSPF.
1054
1055           If Include only the selected files is checked, only the selected
1056           files will be included in the playlist. If a folder is selected,
1057           all of its files are selected. If this check box is not activated,
1058           all audio files are included in the playlist.
1059
1060           Sort by file name selects the usual case where the files are
1061           ordered by file name. With Sort by tag field, it is possible to
1062           sort by a format string with values from tag fields. For instance,
1063           "%{track.3}" can be used to sort by track number (the ".3" is used
1064           to get three digits with leading zeros because strings are used for
1065           sorting). It is also possible to use multiple fields, e.g.
1066           "%{genre}%{year}" to sort using a string composed of genre and
1067           year.
1068
1069           The playlist entries will have relative or absolute file paths
1070           depending on whether Use relative path for files in playlist or Use
1071           full path for files in playlist is set.
1072
1073           When Write only list of files is set, the playlist will only
1074           contain the paths to the files. To generate an extended playlist
1075           with additional information, a format string can be set using the
1076           Write info using control.
1077
1078       File → Quit (Ctrl+Q)
1079           Quits the application.
1080
1081   The Edit Menu
1082       Edit → Select All (Alt+A)
1083           Selects all files.
1084
1085       Edit → Deselect (Ctrl+Shift+A)
1086           Deselects all files.
1087
1088       Edit → Select All in Folder
1089           Selects all files of the current folder.
1090
1091       Edit → Previous File (Alt+Up)
1092           Selects the previous file.
1093
1094       Edit → Next File (Alt+Down)
1095           Selects the next file.
1096
1097       Edit → Find... (Ctrl+F)
1098           Find strings in the file names and the tags. The Find dialog is a
1099           subset of the Replace dialog, which is described below.
1100
1101       Edit → Replace... (Ctrl+R)
1102           This function opens a dialog to find and replace strings in the
1103           file names and the tags. The set of frames where the search is
1104           performed can be restricted by deactivating the Select all check
1105           box and selecting the frames which shall be searched. There are
1106           also search options available to search backwards, case
1107           sensitively, and to use regular expressions.
1108
1109           Depending on the number of files, the search might take some time,
1110           therefore it can be aborted by closing the dialog.
1111
1112   The Tools Menu
1113       Tools → Apply Filename Format
1114           When Automatically apply format is switched off for the filename
1115           format in the configuration dialog, this menu item can be used to
1116           apply the configured format to the names of the selected files.
1117           This can also be used to check whether the file names conform with
1118           the configured format by applying the format to all saved files and
1119           then checking if any files were changed (and therefore marked with
1120           a disk symbol in the file listbox).
1121
1122       Tools → Apply Tag Format
1123           When Automatically apply format is switched off for the tag format
1124           in the configuration dialog, this menu item can be used to apply
1125           the configured format to the tags of the selected files. This can
1126           also be used to check whether the tags conform with the configured
1127           format by applying the format to all saved files and then checking
1128           if any files were changed (and therefore marked with a disk symbol
1129           in the file listbox).
1130
1131       Tools → Apply Text Encoding
1132           Sets the Text encoding selected in Settings → Configure Kid3... →
1133           Tags section → Tag 2 tab for all selected files. If UTF8 is
1134           selected, UTF16 will be used for ID3v2.3.0 tags because UTF8 is not
1135           supported for this format.
1136
1137       Tools → Rename Folder...
1138           This dialog offers the possibility to automatically rename the
1139           currently open folder according to the tags in the files. Several
1140           formats are preconfigured to include information about artist,
1141           album and year in the folder name. It is also possible to set a
1142           custom format and Edit the list of available formats. The following
1143           special codes are used to insert tag values into the folder name:
1144
1145           •   %s %{title} Title (Song)
1146
1147           •   %a %{artist} Artist
1148
1149           •   %l %{album} Album
1150
1151           •   %c %{comment} Comment
1152
1153           •   %y %{year} Year
1154
1155           •   %t %{track} Track (e.g.  01)
1156
1157           •   %t %{track.n} Track with field width n (e.g.  001 for
1158               %{track.3})
1159
1160           •   %T %{tracknumber} Track (without leading zeros, e.g.  1)
1161
1162           •   %g %{genre} Genre
1163
1164           •   %{dirname} Folder name (e.g.  %{year" "}%{dirname} will prepend
1165               the year to the current folder name)
1166
1167           •   %{max-year} The maximum year value found for this folder, can
1168               also be used with other codes than "year"
1169
1170           •   %{min-year} The minimum year value found for this folder
1171
1172           •   %{unq-year} The unique year value found for this folder or
1173               empty if not unique
1174
1175           If a folder separator "/" is found in the format, multiple folders
1176           are created. If you want to create a new folder instead of renaming
1177           the current folder, in the Action combo box select Create Folder
1178           instead of Rename Folder. The Source of the tag information can be
1179           chosen between Tag 1 and Tag 2, Tag 1 and Tag 2. A preview for the
1180           rename operation performed on the first file can be seen in the
1181           From and To sections of the dialog.
1182
1183           Multiple folders can be renamed by selecting them.
1184
1185       Tools → Number Tracks...
1186           If the track numbers in the tags are not set or have the wrong
1187           values, this function can number the tracks automatically in
1188           ascending order. The start number can be set in the dialog. If only
1189           part of the tracks have to be numbered, they must be selected.
1190
1191           When Total number of tracks is checked, the number of tracks will
1192           also be set in the tags.
1193
1194           It is possible to number the tracks over multiple folders. The
1195           folders have to be expanded and selected.
1196
1197           If Reset counter for each folder is checked, track numbering is
1198           restarted with the given number for each folder when multiple
1199           folders are selected.
1200
1201           The number tracks dialog can also be used to format existing track
1202           numbers without changing the values when the check box left to
1203           Start number is deactivated. The total number of tracks will be
1204           added if the corresponding check box is active, which can be used
1205           to set the total for all selected tracks. If only formatting of the
1206           existing numbers is desired, this check box has to be deactivated
1207           too.
1208
1209       Tools → Filter...
1210           The filter can be used to display only those files which match
1211           certain criteria. This is helpful if you want to organize a large
1212           collection and only edit those files which are not in the desired
1213           scheme. The expression defining which files to display uses the
1214           same format codes which are used in the file name format, import
1215           and export.
1216
1217           •   %s %{title} Title (Song)
1218
1219           •   %a %{artist} Artist
1220
1221           •   %l %{album} Album
1222
1223           •   %c %{comment} Comment
1224
1225           •   %y %{year} Year
1226
1227           •   %t %{track} Track (e.g.  01)
1228
1229           •   %t %{track.n} Track with field width n (e.g.  001 for
1230               %{track.3})
1231
1232           •   %T %{tracknumber} Track (without leading zeros, e.g.  1)
1233
1234           •   %g %{genre} Genre
1235
1236           •   %f %{file} File name
1237
1238           •   %p %{filepath} Absolute path to file
1239
1240           •   %e %{extension} File extension
1241
1242           •   %O %{tag1} The format of tag 1 (ID3v1.1 or empty if not
1243               existing)
1244
1245           •   %o %{tag2} The format of tag 2 (ID3v2.3.0, ID3v2.4.0,
1246               ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
1247               existing)
1248
1249           •   %b %{bitrate} Bit rate in kbit/s
1250
1251           •   %v %{vbr} VBR or empty (only for ID3v2.3 with id3lib)
1252
1253           •   %r %{samplerate} Sample rate in Hz
1254
1255           •   %m %{mode} Channel mode (Stereo or Joint Stereo)
1256
1257           •   %h %{channels} Number of channels (1 or 2)
1258
1259           •   %k %{codec} Codec (e.g.  MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
1260               MPC, APE, ASF, AIFF, WAV)
1261
1262           •   %w %{marked} Marked, is 1 if the file is marked (e.g.  because
1263               of truncation or standard violation), empty otherwise
1264
1265           •   %1a %1{artist}, ... Use the prefix 1 to get values of tag 1
1266
1267           •   %2a %2{artist}, ... Use the prefix 2 to get values of tag 2
1268
1269           These codes are replaced with the values for the file, and the
1270           resulting strings can be compared with the following operations:
1271
1272           •   s1 equals s2: true if s1 and s2 are equal.
1273
1274           •   s1 contains s2: true if s1 contains s2, i.e.  s2 is a substring
1275               of s1.
1276
1277           •   s matches re: true if s matches the regular expression re.
1278
1279           True expressions are replaced by 1, false by 0. True values are
1280           represented by 1, true, on and yes, false values by 0, false, off
1281           and no. Boolean operations are not, and, or (in this order of
1282           precedence) and can be grouped by parentheses.
1283
1284           Some filter rules are predefined and can serve as examples for your
1285           own expressions:
1286
1287           All
1288               When the file list is filtered - this is shown by "[filtered]"
1289               in the window title - and all files shall be displayed again,
1290               the filtering can be reverted using this filter. It uses an
1291               empty expression, but a true value would have the same effect.
1292
1293           Filename Tag Mismatch
1294                not (%{filepath} contains "%{artist} - %{album}/%{track}
1295               %{title}")
1296
1297               Tests if the file path conforms with the file name format. This
1298               rule is automatically adapted if the file name format changes.
1299
1300           No Tag 1
1301                %{tag1} equals ""
1302
1303               Displays only files which do not have a tag 1.
1304
1305           No Tag 2
1306                %{tag2} equals ""
1307
1308               Displays only files which do not have a tag 2.
1309
1310           ID3v2.3.0 Tag
1311                %{tag2} equals "ID3v2.3.0"
1312
1313               Displays only files which have an ID3v2.3.0 tag.
1314
1315           ID3v2.4.0 Tag
1316                %{tag2} equals "ID3v2.4.0"
1317
1318               Displays only files which have an ID3v2.4.0 tag.
1319
1320           Tag 1 != Tag 2
1321                not (%1{title} equals %2{title} and %1{album} equals %2{album}
1322               and %1{artist} equals %2{artist} and %1{comment} equals
1323               %2{comment} and %1{year} equals %2{year} and %1{track} equals
1324               %2{track} and %1{genre} equals %2{genre})
1325
1326               Displays files with differences between tag 1 and tag2.
1327
1328           Tag 1 == Tag 2
1329                %1{title} equals %2{title} and %1{album} equals %2{album} and
1330               %1{artist} equals %2{artist} and %1{comment} equals %2{comment}
1331               and %1{year} equals %2{year} and %1{track} equals %2{track} and
1332               %1{genre} equals %2{genre}
1333
1334               Displays files with identical tag 1 and tag 2.
1335
1336           Incomplete
1337                %{title} equals "" or %{artist} equals "" or %{album} equals
1338               "" or %{year} equals "" or %{tracknumber} equals "" or %{genre}
1339               equals ""
1340
1341               Displays files with empty values in the standard tags (title,
1342               artist, album, date, track number, genre).
1343
1344           No Picture
1345                %{picture} equals ""
1346
1347               Displays only files which do not have a picture.
1348
1349           Marked
1350                not (%{marked} equals "")
1351
1352               Displays only files which are marked because they violate the
1353               ID3 standard, are truncated or the picture is too large.
1354
1355           Custom Filter
1356               To add your own filter, select this entry. For instance, if you
1357               want to have a filter for artists starting with "The", replace
1358               "Custom Filter" with the name "The Bands" and press Enter. Then
1359               insert the following expression into the line edit:
1360
1361                %{artist} matches "The.*"
1362
1363               Then click Save Settings. Click Apply to filter the files. All
1364               files processed are displayed in the text view, with a "+" for
1365               those who match the filter and a "-" for the others. When
1366               finished, only the files with an artist starting with "The" are
1367               displayed, and the window title is marked with "[filtered]".
1368
1369       Tools → Convert ID3v2.3 to ID3v2.4
1370           If there are any ID3v2.3 tags in the selected files, they will be
1371           converted to ID3v2.4 tags. Frames which are not supported by TagLib
1372           will be discarded. Only files without unsaved changes will be
1373           converted.
1374
1375       Tools → Convert ID3v2.4 to ID3v2.3
1376           If there are any ID3v2.4 tags in the selected files, they will be
1377           converted to ID3v2.3 tags. Only files without unsaved changes will
1378           be converted.
1379
1380       Tools → Play
1381           This opens a simple toolbar to play audio files. It contains
1382           buttons for the basic operations (Play/Pause, Stop playback,
1383           Previous Track, Next Track, Close), sliders for position and volume
1384           and a display of the current position. If multiple files are
1385           selected, the selected tracks are played, else all files will be
1386           played.
1387
1388   The Settings Menu
1389       Settings → Show Toolbar
1390           Toggles displaying of the toolbar.
1391
1392       Settings → Show Statusbar
1393           Toggles displaying of the statusbar, which displays longer actions
1394           such as opening or saving a folder.
1395
1396       Settings → Show Picture
1397           Toggles displaying of the album cover art preview picture.
1398
1399       Settings → Auto Hide Tags
1400           Empty tags are automatically hidden if this option is active. The
1401           File, Tag 1 and Tag 2 sections can be manually collapsed and
1402           expanded by clicking on the corresponding -/+ buttons.
1403
1404       Settings → Configure Shortcut keys...
1405           Opens a dialog to assign keyboard shortcuts for most of the program
1406           functions. There are even functions without corresponding menu or
1407           button available, e.g.  next file, previous file, select all.
1408
1409
1410       Settings → Configure Kid3...
1411           Opens the configuration dialog, which consists of pages for tags,
1412           files, user actions, and network settings.
1413
1414           Tag specific options can be found on the Tags page, which is itself
1415           separated into four tabs for Tag 1, Tag 2, Tag 3, and All Tags.
1416
1417           If Mark truncated fields is checked, truncated ID3v1.1 fields will
1418           be marked red. The text fields of ID3v1.1 tags can only have 30
1419           characters, the comment only 28 characters. Also the genre and
1420           track numbers are restricted, so that fields can be truncated when
1421           imported or transferred from ID3v2. Truncated fields and the file
1422           will be marked red, and the mark will be removed after the field
1423           has been edited.
1424
1425           With Text encoding for ID3v1 it is possible to set the character
1426           set used in ID3v1 tags. This encoding is supposed to be ISO-8859-1,
1427           so it is recommended to keep this default value. However, there are
1428           tags around with different encoding, so it can be set here and the
1429           ID3v1 tags can then be copied to ID3v2 which supports Unicode.
1430
1431           The check box Use track/total number of tracks format controls
1432           whether the track number field of ID3v2 tags contains simply the
1433           track number or additionally the total number of tracks in the
1434           folder.
1435
1436           When Genre as text instead of numeric string is checked, all ID3v2
1437           genres will be stored as a text string even if there is a
1438           corresponding code for ID3v1 genres. If this option is not set,
1439           genres for which an ID3v1 code exists are stored as the number of
1440           the genre code (in parentheses for ID3v2.3). Thus the genre Metal
1441           is stored as "Metal" or "(9)" depending on this option. Genres
1442           which are not in the list of ID3v1 genres are always stored as a
1443           text string. The purpose of this option is improved compatibility
1444           with devices which do not correctly interpret genre codes.
1445
1446           When WAV files with lowercase id3 chunk is checked, the RIFF chunk
1447           used to store ID3v2 tags in WAV files will be named "id3 " instead
1448           of "ID3 ". By default, Kid3 and other applications using TagLib
1449           accept both the lowercase and the uppercase variant when reading
1450           WAV files, but they use "ID3 " when writing ID3v2 tags to WAV
1451           files. As there exist other applications which only accept "id3 "
1452           (e.g.  JRiver Media Center and foobar2000), this option can be used
1453           to create tags which can be read by such applications.
1454
1455           When Mark standard violations is checked, ID3v2 fields which
1456           violate the standard will be marked red. Details about the
1457           violation are shown in a tooltip:
1458
1459           •   Must be unique
1460
1461           •   New line is forbidden
1462
1463           •   Carriage return is forbidden
1464
1465           •   Owner must be non-empty
1466
1467           •   Must be numeric
1468
1469           •   Must be numeric or number/total
1470
1471           •   Format is DDMM
1472
1473           •   Format is HHMM
1474
1475           •   Format is YYYY
1476
1477           •   Must begin with a year and a space character
1478
1479           •   Must be ISO 8601 date/time
1480
1481           •   Must be musical key, 3 characters, A-G, b, #, m, o
1482
1483           •   Must have ISO 639-2 language code, 3 lowercase characters
1484
1485           •   Must be ISRC code, 12 characters
1486
1487           •   Must be list of strings separated by '|'
1488
1489           •   Has excess white space
1490
1491           The ID3 standard documents are available online:
1492
1493ID3 tag version 2.3.0[10]
1494
1495ID3 tag version 2.4.0 - Main Structure[11]
1496
1497ID3 tag version 2.4.0 - Native Frames[5]
1498
1499           Text encoding defines the default encoding used for ID3v2 frames
1500           and can be set to ISO-8859-1, UTF16, or UTF8.  UTF8 is not valid
1501           for ID3v2.3.0 frames; if it is set, UTF16 will be used instead. For
1502           ID3v2.4.0 frames, all three encodings are possible.
1503
1504           Version used for new tags determines whether new ID3v2 tags are
1505           created as version 2.3.0 or 2.4.0.
1506
1507           Track number digits is the number of digits in Track Number fields.
1508           Leading zeros are used to pad. For instance, with a value of 2 the
1509           track number 5 is set as "05".
1510
1511           The combo box Comment field name is only relevant for Ogg/Vorbis
1512           and FLAC files and sets the name of the field used for comments.
1513           Different applications seem to use different names, "COMMENT" for
1514           instance is used by XMMS, whereas Amarok uses "DESCRIPTION".
1515
1516           The format of pictures in Ogg/Vorbis files is determined by Picture
1517           field name, which can be "METADATA_BLOCK_PICTURE" or "COVERART".
1518           The first is the official standard and uses the same format as
1519           pictures in FLAC tags. "COVERART" is an earlier unofficial way to
1520           include pictures in Vorbis comments. It can be used for
1521           compatibility with legacy players.
1522
1523           If the Mark if larger than (bytes) check box is activated, files
1524           containing embedded album cover art exceeding the given size in
1525           bytes are marked red. This can be used to find files containing
1526           oversized pictures which are not accepted by some applications and
1527           players. The default value is 131072 bytes (128 KB).
1528
1529           Custom Genres can be used to define genres which are not available
1530           in the standard genre list, e.g.  "Gothic Metal". Such custom
1531           genres will appear in the Genre combo box of Tag 2. For ID3v1.1
1532           tags, only the predefined genres can be used.
1533
1534           The list of custom genres can also be used to reduce the number of
1535           genres available in the Genre combo box to those typically used. If
1536           your collection mostly contains music in the genres Metal, Gothic
1537           Metal, Ancient and Hard Rock, you can enter those genres and mark
1538           Show only custom genres. The Tag 2 Genre combo box will then only
1539           contain those four genres and you will not have to search through
1540           the complete genres list for them. In this example, only Metal and
1541           Hard Rock will be listed in the tag 1 genres list, because those
1542           two custom genres entries are standard genres. If Show only custom
1543           genres is not active, the custom genres can be found at the end of
1544           the genres list.
1545
1546           Quick Access Frames defines which frame types are always shown in
1547           the Tag 2 section. Such frames can then be added without first
1548           using the Add button. The order of these quick access frames can be
1549           changed by dragging and dropping items.
1550
1551           The combo box Track number field name is only relevant for RIFF
1552           INFO and sets the name of the field used for track numbers. Track
1553           numbers are not specified in the original RIFF standard, there are
1554           applications which use "ITRK", others use "IPRT".
1555
1556           Tag Format contains options for the format of the tags. When
1557           Automatically apply format is checked, the format configuration is
1558           automatically used while editing text in the line edits.
1559           Validation enables validators in the controls with track/total and
1560           date/time values. The Case conversion can be set to No changes, All
1561           lowercase, All uppercase, First letter uppercase or All first
1562           letters uppercase. To use locale-aware conversion between lowercase
1563           and uppercase characters, a locale can be selected in the combobox
1564           below. The string replacement list can be set to arbitrary string
1565           mappings. To add a new mapping, select the From cell of a row and
1566           insert the text to replace, then go to the To column and enter the
1567           replacement text. When the text to replace starts and ends with a
1568           slash ("/"), a regular expression is used. For regular expressions
1569           containing capturing groups, occurrences of \1, \2, ... in To are
1570           replaced with the string captured by the corresponding capturing
1571           group. To remove a mapping set the From cell to an empty value
1572           (e.g.  by first typing space and then backspace). Inserting and
1573           deleting rows is also possible using a context menu which appears
1574           when the right mouse button is clicked. Replacement is only active,
1575           if the String replacement check box is checked.
1576
1577           The table in Rating contains the mapping of star ratings to the
1578           effective values stored in the tag. The frames with rating
1579           information are listed in the Rating row of the frame list. For
1580           these frames, the rating can be set by giving a number of stars out
1581           of five stars. Different tag formats and different applications use
1582           different values to map the star rating to the value stored in the
1583           tag. In order to display the correct number of stars, Kid3 will
1584           look up a map in this table. The key to look up the mapping is the
1585           frame name, for example "RATING" as used for Vorbis comments or
1586           "IRTD" for RIFF INFO. For ID3v2 tags, a combined key is used
1587           consisting of the frame ID "POPM" of the Popularimeter frame and
1588           its "Email" field, separated by a dot. Therefore, different keys
1589           for ID3v2 exist, e.g.  "POPM.Windows Media Player 9 Series" for the
1590           mapping used by Windows Media Player and Explorer, and simply
1591           "POPM" for POPM frames with an empty "Email" field. As multiple
1592           entries for "POPM" can exist, their order is important. When Kid3
1593           adds a new Popularimeter frame, it will use the first "POPM" entry
1594           to determine the value to be written into the "Email" field. This
1595           value will then specify the mapping to be used for star ratings.
1596           The first entry is also used if no key was found, it is therefore
1597           the default entry.
1598
1599           Besides the Name column containing the keys, the table has columns
1600           1 to 5 for the values to be stored when the corresponding number of
1601           stars is given. The other way round, the values determine the
1602           number of stars which are displayed for the value stored in the
1603           frame. For instance, the row in the table below contains the values
1604           1, 64, 128, 196, 255. The thresholds for the number of stars to be
1605           displayed lay between these values and are compatible with what the
1606           Windows® Explorer uses.
1607
1608           Table 1. Entry in Rating Table
1609           ┌──────┬──────┬───────┬────────┬─────────┬─────────┐
1610Name  1    2     3      4       5       
1611           ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1612           │POPM  │ 1    │ 64    │ 128    │ 196     │ 255     │
1613           ├──────┼──────┼───────┼────────┼─────────┼─────────┤
1614           │Range │ 1-31 │ 32-95 │ 96-159 │ 160-223 │ 224-255 │
1615           └──────┴──────┴───────┴────────┴─────────┴─────────┘
1616           On the page Files the check box Load last-opened files can be
1617           marked so that Kid3 will open and select the last selected file
1618           when it is started the next time.  Preserve file timestamp can be
1619           checked to preserve the file modification time stamp.  Filename for
1620           cover sets the name which is suggested when an embedded image is
1621           exported to a file. With Text encoding (Export, Playlist) the
1622           encoding used when writing files can be set. The default System can
1623           be changed for example if playlists have to be used on a different
1624           device.
1625
1626           If Mark changes is active, changed fields are marked with a light
1627           gray label background.
1628
1629           The section File List determines which files are displayed in the
1630           file list. A Filter can be used to restrict the items in this list
1631           to files with supported extensions. To explicitly specify which
1632           folders to display in the file list or exclude certain folders, the
1633           options Include folders and Exclude folders can be used. They can
1634           contain wildcard expressions, for instance */Music/* to include
1635           only the Music folder, or */iTunes/* to exclude the iTunes folder
1636           from the file list. If multiple such expressions have to be used,
1637           they can be separated by spaces or semicolons.
1638
1639           The buttons Filename from tag and Tag from filename in section
1640           Format open dialogs to edit the formats which are available in the
1641           Format combo boxes (with arrows up and down), which can be found in
1642           the File section of the main window.
1643
1644           Filename Format contains options for the format of the filenames.
1645           The same options as in Tag Format are available.
1646
1647           The User Actions page contains a table with the commands which are
1648           available in the context menu of the file list. For critical
1649           operations such as deleting files, it is advisable to mark Confirm
1650           to pop up a confirmation dialog before executing the command.
1651           Output can be marked to see the output written by console commands
1652           (standard output and standard error).  Name is the name displayed
1653           in the context menu.  Command is the command line to be executed.
1654           Arguments can be passed using the following codes:
1655
1656           •   %F %{files} File paths (a list if multiple files selected)
1657
1658           •   %f %{file} File path to single file
1659
1660           •   %uF %{urls} URLs (a list if multiple files selected)
1661
1662           •   %uf %{url} URL to single file
1663
1664           •   %d %{directory} Folder
1665
1666           •   %s %{title} Title (Song)
1667
1668           •   %a %{artist} Artist
1669
1670           •   %l %{album} Album
1671
1672           •   %c %{comment} Comment
1673
1674           •   %y %{year} Year
1675
1676           •   %t %{track} Track (e.g.  01)
1677
1678           •   %t %{track.n} Track with field width n (e.g.  001 for
1679               %{track.3})
1680
1681           •   %T %{tracknumber} Track (without leading zeros, e.g.  1)
1682
1683           •   %g %{genre} Genre
1684
1685           •   %b %{browser} Command to start the web browser
1686
1687           •   %q %{qmlpath} Base folder of provided QML files
1688
1689           The special code @separator can be set as a command to insert a
1690           separator into the user actions context menu. Menu items can be put
1691           into a submenu by enclosing them with @beginmenu and @endmenu
1692           commands. The name of the submenu is determined by the Name column
1693           of the @beginmenu command.
1694
1695           To execute QML scripts, @qml is used as a command name. The path to
1696           the QML script is passed as a parameter. The provided scripts can
1697           be found in the folder %{qmlpath}/script/ (on Linux® typically
1698           /usr/share/kid3/qml/script/, on Windows qml/script/ inside the
1699           installation folder, and on macOS® in the app folder
1700           kid3.app/Contents/Resources/qml/script/). Custom scripts can be
1701           stored in any folder. If the QML code uses GUI components, @qmlview
1702           shall be used instead of @qml. Additional parameters are passed to
1703           the QML script where they will be available via the getArguments()
1704           function. An overview of some functions and properties which are
1705           available in QML can be found in the appendix QML Interface.
1706
1707           The command which will be inserted with %{browser} can be defined
1708           in the Web browser line edit above. Commands starting with
1709           %{browser} can be used to fetch information about the audio files
1710           from the web, for instance
1711
1712               %{browser} http://lyricwiki.org/%u{artist}:%u{title}
1713
1714           will query the lyrics for the current song in LyricWiki[12]. The
1715           "u" in %u{artist} and %u{title} is used to URL-encode the artist
1716           %{artist} and song %{title} information. It is easy to define your
1717           own queries in the same way, e.g.  an image search with Google[13]:
1718
1719               %{browser} http://images.google.com/images?q=%u{artist}%20%u{album}
1720
1721           To add album cover art to tag 2, you can search for images with
1722           Google or Amazon using the commands described above. The picture
1723           can be added to the tag with drag and drop. You can also add an
1724           image with Add, then select the Picture frame and import an image
1725           file or paste from the clipboard. Picture frames are supported for
1726           ID3v2, MP4, FLAC, Ogg and ASF tags.
1727
1728           To add and delete entries in the table, a context menu can be used.
1729
1730           The Network page contains only a field to insert the proxy address
1731           and optionally the port, separated by a colon. The proxy will be
1732           used when importing from an Internet server when the check box is
1733           checked.
1734
1735           In the Plugins page, available plugins can be enabled or disabled.
1736           The plugins are separated into two sections. The Metadata Plugins &
1737           Priority list contains plugins which support audio file formats.
1738           The order of the plugins is important because they are tried from
1739           top to bottom. Some formats are supported by multiple plugins, so
1740           files will be opened with the first plugin supporting them. The
1741           TaglibMetadata supports most formats, if it is at the top of the
1742           list, it will open most of the files. If you want to use a
1743           different plugin for a file format, make sure that it is listed
1744           before the TaglibMetadata plugin. Details about the metadata plugin
1745           and why you may want to use them instead of TagLib are listed
1746           below.
1747
1748           •   Id3libMetadata: Uses id3lib[14] for ID3v1.1 and ID3v2.3 tags in
1749               MP3, MP2, AAC files. Supports a few more frame types than
1750               TagLib.
1751
1752           •   OggFlacMetadata: Uses libogg[15], libvorbis, libvorbisfile[16]
1753               for Ogg files, and additionally libFLAC++ and libFLAC[17] for
1754               FLAC files. These are the official libraries for these formats.
1755
1756           •   TaglibMetadata: Uses TagLib[18] which supports a lot of audio
1757               file formats. It can be used for all audio files supported by
1758               Kid3.
1759
1760           •   Mp4v2Metadata: mp4v2[19] was originally used by Kid3 to support
1761               M4A files. Can be used in case of problems with the M4A support
1762               of TagLib.
1763
1764           The Available Plugins section lists the remaining plugins. Their
1765           order is not important, but they can be enabled or disabled using
1766           the check boxes.
1767
1768           •   AmazonImport: Used for the Import from Amazon...  function.
1769
1770           •   DiscogsImport: Used for the Import from Discogs...  function.
1771
1772           •   FreedbImport: Used for the Import from gnudb.org...  function.
1773
1774           •   MusicBrainzImport: Used for the Import from MusicBrainz
1775               Release...  function.
1776
1777           •   AcoustidImport: Used for the Import from MusicBrainz
1778               Fingerprint...  function, which depends on the Chromaprint[20]
1779               and libav[21] libraries.
1780
1781           Plugins which are disabled will not be loaded. This can be used to
1782           optimize resource usage and startup time. The settings on this page
1783           take only effect after a restart of Kid3.
1784
1785   The Help Menu
1786       Help → Kid3 Handbook
1787           Opens this handbook.
1788
1789       Help → About Kid3
1790           Displays a short information about Kid3.
1791

KID3-CLI

1793   Commands
1794       kid3-cli offers a command-line-interface for Kid3. If a folder path is
1795       used, the folder is opened. If one or more file paths are given, the
1796       common folder is opened and the files are selected. Subsequent commands
1797       will then work on these files. Commands are specified using -c options.
1798       If multiple commands are passed, they are executed in the given order.
1799       If files are modified by the commands, they will be saved at the end.
1800       If no command options are passed, kid3-cli starts in interactive mode.
1801       Commands can be entered and will operate on the current selection. The
1802       following sections list all available commands.
1803
1804       Help
1805           help [COMMAND-NAME]
1806
1807           Displays help about the parameters of COMMAND-NAME or about all
1808           commands if no command name is given.
1809
1810       Timeout
1811           timeout [default | off | TIME]
1812
1813           Overwrite the default command timeout. The CLI commands abort after
1814           a command specific timeout is expired. This timeout is 10 seconds
1815           for ls and albumart, 60 seconds for autoimport and filter, and 3
1816           seconds for all other commands. If a huge number of files has to be
1817           processed, these timeouts may be too restrictive, thus the timeout
1818           for all commands can be set to TIME ms, switched off altogether or
1819           be left at the default values.
1820
1821       Quit application
1822           exit [force]
1823
1824           Exit application. If there are modified unsaved files, the force
1825           parameter is required.
1826
1827       Change folder
1828           cd [FOLDER]
1829
1830           If no FOLDER is given, change to the home folder. If a folder is
1831           given, change into the folder. If one or more file paths are given,
1832           change to their common folder and select the files.
1833
1834       Print the filename of the current folder
1835           pwd
1836
1837           Print the filename of the current working folder.
1838
1839       Folder list
1840           ls
1841
1842           List the contents of the current folder. This corresponds to the
1843           file list in the Kid3 GUI. Five characters before the file names
1844           show the state of the file.
1845
1846           •   > File is selected.
1847
1848           •   * File is modified.
1849
1850           •   1 File has a tag 1, otherwise '-' is displayed.
1851
1852           •   2 File has a tag 2, otherwise '-' is displayed.
1853
1854           •   3 File has a tag 3, otherwise '-' is displayed.
1855
1856               kid3-cli> ls
1857                 1-- 01 Intro.mp3
1858               > 12- 02 We Only Got This One.mp3
1859                *1-- 03 Outro.mp3
1860
1861           In this example, all files have a tag 1, the second file also has a
1862           tag 2 and it is selected. The third file is modified.
1863
1864       Save the changed files
1865           save
1866
1867       Select file
1868           select [all | none | first | previous | next | FILE...]
1869
1870           To select all files, enter select all, to deselect all files, enter
1871           select none. To traverse the files in the current folder start with
1872           select first, then go forward using select next or backward using
1873           select previous. Specific files can be added to the current
1874           selection by giving their file names. Wildcards are possible, so
1875           select *.mp3 will select all MP3 files in the current folder.
1876
1877               kid3-cli> select first
1878               kid3-cli> ls
1879               > 1-- 01 Intro.mp3
1880                 12- 02 We Only Got This One.mp3
1881                *1-- 03 Outro.mp3
1882               kid3-cli> select next
1883               kid3-cli> ls
1884                 1-- 01 Intro.mp3
1885               > 12- 02 We Only Got This One.mp3
1886                *1-- 03 Outro.mp3
1887               kid3-cli> select *.mp3
1888               kid3-cli> ls
1889               > 1-- 01 Intro.mp3
1890               > 12- 02 We Only Got This One.mp3
1891               >*1-- 03 Outro.mp3
1892
1893       Select tag
1894           tag [TAG-NUMBERS]
1895
1896           Many commands have an optional TAG-NUMBERS parameter, which
1897           specifies whether the command operates on tag 1, 2, or 3. If this
1898           parameter is omitted, the default tag numbers are used, which can
1899           be set by this command. At startup, it is set to 12 which means
1900           that information is read from tag 2 if available, else from tag 1;
1901           modifications are done on tag 2. The TAG-NUMBERS can be set to 1,
1902           2, or 3 to operate only on the corresponding tag. If the parameter
1903           is omitted, the current setting is displayed.
1904
1905       Get tag frame
1906           get [all | FRAME-NAME] [TAG-NUMBERS]
1907
1908           This command can be used to read the value of a specific tag frame
1909           or get information about all tag frames (if the argument is omitted
1910           or all is used). Modified frames are marked with a '*'.
1911
1912               kid3-cli> get
1913               File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
1914                 Name: 01 Intro.mp3
1915               Tag 1: ID3v1.1
1916                 Title         Intro
1917                 Artist        One Hit Wonder
1918                 Album         Let's Tag
1919                 Date          2013
1920                 Track Number  1
1921                 Genre         Pop
1922               kid3-cli> get title
1923               Intro
1924
1925           To save the contents of a picture frame to a file, use
1926
1927               get picture:'/path/to/folder.jpg'
1928
1929           To save synchronized lyrics to an LRC file, use
1930
1931               get SYLT:'/path/to/lyrics.lrc'
1932
1933           It is possible to get only a specific field from a frame, for
1934           example get POPM.Email for the Email field of a Popularimeter
1935           frame. If a file has multiple frames of the same kind, the
1936           different frames can be indexed with brackets, for example the
1937           first performer from a Vorbis comment can be retrieved using get
1938           performer[0], the second using get performer[1].
1939
1940           The pseudo field name "selected" can be used to check if a frame is
1941           selected, for example get artist.selected will return 1 if the
1942           artist frame is selected, else 0.
1943
1944       Set tag frame
1945           set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]
1946
1947           This command sets the value of a specific tag frame. If FRAME-VALUE
1948           is empty, the frame is deleted.
1949
1950               kid3-cli> set remixer 'O.H. Wonder'
1951
1952           To set the contents of a picture frame from a file, use
1953
1954               set picture:'/path/to/folder.jpg' 'Picture Description'
1955
1956           To set synchronized lyrics from an LRC file, use
1957
1958               set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'
1959
1960           To set a specific field of a frame, the field name can be given
1961           after a dot, e.g.  to set the Counter field of a Popularimeter
1962           frame, use
1963
1964               set POPM.Counter 5
1965
1966           An application for field specifications is the case where you want
1967           a custom TXXX frame with "rating" description instead of a standard
1968           Popularimeter frame (this seems to be used by some plugins). You
1969           can create such a TXXX rating frame with kid3-cli, however, you
1970           have to first create a TXXX frame with description "rating" and
1971           then set the value of this frame to the rating value.
1972
1973               kid3-cli> set rating ""
1974               kid3-cli> set TXXX.Description rating
1975               kid3-cli> set rating 5
1976
1977           The first command will delete an existing POPM frame, because if
1978           such a frame exists, set rating 5 would set the POPM frame and not
1979           the TXXX frame. Another possibility would be to use set TXXX.Text
1980           5, but this would only work if there is no other TXXX frame
1981           present.
1982
1983           To set multiple frames of the same kind, an index can be given in
1984           brackets, e.g.  to set multiple performers in a Vorbis comment, use
1985
1986               kid3-cli> set performer[0] 'Liza don Getti (soprano)'
1987               kid3-cli> set performer[1] 'Joe Barr (piano)'
1988
1989           To select certain frames before a copy, paste or remove action, the
1990           pseudo field name "selected" can be used. Normally, all frames are
1991           selected, to deselect all, use set '*.selected' 0, then for example
1992           set artist.selected 1 to select the artist frame.
1993
1994       Revert
1995           revert
1996
1997           Revert all modifications in the selected files (or all files if no
1998           files are selected).
1999
2000       Import from file
2001           import {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2002
2003           Tags are imported from the file FILE in the format with the name
2004           FORMAT-NAME (e.g.  "CSV unquoted", see Import).
2005
2006           If tags is given for FILE, tags are imported from other tags.
2007           Instead of FORMAT-NAME parameters SOURCE and EXTRACTION are
2008           required, see Import from Tags. To apply the import from tags on
2009           the selected files, use tagsel instead of tags. This function also
2010           supports output of the extracted value by using an EXTRACTION with
2011           the value %{__return}(.+).
2012
2013       Automatic import
2014           autoimport [PROFILE-NAME] [TAG-NUMBERS]
2015
2016           Batch import using profile PROFILE-NAME (see Automatic Import,
2017           "All" is used if omitted).
2018
2019       Download album cover artwork
2020           albumart {URL} [all]
2021
2022           Set the album artwork by downloading a picture from URL. The rules
2023           defined in the Browse Cover Art dialog are used to transform
2024           general URLs (e.g.  from Amazon) to a picture URL. To set the album
2025           cover from a local picture file, use the set command.
2026
2027               kid3-cli> albumart
2028               http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
2029
2030       Export to file
2031           export {FILE} {FORMAT-NAME} [TAG-NUMBERS]
2032
2033           Tags are exported to file FILE in the format with the name
2034           FORMAT-NAME (e.g.  "CSV unquoted", see Export).
2035
2036       Create playlist
2037           playlist
2038
2039           Create playlist in the format set in the configuration, see Create
2040           Playlist.
2041
2042       Apply filename format
2043           filenameformat
2044
2045           Apply file name format set in the configuration, see Apply Filename
2046           Format.
2047
2048       Apply tag format
2049           tagformat
2050
2051           Apply tag name format set in the configuration, see Apply Tag
2052           Format.
2053
2054       Apply text encoding
2055           textencoding
2056
2057           Apply text encoding set in the configuration, see Apply Text
2058           Encoding.
2059
2060       Rename folder
2061           renamedir [FORMAT] [create | rename | dryrun] [TAG-NUMBERS]
2062
2063           Rename or create folders from the values in the tags according to a
2064           given FORMAT (e.g.  %{artist} - %{album}, see Rename Folder), if no
2065           format is given, the format defined in the Rename folder dialog is
2066           used. The default mode is rename; to create folders, create must be
2067           given explicitly. The rename actions will be performed immediately,
2068           to just see what would be done, use the dryrun option.
2069
2070       Number tracks
2071           numbertracks [TRACK-NUMBER] [TAG-NUMBERS]
2072
2073           Number the selected tracks starting with TRACK-NUMBER (1 if
2074           omitted).
2075
2076       Filter
2077           filter [FILTER-NAME | FILTER-FORMAT]
2078
2079           Filter the files so that only the files matching the FILTER-FORMAT
2080           are visible. The name of a predefined filter expression (e.g.
2081           "Filename Tag Mismatch") can be used instead of a filter
2082           expression, see Filter.
2083
2084               kid3-cli> filter '%{title} contains "tro"'
2085               Started
2086                 /home/urs/One Hit Wonder - Let's Tag
2087               + 01 Intro.mp3
2088               - 02 We Only Got This One.mp3
2089               + 03 Outro.mp3
2090               Finished
2091               kid3-cli> ls
2092                 1-- 01 Intro.mp3
2093                 1-- 03 Outro.mp3
2094               kid3-cli> filter All
2095               Started
2096                 /home/urs/One Hit Wonder - Let's Tag
2097               + 01 Intro.mp3
2098               + 02 We Only Got This One.mp3
2099               + 03 Outro.mp3
2100               Finished
2101               kid3-cli> ls
2102                 1-- 01 Intro.mp3
2103                 12- 02 We Only Got This One.mp3
2104                 1-- 03 Outro.mp3
2105
2106       Convert ID3v2.3 to ID3v2.4
2107           to24
2108
2109       Convert ID3v2.4 to ID3v2.3
2110           to23
2111
2112       Filename from tag
2113           fromtag [FORMAT] [TAG-NUMBERS]
2114
2115           Set the file names of the selected files from values in the tags,
2116           for example fromtag '%{track} - %{title}' 1. If no format is
2117           specified, the format set in the GUI is used.
2118
2119       Tag from filename
2120           totag [FORMAT] [TAG-NUMBERS]
2121
2122           Set the tag frames from the file names, for example totag
2123           '%{albumartist} - %{album}/%{track} %{title}' 2. If no format is
2124           specified, the format set in the GUI is used. If the format of the
2125           filename does not match this pattern, a few other commonly used
2126           formats are tried.
2127
2128       Tag to other tag
2129           syncto {TAG-NUMBER}
2130
2131           Copy the tag frames from one tag to the other tag, e.g.  to set the
2132           ID3v2 tag from the ID3v1 tag, use syncto 2.
2133
2134       Copy
2135           copy [TAG-NUMBER]
2136
2137           Copy the tag frames of the selected file to the internal copy
2138           buffer. They can then be set on another file using the paste
2139           command.
2140
2141           To copy only a subset of the frames, use the "selected" pseudo
2142           field with the set command. For example, to copy only the disc
2143           number and copyright frames, use
2144
2145               set '*.selected' 0
2146               set discnumber.selected 1
2147               set copyright.selected 1
2148               copy
2149
2150
2151       Paste
2152           paste [TAG-NUMBER]
2153
2154           Set tag frames from the contents of the copy buffer in the selected
2155           files.
2156
2157       Remove
2158           remove [TAG-NUMBER]
2159
2160           Remove a tag.
2161
2162           It is possible to remove only a subset of the frames by selecting
2163           them as described in the copy command.
2164
2165       Configure Kid3
2166           config [OPTION] [VALUE]
2167
2168           Query or set a configuration option.
2169
2170           The OPTION consists of a group name and a property name separated
2171           by a dot. When no OPTION is given, all available groups are
2172           displayed. If only a group name is given, all available properties
2173           of the group are displayed. For a given group and property, the
2174           currently configured value is displayed. To change the setting, the
2175           new value can be passed as a second argument.
2176
2177           If the value of a setting is a list, all list elements have to be
2178           given as arguments. This means that to append an element to an
2179           existing list of elements, all existing elements have to be passed
2180           followed by the new element. In such a situation, it is easier to
2181           use the JSON mode, where the current list can be copied with the
2182           new element appended.
2183
2184   Examples
2185       Set title containing an apostrophe. Commands passed to kid3-cli with -c
2186       have to be in quotes if they do not only consist of a single word. If
2187       such a command itself has an argument containing spaces, that argument
2188       has to be quoted too. In UNIX® shells single or double quotes can be
2189       used, but on the Windows Command Prompt, it is important that the outer
2190       quoting is done using double quotes and inside these quotes, single
2191       quotes are used. If the text inside the single quotes contains a single
2192       quote, it has to be escaped using a backslash character, as shown in
2193       the following example:
2194
2195           kid3-cli -c "set title 'I\'ll be there for you'" /path/to/folder
2196
2197       Set album cover in all files of a folder using the batch import
2198       function:
2199
2200           kid3-cli -c "autoimport 'Cover Art'" /path/to/folder
2201
2202       Remove comment frames and apply the tag format in both tags of all MP3
2203       files of a folder:
2204
2205           kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
2206           -c "tagformat 1" -c "tagformat 2" /path/to/folder/*.mp3
2207
2208       Automatically import tag 2, synchronize to tag 1, set file names from
2209       tag 2 and finally create a playlist:
2210
2211           kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
2212             /path/to/folder/*.mp3
2213
2214       For all files with an ID3v2.4.0 tag, convert to ID3v2.3.0 and remove
2215       the arranger frame:
2216
2217           kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
2218             -c "set arranger ''" /path/to/folder
2219
2220       This Python script uses kid3-cli to generate iTunes Sound Check
2221       iTunNORM frames from replay gain information.
2222
2223
2224           #!/usr/bin/env python3
2225           # Generate iTunes Sound Check from ReplayGain.
2226           import os, sys, subprocess
2227
2228           def rg2sc(dirpath):
2229             for root, dirs, files in os.walk(dirpath):
2230               for name in files:
2231                 if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
2232                   fn = os.path.join(root, name)
2233                   rg = subprocess.check_output([
2234                     'kid3-cli', '-c', 'get "replaygain_track_gain"',
2235                      fn]).strip()
2236                   if rg.endswith(b' dB'):
2237                     rg = rg[:-3]
2238                   try:
2239                     rg = float(rg)
2240                   except ValueError:
2241                     print('Value %s of %s in not a float' % (rg, fn))
2242                     continue
2243                   sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
2244                   subprocess.call([
2245                     'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])
2246
2247           if __name__ == '__main__':
2248             rg2sc(sys.argv[1])
2249
2250
2251   JSON Format
2252       In order to make it easier to parse results from kid3-cli, it is
2253       possible to get the output in JSON format. When the request is in JSON
2254       format, the response will also be JSON. A compact format of the request
2255       will also give a compact representation of the response. If the request
2256       contains an "id" field, it is assumed to be a JSON-RPC request and the
2257       response will contain a "jsonrpc" field and the "id" of the request.
2258       The request format uses the same commands as the standard CLI, the
2259       "method" field contains the command and the parameters (if any) are
2260       given in the "params" list. The response contains a "result" object,
2261       which can also be null if the corresponding kid3-cli command does not
2262       return a result. In case of an error, an "error" object is returned
2263       with "code" and "message" fields as used in JSON-RPC.
2264
2265           kid3-cli> {"method":"set","params":["artist","An Artist"]}
2266           {"result":null}
2267           kid3-cli> {"method":"get","params":["artist",2]}
2268           {"result":"An Artist"}
2269           kid3-cli> {"method": "get", "params": ["artist"]}
2270           {
2271               "result": "An Artist"
2272           }
2273
2274           kid3-cli> {"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}
2275           {"id":"123","jsonrpc":"2.0","result":"An Artist"}
2276
2277

CREDITS AND LICENSE

2279       Kid3
2280
2281       Program written by Urs Fleisch <ufleisch at users.sourceforge.net>
2282
2283       FDL[22]
2284
2285       GPL[23]
2286

INSTALLATION

2288   How to obtain Kid3
2289       Kid3 can be found at https://kid3.kde.org.
2290
2291   Requirements
2292       Kid3 needs Qt(TM)[24].  KDE[25] is recommended but not necessary, as
2293       Kid3 can also be compiled as a Qt(TM) application.  Kid3 can be
2294       compiled for systems where these libraries are available, e.g.  for
2295       GNU/Linux®, Windows® and macOS®. To tag Ogg/Vorbis files, libogg[15],
2296       libvorbis and libvorbisfile[16] are required, for FLAC files libFLAC++
2297       and libFLAC[17].  id3lib[14] is used for MP3 files. These four formats
2298       are also supported by TagLib[18], which can also handle Opus, MPC, APE,
2299       MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker
2300       modules. To import from acoustic fingerprints, Chromaprint[20] and
2301       libav[21] are used.
2302
2303       Kid3 is available for most Linux® distributions, Windows® and macOS®.
2304       Links can be found on https://kid3.kde.org.
2305
2306   Compilation and Installation
2307       You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple
2308       Qt(TM) application and lacks some configuration and session features.
2309
2310       For a KDE version, go into the top folder and type
2311
2312           % cmake .
2313           % make
2314           % make install
2315
2316       To compile for different versions of Qt(TM) or KDE, set the
2317       corresponding cmake options.
2318
2319       If not all libraries are present, Kid3 is built with reduced
2320       functionality. So you should take care to have all desired development
2321       packages installed. On the other side, cmake-options control which
2322       libraries are compiled in. The default is -DWITH_TAGLIB:BOOL=ON
2323       -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON
2324       -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON . These options can be
2325       disabled using OFF.
2326
2327       To build Kid3 as a Qt(TM) application without KDE, use the cmake option
2328       -DWITH_APPS=Qt. To build both a KDE and a Qt(TM) application, set
2329       -DWITH_APPS="Qt;KDE".
2330
2331       To use a specific Qt(TM) installation, set
2332       -DQT_QMAKE_EXECUTABLE=/path/to/qmake.
2333
2334       Generation of RPM-Packages is supported by the file kid3.spec, for
2335       Debian® Packages, the script build-deb.sh is available.
2336
2337       The Qt(TM) application can also be compiled for Windows® and macOS®.
2338       The script buildlibs.sh can be used to download and build all required
2339       libraries and create a Kid3 package.
2340
2341   Configuration
2342       With KDE, the settings are stored in .config/kid3rc. As a Qt(TM)
2343       application, this file is in .config/Kid3/Kid3.conf. On Windows®, the
2344       configuration is stored in the registry. on macOS® in a plist file.
2345
2346       The environment variable KID3_CONFIG_FILE can be used to set the path
2347       of the configuration file.
2348

D-BUS INTERFACE

2350   D-Bus Examples
2351       On Linux® a D-Bus-interface can be used to control Kid3 by scripts.
2352       Scripts can be written in any language with D-Bus-bindings (e.g.  in
2353       Python) and can be added to the User Actions to extend the
2354       functionality of Kid3.
2355
2356       The artist in tag 2 of the current file can be set to the value "One
2357       Hit Wonder" with the following code:
2358
2359       Shell
2360
2361               dbus-send --dest=org.kde.kid3 --print-reply=literal \
2362               /Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
2363               string:'One Hit Wonder'
2364
2365           or easier with Qt(TM)'s qdbus (qdbusviewer can be used to explore
2366           the interface in a GUI):
2367
2368               qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
2369               'One Hit Wonder'
2370
2371       Python
2372
2373               import dbus
2374               kid3 = dbus.SessionBus().get_object(
2375                 'org.kde.kid3', '/Kid3')
2376               kid3.setFrame(2, 'Artist', 'One Hit Wonder')
2377
2378       Perl
2379
2380               use Net::DBus;
2381               $kid3 = Net::DBus->session->get_service(
2382                 "org.kde.kid3")->get_object(
2383                 "/Kid3", "org.kde.Kid3");
2384               $kid3->setFrame(2, "Artist", "One Hit Wonder");
2385
2386   D-Bus API
2387       The D-Bus API is specified in org.kde.Kid3.xml. The Kid3 interface has
2388       the following methods:
2389
2390       Open file or folder
2391           boolean openDirectory(string path);
2392
2393           path
2394               path to file or folder
2395
2396           Returns true if OK.
2397
2398       Unload the tags of all files which are not modified or selected
2399           unloadAllTags(void);
2400
2401       Save all modified files
2402           boolean save(void);
2403
2404           Returns true if OK.
2405
2406       Get a detailed error message provided by some methods
2407           string getErrorMessage(void);
2408
2409           Returns detailed error message.
2410
2411       Revert changes in the selected files
2412           revert(void);
2413
2414       Start an automatic batch import
2415           boolean batchImport(int32 tagMask, string profileName);
2416
2417           tagMask
2418               tag mask (bit 0 for tag 1, bit 1 for tag 2)
2419
2420           profileName
2421               name of batch import profile to use
2422
2423       Import tags from a file
2424           boolean importFromFile(int32 tagMask, string path, int32 fmtIdx);
2425
2426           tagMask
2427               tag bit (1 for tag 1, 2 for tag 2)
2428
2429           path
2430               path of file
2431
2432           fmtIdx
2433               index of format
2434
2435           Returns true if OK.
2436
2437       Import tags from other tags
2438           importFromTags(int32 tagMask, string source, string extraction);
2439
2440           tagMask
2441               tag bit (1 for tag 1, 2 for tag 2)
2442
2443           source
2444               format to get source text from tags
2445
2446           extraction
2447               regular expression with frame names and captures to extract
2448               from source text
2449
2450       Import tags from other tags on selected files
2451           array importFromTagsToSelection(int32 tagMask, string source,
2452                                           string extraction);
2453
2454           tagMask
2455               tag bit (1 for tag 1, 2 for tag 2)
2456
2457           source
2458               format to get source text from tags
2459
2460           extraction
2461               regular expression with frame names and captures to extract
2462               from source text
2463
2464           returnValues
2465               extracted value for "%{__return}(.+)"
2466
2467       Download album cover art
2468           downloadAlbumArt(string url, boolean allFilesInDir);
2469
2470           url
2471               URL of picture file or album art resource
2472
2473           allFilesInDir
2474               true to add the image to all files in the folder
2475
2476       Export tags to a file
2477           boolean exportToFile(int32 tagMask, string path, int32 fmtIdx);
2478
2479           tagMask
2480               tag bit (1 for tag 1, 2 for tag 2)
2481
2482           path
2483               path of file
2484
2485           fmtIdx
2486               index of format
2487
2488           Returns true if OK.
2489
2490       Create a playlist
2491           boolean createPlaylist(void);
2492
2493           Returns true if OK.
2494
2495       Get items of a playlist
2496           array getPlaylistItems(string path);
2497
2498           path
2499               path to playlist file
2500
2501           Returns list of absolute paths to playlist items.
2502
2503       Set items of a playlist
2504           boolean setPlaylistItems(string path, array items);
2505
2506           path
2507               path to playlist file
2508
2509           items
2510               list of absolute paths to playlist items
2511
2512           Returns true if OK, false if not all items were found and added or
2513           saving failed.
2514
2515       Quit the application
2516           quit(void);
2517
2518       Select all files
2519           selectAll(void);
2520
2521       Deselect all files
2522           deselectAll(void);
2523
2524       Set the first file as the current file
2525           boolean firstFile(void);
2526
2527           Returns true if there is a first file.
2528
2529       Set the previous file as the current file
2530           boolean previousFile(void);
2531
2532           Returns true if there is a previous file.
2533
2534       Set the next file as the current file
2535           boolean nextFile(void);
2536
2537           Returns true if there is a next file.
2538
2539       Select the first file
2540           boolean selectFirstFile(void);
2541
2542           Returns true if there is a first file.
2543
2544       Select the previous file
2545           boolean selectPreviousFile(void);
2546
2547           Returns true if there is a previous file.
2548
2549       Select the next file
2550           boolean selectNextFile(void);
2551
2552           Returns true if there is a next file.
2553
2554       Select the current file
2555           boolean selectCurrentFile(void);
2556
2557           Returns true if there is a current file.
2558
2559       Expand or collapse the current file item if it is a folder
2560           boolean expandDirectory(void);
2561
2562           A file list item is a folder if getFileName() returns a name with
2563           '/' as the last character.
2564
2565           Returns true if current file item is a folder.
2566
2567       Apply the file name format
2568           applyFilenameFormat(void);
2569
2570       Apply the tag format
2571           applyTagFormat(void);
2572
2573       Apply text encoding
2574           applyTextEncoding(void);
2575
2576       Set the folder name from the tags
2577           boolean setDirNameFromTag(int32 tagMask, string format,
2578                                     boolean create);
2579
2580           tagMask
2581               tag mask (bit 0 for tag 1, bit 1 for tag 2)
2582
2583           format
2584               folder name format
2585
2586           create
2587               true to create, false to rename
2588
2589           Returns true if OK, else the error message is available using
2590           getErrorMessage().
2591
2592       Set subsequent track numbers in the selected files
2593           numberTracks(int32 tagMask, int32 firstTrackNr);
2594
2595           tagMask
2596               tag mask (bit 0 for tag 1, bit 1 for tag 2)
2597
2598           firstTrackNr
2599               number to use for first file
2600
2601       Filter the files
2602           filter(string expression);
2603
2604           expression
2605               filter expression
2606
2607       Convert ID3v2.3 tags to ID3v2.4
2608           convertToId3v24(void);
2609
2610       Convert ID3v2.4 tags to ID3v2.3
2611           convertToId3v23(void);
2612
2613           Returns true if OK.
2614
2615       Get path of folder
2616           string getDirectoryName(void);
2617
2618           Returns absolute path of folder.
2619
2620       Get name of current file
2621           string getFileName(void);
2622
2623           Returns true absolute file name, ends with "/" if it is a folder.
2624
2625       Set name of selected file
2626           setFileName(string name);
2627
2628           name
2629               file name
2630
2631           The file will be renamed when the folder is saved.
2632
2633       Set format to use when setting the filename from the tags
2634           setFileNameFormat(string format);
2635
2636           format
2637               file name format
2638
2639       Set the file names of the selected files from the tags
2640           setFileNameFromTag(int32 tagMask);
2641
2642           tagMask
2643               tag bit (1 for tag 1, 2 for tag 2)
2644
2645       Get value of frame
2646           string getFrame(int32 tagMask, string name);
2647
2648           tagMask
2649               tag bit (1 for tag 1, 2 for tag 2)
2650
2651           name
2652               name of frame (e.g.  "artist")
2653
2654           To get binary data like a picture, the name of a file to write can
2655           be added after the name, e.g.  "Picture:/path/to/file". In the same
2656           way, synchronized lyrics can be exported, e.g.
2657           "SYLT:/path/to/file".
2658
2659           Returns value of frame.
2660
2661       Set value of frame
2662           boolean setFrame(int32 tagMask, string name, string value);
2663
2664           tagMask
2665               tag bit (1 for tag 1, 2 for tag 2)
2666
2667           name
2668               name of frame (e.g.  "artist")
2669
2670           value
2671               value of frame
2672
2673           For tag 2 (tagMask 2), if no frame with name exists, a new frame is
2674           added, if value is empty, the frame is deleted. To add binary data
2675           like a picture, a file can be added after the name, e.g.
2676           "Picture:/path/to/file". "SYLT:/path/to/file" can be used to import
2677           synchronized lyrics.
2678
2679           Returns true if OK.
2680
2681       Get all frames of a tag
2682           array of string getTag(int32 tagMask);
2683
2684           tagMask
2685               tag bit (1 for tag 1, 2 for tag 2)
2686
2687           Returns list with alternating frame names and values.
2688
2689       Get technical information about file
2690           array of string getInformation(void);
2691
2692           Properties are Format, Bitrate, Samplerate, Channels, Duration,
2693           Channel Mode, VBR, Tag 1, Tag 2. Properties which are not available
2694           are omitted.
2695
2696           Returns list with alternating property names and values.
2697
2698       Set tag from file name
2699           setTagFromFileName(int32 tagMask);
2700
2701           tagMask
2702               tag bit (1 for tag 1, 2 for tag 2)
2703
2704       Set tag from other tag
2705           setTagFromOtherTag(int32 tagMask);
2706
2707           tagMask
2708               tag bit (1 for tag 1, 2 for tag 2)
2709
2710       Copy tag
2711           copyTag(int32 tagMask);
2712
2713           tagMask
2714               tag bit (1 for tag 1, 2 for tag 2)
2715
2716       Paste tag
2717           pasteTag(int32 tagMask);
2718
2719           tagMask
2720               tag bit (1 for tag 1, 2 for tag 2)
2721
2722       Remove tag
2723           removeTag(int32 tagMask);
2724
2725           tagMask
2726               tag bit (1 for tag 1, 2 for tag 2)
2727
2728       Reparse the configuration
2729           reparseConfiguration(void);
2730
2731           Automated configuration changes are possible by modifying the
2732           configuration file and then reparsing the configuration.
2733
2734       Plays the selected files
2735           playAudio(void);
2736

QML INTERFACE

2738   QML Examples
2739       QML scripts can be invoked via the context menu of the file list and
2740       can be set in the tab User Actions of the settings dialog. The scripts
2741       which are set there can be used as examples to program custom scripts.
2742       QML uses JavaScript, here is the obligatory "Hello World":
2743
2744           import Kid3 1.0
2745
2746           Kid3Script {
2747             onRun: {
2748               console.log("Hello world, folder is", app.dirName)
2749               Qt.quit()
2750             }
2751           }
2752
2753       If this script is saved as /path/to/Example.qml, the user command can
2754       be defined as @qml /path/to/Example.qml with name QML Test and Output
2755       checked. It can then be started using the QML Test item in the file
2756       list context menu, and the output will be visible in the window.
2757
2758       Alternatively, the script could also be started independent of Kid3
2759       using the QML tools.
2760
2761           qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2762
2763       or
2764
2765           qmlscene -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
2766
2767       On Windows® and macOS®, the import path must be adapted to the imports
2768       folder inside the installation folder. Scripts started outside of Kid3
2769       will use the current folder, so it should be changed beforehand.
2770
2771       To list the titles in the tags 2 of all files in the current folder,
2772       the following script could be used:
2773
2774           import Kid3 1.0
2775
2776           Kid3Script {
2777             onRun: {
2778               app.firstFile()
2779               do {
2780                 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2781                   console.log(app.getFrame(tagv2, "title"))
2782                 }
2783               } while (app.nextFile())
2784             }
2785           }
2786
2787       If the folder contains many files, such a script might block the user
2788       interface for some time. For longer operations, it should therefore
2789       have a break from time to time. The alternative implementation below
2790       has the work for a single file moved out into a function. This function
2791       invokes itself with a timeout of 1 ms at the end, given that more files
2792       have to be processed. This will ensure that the GUI remains responsive
2793       while the script is running.
2794
2795           import Kid3 1.0
2796
2797           Kid3Script {
2798             onRun: {
2799               function doWork() {
2800                 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2801                   console.log(app.getFrame(tagv2, "title"))
2802                 }
2803                 if (!app.nextFile()) {
2804                   Qt.quit()
2805                 } else {
2806                   setTimeout(doWork, 1)
2807                 }
2808               }
2809
2810               app.firstFile()
2811               doWork()
2812             }
2813           }
2814
2815       When using app.firstFile() with app.nextFile(), all files of the
2816       current folder will be processed. If only the selected files shall be
2817       affected, use firstFile() and nextFile() instead, these are convenience
2818       functions of the Kid3Script component. The following example is a
2819       script which copies only the disc number and copyright frames of the
2820       selected file.
2821
2822           import Kid3 1.1
2823
2824           Kid3Script {
2825             onRun: {
2826               function doWork() {
2827                 if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
2828                   app.setFrame(tagv2, "*.selected", false)
2829                   app.setFrame(tagv2, "discnumber.selected", true)
2830                   app.setFrame(tagv2, "copyright.selected", true)
2831                   app.copyTags(tagv2)
2832                 }
2833                 if (!nextFile()) {
2834                   Qt.quit()
2835                 } else {
2836                   setTimeout(doWork, 1)
2837                 }
2838               }
2839
2840               firstFile()
2841               doWork()
2842             }
2843           }
2844
2845       More example scripts come with Kid3 and are already registered as user
2846       commands.
2847
2848       •   ReplayGain to SoundCheck (ReplayGain2SoundCheck.qml): Create
2849           iTunNORM SoundCheck information from replay gain frames.
2850
2851       •   Resize Album Art (ResizeAlbumArt.qml): Resize embedded cover art
2852           images which are larger than 500x500 pixels.
2853
2854       •   Extract Album Art (ExtractAlbumArt.qml): Extract all embedded cover
2855           art pictures avoiding duplicates.
2856
2857       •   Embed Album Art (EmbedAlbumArt.qml): Embed cover art found in image
2858           files into audio files in the same folder.
2859
2860       •   Embed Lyrics (EmbedLyrics.qml): Fetch unsynchronized lyrics from
2861           web service.
2862
2863       •   Text Encoding ID3v1 (ShowTextEncodingV1.qml): Helps to find the
2864           encoding of ID3v1 tags by showing the tags of the current file in
2865           all available character encodings.
2866
2867       •   ID3v1 to ASCII (Tag1ToAscii.qml): Transliterate extended latin
2868           characters in the ID3v1 tag to ASCII.
2869
2870       •   English Title Case (TitleCase.qml): Formats text in the tags to
2871           English title case.
2872
2873       •   Rewrite Tags (RewriteTags.qml): Rewrite all tags in the selected
2874           files.
2875
2876       •   Export CSV (ExportCsv.qml): Export recursively all tags of all
2877           files to a CSV file.
2878
2879       •   Export Playlist Folder (ExportPlaylist.qml): Copy all files from a
2880           playlist into a folder and rename them according to their position.
2881
2882       •   QML Console (QmlConsole.qml): Simple console to play with Kid3's
2883           QML API.
2884
2885
2886   QML API
2887       The API can be easily explored using the QML Console, which is
2888       available as an example script with a user interface.
2889
2890       Kid3Script
2891           Kid3Script is a regular QML component located inside the plugin
2892           folder. You could use another QML component just as well. Using
2893           Kid3Script makes it easy to start the script function using the
2894           onRun signal handler. Moreover it offers some functions:
2895
2896               onRun: Signal handler which is invoked when the script is started
2897               tagv1, tagv2, tagv2v1: Constants for tag parameters
2898               script: Access to scripting functions
2899               configs: Access to configuration objects
2900               getArguments(): List of script arguments
2901               isStandalone(): true if the script was not started from within Kid3
2902               setTimeout(callback, delay): Starts callback after delay ms
2903               firstFile(): To first selected file
2904               nextFile(): To next selected file
2905
2906
2907       Scripting Functions
2908           As JavaScript and therefore QML too has only a limited set of
2909           functions for scripting, the script object has some additional
2910           methods, for instance:
2911
2912               script.properties(obj): String with Qt properties
2913               script.writeFile(filePath, data): Write data to file, true if OK
2914               script.readFile(filePath): Read data from file
2915               script.removeFile(filePath): Delete file, true if OK
2916               script.fileExists(filePath): true if file exists
2917               script.fileIsWritable(filePath): true if file is writable
2918               script.getFilePermissions(filePath): Get file permission mode bits
2919               script.setFilePermissions(filePath, modeBits): Set file permission mode bits
2920               script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
2921                 file " ")
2922               script.renameFile(oldName, newName): Rename file, true if OK
2923               script.copyFile(source, dest): Copy file, true if OK
2924               script.makeDir(path): Create folder, true if OK
2925               script.removeDir(path): Remove folder, true if OK
2926               script.tempPath(): Path to temporary folder
2927               script.musicPath(): Path to music folder
2928               script.listDir(path, [nameFilters], [classify]): List folder entries
2929               script.system(program, [args], [msecs]): Synchronously start a system command,
2930                 [exit code, standard output, standard error] if not timeout
2931               script.systemAsync(program, [args], [callback]): Asynchronously start a system
2932               command, callback will be called with [exit code, standard output, standard
2933               error]
2934               script.getEnv(varName): Get value of environment variable
2935               script.setEnv(varName, value): Set value of environment variable
2936               script.getQtVersion(): Qt version string, e.g. "5.4.1"
2937               script.getDataMd5(data): Get hex string of the MD5 hash of data
2938               script.getDataSize(data): Get size of byte array
2939               script.dataToImage(data, [format]): Create an image from data bytes
2940               script.dataFromImage(img, [format]): Get data bytes from image
2941               script.loadImage(filePath): Load an image from a file
2942               script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
2943               script.imageProperties(img): Get properties of an image, map containing
2944                 "width", "height", "depth" and "colorCount", empty if invalid image
2945               script.scaleImage(img, width, [height]): Scale an image, returns scaled image
2946
2947       Application Context
2948           Using QML, a large part of the Kid3 functions are accessible. The
2949           API is similar to the one used for D-Bus. For details, refer to the
2950           respective notes.
2951
2952               app.openDirectory(path): Open folder
2953               app.unloadAllTags(): Unload all tags
2954               app.saveDirectory(): Save folder
2955               app.revertFileModifications(): Revert
2956               app.importTags(tag, path, fmtIdx): Import file
2957               app.importFromTags(tag, source, extraction): Import from tags
2958               app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
2959               app.downloadImage(url, allFilesInDir): Download image
2960               app.exportTags(tag, path, fmtIdx): Export file
2961               app.writePlaylist(): Write playlist
2962               app.getPlaylistItems(path): Get items of a playlist
2963               app.setPlaylistItems(path, items): Set items of a playlist
2964               app.selectAllFiles(): Select all
2965               app.deselectAllFiles(): Deselect
2966               app.firstFile([select], [onlyTaggedFiles]): To first file
2967               app.nextFile([select], [onlyTaggedFiles]): To next file
2968               app.previousFile([select], [onlyTaggedFiles]): To previous file
2969               app.selectCurrentFile([select]): Select current file
2970               app.selectFile(path, [select]): Select a specific file
2971               app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
2972               app.requestExpandFileList(): Expand all
2973               app.applyFilenameFormat(): Apply filename format
2974               app.applyTagFormat(): Apply tag format
2975               app.applyTextEncoding(): Apply text encoding
2976               app.numberTracks(nr, total, tag, [options]): Number tracks
2977               app.applyFilter(expr): Filter
2978               app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
2979               app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
2980               app.getFilenameFromTags(tag): Filename from tags
2981               app.getTagsFromFilename(tag): Filename to tags
2982               app.getAllFrames(tag): Get object with all frames
2983               app.getFrame(tag, name): Get frame
2984               app.setFrame(tag, name, value): Set frame
2985               app.getPictureData(): Get data from picture frame
2986               app.setPictureData(data): Set data in picture frame
2987               app.copyToOtherTag(tag): Tags to other tags
2988               app.copyTags(tag): Copy
2989               app.pasteTags(tag): Paste
2990               app.removeTags(tag): Remove
2991               app.playAudio(): Play
2992               app.readConfig(): Read configuration
2993               app.applyChangedConfiguration(): Apply configuration
2994               app.dirName: Folder name
2995               app.selectionInfo.fileName: File name
2996               app.selectionInfo.filePath: Absolute file path
2997               app.selectionInfo.detailInfo: Format details
2998               app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
2999               app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
3000               app.selectionInfo.formatString(tag, format): Substitute codes in format string
3001               app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
3002               select a file
3003               app.selectDirName(caption, dir): Open file dialog to select a folder
3004
3005           For asynchronous operations, callbacks can be connected to signals.
3006
3007               function automaticImport(profile) {
3008                 function onAutomaticImportFinished() {
3009                   app.batchImporter.finished.disconnect(onAutomaticImportFinished)
3010                 }
3011                 app.batchImporter.finished.connect(onAutomaticImportFinished)
3012                 app.batchImport(profile, tagv2)
3013               }
3014
3015               function renameDirectory(format) {
3016                 function onRenameActionsScheduled() {
3017                   app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
3018                   app.performRenameActions()
3019                 }
3020                 app.renameActionsScheduled.connect(onRenameActionsScheduled)
3021                 app.renameDirectory(tagv2v1, format, false)
3022               }
3023
3024       Configuration Objects
3025           The different configuration sections are accessible via methods of
3026           configs. Their properties can be listed in the QML console.
3027
3028               script.properties(configs.networkConfig())
3029
3030           Properties can be set:
3031
3032               configs.networkConfig().useProxy = false
3033
3034
3035
3036               configs.batchImportConfig()
3037               configs.exportConfig()
3038               configs.fileConfig()
3039               configs.filenameFormatConfig()
3040               configs.filterConfig()
3041               configs.findReplaceConfig()
3042               configs.guiConfig()
3043               configs.importConfig()
3044               configs.mainWindowConfig()
3045               configs.networkConfig()
3046               configs.numberTracksConfig()
3047               configs.playlistConfig()
3048               configs.renDirConfig()
3049               configs.tagConfig()
3050               configs.tagFormatConfig()
3051               configs.userActionsConfig()
3052

AUTHOR

3054       Urs Fleisch <ufleisch at users.sourceforge.net>
3055           Software development
3056
3058       Copyright © 2021 Urs Fleisch
3059
3060       FDL
3061
3062

NOTES

3064        1. gnudb.org
3065           http://gnudb.org
3066
3067        2. MusicBrainz
3068           http://musicbrainz.org
3069
3070        3. Discogs
3071           http://discogs.com
3072
3073        4. Amazon
3074           http://www.amazon.com
3075
3076        5. ID3 specification
3077           http://id3.org/id3v2.4.0-frames
3078
3079        6. SYLT Editor
3080           http://www.compuphase.com/software_sylteditor.htm
3081
3082        7. www.gnudb.org
3083           http://www.gnudb.org
3084
3085        8. Discogs
3086           https://www.discogs.com/
3087
3088        9. freedb.org
3089           http://freedb.org
3090
3091       10. ID3 tag version 2.3.0
3092           http://id3.org/id3v2.3.0
3093
3094       11. ID3 tag version 2.4.0 - Main Structure
3095           http://id3.org/id3v2.4.0-structure
3096
3097       12. LyricWiki
3098           http://www.lyricwiki.org
3099
3100       13. Google
3101           http://www.google.com
3102
3103       14. id3lib
3104           http://id3lib.sourceforge.net
3105
3106       15. libogg
3107           http://xiph.org/ogg/
3108
3109       16. libvorbis, libvorbisfile
3110           http://xiph.org/vorbis/
3111
3112       17. libFLAC++ and libFLAC
3113           http://flac.sourceforge.net
3114
3115       18. TagLib
3116           http://taglib.github.io/
3117
3118       19. mp4v2
3119           http://code.google.com/p/mp4v2
3120
3121       20. Chromaprint
3122           http://acoustid.org/chromaprint
3123
3124       21. libav
3125           http://libav.org/
3126
3127       22. FDL
3128           http://www.gnu.org/licenses/licenses.html#FDL
3129
3130       23. GPL
3131           http://www.gnu.org/licenses/licenses.html#GPL
3132
3133       24. Qt(TM)
3134           https://www.qt.io
3135
3136       25. KDE
3137           http://www.kde.org
3138
3139
3140
31413.8.6                             2021-03-18                           KID3(1)
Impressum