Chapter 4. kid3-cli

Displays help about the parameters of COMMAND-NAME or about all commands if no command name is given.

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, these 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 application. If there are modified unsaved files, the force parameter is required.

If no FOLDER is given, change to the home folder. If a folder is given, change into the folder. If one or more file paths are given, change to their common folder and select the files.

Print the filename of the current working folder.

List the contents of the current folder. This corresponds to the file list in the Kid3 GUI. Five characters before the file names show the state of the file.

kid3-cli> ls
  1-- 01 Intro.mp3
> 12- 02 We Only Got This One.mp3
 *1-- 03 Outro.mp3

In this example, all files have a tag 1, the second file also has a tag 2 and it is selected. The third file is modified.

To select all files, enter select all, to deselect all files, enter select none. To traverse the files in the current folder 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 folder.

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

Many commands have an optional TAG-NUMBERS parameter, which specifies whether the command operates on tag 1, 2, or 3. If this parameter is omitted, the default tag numbers are used, which can be set by this command. At startup, it 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, 2, or 3 to operate only on the corresponding tag. If the parameter is omitted, the current setting is displayed.

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

To save the contents of a picture frame to a file, use

get picture:'/path/to/folder.jpg'

To save synchronized lyrics to an LRC file, use

get SYLT:'/path/to/lyrics.lrc'

It is possible to get only a specific field from a frame, for example get POPM.Email for the Email field of a Popularimeter frame. If a file has multiple frames of the same kind, the different frames can be indexed with brackets, for example the first performer from a Vorbis comment can be retrieved using get performer[0], the second using get performer[1].

The pseudo field name "selected" can be used to check if a frame is selected, for example get artist.selected will return 1 if the artist frame is selected, else 0.

The pseudo frame name "ratingstars" can be used to get the value of the "rating" frame as the format specific value corresponding to the number of stars (0 to 5). When using "rating", the internal value is returned.

This command sets the value of a specific tag frame. If FRAME-VALUE is empty, the frame is deleted.

kid3-cli> set remixer 'O.H. Wonder'

To set the contents of a picture frame from a file, use

set picture:'/path/to/folder.jpg' 'Picture Description'

To set synchronized lyrics from an LRC file, use

set SYLT:'/path/to/lyrics.lrc' 'Lyrics Description'

To set a specific field of a frame, the field name can be given after a dot, e.g. to set the Counter field of a Popularimeter frame, use

set POPM.Counter 5

An application for field specifications is the case where you want a custom TXXX frame with "rating" description instead of a standard Popularimeter frame (this seems to be used by some plugins). You can create such a TXXX rating frame with kid3-cli, however, you have to first create a TXXX frame with description "rating" and then set the value of this frame to the rating value.

kid3-cli> set rating ""
kid3-cli> set TXXX.Description rating
kid3-cli> set rating 5

The first command will delete an existing POPM frame, because if such a frame exists, set rating 5 would set the POPM frame and not the TXXX frame. Another possibility would be to use set TXXX.Text 5, but this would only work if there is no other TXXX frame present.

To set multiple frames of the same kind, an index can be given in brackets, e.g. to set multiple performers in a Vorbis comment, use

kid3-cli> set performer[0] 'Liza don Getti (soprano)'
kid3-cli> set performer[1] 'Joe Barr (piano)'

To select certain frames before a copy, paste or remove action, the pseudo field name "selected" can be used. Normally, all frames are selected, to deselect all, use set '*.selected' 0, then for example set artist.selected 1 to select the artist frame.

The pseudo frame name "ratingstars" can be used to set the value of the "rating" frame to the format specific value corresponding to the number of stars (0 to 5). The frame name "rating" can be used to set the internal value.

Setting "ratingstars" on multiple files having different tag formats will not work because the frame with the value mapped from the star count is created for the first file and then used for all files. So instead of kid3-cli -c "set ratingstars 2" * you should rather use for f in *; do kid3-cli -c "set ratingstars 2" "$f"; done.

Revert all modifications in the selected files (or all files if no files are selected).

Tags are imported from the file FILE in the format with the name FORMAT-NAME (e.g. "CSV unquoted", see Import).

If tags is given for FILE, tags are imported from other tags. Instead of FORMAT-NAME parameters SOURCE and EXTRACTION are required, see Import from Tags. To apply the import from tags on the selected files, use tagsel instead of tags. This function also supports output of the extracted value by using an EXTRACTION with the value %{__return}(.+).

Batch import using profile PROFILE-NAME (see Automatic Import, "All" is used if omitted).

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

Tags are exported to file FILE in the format with the name FORMAT-NAME (e.g. "CSV unquoted", see Export).

Create playlist in the format set in the configuration, see Create Playlist.

Apply file name format set in the configuration, see Apply Filename Format.

Apply tag name format set in the configuration, see Apply Tag Format.

Apply text encoding set in the configuration, see Apply Text Encoding.

Rename or create folders from the values in the tags according to a given FORMAT (e.g. %{artist} - %{album}, see Rename Folder), if no format is given, the format defined in the Rename folder dialog is used. The default mode is rename; to create folders, create must be given explicitly. The rename actions will be performed immediately, to just see what would be done, use the dryrun option.

Number the selected tracks starting with TRACK-NUMBER (1 if omitted).

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

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.

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.

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 the tag frames of the selected file to the internal copy buffer. They can then be set on another file using the paste command.

To copy only a subset of the frames, use the "selected" pseudo field with the set command. For example, to copy only the disc number and copyright frames, use

set '*.selected' 0
set discnumber.selected 1
set copyright.selected 1
copy

Set tag frames from the contents of the copy buffer in the selected files.

Remove a tag.

It is possible to remove only a subset of the frames by selecting them as described in the copy command.

Query or set a configuration option.

The OPTION consists of a group name and a property name separated by a dot. When no OPTION is given, all available groups are displayed. If only a group name is given, all available properties of the group are displayed. For a given group and property, the currently configured value is displayed. To change the setting, the new value can be passed as a second argument.

If the value of a setting is a list, all list elements have to be given as arguments. This means that to append an element to an existing list of elements, all existing elements have to be passed followed by the new element. In such a situation, it is easier to use the JSON mode, where the current list can be copied with the new element appended.

Execute a QML script or an executable.

Without @qml a program is executed with arguments. When @qml is given as the first argument, the following arguments are the QML script and its arguments. For example, the tags of a folder can be exported to the file export.csv with the following command.

kid3-cli -c "execute @qml
/usr/share/kid3/qml/script/ExportCsv.qml export.csv"
/path/to/folder/

Here export.csv is the argument for the ExportCsv.qml script, whereas /path/to/folder/ is the FILE argument for kid3-cli.