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