Video file tagging: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
m (removed Category:FAQ using HotCat)
 
(29 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{mininav|[[Video library]]||}}
{{mininav|[[Video library]]||}}
{{incomplete}}
{{incomplete}}
{{VideoLibraryCreate}}
{{notice|This page describes an alternative way of adding movies to the library that is not dependent on file names or online scrapers.}}
{{progress|30}}
'''{{red|{{resize|1.3em|This page describes an alternative way of adding video files to the library that is not dependent on file names or online scrapers. If you have already named and organized your files using Kodi's naming guidelines, then you can safely ignore this page and go to the next step.}}}}'''


= Introduction =
<section begin="intro" />Kodi v18 Leia introduces support for embedded video tags using '''*.mkv''' and '''*.mp4''' video files. '''*.avi''' support is available since v18.x. They are similar in principle to the tags saved in audio files. Only limited support for video tags is available at this time.<section end="intro" />
<section begin="intro" />Kodi v18- Leia introduces support for Video File Tags using '''*.mkv''' and '''*.mp4''' video files. They are similar in principle to the tags saved in Audio files that we are so familiar with, but only limited support is available at this time. This is a very sought after feature for many members.


'''Note''', this is a specialised feature that has been requested by some users. '''This step is not required to add movies and TV Shows to the library'''. If you arrived at this page following the guide, you can safely move onto the next section.<section end="intro" />
= Benefits of embedded video tags =
 
 
mp4 tags are standardized, but only for a rather small subset of the the information kodi can use, see above.. (spiff)
 
TV Shows are not yet supported.
 
 
 
== Why do I want this? ==
There are multiple reasons why one would want to use this feature:
There are multiple reasons why one would want to use this feature:
Media may already contain useful metadata (the reverse however is also true - many files contain "junk" metadata, hence why the feature defaults to off).
Media may already contain useful metadata (the reverse however is also true - many files contain "junk" metadata, hence why the feature defaults to off).
It gives one more control over the metadata than scrapers do (as scrapers may misclassify media and pull the wrong data).
It gives one more control over the metadata than scrapers do (as scrapers may misclassify media and pull the wrong data).
It does away with the need to have .nfo files. Since metadata travels with the media file, there is no longer a need for potentially thousands of these smaller files and can make directory management even easier.
It does away with the need to have [[NFO files]]. Since metadata travels with the media file, there is no longer a need for potentially thousands of these smaller files and can make directory management even easier.
Using ultra-high resolution Artwork/cover images that looks nicer on newer HD displays.(Pretty pictures!)
Using ultra-high resolution [[artwork]]/cover images that looks nicer on newer HD displays. (Pretty pictures!)
 


== How does it change/differ from the old model? ==
Kodi has two options for metadata import: using an online scraper or using local information, traditionally in the form of .nfo files. Local tag reading is bundled into the "Local Information" arm, as logically, metadata is still local (i.e not network-drawn) information. Thus, one can still use a combination of .nfo files and embedded information if they choose "Local Information" rather than to use a scraper.


== How does it change/differ to the old model? ==
It is important to note however that .nfo files will override embedded information. Not all of Kodi's NFO features are supported by embedded metadata yet, so many users may wish to still use the NFO method. (https://forum.kodi.tv/showthread.php?tid=326340)
Kodi has two options for metadata import: using an online scraper or using local information, traditionally in the form of .nfo files. local tag reading is bundled into the "Local Information" arm, as logically, metadata is still local (i.e not network-drawn) information. Thus, one can still use a combination of .nfo files and embedded information if they choose "Local Information" rather than to use a scraper.
 
It is important to note however that .nfo files will override embedded information. Not all of Kodi's NFO features are supported by embedded metadata yet, so many users may wish to still use the NFO method. (https://forum.kodi.tv/showthread.php?tid=326340.


== Settings ==
== Settings ==
The {{kodi}} settings has the option to enable or disable the reading of video file tags. The default setting is disabled.<br />
{{Kodi}} [[settings]] have the option to enable or disable the reading of video file tags at [[Settings/Media/Videos|Settings > Media Settings > Videos > Use video tags]]. The default setting is ''disabled''.
{{red|link to settings page here- Settings>Media Settings>Videos>Use video tags}}
 
This page assumes this setting has been enabled.
 


This page assumes this setting has been ''enabled''.


= Folder & File Structure =
= Folder & File Structure =
The use of Video File Tags does not absolve you from using the correct Folder and File structure for Movies, TV Shows and [[Music_videos|Music Videos]] as detailed in the previous pages. Use the navbox above to locate and read those requirements.
The use of Video File Tags does not absolve you from using the correct Folder and File structure for [[Naming video files/Movies|Movies]], [[Naming video files/TV shows|TV Shows]] and [[Music videos|Music Videos]] as detailed in the previous pages.
 
 


= Tagging =
= Tagging =
Line 50: Line 31:


== Windows ==
== Windows ==
mp3tag is a Windows based metadata editor for many different files types, including MP4 (despite what it's name may suggest). While somewhat complex, it provides very fine-grained control over tagging, and is a worthwhile asset in any media management library.
[http://www.mp3tag.de MP3tag] is a Windows-based metadata editor for many different files and tag types, including MP4 and MKV (despite what it's name may suggest). While somewhat complex, it provides very fine-grained control over [https://help.mp3tag.de/main_tags.html tagging], and is a worthwhile asset in any media management library.


MetaX is a user friendly tagging solution, However it is proprietary and paid ($10). It features much the same core features as MP3tag, but adds an online search functionality to grab metadata from providers such as iTunes, Amazon and others, as well as an autotag feature. This can be useful to people with enormous media collections where the time saved manually tagging justifies the price.
MetaX is a user-friendly tagging solution. However, it is proprietary and paid ($10). It features much the same core features as MP3tag, but adds an online search functionality to grab metadata from providers such as iTunes, Amazon and others, as well as an autotag feature. This can be useful to people with enormous media collections where the time saved manually tagging justifies the price.


== Mac ==


* [https://griff.github.io/metaz/ MetaZ] is a free and open source MP4 metadata lookup and editor for Mac OS.


== Mac ==
== Linux ==
;MP4 tagging:
 
* [https://griff.github.io/metaz/ MetaZ] is a free and open source metadata lookup and editor for Mac OS.
* mp4v2


== Linux ==
== Cross-platform ==


= A note on iTunes =
* exiftool
Apple, in their wisdom, have created a subset of tags that are strictly speaking only meant for use with iTunes. However, most tagging software can read and write these iTunes tags. These tags are also quite useful But will not work with Kodi. Tags include the ability to store Cast (actors), Screenwriter and Director information, as well as age restriction data such as MPAA ratings.


The important point to note here is that just because your tagging software allows you to add these does not mean they will be used. After all, they are unstandardized and were created by Apple solely for use with iTunes and iOS/macOS devices.
== A note on iTunes ==
Apple, in their wisdom, have created a subset of MP4 tags that are strictly speaking only meant for use with iTunes. However, most tagging software can read and write these iTunes tags. These tags are also quite useful but some will not work with Kodi. Tags include the ability to store Cast (actors), Screenwriter and Director information, as well as age restriction data such as MPAA ratings.


The important point to note here is that just because your tagging software allows you to add these does not mean they will be used by Kodi.


= Core Tags =
= Core Tags =


While there are an absolute myriad of tags that one can use, many, if not most of these are unnecessary for video files. Remember that MP4 tags have to have fields for everything - TV shows, movies, music videos and Music! We do not want to populate tags related to music (Such as Artist) in a movie file! As such here are some of the most critical tags for video (TV show and Movie) files.
While there are an absolute myriad of tags that one can use, many, if not most of these are unnecessary for video files. Remember that MP4 tags have to have fields for everything - TV shows, movies, music videos, music, audiobooks, and even images! We usually do not want to populate tags related to music (such as Artist) in a movie file. As such here are some of the most critical tags for video (TV show and Movie) files.


== Title ==
== Title ==
It seems that Kodi will not import a media file without a valid title in the metadata tag. This makes it the most critical tag of all.
Kodi will not import a media file without a valid ''Title'' in the metadata tag. This makes it the most critical tag of all. An exception is made for MKV files which have an <code>IMDBURL</code> or <code>TMDBURL</code> metatag.
 
Title differs from filename - I may have a file called Blade_Runner_2049_(2017)Withalotofexcessinformation.mp4, But the title value can simply be "Blade Runner 2049". Kodi will then display "Blade Runner 2049".


Title also differs from Filename - I may have a file called Blade_Runner_2049_(2017)Withalotofexcessinformation.mp4, But the title value can simply be "Blade Runner 2049". Kodi will then display "Blade Runner 2049).
Beware that many people who distribute video files do not care much for proper metadata within the file even if they are shipping proper NFO or XML files with them. Regardless, their files may still have tags, but with rubbish or spam content. This is the reason why Kodi defaults to not use embedded tags in video files.


== Description ==
== Description ==
Line 90: Line 76:


== Cover/Picture ==
== Cover/Picture ==
Probably the singular greatest benefit to tags is being able to set your own cover image. Don't like the standard cover? Use the collectors Edition or Digital Download cover.
For some users, the singular greatest benefit to tags is being able to set your own cover image. Don't like the standard cover? Use the Collectors Edition or Digital Download cover.


== TV Show Specific Tags ==
== TV Show Specific Tags ==
There are three more tags that should be filled in for TV Shows: Show, Season and Episode Number. At the moment these tags do not seem to be of any practical use in Kodi, but should nevertheless be filled out as this may change.
There are three more tags that should be filled in for TV Shows: '''Show''' (<code>tvsh</code>), numeric '''Season''' (<code>tvsn</code>) and '''Episode Number''' (<code>tves</code>) and the unique '''Production Code''' (<code>tven</code>).  
 
At the moment these tags do not seem to be of any practical use in Kodi, but should nevertheless be filled out as this may change.


= Supported Tags =
= Supported Tags =


{{red|are the tags in this table for both mkv and mp4?}}
Kodi relies on FFmpeg libraries to import MP4, MKV and AVI metadata. The [https://wiki.multimedia.cx/index.php/FFmpeg_Metadata documentation in the Multimedia.cx wiki] is not always up to date, but is correct in general. For proper details, one needs to inspect the [https://www.ffmpeg.org/doxygen/4.0/movenc_8c_source.html <code>mov_write_****_tag()</code> functions in the FFmpeg source code].


Both MP4 and MKV tags are supported, although they use fundamentally different methods of encoding metadata.
== Overview and Comparison ==


{{red|Is it ok to remove the music related tags? Are they separated accurately?}}
{{notice|Kodi variables shown in parentheses below are not supported at the moment, but if they are in the future, these are the most likely mappings.}}
 
{| class="wikitable prettytable sortable"
 
|+ Tag field mapping table
 
! Kodi !! FFmpeg !! MP4 box / atom !! AVI FourCC !! [https://help.mp3tag.de/main_tags.html Mp3tag] !! mp4tags / mp4v2 CLI !! Description
{{red|I cannot find these video related tags in mp3tag}}
|-
 
| || <code>album_artist</code> || <code>aART</code> ||  || <code>ALBUMARTIST</code> || <code>-R</code>, <code>-albumartist</code> || album artist
To get to all the juicy video file related tags in mp3tag, right click on your video file and select "Extended Tags". From here one can see all the tags currently in a file. Add new ones by clicking on the Add button, selecting a Field (what tag to edit" and entering a value. The most critical one in all cases is TITLE, as it seems Kodi will not add a media file if this core tag is missing (and there is no .nfo file).
|-
 
| '''''Album''''' || <code>album</code> || <code>©alb</code> || (<code>IPRD</code>) || <code>ALBUM</code> || <code>-A</code>, <code>-album</code> || album title
This will also allow you to add the cover artwork.
|-
 
| || <code title="read">sort_album</code> (<code title="write">album-sort</code>) || <code>soal</code> ||  || <code>ALBUMSORT</code> ||  ||
{{red|What format is this- id3, APE, Generic, MP4, other?}}
|-
 
| '''''Artist''''' || <code>artist</code> || <code>©art</code>, <code>©ART</code> || (<code>IART</code>) || <code>ARTIST</code> || <code>-a</code>, <code>-artist</code> || artist information
MP4 files use "moov" atoms embedded within the file. These are the same ones used in AAC audio files (such as m4a).
|-
 
|  || <code title="read">artist</code> (<code title="write">author</code>) || <code>©aut</code> ||  ||  ||  || author information
{{red|IMDBURL/TMDBURL is this one tag or two separate tags?}}
|-
 
| || <code title="read">sort_artist</code> (<code title="write">artist-sort</code>) || <code>soar</code> ||  || <code>ARTISTSORT</code> ||  ||
 
|-
 
| || <code>comment</code> || <code>©cmt</code> (<code title="write-only">©des</code>) || (<code>ICMT</code>) || <code>COMMENT</code> || <code>-c</code>, <code>-comment</code> || general comment
 
|-
{| class="prettytable"
| || <code>compilation</code> || <code>cpil</code> ||  || <code>COMPILATION</code> ||  ||
|-
| '''''WritingCredits''''' (split at slashes) || <code>composer</code> || <code>©wrt</code> ||  || <code>COMPOSER</code> || <code>-w</code>, <code>-writer</code> || composer information
|-
| || <code>copyright</code> || <code>©cpy</code> (<code>cprt</code>) || (<code>ICOP</code>) || <code>COPYRIGHT</code> || <code>-C</code>, <code>-copyright</code> || copyright information
|-
| || <code>creation_time</code> ||  ||  || <code>ENCODINGTIME</code> ||  ||
|-
| '''''Year''''' || <code title="read">date</code> || <code>©day</code> || <code>ICRD</code> || <code>RELEASETIME</code> ||  ||
|-
| (''Premiered'') || <code title="write">year</code> || <code>©day</code> ||  || <code>YEAR</code> || <code>-y</code>, <code>-year</code> || release date
|-
| || <code>encoded_by</code> ||  || (<code>ITCH</code>) || <code>ENCODEDBY</code> || <code>-e</code>, <code>-encodedby</code> || name of the person or company who encoded the file
|-
| || <code>encoder</code> || <code>©too</code> (<code>©swr</code>) || (<code>ISFT</code>) || <code>ENCODERSETTINGS</code> || <code>-E</code>, <code>-tool</code> || software used for encoding
|-
| (''ProductionCode'') || <code>episode_id</code> || <code>tven</code> ||  || <code>TVEPISODEID</code> || <code>-o</code>, <code>-episodeid</code> || TV episode ID
|-
|-
! colspan="4" style="background-color:#a1f5e4;" | Video File Tags
| || <code>episode_sort</code> || <code>tves</code> ||  || <code>TVEPISODE</code> || <code>-M</code>, <code>-episode</code> || episode number
|+
! style="background-color:#f5f5a1; text-align:left; width:050px" | ?
! style="background-color:#f5f5a1; text-align:left; width:100px" | Tag
! style="background-color:#f5f5a1; text-align:left; width:050px" | Type
! style="background-color:#f5f5a1; text-align:left; width:450px" | Description
|-
|-
| -B
| || <code>season_number</code> || <code>tvsn</code> ||  || <code>TVSEASON</code> || <code>-n</code>, <code>-season</code> || season number
| -podcast
| NUM
| Set the podcast flag
|-
|-
| -c
| '''''Genre''''' (split at slashes) || <code>genre</code> || <code>©gen</code>, <code>gnre</code> || (<code>IGNR</code>) || <code>GENRE</code> || <code>-g</code>, <code>-genre</code> / <code>-j</code>, <code>-genreid</code> || genre name / ID
| -comment
| STR
| Set a general comment
|-
| -C
| -copyright
| STR
| Set the copyright information
|-  
| -e
| -encodedby
| STR
| Set the name of the person or company who encoded the file
|-
|-
| -E
| (''Set'') || <code>grouping</code> || <code>©grp</code> ||  || <code>CONTENTGROUP</code> || <code>-G</code>, <code>-grouping</code> || grouping name, set
| -tool
| STR
| Set the software used for encoding
|-
|-
| -g
| || <code>hd_video</code> || <code>hdvd</code> ||  || <code>ITUNESHDVIDEO</code> || <code>-H</code>, <code>-hdvideo</code> || HD flag (0 = SD, 1 = 720p, 2 = 1080p/i Full HD, 3 = 2160p UHD)
| -genre
| STR
| Set the genre name
|-
|-
| -G
| || <code>language</code> ||  || (<code>ILNG</code>) || <code>LANGUAGE</code> ||  || main/original spoken/displayed language
| -grouping
| STR
| Set the grouping name
|-
|-
| -H
| || <code>lyrics</code> || <code>©lyr</code> ||  || <code>UNSYNCEDLYRICS</code> || <code>-L</code>, <code>-lyrics</code> || unsynchronized lyrics
| -hdvideo
| NUM
| Set the HD flag (1\0)
|-
|-
| -i
| || <code>media_type</code> || <code>stik</code> ||  || <code>ITUNESMEDIATYPE</code> || <code>-i</code>, <code>-type</code> || Media Type (TV Show, Movie, Music, Audiobook ...)
| -type
| STR
| Set the Media Type(tvshow, movie, music, ...)
|-
|-
| -I
| (''Studio'') || <code>network</code> || <code>tvnn</code> ||  || <code>TVNETWORK</code> || <code>-N</code>, <code>-network</code> || TV network, channel, station
| -contentid
| NUM
| Set the content ID
|-
|-
| -j
| (''Studio'') || <code>publisher</code> ||  ||  || <code>PUBLISHER</code> ||  || publisher
| -genreid
| NUM
| Set the genre ID
|-
|-
| -l
| || <code>producer</code> || <code>©prd</code> ||  ||  ||  || producer
| -longdesc
| STR
| Set the long description
|-
|-
| -m
| (''Director'') || <code>performer</code> || <code>©con</code> ||  || <code>CONDUCTOR</code> ||  || conductor, performer
| -description
| STR
| Set the short description
|-
|-
| -M
| (''Director'') || <code title="read-only">composer</code> || <code>©com</code> ||  || ||  || composer
| -episode
| NUM
| Set the episode number
|-
|-
| -n
| (''Director'') || <code title="read-only">director</code> || <code>©dir</code> || <code>DIRECTOR</code> || ||  || director
| -season
| NUM
| Set the season number
|-
|-
| -N
| (''ShowTitle'') || <code>show</code> || <code>tvsh</code> ||  || <code>TVSHOW</code> || <code>-S</code>, <code>-show</code> || TV show
| -network
| STR
| Set the TV network
|-
|-
| -o
| '''''Plot''''' || <code>synopsis</code> || <code>ldes</code> ||  || <code>PODCASTDESC</code> || <code>-m</code>, <code>-description</code> || short description
| -episodeid
| STR
| Set the TV episode ID
|-
|-
| -O
| '''''PlotOutline''''', (''Overview'') || <code>description</code> || <code>desc</code> ||  || <code>DESCRIPTION</code> || <code>-l</code>, <code>-longdesc</code> || long description
| -category
| STR
| Set the category
|-
|-
| -p
| '''''Title''''' || <code>title</code> || <code>©nam</code> || <code>INAM</code> || <code>TITLE</code> || <code>-s</code>, <code>-song</code> || song title, track name
| -playlistid
| NUM
| Set the playlist ID
|-
|-
| -P
| (''SortTitle'') || <code title="read">sort_name</code> (<code title="write">title-sort</code>) || <code>sonm</code> ||  || <code>TITLESORT</code> ||  ||  
| -picture
| PTH
| Set the picture as a .png
|-
|-
| -r
| (''TagLine'') || <code>subtitle</code> || <code>©st3</code> ||  || (<code>SUBTITLE</code>) ||  ||
| -remove
| STR
| Remove tags by code (e.g. "-r cs" removes the comment and song tags)
|-
|-
| -S
| '''''Track''''' || <code>track</code> || <code>trkn</code> (<code>©trk</code>) || (<code>IPRT</code>) || <code>TRACK</code> || <code>-t</code>, <code>-track</code> / <code>-T</code>, <code>-tracks</code> || track number / number of tracks
| -show
| STR
| Set the TV show
|-
|-
| -X
| || <code>disc</code> || <code>disk</code> ||  || <code>DISCNUMBER</code> || <code>-d</code>, <code>-disk</code> / <code>-D</code>, <code>-disks</code> || disc number / number of discs
| -rating
| STR
| Set the Rating(none, clean, explicit)
|-  
| -y
| -year
| NUM
| Set the release date
|-
|-
|
| (''Rating'') || <code>rating</code> || <code>rtng</code> ||  || <code>ITUNESADVISORY</code> || <code>-X</code>, <code>-rating</code> || Rating (0 = none, 1 = clean, 2 = explicit)
| -help
|
| Display this help text and exit
|-
|-
|
| (''Country'') || <code>location</code> || <code>©xyz</code> (<code>loci</code>) ||  ||  ||  || GPS coordinates
| -version
|
| Display version information and exit
|-
|-
! colspan="4" style="background-color:#a1f5e4;" | Music File Tags- TO BE REMOVED FROM LIST? or is it used for Music Videos?
| (''Trailer'') || || ||  ||  ||  ||  
|+
! style="background-color:#f5f5a1; text-align:left; width:050px" | ?
! style="background-color:#f5f5a1; text-align:left; width:100px" | Tag
! style="background-color:#f5f5a1; text-align:left; width:050px" | Type
! style="background-color:#f5f5a1; text-align:left; width:400px" | Description
|-
|-
| -A
| (''PictureURL'') || ||  ||  ||  ||  ||  
| -album
| STR
| Set the album title
|-
|-
| -a
| (''Votes'') || ||  ||  ||  ||  ||  
| -artist
| STR
| Set the artist information
|-
|-
| -b
| (''UniqueIDs'') || ||  ||  ||  ||  ||
| -tempo
| NUM
| Set the tempo (beats per minute)
|-
|-
| -d
| (''Tags'') || (<code>keywords</code>) || (<code>keyw</code> (<code>©key</code>)) ||  ||  ||  || tags, keywords
| -disk
| NUM
| Set the disk number
|-
|-
| -D
| (''OriginalTitle'') || ||  ||  ||  ||  ||
| -disks
| NUM
| Set the number of disks
|-
|-
| -L
| (''EpisodeGuide'') || ||  ||  ||  ||  ||
| -lyrics
| NUM
| Set the lyrics
|-
|-
| -R
| (''Status'') || ||  ||  ||  ||  ||
| -albumartist
| STR
| Set the album artist
|-
|-
| -s
| (''ShowLink'') || <code>URL</code> || <code>©url</code> ||  ||  ||  ||  
| -song
| STR
| Set the song title
|-
|-
| -t
| (''NamedSeasons'') || ||  ||  ||  ||  || array
| -track
| NUM
| Set the track number
|-
|-
| -T
| || <code>podcast</code> || <code>pcst</code> ||  || <code>PODCAST</code> || <code>-B</code>, <code>-podcast</code> || podcast flag (0/1)
| -tracks
| NUM
| Set the number of tracks
|-
|-
| -w
| || <code>category</code> || <code>catg</code> ||  || <code>PODCASTCATEGORY</code> || <code>-O</code>, <code>-category</code> || category
| -writer
| STR
| Set the composer information
|-
|-
| -z
| (''UniqueID'') || || <code>cnID</code> ||  || <code>ITUNESCATALOGID</code> || <code>-I</code>, <code>-contentid</code>? || content ID
| -artistid
| NUM
| Set the artist ID
|-
|-
| -Z
| (''UniqueID'') || <code>episode_uid</code> || <code>egid</code> ||  || <code>PODCASTID</code> || <code>-I</code>, <code>-contentid</code>? || content ID
| -composerid
| NUM
| Set the composer ID
|}
|}
<!--
mp4tags/mp4v2 CLI:
| || || (<code>covr</code>, <code>thmb</code>) || || || <code>-P</code>, <code>-picture</code> || picture as a .png, Cover
| || || <code>tmpo</code> || || <code>BPM</code> || <code>-b</code>, <code>-tempo</code> || tempo (beats per minute)
| || || plID? || || || <code>-p</code>, <code>-playlistid</code> || playlist ID
| || ||  || || || <code>-z</code>, <code>-artistid</code> || artist ID
| || ||  || || || <code>-Z</code>, <code>-composerid</code> || composer ID
-->
== MP4 tag options ==
For MP4 tags, Kodi reads ''Title'' <code>©nam</code>, ''Writing Credits'' <code>©wrt</code>, ''Plot'' <code>ldes</code>, ''Plot Outline'' <code>desc</code>, ''Year'' <code>©day</code>, ''Album'' <code>©alb</code>, ''Artist'' <code>©art</code>/<code>©ART</code> and ''Track'' <code>trkn</code>/<code>©trk</code> information if available.
<!--
FFmpeg read MOV:
* <code>akID</code> "account_type"
* <code>apID</code> "account_id"
* <code>pgap</code> "gapless_playback"
* <code>purd</code> "purchase_date"
* <code>©ed1</code> "edit_date"
* <code>soaa</code> "sort_album_artist"
* <code>soco</code> "sort_composer"
* <code>sosn</code> "sort_show" 
* <code>©chp</code> "chapter" 
* <code>manu</code>, <code title="MOV write">©mak</code> "make"   
* <code>modl</code>, <code title="MOV write">©mod</code> "model"   
* <code>©enc</code> "encoder"  (<code>@PRM</code> "premiere_version", <code>@PRQ</code> "quicktime_version")
* <code>©hst</code> "host_computer"
* <code>©req</code> "playback_requirements"
* <code>©dis</code> "disclaimer"
* <code>©inf</code> "comment" 
* <code>©wrn</code> "warning" 
* <code>©ope</code> "original_artist"
* <code>©src</code> "original_source"
* <code>©fmt</code> "original_format"
* <code>©prf</code> "performers"
* <code>FIRM</code> "firmware"
FFmpeg 3GPP write:
* <code>perf</code> artist
* <code>titl</code> title
* <code>auth</code> author
* <code>gnre</code> genre
* <code>dscp</code> comment
* <code>albm</code> album
* <code>cprt</code> copyright
* <code>yrrc</code> date
-->
== MKV tag options ==
MKV tagging currently does mostly ignore the Matroska tagging specification to fill library info. Instead, a Kodi standard NFO file can be ''embedded'' into MKV files.


*for mkv you can add an attachment named kodi-metadata. this is an an embedded .nfo file
* An attachment named '''kodi-metadata''' will be scanned as an embedded .nfo file
*for mkv you can add an attachment named kodi-override-metadata. if combined with specifying IMDB/TMDB url, you get a url nfo. if alone, you get an override nfo
* An attachment named '''kodi-override-metadata''' will be scanned as a url nfo if combined with specifying IMDB/TMDB url. if alone, you get an override nfo


The only textual tags supported in MKV fields as of v18.6 are (case-insensitive) ''Title'' = <code>title</code>, ''Director'' = <code>director</code> (multiple entries may be separated by a forward slash) and ''Year'' = <code>date_released</code>.


== AVI tag options ==


= Artwork =
As of v18.6, Kodi only recognizes ''Title'' and ''Year'' variables from AVI tags.<ref name="VideoTagLoaderFFmpeg.cpp">[https://github.com/xbmc/xbmc/blob/master/xbmc/video/tags/VideoTagLoaderFFmpeg.cpp Kodi source code of <code>VideoTagLoaderFFmpeg.cpp</code>]</ref>
for mkv you can have embedded thumbs. currently limited to:
    - 'small_cover.png' or 'small_jover.jpg' for thumbnails (as specified on matroska.org)
    - 'cover.png' or 'cover.jpg' for posters (as specified on matroska.org)
    - 'fanart.png' or 'fanart.jpg' for fanart
 
MP4 artwork is supported.


== FAQ ==


; {{red|I cannot find these video related tags in mp3tag}}
: To get to all the juicy video file related tags in mp3tag, right click on your video file and select "Extended Tags". From here one can see all the tags currently in a file. Add new ones by clicking on the Add button, selecting a Field (what tag to edit) and entering a value. The most critical one in all cases is TITLE, as it seems Kodi will not add a media file if this core tag is missing (and there is no .nfo file).
: This will also allow you to add the cover artwork.
; {{red|What format is this- id3, APE, Generic, MP4, other?}}
: MP4 files use "moov" atoms embedded within the file. These are the same ones used in AAC audio files (such as m4a).
; {{red|IMDBURL/TMDBURL is this one tag or two separate tags?}}
: Two separate ones, only supported within Matroska (MKV) files currently.


= Artwork =
For MKV you can have embedded images. currently limited to:
* 'small_cover.png' or 'small_cover.jpg' for thumb
* 'cover.png' or 'cover.jpg' for poster
* 'fanart.png' or 'fanart.jpg' for fanart
 
'poster' images can be embedded in MP4 files.


{{top}}
{{top}}
Line 354: Line 286:


{{updated|18}}
{{updated|18}}
[[Category:FAQ]]
[[Category:Index]]
[[Category:Index]]
[[Category:How-to]]
[[Category:How-to]]
[[Category:Guides]]
[[Category:Guides]]
[[Category:Manual]]
[[Category:Manual]]
[[Category:Karellen]]
[[Category:Video library]]
[[Category:Video library]]
[[Category:General topics]]
[[Category:General topics]]
[[Category:First time user]]
[[Category:First time user]]
[[Category:Quick Start Guide]]
[[Category:Quick Start Guide]]

Latest revision as of 19:53, 22 February 2023

Home icon grey.png   ▶ Video library ▶ Video file tagging
Incomplete.png INCOMPLETE:
This page or section is incomplete. Please add information or correct uncertain data which is marked with a ?
Emblem-important-yellow.png NOTICE:
This page describes an alternative way of adding movies to the library that is not dependent on file names or online scrapers.

Kodi v18 Leia introduces support for embedded video tags using *.mkv and *.mp4 video files. *.avi support is available since v18.x. They are similar in principle to the tags saved in audio files. Only limited support for video tags is available at this time.

Benefits of embedded video tags

There are multiple reasons why one would want to use this feature: Media may already contain useful metadata (the reverse however is also true - many files contain "junk" metadata, hence why the feature defaults to off). It gives one more control over the metadata than scrapers do (as scrapers may misclassify media and pull the wrong data). It does away with the need to have NFO files. Since metadata travels with the media file, there is no longer a need for potentially thousands of these smaller files and can make directory management even easier. Using ultra-high resolution artwork/cover images that looks nicer on newer HD displays. (Pretty pictures!)

How does it change/differ from the old model?

Kodi has two options for metadata import: using an online scraper or using local information, traditionally in the form of .nfo files. Local tag reading is bundled into the "Local Information" arm, as logically, metadata is still local (i.e not network-drawn) information. Thus, one can still use a combination of .nfo files and embedded information if they choose "Local Information" rather than to use a scraper.

It is important to note however that .nfo files will override embedded information. Not all of Kodi's NFO features are supported by embedded metadata yet, so many users may wish to still use the NFO method. (https://forum.kodi.tv/showthread.php?tid=326340)

Settings

Kodi settings have the option to enable or disable the reading of video file tags at Settings > Media Settings > Videos > Use video tags. The default setting is disabled.

This page assumes this setting has been enabled.

Folder & File Structure

The use of Video File Tags does not absolve you from using the correct Folder and File structure for Movies, TV Shows and Music Videos as detailed in the previous pages.

Tagging

Stop hand.png These pages are maintained by the community and should not be considered an endorsement or recommendation. *


Note: User-friendly options for adding and editing embedded metadata may be lacking for your given platform. Be prepared for challenges when going down this path.

Windows

MP3tag is a Windows-based metadata editor for many different files and tag types, including MP4 and MKV (despite what it's name may suggest). While somewhat complex, it provides very fine-grained control over tagging, and is a worthwhile asset in any media management library.

MetaX is a user-friendly tagging solution. However, it is proprietary and paid ($10). It features much the same core features as MP3tag, but adds an online search functionality to grab metadata from providers such as iTunes, Amazon and others, as well as an autotag feature. This can be useful to people with enormous media collections where the time saved manually tagging justifies the price.

Mac

  • MetaZ is a free and open source MP4 metadata lookup and editor for Mac OS.

Linux

  • mp4v2

Cross-platform

  • exiftool

A note on iTunes

Apple, in their wisdom, have created a subset of MP4 tags that are strictly speaking only meant for use with iTunes. However, most tagging software can read and write these iTunes tags. These tags are also quite useful but some will not work with Kodi. Tags include the ability to store Cast (actors), Screenwriter and Director information, as well as age restriction data such as MPAA ratings.

The important point to note here is that just because your tagging software allows you to add these does not mean they will be used by Kodi.

Core Tags

While there are an absolute myriad of tags that one can use, many, if not most of these are unnecessary for video files. Remember that MP4 tags have to have fields for everything - TV shows, movies, music videos, music, audiobooks, and even images! We usually do not want to populate tags related to music (such as Artist) in a movie file. As such here are some of the most critical tags for video (TV show and Movie) files.

Title

Kodi will not import a media file without a valid Title in the metadata tag. This makes it the most critical tag of all. An exception is made for MKV files which have an IMDBURL or TMDBURL metatag.

Title differs from filename - I may have a file called Blade_Runner_2049_(2017)Withalotofexcessinformation.mp4, But the title value can simply be "Blade Runner 2049". Kodi will then display "Blade Runner 2049".

Beware that many people who distribute video files do not care much for proper metadata within the file even if they are shipping proper NFO or XML files with them. Regardless, their files may still have tags, but with rubbish or spam content. This is the reason why Kodi defaults to not use embedded tags in video files.

Description

This describes the movie/TV Show. A snippet from iTunes' description of Blade Runner 2049 is as follows: "Thirty years after the events of the first film, a new blade runner, LAPD Officer K (Ryan Gosling), unearths a long buried secret that has the potential to plunge what’s left of society into chaos."

Descriptions thus actually describe the character or basic plot of a movie or TV Show. These will be displayed in Kodi when the file is selected.

Best practice at this point seems to be to mirror the Long Description and Short Description, as there does not seem to be any practical distinction between the two.

When using this tag with TV Shows, every episode can be individually described according to the plot of that particular episode.

Content Type

In MP4 there should be four choices: Music, Music Video, Movie and TV Show. The choice does not seem to matter at this point as Kodi can not distinguish files based on this tag, but rather relies on the manual setting when the directory was added. It might be useful to set this properly when tagging however, as a future change to allow Kodi to distinguish these tags may prove invaluable.

Cover/Picture

For some users, the singular greatest benefit to tags is being able to set your own cover image. Don't like the standard cover? Use the Collectors Edition or Digital Download cover.

TV Show Specific Tags

There are three more tags that should be filled in for TV Shows: Show (tvsh), numeric Season (tvsn) and Episode Number (tves) and the unique Production Code (tven). At the moment these tags do not seem to be of any practical use in Kodi, but should nevertheless be filled out as this may change.

Supported Tags

Kodi relies on FFmpeg libraries to import MP4, MKV and AVI metadata. The documentation in the Multimedia.cx wiki is not always up to date, but is correct in general. For proper details, one needs to inspect the mov_write_****_tag() functions in the FFmpeg source code.

Overview and Comparison

Emblem-important-yellow.png NOTICE:
Kodi variables shown in parentheses below are not supported at the moment, but if they are in the future, these are the most likely mappings.
Tag field mapping table
Kodi FFmpeg MP4 box / atom AVI FourCC Mp3tag mp4tags / mp4v2 CLI Description
album_artist aART ALBUMARTIST -R, -albumartist album artist
Album album ©alb (IPRD) ALBUM -A, -album album title
sort_album (album-sort) soal ALBUMSORT
Artist artist ©art, ©ART (IART) ARTIST -a, -artist artist information
artist (author) ©aut author information
sort_artist (artist-sort) soar ARTISTSORT
comment ©cmt (©des) (ICMT) COMMENT -c, -comment general comment
compilation cpil COMPILATION
WritingCredits (split at slashes) composer ©wrt COMPOSER -w, -writer composer information
copyright ©cpy (cprt) (ICOP) COPYRIGHT -C, -copyright copyright information
creation_time ENCODINGTIME
Year date ©day ICRD RELEASETIME
(Premiered) year ©day YEAR -y, -year release date
encoded_by (ITCH) ENCODEDBY -e, -encodedby name of the person or company who encoded the file
encoder ©too (©swr) (ISFT) ENCODERSETTINGS -E, -tool software used for encoding
(ProductionCode) episode_id tven TVEPISODEID -o, -episodeid TV episode ID
episode_sort tves TVEPISODE -M, -episode episode number
season_number tvsn TVSEASON -n, -season season number
Genre (split at slashes) genre ©gen, gnre (IGNR) GENRE -g, -genre / -j, -genreid genre name / ID
(Set) grouping ©grp CONTENTGROUP -G, -grouping grouping name, set
hd_video hdvd ITUNESHDVIDEO -H, -hdvideo HD flag (0 = SD, 1 = 720p, 2 = 1080p/i Full HD, 3 = 2160p UHD)
language (ILNG) LANGUAGE main/original spoken/displayed language
lyrics ©lyr UNSYNCEDLYRICS -L, -lyrics unsynchronized lyrics
media_type stik ITUNESMEDIATYPE -i, -type Media Type (TV Show, Movie, Music, Audiobook ...)
(Studio) network tvnn TVNETWORK -N, -network TV network, channel, station
(Studio) publisher PUBLISHER publisher
producer ©prd producer
(Director) performer ©con CONDUCTOR conductor, performer
(Director) composer ©com composer
(Director) director ©dir DIRECTOR director
(ShowTitle) show tvsh TVSHOW -S, -show TV show
Plot synopsis ldes PODCASTDESC -m, -description short description
PlotOutline, (Overview) description desc DESCRIPTION -l, -longdesc long description
Title title ©nam INAM TITLE -s, -song song title, track name
(SortTitle) sort_name (title-sort) sonm TITLESORT
(TagLine) subtitle ©st3 (SUBTITLE)
Track track trkn (©trk) (IPRT) TRACK -t, -track / -T, -tracks track number / number of tracks
disc disk DISCNUMBER -d, -disk / -D, -disks disc number / number of discs
(Rating) rating rtng ITUNESADVISORY -X, -rating Rating (0 = none, 1 = clean, 2 = explicit)
(Country) location ©xyz (loci) GPS coordinates
(Trailer)
(PictureURL)
(Votes)
(UniqueIDs)
(Tags) (keywords) (keyw (©key)) tags, keywords
(OriginalTitle)
(EpisodeGuide)
(Status)
(ShowLink) URL ©url
(NamedSeasons) array
podcast pcst PODCAST -B, -podcast podcast flag (0/1)
category catg PODCASTCATEGORY -O, -category category
(UniqueID) cnID ITUNESCATALOGID -I, -contentid? content ID
(UniqueID) episode_uid egid PODCASTID -I, -contentid? content ID

MP4 tag options

For MP4 tags, Kodi reads Title ©nam, Writing Credits ©wrt, Plot ldes, Plot Outline desc, Year ©day, Album ©alb, Artist ©art/©ART and Track trkn/©trk information if available.

MKV tag options

MKV tagging currently does mostly ignore the Matroska tagging specification to fill library info. Instead, a Kodi standard NFO file can be embedded into MKV files.

  • An attachment named kodi-metadata will be scanned as an embedded .nfo file
  • An attachment named kodi-override-metadata will be scanned as a url nfo if combined with specifying IMDB/TMDB url. if alone, you get an override nfo

The only textual tags supported in MKV fields as of v18.6 are (case-insensitive) Title = title, Director = director (multiple entries may be separated by a forward slash) and Year = date_released.

AVI tag options

As of v18.6, Kodi only recognizes Title and Year variables from AVI tags.[1]

FAQ

I cannot find these video related tags in mp3tag
To get to all the juicy video file related tags in mp3tag, right click on your video file and select "Extended Tags". From here one can see all the tags currently in a file. Add new ones by clicking on the Add button, selecting a Field (what tag to edit) and entering a value. The most critical one in all cases is TITLE, as it seems Kodi will not add a media file if this core tag is missing (and there is no .nfo file).
This will also allow you to add the cover artwork.
What format is this- id3, APE, Generic, MP4, other?
MP4 files use "moov" atoms embedded within the file. These are the same ones used in AAC audio files (such as m4a).
IMDBURL/TMDBURL is this one tag or two separate tags?
Two separate ones, only supported within Matroska (MKV) files currently.

Artwork

For MKV you can have embedded images. currently limited to:

  • 'small_cover.png' or 'small_cover.jpg' for thumb
  • 'cover.png' or 'cover.jpg' for poster
  • 'fanart.png' or 'fanart.jpg' for fanart

'poster' images can be embedded in MP4 files.

Return to top


Next step: Add Source & Scrape