21 Aug 2020 - The wiki is undergoing a major cleanup. If you arrived here from a search engine and cannot find the page, please use the wiki search instead (top right corner of page)
More info can be found on the forum

Difference between revisions of "Music tagging"

From Official Kodi Wiki
Jump to: navigation, search
(Page re-written)
Line 659: Line 659:
[[Category:Advanced topics]]
[[Category:Advanced topics]]
[[Category:Quick Start Guide]]
[[Category:Quick Start Guide]]
{{DISPLAYTITLE:Music Files & Tagging}}

Revision as of 02:46, 11 October 2017

Steps to create your Music Library
Nuvola apps kscd.png
1. Guide Main Page
2. Music Settings
3. Music File Tagging
4. Scanning Music Into Library
5. Artist information folder
6. Scraping Additional Music data

7. Update Music Library
8. NFO Files
8.1 Music NFO Files
9. Artwork
9.1 Music Artwork

10. Import-export library
10.1 Music Import-Export
11. Backup & Recover

1 Introduction

This page, Music File and Tagging, provides the following information:

  • How the Music section differs from the Video section of Kodi
  • How to organise your music files
  • The recommended method for tagging your music files
  • Explanation of some commonly misunderstood Music File Tags
  • The Audio Files and Tags that Kodi reads and uses

2 Understanding the Music Library

The Music section of Kodi has many differences to the Video section of Kodi. It is important that you read this section to ensure your music and artwork are correctly scraped and displayed.

It is important to understand the fundamental difference between video library operation and the music library operation:

  • The video library is based on using the filenames to obtain online data. If the video files are incorrectly named, then there are no scraper results and there will be no library entry.
  • The music library is based on scanning tags embedded in the music files. It ignores the folder structure and file names you have created to store your music files. Basic and correct tagging is essential to ensure the library is populated correctly. Having slight variations in the tags for artist and album names could mean duplicated and unwanted entries.

3 Folder and File Structure

Although Kodi ignores the folder structure and the names of the folders and files, the structure of your folders is important as it affects the operation of other functions such as Import/Export, nfo files and Artwork. For example, if you have all your music files in one folder (which is possible), then you lose the ability to use local nfo files, local artwork, and the import/export module will not function correctly.

For this reason, Kodi recommends the use of the following structure.

3.1 Files

Remember that Kodi does not extract any information from the filename. The only purpose the file name serves is to provide Kodi a unique id to locate the file.

The name you use for your files is your choice, but it is important that they are:

  1. Consistent
  2. Make sense

Example file names:

  • Using the simple Song Name only = Everybody Wants to Rule the World.flac
  • Using a more complex combination of Artist-Album-Song = Madonna-True Blue-Open Your Heart.flac

If you would like to use track numbers in the file name, then ensure you include the disc number, even if there is only one disc. eg

  • 0102 Everybody Wants to Rule the World.flac or D01T02 Everybody Wants to Rule the World.flac
  • Madonna-True Blue-0106 Open Your Heart.flac or Madonna-True Blue-D01T06 Open Your Heart.flac

Where 0102 = Disc 01 and Track 02

3.2 Folders

Folders are used as follows:

  1. Album folders - Used to group songs from the same album into one folder
  2. Artist folders- Used to group albums from the same artist into one folder
  3. Source folder- Used to group Collections into one folder. (see next section)

The following is a typical recommended structure:

f:\   ....................................(root)
 |__Artist Music   .......................(source folder)
 |  |__ Madonna   ........................(artist folder)
 |  |   |__ Beautiful Stranger (1999)   ..(album folder)
 |  |   |   |__ Song 1
 |  |   |   |__ Song 2
 |  |   |   |__ Song 3 etc
 |  |   |__ Bedtime Stories (1994)   .....(album folder)
 |  |   |   |__ Song 1
 |  |   |   |__ Song 2
 |  |   |   |__ Song 3 etc
 |  |   |__ Like A Prayer (1989)   .......(album folder)
 |  |   |   |__ Song 1
 |  |   |   |__ Song 2
 |  |   |   |__ Song 3 etc
 |  |__ Simply Red   .....................(artist folder)
 |      |__ Picture Book (1985)   ........(album folder)
 |          |__ Song 1
 |          |__ Song 2
 |          |__ Song 3 etc
 |__Compilations   .......................(Source)
 |  |__ Essential Eighties   .............(album folder)
 |  |       |__ Song 1
 |  |       |__ Song 2
 |  |       |__ Song 3 etc
 |  |__ 100% Hits- Best of 2005   ........(album folder)
 |          |__ Song 1
 |          |__ Song 2
 |          |__ Song 3 etc
 |__Classical   ..........................(Source)
 |__Audio Books   ........................(Source)

3.3 Sources

A source folder contains your media collection- in this case Music. This folder is then set as a Source in Kodi which enables Kodi to access your Music. (remember, Kodi does not know where your media is until you tell it)

In the Video section of Kodi, you would set one, or more, sources for Movies, TV Shows, Music Videos, Home Movies etc. The Music section oparates along the same principle.

As an example, you would save your music folders into separate Sources for the following:

  • Single Artist type Albums
    • These are albums released by a single artist or band
    • This source will contain the Artist / Album / Song structure
    • Examples- Kate Bush, Kylie Minogue, Tears for Fears etc
  • Various Artists or Compilation Albums
    • These are albums that contain songs from many different artists or bands.
    • As there is multiple artists, there is no Artist folder. This source would contain the Album / Song structure.
    • Examples- 2017 Grammy Nominees, So Fresh: Hits of 2016, Open Space: The Classic Chillout Album etc
  • Classical Music
    • Albums released by a single Composer. It is a separation from the main stream music in the Single Artist Source, which aids in better sorting in Kodi
    • This source would contain the Artist / Album / Song structure, assuming single composer type albums, and groups all classical music in one source
    • Examples- Vaughan Williams, Rachmaninov, Mozart etc

The idea is to group similar types of albums. This is not a requirement, and Kodi will still function if you grouped your music into a single source. It is a best practice guide which overcomes some hurdles with local files for compilation and collaboration type albums. These hurdles will no longer be an issue from v18 onwards.

Setting and Scanning of Sources is covered in detail in the next step of the guide.

4 Ripping CD's

Kodi has integrated Audio-CD (CDDA) ripping functionality. In order to use this feature, first configure the CD ripping settings (to set which encoder quality to use and where to store the files). To Rip the entire CD, highlight the Audio CD from the My Music root listing and choose Rip Audio CD from the context menu. To rip a single track, enter the Audio CD, highlight the desired track, and choose Rip Audio Track from the context menu.

There is no requirement to use this native Kodi CD Ripper. If you are comfortable using other ripping software, then we recommend you continue using that software. It makes no difference to Kodi which software was used.

5 Tagging

Ever wonder how your music player always knows the name of the song, album, artist and track number of the music you play? This information comes from metadata embedded in the music file. If you purchased your music from an online store, then that store would have embedded the metadata in the file. If you ripped your own music, then the ripping software would have embedded the data into the file, probably without you even knowing. It is not uncommon that only minimal metadata is embedded, but this works very well on simple music players and is a convenient solution to sorting your library on these players.

Kodi also makes use of this embedded metadata. Kodi, being an advanced and feature rich player, requires a greater precision in the embedded tags. Any slight variance in, for example, the Album name between the tracks from the same album will see multiple entries in the library for that Album. Same with Artists. It is not uncommon to have a single album split into three similarly named albums. It is for this reason that there is a separation of the Scanning and Scraping processes for Music. The initial scan allows you to find and correct errors in tagging, before scraping. Failing to do that will create an unmanageable library.

Example of errors in tagging, which will cause duplicated entries in the library...

Similar Name 1 Similar Name 2 Note
György Ligeti Gyorgy Ligeti Accented and unaccented names will create duplicate entries
The Best of The Very Best Of Inconsistent naming between songs of the same album and/or artist will cause duplicated entries
Madonna Madonnna Spelling mistakes will cause duplicated entries for albums and/or artists
Sting Sting and The Police Seen as two separate and unrelated Artists

The easiest method to comprehensively tag your music files is with MusicBrainz Picard.

As Kodi scans your music collection, it copies the data contained in those tags into the Kodi music database. The benefits of this are:

  • Once the scan is complete, the tags are not accessed again
  • All information is now obtained from the database. This has the benefit of dramatically increasing efficency and speed when navigating the library.
  • Now that a database entry exists, you are able to scrape additional information from online sources. This is covered later in the guide.

5.1 MusicBrainz

Kodi has strong support for MusicBrainz tagging. It is highly recommended that users tag their music files using MusicBrainz picard.

MusicBrainz is an open source music encyclopedia that collects music metadata and makes it available to the public. MusicBrainz has a database that, as of Sept 2017, consists of over 1,258,860 Artists, over 1,866,600 albums and over 17,846,800 recordings.

MusicBrainz Picard is the music file tagger software that can access the MusicBrainz database to locate metadata to embed into your music files. It is recommended that your music collection is correctly tagged using the tagging software MusicBrainz Picard. This is a free download. There are other Taggers that are able to access the MusicBraniz database, but Picard seems to be friendliest to use.

Below is a screenshot of the main screen of the Picard software. A brief description of the layout as follows.

  • Top Left Box- Folder listing of your music collection
  • Top Centre Box- Albums are dragged and dropped here in preparation for matching and tagging. Pressing Lookup (greyed out) will commence the lookup process
  • Top Right Box- Matching albums are displayed here and your songs are overlayed. In the screenshot, songs 01, 08 and 09 have been matched to the suggested album. If all songs match and you agree the correct album was located, simply pressing Save will tag the album with the tags displayed in the Bottom Tag Box.
  • Bottom Tag Box - Selecting a song from the Top Right Box will display all available tag fields (left column), the current tags in the music file (Original Value column) and the MusicBrainz tags to be embedded in the music file (right column).

It is important to note that a lot of music is distributed with only the basic metadata embedded, as can be clearly seen in the screenshot below. (Original Value column)

The example in the image below shows the following:

  • Most tags are missing (original value column)
  • The top three yellow entries are incorrect (original value column) and the corrections are in the right column
  • The green entries in the right column indicate new tags to be embedded
  • The black entries at the bottom of the list indicate no change to the existing tags as they are correct.

Although Kodi will populate the library with those minimal tags, the errors in those tags would create havoc in the library.

Further information and guides can be found at the MusicBrainz Picard site.


Although Picard is very easy to use, you must avoid blindly accepting everything offered by the software. It is important that you confirm the correct album was located. Due to the global nature of the database, there are many releases for a single album. These releases differ between countries, usually due to copyright requirements. This may lead you to inadvertendly select the incorrect release for your album, even though it is named exactly the same. The differences between releases may be as simple as different song ordering or the inclusion of additional bonus tracks.

Once the music files are tagged, it is important to avoid modifying the MusicBrainz tags unless you clearly understand the relationship of the MBID's and the other related tags. For example, embedding MBID tags, but then editing the Artist tag or Album Artist tag will result in incorrect entries in the library.

See: MusicBrainz Website
See: MusicBrainz Picard Software

5.2 Cue Sheets

Cue Sheets are used to provide index and playlist information for a large audio file. They are generally used in conjunction with either extracting from, or burning to, Music AudioCD. Cue sheets have the file extension ".cue", and are simple plain text files.

Kodi does provide basic support for using cue sheets to define individual tracks when an entire CD has been ripped into a single music file. However the information provided by the cue sheet standard is much more limited than that of standard tagging, hence to enjoy the full music library features it is recommended that tracks are ripped into separate files and fully tagged.
If you do not use Cue Sheets you can safely move onto the next step.

6 Streams

Various internet video and audio streams can be played back in Kodi as if they were locally stored on your media center by using STRM files. As long as the format and streaming-method (network-protocol) is supported by Kodi, stream can be added. These are basic text files that look like <name>.strm and contain a URL to the internet stream. STRM files can also be added to the video library and can have cover art, summaries, etc.

Some internet sites may have an add-on available that can also access these media streams, rather than having to manually create STRM files. See Add-ons for more information on how to find and install add-ons.

The information in the remainder of this page is provided for technical interest and reference only. It can be safely disregarded if you have no technical interest in Music File Tagging

Next step: Scanning Music Into Library

7 Technical Explanation: File tags

For many categories, such as genres and artists, Kodi supports multiple values in the one field. By default it uses the character sequence " / " to divide the entry into multiple values. This divider may be changed via advancedsettings.xml.

7.1 Resolving Compilations and Multiple Artists

Kodi reads the Album Artist tag in ID3, Ogg, APE and MP4 tags and uses it if available to assign an artist to the album (independently of the track's artist information). This is the "Album Artist" tag (in ID3 this is represented by the "TPE2" tag; in vorbiscomment (ogg) files "ALBUMARTIST", "ALBUM ARTIST" and "ENSEMBLE" are all supported). Multiple artists for either a track or album artist can be specified in "Artist1 / Artist2 / Artist3" format.

If no Album Artist tag exists, Kodi will use the first (primary) artist from the tracks as the Album Artist. Essentially we do a string comparison of all the track artists, and assign the common artists as the Album artist. This is generally the TPE1 tag in ID3.

As many users don't yet use the Album Artist tag, Kodi has an additional filter system for identifying compilation albums, where each track normally has a different artist. As Kodi scans a folder, it does the following:

  1. Identifies albums based on Album name alone in the folder and groups the songs that have the same Album name together as an album.
  2. Runs through each album's assigned songs. If there is 2 or more tracks with the same Track number, the group of songs must come from 2 or more albums, so the Album name is ruled out as a possible compilation.
  3. If any of the songs assigned to the Album name have an Album Artist tag, then Kodi assumes the user knows what they're doing, and this album is also ruled out from being a compilation.
  4. If two or more songs assigned to the Album name then have different primary artists, then the Album name is considered to be a group of songs from a compilation, and the Various Artists" tag is assigned as the album artist.
  5. Otherwise, if all the songs have the same primary artist but don't have the same full artist list (eg a song or two has an additional artist) then the album is assigned the primary artist as it's Album Artist, and we assume the additional artists are guest artists.

7.2 Roles Tags


7.3 Ratings in ID3 tags

Ratings in ID3 tags are read via the POPM field, and (if this doesn't exist) in a custom (TXXX) field named "RATING". For the RATING field, we accept 1-5 as valid ratings. For the POPM field things are more complicated, as there is no established standard in place. We currently most closely respect what Mediamonkey does, and also have some support for what Windows Media Player 11 does. The POPM tag takes a value from 0..255, with 0 meaning no rating, 1 the worst, and 255 the best. We currently map these as follows:

POPM value Star rating
1 * This is a special case for Windows Media Player
9-49 *
50-113 **
114-167 ***
168-218 ****
219-255 *****

8 Audio Formats & Tags

8.1 Supported Audio Formats

Although the list of playable formats is quite comprehensive, it is not accurate to say that every Kodi installation will play every format. The ability to play some of the more obscure formats will depend upon the version of Kodi and the operating system in use. Some formats will require the installation of add-ons.

Default extensions for MUSIC:

.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.


8.2 Supported Metadata Containers

The following metadata containers are supported by Kodi

Metadata Container Note
APEv2 tag
Generic Tag A generic tag for basic data from other odd file types
ID3 v1, v2.3 and v2.4
Xiph.org Vorbis Comments

8.3 Common File & Tag Combination

You will notice that not all the tags listed in the section Supported Audio Formats above are listed in the following table. Those formats that are ommitted do not have provision to support embedded tags. If your collection contains any of these unsupported formats, you will be unable to scan the music into the library. Your options are:

  1. Convert your audio file to a supported format and tag using MusicBrainz Picard. (recommended)
  2. Access your music via the File Manager or via File View

Kodi supports the following common Audio File and Tag Formats

Metadata container Additional Filename extensions
APEv2 tag ape, mp3, aac, wv, mpc
ASF asf, wmv, wma
Generic Tag it, mod, module, nst, wow, s3m, xm
ID3 v1 mp3, aac
ID3 v2 mp3, aac, tta, aif, aiff, wav, flac
iTunes MP4 .3g2 .m4a .m4b .m4p .m4r .m4v .mp4
Xiph.org flac, oga, ogg, opus


  • FLAC files- xiph tags override id3v2 tags
  • mp3 files can have either id3 or APE tags
  • mka, dsf, dff - ID3v2 format read but are handled by ffmpeg tag reader and it does not support all tags from IDE standard)

8.4 Tags Kodi reads

Kodi will scan the following tags embedded in the music file. The column Kodi Version indicates the version of Kodi that the tag was introduced, and will work in subsequent versions.

Kodi Version Vorbis (.Flac) ID3v2 (.mp3) APE MP4 ASF
v16 ALBUM TALB ALBUM \251alb WM/AlbumTitle
v16 TITLE TIT2 TITLE \251nam
v16 YEAR TYER YEAR \251day WM/Year
v16 GENRE TCON GENRE \251gen WM/Genre
v16 MOOD TMOO OR TXXX:MOOD MOOD ----:com.apple.iTunes:MOOD WM/Mood
v16 REPLAYGAIN_TRACK_GAIN REPLAYGAIN_TRACK_GAIN REPLAYGAIN_TRACK_GAIN ----:com.apple.iTunes:replaygain_track_gain replaygain_track_gain
v16 REPLAYGAIN_ALBUM_GAIN REPLAYGAIN_ALBUM_GAIN REPLAYGAIN_ALBUM_GAIN ----:com.apple.iTunes:replaygain_album_gain replaygain_album_gain
v16 REPLAYGAIN_TRACK_PEAK REPLAYGAIN_TRACK_PEAK REPLAYGAIN_TRACK_PEAK ----:com.apple.iTunes:replaygain_track_peak replaygain_track_peak
v16 REPLAYGAIN_ALBUM_PEAK REPLAYGAIN_ALBUM_PEAK REPLAYGAIN_ALBUM_PEAK ----:com.apple.iTunes:replaygain_album_peak replaygain_album_peak
v16 REPLAYGAIN_ALBUM_PEAK REPLAYGAIN_ALBUM_PEAK REPLAYGAIN_ALBUM_PEAK ----:com.apple.iTunes:replaygain_album_peak replaygain_album_peak
v16 MUSICBRAINZ_ARTISTID MUSICBRAINZ ARTIST ID MUSICBRAINZ_ARTISTID ----:com.apple.iTunes:MusicBrainz Artist Id MusicBrainz/Artist Id
v16 MUSICBRAINZ_ALBUMID MUSICBRAINZ ALBUM ID MUSICBRAINZ_ALBUMID ----:com.apple.iTunes:MusicBrainz Album Id MusicBrainz/Album Id
v16 MUSICBRAINZ_TRACKID UFID MUSICBRAINZ_TRACKID ----:com.apple.iTunes:MusicBrainz Track Id
v17 COMPOSER TCOM COMPOSER \251wrt WM/Composer
v17 CONDUCTOR TPE3 CONDUCTOR ----:com.apple.iTunes:CONDUCTOR WM/Conductor
v17 LYRICIST TEXT LYRICIST ----:com.apple.iTunes:LYRICIST WM/Writer
v17 REMIXER or MIXARTIST TPE4 REMIXER or MIXARTIST ----:com.apple.iTunes:REMIXER WM/ModifiedBy
v17 ENGINEER (TIPL) ENGINEER ----:com.apple.iTunes:ENGINEER WM/Engineer
v17 PRODUCER (TIPL) PRODUCER ----:com.apple.iTunes:PRODUCER WM/Producer
v17 DJMIXER (TIPL) DJMIXER ----:com.apple.iTunes:DJMIXER WM/DJMixer
v17 MIXER (TIPL) MIXER ----:com.apple.iTunes:MIXER WM/Mixer
v17 LABEL TPUB LABEL ----:com.apple.iTunes:LABEL WM/Publisher
v17 RELEASETYPE MUSICBRAINZ ALBUM TYPE MUSICBRAINZ_ALBUMTYPE ---:com.apple.iTunes:MusicBrainz Album Type MusicBrainz/Album Type

Return to top

Next step: Scanning Music Into Library