KID3(1) | The Kid3 Handbook | KID3(1) |
NAME¶
kid3, kid3-qt, kid3-cli - Kid3 ID3 TaggerSYNOPSIS¶
kid3 [--help | --help-qt |
--help-kde | --help-all
| --author | --version | --license] [FILE...]
| --author | --version | --license] [FILE...]
kid3-qt [Qt-options] [FILE...]
kid3-cli [-h | --help]
[-c COMMAND1] [ -c COMMAND2...]
[FILE...]
OPTIONS¶
FILEIf FILE is the path to a directory, it will be
opened. If one or more file paths are given, their common directory is opened
and the files are selected.
kid3¶
--helpShow help about options.
--help-qt
Show Qt specific options, see qtoptions(7).
--help-kde
Show KDE specific options, see
kdeoptions(7).
--help-all
Show all options.
--author
Show author information.
--version
Show version information.
--license
Show license information.
kid3-qt¶
Qt-optionsSee qtoptions(7), however, the options have
"-" as a prefix, not "--".
kid3-cli¶
-cExecute a command. Multiple -c options are
possible, they are executed in sequence. See the section about kid3-cli for a
description of the available commands.
-h|--help
Show help about options and commands.
INTRODUCTION¶
Kid3 is an application to edit the ID3v1 and ID3v2 tags in MP3 files in an efficient way. These tags can be edited by most MP3 players, but not in a very comfortable and efficient way. Moreover the tags in Ogg/Vorbis, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker modules (MOD, S3M, IT, XM) are supported too. Kid3 does not grab nor encode MP3 files, but it is targeted to edit the ID3 tags of all files of an album in an efficient way, i.e. with as few mouse clicks and key strokes as possible. Where most other programs can edit either ID3v1 or ID3v2 tags, Kid3 has full control over both versions, can convert tags between the two formats and has access to all ID3v2 tags. Tags of multiple files can be set to the same value, e.g. the artist, album, year and genre of all files of an album typically have the same values and can be set together. If the information for the tags is contained in the file name, the tags can be automatically set from the file name. It is also possible to set the file name according to the tags found in the file in arbitrary formats. The editing task is further supported by automatic replacement of characters or substrings, for instance to remove illegal characters from filenames. Automatic control of upper and lower case characters makes it easy to use a consistent naming scheme in all tags. The tag information for full albums can be taken from gnudb.org[1], TrackType.org[2], MusicBrainz[3], Discogs[4], Amazon[5] or other sources of track lists. The import format is freely configurable by regular expressions. Please report any problems or feature requests to the author.USING KID3¶
Kid3 features¶
•Edit ID3v1.1 tags
•Edit all ID3v2.3 and ID3v2.4 frames
•Edit tags of multiple files
•Convert between ID3v1 and ID3v2 tags
•Edit MP3, Ogg/Vorbis, FLAC, MPC, APE, MP4/AAC,
MP2, Speex, TrueAudio, WavPack, WMA, WAV and AIFF tags
•Generate tags from filename
•Generate tags from the contents of tag
fields
•Generate filename from tags
•Generate and change directory names from
tags
•Generate playlist file
•Automatic case conversion and string
translation
•Import from gnudb.org[1],
TrackType.org[2], MusicBrainz[3], Discogs[4],
Amazon[5] and other data sources
•Export as CSV, HTML, playlist, Kover XML and
other formats. Exported CSV files can be imported again.
Example Usage¶
This section describes a typical session with Kid3. Let's assume we have a directory containing MP3 files with the tracks from the album "Let's Tag" from the band "One Hit Wonder". The directory is named in the "artist - album" format, in our case One Hit Wonder - Let's Tag. The directory contains the tracks in the "track title.mp3" format, which I think is useful because the filenames are short (important when using mobile MP3 players with small displays) and in the correct order when sorted alphabetically (important when using hardware MP3 players which play the tracks in alphabetical order or in the order in which they are burnt on CD and that order is alphabetical when using mkisofs). Besides this, the artist and album information is already in the directory name and does not have to be repeated in the filename. But back to our example, the directory listing looks like this: 01 Intro.mp3 02 We Only Got This One.mp3 03 Outro.mp3 These files have no tags yet and we want to generate them using Kid3. We use Open (File menu or toolbar) and select one of the files in this directory. All files will be displayed in the file listbox. Lazy as we are, we want to use the information in the directory and file names to generate tags. Therefore we select all files, then click the To:Tag 1 button in the File section. This will set the title, artist, album and track values in all files. To set the year and genre values of all files, we keep all files selected and type in "2002" for the Year and select "Pop" from the Genre combobox. To set only these two values, their checkboxes are automatically checked and all other checkboxes are left unchecked. Now we change the selection by only selecting the first file and we see that all tags contain the correct values. The tags of the other files can be verified too by selecting them one by one. When we are satisfied with the tags, we use Save (File menu or toolbar). Selecting Create Playlist from the File menu will generate a file One Hit Wonder - Let's Tag.m3u in the directory.COMMAND REFERENCE¶
The GUI Elements¶
The Kid3 GUI is separated in five sections: At the left are the file and directory listboxes, the right side contains the File, Tag 1 and Tag 2 sections.
The file list contains the names of all the files in the opened directory which
match the selected file name filter (typically *.mp3 *.ogg *.flac *.mpc *.aac
*.m4a *.m4b *.m4p *.mp4 *.mp2 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape). A
single or multiple files can be selected. To select no file, click into the
empty area after the listbox entries. The selection determines the files which
are affected by the operations which are available by using the buttons
described below.
Besides Name, also other columns Size, Type, Date Modified with file details can
be displayed. Columns can be hidden by unchecking their name in the context
menu of the list header. The order of the columns can be changed by
drag'n'drop. The sort order can be toggled by clicking on the column header.
At the left of the names an icon can be displayed: a disc to show that the file
has been modified or information about which tags are present (V1, V2, V1V2 or
NO TAG, no icon is displayed if the file has not been read in yet).
Directories are displayed with a folder icon. If a directory is opened, its
files are displayed in a hierarchical tree. By selecting files from
subdirectories, operations can be executed on files in different directories,
which is useful if the music collection is organized with a folder for each
artist containing folders for albums of this artist.
Clicking the right mouse button inside the file list opens a context menu with
the following commands:
•Expand all: Expands all folder trees
•Collapse all: Collapses all folder trees
•Rename: Changes the name of a file
•Move to Trash: Moves a file to the trash
•Play: Plays a file, see Play
•The subsequent entries are user commands, which
can be defined in the User Actions tab of Configure Kid3. The playback on
double click can also be activated there.
The directory list contains the names of the directories in the opened
directory, as well as the current (.) and the parent (..) directory. It allows
to quickly change the directory without using the Open... command or drag and
drop.
Column visiblity, order and sorting can be configured as described in the
section about the file list.
Shows information about the encoding (MP3, Ogg, FLAC, MPC, APE, MP2, MP4, AAC,
Speex, TrueAudio, WavPack, WMA, WAV, AIFF), bit rate, sample rate, channels
and the length of the file.
The Name line edit contains the name of the file (if only a single file is
selected). If this name is changed, the file will be renamed when the Save
command is used.
The Format combo box and line edit contains the format to be used when the
filename is generated from the first or the second tag. The filename can
contain arbitrary characters, even a directory part separated by a slash from
the file name, but that directory must already exist for the renaming to
succeed. The following special codes are used to insert tag values into the
filename:
•%s %{title} Title (Song)
•%a %{artist} Artist
•%l %{album} Album
•%c %{comment} Comment
•%y %{year} Year
•%t %{track} Track (e.g. 01)
•%t %{track.n} Track with field width n (e.g. 001
for %{track.3})
•%T %{tracknumber} Track (without leading zeros,
e.g. 1)
•%g %{genre} Genre
•%{ignore} Ignored when generating tags from the
file name
The format codes are not restricted to the examples given above. Any frame name
can be used, for instance unified frame names like %{bpm} or format
specific names like %{popm}.
A second Format combo box (with arrow down) is used to generate the tags from
the filename. If the format of the filename does not match this pattern, a few
other commonly used formats are tried.
Some commonly used filename formats are already available in the combo box, but
it is also possible to type in some special format into the line edit.
From:Tag 1, Tag 2: Sets the filename using the selected format and the first tag
or the second tag, respectively.
To:Tag 1, Tag 2: The tags are set from the filename. First, the format specified
in Format is used. If the existing filename does not match this format, the
following formats are tried:
•Artist - Album/Track Song
•Album/Track - Artist - Song
•/Artist - Album - Track - Song
•Album/Artist - Track - Song
•Album/Artist - Song
•Artist/Album/Track Song
If a single file is selected, the GUI controls are filled with the values
extracted from the filename. If multiple files are selected, the tags of the
files are directly set according to the filenames.
The line edit widgets for Title, Artist, Album, Comment, Year, Track and Genre
are used to edit the corresponding value in the first tag of the selected
files. The value will be changed when the file selection is altered or before
operations like Save and Quit and when the corresponding check box at the left
of the field name is checked. This is useful to change only some values and
leave the other values unchanged.
If a single file is selected, all check boxes are checked and the line edit
widgets contain the values found in the tags of this file. If a tag is not
found in the file, the corresponding empty value is displayed, which is an
empty string for the Title, Artist, Album and Comment line edits, 0 for the
numerical Year and Track edits and an empty selected value for the Genre combo
box. The values can be changed and if the corresponding check box is checked,
they will be set for the selected file after the selection is changed. The
file is then marked as modified by a disk symbol in the file listbox but
remains unchanged until the Save command is used.
If multiple files are selected, only the values which are identical in all
selected files are displayed. In all other controls, the empty values as
described above are displayed. All check boxes are unchecked to avoid unwanted
changes. If a value has to be set for all selected files, it can be edited and
the checkbox has to be set. The values will be set for all selected files when
the selection is changed and can be saved using the Save command.
The check boxes also control the operation of most commands affecting the tags,
such as copy, paste and transfer between tags 1 and 2. To make it easier to
use with multiple files where all check boxes are unchecked, these commands
behave in the same way when all check boxes are checked and when all check
boxes are unchecked.
From Tag 2: The tag 1 fields are set from the corresponding values in tag 2. If
a single file is selected, the GUI controls are filled with the values from
tag 2. If multiple files are selected, the tags of the files are directly set.
Copy: The copy buffer is filled with the Tag 1 values. Only values with checked
checkbox will be used in subsequent Paste commands.
Paste: Pastes the values from the copy buffer into the GUI controls.
Remove: This will set all GUI controls to their empty values which results in
removing all values. The saved file will then contain no tag 1.
The GUI controls function in the same way as described for the Tag 1 section,
but the size of the strings is not limited.
For the tag 2 Genre you can also use your own names besides the genres listed in
the combo box, just type the name into the line edit.
The tag 2 can not only contain the same values as the tag 1, the format is built
in a flexible way from several frames which are themselves composed of several
fields. The tag 2 table shows all the frames which are available in the
selected file.
Edit: This will open a window which allows to edit all fields of the selected
frame. If multiple files are selected, the edited fields are applied to all
selected files which contain such a frame.
Add: A requester to select the frame type will appear and a frame of the
selected type can be edited and added to the file. This works also to add a
frame to multiple selected files.
Delete: Deletes the selected frame in the selected files.
Drag album artwork here is shown if the file does not contain embedded cover
art. A picture can be added using drag and drop from a browser or file manager
and will be displayed here. Picture frames can be edited or added by double
clicking on this control.
For information synchronized with the audio data, a specific editor is
available. These frames are supported for ID3v2.3.0 and ID3v2.4.0 tags. To add
such a frame, the specific frame name has to be selected in the list which
appears when the Add button is clicked - SYLT - Synchronized lyric/text or
ETCO - Event timing codes, respectively. The editor is the same for both
types, for the event timing codes, only a predefined set of events is
available whereas for the synchronized lyrics, text has to be entered. In the
following, editing synchronized lyrics is explained.
A file having an ID3v2 tag is selected, the lyrics editor is entered using Add
and selecting SYLT - Synchronized lyric/text. For an existing SYLT frame, it
is selected and Edit is clicked. The player is automatically opened with the
current file so that the file can be played and paused to synchronize lyrics.
The settings at the top of the SYLT editor normally do not have to be changed.
If the lyrics contains characters which are not present in the Latin 1
character set, changing the text encoding to UTF16 (or UTF8 for ID3v2.4.0) is
advisable. For English lyrics and maximum compatibility, ISO-8859-1 should be
used.
The Lyrics section has five buttons at the top. Add will add a new time event in
the table. The time is taken from the position of the player, thus adding an
entry while playing the track will add a line for the currently played
position. The events in the table have to be chronologically ordered,
therefore the row will be inserted accordingly. Entries with an invalid time
are treated specially: If the currently selected row has an invalid time, its
time stamp will be replaced by the current time instead of adding a new row.
If the current time is not invalid, the first row with an invalid time will be
used if present. This behavior should facilitate adding time stamps if the
lyrics text is already in the table but the time stamps are missing (which is
the case when importing unsynchronized lyrics). Note that the invalid time is
represented as 00:00.00, i.e. the same as the time at the absolute beginning
of the track, which is not invalid. To make a time invalid, press the Delete
key, or use Clear from the context menu. New rows inserted using Insert row
from the context menu or created when importing unsynchronized lyrics with
From Clipboard or Import also contain invalid time stamps. Rows in the table
can be deleted by clicking the Delete button or using Delete rows from the
context menu.
Synchronized lyrics can be imported from a file using Import. The expected
format is simple or enhanced LRC. If the selected file does not contain a
square bracket in the first line, it is supposed to be a simple text file with
unsynchronized lyrics. The lines from such a file are then imported having
invalid time stamps. The time information can be added using the Add button or
by manual entry. It is also possible to import lyrics via copy-paste using
From Clipboard. Synchronized lyrics can be written to LRC files using Export.
Note that only entries with valid time stamps will be exported and that the
entries will be sorted by time. Entries with invalid time won't be stored in
the SYLT frame either, so make sure to include all timing information before
leaving the dialog.
The ID3 specification[6] suggests a time stamp for each syllable. However
most players only support the granularity of a line or sentence. To support
both use cases, Kid3 follows the same conventions as SYLT Editor[7].
Text which is entered into the table is assumed to start a new line unless it
starts with a space or a hyphen. Exceptions to this rule are possible by
starting a line with an underscore ('_') to force continuation or a hash mark
('#') to force a new line. These escape characters are not stored inside the
SYLT frame. Inside the SYLT frame, new lines start with a line feed character
(hex 0A) whereas continuations do not. When reading SYLT frames, Kid3 checks
if the first entry starts with a line feed. If this is not the case, it is
assumed that all entries are new lines and that no syllable continuations are
used.
While the track is played, the row associated with the current playing position
is highlighted, so that the correctness of the synchronization information can
be verified. If an offset has to be added to one or more time stamps, this can
be accomplished with the Add offset context menu. Negative values can be used
to reduce the time. Using Seek to position in the context menu, it is possible
to set the playing position to the time of the selected row.
The File Menu¶
File → Open... (Ctrl+O)Opens a directory. All files matching the selected file
name filter will be displayed in the file listbox and the chosen file is
selected.
File → Open Recent
Opens a recently opened directory.
File → Open Directory... (Ctrl+D)
Opens a directory. All files matching the selected file
name filter will be displayed in the file listbox.
File → Save (Ctrl+S)
Saves all changed files in the directory. The changed
files are marked with a disk symbol in the file listbox. If any file names
have been changed, those files will be renamed.
File → Revert
Reverts the changes of one or multiple files. If no files
are selected in the file listbox, the changes of all files will be reverted,
else only the changes of the selected files are reverted.
File → Import...
The Import dialog can be used to import data directly
from a freedb.org server, from a MusicBrainz server, from Discogs, Amazon or
other sources of album track lists in textual format.
Import from a freedb.org server is possible using a dialog which appears when
From Server:gnudb.org or TrackType.org is selected. The artist and album name
to search for can be entered in the two topmost fields, the albums which match
the query will be displayed when Find is clicked and the results from
www.gnudb.org[8] are received. Importing the track data for an album is
done by double-clicking the album in the list. The freedb.org server to import
from can be selected as well as the CGI path. The imported data is displayed
in the preview table of the import dialog. When satisfied with the displayed
tracks, they can be imported by terminating the import dialog with OK.
A search on the Discogs server can be performed using Discogs. As in the
gnudb.org dialog, you can enter artist and album and then choose from a list
of releases. If Standard Tags is marked, the standard information is imported,
e.g. artist, album, and title. If Additional Tags is marked, more information
is imported if available, e.g. performers, arrangers, or the publisher. If
Cover Art is marked, cover art will be downloaded if available.
A search on Amazon can be performed using Amazon. As in the gnudb.org dialog,
you can enter artist and album and then choose from a list of releases. If
Additional Tags is marked, more information is imported if available, e.g.
performers, arrangers, or the publisher. If Cover Art is marked, cover art
will be downloaded if available.
You can search in the same way in the release database of MusicBrainz using From
MusicBrainz Release. The workflow is the same as described for From gnudb.org.
Import from a MusicBrainz server is possible using the dialog which appears when
From MusicBrainz Fingerprint is selected. The Server can be selected as in the
freedb import dialog. Below is a table displaying the imported track data. The
right column shows the state of the MusicBrainz query, which starts with
"Pending" when the dialog is opened. Then the fingerprint is looked
up and if it does not yield a result, another lookup using the tags in the
file is tried. Thus it can be helpful for a successful MusicBrainz query to
store known information (e.g. artist and album) in the tags before the import.
If a result was found, the search ends in the state "Recognized",
otherwise nothing was found or multiple ambiguous results and one of them has
to be selected by the user. OK and Apply use the imported data, Cancel closes
the dialog. The closing can take a while since the whole MusicBrainz machinery
has to be shut down.
For the import of textual data, From File/Clipboard opens a subdialog, where
several preconfigured import formats are available. The first two, "CSV
unquoted" and "CSV quoted" can be used to import data which was
exported by the Export dialog. The CSV data can be edited with a spreadsheet,
and shall be written using tabs as delimiters. Import should then be possible
using "CSV quoted", which is more flexible than "CSV
unquoted". However, its fields cannot contain any double quotes. If you
only export from Kid3 and import later, "CSV unquoted" can be used
as a simple format for this purpose.
The next format, "freedb HTML text", can be used to copy information
from an HTML page of freedb.org[9]. Search an album in freedb and if
the desired information is displayed in the web browser, copy the contents to
the clipboard. Then click the From Clipboard button and the imported tracks
will be displayed in the preview table at the top of the dialog. If you are
satisfied with the imported data, terminate the dialog with OK, which will
insert the data into the tags of the current directory. The destination (Tag
1, Tag 2 or Tag 1 and Tag 2) can be selected with a combo box. The files in
the current directory should be in the correct track order to get their tags
assigned. This is the case if they are numbered.
The next preconfigured import format, "freedb HTML source", can be
used, if the data is available as an HTML document. Import is possible using
the From File button, which opens a file selector, or copying its contents
from an editor and then importing from clipboard. This format can be useful
for offline import, although the HTML document could also be opened in a
browser and then be imported in the first format via the clipboard.
More preconfigured formats, e.g. "Track Title Time", are available. An
empty custom format can be created with Add to be set by the user. Two lines
below the format name can be set with a regular expression to capture the
fields from the import text. The first regular expression will be parsed once
per document to gather per-album data such as artist, album, year and genre.
The second line is tried to match from the start of the document to the end to
get track data, usually number and title. The regular expressions include all
the features offered by Qt, which is most of the what Perl offers. Bracketing
constructs "(..)" create capture buffers for the fields to import
and are preceded by Kid3 specific codes to specify which field to capture. The
codes are the same as used for the filename format, besides the codes listed
below, any frame name is possible:
File → Import from gnudb.org...
•%s %{title} Title (Song)
•%a %{artist} Artist
•%l %{album} Album
•%c %{comment} Comment
•%y %{year} Year
•%t %{track} Track
•%g %{genre} Genre
•%d %{duration} Duration
For example, a track regular expression (second line) to import from an .m3u
playlist could be "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]".
All formats can be changed by editing the regular expressions and the name and
then clicking Save Settings. They will be stored in the kid3rc file in the
configuration directory. This file can be directly edited to have more import
formats or it can be deleted to revert to the default formats. Formats can be
deleted using Remove.
Accuracy shows an estimation of how good the imported information matches the
given tracks. It uses track durations or file names to calculate the level of
similarity in percent. Cover Art shows the URL of the album cover image which
will be downloaded.
To check whether the imported tracks match the current set of files, the
duration of the imported tracks can be compared with the duration of the
files. This option can be enabled with the checkbox Check maximum allowable
time difference and the maximum tolerated difference in time can be set in
seconds. If a mismatch in a length is detected, the length is displayed with a
red background in the preview table.
It the files are ordered differently than the imported tracks, their assigned
tracks have to be changed. This task can be facilitated using the Match with
buttons Length, Track, and Title, which will reorder the tracks according to
the corresponding field. To correct the assignments manually, a track can be
dragged with the left mouse button and the Ctrl key hold down, and then
dropped at the new location.
When the import dialog is opened, it contains the actual contents of the tags.
The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using the
Destination combo box. The button on the right of this combo box can be used
to revert the table to the current contents of the tags. The checkboxes in the
first table column can be used to select the tracks which are imported. This
can be useful if a folder contains the tracks of both CDs of a double CD and
only the tracks of the second CD have to be imported.
To identify the tracks which are imported, it is possible to display the file
names or the full paths to the files using the context menu of the table
header. The values in the import table can be edited. The revert-button to the
right of the Destination combo box can be used to restore the contents of the
tags, which can also be useful after changing the Destination.
Almost all dialogs feature a Save Settings button, which can be used to store
the dialog specific settings and the window size persistently.
From Tags leads to a subdialog to set tag frames from the contents of other tag
frames. This can be used to simply copy information between tags or extract a
part from one frame and insert it in another.
As in the import from file/clipboard, there are freely configurable formats to
perform different operations. Already preconfigured are formats to copy the
Album value to Album Artist, Composer or Conductor, and to extract the Track
Number from Title fields which contain a number. There is also a format to
extract a Subtitle from a Title field.
The following example explains how to add a custom format, which sets the
information from the Subtitle field also in the Comment field. Create a new
format using Add and set a new name, e.g. "Subtitle to Comment".
Then enter "%{subtitle}" in Source and "%{comment}(.*)"
for Extraction and click Save Settings.
The expression in Source can contain format codes for arbitrary tag frames,
multiple codes can be used to combine the contents from different frames. For
each track, a text is generated from its tags using the Source format, and the
regular expression from Extraction is applied to this text to set new values
for the tags. Format codes are used before the capturing parentheses to
specify the tag frame where the captured text shall be stored. It works in the
same way as for the import from file/clipboard.Import from a freedb.org server using gnudb.org album
search. This menu item opens the same import dialog as Import..., but opens
directly the gnudb.org dialog.
File → Import from TrackType.org...
Import from the TrackType.org server. This menu item
opens the same import dialog as Import..., but opens directly the
TrackType.org dialog.
File → Import from Discogs...
Import from the Discogs server. This menu item opens the
same import dialog as Import..., but opens directly the From Discogs
dialog.
File → Import from Amazon...
Import from Amazon. This menu item opens the same import
dialog as Import..., but opens directly the From Amazon dialog.
File → Import from MusicBrainz Release...
Import from the MusicBrainz release database. This menu
item opens the same import dialog as Import..., but opens directly the From
MusicBrainz Release dialog.
File → Import from MusicBrainz Fingerprint...
Import from a MusicBrainz server. This menu item opens
the same import dialog as Import..., but opens directly the From MusicBrainz
Fingerprint dialog.
File → Automatic Import...
Automatic Import allows to import information for
multiple albums from various web services. If directories are selected in the
file list, track data for the selected directories will be imported. If no
directory is selected, all directories in the file list will be imported.
The tag type (Tag 1, Tag 2, Tag 1 and Tag 2) can be selected using the
Destination combo box.
Profiles determine which servers will be contacted to fetch album information.
Some profiles are predefined (All, MusicBrainz, Discogs, Cover Art), custom
profiles can be added using the Add button at the right of the Profile combo
box.
The table below shows the servers which will be used when importing album
information using the selected profile. The import process for an album is
finished if all required information has been found, so the order of the rows
in the table is important. It can be changed using the Move Up and Move Down
buttons. Edit can be used to change an existing entry. The Server selection
offers the same servers as can be used in the import functions. Standard Tags,
Additional Tags, Cover Art determine the information which shall be fetched
from the server. Finally, Accuracy is the minimum accuracy which must be
achieved to accept the imported data. If the accuracy is insufficient, the
next server in the list will be tried. The same dialog containing the server
properties appears when Add is clicked to add a new server entry. Existing
entries can be deleted using Remove.
To launch an automatic batch import with the selected profile, click Start.
Details about the running import are displayed at the top of the dialog. The
process can be aborted with the Abort button.
File → Browse Cover Art...
The Browse Cover Art dialog helps to find album cover
art. Artist/Album is filled from the tags if possible. Source offers a variety
of websites with album cover art. The URL with artist and album as parameters
can be found beneath the name. URL-encoded values for artist and album can be
inserted using %u{artist} and %u{album}, other values from the
tags are possible too, as described in Configure Kid3, User Actions. More
sources can be entered after the entry "Custom Source" by replacing
"Custom Source" with the source's name, pressing Enter, then
inserting the URL and finally pressing Save Settings. The resulting browser
command is displayed at the top of the dialog and can be started by clicking
Browse. The browser, which can be configured in the settings, is started with
the selected source. A cover image can then be dragged from the browser into
the Kid3 window and will be set in the picture frame of the selected files.
Because not all browsers support drag'n'drop of images and the pictures on
websites often have a URL, in such cases Kid3 will receive the URL and not the
picture. If the URL points to a picture, it will be downloaded. However, if
the URL refers to some other web resource, it has to be translated to the
corresponding picture. Such mappings are defined in the table URL extraction.
The left column Match contains a regular expression which is compared with the
URL. If it matches, the captured expressions in parentheses are inserted into
the pattern of the right Picture URL column (at the positions marked with \1
etc.). The replaced regular expression contains the URL of the picture. By
this means cover art can be imported from Amazon, Google Images, etc. using
drag'n'drop. It is also possible to define your own mappings.
File → Export...
The Export Dialog is used to store data from the tags in
a file or the clipboard. The editor at the top shows a preview of the data to
export. If the export data contain tabulator characters, the export is
displayed in a table. The data will be generated from the tags in the current
directory according to the configured format.
The format settings are similar as in the Import dialog: The topmost field
contains the title (e.g. "CSV unquoted"), followed by the header,
which will be generated at the begin of the file. The track data follows; it
is used for every track. Finally, the trailer can be used to generate some
finishing text.
The format fields do not contain regular expressions as in the Import dialog,
but only output format expressions with special %-expressions, which will be
replaced by values from the tags. The whole thing works like the file name
format, and the same codes are used plus some additional codes. Not only the
codes listed below but all tag frame names can be used.
File → Create Playlist
•%s %{title} Title (Song)
•%a %{artist} Artist
•%l %{album} Album
•%c %{comment} Comment
•%y %{year} Year
•%t %{track} Track (e.g. 01)
•%t %{track.n} Track with field width n (e.g. 001
for %{track.3})
•%T %{tracknumber} Track (without leading zeros,
e.g. 1)
•%g %{genre} Genre
•%f %{file} File name
•%p %{filepath} Path
•%u %{url} URL
•%d %{duration} Duration in minutes:seconds
•%D %{seconds} Duration in seconds
•%n %{tracks} Number of tracks of the album
•%e %{extension} File extension
•%O %{tag1} The format of tag 1 (ID3v1.1 or empty
if not existing)
•%o %{tag2} The format of tag 2 (ID3v2.3.0,
ID3v2.4.0, ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
existing)
•%b %{bitrate} Bit rate in kbit/s
•%v %{vbr} VBR or empty (only for ID3v2.3 with
id3lib)
•%r %{samplerate} Sample rate in Hz
•%m %{mode} Channel mode (Stereo or Joint
Stereo)
•%h %{channels} Number of channels (1 or 2)
•%k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg
Vorbis, FLAC, MPC, APE, ASF, AIFF, WAV)
A few formats are predefined. "CSV unquoted" separates the fields by
tabs. Data in this format can be imported again into Kid3 using the import
format with the same name. "CSV quoted" additionally encloses the
fields by double quotes, which eases the import into spreadsheet applications.
However, the fields shall not contain any double quotes when this format is
used. "Extended M3U" and "Extended PLS" generate playlists
with extended attributes and absolute path names. "HTML" can be used
to generate an HTML page with hyperlinks to the tracks. "Kover XML"
creates a file which can be imported by the cover printing program Kover.
"Technical Details" provides information about bit rate, sample
rate, channels, etc. Finally, "Custom Format" is left empty for
definition of a custom format. You can define more formats of your own by
adding lines in the file kid3rc in the configuration directory. The other
formats can be adapted to your needs.
The source of the tags to generate the export data (Tag 1 or Tag 2) can be
selected with a combo box. Pushing To File or To Clipboard stores the data in
a file or on the clipboard. OK and Cancel close the dialog, whereas OK accepts
the current dialog settings.Creates a playlist. The format and contents of the
playlist can be set by various options.
The name of the playlist can be the Same as directory name or use a Format with
values from the tags, e.g. "%{artist} - %{album}" to have the artist
and album name in the playlist file name. The format codes are the same as for
Export. The extension depends on the playlist format.
The location of the generated playlist is determined by the selection of the
Create in combo box.
Current directory
File → Quit (Ctrl+Q)
The playlist is created in the current directory and
contains only files of the current directory.
Every directory
A playlist is created in every directory which contains
listed files, and each playlist contains the files of that directory.
Top-level directory
Only one playlist is created in the top-level directory
(i.e. the directory of the file list) and it contains the listed files of the
top-level directory and all of its sub-directories.
The Format of the playlist can be M3U, PLS or XSPF.
If Include only the selected files is checked, only the selected files will be
included in the playlist. If a directory is selected, all of its files are
selected. If this check box is not activated, all audio files are included in
the playlist.
Sort by file name selects the usual case where the files are ordered by file
name. With Sort by tag field, it is possible to sort by a format string with
values from tag fields. For instance, "%{track.3}" can be used to
sort by track number (the ".3" is used to get three digits with
leading zeros because strings are used for sorting). It is also possible to
use multiple fields, e.g. "%{genre}%{year}" to sort using a string
composed of genre and year.
The playlist entries will have relative or absolute file paths depending on
whether Use relative path for files in playlist or Use full path for files in
playlist is set.
When Write only list of files is set, the playlist will only contain the paths
to the files. To generate an extended playlist with additional information, a
format string can be set using the Write info using control.Quits the application.
The Edit Menu¶
Edit → Select All (Alt+A)Selects all files.
Edit → Deselect (Ctrl+Shift+A)
Deselects all files.
Edit → Select All in Directory
Selects all files of the current directory.
Edit → Previous File (Alt+Up)
Selects the previous file.
Edit → Next File (Alt+Down)
Selects the next file.
Edit → Find... (Ctrl+F)
Find strings in the file names and the tags. The Find
dialog is a subset of the Replace dialog, which is described below.
Edit → Replace... (Ctrl+R)
This function opens a dialog to find and replace strings
in the file names and the tags. The set of frames where the search is
performed can be restricted by deactivating the Select all checkbox and
selecting the frames which shall be searched. There are also search options
available to search backwards, case sensitively, and to use regular
expressions.
Depending on the number of files, the search might take some time, therefore it
can be aborted by closing the dialog.
The Tools Menu¶
Tools → Apply Filename FormatWhen Format while editing is switched off for the
filename format in the configuration dialog, this menu item can be used to
apply the configured format to the names of the selected files. This can also
be used to check whether the file names conform with the configured format by
applying the format to all saved files and then checking if any files were
changed (and therefore marked with a disk symbol in the file listbox).
Tools → Apply Tag Format
When Format while editing is switched off for the tag
format in the configuration dialog, this menu item can be used to apply the
configured format to the tags of the selected files. This can also be used to
check whether the tags conform with the configured format by applying the
format to all saved files and then checking if any files were changed (and
therefore marked with a disk symbol in the file listbox).
Tools → Apply Text Encoding
Sets the Text encoding selected in Settings/Configure
Kid3.../Tags/Tag 2 for all selected files. If UTF8 is selected, UTF16 will be
used for ID3v2.3.0 tags because UTF8 is not supported for this format.
Tools → Rename Directory...
This dialog offers the possibility to automatically
rename the currently open directory according to the tags in the files.
Several formats are preconfigured to include information about artist, album
and year in the directory name. It is also possible to set a custom format,
the following special codes are used to insert tag values into the directory
name:
Tools → Number Tracks...
•%s %{title} Title (Song)
•%a %{artist} Artist
•%l %{album} Album
•%c %{comment} Comment
•%y %{year} Year
•%t %{track} Track (e.g. 01)
•%t %{track.n} Track with field width n (e.g. 001
for %{track.3})
•%T %{tracknumber} Track (without leading zeros,
e.g. 1)
•%g %{genre} Genre
If a directory separator "/" is found in the format, multiple
directories are created. If you want to create a new directory instead of
renaming the current directory, select Create Directory instead of Rename
Directory. The source of the tag information can be chosen between From Tag 1
and Tag 2, From Tag 1 and From Tag 2. A preview for the rename operation
performed on the first file can be seen in the From and To sections of the
dialog.
Multiple directories can be renamed by selecting them.If the track numbers in the tags are not set or have the
wrong values, this function can number the tracks automatically in ascending
order. The start number can be set in the dialog. If only part of the tracks
have to be numbered, they must be selected.
When Total number of tracks is checked, the number of tracks will also be set in
the tags.
It is possible to number the tracks over multiple directories. The folders have
to be expanded and selected.
Tools → Filter...
The filter can be used to display only those files which
match certain criteria. This is helpful if you want to organize a large
collection and only edit those files which are not in the desired scheme. The
expression defining which files to display uses the same format codes which
are used in the file name format, import and export.
Tools → Convert ID3v2.3 to ID3v2.4
•%s %{title} Title (Song)
•%a %{artist} Artist
•%l %{album} Album
•%c %{comment} Comment
•%y %{year} Year
•%t %{track} Track (e.g. 01)
•%t %{track.n} Track with field width n (e.g. 001
for %{track.3})
•%T %{tracknumber} Track (without leading zeros,
e.g. 1)
•%g %{genre} Genre
•%f %{file} File name
•%p %{filepath} Absolute path to file
•%e %{extension} File extension
•%O %{tag1} The format of tag 1 (ID3v1.1 or empty
if not existing)
•%o %{tag2} The format of tag 2 (ID3v2.3.0,
ID3v2.4.0, ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF, or empty if not
existing)
•%b %{bitrate} Bit rate in kbit/s
•%v %{vbr} VBR or empty (only for ID3v2.3 with
id3lib)
•%r %{samplerate} Sample rate in Hz
•%m %{mode} Channel mode (Stereo or Joint
Stereo)
•%h %{channels} Number of channels (1 or 2)
•%k %{codec} Codec (e.g. MPEG 1 Layer 3, MP4, Ogg
Vorbis, FLAC, MPC, APE, ASF, AIFF, WAV)
•%1a %1{artist}, ... Use the prefix 1 to get
values of tag 1
•%2a %2{artist}, ... Use the prefix 2 to get
values of tag 2
These codes are replaced with the values for the file, and the resulting strings
can be compared with the following operations:
•s1 equals s2: true if s1 and s2 are equal.
•s1 contains s2: true if s1 contains s2, i.e. s2
is a substring of s1.
•s matches re: true if s matches the regular
expression re.
True expressions are replaced by 1, false by 0. True values are represented by
1, true, on and yes, false values by 0, false, off and no. Boolean operations
are not, and, or (in this order of precedence) and can be grouped by
parentheses.
Some filter rules are predefined and can serve as examples for your own
expressions:
All
When the file list is filtered - this is shown by
"[filtered]" in the window title - and all files shall be displayed
again, the filtering can be reverted using this filter. It uses an empty
expression, but a true value would have the same effect.
Filename Tag Mismatch
not (%{filepath} contains "%{artist} -
%{album}/%{track} %{title}")
Tests if the file path conforms with the file name format. This rule is
automatically adapted if the file name format changes.
No Tag 1
%{tag1} equals ""
Displays only files which do not have a tag 1.
No Tag 2
%{tag2} equals ""
Displays only files which do not have a tag 2.
ID3v2.3.0 Tag
%{tag2} equals "ID3v2.3.0"
Displays only files which have an ID3v2.3.0 tag.
ID3v2.4.0 Tag
%{tag2} equals "ID3v2.4.0"
Displays only files which have an ID3v2.4.0 tag.
Tag 1 != Tag 2
not (%1{title} equals %2{title} and %1{album} equals
%2{album} and %1{artist} equals %2{artist} and %1{comment} equals %2{comment}
and %1{year} equals %2{year} and %1{track} equals %2{track} and %1{genre}
equals %2{genre})
Displays files with differences between tag 1 and tag2.
Tag 1 == Tag 2
%1{title} equals %2{title} and %1{album} equals
%2{album} and %1{artist} equals %2{artist} and %1{comment} equals %2{comment}
and %1{year} equals %2{year} and %1{track} equals %2{track} and %1{genre}
equals %2{genre}
Displays files with identical tag 1 and tag 2.
Incomplete
%{title} equals "" or %{artist} equals
"" or %{album} equals "" or %{year} equals "" or
%{tracknumber} equals "" or %{genre} equals ""
Displays files with empty values in the standard tags (title, artist, album,
date, track number, genre).
No Picture
%{picture} equals ""
Displays only files which do not have a picture.
Custom Filter
To add your own filter, select this entry. For instance,
if you want to have a filter for artists starting with "The",
replace "Custom Filter" with the name "The Bands" and
press Enter. Then insert the following expression into the line edit:
%{artist} matches "The.*"
Then click Save Settings. Click Apply to filter the files. All files processed
are displayed in the text view, with a "+" for those who match the
filter and a "-" for the others. When finished, only the files with
an artist starting with "The" are displayed, and the window title is
marked with "[filtered]".
If there are any ID3v2.3 tags in the selected files, they
will be converted to ID3v2.4 tags. Frames which are not supported by TagLib
will be discarded. Only files without unsaved changes will be converted.
Tools → Convert ID3v2.4 to ID3v2.3
If there are any ID3v2.4 tags in the selected files, they
will be converted to ID3v2.3 tags. Only files without unsaved changes will be
converted.
Tools → Play
This opens a simple toolbar to play audio files. It
contains buttons for the basic operations (Play/Pause, Stop playback, Previous
Track, Next Track, Close), sliders for position and volume and a display of
the current position. If multiple files are selected, the selected tracks are
played, else all files will be played.
The Settings Menu¶
Settings → Show ToolbarToggles displaying of the toolbar.
Settings → Show Statusbar
Toggles displaying of the statusbar, which displays
longer actions such as opening or saving a directory.
Settings → Show Picture
Toggles displaying of the album cover art preview
picture.
Settings → Auto Hide Tags
Empty tags are automatically hidden if this option is
active. The File, Tag 1 and Tag 2 sections can be manually collapsed and
expanded by clicking on the corresponding -/+ buttons.
Settings → Configure Kid3...
Opens the configuration dialog, which consists of pages
for tags, files, user actions, and network settings.
Tag specific options can be found on the Tags page, which is itself separated
into three tabs for Tag 1, Tag 2, and Tag 1 and Tag 2.
If Mark truncated fields is checked, truncated ID3v1.1 fields will be marked
red. The text fields of ID3v1.1 tags can only have 30 characters, the comment
only 28 characters. Also the genre and track numbers are restricted, so that
fields can be truncated when imported or transferred from ID3v2. Truncated
fields and the file will be marked red, and the mark will be removed after the
field has been edited.
With Text encoding for ID3v1 it is possible to set the character set used in
ID3v1 tags. This encoding is supposed to be ISO-8859-1, so it is recommended
to keep this default value. However, there are tags around with different
encoding, so it can be set here and the ID3v1 tags can then be copied to ID3v2
which supports Unicode.
The check box Use track/total number of tracks format controls whether the track
number field of ID3v2 tags contains simply the track number or additionally
the total number of tracks in the directory.
When Genre as text instead of numeric string is checked, all ID3v2 genres will
be stored as a text string even if there is a corresponding code for ID3v1
genres. If this option is not set, genres for which an ID3v1 code exists are
stored as the number of the genre code (in parentheses for ID3v2.3). Thus the
genre Metal is stored as "Metal" or "(9)" depending on
this option. Genres which are not in the list of ID3v1 genres are always
stored as a text string. The purpose of this option is improved compatibility
with devices which do not correctly interpret genre codes.
Text encoding defines the default encoding used for ID3v2 frames and can be set
to ISO-8859-1, UTF16, or UTF8. UTF8 is not valid for ID3v2.3.0 frames; if it
is set, UTF16 will be used instead. For ID3v2.4.0 frames, all three encodings
are possible.
Version used for new tags determines whether new ID3v2 tags are created as
version 2.3.0 or 2.4.0. In the first case, id3lib is used as it was in earlier
versions of Kid3 and TagLib is only applied when an ID3v2.4.0 tag is
encountered. In the second case, ID3v2.4.0 (TagLib), TagLib is generally used
for MP3 files; changed or newly created tags will then be saved in version
2.4.0. When ID3v2.3.0 (TagLib) is selected, TagLib is also used for ID3v2.3.0
tags.
Track number digits is the number of digits in Track Number fields. Leading
zeros are used to pad. For instance, with a value of 2 the track number 5 is
set as "05".
The combo box Comment field name is only relevant for Ogg/Vorbis and FLAC files
and sets the name of the field used for comments. Different applications seem
to use different names, "COMMENT" for instance is used by xmms,
whereas amaroK uses "DESCRIPTION".
The format of pictures in Ogg/Vorbis files is determined by Picture field name,
which can be METADATA_BLOCK_PICTURE or COVERART. The first is the official
standard and uses the same format as pictures in FLAC tags. COVERART is an
earlier unofficial way to include pictures in Vorbis comments. It can be used
for compatibility with legacy players.
Custom Genres can be used to define genres which are not available in the
standard genre list, e.g. "Gothic Metal". Such custom genres will
appear in the Genre combo box of Tag 2. For ID3v1.1 tags, only the predefined
genres can be used.
The list of custom genres can also be used to reduce the number of genres
available in the Genre combo box to those typically used. If your collection
mostly contains music in the genres Metal, Gothic Metal, Ancient and Hard
Rock, you can enter those genres and mark Show only custom genres. The Tag
2Genre combo box will then only contain those four genres and you will not
have to search through the complete genres list for them. In this example,
only Metal and Hard Rock will be listed in the tag 1 genres list, because
those two custom genres entries are standard genres. If Show only custom
genres is not active, the custom genres can be found at the end of the genres
list.
Quick Access Tags defines which frame types are always shown in the Tag 2
section. Such frames can then be added without first using the Add button.
Tag Format contains options for the format of the tags. When Format while
editing is checked, the format configuration is automatically used while
editing text in the line edits. The Case conversion can be set to No changes,
All lowercase, All uppercase, First letter uppercase or All first letters
uppercase. To use locale-aware conversion between lowercase and uppercase
characters, a locale can be selected in the combobox below. The string
replacement list can be set to arbitrary string mappings. To add a new
mapping, select the From cell of a row and insert the text to replace, then go
to the To column and enter the replacement text. To remove a mapping set the
From cell to an empty value (e.g. by first typing space and then backspace).
Inserting and deleting rows is also possible using a context menu which
appears when the right mouse button is clicked. Replacement is only active, if
the String replacement checkbox is checked.
On the page Files the check box Load last-opened files can be marked so that
Kid3 will open and select the last selected file when it is started the next
time. Preserve file timestamp can be checked to preserve the file modification
time stamp. Filename for cover sets the name which is suggested when an
embedded image is exported to a file.
If Mark changes is active, changed fields are marked with a light gray label
background.
Filename Format contains options for the format of the filenames. The same
options as in Tag Format are available.
The User Actions page contains a table with the commands which are available in
the context menu of the file list. For critical operations such as deleting
files, it is advisable to mark Confirm to pop up a confirmation dialog before
executing the command. Output can be marked to see the output written by
console commands (standard output and standard error). Name is the name
displayed in the context menu. Command is the command line to be executed.
Arguments can be passed using the following codes:
will query the lyrics for the current song in LyricWiki[10]. The
"u" in %u{artist} and %u{title} is used to URL-encode the artist
%{artist} and song %{title} information. It is easy to define your own queries
in the same way, e.g. an image search with Google[11]:
To add album cover art to tag 2, you can search for images with Google or Amazon
using the commands described above. The picture can be added to the tag with
drag and drop. You can also add an image with Add, then select the Picture
frame and import an image file or paste from the clipboard. Picture frames are
supported for ID3v2, MP4, FLAC, Ogg and ASF tags.
To add and delete entries in the table, a context menu can be used.
The Network page contains only a field to insert the proxy address and
optionally the port, separated by a colon. The proxy will be used when
importing from an Internet server when the checkbox is checked.
In the Plugins page, available plugins can be enabled or disabled. The plugins
are separated into two sections. The Metadata Plugins & Priority list
contains plugins which support audio file formats. The order of the plugins is
important because they are tried from top to bottom. Some formats are
supported by multiple plugins, so files will be opened with the first plugin
supporting them. The TaglibMetadata supports most formats, if it is at the top
of the list, it will open most of the files. If you want to use a different
plugin for a file format, make sure that it is listed before the
TaglibMetadata plugin. Details about the metadata plugin and why you may want
to use them instead of TagLib are listed below.
Settings → Configure Shortcuts...
•%F %{files} File paths (a list if multiple files
selected)
•%f %{file} File path to single file
•%uF %{urls} URLs (a list if multiple files
selected)
•%uf %{url} URL to single file
•%d %{directory} Directory
•%s %{title} Title (Song)
•%a %{artist} Artist
•%l %{album} Album
•%c %{comment} Comment
•%y %{year} Year
•%t %{track} Track (e.g. 01)
•%t %{track.n} Track with field width n (e.g. 001
for %{track.3})
•%T %{tracknumber} Track (without leading zeros,
e.g. 1)
•%g %{genre} Genre
•%b %{browser} Command to start the web
browser
The command which will be inserted with %{browser} can be defined in the Web
browser line edit above. Commands starting with %{browser} can be used to
fetch information about the audio files from the web, for instance
%{browser} http://lyricwiki.org/%u{artist}:%u{title}
•Id3libMetadata: Uses id3lib[12] for
ID3v1.1 and ID3v2.3 tags in MP3, MP2, AAC files. Supports a few more frame
types than TagLib. Another reason to use it is that TagLib only supports
ID3v2.3 since version 1.8.
•OggFlacMetadata: Uses libogg[13],
libvorbis, libvorbisfile[14] for Ogg files, and additionally
libFLAC++ and libFLAC[15] for FLAC files. Reasons to use them are
pictures in Ogg files, which are not supported by TagLib and that these are
the official libraries for these formats.
•TaglibMetadata: Uses TagLib[16] which
supports a lot of audio file formats. Since version 1.8, it also supports
ID3v2.3, so it can be used for all audio files supported by Kid3.
•Mp4v2Metadata: mp4v2[17] was originally
used by Kid3 to support M4A files. However, newer versions of TagLib provide
good M4A support, so this plugin is not built by default.
The Available Plugins section lists the remaining plugins. Their order is not
important, but they can be enabled or disabled using the check boxes.
•AmazonImport: Used for the Import from Amazon...
function.
•DiscogsImport: Used for the Import from
Discogs... function.
•FreedbImport: Used for the Import from
gnudb.org... and Import from TrackType.org... functions.
•MusicBrainzImport: Used for the Import from
MusicBrainz Release... function.
•AcoustidImport: Used for the Import from
MusicBrainz Fingerprint... function, which depends on the
Chromaprint[18] and libav[19] libraries.
Plugins which are disabled will not be loaded. This can be used to optimize
resource usage and startup time. The settings on this page take only effect
after a restart of Kid3.Opens a dialog to assign keyboard shortcuts for most of
the program functions. There are even functions without corresponding menu or
button available, e.g. next file, previous file, select all.
The Help Menu¶
Help → Kid3 HandbookOpens this handbook.
Help → About Kid3
Displays a short information about Kid3;.
KID3-CLI¶
Commands¶
kid3-cli offers a command-line-interface for Kid3. If a directory path is used, the directory is opened. If one or more file paths are given, the common directory is opened and the files are selected. Subsequent commands will then work on these files. Commands are specified using -c options. If multiple commands are passed, they are executed in the given order. If files are modified by the commands, they will be saved at the end. If no command options are passed, kid3-cli starts in interactive mode. Commands can be entered and will operate on the current selection. The following sections list all available commands.help [COMMAND-NAME]
Displays help about the parameters of COMMAND-NAME or about all commands
if no command name is given.timeout [default | off | TIME]
Overwrite the default command timeout. The CLI commands abort after a command
specific timeout is expired. This timeout is 10 seconds for ls and
albumart, 60 seconds for autoimport and filter, and 3
seconds for all other commands. If a huge number of files has to be processed,
this timeouts may be too restrictive, thus the timeout for all commands can be
set to TIME ms, switched off altogether or be left at the default
values.exit [force]
Exit application. If there are modified unsaved files, the force
parameter is required.cd [DIRECTORY]
If no DIRECTORY is given, change to the home directory. If a directory is
given, change into the directory. If one or more file paths are given, change
to their common directory and select the files.pwd
Print the filename of the current working directory.ls
List the contents of the current directory. This corresponds to the file list in
the Kid3 GUI. Four characters before the file names show the state of the
file.
•> File is selected.
•* File is modified.
•1 File has a tag 1, otherwise '-' is
displayed.
•2 File has a tag 2, otherwise '-' is
displayed.
kid3-cli> ls 1- 01 Intro.mp3 > 12 02 We Only Got This One.mp3 *1- 03 Outro.mp3
save
select [all | none | first | previous | next |
FILE...]
To select all files, enter select all, to deselect all files, enter
select none. To traverse the files in the current directory start with
select first, then go forward using select next or backward
using select previous. Specific files can be added to the current
selection by giving their file names. Wildcards are possible, so select
*.mp3 will select all MP3 files in the current directory.
kid3-cli> select first kid3-cli> ls > 1- 01 Intro.mp3 12 02 We Only Got This One.mp3 *1- 03 Outro.mp3 kid3-cli> select next kid3-cli> ls 1- 01 Intro.mp3 > 12 02 We Only Got This One.mp3 *1- 03 Outro.mp3 kid3-cli> select *.mp3 kid3-cli> ls > 1- 01 Intro.mp3 > 12 02 We Only Got This One.mp3 >*1- 03 Outro.mp3
tag [TAG-NUMBERS]
Many commands have an optional TAG-NUMBERS parameter, which specifies
whether the command operates on tag 1 or tag 2. If this parameter is omitted,
the default tag numbers are used, which can be set by this command. At
startup, is is set to 12 which means that information is read from tag 2 if
available, else from tag 1; modifications are done on tag 2. The
TAG-NUMBERS can be set to 1 or 2 to operate only
on the corresponding tag. If the parameter is omitted, the current setting is
displayed.get [all | FRAME-NAME] [TAG-NUMBERS]
This command can be used to read the value of a specific tag frame or get
information about all tag frames (if the argument is omitted or all is
used). Modified frames are marked with a '*'.
kid3-cli> get File: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo Name: 01 Intro.mp3 Tag 1: ID3v1.1 Title Intro Artist One Hit Wonder Album Let's Tag Date 2013 Track Number 1 Genre Pop kid3-cli> get title Intro
get picture:"/path/to/folder.jpg"
get SYLT:"/path/to/lyrics.lrc"
set {FRAME-NAME} {FRAME-VALUE}
[TAG-NUMBERS]
This command sets the value of a specific tag frame.
kid3-cli> set remixer "O.H. Wonder"
set picture:"/path/to/folder.jpg" "Picture Description"
set SYLT:"/path/to/lyrics.lrc" "Lyrics Description"
revert
Revert all modifications in the selected files (or all files if no files are
selected).import {FILE} {FORMAT-NAME}
[TAG-NUMBERS]
Tags are imported from the file FILE (or from the clipboard if
clipboard is used for FILE) in the format with the name
FORMAT-NAME (e.g. "CSV unquoted", see Import).autoimport [PROFILE-NAME]
[TAG-NUMBERS]
Batch import using profile PROFILE-NAME (see Automatic Import,
"All" is used if omitted).albumart {URL} [all]
Set the album artwork by downloading a picture from URL. The rules
defined in the Browse Cover Art dialog are used to transform general URLs
(e.g. from Amazon) to a picture URL. To set the album cover from a local
picture file, use the set command.
kid3-cli> albumart http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
export {FILE} {FORMAT-NAME}
[TAG-NUMBERS]
Tags are exported to file FILE (or to the clipboard if clipboard
is used for FILE) in the format with the name FORMAT-NAME (e.g.
"CSV unquoted", see Export).playlist
Create playlist in the format set in the configuration, see Create
Playlist.filenameformat
Apply file name format set in the configuration, see Apply Filename
Format.tagformat
Apply tag name format set in the configuration, see Apply Tag Format.textencoding
Apply text encoding set in the configuration, see Apply Text Encoding.renamedir [FORMAT] [create | rename | dryrun]
[TAG-NUMBERS]
Rename or create directories from the values in the tags according to a given
FORMAT (e.g. %{artist} - %{album}, see Rename Directory), if no
format is given, the format defined in the Rename directory dialog is used.
The default mode is rename; to create directories, create must
be given explicitly. The rename actions will be performed immediately, to just
see what would be done, use the dryrun option.numbertracks [TRACK-NUMBER]
[TAG-NUMBERS]
Number the selected tracks starting with TRACK-NUMBER (1 if
omitted).filter [FILTER-NAME | FILTER-FORMAT]
Filter the files so that only the files matching the FILTER-FORMAT are
visible. The name of a predefined filter expression (e.g. "Filename
Tag Mismatch") can be used instead of a filter expression, see
Filter.
kid3-cli> filter '%{title} contains "tro"' Started /home/urs/One Hit Wonder - Let's Tag + 01 Intro.mp3 - 02 We Only Got This One.mp3 + 03 Outro.mp3 Finished kid3-cli> ls 1- 01 Intro.mp3 1- 03 Outro.mp3 kid3-cli> filter All Started /home/urs/One Hit Wonder - Let's Tag + 01 Intro.mp3 + 02 We Only Got This One.mp3 + 03 Outro.mp3 Finished kid3-cli> ls 1- 01 Intro.mp3 12 02 We Only Got This One.mp3 1- 03 Outro.mp3
to24
to23
fromtag [FORMAT] [TAG-NUMBERS]
Set the file names of the selected files from values in the tags, for example
fromtag "%{track} - %{title}" 1. If no format is specified,
the format set in the GUI is used.totag [FORMAT] [TAG-NUMBERS]
Set the tag frames from the file names, for example totag
"%{albumartist} - %{album}/%{track} %{title}" 2. If no format is
specified, the format set in the GUI is used. If the format of the filename
does not match this pattern, a few other commonly used formats are
tried.syncto {TAG-NUMBER}
Copy the tag frames from one tag to the other tag, e.g. to set the ID3v2 tag
from the ID3v1 tag, use syncto 2.copy [TAG-NUMBER]
Copy the tag frames of the selected file to the internal copy buffer. They can
then be set on another file using the paste command.paste [TAG-NUMBER]
Set tag frames from the contents of the copy buffer in the selected
files.remove [TAG-NUMBER]
Remove a tag.play [pause | stop | previous | next]
Start audio playback. Once it has been started, it can be controlled with the
pause (to pause and resume), stop, previous and
next options.Examples¶
Set album cover in all files of a directory using the batch import function:kid3-cli -c 'autoimport "Cover Art"' /path/to/dir
kid3-cli -c 'set comment "" 1' -c 'set comment "" 2' \ -c 'tagformat 1' -c 'tagformat 2' /path/to/dir/*.mp3
kid3-cli -c autoimport -c 'syncto 1' -c fromtag -c playlist \ /path/to/dir/*.mp3
kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \ -c "set arranger ''" /path/to/dir
#!/usr/bin/env python # Generate iTunes Sound Check from ReplayGain. from __future__ import print_function import os, sys, subprocess def rg2sc(dirpath): for root, dirs, files in os.walk(dirpath): for name in files: if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')): fn = os.path.join(root, name) rg = subprocess.check_output([ 'kid3-cli', '-c', 'get "replaygain_track_gain"', fn]).strip() if rg.endswith(b' dB'): rg = rg[:-3] try: rg = float(rg) except ValueError: print('Value %s of %s in not a float' % (rg, fn)) continue sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10 subprocess.call([ 'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn]) if __name__ == '__main__': rg2sc(sys.argv[1])
CREDITS AND LICENSE¶
Kid3 Program written by Urs Fleisch <ufleisch at users.sourceforge.net> FDL[20] GPL[21]INSTALLATION¶
How to obtain Kid3¶
Kid3 can be found at http://kid3.sourceforge.net.Requirements¶
Kid3 needs Qt[22]. KDE[23] is recommended but not necessary, as Kid3 can also be compiled as a Qt application. Kid3 can be compiled for systems where these libraries are available, e.g. for GNU/Linux, Windows and Mac OS X. To tag Ogg/Vorbis files, libogg[13], libvorbis and libvorbisfile[14] are required, for FLAC files libFLAC++ and libFLAC[15]. id3lib[12] is used for MP3 files. These four formats are also supported by TagLib[16], which can also handle MPC, APE, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF files and tracker modules. To import from acoustic fingerprints, Chromaprint[18] and libav[19] are used. Kid3 is available for most Linux distributions, Windows and Mac OS X. Links can be found on http://kid3.sourceforge.net.Compilation and Installation¶
You can compile Kid3 with or without KDE. Without KDE, Kid3 is a simple Qt application and lacks some configuration and session features. For a KDE 4 version, go into the top directory and type% cmake . % make % make install
Configuration¶
With KDE, the file name filter and format, the import formats, the filename and ID3 formats, the toolbar and statusbar settings as well as the window size will be be saved in the standard location in file kid3rc. As a Qt application, this file is in .config/Kid3/Kid3.conf. On Windows, the configuration is stored in the registry.D-BUS INTERFACE¶
D-Bus Examples¶
The Qt 4 and KDE 4 versions on Linux offer a D-Bus-Interface to control Kid3 by scripts. Scripts can be written in any language with D-Bus-bindings (e.g. in Python) and can be added to the User Actions to extend the functionality of Kid3. The artist in tag 2 of the current file can be set to the value "One Hit Wonder" with the following code: Shelldbus-send --dest=net.sourceforge.kid3 --print-reply=literal \ /Kid3 net.sourceforge.Kid3.setFrame int32:2 string:'Artist' \ string:'One Hit Wonder'
qdbus net.sourceforge.kid3 /Kid3 setFrame 2 Artist \ 'One Hit Wonder'
import dbus kid3 = dbus.SessionBus().get_object( 'net.sourceforge.kid3', '/Kid3') kid3.setFrame(2, 'Artist', 'One Hit Wonder')
use Net::DBus; $kid3 = Net::DBus->session->get_service( "net.sourceforge.kid3")->get_object( "/Kid3", "net.sourceforge.Kid3"); $kid3->setFrame(2, "Artist", "One Hit Wonder");
D-Bus API¶
The D-Bus API is specified in net.sourceforge.Kid3.xml. The Kid3 interface has the following methods:boolean
openDirectory(string path);
path
path to file or directory
Returns true if OK.boolean save(void);
Returns true if OK.string getErrorMessage(void);
Returns detailed error message.revert(void);
boolean batchImport(int32 tagMask,
string profileName);
tagMask
tag mask (bit 0 for tag 1, bit 1 for tag 2)
profileName
name of batch import profile to use
boolean importFromFile(int32 tagMask,
string path,
int32 fmtIdx);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
path
path of file
fmtIdx
index of format
Returns true if OK.downloadAlbumArt(string url,
boolean allFilesInDir);
url
URL of picture file or album art resource
allFilesInDir
true to add the image to all files in the directory
boolean exportToFile(int32 tagMask,
string path,
int32 fmtIdx);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
path
path of file
fmtIdx
index of format
Returns true if OK.boolean createPlaylist(void);
Returns true if OK.quit(void);
selectAll(void);
deselectAll(void);
boolean firstFile(void);
Returns true if there is a first file.boolean previousFile(void);
Returns true if there is a previous file.boolean nextFile(void);
Returns true if there is a next file.boolean selectFirstFile(void);
Returns true if there is a first file.boolean selectPreviousFile(void);
Returns true if there is a previous file.boolean selectNextFile(void);
Returns true if there is a next file.boolean selectCurrentFile(void);
Returns true if there is a current file.boolean expandDirectory(void);
A file list item is a directory if getFileName() returns a name with '/' as the
last character.
Returns true if current file item is a directory.applyFilenameFormat(void);
applyTagFormat(void);
applyTextEncoding(void);
boolean setDirNameFromTag(int32 tagMask,
string format,
boolean create);
tagMask
tag mask (bit 0 for tag 1, bit 1 for tag 2)
format
directory name format
create
true to create, false to rename
Returns true if OK, else the error message is available using
getErrorMessage().numberTracks(int32 tagMask,
int32 firstTrackNr);
tagMask
tag mask (bit 0 for tag 1, bit 1 for tag 2)
firstTrackNr
number to use for first file
filter(string expression);
expression
filter expression
convertToId3v24(void);
convertToId3v23(void);
Returns true if OK.string getDirectoryName(void);
Returns absolute path of directory.string getFileName(void);
Returns true absolute file name, ends with "/" if it is a
directory.setFileName(string name);
name
file name
The file will be renamed when the directory is saved.setFileNameFormat(string format);
format
file name format
setFileNameFromTag(int32 tagMask);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
string getFrame(int32 tagMask,
string name);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
name
name of frame (e.g. "artist")
To get binary data like a picture, the name of a file to write can be added
after the name, e.g. "Picture:/path/to/file". In the same
way, synchronized lyrics can be exported, e.g. "SYLT:/path/to/file".
Returns value of frame.boolean setFrame(int32 tagMask,
string name,
string value);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
name
name of frame (e.g. "artist")
value
value of frame
For tag 2 ( tagMask 2), if no frame with name exists, a new frame
is added, if value is empty, the frame is deleted. To add binary data
like a picture, a file can be added after the name, e.g.
"Picture:/path/to/file". "SYLT:/path/to/file" can be used
to import synchronized lyrics.
Returns true if OK.array of string
getTag(int32 tagMask);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
Returns list with alternating frame names and values.array of string getInformation(void);
Properties are Format, Bitrate, Samplerate, Channels, Duration, Channel Mode,
VBR, Tag 1, Tag 2. Properties which are not available are omitted.
Returns list with alternating property names and values.setTagFromFileName(int32 tagMask);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
setTagFromOtherTag(int32 tagMask);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
copyTag(int32 tagMask);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
pasteTag(int32 tagMask);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
removeTag(int32 tagMask);
tagMask
tag bit (1 for tag 1, 2 for tag 2)
reparseConfiguration(void);
Automated configuration changes are possible by modifying the configuration file
and then reparsing the configuration.playAudio(void);
AUTHOR¶
Urs Fleisch <ufleisch at users.sourceforge.net>Software development
COPYRIGHT¶
Copyright © 2014 Urs FleischNOTES¶
- 1.
- gnudb.org
- 2.
- TrackType.org
- 3.
- MusicBrainz
- 4.
- Discogs
- 5.
- Amazon
- 6.
- ID3 specification
- 7.
- SYLT Editor
- 8.
- www.gnudb.org
- 9.
- freedb.org
- 10.
- LyricWiki
- 11.
- 12.
- id3lib
- 13.
- libogg
- 14.
- libvorbis, libvorbisfile
- 15.
- libFLAC++ and libFLAC
- 16.
- TagLib
- 17.
- mp4v2
- 18.
- Chromaprint
- 19.
- libav
- 20.
- FDL
- 21.
- GPL
- 22.
- Qt
- 23.
- KDE
2014-08-21 | 3.1.1 |