Repository navigation
Component Documentation
This document provides detailed information about each tool and module in the CommercialBreaker & Toonami Tools ecosystem.
The tools work together in a specific sequence to create your Toonami channel:
1. LoginToPlex (Optional) → 2. FolderMaker → 3. ToonamiChecker → 4. LineupPrep → 5. BumpEncoder →
6. UncutEncoder → 7. Multilineup → 8. ShowScheduler (Merger) X4 → 9. EpisodeFilter (EpisodeFilter) → 10. GetPlexTimestamps (Optional) →
11. CommercialBreaker →
12. CommercialInjectorPrep → 13. CommercialInjector → 14. BlockMaker (BlockIDCreator) → 15. ShowScheduler (Merger) (again) X4 → 16. CutlessFinalizer (If using cutless mode) → 17. ExtraBumps (FileProcessor) (Optional) → 18. PlexAutoSplitter (Optional) → 19. PlexSplitRenamer (Optional) → 20. PlexToDizqueTV/PlexToTunarr → 21. DizqueTVManager (FlexInjector) (If using DizqueTV)
File: ToonamiTools/LoginToPlex.py
Classes: PlexServerList, PlexLibraryManager, PlexLibraryFetcher
Purpose: Authenticates with Plex, retrieves a list of available Plex servers, and fetches libraries from a selected server. This information is crucial for other tools that interact with the user's Plex media.
Key Features & Process:
PlexServerList Class:
- Purpose: Handles the initial Plex authentication and retrieves a list of servers associated with the user's account.
-
Authentication (
GetPlexTokenmethod):- Uses the
plexauthlibrary to initiate an OAuth flow with Plex.tv. - Constructs a payload with
X-Plex-*headers identifying the application ("Commercial Breaker"). - Obtains an authentication URL (
auth_url) which the user must open in a browser to grant access. - Supports a callback mechanism (
auth_url_callback) to pass theauth_urlto the GUI or other handlers (e.g., for display or automatic opening). If no callback is provided, it defaults to opening the URL in a web browser and printing it to the console. - Waits for the user to authenticate and then retrieves the Plex access token.
- Stores the token (
self.plex_token) and the list of server names (self.plex_servers).
- Uses the
-
Server Listing (
GetPlexServerListmethod):- Calls
GetPlexTokento ensure authentication. - Uses the obtained token to connect to
MyPlexAccount(fromplexapi.myplex). - Fetches the user's resources (Plex servers) and populates
self.plex_serverswith their names.
- Calls
- Inputs: User interaction for browser-based authentication.
-
Outputs:
- Plex authentication token (stored and accessible via
self.plex_token). - List of Plex server names (stored and accessible via
self.plex_servers). - Authentication URL (passed to callback or opened in browser).
- Plex authentication token (stored and accessible via
PlexLibraryManager Class:
- Purpose: Given a selected Plex server name and a token, it connects to that server and retrieves its base URL.
-
Details Fetching (
GetPlexDetailsmethod):- Takes the selected server name and Plex token.
- Connects to
MyPlexAccountusing the token. - Finds the specified server resource from the account's resources.
- Connects to the selected Plex server (
selected_resource.connect()). - Stores the server's base URL (
plex._baseurl) inself.plex_url.
- Inputs: Selected Plex server name, Plex authentication token.
-
Outputs: Plex server base URL (e.g.,
http://localhost:32400).
PlexLibraryFetcher Class:
- Purpose: Fetches a list of library names from a specific Plex server, given its URL and token.
-
Library Fetching (
GetPlexLibrariesmethod):- Takes the Plex server URL and token.
- Connects to the
PlexServerusing the provided URL and token. - Retrieves all library sections (
server.library.sections()). - Populates
self.librarieswith the titles (names) of these libraries.
- Inputs: Plex server base URL, Plex authentication token.
- Outputs: List of library names available on the server.
Workflow Integration:
-
PlexServerListis used first to log in and get available servers. - The user selects a server.
-
PlexLibraryManageruses the selected server name and token to get the server's URL. -
PlexLibraryFetcheruses the server URL and token to get the list of libraries on that server. - The selected libraries (e.g., for anime, Toonami content) and Plex credentials (URL, token) are then stored (typically in
config.pyor a local database byFrontEndLogic.py) for use by other tools.
File: ToonamiTools/ToonamiChecker.py
Classes: ToonamiShowsFetcher, ToonamiChecker
Purpose: Identifies which shows in the user's local anime folder are known to have aired on the configured network (eg. Toonami) by cross-referencing with a list fetched from Wikipedia. It then saves this information, including file paths, to a database.
Key Features & Process:
ToonamiShowsFetcher Class:
-
Purpose: Fetches a list of programs broadcast by a specified network (e.g., "Toonami", configurable via
config.network) from Wikipedia. -
Data Fetching (
get_toonami_showsmethod):- Uses the Wikipedia API (
action=parse) to get the HTML content of the "List of programs broadcast by [network]" page. - Parses the HTML using
BeautifulSoupto find tables with classwikitable. - Iterates through these tables, identifying relevant columns like 'title' (or 'program') and 'year(s) aired' (or 'airdate').
- Extracts show titles and their airing years, cleaning the data (removing footnotes, normalizing years).
- Returns a Pandas DataFrame with 'Title' and 'Year' columns, with duplicates dropped.
- Uses the Wikipedia API (
-
Inputs:
config.network(e.g., "Toonami"). - Outputs: Pandas DataFrame of Toonami shows and their airing years.
ToonamiChecker Class:
- Purpose: Compares the fetched list of Toonami shows with video files in a user-specified anime folder, identifies matches, and saves the results to a SQLite database.
-
Initialization: Takes the path to the user's
anime_folder. -
Video File Scanning (
get_video_filesmethod):- Walks through the
anime_folder(and subfolders) to find video files (e.g., .mkv, .mp4). - Uses regex (
r'^(.*?)(?: - S\d{1,2}E\d{1,2})') to extract the show title from filenames. - Returns a dictionary mapping show titles to a list of their corresponding episode file paths (relative to
anime_folder).
- Walks through the
-
Show Name Normalization (
normalize_and_mapmethod):- Converts show names to lowercase.
- Removes special characters and handles underscores using
unidecodeand regex. - Applies custom name mappings defined in
config.show_name_mappingto handle variations or alternative titles (e.g., "fmab" to "fullmetal alchemist brotherhood").
-
Comparison (
compare_showsmethod):- Fetches Toonami shows using
ToonamiShowsFetcher. - Gets local video files using
get_video_files. - Normalizes both the Wikipedia show titles and the local file show titles using
normalize_and_map. - Compares the normalized lists to find matches.
- For matched shows, it creates a dictionary
toonami_episodesmapping(show_title, episode_filename)to the full, normalized file path of the episode.
- Fetches Toonami shows using
-
Database Saving:
-
save_episodes_to_spreadsheet(method name is a misnomer, saves to DB): Saves thetoonami_episodes(Title, Episode filename, Full_File_Path) to theToonami_Episodestable in the SQLite database (config.network.db). Handles existing data by appending and removing duplicates. -
save_show_names_to_spreadsheet(method name is a misnomer, saves to DB): Saves unique matched show titles to theToonami_Showstable. Handles existing data similarly.
-
-
User Interaction Flow (
prepare_episode_data,process_selected_showsmethods):-
prepare_episode_data: Callscompare_showsand returns unique show names found locally that were on Toonami, along with the fulltoonami_episodesdictionary. This allows the GUI (FrontEndLogic) to present a list of shows for the user to select/deselect. -
process_selected_shows: Takes the user's selection of shows and thetoonami_episodesdata, filters the episodes to only include selected shows, and then saves this filtered data to the database tables.
-
-
Inputs:
-
anime_folder(path to user's anime collection). -
config.network,config.show_name_mapping. - User selection of shows (via
FrontEndLogic).
-
-
Outputs:
- Populates/updates
Toonami_EpisodesandToonami_Showstables in the SQLite database ([config.network].db).
- Populates/updates
Significance: This tool is crucial for identifying relevant content for the Toonami channel, ensuring that only shows that actually aired on the configured network (eg. Toonami) and are present in the user's library, are considered for the lineup. The database tables it creates are used by subsequent tools.
File: ToonamiTools/LineupPrep.py
Class: MediaProcessor
Purpose: Processes bump video files from a specified folder, extracts metadata (show names, placements, versions, colors) based on their filenames, and categorizes them into "nice" (matching known shows and patterns) and "naughty" (not matching) lists. This structured data is saved to a database for use in lineup creation.
Key Features & Process:
-
Initialization:
- Takes a
bump_folderpath. - Loads keywords, show name mappings (
show_name_mapping,show_name_mapping_2,show_name_mapping_3), and colors fromconfig.py.
- Takes a
-
Filename Parsing Logic:
-
Keyword Counting (
count_keywordsmethod): Determines the type of bump (single, double, triple show involvement) based on keywords like "back", "to ads", "generic", "intro", "next", "from", "later" in the filename. Returns 1 for singles, 2 for "from" bumps, 3 for "later" bumps, 0 for generic/robot bumps. -
Show Name Transformation (
_apply_show_name_mapping,_clean_show_namemethods):- Applies multiple levels of show name mappings from
configto the filename. - Cleans show names by removing special characters and normalizing spaces.
- Applies multiple levels of show name mappings from
-
Dynamic Regex Generation (
generate_dynamic_regexmethod): Creates regex patterns based on thecountfromcount_keywordsand a list of knownshows(retrieved from theToonami_Showsdatabase table).-
count == 1(Single show bumps): e.g.,Toonami [Version] [ShowName1] [PlacementKeyword] [AdVersion?] [Color?] -
count == 2(Double show bumps, "from"): e.g.,Toonami [Version] [ShowName1] [PlacementKeyword] [ShowName2] [AdVersion?] [Color?] -
count >= 3(Triple show bumps, "later"): e.g.,Toonami [Version] [Placement1?] [ShowName1] [Placement2] [ShowName2] [Placement3] [ShowName3] [AdVersion?] [Color?] -
count == 0(Generic/Robot bumps): e.g.,Toonami [Version] [robot|clyde] [AdVersion?]
-
-
Data Extraction (
_extract_data_from_patternmethod): Applies the generated regex to the (transformed) filename to extract named groups likeTOONAMI_VERSION,SHOW_NAME_1,PLACEMENT_2,SHOW_NAME_2,AD_VERSION,COLOR, etc.
-
Keyword Counting (
-
File Processing (
_process_data_patternsmethod):- Retrieves all media files (mkv, mp4) from the
bump_folder. - For each file, cleans the filename (removes extension, replaces underscores with spaces).
- Calls
_extract_data_from_patternto get metadata. - Normalizes extracted show names (e.g.,
SHOW_NAME_1) using the lowercase version of the combined mappings. -
Status Setting (
_set_statusmethod):- Sets status to 'nice' if extracted show names are found in the list of known
shows(fromToonami_Showstable) or if the bump is a recognized generic bump (fromconfig.genric_bumps). - Otherwise, sets status to 'naughty'.
- Sets status to 'nice' if extracted show names are found in the list of known
- Appends processed data to either a
new_df(for matches) orno_match_df.
- Retrieves all media files (mkv, mp4) from the
-
Database Interaction (
run,_save_to_sqlmethods):- Connects to the SQLite database (
[config.network].db). - Reads the
Toonami_Showstable to get the list of valid show titles (normalized). - Saves the processed bump data into several tables:
-
nice_list: Bumps with 'nice' status. -
naughty_list: Bumps with 'naughty' status. -
no_match: Files for which no pattern was matched. -
lineup_prep_out: A subset ofnice_list(droppingORIGINAL_FILE_PATHandStatus), which serves as the primary input forBumpEncoder.
-
- Handles existing tables by appending new data and removing duplicates.
- Connects to the SQLite database (
-
Inputs:
-
bump_folder(path to bump files). -
config.py(keywords, show_name_mappings, colors, generic_bumps, network name). -
Toonami_Showstable from the database.
-
-
Outputs:
- Populates/updates
nice_list,naughty_list,no_match, andlineup_prep_outtables in the SQLite database.
- Populates/updates
Significance: This tool is critical for structuring raw bump files into a usable format. It standardizes naming and categorizes bumps, making it possible for subsequent tools like BumpEncoder and ShowScheduler (Merger) to build coherent Toonami lineups. The lineup_prep_out table is the key handoff to the next stage of encoding.
File: ToonamiTools/BumpEncoder.py
Purpose: Processes bump data from the lineup_prep_out database table to create standardized codes for each bump. These codes are used for efficient library management and bump selection during lineup generation by the Merger (ShowScheduler).
Key Features & Process:
-
Input: Reads data from the
lineup_prep_outtable (created byLineupPrep). This table is expected to have columns likePLACEMENT_1,PLACEMENT_2,PLACEMENT_3,SHOW_NAME_1,SHOW_NAME_2,SHOW_NAME_3,TOONAMI_VERSION,AD_VERSION, andCOLOR. -
Show Abbreviation (
get_abbrmethod):- For each unique show name encountered (e.g., in
SHOW_NAME_1), it generates a 3-letter uppercase abbreviation.- If the name has multiple words, it uses the first two letters of the first word and the first letter of the second word (e.g., "Dragon Ball Z" -> "DRB").
- If one word, it uses the first three letters (e.g., "Naruto" -> "NAR").
- If an abbreviation already exists, it appends a number to ensure uniqueness (e.g., "DRB1", "DRB2").
- These abbreviations are stored in an internal dictionary (
self.codes) mapping full names to abbreviations, and this dictionary is later saved to thecodestable in the database. - The method returns a string like
S1:DRB(for Show 1: Dragon Ball Z) orP1:NXT(for Placement 1: Next).
- For each unique show name encountered (e.g., in
-
Code Creation (
create_codemethod):- For each row (bump) in the input DataFrame:
- It generates placement codes (e.g.,
P1:BCKfor "Back") and show codes (e.g.,S1:GNDfor "Gundam") usingget_abbr. - It constructs a composite code string by concatenating:
- Toonami Version (e.g.,
V2.0becomesV2) - Placement and Show codes in order (e.g.,
P1:BCK-S1:GND) - Ad Version (e.g.,
-AV1if present) - Color (e.g.,
-Bif color is "Blue", taking the first letter) - Number of Shows (e.g.,
-NS1for a single show bump,-NS2for double,-NS3for triple).
- Toonami Version (e.g.,
- It generates placement codes (e.g.,
-
Example Code:
V2-P1:BCK-S1:GND-P2:NXT-S2:BLE-AV1-R-NS2(Toonami Version 2.0, Back Gundam, Next Bleach, Ad Version 1, Red, 2 Shows)
- For each row (bump) in the input DataFrame:
-
DataFrame Encoding (
encode_dataframemethod):- Applies
create_codeto each row to generate aCodecolumn. - Extracts
sort_ver(e.g.,2fromV2) andsort_ns(e.g.,1fromNS1) from theCodefor sorting purposes. - Sorts the DataFrame by
sort_verthensort_ns.
- Applies
-
Database Output:
-
codestable: Stores the mapping of full show names (and placement names) to their generated abbreviations (e.g., "Dragon Ball Z" | "DRB"). -
main_datatable: Contains the original bump data along with the newCodecolumn (andsort_ver,sort_nsdropped). -
singles_datatable: A subset ofmain_datacontaining only single-show bumps (Codecontains-NS1). -
multibumps_v8_datatable: A subset ofmain_datacontaining multi-show bumps (Codecontains-NS2or-NS3). (Note: the 'v8' seems hardcoded here in thesave_encoded_dataframesmethod, which might be an oversight if it's meant to be dynamic). -
multibumps_vX_datatables: For each unique Toonami version (sort_ver) found in the multibumps, a separate table is created (e.g.,multibumps_v2_data,multibumps_v9_data).
-
-
Overall Workflow (
encode_and_savemethod):- Reads
lineup_prep_out. - Encodes the DataFrame.
- Saves the various derived DataFrames (
main_data,singles_data,multibumps_vX_data) to the database. - Saves the
codesmapping table to the database.
- Reads
Significance:
- The
BumpEncoderstandardizes bump representation, making it easier for theMerger (ShowScheduler)to identify and sequence bumps based on the shows they feature and their type (single, double, triple, version, etc.). - The
codestable is crucial for theMergerto decode these abbreviations back to full show names when processing the lineup.
File: ToonamiTools/UncutEncoder.py
Class: UncutEncoder
Purpose: Prepares data specifically for an "uncut" Toonami lineup. It identifies episode files from toonami_episodes, assigns them unique BLOCK_IDs, and strategically inserts corresponding intro/generic bumps (from singles_data) before each show block. This process creates the uncut_encoded_data table, which lists all files (episodes and their selected intro bumps) for a continuous uncut viewing experience. This table serves as a comprehensive list of content confirmed for this type of lineup.
Key Features & Process:
-
Initialization:
- Connects to the SQLite database (
[config.network].db).
- Connects to the SQLite database (
-
Bump Data Loading (
load_bumps_datamethod):- Reads bump data from the
singles_datatable (created byBumpEncoder). - Applies show name mappings (from
config.show_name_mapping,_2,_3) to theSHOW_NAME_1column in the loaded bumps data. - Creates a
default_bump_cycleby selecting generic bumps (e.g., containing 'clydes' or 'robot' inSHOW_NAME_1) to be used as a fallback if specific intro bumps are not found.
- Reads bump data from the
-
Episode File Discovery (
find_filesmethod):- Queries the
toonami_episodestable (created byToonamiChecker) forFull_File_Pathof episodes. - Parses each file path to extract show name, season number, and episode number using regex (
r"/([^/]+)/Season (\d+)/[^/]+ - S(\d+)E(\d+)"). - Sorts these episodes by show name, season, and episode number to ensure chronological order.
- For each episode, creates a
BLOCK_IDin the formatSHOW_NAME_SXXEYY(e.g.,FULLMETAL_ALCHEMIST_S01E01). Show names are uppercased, spaces replaced with underscores, and non-alphanumeric characters removed. - Populates
self.file_paths(list of full episode paths) andself.block_ids(list of corresponding block IDs).
- Queries the
-
Intro Bump Insertion (
insert_intro_bumpsmethod):- Iterates through the sorted
file_pathsandblock_ids(in reverse to maintain correct insertion indices). - For each episode (identified by its
block_id):- Extracts and normalizes the show name from the
block_id. - Applies show name mappings.
- Searches
self.bumps_df(loadedsingles_data) for:- Specific "Intro" bumps for that show (where
PLACEMENT_2contains 'Intro'). - If not found, specific "Generic" bumps for that show (where
PLACEMENT_2contains 'Generic'). - If neither is found, uses the next bump from
self.default_bump_cycle.
- Specific "Intro" bumps for that show (where
- Uses
itertools.cyclefor each show's intro/generic bumps (self.intro_bump_cycle,self.generic_bump_cycle) to rotate through available bumps if multiple exist. - Inserts the chosen intro bump's
FULL_FILE_PATHand the episode'sBLOCK_IDat the beginning of theself.file_pathsandself.block_idslists for that show block.
- Extracts and normalizes the show name from the
- Iterates through the sorted
-
Database Output (
create_tablemethod):- Creates a Pandas DataFrame from the final
self.file_pathsandself.block_ids. - Saves this DataFrame to the
uncut_encoded_datatable in the database, replacing it if it exists. This table containsFULL_FILE_PATH(for both bumps and episodes) andBLOCK_ID(repeated for all files within the same block).
- Creates a Pandas DataFrame from the final
-
Overall Workflow (
runmethod):load_bumps_data()find_files()insert_intro_bumps()create_table()
-
Inputs:
-
singles_datatable (for bump information). -
toonami_episodestable (for episode file paths). -
config.py(show name mappings, network name).
-
-
Outputs:
-
uncut_encoded_datatable in the SQLite database. This table represents a sequence of files (bumps and episodes) ready for an uncut Toonami lineup.
-
Significance: UncutEncoder is vital for users wanting a Toonami experience that preserves full episodes while including thematic Toonami intros. The uncut_encoded_data table it produces contains a complete list of all files (episodes and their bumps) that will form the uncut lineup. This table is then used by EpisodeFilter to specifically isolate the episode files from this lineup, ensuring that only these actual content episodes that have associated bumps (and not the bumps) are passed to CommercialBreaker for processing. The BLOCK_ID system ensures that shows are grouped correctly with their intros. This is important as shows that do not have bumps associated with them will not be included in the final lineup.
File: ToonamiTools/Multilineup.py
Class: Multilineup
Purpose: Re-orders multi-show bump tables (e.g., multibumps_vX_data created by BumpEncoder) to create a more logical and flowing sequence of bumps. The goal is to ensure that the "Later" show of one bump becomes the "Now" or "Next" show of the subsequent bump, creating a continuous chain.
Key Features & Process:
-
Initialization:
- Connects to the SQLite database (
[config.network].db). - Initializes
used_rows(a set to track already processed bumps) andrecent_shows(a list to de-prioritize recently featured shows).
- Connects to the SQLite database (
-
Bump Selection Logic:
-
Weighted Selection (
weighted_selectionmethod): Selects a bump from a given DataFrame, applying lower weights to bumps featuring shows that are inself.recent_showsto encourage variety. -
Unused Bumps (
unused_bumpsmethod): Retrieves bumps from a specified table that haven't been used yet (i.e., their index is not inself.used_rows). -
Optimal First Bump (
find_optimal_first_bumpmethod): Tries to select an ideal starting bump for a sequence. It prioritizes bumps where:-
SHOW_NAME_1is not another bump'sSHOW_NAME_3, ANDSHOW_NAME_3is another bump'sSHOW_NAME_1(good starting point). - Or, a variation involving counts of
SHOW_NAME_1vsSHOW_NAME_3occurrences. - Or,
SHOW_NAME_1is theSHOW_NAME_3of multiple other bumps. - If none of the above, it picks the first available bump.
-
-
Next Row Selection (
get_next_rowmethod): This is the core logic for chaining bumps.- If
self.next_show_nameis set (from the previous bump's "Later" or "Next" show):- It tries to find a bump where
PLACEMENT_2is 'next' andSHOW_NAME_1matchesself.next_show_name. Among these, it prioritizes bumps whoseSHOW_NAME_3(the "Later" show) has fewer upcoming "Now" bumps available, aiming to use up rarer continuations first. - If no such 'next' bump is found, it looks for 'next from' or 'from' bumps where
SHOW_NAME_2matchesself.next_show_name.
- It tries to find a bump where
- If no specific
next_show_nameis set or no suitable continuation is found, it falls back to a weighted random selection from all unused bumps. - Once a row is selected, its index is added to
self.used_rows. -
self.next_show_nameis updated based on the selected bump'sSHOW_NAME_3(ifPLACEMENT_2is 'next') orSHOW_NAME_1.
- If
-
Weighted Selection (
-
Table Reordering (
reorder_table,reorder_all_tablesmethods):-
reorder_table:- Takes a
table_name(e.g.,multibumps_v2_data). - Creates a new table with
_reorderedsuffix (e.g.,multibumps_v2_data_reordered). - Selects an optimal first bump using
find_optimal_first_bump. - Writes this first bump to the new reordered table.
- Enters a loop:
- Gets the next bump using
get_next_row. - Writes it to the reordered table.
- Updates
self.recent_shows.
- Gets the next bump using
- Continues until all bumps from the original table are used.
- Takes a
-
reorder_all_tables: Iterates through potential table names (multibumps_v0_datatomultibumps_v9_data) and callsreorder_tablefor each one that exists.
-
-
Inputs:
- Various
multibumps_vX_datatables from the database (created byBumpEncoder). -
config.network(for database name).
- Various
-
Outputs:
- Creates new tables in the database with
_reorderedsuffix (e.g.,multibumps_v2_data_reordered), containing the bumps in a more logical sequence.
- Creates new tables in the database with
Significance: Multilineup is crucial for creating engaging Toonami blocks where the announcements flow logically from one multi-show bump to the next. The reordered tables it produces are used by the ShowScheduler (Merger) to construct the final channel lineup, ensuring that transitions between shows are smooth and make narrative sense based on the bump announcements.
File: ToonamiTools/BlockMaker.py (Class: BlockMaker)
Purpose: Processes data from the commercial_injector table (which contains paths to cut episode parts and associated metadata), generates a standardized BLOCK_ID for each entry, and saves the result to the commercial_injector_final table. The BLOCK_ID groups all parts of the same original episode, which is crucial for subsequent lineup scheduling.
Key Features & Process:
-
Initialization (
__init__method):- Connects to the SQLite database (
[config.network].db).
- Connects to the SQLite database (
-
Data Loading (
load_datamethod):- Reads all data from the
commercial_injectortable into a Pandas DataFrame. This table is expected to containFULL_FILE_PATHfor cut episode parts.
- Reads all data from the
-
Block ID Generation (
create_block_idstatic method):- Takes a
FULL_FILE_PATHas input. - Normalizes the path and splits it into components.
- Extracts the series name (assumed to be the third-to-last component of the path, e.g., the show's folder name).
- Uses a regex (
r'S\d{2}E\d{2}') to find a season and episode pattern (e.g., "S01E01") in the filename (last path component). - If the pattern is found, it constructs a
block_idstring:SERIES_NAME-SXXEYY. - This
block_idis then normalized by replacing non-alphanumeric characters with underscores and converting to uppercase (e.g.,FULLMETAL_ALCHEMIST_BROTHERHOOD-S01E01). - Returns
Noneif the season/episode pattern is not found in the filename.
- Takes a
-
Block ID Assignment (
assign_block_idsmethod):- Applies the
create_block_idmethod to theFULL_FILE_PATHcolumn of the DataFrame to create a newBLOCK_IDcolumn. - Iterates through the DataFrame to handle any rows where
BLOCK_IDmight beNone(due tocreate_block_idnot finding the pattern):- If a
BLOCK_IDisNone, it attempts to fill it with theBLOCK_IDfrom the next row. - If the next row is also
Noneor doesn't exist, it uses theself.last_block_id(the last successfully generated/propagatedBLOCK_IDfrom a previous row). This ensures that all parts related to an episode (even if some filenames are non-standard) get grouped under the sameBLOCK_IDas long as at least one part's filename allows ID generation.
- If a
- Applies the
-
Data Saving (
save_datamethod):- Drops the
SHOW_NAME_1andSeason and Episodecolumns from the DataFrame (as this information is now encapsulated or made redundant by theBLOCK_IDand the structured path). - Saves the modified DataFrame (now including the
BLOCK_IDcolumn and with dropped columns) to a new table namedcommercial_injector_finalin the database, replacing it if it already exists.
- Drops the
-
Overall Workflow (
runmethod):load_data()assign_block_ids()save_data()
Inputs:
-
commercial_injectortable from the SQLite database ([config.network].db). This table should containFULL_FILE_PATHfor cut episode segments. - File path structure that generally includes
ShowName/SeasonXX/ShowName - SXXEXX - PartX.ext.
Outputs:
-
commercial_injector_finaltable in the SQLite database. This table includes the original data fromcommercial_injectorplus aBLOCK_IDcolumn, and excludes theSHOW_NAME_1andSeason and Episodecolumns.
Significance: Consistent BLOCK_IDs are essential for the ShowScheduler (Merger) to correctly group all parts of a cut episode (e.g., intro, content part 1, content part 2, outro) and schedule them together as a single logical "episode block." This tool ensures that even if filenames are slightly inconsistent, related parts are correctly associated, which is crucial for building a coherent lineup from pre-cut content. It prepares the data specifically for the "cut content" path of the ShowScheduler.
File: ToonamiTools/Merger.py
Purpose: Creates cohesive lineups and manages show sequencing by merging bump lists with episode blocks.
Key Functionality & Configuration:
-
Dual Functionality:
-
Initial Run: Creates a base lineup structure from a bump list (e.g.,
multibumps_v9_data_reorderedfromconfig.TOONAMI_CONFIG[version]["merger_bump_list"]) and an input episode data table (e.g.,commercial_injector_finaloruncut_encoded_datafromconfig.TOONAMI_CONFIG[version]["encoder_in"]). - Second Run: Can be used to integrate commercial-cut content or refine lineups.
-
Initial Run: Creates a base lineup structure from a bump list (e.g.,
-
Input Tables:
-
encoder_table: Contains bump data with encoded show information (e.g.,multibumps_v9_data_reordered). This table has aCodecolumn that indicates the shows involved in a bump (e.g.,-S1:DBZ-S2:GITS-NS3for a triple bump). -
commercial_table: Contains episode data, includingFULL_FILE_PATHandBLOCK_ID(e.g.,commercial_injector_finalfor cut content,uncut_encoded_datafor uncut).
-
-
Output Table: Saves the generated lineup to a specified table (e.g.,
lineup_v9fromconfig.TOONAMI_CONFIG[version]["merger_out"]). -
Show Name Normalization: Uses
config.show_name_mappingto standardize show names. -
Episode Block Management:
-
reuse_episode_blocks(boolean, constructor arg): IfTrue, episode blocks for a show are reused from the beginning once exhausted. IfFalse, the show is skipped once all its blocks are used. -
continue_from_last_used_episode_block(boolean, constructor arg): IfTrue, the scheduler attempts to continue from the last used episode block for each show (persisted inlast_used_episode_blocktable). Otherwise, it resets tracking. -
shows_with_no_more_blocks(internal set): Tracks shows that have run out of blocks whenreuse_episode_blocksisFalse.
-
-
Uncut Mode:
-
uncut(boolean, constructor arg, also inconfig.TOONAMI_CONFIG[version]["uncut"]): IfTrue, schedules for uncut content. This also influencesapply_ns3_logic.
-
Core Scheduling Logic (generate_schedule method):
- Iterates through the
encoder_df(bump list). - For each bump (
row), extracts the shows involved (showslist fromrow["Code"]) and the bump code itself (code_value). -
NS2/NS3 Bump Handling (
apply_ns3_logic- enabled if NS2 bumps exist and not inuncutmode):-
NS2 Bumps (e.g.,
Codecontains-NS2): These are typically "Next Show" transitions involving two shows (Show A, then Show B).- The scheduler ensures continuity: if the
last_show_namefrom the previous segment isn't Show B, it first inserts an episode block of Show B. - Then, the NS2 bump file itself is added.
- Finally, an episode block of Show A is added (often with
delete_intro=Truefor the first part of Show A).
- The scheduler ensures continuity: if the
-
NS3 Bumps (e.g.,
Codecontains-NS3): These are typically "Now Show A, Next Show B, Later Show C" transitions.-
_detect_ns2_ns3_chain: If an NS3 bump for Show A immediately follows an NS2 bump that also featured Show A, the first show (Show A) in the NS3 list is skipped to avoid repetition. - The NS3 bump file is added.
- Episode blocks for the shows in the NS3 list (potentially adjusted by the chain detection or if the next bump is also an NS3 for the same tail show) are inserted sequentially.
-
-
_attempt_interweave: Adds a blank row for spacing if the next bump starts with a different show and there's no direct NS2/NS3 handoff.
-
NS2 Bumps (e.g.,
-
Episode Block Insertion (
_insert_episode_block):-
get_next_episode_block(show): Retrieves the next availableBLOCK_IDfor the givenshowfromcommercial_injector_df.- Considers
last_used_episode_blockifcontinue_from_last_used_episode_blockis true. - Handles
reuse_episode_blocksor adds toshows_with_no_more_blocks.
- Considers
- The files corresponding to the selected
BLOCK_IDare fetched fromcommercial_injector_dfand appended to thefinal_df. -
delete_intro: If true (usually after a transition bump), the first file of the block (assumed to be an intro) is skipped.
-
-
NS3 Special Index Adjustment (
adjust_final_df_based_on_ns3_indices):- If
apply_ns3_logicis true,get_ns3_special_indicesfinds NS3 bumps that immediately follow an NS2 bump for the same show. - A simplistic reordering attempts to swap the NS3 bump with the content two rows above it, then removes the original NS3 bump row. This aims to fix specific transition flow issues.
- If
-
Adding Unused Shows (
add_unused_shows_to_schedule):- If
continue_from_last_used_episode_blockis true, this logic attempts to insert blocks from shows not yet used in the current schedule. -
locate_lines_of_fourth_unique_block_id: Identifies "anchor points" in the schedule (just before the fourth unique block ID within an NS3 segment) to insert these unused shows, aiming for variety.
- If
Anti-Repetition & Continuity:
- The core logic of processing bumps sequentially and using
last_show_namehelps maintain continuity. - NS2/NS3 handling is specifically designed for complex multi-show transitions.
-
reuse_episode_blocksandcontinue_from_last_used_episode_blockmanage how shows are revisited or continued across multiple schedule generations.
Example Simplified Flow for a Triple Bump ("Now ShowA, Next ShowB, Later ShowC" - an NS3 type):
- NS3 Bump File (e.g.,
NOW_A_NEXT_B_LATER_C.mp4) is added to schedule. - Episode Block for ShowA is added.
- Episode Block for ShowB is added.
- Episode Block for ShowC is added. The next bump processed would ideally start with "Now ShowC...".
Database Interaction:
- Reads from:
encoder_table,commercial_table,codes,last_used_episode_block(optional). - Writes to:
save_table,last_used_episode_block(optional). All table names are typically sourced fromconfig.TOONAMI_CONFIGbased on the selected Toonami version.
File: ToonamiTools/EpisodeFilter.py
Purpose: Processes a lineup table (e.g., uncut_encoded_data from UncutEncoder, or a lineup_vX table from ShowScheduler) which contains a mix of episode file paths and bump file paths. Its primary function is to isolate the actual episode files by filtering out bump files. Bump files are identified by checking if their FULL_FILE_PATH contains the config.network name (e.g., "Toonami"), as bump filenames conventionally include the network name. The resulting list of episode files is then used for further processing, typically by CommercialBreaker or for file relocation.
Operating Modes (controlled by the prepopulate flag in the run method):
-
Filter and Move (
prepopulate=False): After filtering out bumps and identifying episode files, it physically relocates the entire parent show directories of these episode files to a specified target directory (e.g.,toonami_filtered). -
Prepopulate Selection (
prepopulate=True): After filtering out bumps, it collects and returns a list of unique file paths for the identified episode files without moving them. This list is typically used as direct input forCommercialBreaker.
Filtering Logic:
- An input table (e.g.,
uncut_encoded_dataorlineup_v8_uncut) is read from the database. This table represents a lineup that includes both episode files and bump files. - The core filter
~df['FULL_FILE_PATH'].str.lower().str.contains(config.network.lower(), na=False)is applied:- Bump files (e.g., "Toonami 3.0 Fullmetal Alchemist To Ads.mp4") will match
config.network.lower()and thus be excluded by the~(NOT operator). - Episode files (e.g., "/path/to/Fullmetal Alchemist/Season 1/Fullmetal Alchemist - S01E01.mkv") typically will not match
config.network.lower()in their path and thus be included.
- Bump files (e.g., "Toonami 3.0 Fullmetal Alchemist To Ads.mp4") will match
- The
CodeandBLOCK_IDcolumns are dropped from the filtered data, as the focus is on the episode file paths themselves. - The result (a list of episode file paths, or their parent directories for moving) is either written to a new table (e.g.,
lineup_v8_uncut_filtered), used to move files, or returned as a list of paths.
Assumptions:
- The input table to
EpisodeFiltercontainsFULL_FILE_PATHfor both episodes and bumps. - Bump filenames consistently include the network name, allowing them to be filtered out.
Significance: EpisodeFilter plays a crucial role in optimizing the media processing pipeline by ensuring that the time-intensive CommercialBreaker tool only processes actual episode content that will be used in the final lineup. By intelligently filtering out bumps from a pre-defined lineup (which already reflects show/bump availability), it prevents unnecessary processing of bump files and episode files that do not have associated bumps, which do not require commercial detection. This targeted approach significantly speeds up the overall workflow, especially when dealing with large media libraries and numerous bumps. In "Filter and Move" mode, it also helps organize the relevant episode source files into a dedicated processing or staging area.
File: ToonamiTools/GetTimestampPlex.py
Class: GetPlexTimestamps
Purpose: Fetches "skip intro" marker timestamps from a Plex server for episodes in a specified library. These timestamps are saved to a text file and can be used by CommercialBreaker as a fallback or primary method for identifying intro segments, especially in "Low Power Mode" or "Fast Mode".
Key Features & Process:
-
Initialization:
- Takes Plex server URL (
plex_url), Plex token (plex_token), the name of the Plex library to scan (library_name), and a directory to save the output (save_dir). - Connects to the Plex server using
plexapi.server.PlexServer.
- Takes Plex server URL (
-
Timestamp Extraction (
runmethod):- Retrieves all media items (shows/movies) from the specified Plex library section.
- For each media item, it iterates through its episodes.
- For each episode, it fetches the item's full metadata using
plex.fetchItem(f'/library/metadata/{episode.ratingKey}'). - Checks if the item has
markers(Plex's feature for things like intros, credits). - If 'intro' markers exist:
- Extracts the
startandendtime offsets (in milliseconds). - Converts these to seconds.
- Retrieves the episode's file path (
item.media[0].parts[0].file). - Extracts the filename from the path.
- Writes a line to
intros.txt(in thesave_dir) in the format:filename.ext = end_time_in_seconds. (The commented-out line suggests it previously might have saved start and end times).
- Extracts the
-
Inputs:
- Plex server URL and token.
- Name of the Plex library containing anime.
- Output directory for the timestamp file.
-
Outputs:
- A text file named
intros.txtin thesave_dir. Each line contains an episode filename and the end timestamp of its intro in seconds (e.g.,MyShow - S01E01.mkv = 90.500).
- A text file named
- Error Handling: Basic print statements for progress and loaded items. Does not explicitly show robust error handling for network or Plex API issues in the provided snippet.
Significance:
- Provides an alternative or supplementary method for
CommercialBreakerto identify intro segments without relying solely on black frame/silence detection. - Can be much faster than visual/audio analysis if Plex has already marked intros.
- The output
intros.txtis read byCommercialBreakerLogic(specificallyTimestampManager) to create cut points.
Location: ComBreak/ directory
Purpose: Complete commercial break detection and processing system
The CommercialBreaker system is composed of several specialized components working together to detect commercial break points in videos and optionally cut files at those points.
-
CommercialBreakerLogic.py (
CommercialBreakerLogic): Main orchestrator that coordinates the entire detection and cutting process, called by all UIs. -
CommercialBreakerGUI.py (
CommercialBreakerGUI): Main GUI for ComBreak, handles user input and mode selection. -
EnhancedInputHandler.py (
EnhancedInputHandler): Handles both folder and file selection modes, consolidates mixed inputs. -
VideoLoader.py (
VideoLoader): Manages video file discovery and filtering, provides frame-by-frame access. -
VideoFileManager.py (
VideoFilesManager): Tracks processing state and file organization, singleton pattern.
-
ChapterExtractor.py (
ChapterExtractor): Examines video metadata for embedded chapter markers (highest priority, fastest, most reliable). -
SilentBlackFrameDetector.py (
SilentBlackFrameDetector): Orchestrates complex detection process using:- SilenceDetector: Identifies silent periods using FFmpeg
- VideoPreprocessor: Downscales only silent segments
- BlackFrameAnalyzer: Analyzes frames for darkness
-
TimestampManager.py (
TimestampManager): Handles timestamp file operations, two-stage filtering, Plex timestamp integration -
VirtualCut.py (
VirtualCut): Used only in Cutless Mode to create virtual references instead of physical cuts, outputting to thecommercial_injector_preptable.
- Low Power Mode: Chapter Extraction → Plex Timestamps (from plex_timestamps.txt)
- Fast Mode: Chapter Extraction → Plex Timestamps → Silent Black Frame Detection
- Normal Mode: Chapter Extraction → Silent Black Frame Detection → Plex Timestamps (fallback)
Note: Fast Mode and Low Power Mode are mutually exclusive (cannot be enabled together). Destructive Mode and Cutless Mode are also mutually exclusive. This is enforced in the GUI and logic.
-
VideoCutter.py (
VideoCutter): Handles the actual file processing- Traditional Mode: Physically cuts videos at detected timestamps, creates multiple files per episode (Part 1, Part 2, etc.)
-
Cutless Mode: Uses
VirtualCutto create virtual references, no physical files are created, only database entries
- ProgressManager: Tracks progress across three distinct processing phases (silence detection, downscaling, frame analysis) with accurate pre-calculation of total steps.
- Resilient design: Process continues even if individual files fail, progress tracking remains accurate, resource cleanup is guaranteed.
For a full technical breakdown, see docs/ComBreakDocs in the repository.
File: ToonamiTools/ExtraBumps.py
Class: FileProcessor
Purpose: Integrates additional video files (referred to as "special bumps" or "bonus" content) from a specified input directory into existing lineup tables in the database. These are inserted at random intervals.
Key Features & Process:
-
Initialization:
- Takes an
input_dir(where the special bump/bonus video files are located). - Connects to the SQLite database (
[config.network].db). - Retrieves a list of all table names in the database that match the pattern
lineup_v%(e.g.,lineup_v2,lineup_v8_uncut). These are the target lineup tables to which bonus content will be added.
- Takes an
-
File Processing (
process_filesmethod):- Iterates through each identified
lineup_name(e.g.,lineup_v2). - Reads the corresponding lineup table from the database into a Pandas DataFrame (
df_input). - Walks through the
self.input_dirto find all files and collects their full paths. - Creates a new DataFrame (
df) from these collected bonus file paths, with columnsFULL_FILE_PATH,Code(empty string), andBLOCK_ID(empty string). - Shuffles this
dfof bonus files randomly. -
Insertion Logic:
- Iterates through the shuffled bonus files.
- For each bonus file, it calculates an insertion position (
pos) in thedf_input(the original lineup). The position is incremented by a random integer between 3 and 7 from the previous insertion point. This ensures bonus content is spread out. - If the calculated
posis within the bounds ofdf_input, the current bonus file (as a single-row DataFrame) is inserted at that position. - The loop breaks if
posgoes beyond the length ofdf_input.
-
Database Output:
- The modified
df_input(now containing the inserted bonus files) is saved back to the database under a new table name, which is the originallineup_namewith_bonusappended (e.g.,lineup_v2_bonus). The original table is replaced if the_bonustable already exists.
- The modified
- Iterates through each identified
-
Inputs:
-
input_dir: A folder containing video files to be used as bonus content. - Existing
lineup_v%tables in the SQLite database. -
config.network(for database name).
-
-
Outputs:
- Creates new tables in the database with
_bonussuffix (e.g.,lineup_v2_bonus), containing the original lineup data interspersed with the bonus content.
- Creates new tables in the database with
Significance: This tool allows for the dynamic enrichment of pre-generated Toonami lineups with additional content like special Toonami event bumps, music videos, or any other short video pieces the user wants to include, adding variety and customization to the final channel.
File: ToonamiTools/PlexAutoSplitter.py
Class: PlexAutoSplitter
Purpose: Automates the "split apart" action in Plex for media items that Plex has incorrectly merged (i.e., a single library entry points to multiple distinct video files). This is crucial for ensuring each video part or episode is treated as a separate entity for accurate lineup generation and playback.
Problem Solved:
Plex's automatic matching can sometimes incorrectly merge multiple video files (e.g., parts of a multi-part episode, or different episodes that Plex thinks are the same) into a single item in the library. PlexAutoSplitter identifies these merged items and programmatically splits them.
Key Features & Process:
-
Initialization:
- Takes Plex URL, token, and a timeout value from
config.py. - Initializes a
PlexServerinstance from theplexapi.serverlibrary. - Sets up a Selenium WebDriver (Chrome) with specific options (e.g., headless, disabling GPU, specific user agent).
- Takes Plex URL, token, and a timeout value from
-
Library Iteration:
- The main method
split_plex_items_in_library(library_name, series_title=None, season_number=None, episode_number=None)iterates through a specified Plex library. - It can target an entire library, a specific series, a season within a series, or a particular episode.
- The main method
-
Merged Item Identification (
check_and_split_itemmethod):- For each video item, it checks if
len(item.media)> 1. If true, it indicates that Plex has associated multiple media files with this single library entry, meaning it's a merged item.
- For each video item, it checks if
-
Splitting Action (
split_itemmethod):- If a merged item is found:
- Constructs the Plex Web URL for the item's pre-play screen (e.g.,
http://<plex_url>/web/index.html#!/server/<server_machine_id>/details?key=%2Flibrary%2Fmetadata%2F<item_rating_key>). - Uses Selenium to navigate to this URL.
- Locates and clicks the "more actions" button (ellipsis).
- Locates and clicks the "Split Apart" option from the context menu.
- Waits for a confirmation modal and clicks "Yes" (or "OK" - the exact text might vary and is handled by trying multiple XPath selectors).
- Logs the action and waits for a short period for Plex to process the split.
- Constructs the Plex Web URL for the item's pre-play screen (e.g.,
- If a merged item is found:
-
Error Handling:
- Includes
try-exceptblocks to catchNoSuchElementException(if UI elements are not found) and other general exceptions during the Selenium interactions. - Ensures the WebDriver quits properly using a
finallyblock.
- Includes
-
Configuration:
- Relies on
config.PLEX_URL,config.PLEX_TOKEN, andconfig.PLEX_TIMEOUT. -
config.CHROME_DRIVER_PATHspecifies the path to the ChromeDriver executable.
- Relies on
Technical Approach:
- Combines
plexapifor library navigation and item metadata retrieval. - Uses
seleniumfor web browser automation to perform UI actions (clicking buttons) that are not directly available via the Plex API. This is necessary because the "Split Apart" functionality is primarily a Plex Web UI feature.
Usage:
- Typically run after adding new media to Plex or if merged items are suspected.
- Can be invoked programmatically by other scripts or run manually.
Dependencies:
plexapiselenium- Google Chrome browser and a compatible ChromeDriver.
Limitations:
- Relies on the stability of Plex Web UI element selectors (XPaths). Changes in Plex's UI could break the splitting functionality.
- Requires a running Plex server and valid credentials.
- The process can be slow as it involves browser automation and page loads for each split action.
File: ToonamiTools/RenameSplitPlex.py
Class: PlexLibraryUpdater
Purpose: After items in a Plex library have been split (e.g., by PlexAutoSplitter), this tool renames them based on their underlying filenames. This is often necessary because splitting items in Plex might leave them with generic or identical titles, and this tool ensures their titles in Plex match the actual content.
Key Features & Process:
-
Initialization:
- Takes Plex URL (
plex_url), Plex token (plex_token), and the targetlibrary_name. - Initializes a
PlexServerinstance and gets the specified library section. - Defines a regex pattern
self.pattern = r'\/([^\/]+)\.mp4$'(or similar for other extensions if generalized) to extract the base filename (without extension and preceding path) from the full file path stored in Plex.
- Takes Plex URL (
-
Title Updating (
update_titlesmethod):- Iterates through all video items in the specified Plex library (
self.library.all()). - For each
videoitem:- Retrieves the full file path of its primary media part (
video.media[0].parts[0].file). - Applies the regex
self.patternto this file path to extract the desired base filename, which becomes thenew_title. - If the regex matches and a
new_titleis extracted:- It checks if the video's current title (
video.title) already matches thenew_title. If so, it skips updating to avoid unnecessary API calls. - If the titles differ, it edits the Plex item's title using
video.edit(**{'title.value': new_title, 'title.locked': 1}).-
title.value: Sets the new title. -
title.locked: Sets the title lock to 1 (locked), preventing Plex from automatically changing it later based on its own metadata agents.
-
- Logs the title update.
- It checks if the video's current title (
- If the regex does not match the file path, it logs that the pattern didn't match.
- Retrieves the full file path of its primary media part (
- Iterates through all video items in the specified Plex library (
-
Inputs:
- Plex server URL and token.
- Name of the Plex library to process.
-
Actions:
- Directly modifies the titles of items within the Plex library.
-
Dependencies:
-
plexapilibrary. - A running Plex server with accessible credentials.
-
Significance:
- Complements
PlexAutoSplitter. After splitting, items might have generic names (e.g., "Show Title - Part 1", "Show Title - Part 1" again if Plex didn't differentiate). This tool ensures each item gets a unique and descriptive title based on its filename (e.g., "Show Title - S01E01 - Episode Name - Part 1"). - Locking the title (
title.locked: 1) is important to maintain these custom names against Plex's own metadata refreshes. - Provides clarity in the Plex interface and ensures that downstream tools that rely on Plex item titles can correctly identify content.
File: ToonamiTools/PlexToDizqueTV.py
Class: PlexToDizqueTVSimplified
Purpose: Transfers a curated lineup of Plex media items (defined in a database table) to a specified DizqueTV channel. It handles fetching media from Plex, converting them to DizqueTV program format, and adding them to the channel. It supports "Cutless Mode" by including custom start/end times if provided in the lineup data.
Key Features & Process:
-
Initialization:
- Takes Plex URL/token, names of anime and Toonami Plex libraries, the database
tablename containing the lineup, DizqueTV URL, targetchannel_number, and acutless_modeboolean flag. - Plex and DizqueTV API clients are initialized in the
runmethod.
- Takes Plex URL/token, names of anime and Toonami Plex libraries, the database
-
Library Initialization (
_init_librariesmethod):- Caches media items from the specified Plex libraries (
anime_libraryandtoonami_library) into dictionaries (self.anime_media,self.toonami_media) mapping filenames to Plex item objects. This speeds up lookup. - If
cutless_modeisFalse, loading theanime_libraryis skipped (as cut content is expected to be in thetoonami_library). - Handles both TV shows (iterating episodes) and movies.
- Caches media items from the specified Plex libraries (
-
Media Item Retrieval (
get_media_item,_find_in_librarymethods):- Given a
file_pathfrom the lineup table:- Determines the primary Plex library to search using
determine_library(ifcutless_modeis true, it checks filename for network name; otherwise, defaults totoonami_library). - Searches the cached media dictionaries first by full filename, then by filename without extension.
- Includes Unicode normalization (
_normalize_unicode) for filenames with special characters. - If
cutless_modeis true and the item is not found by filename in the anime library, it attempts to parse show title, season, and episode from the filename and find it viaplex.library.section(anime_library).get(show_title).episode(season, episode), with fuzzy matching for show titles (fuzzy_find_show). - If not found in the primary library, it tries the secondary library (if applicable).
- Determines the primary Plex library to search using
- Given a
-
Lineup Processing (
runmethod):- Connects to Plex and DizqueTV.
- Loads the lineup DataFrame from the specified database
table. - Iterates through each row (media item) in the lineup DataFrame:
- Retrieves the
FULL_FILE_PATH. - Calls
get_media_itemto find the corresponding Plex item. - If the Plex item is found:
- Converts the Plex item to a DizqueTV program object using
dtv.convert_plex_item_to_program(). - If the lineup row contains
startTimeorendTime(used in Cutless Mode), these are added to the DizqueTV program's_dataasseekPositionandendPosition(in milliseconds). - Adds the configured program to a list
to_add.
- Converts the Plex item to a DizqueTV program object using
- If the Plex item is not found, it's added to a
missing_fileslist.
- Retrieves the
- If any files are missing, an exception is raised.
-
DizqueTV Channel Update:
- Retrieves the DizqueTV channel by
channel_number. If not found, creates a new one. - Deletes all existing programs from the channel.
- Adds the new list of programs (
to_add) to the channel.
- Retrieves the DizqueTV channel by
-
Inputs:
- Plex server URL/token, anime library name, Toonami library name.
- DizqueTV server URL, target channel number.
- Name of the SQLite database table containing the ordered lineup (with
FULL_FILE_PATH, and optionalstartTime,endTimecolumns). -
cutless_modeflag. -
config.pyfor show name mappings (used infuzzy_find_show).
-
Outputs/Actions:
- Modifies a DizqueTV channel by replacing its programming with the new lineup.
- Logs progress and any missing files to the console.
Significance: This is the component responsible for translating the abstract lineup (stored in the database) into a playable channel on DizqueTV. Its support for startTime and endTime is critical for the "Cutless Mode" functionality, allowing DizqueTV to play specific segments of original, uncut files to simulate commercial breaks.
File: ToonamiTools/PlexToTunarr.py
Class: PlexToTunarr
Purpose: Transfers a curated lineup of Plex media items (defined in a database table) to a specified Tunarr channel. It fetches media from Plex, converts them into Tunarr program format, and updates the channel programming. It also handles the insertion of "flex" (placeholder/filler) content if Toonami-branded items appear consecutively without an intro.
Key Features & Process:
-
Initialization:
- Takes Plex URL/token, Plex
library_name(typically the Toonami library), databasetablename for the lineup, Tunarr URL, targetchannel_number,flex_duration, and an optionalchannel_name. - Connects to Plex.
- Loads lineup data from the specified SQLite
tableinto a DataFrame. - Initializes
plex_source_infoby callingget_plex_source_infoto find or create the Plex media source ID in Tunarr.
- Takes Plex URL/token, Plex
-
Tunarr Media Source Management (
get_plex_source_info,get_plex_media_source_id,create_plex_media_source):- Retrieves existing media sources from Tunarr (
/api/media-sources). - Tries to find a Plex source matching the
plex_url. - If no exact match, uses the first available Plex source.
- If no Plex source exists, attempts to create one automatically using the provided Plex URL and token.
- Retrieves existing media sources from Tunarr (
-
Tunarr Channel Management (
get_channel_by_number,create_channel,delete_all_programs):-
get_channel_by_number: Fetches channel details from Tunarr. -
create_channel: Creates a new channel in Tunarr if one doesn't exist, using default settings and the first available transcode config. -
delete_all_programs: Clears existing programming from a channel by posting an empty lineup.
-
-
Plex Item to Tunarr Program Conversion (
build_full_programmethod):- Takes a Plex item object.
- Constructs a Tunarr program dictionary with fields like
type: "content",externalSourceType: "plex",externalSourceId(fromplex_source_info),date,duration,serverFileKey,serverFilePath,externalKey(Plex ratingKey),summary,title,uniqueId.
-
Lineup Posting with Flex Injection (
post_manual_lineupmethod):- This is the core logic for building the Tunarr channel's programming.
- Iterates through the
plex_items(derived from the input DB table). -
Program Array (
programs):- For each unique Plex item,
build_full_programis called. - The program's
originalIndexis set. - A single "flex" program object is created if needed (type: "flex", duration from
self.flex_duration).
- For each unique Plex item,
-
Lineup Array (
lineup):- This array defines the sequence of programs. Each entry is an object like
{"duration": ..., "index": ..., "type": "index"}pointing to an item in theprogramsarray. -
Flex Injection Logic:
- Tracks if the
prev_was_toonami(based on title matchingconfig.network). - If the previous item was a Toonami item AND the current item is also a Toonami item AND the current item's title does NOT contain "intro" (case-insensitive):
- A reference to the "flex" program is inserted into the
lineupbefore the current item.
- A reference to the "flex" program is inserted into the
- Tracks if the
- The actual Plex item is then added to the
lineup.
- This array defines the sequence of programs. Each entry is an object like
- Handles duplicate Plex items in the sequence by either creating a new persisted=false program object (if it's the last occurrence) or by re-referencing the first occurrence's index in the
programsarray. - The final payload
{ "type": "manual", "lineup": ..., "programs": ... }is POSTed to/api/channels/{channel_id}/programming.
-
Main Workflow (
runmethod):- Fetches all media from the specified Plex
library_name. - Filters these
all_mediaitems based onFULL_FILE_PATHs present in the loaded databasetable(lineup). - Gets or creates the Tunarr channel.
- Deletes all old programs from the channel.
- Calls
post_manual_lineupto add the new programming.
- Fetches all media from the specified Plex
-
Inputs:
- Plex server URL/token, Plex library name.
- Tunarr server URL, target channel number, flex duration.
- Name of the SQLite database table containing the ordered lineup (with
FULL_FILE_PATH). -
config.network(for identifying Toonami-branded titles).
-
Outputs/Actions:
- Modifies a Tunarr channel by replacing its programming.
- May create a new Plex media source or channel in Tunarr if they don't exist.
- Logs extensively using Python's
loggingmodule.
Significance: This component bridges the gap between the generated Toonami lineup and the Tunarr platform. Its key differentiator from the DizqueTV version is the built-in flex injection logic during lineup construction, tailored for Tunarr's programming model.
File: ToonamiTools/FlexInjector.py
Class: DizqueTVManager
Purpose: Modifies an existing DizqueTV channel's programming to insert "flex" content (offline placeholders) between consecutive Toonami-branded items, unless the second item is an "Intro". This is used to simulate commercial breaks or transitions.
Key Features & Process:
-
Initialization:
- Takes DizqueTV platform URL (
platform_url), targetchannel_number, flexduration(string like "MM:SS"), andnetworkname (e.g., "Toonami" fromconfig.network). - Constructs the DizqueTV API URL.
- Takes DizqueTV platform URL (
-
Time Conversion (
convert_to_millisecondsmethod):- Converts a "MM:SS" duration string into milliseconds.
-
Flex Target Identification (
is_flex_targetmethod):- Checks if a given program
titlecontains theself.networkname (case-insensitive). This identifies Toonami-branded content.
- Checks if a given program
-
Flex Insertion Logic (
insert_flexmethod):- Takes the
channel_data(a dictionary representing the channel's programming, typically fetched from DizqueTV API). - Calculates
flex_lengthin milliseconds. - Iterates through the
programs_listfromchannel_data. - Appends the current program to a
new_programslist. -
Conditions for inserting flex:
- If the current program is a
flex_target(Toonami item) AND - There is a next program AND
- The next program is also a
flex_target(Toonami item) AND - The next program's title does NOT contain "Intro" (case-insensitive) AND
- The next program is NOT already an offline/flex entry (
'isOffline' not in programs_list[i + 1]). - Then, an
is_offline_entry(flex item:{'duration': flex_length, 'isOffline': True}) is appended tonew_programs.
- If the current program is a
- Also handles a specific case: if the next item's title contains "Intro", a flex entry is added before that intro, regardless of the current item's branding. This seems to ensure a break before intros following any content.
- If a program in the original list is already an offline entry (
'isOffline' in program), its duration is updated toflex_length. - Returns the
channel_datawith the modifiedprogramslist.
- Takes the
-
Main Workflow (
mainmethod):- Fetches the current programming for the specified
channel_numberfrom the DizqueTV API (/api/channel/{channel_number}). - Calls
insert_flexto modify the fetched channel data. - Posts the modified channel data back to DizqueTV API (
/api/channel) to update the channel. - Logs progress and success/failure.
- Fetches the current programming for the specified
-
Inputs:
- DizqueTV server URL.
- Target channel number.
- Flex duration string (e.g., "02:30").
- Network name (e.g., "Toonami") for identifying relevant programs.
-
Outputs/Actions:
- Modifies the programming of an existing DizqueTV channel by inserting or updating flex/offline items.
Significance: This tool provides a way to dynamically add simulated commercial breaks or transition fillers into a DizqueTV channel after its initial programming has been set up by PlexToDizqueTV. It allows for fine-tuning the pacing of the Toonami block.
File: ExtraTools/ManualShowAdder.py
Purpose: Adds custom shows to Toonami lineup
Use Cases:
- Adding shows that "should have been" on Toonami
- Integrating custom or fan-favorite content
- Expanding beyond historical Toonami catalog
Requirements:
- Show must be cut (uses traditional cutting)
- Requires custom bumps ("to ads", "back", optionally "generic")
- Automatically integrates with existing lineup system
Note: The file ExtraTools/ManualShowAdder.py was not provided in the codebase. The documentation above is based on the description in the README and the placeholder in Component-Documentation. Functionality details cannot be confirmed without the source code.
File: ExtraTools/ManualTimestampEditor.py
Class: FolderMatchingTool (Tkinter GUI application)
Purpose: Provides a graphical interface for users to manually create or edit timestamp files (.txt) associated with video files (.mkv). These timestamp files are used by CommercialBreaker to determine cut points.
Key Features & Process:
- GUI Application: Built using Tkinter.
-
Folder Selection:
- Allows the user to select an "Anime Folder" (input video files) and a "Cut Folder" (output/timestamp files).
-
select_in_folder: Stores the path to the anime folder. -
select_out_folder: Stores the path to the cut/timestamp folder.
-
Timestamp File Management (
process_foldersmethod):- When "Edit Timestamps" is clicked:
- Walks through the selected "Anime Folder".
- For each
.mkvfile found, it determines the corresponding path for a.mkv.txttimestamp file in the "Cut Folder" (maintaining the relative directory structure). - If a timestamp file does not exist, it creates an empty one. This ensures every video file can have its timestamps edited.
- When "Edit Timestamps" is clicked:
-
Timestamp Editing Interface:
- A new Toplevel window ("Timestamps") is created.
- A
Textwidget (self.text_box) on the left displays the content of the selected timestamp file. - A
Frameon the right lists all.mkv.txtfiles found in the "Cut Folder", organized by subfolder.- Clicking on a filename in this list calls
display_file_contents.
- Clicking on a filename in this list calls
-
display_file_contents(file_path):- If another file was being edited, its current content from
self.text_boxis saved to a temporary file. - If the
file_pathis being opened for the first time in this session, its content is copied to a new temporary file (original is preserved until explicit save). - The content of the (potentially temporary) timestamp file is loaded into
self.text_box.
- If another file was being edited, its current content from
-
Saving Changes (
save_changesmethod):- When the "Save" button in the "Timestamps" window is clicked:
- Iterates through all
self.temp_files(which maps original file paths to their temporary counterparts). - Copies the content from each temporary file back to the original timestamp file, overwriting it.
- Deletes the temporary files.
- Iterates through all
- When the "Save" button in the "Timestamps" window is clicked:
- Temporary File Usage: Edits are made to temporary copies of the timestamp files. Originals are only overwritten upon explicit save. This provides a safety net against accidental changes.
-
Inputs:
- User-selected "Anime Folder" (containing
.mkvvideos). - User-selected "Cut Folder" (where
.mkv.txttimestamp files are/will be stored). - Manual text input by the user into the text box.
- User-selected "Anime Folder" (containing
-
Outputs:
- Creates or modifies
.txtfiles in the "Cut Folder", containing timestamps (presumably one per line, representing cut points in seconds or HH:MM:SS.milliseconds format, though the exact format isn't dictated by this editor itself but by whatCommercialBreakerexpects).
- Creates or modifies
Significance: This tool offers a manual override and fine-tuning capability for the commercial break points identified by CommercialBreaker. If automated detection is imperfect or if users want precise control, they can use this GUI to adjust the timestamps directly.
File: ExtraTools/CutFailRenamer.py
Class: CutFileRenamer
Purpose: Renames video files (specifically .mp4 parts) in a directory structure, adjusting their part numbers. This is typically used to correct filenames if a previous cutting process was interrupted or resulted in an off-by-one error in part numbering (e.g., parts starting from 000 instead of 1, or needing to increment all part numbers).
Key Features & Process:
-
Initialization:
- Takes an
input_dirwhich is the root directory containing the cut video files to be processed.
- Takes an
-
File Renaming Logic (
rename_filesmethod):- Walks through the
input_dirand its subdirectories. - For each file found:
- Checks if the file ends with ".mp4".
- Splits the filename by "Part " to identify if it's a multi-part file.
- If it is a part file and the part identifier (e.g., "000" from "Part 000.mp4") is a digit:
- Extracts the
part_number(integer). - Constructs a
new_nameby replacing the old part string (e.g., "Part 000") with a new part string where the number is incremented by 1 (e.g., "Part 1"). The original code examplef"Part {str(part_number).zfill(3)}"for the old part string andf"Part {part_number + 1}"for the new part string suggests it's designed to re-index parts that might be 0-indexed or to shift all part numbers up by one. - The line
os.rename(old_name, new_path)is commented out in the provided snippet, so it currently only prints what it would rename. To make it functional, this line would need to be uncommented.
- Extracts the
- If the file doesn't match the expected pattern, it's skipped.
- Walks through the
-
Example Usage (in the script):
input_dir = r"M:\Cut"- An instance of
CutFileRenameris created andrename_files()is called.
-
Inputs:
-
input_dir: Path to the directory containing cut.mp4files with "Part XXX" in their names.
-
-
Outputs/Actions:
- (If
os.renameis uncommented) Renames files in place within theinput_dir. - Prints intended renaming actions or skipped files to the console.
- (If
Significance: This is a utility tool for correcting filename inconsistencies that can arise from the video cutting process, especially if CommercialBreaker or another tool produces parts that need re-numbering for consistency or compatibility with Plex/other media servers' stacking behavior. The current implementation seems geared towards incrementing part numbers (e.g., "Part 000" -> "Part 1", "Part 001" -> "Part 2").
File: ToonamiTools/FolderMaker.py
Class: FolderMaker
Purpose: Creates a predefined set of necessary subdirectories within a given input directory. This ensures that the various tools in the CommercialBreaker & Toonami Tools ecosystem have the expected folder structure to read from and write to.
Key Features & Process:
-
Initialization:
- Takes a
dir_inputwhich is the base directory where subfolders will be created. - Has a predefined list of
self.folders = ['cut', 'toonami_filtered']. These are the names of the subdirectories it will create.
- Takes a
-
Folder Creation (
runmethod):- Iterates through the
self.folderslist. - For each
foldername in the list, it constructs the full path usingos.path.join(self.dir_input, folder). - Uses
os.makedirs(path, exist_ok=True)to create the directory.-
exist_ok=Truemeans that if the directory already exists, the function will not raise an error, making the operation idempotent.
-
- Prints a confirmation message for each folder created.
- Iterates through the
-
Inputs:
-
dir_input: The parent directory where the subfolderscutandtoonami_filteredwill be created. This is typically the "Working Folder" selected by the user in the GUI.
-
-
Outputs/Actions:
- Creates the 'cut' and 'toonami_filtered' subdirectories inside
dir_inputif they don't already exist. - Prints creation status to the console.
- Creates the 'cut' and 'toonami_filtered' subdirectories inside
Significance:
- A simple but essential utility that sets up the foundational directory structure used by many other components in the pipeline.
-
cutfolder: Typically used byCommercialBreakeras an output directory for timestamp files or physically cut video segments. Also used byCommercialInjectorPrep(CommercialInjectorPrep). -
toonami_filteredfolder: Used byEpisodeFilter(EpisodeFilter) as a destination for moved show directories. - Ensures consistency and prevents errors that might arise if tools expect certain directories that haven't been created. Called early in the
prepare_contentworkflow inFrontEndLogic.py.
This component ecosystem works together to transform a standard anime library into an authentic Toonami experience, with each tool handling a specific aspect of the complex pipeline required for professional-quality results.