mkv_episode_matcher package

Submodules

mkv_episode_matcher.config module

mkv_episode_matcher.config.get_config(file)[source]

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()[source]
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)[source]

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

mkv_episode_matcher.episode_matcher module

mkv_episode_matcher.episode_matcher.check_filename(filename)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

mkv_episode_matcher.mkv_to_srt module

mkv_episode_matcher.mkv_to_srt.convert_mkv_to_srt(season_path, mkv_files)[source]

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)[source]

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)[source]

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.

mkv_episode_matcher.tmdb_client module

class mkv_episode_matcher.tmdb_client.RateLimitedRequest(rate_limit=30, period=1)[source]

Bases: object

A class that represents a rate-limited request object.

rate_limit

Maximum number of requests allowed per period.

Type

int

period

Period in seconds.

Type

int

requests_made

Counter for requests made.

Type

int

start_time

Start time of the current period.

Type

float

lock

Lock for synchronization.

Type

Lock

get(url)[source]

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)[source]

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)[source]

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)[source]

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.utils module

mkv_episode_matcher.utils.check_filename(filename, series_title, season_number, episode_number)[source]

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)[source]

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])[source]

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)[source]

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)[source]

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

Module contents