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:
Note: Before any tools run, users must first select their platform (DizqueTV, Tunarr, or ComBreakDirect) via the UI. This determines the workflow path and whether Plex authentication is required.
0. Platform Selection (UI) →
1. LoginToPlex (Conditional - Required for DizqueTV/Tunarr, Skipped for ComBreakDirect) → 2. FolderMaker → 3. ToonamiChecker → 4. LineupPrep → 5. BumpEncoder →
6. UncutEncoder → 7. Multilineup → 8. ShowScheduler (Merger) X4 → 9. EpisodeFilter (EpisodeFilter) → 10. GetPlexTimestamps (Optional) →
11. CommercialBreaker → 11a. VirtualCut (Conditional - Required for cutless mode) →
12. CommercialInjectorPrep (Conditional - Required for traditional mode) → 13. CommercialInjector → 14. BlockMaker (BlockIDCreator) → 14a. PostCutBumpFilter → 15. ShowScheduler (Merger) (again) X4 → 16. CutlessFinalizer (Conditional - Required for cutless mode) → 16a. BumpCalculator (Conditional - Required for ComBreakDirect) → 17. ExtraBumps (FileProcessor) (Optional) 18. PlexAutoSplitter (Optional) → 19. PlexSplitRenamer (Optional) → 20. PlexToDizqueTV/PlexToTunarr/ComBreakToComBreakDirect → 21. DizqueTVManager (FlexInjector) (Conditional - Required for DizqueTV) → 22. ComBreakDirect Server (Conditional - Required for ComBreakDirect)
File: API/utils/NetworkManager.py
Functions: validate_network_name, update_config_network
Purpose: Validates and persists the active network used across the app.
Details:
-
validate_network_name(network_name)- Probes Wikipedia with a custom User-Agent using urllib.
- Tries these pages:
List_of_programs_broadcast_by_<Network>and..._on_<Network>. - Returns
(True, message)when found; otherwise(False, guidance).
-
update_config_network(config_path, new_network)- Rewrites or inserts
network = "..."inconfig.py.
- Rewrites or inserts
File: API/FrontEndLogic.py
Methods: validate_network, apply_network, reset_network
Purpose: Orchestrates validation, updates config.py, and broadcasts status/errors.
Restart Model:
- UIs call
apply_networkthen re‑exec the process so modules import the newconfig.networkand the DB path switches to<network>.dbreliably.
-
TOM (
GUI/TOM.pyPage 1): Advanced dialog → Validate, Apply & Restart, Reset to Default. -
Absolution (
GUI/Absolution.pyPage 1): Bottom‑right Advanced overlay → Validate, Apply & Restart, Reset. -
Clydes (
CLI/clydes.py): Startup prompt to change network; instructs re‑run after persisting.
These utilities provide Plex integration with minimal dependencies.
File: API/utils/PlexClient.py
Classes: PlexAuthClient, PlexAccountClient, PlexResource
Purpose: Handles Plex OAuth authentication and account management.
Key Components:
PlexAuthClient Class:
- Purpose: Manages OAuth PIN-based authentication flow
-
Key Methods:
-
start_auth()- Initiates OAuth flow, returns auth URL and PIN ID -
poll_for_token(pin_id)- Polls for user approval, returns auth token -
get_token()- Convenience method combining auth flow
-
-
Implementation: Uses Python stdlib
urllibfor HTTP operations - Inputs: None (OAuth is interactive)
- Outputs: Plex authentication token
PlexAccountClient Class:
- Purpose: Manages Plex account operations and server discovery
-
Key Methods:
-
get_resources()- Returns list of all Plex resources (servers, players, etc.) -
get_servers()- Returns only server resources
-
- Implementation: Makes authenticated requests to Plex.tv API
- Inputs: Plex authentication token
-
Outputs: List of
PlexResourceobjects
PlexResource Class:
- Purpose: Represents a Plex server or device
-
Attributes:
-
name- Resource name -
client_identifier- Unique ID -
provides- Resource type ('server', 'player', etc.) -
owned- Ownership status -
connections- List of connection URLs with metadata
-
File: API/utils/PlexServer.py
Classes: SimplePlexServer, SimplePlexLibrary, SimplePlexSection, SimplePlexShow, SimplePlexEpisode
Purpose: Provides minimal Plex Media Server client functionality.
Key Components:
SimplePlexServer Class:
- Purpose: Main server interface
-
Key Methods:
-
get_libraries()- Returns all libraries -
get_library_by_name(name)- Find library by name
-
- Implementation: Makes requests to Plex server API
- Inputs: Server base URL, auth token, optional client identifier
- Outputs: Library objects
SimplePlexLibrary, SimplePlexSection, SimplePlexShow, SimplePlexEpisode Classes:
- Purpose: Represent Plex library hierarchy
- Implementation: Each class provides methods to navigate down the hierarchy
- Example Flow: Server → Libraries → Sections → Shows → Episodes
File: API/utils/PlexConnectionHelper.py
Class: PlexConnectionHelper
Purpose: Smart connection management with automatic URL retry.
Key Features:
- Smart Connection Logic: Automatically tries all available server URLs
- Connection Priority: Local network → Direct connections → Relay URLs
- Automatic Failover: Returns first successful connection
- Connection Discovery: Finds all available Plex servers
Key Methods:
-
discover_servers()- Gets list of available Plex servers -
connect_smart(resource)- Connects to server trying all URLs -
connect_with_server_name(name)- Discovers and connects by name
Connection Strategy:
- Sorts connection URLs by type (local, direct, relay)
- Attempts each URL with timeout
- Returns first successful connection
- Logs all connection attempts
File: ToonamiTools/LoginToPlex.py
Classes: PlexServerList, PlexLibraryManager, PlexLibraryFetcher
Purpose: High-level wrapper for Plex authentication workflow. Uses the Plex client utilities to authenticate, discover servers, and fetch libraries.
Key Features & Process:
PlexServerList Class:
- Purpose: Handles initial Plex authentication and retrieves server list
-
Authentication Process:
- Uses
PlexAuthClientto initiate OAuth flow - Obtains authentication URL for user to approve
- Supports callback mechanism for GUI integration
- Retrieves and stores Plex access token
- Uses
PlexAccountClientto discover available servers
- Uses
- Inputs: User interaction for browser-based authentication
-
Outputs:
- Plex authentication token
- List of Plex server names
- Authentication URL (via callback or browser)
PlexLibraryManager Class:
- Purpose: Connects to selected Plex server and retrieves its URL
-
Connection Process:
- Takes selected server name and auth token
- Uses
PlexConnectionHelper.connect_with_server_name()for smart connection - Automatically handles connection retry with multiple URLs
- Stores server's base URL
- Inputs: Selected Plex server name, Plex authentication token
-
Outputs: Plex server base URL (e.g.,
http://192.168.1.100:32400)
PlexLibraryFetcher Class:
- Purpose: Fetches library list from Plex server
-
Library Fetching:
- Takes server URL and auth token
- Creates
SimplePlexServerinstance - Calls
get_libraries()to retrieve all library sections - Populates list with library titles
- Inputs: Plex server base URL, Plex authentication token
- Outputs: List of library names available on server
Workflow Integration:
-
PlexServerListauthenticates and discovers servers - User selects a server from the list
-
PlexLibraryManagerconnects to selected server (with automatic retry) -
PlexLibraryFetcherretrieves available libraries - Credentials and library selections stored 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. -
HTTP Client: Uses
CurlHttpClientfromAPI.utils.NetworkUtils(curl subprocess) instead of the requests library. -
HTML Parsing: Uses
WikipediaTableParser(regex-based) fromAPI.utils.NetworkUtilsto extract tables instead of BeautifulSoup. - 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).
- Data Structure: Returns a dictionary containing show data (keys: 'Title', 'Year'), with duplicates removed.
- Uses the Wikipedia API (
-
Inputs:
config.network(e.g., "Toonami"). -
Outputs: Dictionary of Toonami shows with their airing years (structure:
{"show_name": {"Title": "...", "Year": "..."}}).
*Uses stdlib-based HTTP operations (curl subprocess via NetworkUtils) and regex-based HTML parsing, eliminating dependencies on requests and beautifulsoup4 libraries.
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):-
Networkless Mode: If
config.network.lower() == "networkless", Wikipedia validation is bypassed entirely. All shows in the video library are included without filtering, allowing use of any custom content collection. -
Standard Mode: 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.
-
Networkless Mode: If
-
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
-
Data Structure: Appends processed data (as dictionaries) to lists:
new_data(for matches) orno_match_data(for non-matches).
- Retrieves all media files (mkv, mp4) from the
-
Database Interaction (
run,_save_to_sqlmethods) *- Connects to the SQLite database (
[config.network].db) viaDatabaseManager. - Reads the
Toonami_Showstable usingfetchall_as_dicts()to get the list of valid show titles (normalized). - Data Processing: Uses lists of dictionaries instead of pandas DataFrames for all bump data manipulation.
- Deduplication Strategy: Combines existing data with new data, creates tuple keys from all column values, and keeps last occurrence of duplicates using dictionary-based deduplication.
- Saves the processed bump data into several tables using
bulk_insert_dicts()orreplace_table_data():-
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 via atomic table replacement.
- 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) usingfetchall_as_dicts(). Each bump is represented as a dictionary with keys 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 bump dictionary in the input data list:
- 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 bump dictionary in the input data list:
-
Data Encoding (
encode_dataframemethod) (method name unchanged for compatibility):- Iterates through each dictionary, applies
create_codeto generate aCodefield. - Uses
re.search()to extractsort_ver(e.g.,2fromV2) andsort_ns(e.g.,1fromNS1) from theCodefor sorting purposes. - Sorts the list of dictionaries using
data.sort(key=lambda x: (x['sort_ver'], x['sort_ns'])).
- Iterates through each dictionary, applies
-
Database Output (using dict-based DatabaseManager methods):
-
codestable: Stores the mapping of full show names (and placement names) to their generated abbreviations (e.g., "Dragon Ball Z" | "DRB"). Saved usingbulk_insert_dicts(). -
main_datatable: Contains the original bump data along with the newCodefield (withsort_ver,sort_nsremoved). Created usingcreate_table_from_dicts(). -
singles_datatable: A subset ofmain_datacontaining only single-show bumps (Codecontains-NS1). Filtered with list comprehension:[row for row in data if '-NS1' in row['Code']]. -
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). Created by grouping withdefaultdictand filtering.
-
-
Overall Workflow (
encode_and_savemethod):- Reads
lineup_prep_outas list of dictionaries. - Encodes the data (iterates and adds
Codefield to each dict). - Saves the various derived data lists (
main_data,singles_data,multibumps_vX_data) to the database using dict-based methods. - Saves the
codesmapping table to the database usingbulk_insert_dicts().
- 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:
- Takes optional
post_cutparameter (default:False).- When
post_cut=False: Operates on originalmultibumps_vX_datatables and creates_reorderedoutput tables. - When
post_cut=True: Operates on filteredmultibumps_vX_data_postcuttables (created byPostCutBumpFilter) and creates_reordered_postcutoutput tables.
- When
- 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).
- Takes optional
-
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) with appropriate suffix and callsreorder_tablefor each one that exists.
-
-
Inputs:
-
Standard mode (
post_cut=False): Variousmultibumps_vX_datatables from the database (created byBumpEncoder). -
Post-cut mode (
post_cut=True): Variousmultibumps_vX_data_postcuttables from the database (created byPostCutBumpFilter). -
config.network(for database name).
-
Standard mode (
-
Outputs:
-
Standard mode: Creates new tables with
_reorderedsuffix (e.g.,multibumps_v2_data_reordered). -
Post-cut mode: Creates new tables with
_reordered_postcutsuffix (e.g.,multibumps_v2_data_reordered_postcut). - Both output types contain the bumps in a more logical sequence optimized for show transitions.
-
Standard mode: Creates new tables with
Significance: Multilineup is crucial for creating engaging Toonami blocks where the announcements flow logically from one multi-show bump to the next. The tool runs twice in the pipeline: first before episode filtering to reorder all bumps, then again after PostCutBumpFilter (when using multi-show bumps) to reorder only the filtered bumps. 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/CommercialInjectorPrep.py
Class: AnimeFileOrganizer
Purpose: Scans and catalogs cut anime files from the cut directory, extracting metadata from filenames and organizing them into a structured database table. This prepares cut episode parts for commercial bump injection by creating an organized inventory of all available segments.
Important: This component is only used in traditional cutting mode. In Cutless Mode, this step is skipped entirely and its role is taken over by VirtualCut (see CommercialBreaker System Overview below), which creates the commercial_injector_prep table with virtual segment references instead of physical cut file paths.
Key Features & Process *
-
Initialization:
- Takes
anime_dir(path to thecutfolder containing cut episode parts) as input. - Uses
DatabaseManagerfor all database operations andErrorManagerfor error reporting.
- Takes
-
File Discovery (
organize_filesmethod):- Recursively walks the
anime_dirdirectory tree to find all.mp4files. - Uses regex pattern
r'(.+?) - (S\d{2}E\d{2}) - Part (\d{3})\.mp4'to extract metadata from filenames:- Show name (e.g., "Naruto")
- Season and episode (e.g., "S01E28")
- Part number (e.g., "001", "002")
- Creates a dictionary for each matched file containing:
-
SHOW_NAME_1: Extracted show name -
Season and Episode: Season/episode identifier -
Part Number: Part number within the episode -
FULL_FILE_PATH: Absolute path to the file
-
- Collects all matched files into a list of dictionaries.
- Recursively walks the
-
Data Validation:
- Checks directory existence and read permissions
- Verifies that cut files were found (raises error if empty)
- Warns if fewer than 3 unique episodes detected (suggests running CommercialBreaker on more content)
- Reports detailed error messages with suggestions for common issues
-
Database Operations *
- Checks if
commercial_injector_preptable exists usingdb_manager.table_exists() - If table exists:
- Reads existing data via
fetchall_as_dicts() - Ensures column compatibility between existing and new data
- Combines datasets and deduplicates by
FULL_FILE_PATH(keeping last occurrence) - Replaces table atomically using
replace_table_data()
- Reads existing data via
- If table doesn't exist:
- Creates new table via
create_table_from_dicts()
- Creates new table via
- All operations use dict-based DatabaseManager methods instead of pandas
- Checks if
Inputs:
-
anime_dir: Path to directory containing cut episode parts (typically[working_folder]/cut/) - Files must follow naming convention:
ShowName - SXXEXX - Part XXX.mp4
Outputs:
-
commercial_injector_preptable in SQLite database with columns:-
SHOW_NAME_1: Show name extracted from filename -
Season and Episode: Season/episode identifier (e.g., "S01E28") -
Part Number: Part number as string (e.g., "001") -
FULL_FILE_PATH: Absolute path to the cut file
-
Significance: This tool bridges the commercial detection phase and the bump injection phase in traditional cutting mode. After CommercialBreaker has cut episodes into parts, CommercialInjectorPrep catalogs all those parts in a structured format. This inventory allows CommercialInjector to systematically insert appropriate bumps between episode segments, creating the authentic Toonami commercial break experience. Without this cataloging step (or its cutless alternative, VirtualCut), the system wouldn't know what cut parts are available for lineup assembly.
Cutless Mode Alternative: In cutless mode, this entire step is bypassed. VirtualCut (part of the CommercialBreaker system) directly creates the commercial_injector_prep table with virtual segment references, allowing the pipeline to continue seamlessly without physical file cutting.
File: ToonamiTools/CommercialInjector.py
Class: LineupLogic
Purpose: The linchpin in creating an authentic cut anime lineup by inserting mid-episode bumps ("to ads", "back") between cut episode parts. Works synergistically with CommercialInjectorPrep to create complete episode sequences with contextually appropriate commercial break bumps, following a sophisticated fallback hierarchy when show-specific bumps are unavailable.
Key Features & Process *
-
Initialization:
- Uses
DatabaseManagerfor all database operations andErrorManagerfor error reporting. - Imports
show_name_mapperfor consistent show name normalization across different data sources.
- Uses
-
Data Loading (
generate_lineupmethod) *- Loads cut episode parts from
commercial_injector_preptable as list of dictionaries viafetchall_as_dicts() - Loads single-show bumps from
singles_datatable (created by BumpEncoder) as list of dictionaries - Validates that both datasets contain data (raises errors with helpful suggestions if empty)
- Loads cut episode parts from
-
Bump Sanitization:
- Creates sanitized version of bump data by splitting
FULL_FILE_PATHon 'Θ' delimiter - This handles bump files that may contain metadata suffixes
- Creates sanitized version of bump data by splitting
-
Show Name Normalization *
- Applies two-stage normalization to all show names in both parts and bumps data:
- Maps to canonical values using
show_name_mapper.map(x, strategy='all') - Cleans for matching using
show_name_mapper.clean(x, mode='matching')
- Maps to canonical values using
- Ensures consistent naming between episode parts and bumps (handles ampersands, apostrophes, etc.)
- Iterates through dict lists using native Python loops instead of pandas apply
- Applies two-stage normalization to all show names in both parts and bumps data:
-
Data Sorting *
- Sorts parts data using
data.sort(key=lambda x: (x['SHOW_NAME_1'], x['Season and Episode'], x['Part Number'])) - Ensures episode parts are processed in correct order
- Sorts parts data using
-
Bump Matching & Fallback Hierarchy:
-
Show-Specific Bumps (Priority 1): Attempts to find bumps specifically for the current show
- Looks for placement-specific bumps (e.g., "Naruto to ads", "Naruto back")
- Uses
defaultdictto organize bumps by show name and placement
-
Generic Anime Bumps (Priority 2): Falls back to anime-generic bumps if show-specific unavailable
- Looks for bumps labeled with generic anime identifiers
-
Universal Generic Bumps (Priority 3): Final fallback to Clydes or Robot bumps
- Ensures every episode gets some form of commercial break, even without show-specific content
- Uses
itertools.cycleto rotate through available generic bumps
-
Show-Specific Bumps (Priority 1): Attempts to find bumps specifically for the current show
-
Lineup Assembly:
- Groups episode parts by
SHOW_NAME_1andSeason and Episodeusingdefaultdict(list) - For each episode group:
- Inserts intro/opening part
- Inserts "to ads" bump before commercial break
- Inserts middle content parts
- Inserts "back" bump returning from commercial
- Inserts closing/outro part
- Builds final lineup as list of dictionaries with
FULL_FILE_PATHentries
- Groups episode parts by
-
Database Output *
- Saves complete lineup to
commercial_injectortable - Uses
replace_table_data()for atomic table replacement - Output contains alternating pattern of episode parts and bumps
- Saves complete lineup to
Inputs:
-
commercial_injector_preptable: Cut episode parts with show names and part numbers -
singles_datatable: Single-show bumps with placement information -
config.network: Network name for database selection
Outputs:
-
commercial_injectortable in SQLite database containing:- Interleaved episode parts and commercial bumps
-
FULL_FILE_PATH: Paths to both episode segments and bump files -
SHOW_NAME_1: Normalized show names -
Season and Episode: Episode identifiers -
Part Number: Part numbers for episode segments
Significance: CommercialInjector is the core component that transforms cut anime episodes into authentic Toonami-style programming. By intelligently selecting and inserting appropriate commercial break bumps between episode parts, it recreates the classic Toonami viewing experience. The sophisticated fallback hierarchy ensures every episode gets proper commercial transitions, even when show-specific bumps are missing. This is the critical step that differentiates a simple episode collection from a professionally-produced Toonami block with authentic commercial break aesthetics.
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). Loaded as list of dictionaries viafetchall_as_dicts(). -
commercial_table: Contains episode data, includingFULL_FILE_PATHandBLOCK_ID(e.g.,commercial_injector_finalfor cut content,uncut_encoded_datafor uncut). Loaded as list of dictionaries.
-
-
Output Table: Saves the generated lineup to a specified table (e.g.,
lineup_v9fromconfig.TOONAMI_CONFIG[version]["merger_out"]). Saved usingcreate_table_from_dicts(). -
Show Name Normalization:
- Decodes show codes via the
codestable (loaded as dict mapping). - Uses
_assign_show_name_from_block_id()method to parse BLOCK_ID strings (e.g.,"NARUTO_S01E01"→"naruto"). - Normalizes decoded names using
show_name_mapper.map(name, strategy='all')followed byshow_name_mapper.clean(mapped, mode='matching')to align with bump and episode data. - All string operations use native Python methods instead of pandas string methods.
- Decodes show codes via the
-
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.
-
-
Data Structures *
-
self.encoder_data: Bump list (List[Dict]) instead of DataFrame -
self.decoded_data: Decoded show names (List[Dict]) -
self.commercial_injector_data: Episode blocks (List[Dict]) -
final_lineup: Accumulated lineup list instead of DataFrame -
Grouping: Uses
collections.defaultdictfor grouping instead of pandas groupby
-
Core Scheduling Logic (generate_schedule method) *
- Iterates through the
encoder_datalist (bump list dictionaries). - For each bump dictionary (
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).- Continuity guard: If Show A’s next episode block cannot be placed immediately after the NS2 code, the scheduler skips appending that NS2 bump to preserve the invariant that bump rows are followed by appropriate program content.
- If the
last_show_namefrom the previous segment isn't Show B, an episode block of Show B is inserted first. - The NS2 bump file is added only when Show A’s next block is available to follow it.
- Then, an episode block of Show A is added (often with
delete_intro=Truefor the first part of Show A).
-
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_data(list of dicts).- Considers
last_used_episode_blockifcontinue_from_last_used_episode_blockis true. - Handles
reuse_episode_blocksor adds toshows_with_no_more_blocks. - Uses list filtering:
[row for row in commercial_injector_data if row['show'] == target_show]
- Considers
- The files corresponding to the selected
BLOCK_IDare fetched fromcommercial_injector_dataand appended to thefinal_lineuplist. -
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/CutlessFinalization.py
Class: CutlessFinalizer
Purpose: Finalizes cutless mode lineups by calculating precise start/end timestamps for virtual segments and transforming the data into the format required by DizqueTV and Tunarr platforms. This critical step enables virtual cutting without physically modifying video files, preserving original media while providing frame-accurate playback control.
Key Features & Process *
-
Initialization:
- Takes
networkname as parameter (e.g., "Toonami" fromconfig.network) - Uses
DatabaseManagerfor all database operations andErrorManagerfor error reporting - Validates that required tables exist before processing
- Takes
-
Cutless Mapping Loading (
_get_cutless_mappingmethod) *- Loads virtual cut data from
commercial_injector_preptable as dictionary indexed byFULL_FILE_PATH - Validates critical columns exist (
startTime,endTime,ORIGINAL_FILE_PATH) - Checks that data isn't empty and raises detailed errors if missing
- Validates timestamp data quality:
- Separates anime files from bump files (bumps contain network name in path)
- Ensures anime files have either
startTimeORendTime(at least one required) - Raises critical error if anime files missing both timestamps (indicates failed commercial detection)
- Returns data as dict mapping
FULL_FILE_PATH→ row data for O(1) lookups
- Loads virtual cut data from
-
Bump Duration Loading (
_get_bump_durationsmethod) *- Loads pre-calculated bump durations from
bump_durationstable - Created by BumpCalculator during Prepare Content workflow
- Cleans and validates data:
- Strips whitespace from file paths
- Converts duration values to numeric (filters invalid values)
- Removes duplicates (keeps last occurrence)
- Returns as dict mapping
FULL_FILE_PATH→ duration for fast lookups - Gracefully handles missing table (returns empty dict with warning)
- Loads pre-calculated bump durations from
-
Lineup Table Discovery (
_get_lineup_tablesmethod):- Queries database schema for all tables matching pattern
lineup_v* - Excludes uncut lineup tables (those containing "uncut" in name)
- Returns list of cut lineup tables that need cutless finalization
- Handles version-specific lineups (v2, v8, v9, etc.)
- Queries database schema for all tables matching pattern
-
Duration Injection (
_inject_durationsmethod) *- For each lineup entry:
- Checks if duration already exists (skips if present)
- Looks up duration in bump_durations dict for bump files
- Calculates duration from timestamps for anime files:
- If both startTime and endTime exist:
duration = endTime - startTime - If only startTime exists: uses total video duration - startTime
- Converts milliseconds to seconds for consistency
- If both startTime and endTime exist:
- Falls back to probing file with DurationManager if no other method works
- Validates all lineup rows have duration data before proceeding
- Uses native Python dict operations and list iterations
- For each lineup entry:
-
Cutless Data Transformation:
- Merges lineup data with cutless mapping data:
- Looks up each
FULL_FILE_PATHin the cutless mapping dict - Adds
startTime,endTime, andORIGINAL_FILE_PATHfields - For bump files:
startTimeandendTimeare null (plays full file) - For anime segments: precise millisecond timestamps for virtual cutting
- Looks up each
- Creates
lineup_vX_cutlessoutput table with complete timing metadata
- Merges lineup data with cutless mapping data:
-
Database Output *
- Processes each lineup table (
lineup_v2,lineup_v8,lineup_v9, etc.) - Saves cutless-enabled version with
_cutlesssuffix - Uses
replace_table_data()for atomic table replacement - Final tables contain all data needed for cutless playback
- Processes each lineup table (
-
Overall Workflow (
runmethod):- Discover all cut lineup tables in database
- Load cutless mapping data (virtual cut timestamps)
- Load bump duration data
- For each lineup table:
- Load lineup data as list of dicts
- Inject duration information
- Validate all rows have durations
- Merge with cutless mapping (add timestamps)
- Save to
lineup_vX_cutlesstable
Inputs:
-
commercial_injector_preptable: Virtual cut mapping withstartTime,endTime,ORIGINAL_FILE_PATH -
bump_durationstable: Pre-calculated bump file durations (from BumpCalculator) -
lineup_vXtables: Cut lineup tables from Merger (ShowScheduler) -
config.network: Network name for database selection
Outputs:
-
lineup_vX_cutlesstables in SQLite database containing:-
FULL_FILE_PATH: Virtual segment path (may not physically exist) -
ORIGINAL_FILE_PATH: Path to actual video file on disk -
startTime: Start time in milliseconds (null for bumps) -
endTime: End time in milliseconds (null for bumps/last segment) -
duration: Segment duration in seconds - All other lineup metadata (show names, codes, etc.)
-
Significance: CutlessFinalization is the transformative component that enables zero-disk-overhead Toonami channels. By calculating precise timestamps and preserving references to original files, it allows DizqueTV and Tunarr to play exact segments without creating thousands of cut files. This revolutionary approach:
- Saves massive disk space - No duplicate cut files needed
- Preserves quality - Original files remain untouched
- Enables flexibility - Commercial break points can be adjusted without re-cutting
- Maintains compatibility - Works seamlessly with existing Plex libraries
This is the final critical step for cutless mode, transforming standard lineups into virtual-cut-ready data that platforms can use for frame-accurate playback. Without this finalization, the cutless workflow cannot function.
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. -
Networkless Mode (
config.network.lower() == "networkless"):- Uses folder-based filtering instead of network name matching.
- Filters out files with
/bump,\bump,/special, or\specialin their paths. - This prevents issues with the network name "Networkless" appearing in file paths while still excluding bump files.
-
Standard Mode (any other network):
- 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.
- The core filter
- 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
SimplePlexServerfromAPI.utils.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): Cutless Mode replacement for CommercialInjectorPrep (step 12 in the pipeline). Instead of cataloging physical cut files, VirtualCut creates virtual segment references with precise timestamps. Outputs to thecommercial_injector_preptable with the same schema as traditional mode, plus additionalstartTime,endTime, andORIGINAL_FILE_PATHcolumns. This allows the rest of the pipeline (CommercialInjector, BlockMaker, Merger, etc.) to proceed identically regardless of cutting mode.
- 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.). After cutting, the
CommercialInjectorPreptool catalogs these cut files. -
Cutless Mode: Uses
VirtualCutto create virtual references, no physical files are created, only database entries with timestamps. VirtualCut directly populatescommercial_injector_preptable, replacing the need for CommercialInjectorPrep (step 12 in the pipeline).
-
Traditional Mode: Physically cuts videos at detected timestamps, creates multiple files per episode (Part 1, Part 2, etc.). After cutting, the
- 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.md 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/PostCutBumpFilter.py
Class: PostCutBumpFilter
Purpose: Filters multi-show bump data after the commercial cutting pipeline completes, ensuring that only bumps referencing shows with available episode blocks remain in the lineup tables.
Problem Solved:
When creating lineups with multi-show bumps (bumps that reference multiple different shows), some bumps may reference shows for which no episode data was cut or prepared. These orphaned bumps would cause errors or display issues in the final lineup. PostCutBumpFilter removes these problematic entries automatically.
Key Features & Process:
-
Initialization:
- Connects to the database using
DatabaseManager. - Initializes the
ErrorManagerfor warnings and errors. - Loads the list of generic bump names from
config.generic_bumps(these are show-agnostic bumps that should never be filtered). - Normalizes all generic bump names using the
show_name_mapperutility for consistent matching.
- Connects to the database using
-
Show Name Normalization:
- Uses the
show_name_mapperutility withstrategy='all'andmode='matching'to ensure consistent show name matching. - Handles variations in show naming across different data sources.
- Generic bumps (like "Toonami", "Adult Swim", etc.) are excluded from filtering.
- Uses the
-
Available Shows Collection (
_collect_allowed_showsmethod):- Reads the
commercial_injector_preptable which contains all shows that were successfully processed through the commercial cutting pipeline. - Extracts show names from multiple possible column names:
show_name,BLOCK_ID, orSHOW_NAME_1. - Normalizes each show name and builds a set of allowed shows.
- Raises an error if the episode table is missing or empty, as this indicates the pipeline didn't complete.
- Reads the
-
Multi-Show Bump Filtering:
-
Lineup Table Filtering (
_filter_lineup_tablemethod):- Reads the
lineup_prep_outtable containing prepared lineup entries. - For each row, checks if any show references (in
SHOW_NAME_1,SHOW_NAME_2,SHOW_NAME_3columns) point to shows not in the allowed set. - Skips generic bumps during this check.
- Removes rows with missing show references.
- Creates a new table
lineup_prep_out_postcutwith only valid entries.
- Reads the
-
Multibump Tables Filtering (
_filter_multibump_tablesmethod):- Iterates through multibump tables (
multibumps_v0_datathroughmultibumps_v9_data). - Applies the same filtering logic to each table.
- Creates
*_postcutversions of each multibump table. - Drops and resets the
*_reordered_postcuttables so they can be rebuilt fresh.
- Iterates through multibump tables (
-
Lineup Table Filtering (
-
Reporting (
runmethod):- Tracks which shows had bumps removed and how many.
- Sends a warning through
ErrorManagerlisting the top 5 most impacted shows. - Provides actionable suggestions: add episode cuts for missing shows or remove their multi-show bumps.
-
Inputs:
-
commercial_injector_preptable (contains available episode blocks). -
lineup_prep_outtable (contains prepared lineup with multi-show bumps). -
multibumps_v*_datatables (contains multi-show bump data). -
config.generic_bumps(list of show-agnostic bump names).
-
-
Outputs:
-
lineup_prep_out_postcuttable (filtered lineup). -
multibumps_v*_data_postcuttables (filtered multibump tables). - Warning messages about removed bumps (via ErrorManager).
-
When to Use:
- Run automatically after the commercial cutting pipeline when using multi-show bumps.
- Ensures clean lineup data for downstream tools like
PlexToDizqueTV,PlexToTunarr, orComBreakToComBreakDirect. - Can be skipped if not using multi-show bumps or if all referenced shows have episode data.
Significance: This tool prevents runtime errors and display issues caused by bumps referencing non-existent show data, ensuring the final Toonami channel lineup is consistent and error-free.
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
SimplePlexServerinstance fromAPI.utils.PlexServer. - 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:
- Uses
SimplePlexServerfromAPI.utils.PlexServerfor 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:
selenium- Google Chrome browser and a compatible ChromeDriver.
- Plex client utilities from
API.utils
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
SimplePlexServerinstance fromAPI.utils.PlexServerand 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:
- Plex client utilities from
API.utils - A running Plex server with accessible credentials.
- Plex client utilities from
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. -
SimplePlexServer(fromAPI.utils.PlexServer) and DizqueTV API clients are initialized in therunmethod.
- 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 using
SimplePlexServerfromAPI.utils.PlexServer. - 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: ToonamiTools/ComBreakToComBreakDirect.py
Class: ComBreakToComBreakDirect
Purpose: Pushes a curated cutless lineup from the database to the ComBreakDirect streaming server. This integration tool handles data transformation from the cutless database format to ComBreakDirect's expected API format.
Key Features & Process:
-
Initialization:
- Takes database
tablename (cutless lineup table likelineup_v8_cutless),channel_number,flex_duration(commercial break length),networkname, ComBreakDirectbase_url, andcommercial_folderpath. - Validates that the specified cutless table exists in the database.
- Automatically starts ComBreakDirect server if not already running.
- Takes database
-
Flex Duration Parsing (
_parse_flex_durationmethod):- Accepts both string format ("MM:SS") and integer (milliseconds).
- Converts "MM:SS" format to milliseconds for API compatibility.
-
Lineup Loading (
_load_lineup_from_databasemethod):- Reads the specified cutless table from the database.
- Expected columns:
FULL_FILE_PATH,Code,startTime,endTime,duration(optional),BLOCK_ID. - Converts all time values to milliseconds if needed.
-
Payload Construction (
_build_payloadmethod):- Transforms database rows into ComBreakDirect API format.
- Each lineup item includes:
-
file_path: Full path to video file -
code: Bump encoding code (from BumpEncoder) -
block_id: Episode/show identifier (from BlockMaker) -
start_time: Seek position in milliseconds -
end_time: Stop position in milliseconds -
duration: Total file duration in milliseconds
-
- Constructs final payload with channel metadata:
-
channel_number,network,lineup,flex_duration,commercial_folder
-
- When
infinite=True(always set byFrontEndLogic.create_toonami_channelfor ComBreakDirect), also includes:-
infinite:true— tells LoadingDock to stash_infinite_metaon the channel -
infinite_meta:{toonami_version, cutless_enabled, commercial_folder}— read by FactoryFloor's LineupExtender so it knows whichTOONAMI_CONFIG_CONTrow to use for future extensions
-
-
Episode Cursor Seeding (
_seed_episode_cursormethod):- Runs BEFORE
_push_lineupwhenself.infinite=True. - Sweeps the loaded lineup rows for BLOCK_IDs (format
SHOW_NAME_S##E##). - Derives each show key via
show_name_mapper.clean(show_name_mapper.map(name), mode='matching')to exactly match ShowScheduler's internal cursor format — derive any other way and the cursor lookup silently misses. - Takes the max BLOCK_ID per show within the new lineup.
- Merges with the existing
last_used_episode_blocktable, taking the larger BLOCK_ID per show (never rolls a cursor backwards). - Without this seed step, the first extension treats every show as "no prior position" and picks whatever ShowScheduler's index has at position 0 — usually NOT the next episode the viewer expects after the initial lineup.
- Runs BEFORE
-
Module-level helper
load_lineup_rows(table, db_manager=None):- Extracted from the original
_load_lineupso both initial channel creation AND the infinite extension flow share the same row normalization. -
InfiniteChannelExtendercalls this directly with each per-extension table name.
- Extracted from the original
-
Server Communication (
_push_to_servermethod):- POSTs the payload to
{base_url}/channelsendpoint. - Handles HTTP errors and connection failures.
- Logs the server response including playlist and guide URLs.
- POSTs the payload to
-
Health Check (
_check_server_healthmethod):- Queries
{base_url}/statusendpoint with retries. - Waits up to 30 seconds for server to become ready.
- Raises exception if server doesn't respond.
- Queries
-
Main Workflow (
runmethod):- Load lineup data from database
- Parse flex duration
- Build API payload
- Check server health
- Push lineup to server
- Log playlist and guide URLs
-
Inputs:
- Cutless lineup table name (e.g.,
lineup_v8_cutless) - Channel configuration (number, network, flex duration)
- ComBreakDirect server URL
- Commercial folder path
- Cutless lineup table name (e.g.,
-
Outputs/Actions:
- Creates or updates a channel on ComBreakDirect server
- Logs playlist URL and XMLTV guide URL for use with Plex
Significance: This component is the bridge between CommercialBreaker's cutless pipeline and the ComBreakDirect streaming server. It eliminates the need for DizqueTV or Tunarr by pushing lineup data directly to a self-hosted streaming solution.
File: ToonamiTools/InfiniteChannelExtender.py
Class: InfiniteChannelExtender
Purpose: One-shot orchestrator that builds a single extension chunk for an infinite ComBreakDirect channel. Invoked by ComBreakDirect.docks.LineupExtender whenever its threading.Timer fires.
Key Features & Process:
-
Initialization:
- Takes no arguments; constructs its own
DatabaseManagerandErrorManagerreferences via the singleton accessors.
- Takes no arguments; constructs its own
-
Main Method (
generate_chunk(channel_number, infinite_meta)):- Reads
toonami_versionfrominfinite_meta(raises if missing). - Looks up
config.TOONAMI_CONFIG_CONT[toonami_version]to get the encoder table name, bump-list table name, anduncutflag — same per-version configuration the manual Page-7 continuation uses. - Computes a per-extension output table name:
{merger_out}_inf_ch{channel}_ext{seq}whereseqisint(infinite_meta.get('extension_seq') or 0) + 1. Example:lineup_v9_cont_inf_ch61_ext3. Per-chunk tables keep each extension debuggable in isolation and avoid clobbering the manual Page-7_contflow. - Instantiates
ShowScheduler(reuse_episode_blocks=True, continue_from_last_used_episode_block=True, uncut=...). Withreuse=Truethe scheduler cycles back to a show's first block if it ever exhausts the cursor, so generation is truly unbounded. - Calls
merger.run(bump_list_table, encoder_table, output_table)to produce the chunk. The scheduler advances the per-show cursor inlast_used_episode_blockas a side effect. - If
cutless_enabled(always true for ComBreakDirect), callsCutlessFinalizer.run_for_table(output_table, output_table + "_cutless")to produce the cutless companion. - Loads the rows via the shared
load_lineup_rowshelper and returns(rows, output_table).
- Reads
-
Failure Modes:
- Missing
toonami_versionininfinite_meta→RuntimeError. - Missing
TOONAMI_CONFIG_CONTentry →RuntimeError. - ShowScheduler doesn't produce the output table →
RuntimeError. -
CutlessFinalizer.run_for_tablereturnsFalse→RuntimeError. - ShowScheduler produced an empty chunk → returns
([], output_table)for the caller to treat as a soft failure (disables the LineupExtender after surfacing to S.A.R.A.).
- Missing
-
Inputs:
-
channel_number— used in the per-extension table name to avoid collisions across simultaneous channels. -
infinite_meta— the channel's_infinite_metadict; providestoonami_version,cutless_enabled,extension_seq.
-
-
Outputs:
- New SQLite tables
lineup_v{N}_cont_inf_ch{ch}_ext{seq}andlineup_v{N}_cont_inf_ch{ch}_ext{seq}_cutless. - Returns
(rows, consumable_table_name)for the caller. Rows are inload_lineup_rowsshape: dicts ofblock_id,file_path,code,start_time,end_time,duration. - Advances per-show cursors in
last_used_episode_block.
- New SQLite tables
Significance: This is the engine that makes ComBreakDirect channels infinite. Every time the LineupExtender's timer fires, this component runs the same ShowScheduler + CutlessFinalizer pipeline as the initial channel creation, but with the cursor already advanced — so chunk N+1 picks up exactly where chunk N left off for every show. No re-airing already-seen episodes, no jumping past episodes the viewer hasn't seen.
File: ToonamiTools/BumpCalculator.py
Class: BumpCalculator
Purpose: Calculates and persists video durations for all bump files identified by LineupPrep. This ensures that duration information is available throughout the pipeline without requiring repeated ffprobe calls.
Key Features & Process:
-
Initialization:
- Optionally takes a
status_callbackfor progress updates. - Initializes
DurationManagerfor efficient duration extraction. - Connects to database to access bump metadata.
- Optionally takes a
-
Bump File Loading (
runmethod):- Reads from the
nice_listtable (created by LineupPrep at step 4). - Extracts all unique
FULL_FILE_PATHentries for bump files. - Deduplicates paths to avoid redundant processing.
- Reads from the
-
Duration Calculation:
- Iterates through each unique bump file path.
- Uses
DurationManagerto probe each video file with ffprobe. - Stores duration in milliseconds for each file.
- Handles missing files gracefully with warnings.
-
Database Persistence:
- Creates a
bump_durationstable in the database. - Stores mapping of
FULL_FILE_PATHtoduration(in milliseconds). - Replaces existing table if present.
- Creates a
-
Progress Reporting:
- Calls
status_callbackafter processing each file. - Reports progress as "[X/Total] Measuring duration for filename.mp4".
- Provides user feedback during long-running operations.
- Calls
-
Main Workflow (
runmethod):- Load bump file paths from
nice_listtable - Deduplicate and normalize paths
- Calculate durations using DurationManager
- Store results in
bump_durationstable - Report warnings for any missing files
- Load bump file paths from
-
Inputs:
-
nice_listtable from database (populated by LineupPrep) - Optional status callback function
-
-
Outputs:
- Creates
bump_durationstable with file paths and durations in milliseconds - Enables downstream tools to look up bump durations without probing files
- Creates
Significance: This tool runs during the prepare_cut_anime() workflow (step 16a, optional, when using cutless mode). By pre-calculating all bump durations once and storing them in the database, it provides fast duration lookups for CutlessFinalizer and other tools that need to know how long bumps are for timing calculations.
Location: ComBreakDirect/ directory
Purpose: Self-contained continuous MPEG-TS streaming server using Studio → FIFO → Broadcast FFmpeg → BroadcastTower architecture.
Modular Architecture:
ComBreakDirect/
├── ComBreakDirectServer.py # Main Flask application
├── docks/ # Core processing modules
│ ├── LoadingDock.py # Lineup processing & ad injection
│ ├── FactoryFloor.py # Storage & M3U8/XMLTV generation
│ ├── UnloadingDock.py # Broadcast streaming & multi-client management
│ └── LineupExtender.py # Per-channel timer-based infinite-extension watchdog
├── utilities/ # Supporting modules
│ ├── BroadcastTower.py # Multi-client distribution engine
│ ├── AudioTrackSelector.py # Intelligent audio selection
│ ├── CommercialBreakRenderer.py # Pre-rendering system
│ ├── CleanupManager.py # Automatic file maintenance
│ └── configuration.py # Path resolution
└── UI/ # Web interface
└── WebUI.py # Landing page
Key Capabilities:
- Continuous MPEG-TS Streaming: True broadcast-style streaming with seamless program transitions
- BroadcastTower Architecture: Multi-client support via Antenna pattern (one transcode, multiple viewers)
-
Broadcast FFmpeg Layer: Uses
+genptsto flatten program transitions and prevent Jellyfin/Plex freezing - WebUI: Toonami-themed landing page with setup instructions
- HDHomeRun Discovery: Automatic Plex/Jellyfin integration via device discovery
- Intelligent Audio Selection: Configurable audio track selection (defaults to English for Toonami dubs)
- Guide Generation: XMLTV with full show metadata (season/episode/title)
- Commercial Injection: Server-side ad break pre-rendering and insertion
- Auto Start/Stop: Studio and broadcast FFmpeg only run when clients connected
- Channel Timing: Sophisticated timing algorithm for perfect sync across all clients
-
CommercialBreakRenderer Cache: Predictively renders
_pre_rendered_breaks/*.tsassets -
Infinite Channel Extension: Per-channel
LineupExtendertimer arms ahead of channel end and runs ShowScheduler+CutlessFinalizer to append fresh content — wall-clock based, fires independent of playback
Loading Dock Details:
-
process_lineupmaps incoming payloads (fromPOST /channels) into streaming-ready channel dictionaries. - Consecutive bumps trigger
_inject_commercials, which reserves or renders commercial breaks throughCommercialBreakRenderer. -
_format_for_streamingnormalizes timings, assignsblock_idfallbacks, and produces the rolling channel timeline (start,stop,duration, seek offsets). The inner program-builder_format_programs(lineup_data, anchor_time)is extracted soformat_extensioncan reuse it. -
format_extension(lineup_data, existing_channel_data)reuses_inject_commercials+_format_programswithanchor_timeset to the existing channel's tailstop, producing program dicts whose timestamps land contiguously after the existing timeline. Used byLineupExtenderto splice extension chunks onto a running channel. - When the incoming payload has
infinite: true, LoadingDock stashes a populatedchannel_data['_infinite_meta']block (withenabled=True) before handing to FactoryFloor.
Factory Floor Details:
-
store_channelpersists the channel data inchannels.json, guarded by a threading lock. Calls_maybe_spawn_extender(channel_data)after persisting so infinite channels get a watchdog immediately. -
extend_channel(channel_number, new_programs)is the append-only growth path used byLineupExtender— takes the factory lock, callsprograms.extend(new_programs)(never replaces or reorders, which would race the Studio's live read), bumps_infinite_meta.extension_seq, stampslast_extension_at, resetsconsecutive_failures, and persists. -
_maybe_spawn_extender(channel_data)spawns aLineupExtenderfor any channel with_infinite_meta.enabled=Trueand a LoadingDock back-reference. Idempotent — won't double-spawn. Called atstore_channeland during_load_channelsstartup so channels persisted from a prior run get their watchdogs rearmed. -
_save_channelsstrips ephemeral_runtimekeys (Studio'scurrent_indexis re-derived from UTC on next startup) before writing to disk. -
generate_playlistandgenerate_xmltvuse helper methods (_consolidate_programs_by_block_id,_extract_show_metadata_from_block_id) to output user-facing metadata. - Storage location defaults to
CBDIRECT_DATA_ROOTviautilities.configuration.resolve_storage_path.
Unloading Dock Details (Broadcasting Architecture):
-
Studio Thread (
build_stream): Calculates current channel position, spawns FFmpeg per program with normalization (H.264 1080p 30fps, AAC stereo 48kHz, CBR 5.4 Mbps), writes MPEG-TS to FIFO -
Broadcast FFmpeg (
start_broadcast_ffmpeg): Reads FIFO with-fflags +genpts+discardcorrupt, creates continuous stream, rate limits broadcasting (13ms per chunk) - BroadcastTower: Receives continuous stream, distributes to all connected Antenna objects (one per client)
- Antenna: Per-client buffer (132 chunks, ~2 seconds) with rate-limited iteration to prevent buffering ahead
-
Lifecycle: Auto start/stop - studio and broadcast FFmpeg only run when clients connected (detected via
broadcast_tower.has_antennas()) -
Output Wrapper: Thin layer that calls FactoryFloor for playlists/guides (
get_master_playlist,get_xmltv_guide,get_lineup_json)
API Endpoints:
-
WebUI Routes:
-
GET /- Landing page with setup instructions and copy-to-clipboard URLs
-
-
Continuous MPEG-TS Streaming:
-
GET /video/channel/{number}- Continuous broadcast stream (HDHomeRun-compatible)
-
-
Channel Management:
-
POST /channels- Create/update channel with lineup data -
GET /playlist.m3u8- Master M3U8 playlist -
GET /api/xmltv.xml- XMLTV guide
-
-
Plex/Jellyfin Discovery:
-
GET /discover.json- HDHomeRun discovery -
GET /lineup.json- Channel lineup -
GET /lineup_status.json- Scan status -
GET /status- Server health check -
POST /wipe- Clear all data (channels, towers, pre-rendered breaks)
-
Technical Features:
- Studio → FIFO → Broadcast FFmpeg → BroadcastTower: Four-layer architecture for continuous streaming
-
PTS Regeneration: Broadcast FFmpeg's
+genptscreates seamless transitions between programs - Multi-Client Distribution: BroadcastTower broadcasts to multiple Antenna objects (one per client)
- Rate Limiting: 13ms per chunk (~5.4 Mbps CBR) prevents antenna buffer overflow
- Auto Lifecycle: Studio and broadcast FFmpeg start/stop based on client connections
- Configurable Audio: Automatic audio track selection based on DEFAULT_LANGUAGE config (defaults to English)
- Commercial Pre-rendering: Background thread maintains 1-hour window of pre-rendered breaks
- Automatic Cleanup: CleanupManager removes old pre-rendered breaks (4+ hours old)
Integration with Pipeline:
- Called automatically by
LogicController._ensure_combreakdirect_server() - Receives lineup data via
ComBreakToComBreakDirectREST API - Provides playlist/guide URLs for Plex integration
- Runs in background during WebUI operation (Docker mode)
- WebUI accessible at
http://localhost:8083/by default
For detailed ComBreakDirect documentation, see ComBreakDirect.md.
File: ComBreakDirect/docks/LineupExtender.py
Class: LineupExtender
Purpose: Per-channel watchdog that schedules a single threading.Timer to fire ahead of the channel's natural end and append a fresh extension chunk. Spawned by FactoryFloor._maybe_spawn_extender for every channel that arrives with _infinite_meta.enabled=True (i.e., every ComBreakDirect channel).
Key Features & Process:
-
Initialization:
- Takes the owning
FactoryFloor(not LoadingDock — see "Lazy LoadingDock lookup" below) and achannel_number. - Reads tunables from
configwith class-default fallbacks:INFINITE_EXTEND_LEAD_MS(default 10 800 000 ms = 3 hours),INFINITE_MIN_FREE_DISK_BYTES(default 2 GiB).
- Takes the owning
-
Timer Lifecycle:
-
start()calls_schedule_next()which computes a delay ofmax(0, (last_program.stop_iso - now_utc) - lead_ms)and arms a freshthreading.Timer(delay_s, self._on_timer_fire). Channels shorter than the lead window (or already past their end) fire immediately. -
cancel()cancels any pending timer; idempotent. Called when the channel is removed. -
is_active()returns whether a future extension is still scheduled.
-
-
Timer Callback (
_on_timer_fire→_do_extension):- Race-check that the channel still exists in FactoryFloor; cancel watchdog if it doesn't.
- Check
_infinite_meta.enabled(an external party may have disabled it); return without rescheduling if so. - Check
_infinite_meta.consecutive_failuresagainstMAX_CONSECUTIVE_FAILURES(3); call_disableand surface to S.A.R.A. if exceeded. - Disk-space gate via
_has_disk_space(): skip if the storage partition has less thanmin_free_disk_bytesfree; bump failures and retry inRETRY_AFTER_FAILURE_MS(5 min). - Call
_build_extension(channel_data, meta)which delegates toToonamiTools.InfiniteChannelExtender.generate_chunkand thenloading_dock.format_extensionto anchor the new programs to the existing tail. - If the channel was deleted during the long-running build, discard the new programs and cancel.
- Call
factory_floor.extend_channel(channel_number, new_programs). - Recompute the new channel-end and arm a fresh timer via
_schedule_next().
-
Lazy LoadingDock Lookup:
- The extender stores only the
FactoryFloorreference, accessing LoadingDock through a@propertythat resolvesself.factory_floor.loading_dockon first use. - This sidesteps the bootstrap chicken-and-egg:
FactoryFloor.__init__spawns watchdogs for any channels recovered from disk, but at that exact momentLoadingDock.__init__is still mid-assignment ofself.factory_floor = FactoryFloor(...)— itsfactory_floorattribute doesn't yet exist. Deferring the lookup until the timer actually fires guarantees LoadingDock has finished constructing.
- The extender stores only the
-
Wall-Clock vs Playback:
- The trigger condition
(last_program.stop - now) < lead_msis wall-clock based. The watchdog deliberately does NOT read Studio'scurrent_index. If it did, channels would never extend while no client was streaming — and a returning viewer would land in the modulo loop fallback (replaying program 0) instead of finding fresh content.
- The trigger condition
-
Failure Modes & Backoff:
- Recoverable failure (disk pressure, single-pass build error) → bump
_infinite_meta.consecutive_failures, surface a warning viaErrorManager, retry afterRETRY_AFTER_FAILURE_MS(5 min). - Three consecutive failures →
_disable(channel_data, reason): set_infinite_meta.enabled=False, persist via_save_channels, surface an error to S.A.R.A., cancel the watchdog. The Studio's modulo loop keeps playing existing programs in the meantime, so the channel doesn't die — it just stops growing. - Hard failure (ShowScheduler produces zero programs — shouldn't happen with
reuse_episode_blocks=True) → disable immediately.
- Recoverable failure (disk pressure, single-pass build error) → bump
-
Inputs:
- Constructor: owning
FactoryFloor, channel number. - Per-tick read of
channel_data['_infinite_meta']andchannel_data['programs'][-1]['stop'].
- Constructor: owning
-
Outputs:
- Mutates
channel_data['_infinite_meta'](extension_seq,last_extension_at,consecutive_failures, occasionallyenabled). - Calls
factory_floor.extend_channelwhich appends tochannel_data['programs']and persistschannels.json.
- Mutates
Significance: This is the difference between a channel that runs ~40 hours and quits, and a channel that runs forever. Everything else in the infinite-channel chain (cursor seeding, extension orchestration, append-only extension) only matters because LineupExtender keeps calling it on a sensible cadence. Without this component, a ComBreakDirect channel is just a one-shot lineup — no different from a DizqueTV channel.
File: ComBreakDirect/utilities/BroadcastTower.py
Classes: BroadcastTower, Antenna
Purpose: Multi-client streaming distribution engine using the broadcast tower metaphor. Provides true broadcast-style streaming where a single source feeds multiple clients simultaneously.
Architecture Metaphor:
- BroadcastTower: Like a TV broadcast tower - receives signal from broadcast FFmpeg and transmits to all antennas
- Antenna: Individual client receiver with minimal buffer for signal stability
- No Buffering at Tower: Only transmits what's broadcasting RIGHT NOW (live signal only)
Key Features & Process:
BroadcastTower Class:
- Initialization: Creates empty antenna list, initializes stats tracking
-
broadcast(chunk: bytes): Sends MPEG-TS chunk to ALL connected antennas immediately- No buffering - chunk is immediately distributed and discarded
- Calls
antenna.receive(chunk)for each antenna - Updates broadcast statistics
-
connect_antenna(client_id: str) -> Antenna: Creates new Antenna for connecting client- Antenna joins at LIVE position (no historical signal)
- Returns Antenna object for client to iterate
-
disconnect_antenna(antenna: Antenna): Removes antenna from active list -
has_antennas() -> bool: Critical for lifecycle management- Broadcast FFmpeg checks this to determine if it should continue
- When returns False, broadcast FFmpeg stops
-
get_stats() -> dict: Returns active antenna count and broadcast totals
Antenna Class:
- Initialization: Creates client-specific buffer (132 chunks, ~2 seconds at 66 chunks/sec)
-
receive(chunk: bytes): Called by BroadcastTower to add chunk to buffer- If buffer full, oldest chunk dropped (tracks as "signal lost")
- Uses deque with maxlen for automatic overflow handling
-
read_signal(timeout: float) -> Optional[bytes]: Blocking read with timeout- Waits for next chunk or timeout
- Returns None on timeout or disconnect
-
__iter__() -> Iterator[bytes]: Rate-limited iteration over signal- Yields chunks with 13ms interval (matches broadcast rate)
- Prevents client from buffering ahead
- Auto-disconnect detection via
activeflag
-
disconnect(): Cleanup method- Sets
active = Falseto stop iteration - Removes self from BroadcastTower
- Logs statistics (chunks received, signal lost count)
- Sets
Threading & Synchronization:
-
BroadcastTower: Uses
threading.Lockandthreading.Conditionfor thread-safe antenna management - Antenna: Individual lock and condition per client for independent buffering
- No Race Conditions: Lock protects antenna list modifications, condition signals new chunks
Rate Limiting:
- Antenna Iteration: 13ms per chunk (~75 chunks/second, ~5.4 Mbps for 9400-byte chunks)
- Purpose: Prevents clients from draining buffer faster than broadcast rate
- Result: Clients forced to consume at real-time rate, can't buffer way ahead
Signal Stability:
- Buffer Size: 132 chunks (~2 seconds) provides network jitter tolerance
- Signal Lost Tracking: Counts when client can't keep up with broadcast rate
-
Auto-Disconnect: Iteration stops cleanly when
active = False
Integration with UnloadingDock:
- Created by
UnloadingDock.create_broadcast_tower(channel_number) - Fed by broadcast FFmpeg via
broadcast(chunk)calls - Clients connect via
UnloadingDock.connect_client()which returns Antenna - Flask generator iterates Antenna:
for chunk in antenna: yield chunk
Why This Architecture Works:
- Single Source: Broadcast FFmpeg creates one continuous stream per channel
- Unlimited Clients: BroadcastTower distributes to unlimited antennas with minimal overhead
- No Tower Buffering: Prevents clients from reading ahead (only live signal broadcast)
- Small Antenna Buffer: Just enough for network stability (~2 seconds)
- Rate Limiting: Forces real-time consumption via 13ms iteration interval
- Resource Efficient: No per-client transcoding - single transcode distributed to all
Statistics & Monitoring:
- BroadcastTower: Tracks total chunks broadcast, total MB broadcast, active antenna count
- Antenna: Tracks chunks received, signal lost count (buffer overflows)
-
Logging:
[BROADCAST_TOWER]and[ANTENNA]prefixes for debugging
Critical Role in Multi-Client Support:
The BroadcastTower is what enables multiple clients (VLC, Plex, Jellyfin) to watch the same channel simultaneously without conflicts or per-client transcoding overhead. Combined with broadcast FFmpeg's +genpts flag, it creates the truly continuous multi-client streaming experience.
File: ComBreakDirect/utilities/AudioTrackSelector.py
Class: AudioTrackSelector
Purpose: Intelligent audio track selection for multi-audio video files. Automatically selects the appropriate audio track based on user preferences during streaming.
Problem Solved: Anime often contains multiple audio tracks (Japanese original, English dubs, director commentary, etc.). Without intelligent selection, FFmpeg would default to the first track, which might not be the desired language. AudioTrackSelector analyzes available tracks and selects the best match based on configuration.
Configuration:
-
DEFAULT_LANGUAGE: Set in
config.py(defaults to'english'for Toonami's English dub focus) -
LANGUAGE_VARIATIONS: Dictionary defining language tag variations
- Example:
'english': ['eng', 'english', 'en', 'en-us', 'en-gb'] - Supports multiple languages: English, Japanese, Spanish, French, German, etc.
- Example:
Key Methods:
-
find_best_audio_track(file_path, preferred_language): Main selection method- Analyzes file using FFprobe to enumerate audio tracks
- Searches for tracks matching preferred language
- Returns audio track index (0-based)
- Fallback: Returns 0 (first track) if no language match found
-
get_audio_tracks(file_path): Uses FFprobe to enumerate available audio tracks- Returns list of dicts with track metadata (index, language, title, codec)
-
get_ffmpeg_audio_mapping(file_path): Generates FFmpeg arguments for audio selection- Returns list like
['-map', '0:a:2']to select specific audio track - Used by Studio thread when spawning FFmpeg for programs
- Returns list like
Selection Logic:
- Configured Language Match: Searches all audio tracks for configured DEFAULT_LANGUAGE
- Language Tag Variations: Checks all variations (e.g., 'eng', 'en', 'english')
- Case Insensitive: Matches regardless of capitalization
- First Track Fallback: If no language match, defaults to first audio track
- Consistency: Maintains same audio selection across all segments of an episode
Usage in ComBreakDirect:
- Called by
UnloadingDockStudio thread during program FFmpeg spawning - Integrated with
CommercialBreakRendererfor break rendering - Respects user's language preference from config.py
- Ensures consistent audio across all content
Example Configuration:
# In config.py
DEFAULT_LANGUAGE = 'english' # or 'japanese', 'spanish', etc.
LANGUAGE_VARIATIONS = {
'english': ['eng', 'english', 'en', 'en-us', 'en-gb'],
'japanese': ['jpn', 'japanese', 'jp', 'ja'],
'spanish': ['spa', 'spanish', 'es', 'es-es', 'es-mx']
}Error Handling:
- Gracefully handles files with missing audio metadata
- Returns first track (index 0) on any FFprobe errors
- Logs warnings for problematic files
Significance: This component eliminates the need for manual audio track specification and ensures viewers always get the correct language track (English for Toonami dubs by default), even when source files contain multiple audio streams.
File: ComBreakDirect/utilities/CommercialBreakRenderer.py
Class: CommercialBreakRenderer
Purpose: Pre-rendering system for commercial breaks. Eliminates startup delays by rendering commercial breaks ahead of time and maintaining a cache of ready-to-stream break files.
The Problem: Originally, commercial breaks were rendered on-demand during streaming, causing:
- 30+ second delays when starting channels
- Timeout issues with Plex/Jellyfin
- Poor user experience during first playback
- CPU spikes during streaming
The Solution: Pre-rendering system that:
- Renders breaks ahead of time (1 hour window by default)
- Stores rendered breaks in
_pre_rendered_breaks/folder - Background thread maintains the break library
- Instant playback when commercial slots are needed
Key Methods:
-
plan_break(break_id, duration_ms): Creates break plan without rendering- Generates unique break ID based on BLOCK_ID, network, marker, and duration
- Reserves output file path:
_pre_rendered_breaks/<break_id>.ts - Selects random commercials that fit duration (with tolerance)
- Stores break plan in cache for later rendering
-
get_or_build_break(break_id, duration_ms): Gets cached break or renders it- Checks if break already rendered and cached
- If missing, renders immediately using FFmpeg
- Returns file path to rendered break
-
pre_render_window(breaks, window_ms): Renders breaks for upcoming time window- Takes list of all breaks in channel
- Filters to breaks within window (e.g., next 1 hour)
- Renders each break if not already cached
- Called by LoadingDock after channel creation
-
pre_render_upcoming_breaks(channel_data, hours_ahead): Proactive rendering for channel- Analyzes channel timeline to find upcoming breaks
- Renders breaks for specified hours ahead (default 1.0)
- Used for initial pre-rendering when channel created
-
start_background_renderer(channels_callback): Continuous background maintenance- Spawns daemon thread that monitors all channels
- Periodically scans for upcoming breaks (every 10 minutes)
- Pre-renders breaks staying 1 hour ahead
- Runs until server shutdown
Rendering Process:
- Commercial Selection: Randomly selects commercials from folder that fit duration
- FFmpeg Concatenation: Uses concat demuxer to stitch commercials
-
Audio Track Selection: Integrates with
AudioTrackSelectorfor correct language - Normalization: Renders to standard format (H.264 1080p 30fps, AAC stereo 48kHz)
-
Output: Saves as MPEG-TS file in
_pre_rendered_breaks/
Break Cache Structure:
- Key: Break ID (unique per BLOCK_ID + network + marker + duration)
-
Value: Dict with
id,path,duration_ms, andcommercialslist - Persistence: Cache maintained in memory (files on disk)
Integration Points:
-
LoadingDock: Calls
plan_break()when injecting commercials, thenpre_render_window()for initial rendering - UnloadingDock: Studio thread plays pre-rendered breaks like any other program
- Background Thread: Started by ComBreakDirectServer on initialization
Performance Benefits:
- Cold Start: First channel creation takes ~25-30s for pre-rendering (acceptable one-time cost)
- Warm Start: Subsequent breaks are instant (already rendered)
- Background Rendering: Maintains cache invisibly while channel running
- No Stream Delays: All breaks ready before they're needed
Configuration:
-
commercial_folder: Path to commercial library -
temp_folder: Location for_pre_rendered_breaks/(defaults toCBDIRECT_DATA_ROOT) -
hours_ahead: How far ahead to pre-render (default 1.0 hour)
Cleanup:
Rendered breaks are cleaned up by CleanupManager when older than 4 hours.
Significance: This component is critical for providing a smooth, TV-like experience. Without pre-rendering, every commercial break would cause a 5-10 second pause while FFmpeg renders the break on-the-fly, destroying the illusion of watching live TV.
File: ComBreakDirect/utilities/CleanupManager.py
Class: CleanupManager
Purpose: Automatic maintenance system for temporary files. Periodically removes old pre-rendered commercial breaks to prevent disk space accumulation.
The Problem:
- Pre-rendered commercial breaks accumulate in
_pre_rendered_breaks/folder - Each break is 50-150 MB depending on duration
- Without cleanup, disk space fills up over time
- Old breaks for past time slots are never needed again
The Solution: Background cleanup thread that:
- Runs every 5 minutes by default
- Removes pre-rendered breaks older than 4 hours
- Minimal CPU/IO impact
- Fully automatic (no user intervention needed)
Key Methods:
-
__init__(temp_folder): Initializes with path to_pre_rendered_breaks/folder -
start_cleanup_thread(break_max_age_hours, cleanup_interval_minutes): Starts background cleanup- Spawns daemon thread for automatic cleanup
-
break_max_age_hours: How old breaks must be before deletion (default 4 hours) -
cleanup_interval_minutes: How often to run cleanup (default 5 minutes) - Returns thread object
-
_cleanup_old_breaks(max_age_hours): Performs actual cleanup- Scans
_pre_rendered_breaks/folder for.tsfiles - Checks file modification time
- Deletes files older than threshold
- Logs cleanup actions
- Scans
Cleanup Logic:
-
File Discovery: Lists all
.tsfiles in temp folder - Age Check: Compares file modification time to current time
-
Threshold Comparison: If
(now - mtime) > max_age_hours, delete - Safe Deletion: Catches and logs exceptions for locked/missing files
Integration:
-
Started by:
FactoryFloorduring initialization - Runs alongside: CommercialBreakRenderer background thread
- Coordinates with: Pre-rendering system (cleans up after renderer)
Configuration:
# Default values
break_max_age_hours = 4.0 # Delete breaks older than 4 hours
cleanup_interval_minutes = 5.0 # Run cleanup every 5 minutesPerformance Characteristics:
- CPU Impact: Minimal (simple file stat checks)
- IO Impact: Low (only scans one folder)
- Disk Space Savings: Prevents unbounded growth
- Frequency: 5-minute interval balances cleanup vs overhead
Why 4 Hours?:
- Pre-renderer maintains 1-hour ahead cache
- Provides 3-hour safety margin for already-rendered breaks
- Breaks older than 4 hours are guaranteed to be in the past
- Never deletes breaks that might still be needed
Thread Safety:
- Daemon thread (dies with parent process)
- No coordination needed (file deletion is atomic)
- Cleanup runs independently of rendering
Logging:
- Logs each cleanup run
- Reports number of files deleted
- Warns on deletion errors (file locked, permissions, etc.)
Significance: CleanupManager is the "janitor" that keeps the server running smoothly long-term. Without it, a server running 24/7 would fill its disk with thousands of old commercial break files. With it, the system maintains a steady state with only recent/upcoming breaks stored.
File: ComBreak/DurationManager.py
Class: DurationManager
Purpose: Centralized singleton manager for video duration extraction using ffprobe. Provides caching to avoid redundant file probing operations.
Key Features & Process:
-
Singleton Pattern:
- Only one instance exists per application
- Accessed via
get_duration_manager()function - Thread-safe implementation
-
Duration Extraction (
get_durationmethod):- Takes a file path and returns duration in seconds (float)
- Uses ffprobe to query video metadata
- Command:
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1
-
Caching System:
- Internal cache stores
{file_path: duration}mappings - Cache key includes file modification time to detect changes
- Subsequent calls for same file return cached value
- Significantly improves performance for repeated queries
- Internal cache stores
-
Error Handling:
- Returns
0.0if file doesn't exist - Returns
0.0if ffprobe fails - Logs errors for debugging
- Returns
-
Cache Management:
-
clear_cache()- Clears all cached durations - Automatic invalidation on file modification
-
- Usage Pattern:
from ComBreak.DurationManager import get_duration_manager
duration_mgr = get_duration_manager()
duration_seconds = duration_mgr.get_duration("/path/to/video.mkv")Significance: Centralizes all duration queries throughout the application, preventing redundant ffprobe calls and improving performance. Used by BumpCalculator, CutlessFinalization, and other components that need video duration information.
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.md and the placeholder in Component-Documentation.md. 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.