[WS] TheMovieDB

[Sweder]

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]

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]

Thanks for the script.

[rojaljelly]

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]

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]

@LyricsLover

There are existing specialized tools around the naming and metadata for Movies and TV-Shows

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]

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]

@rojaljelly

This excellent script was written for movies but I would need somthing similar for series.

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]

@ny_dave69

I know I'm late to the table but would be interested in getting the episode data from the TMDB.

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]

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

---

As an alternative approach for:

@ny_dave69

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.

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

GitHub - AverageHoarder/mkvpropr: Python script to interactively and recursively...

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

MP3Tag Title not used as MKV Titles

I've solved this issue in my python script mkvpropr by setting the file title based on the title in matching .nfo files (that tinyMediaManager generates for each of my movies/tv show episodes). Example movie .nfo excerpt: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <!--created on 2024-08-26 20:19:13 - tinyMediaManager 5.0.9--> <movie> <title>Der Blade Runner</title> <originaltitle>Blade Runner</originaltitle> The mkv file title would be set to Der Blade Runner. And should tha…

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

[Casual_Tea]

@LyricsLover

write the metadata into your MKV

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]

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.inc and TMDB#Settings.settings into 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.src and TMDB#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 replace en-GB with a "language-REGION" of your choice, e.g. de-DE, en-US, even it-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/EXPLICIT when 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 IMDB and IMDBURL for movies and TV shows.
• TVDB - uses TVDB for TV shows.
• Wikidata - uses WIKIDATA for 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 TMDB or TMDBURL tags.

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, 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.

• 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)

[RobertM]

@arb

I’ve made a version that can handle singular movies or multiple TV show episodes in a season.

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]

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:

@arb

Episodes can be filtered when separated by commas like 1,2,5,10. This is necessary for Specials (season 0) as the script can take 10 seconds per 100 episodes.

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]

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]

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

@rojaljelly

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.

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]

@arb

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

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]

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]

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]

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.