MKV Episode Matcher API Documentation

CLI

mkv_episode_matcher.__main__.main()

Entry point of the application.

This function is responsible for starting the application, parsing command-line arguments, setting the configuration, and processing the show.

Command-line arguments: –tmdb-api-key: The API key for the TMDb API. If not provided, the function will try to get it from the cache or prompt the user to input it. –show-dir: The main directory of the show. If not provided, the function will prompt the user to input it. –season: The season number to be processed. If not provided, all seasons will be processed. –dry-run: A boolean flag indicating whether to perform a dry run (i.e., not rename any files). If not provided, the function will rename files. –get-subs: A boolean flag indicating whether to download subtitles for the show. If not provided, the function will not download subtitles. –tesseract-path: The path to the tesseract executable. If not provided, the function will try to get it from the cache or prompt the user to input it.

The function logs its progress to two separate log files: one for standard output and one for errors.

Utils

mkv_episode_matcher.utils.check_filename(filename, series_title, season_number, episode_number)

Check if a filename matches the expected naming convention for a series episode.

Parameters:

filename (str) – The filename to be checked.
series_title (str) – The title of the series.
season_number (int) – The season number of the episode.
episode_number (int) – The episode number of the episode.

Returns:

True if the filename matches the expected naming convention, False otherwise.

Return type:

bool

This function checks if the given filename matches the expected naming convention for a series episode. The expected naming convention is ‘{series_title} - S{season_number:02d}E{episode_number:02d}.mkv’. If the filename matches the expected pattern, it returns True; otherwise, it returns False.

Example

If filename = ‘Example - S01E03.mkv’, series_title = ‘Example’, season_number = 1, and episode_number = 3, the function will return True because the filename matches the expected pattern.

mkv_episode_matcher.utils.cleanup_ocr_files(show_dir)

Clean up OCR files generated during the episode matching process.

Parameters:: show_dir (str) – The directory containing the show files.
Returns:: None

This function cleans up the OCR files generated during the episode matching process. It deletes the ‘ocr’ directory and all its contents in each season directory of the show.

mkv_episode_matcher.utils.get_subtitles(show_id, seasons: Set[int])

Retrieves and saves subtitles for a given TV show and seasons.

Parameters:

show_id (int) – The ID of the TV show.
seasons (Set[int]) – A set of season numbers for which subtitles should be retrieved.

Returns:

None

mkv_episode_matcher.utils.rename_episode_file(original_file_path, season_number, episode_number)

Rename an episode file with a standardized naming convention.

Parameters:

original_file_path (str) – The original file path of the episode.
season_number (int) – The season number of the episode.
episode_number (int) – The episode number of the episode.

Returns:

None

This function renames an episode file with a standardized naming convention based on the series title, season number, and episode number. If a file with the intended new name already exists, it appends a numerical suffix to the filename until it finds a unique name.

Example

If original_file_path = ‘/path/to/episode.mkv’, season_number = 1, and episode_number = 3, and the series title is ‘Example’, the function will rename the file to ‘Example - S01E03.mkv’ if no file with that name already exists. If a file with that name already exists, it will be renamed to ‘Example - S01E03_2.mkv’, and so on.

mkv_episode_matcher.utils.scramble_filename(original_file_path, file_number)

Scrambles the filename of the given file path by adding the series title and file number.

Parameters:

original_file_path (str) – The original file path.
file_number (int) – The file number to be added to the filename.

Returns:

None

TMDB Interface

class mkv_episode_matcher.tmdb_client.RateLimitedRequest(rate_limit=30, period=1)

Bases: object

A class that represents a rate-limited request object.

Variables:

rate_limit (int) – Maximum number of requests allowed per period.
period (int) – Period in seconds.
requests_made (int) – Counter for requests made.
start_time (float) – Start time of the current period.
lock (Lock) – Lock for synchronization.

get(url)

Sends a rate-limited GET request to the specified URL.

Parameters:: url (str) – The URL to send the request to.
Returns:: The response object returned by the request.
Return type:: Response

mkv_episode_matcher.tmdb_client.fetch_season_details(show_id, season_number)

Fetch the total number of episodes for a given show and season from the TMDb API.

Parameters:

show_id (str) – The ID of the show on TMDb.
season_number (int) – The season number to fetch details for.

Returns:

The total number of episodes in the season, or 0 if the API request failed.

Return type:

int

mkv_episode_matcher.tmdb_client.fetch_show_id(show_name)

Fetch the TMDb ID for a given show name.

Parameters:: show_name (str) – The name of the show.
Returns:: The TMDb ID of the show, or None if not found.
Return type:: str

mkv_episode_matcher.tmdb_client.get_number_of_seasons(show_id)

Retrieves the number of seasons for a given TV show from the TMDB API.

Parameters: - show_id (int): The ID of the TV show.

Returns: - num_seasons (int): The number of seasons for the TV show.

Raises: - requests.HTTPError: If there is an error while making the API request.

mkv_episode_matcher.tmdb_client.get_episode_info(show_name, season, episode)

Get episode information for a given show, season, and episode number.

Parameters:

show_name (str) – The name of the show.
season (int) – The season number.
episode (int) – The episode number.

Returns:

A dictionary containing the episode information.

MKV Conversion

Episode Matching

Configuration

mkv_episode_matcher.config.get_config(file)

Read and return the configuration from the specified file.

Parameters:: file (str) – The path to the configuration file.
Returns:: The configuration settings as a dictionary.
Return type:: dict

mkv_episode_matcher.config.get_total_threads()

mkv_episode_matcher.config.set_config(tmdb_api_key, open_subtitles_api_key, open_subtitles_user_agent, open_subtitles_username, open_subtitles_password, show_dir, file, tesseract_path=None)

Sets the configuration values and writes them to a file.

Parameters:

tmdb_api_key (str) – The API key for TMDB (The Movie Database).
open_subtitles_api_key (str) – The API key for OpenSubtitles.
open_subtitles_user_agent (str) – The user agent for OpenSubtitles.
open_subtitles_username (str) – The username for OpenSubtitles.
open_subtitles_password (str) – The password for OpenSubtitles.
show_dir (str) – The directory where the TV show episodes are located.
file (str) – The path to the configuration file.
tesseract_path (str, optional) – The path to the Tesseract OCR executable.

Returns:

None