video_utils.videotagger package

Submodules

video_utils.videotagger.base_item module

Base class for metadata objects

class video_utils.videotagger.base_item.BaseItem(*args, data=None, version=None, **kwargs)

Bases: BaseAPI

Extends the BaseAPI class for use in Episdode, Movie, Person, etc.

addComment(text)

Add a user comment to metadata information

Parameters:: text (str) – Comment to add
Keyword Arguments:: None –
Returns:: None

get(*args): Get value of key from data dict

getExtra(*args)

Method to get extra information from an api

Parameters:: *args (list) – Keys for API call
Keyword Arguments:: None –
Returns:: Extra information
Return type:: dict

getID(external: str | None = None, **kwargs) → str | None

Method to get ID of object, or external ID of object

Parameters:

None –

Keyword Arguments:

external (str) – Set to external ID key. Will return None if not found
**kwargs – Various accepted, none used

Returns:

Return the item ID or None if not found

getIDPlex(**kwargs)

Get ID of object or external ID of object in Plex standard format

The Plex format for the ID is “{source-ID}” where source is tmdb, tvdb, or imdb and ID is the ID; imdb IDs begin with tt.

Parameters:: None –
Keyword Arguments:: **kwargs – All keywords accepted by getID()
Returns:: Return the item ID or None if not found

property isEpisode

Identifies object as episode

Type:: bool

property isExtra

Identifies object as extra

Type:: bool

property isMovie

Identifies object as movie

Type:: bool

property isPerson

Identifies object as person

Type:: bool

property isSeries

Identifies object as TV series

Type:: bool

keys(): Return keys from the data dict

metadata(**kwargs)

Method to get metadata in internal, standard format

Parameters:: None –
Keyword Arguments:: **kwargs –
Returns:: Metadata in internal, standard format
Return type:: dict

pop(key, *args): Pop off a key from the data dict

setVersion(version)

Set version of file (i.e., Extended Edition); only valid for movies.

Parameters:: version (str) – Movie version
Keyword Arguments:: None –
Returns:: None

write_tags(fpath, **kwargs)

” Method to write metadata to file

Parameters:: fpath (str) – Path to video file to write metadata to
Keyword Arguments:: **kwargs –
Returns:: True if tags written, False otherwise
Return type:: bool

video_utils.videotagger.episode module

Classes for episode information

class video_utils.videotagger.episode.BaseEpisode(*args, **kwargs)

Bases: BaseItem

Base object for episode information from TMDb or TVDb

Provides methods that are used in both TMDbEpisode and TVDbEpisode objects for cleaner code.

get_basename(**kwargs) → str

Get file name in semi-Plex convention

This method returns file name in semi-Plex convention for the given episode based on season/episode number and name. The series ID from whichever database the metadata were obtained is included. Note that the series name is NOT included.

Example

>>> ep = Episode.TVDbEpisode(269782, 1, 1)
>>> print(ep.get_basename())
'S01E01 - Pilot.tvdb269782'

Parameters:: None –
Keyword Arguments:: **kwargs – Any accepted, all ignored
Returns:: File name in semi-Plex convention
Return type:: str

get_dirname(root: str = '') → str

Get directory structure in Plex convention

This method returns directory structure in the Plex convention for the given episode based on series name and season.

Example

>>> ep = Episode.TVDbEpisode(269782, 1, 1)
>>> print(ep.get_dirname())
'TV Shows/Friends with Better Lives (2014)/Season 01'

Parameters:: None –
Keyword Arguments:: root (str) – Root directory, is prepended to path
Returns:: Directory structure in Plex convention
Return type:: str

class video_utils.videotagger.episode.TMDbEpisode(*args, **kwargs)

Bases: BaseEpisode

Object for episode information from TMDb

EXTRA = ['external_ids', 'credits']

class video_utils.videotagger.episode.TVDbEpisode(*args, **kwargs)

Bases: BaseEpisode

Object for episode information from TVDb

video_utils.videotagger.episode.get_basename(seasonNum: int, episodeNum: int, title: str, ID: str = '', **kwargs) → str

Helper function for getting basename

This function is used for generating basenames from both TMDbEpisode and TVDbEpisode so that names can be truncated to 50 characters and invalid characters can be replaced

Parameters:

seasonNum (int) – Episode season number
episodeNum (int) – Episode number
title (str) – Episode title

Keyword Arguments:

ID (str) – Series ID
**kwargs – Passed to the video_utils.videotagger.utils.replace_chars() function

Returns:

Episode base name

Return type:

str

video_utils.videotagger.episode.to_list(arg) → list

Convert variable to a list

Parameters:: arg – convert argument to a list

video_utils.videotagger.gui module

video_utils.videotagger.movie module

Classes for movie information

class video_utils.videotagger.movie.BaseMovie(*args, **kwargs)

Bases: BaseItem

Base object for movie information from TMDb or TVDb

Provides methods that are used in both TMDbMovie and TVDbMovie objects for cleaner code

get_basename(**kwargs)

Get file name in Plex convention

This method returns file name in Plex convetion for given movie based on movie title and release year. The movie version and database ID from whichever database the metadata were obtained is incluced.

Example

>>> movie = Movie.TMDbMovie(435)
>>> print(movie.get_basename())
'The Day After Tomorrow (2004)..tmdb435'

>>> movie = Movie.TMDbMovie(435)
>>> movie.setVersion('Extended Edition')
>>> print(movie.get_basename())
'The Day After Tomorrow (2004).Extended Edition.tmdb435'

Parameters:: None –
Keyword Arguments:: **kwargs – Passed to replace_chars() function
Returns:: File nam in Plex convention
Return type:: str

get_dirname(root='')

Get directory structure in Plex convention

This method returns directory structure in Plex convetion for given movie based on movie title and release year.

Example

>>> movie = Movie.TMDbMovie(435)
>>> print(movie.get_dirname())
'Movies/The Day After Tomorrow (2004)'

Parameters:: None –
Keyword Arguments:: root (str) – Root directory, is prepended to path
Returns:: Directory structure in Plex convention
Return type:: str

class video_utils.videotagger.movie.TMDbMovie(*args, **kwargs)

Bases: BaseMovie

Object for movie information from TMDb

EXTRA = ['external_ids', 'credits', 'content_ratings', 'release_dates']

class video_utils.videotagger.movie.TVDbMovie(*args, **kwargs)

Bases: BaseMovie

Object for movie information from TVDb

EXTRA = ['external_ids', 'credits', 'content_ratings']

video_utils.videotagger.movie.get_basename(title: str, year: int | None = None, version: str = '', ID: str = '', isExtra: bool = False, **kwargs) → str

Helper function for getting basename

This function is used for generating basenames from both TMDbMovie and TVDbMovie so that title can be truncated to 50 characters, version truncated to 20 characters, and invalid characters can be replaced.

Parameters:

title (str) – Movie title

Keyword Arguments:

year (int) – Release year of movie
version (str) – Movie version; e.g., Extended Edition, Unrated
ID (str) – Movie ID
isExtra (bool) –
**kwargs – Passed to the video_utils.videotagger.utils.replace_chars() function

Returns:

Movie base name

Return type:

str

video_utils.videotagger.parsers module

Parsers for metadata from TVDb and TMDb

video_utils.videotagger.parsers.characters_to_credits(info: dict) → dict

Convert characters to credits dict

TVDb v4 API uses the ‘characters’ tag to store information for all cast and crew for a series (or episode). This method acts to convert that into the ‘credits’ dict as expected from the v3 API and TMDb for consistency.

video_utils.videotagger.parsers.image_paths(info, **kwargs): Build paths to poster/cover/banner/fanart images

video_utils.videotagger.parsers.parse_credits(info, **kwargs)

Function to parse credits into Person objects

Parameters:: info (dict) – Data from an API call

Keyword argumetns:: None.

Returns:: Updated dictionary
Return type:: dict

video_utils.videotagger.parsers.parse_info(info, **kwargs)

Wrapper function for parsing/standardizing data

Parameters:: info (dict) – Data from API request
Keyword Arguments:: **kwargs –
Returns:: Data from input, but parsed to standardized format
Return type:: dict

video_utils.videotagger.parsers.parse_releases(info, **kwargs): Parse release information from TMDb

video_utils.videotagger.parsers.standardize(info, **kwargs)

Standardize TVDb and TMDb to internal tag convention; similar to TMDb

Parameters:: info (dict) – Data from API request
Keyword Arguments:: **kwargs –
Returns:: Data from input, but converted to standardized tags
Return type:: dict

video_utils.videotagger.parsers.tvdb2tmdb(info)

Convert TVDb data to TMDb for consistent parsing

Parameters:: info (dict) – Data from API request
Keyword Arguments:: None. –
Returns:: Keys modified from TVDb to TMDb
Return type:: dict

video_utils.videotagger.person module

Class for metadata about person

class video_utils.videotagger.person.Person(*args, **kwargs)

Bases: BaseItem

Class for person metadata

Used for actors, directors, etc.

video_utils.videotagger.readers module

To read metadata from MP4 and MKV files

video_utils.videotagger.readers.mkv_reader(file_path)

Read metadata from MKV file and parse into ‘internal’ format

Parameters:: file_path (str) – Path to MKV file to extract metadata from
Keyword Arguments:: None. –
Returns:: Dictionary containing metadata if found, otherwise, emtpy dict
Return type:: dict

video_utils.videotagger.readers.mp4_reader(file_path)

Read metadata from MP4 file and parse into ‘internal’ format

Parameters:: file_path (str) – Path to MP4 file to extract metadata from
Keyword Arguments:: None –
Returns:: Dictionary containing metadata if found, otherwise, emtpy dict
Return type:: dict

video_utils.videotagger.series module

Classes for Series objects

class video_utils.videotagger.series.BaseSeries(*args, **kwargs)

Bases: BaseItem

Base class for TMDb and TVDb Series

class video_utils.videotagger.series.TMDbSeries(*args, **kwargs)

Bases: BaseSeries

For TMDb Series objects

EXTRA = ['external_ids', 'content_ratings']

class video_utils.videotagger.series.TVDbSeries(*args, **kwargs)

Bases: BaseSeries

For TVDb Series objects

static sort_series(info: dict, key: str = 'seasons') → dict

video_utils.videotagger.tags module

Lookup tables for tag names

Provides lookup tables for converting from MP4/MKV tags to the conventions used internally in the package. Also provides inverted lookup tables for converting from internal convention to MP4/MKV tags.

video_utils.videotagger.tags.encoder(val): Convert val to correct type for writting tags

video_utils.videotagger.tags.freeform(tag)

Generate MP4 freeform tag

Note from the mutagen package:: The freeform ‘—-‘ frames use a key in the format ‘—-:mean:name’ where ‘mean’ is usually ‘com.apple.iTunes’ and ‘name’ is a unique identifier for this frame. The value is a str, but is probably text that can be decoded as UTF-8. Multiple values per key are supported.

video_utils.videotagger.utils module

Utilities for video tagging

video_utils.videotagger.utils.add_text(fpath_data, text)

Add text to image object

This function adds a text string to a pillow Image object

Parameters:

fpath_data (file, bytes) – Path to a file to read in or bytes of file
text (str) – String to add to image

Keyword Arguments:

None –

Returns:

Image data

Return type:

bytes

video_utils.videotagger.utils.download(url)

Download data from URL

Parameters:: url (str) – Full URL of data to download
Keyword Arguments:: None. –
Returns:: Data downloaded from file; None if failed
Return type:: bytes

video_utils.videotagger.utils.download_cover(video_path, url, text=None)

Wrapper function to download artwork and add version text

Parameters:

video_path (str) – Path to video file artwork is for
url (str) – URL of artwork to download

Keyword Arguments:

text (str) – Text to add to artwork; typically is movie version

Returns:

Path to downloaded image on local disc, and bytes for image data

Return type:

tuple

video_utils.videotagger.utils.get_font(text, bbox)

Determine font size for movie version

This function determines the font size to use when adding movie version information to a poster. The font size is determined by iteratively increasing the font size until the text will no longer fit inside the specified box. The font size is the decremented slightly to ensure it fits. Space is also added between letters to ensure that the text spans most of the box horizontally.

Parameters:

text (str) – Text to add to the movie poster
bbox (iterable) – Dimensions of the box (width,height) to write text in

Keyword Arguments:

None –

Returns:

Input text (may be updated with extra space between characters): and a pillow ImageFont font object.

Return type:

tuple

video_utils.videotagger.utils.is_id(db_id): Check to ensure the db_id is valid db_id

video_utils.videotagger.utils.replace_chars(*args, repl: str = ' ', **kwargs) → str | list[str]

Replace invalid path characters; ‘&’ replaced with ‘and’

Parameters:

*args (str) – String(s) to replace characters in

Keyword Arguments:

repl (str) – String to replace bad characters with; default is space (’ ‘)
**kwargs –

Returns:

String, or list, with bad values replaced by repl value

video_utils.videotagger.writers module

To write metadata to MP4/MKV files

video_utils.videotagger.writers.add_tag(ele, key, val) → None

Add a tag to XML element for MKV tagging

Parameters:

ele – Element to add tag to
key – Tag name to add
val – Value of the tag

Keyword Arguments:

None. –

Returns:

None

video_utils.videotagger.writers.add_target(ele, level)

Add a target level to the XML file from MKV tagging

Parameters:

ele – Element to add tag to
level – Level of the tag

Keyword Arguments:

None. –

Returns:

An ElementTree SubElement instance

video_utils.videotagger.writers.delete_attachments(fpath: str, nremove: int = 10) → None

Delete a bunch of attachments in an MKV file

Parameters:: fpath (str) – Full path to file

Keywords:: nremove (int): Number of attachments to try to delete

Returns:: None

video_utils.videotagger.writers.get_version(metadata)

Extract version from meta data

Parameters:: metadata (dict) – Metadata for file
Returns:: The version of the file
Return type:: str

video_utils.videotagger.writers.mkv_tagger(fpath: str, metadata: dict) → int

Parse information from the IMDbPY API and write Tag data to MP4 files.

Parameters:

fpath (str) – Full path of file to write metadata to.
metadata (dict) – Meta data where keys are internal metadata keys and values are metadata values

Keyword Arguments:

None. –

Returns:

Returns following values based on completion.

0 : Completed successfully.
1 : Input was NOT and MKV
2 : IMDb ID was not valid
3 : Failed to download information from IMDb AND themoviedb.org
4 : Writing tags is NOT possible
5 : Failed when trying to remove tags from file.
6 : Failed when trying to write tags to file.
10 : IMDbPY not installed AND getTMDb_Info failed to import
11 : File is too large.

Return type:

int

video_utils.videotagger.writers.mp4_tagger(fpath: str, metadata: dict) → int

Parse information from the IMDbPY API and write Tag data to MP4 files.

Parameters:

fpath (str) – Full path of file to write metadata to.
metadata (dict) – Dictionary of meta data where keys are internal metadata keys and values are metadata values

Keyword Arguments:

None –

Returns:

Returns following values based on completion.

0 : Completed successfully.
1 : Input was NOT and MP4
2 : IMDb ID was not valid
3 : Failed to download information from IMDb AND themoviedb.org
4 : Writing tags is NOT possible
5 : Failed when trying to remove tags from file.
6 : Failed when trying to write tags to file.
10 : IMDbPY not installed AND getTMDb_Info failed to import
11 : File is too large

Return type:

int

video_utils.videotagger.writers.to_mkv(metadata: dict) → dict

Convert internal tags to MKV tags

Parameters:: metadata (dict) – Metadata returned by a TVDb or TMDb movie or episde object
Keyword Arguments:: None. –
Returns:: Dictionary with valid MKV tag level and tags as keys
Return type:: dict

video_utils.videotagger.writers.to_mp4(metadata: dict) → dict

Convert internal tags to MP4 tags

Parameters:: metadata (dict) – Metadata returned by a TVDb or TMDb movie or episde object
Keyword Arguments:: None. –
Returns:: Valid MP4 tags as keys and correctly encoded values
Return type:: dict

video_utils.videotagger.writers.write_tags(fpath: str, metadata: dict, **kwargs) → bool

Wrapper for mp4_tagger and mkv_tagger

Parameters:

fpath (str) – Full path of file to write tags to
metadata (dict) – Dictionary with tag/values to write

Keyword argumetns:: **kwargs : Silently ignored

Returns:: True if tags written, False otherwise
Return type:: bool

Module contents

Tag video files

Download and write metadata to video files from TMDb or TVDb

class video_utils.videotagger.TMDb(*args, **kwargs)

Bases: BaseAPI

Class for high-level interaction with TMDb API

byIMDb(IMDbID, **kwargs): Search TMDb for a given Movie or TV episode using IMDb ID

Search TMDb for a given Movie or TV episode

Keyword Arguments:

title (str) – Title of movie OR title of TV Series
episode (str) – Title of TV series episode
seasonEp (tuple) – The season and episode number of the TV series episode

class video_utils.videotagger.TVDb(*args, **kwargs)

Bases: BaseAPI

Class for high-level interaction with TMDb API

byIMDb(IMDbID, season=None, episode=None, **kwargs): Search TVDb for a given Movie or TV episode using IMDb series ID

search(title: str | None = None, kind: str | None = None, episode=None, seasonEp=None, year=None, dvdOrder=None, page=None, nresults=10, **kwargs): Search TVDb for a given Movie or TV episode

video_utils.videotagger.compare_aired_dvd(title, year, season_ep, episode, aired, dvd)

Compare aired and dvd order

Parameters:

title (str) – Title of the series/movie
year (int) – Release year of the series/movie
season_ep (list) – The [season #, episode #] for the series/movie. Will be None is determined to be movie.
episode (str) – Name of the episode of the series. Will be None is determined to be movie.
aired (list) – List of aired-order results returned from search
dvd (list) – List of dvd-order results fretruend from search

video_utils.videotagger.getMetaData(fpath=None, dbID=None, seasonEp=None, version='', **kwargs)

Get Movie or Episode object based on information from file name or dbID

Parameters:

None –

Keyword Arguments:

fpath (str) – Full path, or base name of file to get information for. MUST match naming conventions
dbID (str) – TVDb or TMDb to use for file; overrides any information parsed from file name
seasonEP (tuple,list) – Season and episode number
version (str) – Version for movie; e.g., Extended Edition

Returns:

A TMDbMovie, TMDbEpisode, TVDbMovie, or TVDbEpisode object

video_utils.videotagger package

Subpackages

Submodules

video_utils.videotagger.base_item module

video_utils.videotagger.episode module

video_utils.videotagger.gui module

video_utils.videotagger.movie module

video_utils.videotagger.parsers module

video_utils.videotagger.person module

video_utils.videotagger.readers module

video_utils.videotagger.series module

video_utils.videotagger.tags module

video_utils.videotagger.utils module

video_utils.videotagger.writers module

Module contents