I’ve made a suite of .src’s built on @Sweder and @RobertM's scripts that can handle singular movies or multiple TV show episodes in a season.
The main advantage this has over external files and a complete reliance on scrapers is that you can store all the metadata you want directly into a file to create customised videos in media players, for personal organisation and as part of your own Mp3tag workflow (filenames, folders, .nfo's etc.)
I’ve tested it on Windows with .mp4’s on iTunes using ITUN/ITUNES tags and .mkv’s on Kodi which reads TMDB and TMDBURL tags for enabling scraping facilities.
Installation and Maintenance
For new users:
Please refer to this topic on how to navigate to Mp3tag’s configuration folder.
-
There's three different files that make up a web/tag source:
- .src’s are the basic files that lets you search for data then adjust it into usable tags for your files.
- .inc contains extra code that is shared across .src’s to save space.
- .settings lets you configure a web source with options.
-
From your TMDB zip file, copy over
TMDB#Results.incandTMDB#Settings.settingsinto the sources folder. Please do not rename or remove these as they are essential for the web source to work. -
From your TMDB zip file, open the Search folder; you’ll find
TMDB#Search - Movie.src,TMDB#Search - Multi.srcandTMDB#Search - TV.src.Copy all of these .src’s into the into the sources folder. -
This requires a TMDB API key, though registration is very easy. You then need to paste it into every .src file you use as well as set your default language for searches.
- Open each .src you have copied over using any basic text editor (Right click → Open with… → Notepad).
- In each .src, find
!!!YOUR_API_KEY!!!in[IndexUrl]and replace it with your API key (32 characters long). - You can also change your default language in each .src which appears in your search prompt. Find
||Language||en-GB||&language=%s||in[SearchBy]and replaceen-GBwith a "language-REGION" of your choice, e.g.de-DE,en-US, evenit-FR.
-
Now, you are able to try out the source in Mp3tag from Tag Sources in the toolbar! Try it with your favourite movie or TV show using the appropriate .src. Have a look at the next section Files for what other .src’s are available in case you ever require more precise features.
For current users:
-
Whenever a file is updated as shown in the Changelog or README.txt, you’ll again need to paste your API key/default language/any personal modifications to the newer versions.
-
If you know how to develop in the web sources framework, you are welcome to edit or reverse-engineer all files as you wish (edit tag labels, add/remove functionality, add settings translations etc.). For personal use and learning, go ahead!
-
I (@arb) am currently maintaining this source so please be fair: post any changes or updates you've made to the scripts in this topic to keep it all together or message me privately. Credit will always be given in the changelog to everyone with work added into a release and help given where possible.
Files
Essential
Results generates metadata from queries made by most .src’s.
Settings saves your preferences between all .src’s and shows a tooltip for more information when you hover your cursor over a label.
Reminder: Both files must be saved in the sources folder and kept the same name for the script to work.
Search
These .src's are your starting points to find content and grab metadata from possible results:
- Movie - finds movies, can filter by a specific year.
- TV - finds TV shows by season, can filter specific seasons and episodes.
- Multi - finds movies and TV shows, can filter seasons/episodes but not by year.
ID
Once you've tagged a file with TMDB or TMDBURL, this will retrieve its data directly.
Get
These will retrieve specific metadata directly from a TMDB ID:
- Alternative Titles - movie/TV show titles changed between regions or releases, also includes translations and romaji.
- Content Ratings - once set up in Settings, returns ratings for content based on your region, can also apply
ITUNESADVISORY/EXPLICITwhen required. - TV Seasons - all seasons available for a TV show, can filter by episodes.
- TV Episodes - all episodes available for a TV show’s season.
- Posters and Stills - all posters for movies, TV shows and seasons, stills for episodes. Best used for cover artwork.
- Backdrops - all wallpapers for movies, TV shows and seasons for software UI’s.
- Logos - all logos for movies and TV shows in several formats including .svg which can be preview online or saved as .png.
External ID
These are alternatives to TMDB and TMDBURL:
- IMDB - uses
IMDBandIMDBURLfor movies and TV shows. - TVDB - uses
TVDBfor TV shows. - Wikidata - uses
WIKIDATAfor movies and TV shows.
Check
These let you quickly look up TMDB configurations:
- Content Ratings - Movie - all ratings for a searched/default region.
- Content Ratings - TV - all ratings for a searched/default region.
- Languages - all supported languages, not all are widely used.
- Regions - all supported regions, not all are widely used.
- Primary Translations - the most mainly supported language-REGION combinations.
Concepts
These are simply tests to push the capabilities of web sources:
- Search or ID - a combination of Search - Multi and ID; it prioritises using ID over a search term if both are supplied in a search. This may be preferable for users that want a one-click solution instead of several .src's, however you cannot filter by year or other pages.
Quick
These are fast, lean versions of the main Search function. Use this if you only need basic metadata for file explorers:
- Quick Results.inc - a compact version of Results.inc: this is essential for the following scripts...
- Quick Search - Movie - finds movies, can filter by a specific year.
- Quick Search - TV - finds TV shows by season, can filter specific seasons and episodes.
- Quick ID - retrieve data directly if you have saved
TMDBorTMDBURLtags.
For most files:
-
The scripts will let you know of any wee mistakes. You can select “Back” to return to the previously displayed prompt and try again or use given metadata.
-
Season and episode don’t have to be filled in; the script will automatically ignore it for movies, retrieve all of a season’s episodes
-
Episodes can be filtered when separated by commas like 1,2,5,10.
-
Episodes can also be filtered in ranges, e.g. 1-5,8-10.
-
Episodes can have a limit defined in Settings to reduce the amount returned in “Adjust tags”. The default is set to 20.
-
The script can take 6-10 seconds per 100 episodes. Consider the options above when searching for Specials (Season 0) when there are hundreds of episodes.
-
You can bring up a list of seasons for TV shows when searching for something silly like season 100. Use this to add metadata to make your next search easier.
-
Languages can be refined from a search too if you ever want a translation or region-based titles/ratings.
-
You can search without a language to return more results in certain Get .src’s: beware as this can produce hundreds of results.
-
Settings can be localised by copying the
“en": [] section in"localizations": {}, run it through a translator of your choice and refine as needed.
Actions
TBD
Icons
Mp3tag v3.34 for Windows added custom toolbars which uses .ico files to add an icon to your functionality. They're also stored in .icl files which is a nifty way to see them all when choosing. They share the same name as the script they're paired with but swap them about if you want!:
- Save the icons somewhere handy on your device (the sources folder is convenient but it won't save your .ico files when using Save configuration...)
- Go to View -> Toolbars and select either Mp3tag's main toolbar or a fresh new custom toolbar for your own use.
- Select a script, give it a tooltip to remind you of what it does and find the .ico/.icl to load in the icons and assign it to that script.
Other
README is simply a quick reference for more information when needed, it is not essential but worth keeping around.
Tag Mappings
I’ve used Mp3tag's tag mappings as a basis for naming labels, as they create compatibility with several different tagging syntaxes, not just ID3. They are closer to .mp4's tagging standard but I took cues from .mkv's standard to prioritise much wider compatibility.
Tags can be renamed afterwards using Mp3tag's Options, remapped through TMBD settings or manually with Mp3tag's own functionality to assist you. Apologies however if what is supplied from this suite doesn’t 100% match your workflow.
Web Sources
Basic
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| - |  |
Localised artwork for movie/per season |
| ACTOR | MKV |
Cast of movie/per episode |
| ARTIST | |
Any found musicians/singing voices |
| CREATOR |  |
Custom tag following the format of ACTOR, DIRECTOR and PRODUCER |
| CHARACTER | |
Roles played by actors in a movie/per episode; please note this is kept separate from ACTOR |
| COMMENT | |
Can be used for anything; used to list metadata that isn't displayed or indexed by file explorers |
| COMPOSER | |
Any found music writer |
| CONDUCTOR | |
Any found musical conductors |
| COPYRIGHT | |
Combination of TVNETWORK and PUBLISHER |
| COUNTRY | MKV |
Production country as text |
| COUNTRYID | |
Custom tag for origin country as ISO 3166-1 |
| DIRECTOR | MP4 |
Director and co-directors |
| ERROR: |  |
Only used to inform of errors, please uncheck |
| GENRE | |
Delimited; can separate any with "&" in settings |
| CONTENTGROUP | |
Used for "Collection"; could be used to keep movies/TV shows/music/whatever under one name |
| INVOLVEDPEOPLE | |
"Character 1 / Character 2":Actor;Job:Crew Member (Complete list of credits for a movie/per episode) |
| LYRICIST | |
Any found lyric writer |
| NARRATOR | |
Any found narrator |
| ORIGTITLE | |
Custom tag based on ORIGALBUM; movie title in original language or stylisation |
| PRODUCER | MKV |
Producer or co-producers |
| RELEASETIME | |
YYYY-MM-DD |
| SUBTITLE | |
A catchy sentence/tagline |
| TITLE | |
Title of movie/per episode; can include multiple tags for alternative titles |
| TMDB | MKV |
movie/ID or tv/ID; can use ID in directories or filenames to enable Plex scraping |
| TMDBURL |  Kodi |
Full link to movie/episode; can store in .mkv's to enable Kodi scraping when set to "Use video tags" |
| TOTALTVEPISODES | |
Custom tag based on TOTALTRACKS |
| TOTALTVSEASONS | |
Custom tag based on TOTALDISCS |
| TRACK | |
Only used to create a list of episodes, please uncheck; could be used for movies in a series |
| TVEPISODE | MP4 |
Number of episode per season |
| TVEPISODEID | MP4 |
Production code per episode; can sort by intended order rather than actual airing order |
| TVNETWORK | MP4 |
Broadcasters of a TV show |
| TVSEASON | MP4 |
Number of season per TV show |
| TVSEASONDESC | |
Custom tag for description per season |
| TVSEASONTITLE | |
Custom tag for title per season |
| TVSHOWDESC | |
Custom tag for TV show description |
| YEAR | |
YYYY; can be set to YYYY-MM-DD |
External ID (from Settings or .src)
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| IMDB | MKV |
Same function as TMDB |
| IMDBURL | Kodi |
Same function as TMDBURL |
| TVDB | MKV |
Same function as TMDB |
| WIKIDATA | |
Custom tag with same function as TMDB |
Remap -> MP4
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| DESCRIPTION | |
A detailed explanation of a movie/per episode |
| EDITOR | |
Custom tag following the format of ACTOR, DIRECTOR and PRODUCER |
| ITUNESADVISORY | MP4 |
1 for explicit; based on ITUNEXTC ratings and also when unrated as a precaution |
| ITUNESMEDIATYPE | MP4 |
Denotes if "Movie" or "TV Show" when first imported into Apple software; can set to use "Short Film" and "TV Movie" depending on runtime per movie/episode |
| ITUNEXTC | MP4 |
Region｜Rating ; no data for "Standard", "Score" or "Reasons" |
| ITUNMOVI | MP4 |
XML formatted COPYRIGHT, ACTOR, DIRECTOR, PRODUCER and WRITER/SCREENPLAY; can be read as a tag/atom by Plex/Apple software |
| ORIGTVSHOW | |
Custom tag based on ORIGALBUM; TV show title in original language |
| PODCASTDESC | |
a.k.a "Long Description"; a combination of other descriptive fields |
| PODCASTKEYWORDS | |
a.k.a "Keywords"; user submitted for searches or discovery, also contains TMDB's "Tones" |
| PUBLISHER | |
Closest match to a relevant tag for "Studio" or "Production Company" |
| SCREENPLAY | |
Custom tag following the format of ACTOR, DIRECTOR and PRODUCER |
| TVSHOW | MP4 |
Title of TV show; can include multiple tags for alternative titles |
| WRITER | |
Custom tag following the format of ACTOR, DIRECTOR and PRODUCER |
Remap -> MKV
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| ALBUM | |
Ideally for music releases; remapping for TVSHOW to preserve TITLE in Windows File Explorer |
| CONTENT_TYPE | MKV |
Proper formatting for ITUNESMEDIATYPE |
| EDITED_BY | MKV |
Proper formatting for EDITOR |
| EXPLICIT | |
Custom tag based on ITUNESADVISORY; 1 for explicit |
| KEYWORDS | MKV |
Proper formatting for PODCASTKEYWORDS |
| LAW_RATING | MKV |
Proper formatting for ITUNESADVISORY; can set as Region｜Rating or just Rating |
| ORIGALBUM | |
Ideally for original source of a music release; remapping for ORIGTVSHOW |
| PRODUCTION_STUDIO | MKV |
Proper formatting for PUBLISHER |
| SCREENPLAY_BY | MKV |
Proper formatting for SCREENPLAY |
| SUMMARY | MKV |
Proper formatting for DESCRIPTION |
| SYNOPSIS | MKV |
Proper formatting for PODCASTDESC |
| WRITTEN_BY | MKV |
Proper formatting for WRITER |
Remap -> Maximum Compatibility
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| - | - | All tags available from Basic, MP4 and MKV as separate tags |
| GROUPING | |
Extra tag used by Apple for sorting media by anything; remapping for CONTENTGROUP |
| SETSUBTITLE | |
Ideally for a subtitle per season (TMDB only gives one subtitle); remapping for SUBTITLE |
Actions
Add Sort Tags/Fix Tags
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| ALBUMSORT | |
Formats ALBUM into a separate tag |
| ALBUMARTISTSORT | |
Formats ALBUMARTIST into a separate tag |
| ARTISTSORT | |
Formats ARTIST into a separate tag |
| COMPOSERSORT | |
Formats COMPOSER into a separate tag |
| TITLESORT | |
Formats TITLE into a separate tag |
| TVSHOWSORT | MP4 |
Formats TVSHOW into a separate tag |
Remap Tags - MP4/Remap Tags - Auto/Fix Tags
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| ITUNESHDVIDEO | MP4 |
1 for 720p, 2 for 1080p; tells Apple software the file is HD |
Tag Compatibility
Windows File Explorer
| TAG NAME | COLUMN NAME | MP4 | MKV |
|---|---|---|---|
| - | Cover Art | ||
| ALBUM | Album | |
|
| ALBUMSORT | Sort album | |
|
| ALBUMARTIST | Album artist | |
|
| ALBUMARTISTSORT | Sort album artist | |
|
| ARTIST | Contributing artists | |
|
| ARTISTSORT | Sort contributing artists | |
|
| COMMENT | Comments | |
|
| COMPOSER | Composers | |
|
| COMPOSERSORT | Sort composer | |
|
| DESCRIPTION | Description | |
|
| COPYRIGHT | Copyright | |
|
| DIRECTOR | Directors | |
|
| GENRE | Genre | |
|
| KEYWORDS | Tags | |
|
| LAW_RATING | Parental rating | |
|
| PRODUCER | Producer | |
|
| RELEASETIME | Date | |
|
| SUBTITLE | Subtitle / Episode name | |
|
| TITLE | Title | |
|
| TITLESORT | Sort title | |
|
| TRACK | # | |
|
| TVEPISODE | Episode number | |
|
| TVSEASON | Season number | |
|
| WRITTEN_BY | Writers | |
|
| YEAR | Year | |
Apple Software (iTunes, Apple Music, Apple TV etc.)
| TAG NAME | COLUMN NAME | MP4 | MKV |
|---|---|---|---|
| - | Cover Art | |
|
| ALBUM | Album (iTunes/Apple Music) | |
|
| ALBUMSORT | Sort Album (iTunes/Apple Music) | |
|
| ALBUMARTIST | Album Artist (iTunes/Apple Music) | |
|
| ALBUMARTISTSORT | Sort Album Artist (iTunes/Apple Music) | |
|
| ARTIST | Artist (iTunes/Apple Music) / Director; not recommended as this can be accessed from ITUNMOVI |
|
|
| ARTISTSORT | Sort Artist (iTunes/Apple Music) / Sort Director | |
|
| COMMENT | Comments | |
|
| COMPOSER | Composer (iTunes/Apple Music) | |
|
| COMPOSERSORT | Sort Composer (iTunes/Apple Music) | |
|
| DESCRIPTION | Description | |
|
| GENRE | Genre | |
|
| GROUPING | Grouping | |
|
| ITUNESADVISORY | Title 🅴 (iTunes/Apple Music) / Title 🅲 (iTunes); only in List view, ITUNEXTC will override this in iTunes |
|
|
| ITUNESHDVIDEO | HD icon |
|
|
| ITUNESMEDIATYPE | Categorises file into Movie, TV Show or Home Videos on first import | |
|
| ITUNEXTC | Title Rating |
|
|
| ITUNMOVI | Movie/episode overview; how Apple stores and displays COPYRIGHT, ACTOR, DIRECTOR, PRODUCER and WRITER |
|
|
| PODCASTDESC | Movie/episode overview; more detailed version of the Description column | |
|
| TITLE | Title | |
|
| TITLESORT | Sort Title | |
|
| TRACK | Track (iTunes/Apple Music) | |
|
| TVEPISODE | Episode Number | |
|
| TVEPISODEID | Episode Code | |
|
| TVSEASON | Season | |
|
| TVSHOW | Show | |
|
| TVSHOWSORT | Sort Show | |
|
| YEAR | Year / Release Date | |
Limitations
There are limitations with this script in comparison to other software to consider:
-
This is based on English, please let me know if any issues occur for other languages.
-
This can only make one query at a time so a script will retrieve tags for one movie or one TV season. You can however batch/bulk tag multiple files for TV episodes.
-
Auto-tagging is not possible, you must search for your desired content then choose which tags to save (the search fields can enter some data for you if already saved in your file like
TITLE,TMDB,RELEASETIMEetc.). -
Sources can’t save or manipulate external files so it can’t sort folder hierarchies, export XML or save/delete image files for you. This must be done manually or by using Actions/Export/Tools.
-
Only one cover can be added between all selected files in “Adjust Tags”. Hopefully support can come for more artwork to be applied to one file or separate artwork for multiple files; in the meantime, you could try out Get - Posters and Stills.
-
Several settings exist for lowering requests for data, consider this if you have limited download data. This script does require additional data for TV shows, requested season, cover/preview images, credits, alternative titles, content ratings and external ID’s. The Quick scripts don't require as much data to retrieve the essentials.
-
TMDB does contain metadata that isn't retrievable through the API:
- Collections (specifically full data about each movie/episode in a collection)
- Episode Groups (user-made alternative episode orders like a home release order)
- multiple taglines (previous ones can be viewed using TMDB's editing functionality)
- IMDB episode ID’s (it does but requires a ridiculous amount of requests made for each)
-
TMDB doesn’t offer some metadata that other databases do:
- long plot descriptions (i.e. synopsises, overviews, outlines)
- official organisation for content ratings (i.e. a "Standard")
- reasons for a content rating
- subtitles or closed captions
- translation/dubbing credits
- alternative episode listings (outside of episode production code numbers)
-
TMDB is subject to user contribution. For the most part it is an excellent resource however accuracy, translations and completion can vary even for popular content. If you notice any mistakes, it may be a good idea to update faulty data yourself using your account on TMDB where possible. Here's some things to look out for:
- actors showing up twice
- characters being called an actor
- content ratings being added/removed
- production countries without corresponding ISO 3166-1 values
- alternative titles showing that should’ve been set as a “series title” like Pirates of the Caribbean 5 - Dead Men Tell No Tales
-
User contributions also means data can constantly change, for newer content still in production and even with older completed entries. Due to this and other restrictions, I haven’t added support for certain metadata:
- user ratings (better leaving that for scraping)
- budget/revenue
- technical details like a file’s resolution (most software reads this natively anyway).
- an exception is primary artwork which is chosen by a non-stop popular vote
-
You can choose to map tags for .mp4 or .mkv: it is completely up to you what video format you use. Look into what you use to play your media and how you organise/sort/find your media then work from there to decide:
- MP4 is more widely supported by all operating systems.
- Apple products only use MP4, not MKV.
- Certain MP4 metadata such as tags/keywords, content rating, directors, copyright etc. is editable from Windows File Explorer and other software, sadly not via Mp3tag.
- MKV has technical advantages with packaging multiple audio tracks, video tracks, subtitles and even fonts in one file.
- Most media libraries support scraping using MKV's, not MP4
- MKV metadata is barely used by anything.
-
I don’t own a Mac or Apple TV and have limited experience with Plex/Kodi/Emby/Jellyfin etc. However if any issues appear in the Mac version of Mp3tag or otherwise things don't seem right, please let me know and I will try to solve it regardless.
Changelog for v1.06 (Last updated: 28/04/2026)
1.06
All files
- now have versions appended to top for easier identification
- .ico files for every web source (suited for Default appearance)
- updated README.txt with swanky ASCII artwork
- added Length column in "Adjust Tags"
- added [MinAppVersionMac]
- RELEASETIME now a basic tag
- removed COLLECTION, not actually an MKV tag
- removed ACTOR->ARTIST, DIRECTOR->ALBUMARTIST and WRITER->COMPOSER remaps
- replaced GROUPING with CONTENTGROUP
- remap CONTENTGROUP->GROUPING in max compatibility
- added EXPLICIT, equivalent of ITUNESADVISORY
- added SCREENPLAY for MP4, SCREENPLAY_BY for MKV
- SCREENPLAY values are now separate from WRITER but stay combined for ITUNMOVI
- added EDITOR for MP4, EDITED_BY for MKV
- added NARRATOR when found in crew
- added ARTIST when a musician is found in crew and cast as singing voice
- added LYRICIST when a musician found in crew
- added CONDUCTOR when a musician found in crew
- added COMPOSER when a musician is found in crew
- added CHARACTER, may require manual review as it captures a LOT of entries
- added CREATOR, for completion's sake
- added more job roles to be assigned to PRODUCER/WRITER for better detection
Settings.settings
- added "Year" to set YEAR as YYYY-MM-DD or YYYY
Results.inc
- fixed newlines on ITUNMOVI
- fixed ITUNEXTC/LAW_RATING when regions found but no values for ratings
- fixed episodes not being returned when missing an air date
(Quick) Search - Movie/TV/Multi.src / Concept - Search or ID.src
- prioritises SORT tags over normal tags for searching
Quick Results.inc
- added CONTENTGROUP
Get - Posters and Stills
- clearer error when a season/episode exists but has no posters/stills
Get - Posters and Stills / Backdrops / Logos
- quick UI clarifiation for previewing ALL images via website
Any issues/requests, please give a shout! 
The Movie Database (TMDB) v1.06.zip (2.3 MB)