Kid3 CLI

https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html
Admin
Kid3 CLI is a command-line audio tag editor that allows users to view, edit, and convert metadata...
Tokens:9,097
Snippets:72
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Select and list files with kid3-cli

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Example of using the select command to select files and the ls command to list them, showing the state of each file. The output shows the selected file with '>' and modified files with '*'. The example demonstrates selecting the first file, moving to the next, and selecting all MP3 files.

```text
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
```

--------------------------------

### Get all tag frames and get title

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Shows output of 'get' with no arguments (all frames) and 'get title' returning the title value. Modified frames are marked with '*'. The output includes file format and tag details.

```shell
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
```

--------------------------------

### filter command: filter files by title and reset

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Filters files by a format expression and shows the resulting list. The example filters titles containing 'tro', then resets with 'filter All'. Output shows which files are added or removed.

```text
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
```

--------------------------------

### get [all | FRAME-NAME] [TAG-NUMBERS]

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Reads the value of a specific tag frame or gets information about all tag frames. Supports saving picture frames to files, synchronized lyrics to LRC files, accessing specific fields, indexing multiple frames, checking selection, and using ratingstars.

```APIDOC
## get [all | FRAME-NAME] [TAG-NUMBERS]

### Description
Reads the value of a specific tag frame or gets information about all tag frames (if the argument is omitted or `all` is used). Modified frames are marked with a '*'.

### Method
get

### Endpoint
kid3-cli get [all | FRAME-NAME] [TAG-NUMBERS]

### Parameters
#### Arguments
- **all | FRAME-NAME** (string) - Optional - If omitted or `all`, displays all tag frames. Otherwise, specifies the frame name to read.
- **TAG-NUMBERS** (string) - Optional - Specifies which tag numbers to operate on.

### Usage Examples
```
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.

```

--------------------------------

### playlist

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Creates a playlist using the configured format.

```APIDOC
## playlist

### Description
Creates a playlist in the format set in the configuration.

### Syntax
`playlist`
```

--------------------------------

### Set picture frame from file

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets the contents of a picture frame from a file, with a description.

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

--------------------------------

### Set ratingstars on multiple files

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Shows the recommended loop for setting 'ratingstars' on multiple files, because using a wildcard with -c does not work correctly.

```shell
for f in *; do kid3-cli -c "set ratingstars 2" "$f"; done
```

--------------------------------

### config

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Queries or sets configuration options.

```APIDOC
## config

### Description
Queries or sets 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.

### Syntax
`config [OPTION] [VALUE]`

### Parameters
- **OPTION** (string) - Optional - The configuration option in the form `group.property`.
- **VALUE** (string) - Optional - The new value to set.
```

--------------------------------

### fromtag

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets file names from tag values.

```APIDOC
## fromtag

### Description
Sets the file names of the selected files from values in the tags. If no format is specified, the format set in the GUI is used.

### Syntax
`fromtag [FORMAT] [TAG-NUMBERS]`

### Parameters
- **FORMAT** (string) - Optional - The format string (e.g. `%{track} - %{title}`).
- **TAG-NUMBERS** (string) - Optional - Tag numbers to use.

### Example
```
kid3-cli> fromtag '%{track} - %{title}' 1
```
```

--------------------------------

### Create custom TXXX rating frame

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Creates a TXXX frame with description 'rating' and sets its value. The first command deletes an existing POPM frame to ensure 'set rating 5' targets the TXXX frame.

```shell
kid3-cli> **set rating ""**
kid3-cli> **set TXXX.Description rating**
kid3-cli> **set rating 5**
```

--------------------------------

### albumart command: download album cover from URL

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Downloads album artwork from a URL and sets it as the album cover. The URL is transformed according to the rules in the Browse Cover Art dialog. Use the set command for local picture files.

```text
kid3-cli> **albumart
http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC**
```

--------------------------------

### tagformat

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Applies the configured tag name format to the selected files.

```APIDOC
## tagformat

### Description
Applies the tag name format set in the configuration.

### Syntax
`tagformat`
```

--------------------------------

### Set synchronized lyrics from LRC file

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets synchronized lyrics from an LRC file with a description.

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

--------------------------------

### filenameformat

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Applies the configured file name format to the selected files.

```APIDOC
## filenameformat

### Description
Applies the file name format set in the configuration.

### Syntax
`filenameformat`
```

--------------------------------

### totag

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets tag frames from file names.

```APIDOC
## totag

### Description
Sets the tag frames from the file names. 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.

### Syntax
`totag [FORMAT] [TAG-NUMBERS]`

### Parameters
- **FORMAT** (string) - Optional - The format string (e.g. `%{albumartist} - %{album}/%{track} %{title}`).
- **TAG-NUMBERS** (string) - Optional - Tag numbers to use.

### Example
```
kid3-cli> totag '%{albumartist} - %{album}/%{track} %{title}' 2
```
```

--------------------------------

### Execute QML script with kid3-cli -c execute @qml

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Executes the ExportCsv.qml QML script via kid3-cli, passing export.csv as the script argument and /path/to/folder/ as the FILE argument for kid3-cli. The @qml flag must be the first argument after execute to run a QML script instead of a program.

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

--------------------------------

### syncto

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Copies tag frames from one tag to another.

```APIDOC
## syncto

### Description
Copies the tag frames from one tag to the other tag.

### Syntax
`syncto <TAG-NUMBER>`

### Parameters
- **TAG-NUMBER** (integer) - Required - The tag number to copy from.

### Example
```
kid3-cli> syncto 2
```
```

--------------------------------

### export

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Exports tags to a file in a specified format.

```APIDOC
## export

### Description
Exports tags to a file in the specified format.

### Syntax
`export <FILE> <FORMAT-NAME> [TAG-NUMBERS]`

### Parameters
- **FILE** (string) - Required - The file to export tags to.
- **FORMAT-NAME** (string) - Required - The name of the export format (e.g. "CSV unquoted").
- **TAG-NUMBERS** (string) - Optional - Tag numbers to export.
```

--------------------------------

### import {FILE} {FORMAT-NAME} [TAG-NUMBERS]

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Imports tags from a file in a specified format, or from other tags when 'tags' is given as FILE. Supports output of extracted values using a special extraction pattern.

```APIDOC
## import {FILE} {FORMAT-NAME} [TAG-NUMBERS]

### Description
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}(.+)`.

### Method
import

### Endpoint
kid3-cli import {FILE} {FORMAT-NAME} [TAG-NUMBERS]

### Parameters
#### Arguments
- **FILE** (string) - Required - The file to import from. If `tags`, imports from other tags.
- **FORMAT-NAME** (string) - Required - The name of the import format (e.g. "CSV unquoted"). If FILE is `tags`, this is replaced by SOURCE and EXTRACTION.
- **TAG-NUMBERS** (string) - Optional - Specifies which tag numbers to operate on.

```

--------------------------------

### Save picture frame to file

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Saves the contents of a picture frame to a file using the 'picture:' prefix in the frame name.

```shell
**get picture:'/path/to/folder.jpg'**
```

--------------------------------

### Set multiple performers with index

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets multiple frames of the same kind using bracket indices, e.g., performers in a Vorbis comment.

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

--------------------------------

### copy command: copy selected frames using set

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Copies only selected frames (disc number and copyright) to the internal copy buffer. The 'selected' pseudo field is used with the set command to choose which frames to copy.

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

--------------------------------

### albumart

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Downloads album cover artwork from a URL and sets it as the album art.

```APIDOC
## albumart

### Description
Set the album artwork by downloading a picture from the given URL. The rules defined in the Browse Cover Art dialog are used to transform general URLs (e.g. from Amazon) to a picture URL.

### Syntax
`albumart <URL> [all]`

### Parameters
- **URL** (string) - Required - The URL of the picture to download.
- **all** (flag) - Optional - Apply to all selected files.

### Example
```
kid3-cli> albumart http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC
```
```

--------------------------------

### textencoding

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Applies the configured text encoding to the selected files.

```APIDOC
## textencoding

### Description
Applies the text encoding set in the configuration.

### Syntax
`textencoding`
```

--------------------------------

### autoimport [PROFILE-NAME] [TAG-NUMBERS]

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Performs batch import using a specified profile, defaulting to 'All' if omitted.

```APIDOC
## autoimport [PROFILE-NAME] [TAG-NUMBERS]

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

### Method
autoimport

### Endpoint
kid3-cli autoimport [PROFILE-NAME] [TAG-NUMBERS]

### Parameters
#### Arguments
- **PROFILE-NAME** (string) - Optional - The name of the import profile. Defaults to "All" if omitted.
- **TAG-NUMBERS** (string) - Optional - Specifies which tag numbers to operate on.

```

--------------------------------

### paste

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Pastes tag frames from the copy buffer to the selected files.

```APIDOC
## paste

### Description
Sets tag frames from the contents of the copy buffer in the selected files.

### Syntax
`paste [TAG-NUMBER]`

### Parameters
- **TAG-NUMBER** (integer) - Optional - The tag number to paste to.
```

--------------------------------

### renamedir

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Renames or creates folders based on tag values.

```APIDOC
## renamedir

### Description
Renames or creates folders from the values in the tags according to a given format. If no format is given, the format defined in the Rename folder dialog is used.

### Syntax
`renamedir [FORMAT] [create|rename|dryrun] [TAG-NUMBERS]`

### Parameters
- **FORMAT** (string) - Optional - The format string (e.g. `%{artist} - %{album}`).
- **create|rename|dryrun** (enum) - Optional - The mode of operation. Default is `rename`.
- **TAG-NUMBERS** (string) - Optional - Tag numbers to use.
```

--------------------------------

### numbertracks

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Numbers the selected tracks sequentially.

```APIDOC
## numbertracks

### Description
Numbers the selected tracks starting with the given track number (default 1).

### Syntax
`numbertracks [TRACK-NUMBER] [TAG-NUMBERS]`

### Parameters
- **TRACK-NUMBER** (integer) - Optional - The starting track number. Default is 1.
- **TAG-NUMBERS** (string) - Optional - Tag numbers to apply the numbering to.
```

--------------------------------

### copy

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Copies tag frames to an internal buffer for later pasting.

```APIDOC
## copy

### Description
Copies 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.

### Syntax
`copy [TAG-NUMBER]`

### Parameters
- **TAG-NUMBER** (integer) - Optional - The tag number to copy from.

### Example
```
set '*.selected' 0
set discnumber.selected 1
set copyright.selected 1
copy
```
```

--------------------------------

### Set remixer frame

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets the value of the 'remixer' frame. If the value is empty, the frame is deleted.

```shell
kid3-cli> **set remixer 'O.H. Wonder'**
```

--------------------------------

### revert

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

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

```APIDOC
## revert

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

### Method
revert

### Endpoint
kid3-cli revert

### Parameters
None.

```

--------------------------------

### to24

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Converts ID3v2.3 tags to ID3v2.4.

```APIDOC
## to24

### Description
Converts ID3v2.3 tags to ID3v2.4.

### Syntax
`to24`
```

--------------------------------

### set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets the value of a specific tag frame. If the value is empty, the frame is deleted. Supports setting picture frames from files, synchronized lyrics from LRC files, specific fields, indexed frames, selection, and ratingstars.

```APIDOC
## set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]

### Description
Sets the value of a specific tag frame. If FRAME-VALUE is empty, the frame is deleted.

### Method
set

### Endpoint
kid3-cli set {FRAME-NAME} {FRAME-VALUE} [TAG-NUMBERS]

### Parameters
#### Arguments
- **FRAME-NAME** (string) - Required - The name of the frame to set.
- **FRAME-VALUE** (string) - Required - The value to set. If empty, the frame is deleted.
- **TAG-NUMBERS** (string) - Optional - Specifies which tag numbers to operate on.

### Usage Examples
```
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`.

```

--------------------------------

### Save synchronized lyrics to LRC file

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Saves synchronized lyrics to an LRC file using the 'SYLT:' prefix.

```shell
**get SYLT:'/path/to/lyrics.lrc'**
```

--------------------------------

### to23

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Converts ID3v2.4 tags to ID3v2.3.

```APIDOC
## to23

### Description
Converts ID3v2.4 tags to ID3v2.3.

### Syntax
`to23`
```

--------------------------------

### remove

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Removes a tag or selected frames.

```APIDOC
## remove

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

### Syntax
`remove [TAG-NUMBER]`

### Parameters
- **TAG-NUMBER** (integer) - Optional - The tag number to remove.
```

--------------------------------

### Set specific field of a frame

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Sets a specific field of a frame using dot notation, e.g., Counter field of a Popularimeter frame.

```shell
**set POPM.Counter 5**
```

--------------------------------

### filter

Source: https://docs.kde.org/trunk_kf6/en/kid3/kid3/kid3-cli.html

Filters the visible files based on a filter expression or predefined filter name.

```APIDOC
## filter

### Description
Filters the files so that only the files matching the filter format are visible. A predefined filter name can be used instead of a filter expression.

### Syntax
`filter [FILTER-NAME|FILTER-FORMAT]`

### Parameters
- **FILTER-NAME** (string) - Optional - The name of a predefined filter expression (e.g. "Filename Tag Mismatch").
- **FILTER-FORMAT** (string) - Optional - A filter expression (e.g. `%{title} contains "tro"`).

### Example
```
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
```
```
Tokens:
Raw