[WS] TheMovieDB

Sweder · February 28, 2020, 7:04am

Hi,

first of all I would just like to commend briefly MP3Tag and everyone who is involved in this app - you do a great job, thanks so much for that. I combine tagging my library with Musicbrainz Picard and I haven't found any other functional software alternative of this combination yet. I tried about 30 of them myself, including paid ones.

I attach WS script to grab data from TheMovieDB(.org). Perhaps most will not use it, but it can help someone. I make the result of tagging as the largest possible set of variants of using individual fields. Therefore, some values are repeated in different fields (eg. DESCRIPTION, COMMENT, PLOT, SYNOPSIS etc.) to achieve the widest compatibility with different players, media servers, etc. Currently tested only on MP4 and MKV containers and in KODI, Plex, Emby, Jellyfin environments. I built the basic set of data to be filled in tagfields with the MetaX application.

To ensure script functionality, you need to register at TheMovieDB(.org), generate an API key (https://www.themoviedb.org/settings/api) and use it in URLs. Specific places are marked there in the script.

I am not a programmer, this is my first MP3Tag WS script and therefore I apologize in advance for any errors or bad data acquisition and processing methods, procedures etc.. I will be glad for any adjustments and improvements to make it work properly and general satisfaction.

Many thanks for your attention
TheMovieDB.com (v 1.0).src (10.4 KB)

DingoRouge · June 3, 2020, 7:56am

Hi,

I was willing to include such a tagging facility in my DVB-T remuxing python script when I saw your job. It is not worth trying anymore thanks to you.

It should definitely be included in MP3TAG by default so that each user don't have to request a development key.

By the way, there is a tag you may add. Do you know of the TMDBURL tag ? I haven't seen it in your code and it may ease the job with KODI.

Thanks again
Greg

JB1K · April 16, 2022, 12:49pm

Thanks for the script.

rojaljelly · August 11, 2024, 8:34am

The topic is quite old but still very interesting for me.
This excelent script was written for movies but I would need somthing similar for series.
I'm sure this request is much more complicated than single movies...

My requested tags would be:

series (TVSHOW)
season (TVSEASON)
episode (TVEPISODE)
episode name (TITLE)
summary (COMMENTS)
year (or release date) of each episode (YEAR)

I'm not sure how many users are working with mp3tag for keeping their collections of movies and tv shows on track, because its main focus is on music. But for me mp3tag is one of my overall top 3 daily used applications which I use 75% for series-, 20% movies- and 5% music-tagging. A working script (and I'm not good enough for writing my own scripts) for tv shows and movies would save a lot of manual copy/paste actions.

LyricsLover · August 11, 2024, 9:37am

As you can see for your other request, I don't think that too many people are using Mp3tag to tag series. There are existing specialized tools around the naming and metadata for Movies and TV-Shows, inlcuding the ability to display them on the big TV screen.

Casual_Tea · August 11, 2024, 10:44am

In my experience most people who collect movies and tv shows at scale either use the *arr stack (Sonarr, Radarr etc.) to name their files after downloading, or they use something like Filebot or tinyMediaManager to perform it semi automatic.
Personally I use tinyMediaManager to create the folderstructure and file names, fetch local artworks, create .nfo files with all metadata related to the movie/tvshow and also fetch a local trailer.
Once that is done I use a few python scripts I wrote to reorder, name and flag the audio- and subtitle tracks within the files efficiently while using the fixed naming created by tmm to for example set the file title to the movie name or episode name within my scripts.
Plex, Jellyfin and Kodi can all import the resulting local files (with minor differences).

ny_dave69 · March 22, 2025, 2:05pm

I know I'm late to the table but would be interested in getting the episode data from the TMDB.
I've used both Filebot and TMM but neither actually tags the video file, rather they create small text or picture files ie; nfo, xml, jpg, tbn, etc... but those files eat up a lot of NAS disk space.
Just tagging the movie files with the data saved me a huge amount of disk space.
Now I would like to save even more space since series video files are smaller but there are so many more and all have those small text/picture files.

Yes they are a small file size, a few Kb but files are broken into blocks on a disk, and that adds up quickly..

I have been trying to create my own source file along the lines of the movie one, but I just don't have the programing skills, so any help would be appreciated
thanks

RobertM · April 10, 2025, 11:19am

You can use Sweder's TheMovieDB script as a template, modifying it to get TV series information from TMDB.

In your script's opening section, change the values for index and album url.
Replace the movie related values with values relevant for TV series, as follows:

[IndexUrl]=https://api.themoviedb.org/3/search/tv?query=%s&api_key=YOUR_API_KEY&language=en-GB
[AlbumUrl]=https://api.themoviedb.org/3/tv/

(also replace language value of en-GB with your preferred language if required).

Sweder's movie script assumes your filename contains searchable information (one item, the film title, once year is stripped out) [SearchBy]=$regexp(%_filename%,$\d+$,)

However, I'd recommend sourcing series title and year in your [SearchBy] criteria directly from Mp3tag fields (even though that means you have to set up those field tag values first).

[SearchBy]=Series||%title%||%s||Year||%year%||&year=%s

Note how this search by set-up refers to two fields (series title and year) each defined as 'triples' of field prompt, field source, and field search value.
Each Mp3tag field source value initialises its field search value, but the actual field search value can be overwritten at run time, for example if you want to try searching for a different year.

These || delimited triplicates are described in Mp3tag's Developing Tag Sources documentation but I don't think it's made particularly clear there how the search by %s values (plus other text in each third position of the || delimited triplicates) get strung together and used in construction of the %s value referred to in [IndexUrl].
In other words, the strung together search by field values (plus their hard-coded text parts) constitute the %s component of [IndexUrl] when you interactively run your tag source script.

For TV series you want to replace what's inside Sweder's json_foreach loop within the ParserScriptIndex section with the following code:

  ### URL to detail ### 
  json_select "id"
  SayRest
  Say "?append_to_response=aggregate_credits,content_ratings,external_ids&api_key=YOUR_API_KEY&language=en-GB"
  Say "|"
  
  ### id ###
  json_select "id"
  SayRest
  Say "|"
  
  ### name ###
  json_select "name"
  SayRest
  Say "|"
  
  ### original name ###
  json_select "original_name"
  SayRest
  Say "|"
      
  ### first air date ###
  json_select "first_air_date"
  SayRest
  Say "|"
  
  ### preview on web ###
  json_select "id"
  Say "https://www.themoviedb.org/tv/"
  SayRest
  SayNewline

It's up to you what TV series detail you want to retrieve of course, but note I've included aggregate_credits, content_ratings and external_ids via TMDB's append to response method.

Bearing in mind I'm particularly interested in tagging MKV files, here's a few example fields that could be included in your ParserScriptAlbum section.

Note that the first item retrieved in the following code is the TV series id.
You'll need this if you want to subsequently get specific season or episode info after retrieving information for TV series as a whole.

### id -> TMDB ###
OutputTo "TMDB"
json_select "id"
Say "tv/"
SayRest 

### first_air_date -> RELEASETIME -> DATE_RELEASED  ###
OutputTo "RELEASETIME"
json_select "first_air_date"
SayRest

### created_by.name -> WRITTEN_BY ###
OutputTo "WRITTEN_BY"
json_select_many "created_by" "name" ", "
SayRest

### genres.name(3) -> GENRE ### /* first three genres */
OutputTo "GENRE"
json_select_many "genres" "name" ", " "" 3
SayRest

### overview -> COMMENT ###
OutputTo "COMMENT"
json_select "overview"
SayRest

### poster_path -> COVERURL ###
OutputTo "COVERURL"
Say "https://image.tmdb.org/t/p/w185" 
### /* You can replace this URL by one selected from list below to change your preferred size of cover image */
# List of preferred poster image widths
#   "https://image.tmdb.org/t/p/original"
#   "https://image.tmdb.org/t/p/w92"
#   "https://image.tmdb.org/t/p/w154"
#   "https://image.tmdb.org/t/p/w185"
#   "https://image.tmdb.org/t/p/w342"
#   "https://image.tmdb.org/t/p/w500"
#   "https://image.tmdb.org/t/p/w780"

json_select "poster_path"
SayRest

### country ###
OutputTo "COUNTRY"
json_select_many "production_countries" "name" ", "
SayRest

### cast ### /* first five actors */
json_select_object "aggregate_credits"
  OutputTo "ARTIST"
  json_select_many "cast" "name" ", " "" 5
  SayRest
json_unselect_object

### parental rating ### /* prefer GB, but if not found then use US rating */
json_select_object "content_ratings"
  json_foreach "results"
    IfNotOutput "LAW_RATING"
      json_select "iso_3166_1"
      If "GB"
        OutputTo "LAW_RATING"
        json_select "rating"
        SayRest
      EndIf
    EndIf
  json_foreach_end
  
  IfNotOutput "LAW_RATING"
  json_foreach "results"
    IfNotOutput "LAW_RATING"
      json_select "iso_3166_1"
      If "US"
        OutputTo "LAW_RATING"
        json_select "rating"
        SayRest
      EndIf
    EndIf
  json_foreach_end
  EndIf
json_unselect_object

### external ids ###
json_select_object "external_ids"
  OutputTo "IMDB"
  json_select "imdb_id"
  SayRest
  OutputTo "TVDB"
  json_select "tvdb_id"
  SayRest
json_unselect_object

Just to emphasise once again, the approach above only gets you series level information.
In other words, the retrieval of aggregate information for entire TV series as a whole, rather than for particular seasons or individual episodes of a show.
I'll include more detail on how to get specific season or episode level information in next post.

RobertM · April 10, 2025, 11:44am

TheMovieDB has search API for movies and for TV series.
But not for particular seasons or individual episodes of a show.

This doesn't mean you can't retrieve specific season or episode information.
It just means you can't [SearchBy] show title, year, or any other search by criteria and simply plug them into [IndexUrl] to then pick from a list of total results as returned from the ParserScriptIndex section.

Instead, you need fully construct [AlbumUrl].

In practice, this just means you need the TV series id number along with the season and episode numbers.

For example, to retrieve specific episode information (including appended credits info), you need to construct an [AlbumUrl] that ultimately looks like this:

https://api.themoviedb.org/3/tv/{series_id}/season/{season_number}/episode/{episode_number}?append_to_response=credits&api_key=YOUR_API_KEY&language=en-GB

In other words, series_id, season_number and episode_number values are your search criteria, which you can specify like this:

[SearchBy]=SeriesId||$regexp(%tmdb%,.*/,)||%s||Season||%tvseason%||/season/%s||Episode||%tvepisode%||/episode/%s

I hold TMDB's TV series id in Mp3tag's %tmdb% field, but with its numerical part prefixed tv/ for MKV files (as per Matroska specification).
The $regexp function above is simply a way of stripping the tv/ prefix back out again before using it for search purposes.

Note how this search by set-up refers to three fields (series id, season number and episode number) defined as || delimited triplicates, where each triple is composed of the field prompt, field source, and field search value (plus hard-coded text).

The three field search values are all represented by %s, but season number is prefixed /season/, and episode number is prefixed /episode/, so that when they get strung together they become:

{series_id}/season/{season_number}/episode/{episode_number}

As mentioned, these strung together values don't get plugged into [IndexUrl] to produce a list of search query results as they would for TV series as a whole, instead the combined %s value is used to construct an AlbumUrl for direct use.
The AlbumUrl for episode level information is thus:

[AlbumUrl]=https://api.themoviedb.org/3/tv/%s?append_to_response=credits,external_ids&api_key=YOUR_API_KEY&language=en-GB

Since this approach is a bit different to that of using a ParserScriptIndex section and producing list of search query results, I've attached a commented template script.

TMDB TV Episode (Template v1.0).src (6.4 KB)

There's only a few items included in this template example (air date, episode name and directors).
The intention is more to illustrate with code and comments how the search query step is skipped and how album url is otherwise constructed when using unique ids.

I haven't included a similar template for retrieving specific season level info as that would just be a simpler version of the episode level script.

LyricsLover · April 10, 2025, 11:59am

Thank you very much for your detailed instructions and template script @RobertM !

As an alternative approach for:

you could use the specially made tool to read your already existing NFO files and write the metadata into your MKV:

Note: The python script mkvpropr is made by @Casual_Tea discussed here:

This idea does not use a WSS script. It reuses your already collected, existing metadata.

Casual_Tea · April 10, 2025, 1:05pm

Thank you for mentioning my script but that's not really its focus. The only information it currently extracts from the .nfo and writes to the .mkv file is the movie or episode title, which it sets as the mkv file title (part of the segment information, not a matroska tag as such).

The main focus of my script is to quickly set the track languages, track names and track flags for many files at once as quickly and efficiently as possible.

Like in this example where all tracks have a language of "und" = undefined, rudimentary track names like "Deu", "Eng" etc. and no forced, default, sdh (hard of hearing) or commentary flags.
None of these mkv properties are matroska tags but each player I've used supports them. The track languages and flags allow programs to automatically select the correct audio/subtitle track based on user preference. The file title is usually displayed in place of the filename in the program title and the track names give users enough information to quickly choose a track manually.

I had considered to add tagging support (since I already parse the related .nfo file to extract the movie/episode title in the script). However since none of the media centers and video players I use (Plex, Jellyfin, Kodi, mpv) officially support matroska tags (or only a few) and there is a lot of debate/confusion as to which TargetTypeValue which tag for movies/tv shows should get, I didn't bother implementing this functionality so far.

In my experience, the xml data in .nfo files is far more widely supported by media centers than matroska tags and the space requirement of an .nfo file is negligible. I have 7879 .nfos in my movie folders and together they take up 114MB. Local artwork files are an entirely different matter.

arb · November 8, 2025, 2:34pm

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 data and export folders 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 COMMENT field 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 .src in !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 replace en-GB with a "language-REGION" of your choice, e.g. de-DE, en-US, even it-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 TITLE of 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, RELEASETIME etc.
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

@arb

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

@arb

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

The Movie Database (TMDB) for Mp3tag v1.07.1.zip (2.6 MB)

RobertM · November 18, 2025, 6:40pm

There's quite a lot to take in with arb's TMDB scripts.
I don't claim to understand all the technical details at this stage, but here are a few observations stemming from initial try out anyway.

Search by year

One limitation of using TMDB's general multi search query, as opposed to more specific movie search or TV search queries, is that multi search doesn't take a year parameter.

I mentioned in an earlier post on this thread that Sweder's original movie script assumes the filename contains search information, but uses only one item, the film title (after year digits are stripped out) [SearchBy]=$regexp(%_filename%,$\d+$,)

In the context of searching for TV series, I recommended sourcing series title and year in [SearchBy] criteria directly from Mp3tag fields [SearchBy]=Series||%title%||%s||Year||%year%||&year=%s

To clarify, I think including the option to search by year is useful with movies too.
If anything, I'd say even more so than TV series.

Note that TMDB's movie search and TV search APIs both include two sets of searchable year dates.
With TV search you can look specifically for the first air date year, or you can search any year (the first air date and all episode air dates).
With movie search you can search on primary release year or simply year.

TMDB don't really describe how year search differs from primary release year search for movies, but my preference is to search on primary release year.
I've thus modified my own personal copy of Sweder's original TheMovieDB.com (v 1.0).src script to include primary release year in [SearchBy] as follows:

[SearchBy]=Title||%title%||%s||Year||%year%||&primary_release_year=%s

For example, a search by title "Treasure Island" + primary release year "1950" takes you straight to that version of the movie.

By contrast, TMDB multi search on "Treasure Island", with no option to search by year, lists 20 results (with a range of release dates) from which to choose, including TV series as well as movies.
The iconic 1950 film is listed down in sixth place.

Even if movie search inclusion of primary release year doesn't take you straight to the detail, you should at least get a clearer list of search results.

For example, "Star Wars" + "1977" lists only two results: "Star Wars" (released 1977-05-25), and "The Making of Star Wars" (released 1977-09-16).

Whereas search for "Star Wars" on its own (without year specification) lists 20 results, of which "The Making of Star Wars" isn't even included (suggesting the list of returned results simply maxes out at 20).

Episode number

I note that episode number isn't sourced from %tvepisode%.
The [SearchBy] criteria 'triple' definition for episodes in arb's "TMDB#Search or ID.src" is given as: Episodes||||&episodes=%s
I wasn't sure why the middle term of the triple (the source field) was left blank.

MP4-centric scripts

The scripts seem to be focused on MP4 format video.
At least, they do to me, as my focus is very much on MKV format files.

For example, if I use "TMDB#Search or ID.src" to tag a TV show episode, then I end up with series title in TVSHOW and episode name in TITLE.
TVSHOW isn't an official Matroska tag.

As well as being MKV-centric, my focus is very Windows-centric too.
Thus, for me, it makes more sense to output TMDB's TV episode name to SUBTITLE, since Windows readily displays that as Episode name for MKV files.

Similarly, arb's scripts create WRITER, whereas the official Matroska tag is WRITTEN_BY, which Windows displays as Writers.

This isn't a criticism of arb's scripts particularly. It's more of an observation.
It would be difficult to come up with scripts to tag both MP4 and MKV in an entirely consistent manner, as the two sets of tags are quite different.
This is just a heads up to others really. - Regardless of whether you're starting with Sweder's original movie script or using arb's multi purpose one, be prepared to have to modify the code in order to get TMDB API retrieved values mapping to tags exactly the way you want.

arb · November 18, 2025, 11:19pm

Oh thank goodness finally some feedback. Thank you, it genuinely helps

Search by year

This wasn’t a consideration but you’ve detailed it as a fair necessity. I saw multi as a quicker solution to switching between different searches but having only 20 results per page is hassle for more prevalent titles like “Treasure Island”.

I got a bit obsessed with an all-in-one solution in the form of Search or ID, then having solved that I settled on separate scripts as options to any personal preferences. I did test a field in said script where the user could pick multi, movie or tv searches that would even fill in the appropriate type based on ITUNESMEDIATYPE: it became a bother to change when necessary, then needed the extra field for Episodes and definitely doesn’t have space for Year.

I’ll make a start on separate Search - Movie and Search - TV Show scripts to take advantage of this.

Episode number

Searching for TV shows is mainly by title and season number, which can have their fields pre-filled from the first selected file. There’s no way to pre-fill episode numbers from multiple files but this field still exists for such a use:

I’m working towards support for a range feature (e.g. 1-5,8-10) with the new SayFormat and UseFormat commands and also an episode limiting feature.

MP4-centric scripts

Funny because I’m the same, I only use MKV’s. Video tags sadly seem just for personal categorisation now.

I scrapped a feature for remapping tags to iTunes, Plex, Kodi, DLNA etc. when it became obvious most video tags are read from XML/NFO files. It became difficult correlating which tags used by one software were deemed essential for others like CAST, ACTOR, ACTORS or ARTIST and god-forbid ARTISTS all the same thing… no wait, ARTIST’s actually DIRECTOR.

I’ve also given up adhering to Windows File Explorer’s shoddy support for MKV’s (close enough to giving up on Windows as it is ) and fling any extra data from incompatible tags into COMMENT, which gets indexed and helps with searches.

Instead, I aimed for the closest thing to a standardised mapping of tags between file formats, rather than fighting the eternal struggle of what compatibilities in which software. Mp3Tag’s mappings work great so I relied on MP4-centric tag names like TVSHOW for this reason. Custom tags like WRITER annoy me frankly but it falls more in line with existing Mp3Tag fields.

MKV’s target system is far more flexible and gravely under-utilised, given that TITLE could easily become different tags at different levels (CHAPTER=30, EPISODETITLE=50, TVSHOW=60), meaning SUBTITLE can be kept separate with a range of tags to be used more in line with it’s implication without having to bend to Window’s implementation. Mp3Tag still has a way to go to mapping more combinations for MKV that will likely never be adopted by companies with diminished interest in looking after people’s own collections.

I’ll consider another remapping solution where users can define their own mappings but for now I can throw in some more MKV tags into Extra Tags to help out.

The only other thing I could suggest is Options→Mapping but that’s unfair to expect simply for one web source.

(…rather than waiting for Microsoft to stop trying to salvage Co-pilot then fix their patchwork OS UI/GUI then make a context menu that isn’t a complete embarrassment THEN maybe update their File Explorer.)

rojaljelly · November 19, 2025, 9:11pm

It took me quite some time to get everything running - to be honest, mostly because I was afraid of starting with the topic. Also the readme didn’t say, where to put which files which was a bit frustrating.

But after 1 week of testing and adding some litte details of the code (searching with German titles does require some tweeking), I want to kick my own ass because I didn’t have tested it earlier. The Scripts save me sooo much time!

RobertM has made some great comments. I can only support his thoughts about the year as search criteria and some episode number problems.

It would be great, having searces especially for movies ot tv.
Usually you know which media type you are searching for and this will help slimming down the search results.

When doing episode-specific searches like “3,7,15” the results are provided with enumeration numbers “1,2,3”. Showing episode numbers on TMDB side of the results would be nice.

If I was able to do this kind of coding, I would have tried to do a similar script for TVDB, because they are more open minded with multiple episode sortings (airded/DVD/absolute…) or allowing movies as extras for tv series.

Ther is always some room for improvements, but to say it once again: I’m super happy to have the script as it is!

arb · November 19, 2025, 10:11pm

Thank you! I’ve seen scripts with .bat files to install/update web sources but not sure how to really do it properly so apologies if it’s not been clear how to deal with installation. Here’s a link for future reference Web Sources Archive - Howto - Mp3tag Community

@RobertM ’s been great and I’m chuffed he’s looked into the matter

Unfortunately Mp3Tag’s current method is strictly TRACK generates an array of results and is always to the left, then TITLE then any other tags in-between. The intention seems focused on music files rather than video which for a program based on MP3’s is completely valid.

The script does return results by your given episode order so it should be TVEPISODE 3, 7 and 15 even though TRACK makes it look otherwise. I’d love to have a way of determining an ordering of tags for the Tracks section and will pitch that to the developer.

I did look into TVDB as an alternative but apparently it’s falling apart in terms of developer support. Fair enough using it for pre-existing content but not sure of it’s longevity. Hopefully I’m wrong but avoiding it for now

Please let me know what tweaks helped you for your language, I use English but want to try supporting multiple languages I’ll aim to provide update within the next week as I noticed some problems with ITUNEXTC, INVOLVEDPEOPLE and SORT tags

rojaljelly · November 21, 2025, 9:05am

Following letter replacements I have added/changed:

&,und
+,und
=,ist
Ä,A
Ö,O
Ü,U
ä,a
ö,o
ü,u
ß,ss

I personally prefer TMDB for movies, but TVDB for TV series because I find their season order system easier to use, as many series have a different order on DVD or streaming services, or where episodes have been split/joined together.
But I understand your concerns regarding TVDB, as their homepage inspires so little confidence and is overloaded with advertising, unlike the modern design of TMDB.

arb · November 21, 2025, 1:40pm

Are those replacements for multiple tags or just for SORT tags? I was looking take that of the script to replace with a separate Action to generate them much quicker and keep the script’s loading time low. It already has most of the replacements you’ve noted but might need tweaking/separate versions for language-based ones like &, + and =.

The script does also create TVDB tags if this is of any help.

rojaljelly · November 21, 2025, 2:20pm

Sorry for not being precice enough.
These are replacements for the search string to avoid invalid urls.
Umlauts are a peculiarity of the German and Hungarian languages.

[SearchBy]=movie|tv/ID||$if2($regexp(%tmdburl%,https://www.themoviedb.org/(.*?/.*?)(/.*|$),$1),%tmdb%)||%s?||Title|Show||$regexp($replace($if2(%tvshow%,$if2(%title%,%_filename%)),., ,&,und,+,und,=,ist,@,at,Ä,A,Ö,O,Ü,U,ä,a,ö,o,ü,u,ß,ss),'[^A-Za-z0-9 -_]',)||search/multi?query=%s||Season||$if(%tvseason%,$num(%tvseason%,1),)||&season=%s||Episodes||||&episodes=%s||Language||de-DE||&language=%s&api_key=!!!YOUR_API_KEY!!!

Yes, I have notived, that there is also a tag for TVDB in the script, but I think the TVDB tags are only working for series, not for movies.
But it still helped me develop the idea of how to name my files so that the videos can be recognized by the PLEX agent to define a specific movie/series (PLEX recognizes the strings {tvdb-xxxxx}, {tmdb-xxxxx} and {imdb-xxxxx}).

arb · November 21, 2025, 2:54pm

Once there’s the ability to place settings values into [SearchBy], I can work on a way to get that $replace() format string into all Search .src’s easier.

Yeah, TMDB doesn’t offer TVDB for movies: External IDs. MKV’s have a recommended tag for it as TVDB2 but unlikely to happen.