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

mkv_episode_matcher.mkv_to_srt.convert_mkv_to_srt(season_path, mkv_files)

Converts MKV files to SRT format.

Parameters:

  • season_path (str) – The path to the season directory.

  • mkv_files (list) – List of MKV files to convert.

Returns:

None

mkv_episode_matcher.mkv_to_srt.convert_mkv_to_sup(mkv_file, output_dir)

Convert an .mkv file to a .sup file using FFmpeg and pgs2srt.

Parameters:

  • mkv_file (str) – Path to the .mkv file.

  • output_dir (str) – Path to the directory where the .sup file will be saved.

Returns:

Path to the converted .sup file.

Return type:

str

mkv_episode_matcher.mkv_to_srt.perform_ocr(sup_file_path)

Perform OCR on a .sup file and save the extracted text to a .srt file.

Parameters:

sup_file_path (str) – Path to the .sup file.

Episode Matching

mkv_episode_matcher.episode_matcher.check_filename(filename)

Check if the filename is in the correct format.

Parameters:

filename (str) – The filename to check.

Returns:

True if the filename is in the correct format, False otherwise.

Return type:

bool

mkv_episode_matcher.episode_matcher.compare_and_rename_files(srt_files, reference_files, dry_run=False)

Compare the srt files with the reference files and rename the matching mkv files.

Parameters:

  • srt_files (dict) – A dictionary containing the srt files as keys and their contents as values.

  • reference_files (dict) – A dictionary containing the reference files as keys and their contents as values.

  • dry_run (bool, optional) – If True, the function will only log the renaming actions without actually renaming the files. Defaults to False.

mkv_episode_matcher.episode_matcher.compare_text(text1, text2)

Compare two lists of text lines and return the number of matching lines.

Parameters:

  • text1 (list) – List of text lines from the first source.

  • text2 (list) – List of text lines from the second source.

Returns:

Number of matching lines between the two sources.

Return type:

int

mkv_episode_matcher.episode_matcher.extract_season_episode(filename)

Extract the season and episode number from the filename.

Parameters:

filename (str) – The filename to extract the season and episode from.

Returns:

A tuple containing the season and episode number.

Return type:

tuple

mkv_episode_matcher.episode_matcher.extract_srt_text(filepath)

Extracts the text from an SRT file.

Parameters:

filepath (str) – The path to the SRT file.

Returns:

A list of lists, where each inner list represents a block of text from the SRT file.

Each inner list contains the lines of text for that block.

Return type:

list

mkv_episode_matcher.episode_matcher.process_reference_srt_files(series_name)

Process reference SRT files for a given series.

Parameters:

series_name (str) – The name of the series.

Returns:

A dictionary containing the reference files where the keys are the MKV filenames

and the values are the corresponding SRT texts.

Return type:

dict

mkv_episode_matcher.episode_matcher.process_show(season=None, dry_run=False, get_subs=False)

Process the show by downloading episode images and finding matching episodes.

Parameters:

  • season (int, optional) – The season number to process. If provided, only that season will be processed. Defaults to None.

  • force (bool, optional) – Whether to force re-processing of episodes even if they already exist. Defaults to False.

  • dry_run (bool, optional) – Whether to perform a dry run without actually processing the episodes. Defaults to False.

  • threshold (float, optional) – The threshold value for matching episodes. Defaults to None.

mkv_episode_matcher.episode_matcher.process_srt_files(show_dir)

Process all SRT files in the given directory and its subdirectories.

Parameters:

show_dir (str) – The directory path where the SRT files are located.

Returns:

A dictionary containing the SRT file paths as keys and their corresponding text content as values.

Return type:

dict

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