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 using this tag source has over external files and a complete reliance on scrapers is that you can store all the metadata you want directly into your media to create customised videos in media servers, for personal organisation and as part of your own Mp3tag workflow (creating 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
This requires a TMDB API key, though registration is very easy.
Installation has been made simple for this tag source, though we advise you to read this topic on where files should be kept in Mp3tag’s configuration folder if any errors occur due to files missing or misplaced.
-
Download the .zip file at the bottom and extract the files.
-
Open Mp3tag.
-
Click File → Open configuration folder.
-
Follow Full Installation, which will install the tag source and Configurators to help with maintenance. A new tools and icons folder will also be made.
-
Alternatively, use Manual Installation if you're not interested in Configurators or use a Mac as unfortunately Exports are not quite the same as in Windows.
Full Installation (Windows / Linux using Wine / with Configurators)
-
In Mp3tag, save your work and clear away your files.
-
In your download, open
!Install - Search. -
Copy the
dataandexportfolders into the Mp3tag configuration folder.- Allow files to be merged or replaced: no important files will be touched, only TMDB and Configurator files.
-
From your download, drag the two Tool - Load... Configurator.mp3's into Mp3tag.
- These are already copied over in data which you can use for future installations and updates.
-
Select these two .mp3's and run Actions → Configurators → Install a Tool.
- If you have no tools installed, you might get pop-up warning "tools.ini" was not found. Don't worry, this will stop as the file should now have been created.
-
Right-click either .mp3 and run Tools → Load all Configurators.
- This will replace any other files in the preview pane of Mp3tag. Ensure you have no unfinished work before progressing.
-
Select all .mp3's and run Actions → Configurators → Add to Toolbar and choose your preferred toolbar.
- Again, you may get a pop-up if "toolbar_custom.ini" wasn't found. No worries.
-
Right-click on the toolbar → Customize... and click OK to update the toolbar with your new functionality.
-
Select any one .mp3 and run Actions → Configurators → Change Toolbar Icons and choose your current theme.
-
Right-click on the toolbar or go to File → Options... → Appearance to update your new icons.
- Default and manually set icons will not be updated.
-
Click TMBD - Settings on your toolbar or go to Tag Sources → TMDB → Settings to input your API key and change your language settings.
-
Select the Tag Source - Search .mp3's then run the Update Tag Source action. Double-check the
COMMENTfield to confirm the key is seen as valid.
-
You're now ready to use the tag source!
-
Repeat this process for Get, Check and External ID if you want to try them out. You'll already have Load all Configurators so you can simply copy over data then load and use your new functionality.
-
We advise you backup the entire configuration folder to external storage once installed as not all files will be archived using Save configuration... .
Manual Installation (Mac / Linux using Wine / without Configurators)
-
In your download, search for
.srcin!Install - Search. -
Open each .src using any basic text editor.
-
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. -
Copy over each .src, TMBD.inc and TMDB#Settings.settings into data → sources in the Mp3tag configuration folder.
-
You're now ready to use the tag source!
-
Repeat this process for Get, Check and External ID if you want to try them out, without copying the .inc and .settings files again.
-
API Key, Language, Region and Search Filter are unusable in Settings for now.
Maintenance
-
You can rename sources (.src) and actions (.mta) to your language or preference and copy the filename into the
TITLEof its corresponding Configurator to pair them up. -
You can easily delete any items from the toolbar or add more/edit them manually using right click → Customize... .
-
If you're not happy with Configurators, you can simply delete the tools and icons folders if they don't contain any of your own files, then remove any undesired Actions, Tools and Exports normally through Mp3tag.
-
Tag Sources can be deleted from the sources folder.
-
Whenever a file is updated as shown in the Changelog or TMDB README.txt, you should review these files to rename files and paste in any modifications to the newer versions before replacing. You can use the Update Tag Source action to easily re-apply your settings.
-
If you know how to develop using the Web/Tag 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!
-
@arb is currently maintaining this source so please be fair: updates or quick fixes you've made to the files should be posted in this topic, including new functionality or personal modifications that may or may not be put into the next release. Please send a private message before making any new topics or redistributing any part of the tag source. Full credit will always be given in the changelog to everyone with work added into a release and help given where possible.
Files
Essential
TMDB.inc contains code that is shared across .src’s. Settings saves your preferences between all .src’s.
Reminder: Both files must be kept in the sources folder and kept the same name for the tag source to work.
Search
These are your starting points to find content and grab metadata:
Movies - finds movies, can filter by a specific year. TV Shows - finds TV shows by season, can filter by ranges of episodes. Any or ID - finds both, can filter seasons/episodes but not year or pages. It prioritises using a TMDB ID over a search term if both are entered. Made for users that want a one-click solution.
Once you've tagged a file with TMDB or TMDBURL, the following can retrieve data directly:
Get
These will retrieve more items of a specific type of metadata:
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/EXPLICIT when required.
TV Seasons - all seasons available for a TV show, can filter by ranges of 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.
Backdrops - all wallpapers for movies, TV shows and seasons for media server 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
You can use ID's from other databases to find data from TMDB.
IMDb - uses
IMDB and IMDBURL for movies, TV shows and TV episodes.
TheTVDB - uses 
TVDB for TV shows, TV seasons and TV episodes.
Wikidata - uses 
WIKIDATA for movies, TV shows, TV seasons and TV episodes.
Check
These let you quickly look up TMDB configurations:
Content Ratings - Movies - all ratings for a searched/default region. Content Ratings - TV Shows - 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.
Extra features
-
The sources 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 numbers don’t have to be filled in; it will automatically be ignored for movies and default to Season 1 for TV shows.
-
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. -
If you're re-tagging one file, the episode number will be filled in for you.
-
Episodes can have a limit defined in Settings to reduce the amount returned in “Adjust tags”. The default is set to 100.
-
The tag source 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 by 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.
Configurators
This is a custom system built entirely within Mp3tag to manage your tag sources and toolbars. It is not required to run the tag sources but it does add handy features like updating API keys, languages and search filters in your files. Each .mp3 represents a function of Mp3tag that can be used with special Actions to perform certain tasks, such as:
Tool - Load all Configurators Tool Tool - Load 'TMDB' Configurators Action - Add to Toolbar - Custom Action - Add to Toolbar - Main Action - Change Toolbar Icons - Default (Dark) Action - Change Toolbar Icons - Default Action - Change Toolbar Icons - Original Action - Install a Tool Action - Update Tag Source Action - _Refresh Configurators
Certain Configurators only work with certain Actions, e.g. Tag Source Configurators can only be ran with Update Tag Source.
Change Toolbar Icons can be used with any one Configurator to update icons provided in the download: again, default and manually set icons will not be touched.
Refresh Configurators will clear temporary data from a Configurator after use.
You can easily rename Configurators using TITLE for the filename of its corresponding file, ALBUM for what type it is and TITLESORT to define a tooltip when put into a toolbar then running through any Configurator Action.
Tag source settings with a 
next to it requires Update Tag Source to be used.
Other
README is simply a quick reference for more information when needed. It should be checked whenever an update is released but it is not essential to keep.
Icon .ico's are sorted into specialised folders corresponding to an Mp3tag theme. You can always replace them with your own or use them without Configurators, if you like.
Tag Mappings
Mp3tag's tag mappings create compatibility with several different tagging syntaxes. They include a mixture of .mp4 and .mkv tagging standards to prioritise much wider compatibility. This tag source also uses non-standard tags to include extra data that may be useful.
Tags can be remapped through TMBD Settings or manually with Mp3tag's own functionality. Apologies however if these tags don’t match your workflow 100%.
You can see which tags work with what software using this wiki.
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 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 scraping in Plex |
| TMDBURL |  Kodi |
Full link to movie/episode; can store in .mkv's to enable scraping in Kodi 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
| 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 |
Settings → 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 |
Settings → Remap Tags → 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 |
Settings → Remap Tags → Maximum Compatibility
| TAG NAME | EXISTING? | PURPOSE |
|---|---|---|
| - | - | All of the above tags are available 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 |
Limitations
There are limitations in comparison to other software to consider:
-
This is based on English, please let me know if any issues occur for other languages.
-
You can only make one query at a time to retrieve tags for one movie or one TV season to tag multiple files with TV episodes.
-
Automation is not possible, you must search for your desired content then choose which tags to save. The search fields can auto-fill 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.
-
If you have limited download data, several settings exist for lowering data requests including a Quick Mode. This tag source does require additional data for TV shows, requested season, cover/preview images, credits, alternative titles, content ratings and external ID’s.
-
TMDB has 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 have 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 software restrictions, I haven’t added support for certain metadata:
- user ratings (best left for scraping)
- budget/revenue
- technical details like a file’s resolution (most software reads this natively anyway)
- an exception is primary artwork which is provided but chosen by an ongoing 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 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 advantages with packaging multiple audio tracks, video tracks, subtitles and even fonts in one file.
- Most media servers 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.07.1 (Last updated: 05/10/2026)
1.07.1
All files
- a radical new way to install and update tag sources and toolbars with Configurators,
all done through Mp3tag! (currently tested only on Windows, cross-compatibility TBD) - API keys, language-REGION, search filter terms can be stored and used from settings
using Configurators - toolbar icons are quick and easy to assign between Default/Default (Dark)/Original
using Configurators - API key will be cleared from .src when updated if invalid/removed from settings
using Configurators - can now be made into Quick versions via setting
- data requests lowered in Quick modes
- reorganised folders for for easier installation/access for Configurators
- updated !!! IMPORTANT !!! to reflect new API key updating method
- updated .ico's to Fluent UI Icons standardisation with custom ones here and there
- changed certain Use commands to UseFormat for reliability if no value
- better failsafes for punctuation like quotes
- auto-fill search by TVEPISODE when a single file selected
- debug files automatically route to sources folder in Windows
- changed IndexInput/AlbumInput to !IndexInput/!AlbumInput
- changed Index/Album to !IndexDebug/!AlbumDebug
- made indenting all tabs and stricter heirarchy
- fixed bad folding in text editors with a missing json_unselect_object
New Files
- "Configurators - File 1/2".mte's, necessary for Configurators to work
- "Configurator".mp3, simple files corresponding to an action, source or tool
- "Update Tag Source".mta, the one you've all been waiting for...
- "Install a Tool".mta, adds even the most complicated of tools easy-peasy
- "Add to Toolbar".mta's, add functionality easily to your main or custom toolbar
- "Change Toolbar Icons".mta's, alter any icons found from specific icons folders
- "_Refresh Configurators".mta, for clearing extra TEMP_ tags or updating filenames
- even more .ico's, icons to go with Configurators and installed functionality
Removed Files
- "Search - Multi".src, made redundant by "Search - Any or ID"
- "ID".src, made redundant by "Search - Any or ID"
- "Quick" src.'s/.inc, made redundant by setting
- Icon.icl files, will restore if there's interest
- Actions, will return once upgraded
Search .src's
- "Search - Any or ID", renamed from "Concept - Search or ID" for organisation
- "Search - Movies", renamed from "Search - Movie" for consistency
- "Search - TV Shows", renamed from "Search - TV" for consistency
- improved auto-filling searches for TV content
- $trim() in all text search entries
External ID .src's
- renamed to official names: IMDb, TheTVDB and Wikidata
- upgraded to show results for movie, TV show, season and episode
TMDB.inc
- renamed from "TMDB#Results" for organisation
- made CREATOR output processing ridiculously simpler
- skips ITUNMOVI if empty due to no data available
- added basic $dedup()'s to INVOLVEDPEOPLE
- more failsafes for delimiters in INVOLVEDPEOPLE
- fixed potential error with credits processing where last value could be removed
- fixed occurence where season credits have a different JSON scheme
- fixed loops from recent change to json_foreach commands
Results.inc / Get - Alternative Titles.src
- removed punctuation filtering from ORIG tags so they're truly the original
Settings.settings
- "Experimental" heading removed
- "API Key", "Language" and "Region" can now be used with Configurators
- added "Search filter", can list comma-delimited letters like $replace()
- added "Quick Mode", toggle between standard/quick processing
1.07.1
All .src's
- fixed missing carriage return when inserting API key
Configurators#Update Tag Source.mta
- fixed missing carriage return when inserting API key
- fixed an issue where COMMENT would show entire .src in search filter section
- fixed TEMP_ tags not clearing
TMDB#Settings.settings
- added gear icons to settings that are compatible with Update Tag Source
Any issues/requests/additions, please let me know 
Mp3tag versions required: Windows 3.36, Mac 1.10.0