Repository navigation
Developer Guide
This guide provides information for developers who want to contribute to CommercialBreaker & Toonami Tools or understand the codebase structure.
The codebase uses a central orchestrator pattern where API/FrontEndLogic.py serves as the API layer for all user interfaces:
┌─────────────────┬─────────────────┬─────────────────┐
│ TOM.py │ Absolution.py │ clydes.py │
│ (Tkinter) │ (Web/REMI) │ (CLI) │
└─────────┬───────┴─────────┬───────┴─────────┬───────┘
│ │ │
└─────────────────┼─────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐ ┌──────────────────────────────┐
│ FrontEndLogic.py (Orchestrator/API) │ │ Supporting API Modules │
│ • LogicController class │======│ ─────────────────────────── │
│ • State management via SQLite │ │ FlagManager.py │
│ • Threading for background operations │ │ • Platform compatibility │
└─────────────────────────────────────────────────────────────┘ │ • Global flags │
│ │ message_broker.py │
▼ │ • In-memory pub/sub │
┌─────────────────────────────────────────────────────────────┐ │ • Real-time communication │
│ ToonamiTools & ComBreak Modules (Core Logic) │ └──────────────────────────────┘
└─────────────────────────────────────────────────────────────┘
Supporting modules are used by FrontEndLogic for platform checks and real-time updates, but are not intermediary layers between the orchestrator and the core processing modules.
- Single Source of Truth: FrontEndLogic.LogicController manages all application state
- Interface Agnostic: Same API works for GUI, web, and CLI interfaces
- Real-time Updates: Status broadcasting keeps all UIs synchronized via the message broker
- Background Processing: Long operations run in threads with progress updates
- Platform Compatibility: Automatic evaluation of features like cutless mode
# Python 3.11+ required
python --version
# Install dependencies
pip install -r requirements.txt
# For GUI development (optional)
pip install -r requirements/graphics.txtCommercialBreaker/
├── main.py # Entry point - interface selection
├── API/ # Orchestration and API modules
│ ├── FrontEndLogic.py # Central orchestrator API (LogicController)
│ └── components/ # Supporting components
│ ├── FlagManager.py # Global flag management
│ └── MessageBroker.py # In-memory pub/sub for real-time updates
├── GUI/ # User interfaces
│ ├── TOM.py # Primary Tkinter GUI
│ ├── Absolution.py # Web interface (REMI)
│ └── CommercialBreaker.py # Standalone GUI for ComBreak
├── CLI/ # Command-line interfaces
│ ├── clydes.py # Interactive CLI
│ └── CommercialBreakerCLI.py
├── ComBreak/ # Commercial detection system
│ ├── CommercialBreakerLogic.py # Main orchestrator
│ ├── ChapterExtractor.py # Chapter-based detection
│ ├── SilentBlackFrameDetector.py # Audio/video detection
│ ├── VideoCutter.py # File cutting operations
│ ├── VirtualCut.py # Cutless mode operations
│ └── ...
├── ToonamiTools/ # Toonami-specific automation
│ ├── LoginToPlex.py # Plex authentication
│ ├── toonamichecker.py # Show validation
│ ├── commercialinjector.py # Bump insertion
│ └── ...
└── ExtraTools/ # Case use utilities
When adding new functionality, integrate with the orchestrator:
# API/FrontEndLogic.py
class LogicController:
def new_feature(self):
def feature_thread():
self._broadcast_status_update("Starting new feature...")
# Your logic here
tool = ToonamiTools.NewTool()
result = tool.run()
self._broadcast_status_update("Feature completed!")
thread = threading.Thread(target=feature_thread)
thread.start()All UIs should use the same LogicController API and subscribe to updates via the message broker:
# For TOM (Tkinter)
class NewPage(ttk.Frame):
def __init__(self, parent, controller, logic):
self.logic = logic # LogicController instance
# Subscribe to updates via message broker
self.logic.subscribe_to_updates('status_updates', self.update_status)
# Button handler
button = ttk.Button(self, command=self.logic.new_feature)
# For Absolution (Web)
class NewPage(BasePage):
def __init__(self, app, *args, **kwargs):
self.logic = LogicController()
# Subscribe to updates via message broker
self.logic.subscribe_to_status_updates(self.update_status_display)
# Same API call
button.onclick.connect(self.logic.new_feature)Provide user feedback for all operations using the message broker:
def long_running_operation(self):
self._broadcast_status_update("Initializing...")
for i, item in enumerate(items):
self._broadcast_status_update(f"Processing {i+1}/{len(items)}: {item}")
# Process item
self._broadcast_status_update("Operation completed!")Use consistent error handling with user feedback:
def risky_operation(self):
try:
self._broadcast_status_update("Starting operation...")
# Risky code here
self._broadcast_status_update("Operation successful!")
except SpecificException as e:
error_msg = f"Known error occurred: {str(e)}"
self._broadcast_status_update(error_msg)
except Exception as e:
error_msg = f"Unexpected error: {str(e)}"
self._broadcast_status_update(error_msg)
raise # Re-raise for debugging- Create your tool class:
# ToonamiTools/YourNewTool.py
import sqlite3
import config
class YourNewTool:
def __init__(self, param1, param2):
self.param1 = param1
self.param2 = param2
self.db_path = f'{config.network}.db'
def run(self):
# Your tool logic
with sqlite3.connect(self.db_path) as conn:
# Database operations
pass
return result- Add to ToonamiTools/init.py:
from .YourNewTool import YourNewTool- Integrate with FrontEndLogic:
# API/FrontEndLogic.py
def use_your_new_tool(self):
def tool_thread():
self._broadcast_status_update("Running your new tool...")
param1 = self._get_data("some_config")
param2 = self._get_data("other_config")
tool = ToonamiTools.YourNewTool(param1, param2)
result = tool.run()
self._broadcast_status_update("Tool completed!")
thread = threading.Thread(target=tool_thread)
thread.start()Follow the existing component architecture:
# ComBreak/YourComponent.py
class YourComponent:
def __init__(self, config_params):
self.config = config_params
def process(self, input_data):
# Component-specific logic
return processed_data
def cleanup(self):
# Resource cleanup
passIntegrate with CommercialBreakerLogic:
# ComBreak/CommercialBreakerLogic.py
def enhanced_detection(self, files, output_dir):
component = YourComponent(self.config)
for file in files:
result = component.process(file)
# Handle result
component.cleanup()- Long Operations: Always run in background threads
- UI Updates: Use broadcast messages, not direct UI manipulation
- Resource Management: Implement proper cleanup in finally blocks
def resource_intensive_operation(self):
def operation_thread():
resource = None
try:
self._broadcast_status_update("Acquiring resources...")
resource = acquire_expensive_resource()
self._broadcast_status_update("Processing...")
result = process_with_resource(resource)
self._broadcast_status_update("Operation completed!")
except Exception as e:
self._broadcast_status_update(f"Error: {str(e)}")
finally:
if resource:
resource.cleanup()
thread = threading.Thread(target=operation_thread)
thread.start()- Large Files: Process in chunks
- Temporary Files: Clean up promptly
- Database Connections: Use context managers
def process_large_file(self, file_path):
try:
with open(file_path, 'rb') as f:
while True:
chunk = f.read(8192) # 8KB chunks
if not chunk:
break
process_chunk(chunk)
except IOError as e:
self._broadcast_status_update(f"File error: {e}")When adding features that support cutless mode:
def feature_with_cutless_support(self):
cutless_enabled = FlagManager.cutless
if cutless_enabled:
# Virtual processing path
self.create_virtual_entries()
else:
# Traditional file processing path
self.process_physical_files()Use the FlagManager for platform compatibility:
def platform_specific_feature(self):
platform_type = self._get_data("platform_type")
if platform_type == "dizquetv":
self.dizquetv_implementation()
elif platform_type == "tunarr":
self.tunarr_implementation()
else:
raise ValueError(f"Unsupported platform: {platform_type}")Use the broadcast system for user-visible logs:
def debug_operation(self):
self._broadcast_status_update("Debug: Starting operation")
# For developer debugging
print(f"Debug: Internal state = {self.internal_state}")
# For user feedback
self._broadcast_status_update("Processing step 1 of 3...")- Status Updates Not Appearing: Check message broker configuration
- Threading Issues: Ensure UI updates only via broadcasts
- Database Locks: Use shorter connection contexts
- Platform Compatibility: Verify FlagManager.cutless evaluation
Follow Python conventions:
- Use type hints where practical
- Document classes and complex functions
- Keep methods focused and single-purpose
- Use descriptive variable names
- Fork and Branch: Create feature branch from main
- Implement: Follow architecture patterns
- Test: Add unit tests for new functionality
- Document: Update relevant documentation
- Review: Submit PR with clear description
When adding features:
- Update API-Reference for new orchestrator methods
- Update Component-Documentation for new tools
- Update User-Guides for new UI features
- Add FAQ entries for common questions
To create a new interface:
- Implement LogicController Integration:
class CustomInterface:
def __init__(self):
self.logic = LogicController()
self.logic.subscribe_to_status_updates(self.handle_status)
def handle_status(self, message):
# Update your interface
pass- Add to main.py:
def main():
parser.add_argument('--custom', action='store_true')
if args.custom:
from CustomInterface import run_custom_interface
run_custom_interface()This architecture enables flexible extension while maintaining consistency across the codebase.
S.A.R.A. is a comprehensive testing framework that validates the entire ToonamiTools workflow using simulated data.
S.A.R.A. executes a complete workflow test that includes:
- Content preparation and filtering
- Simulated commercial detection using fake timestamps
- Cutless mode processing
- Database operations
- Complete Lineup creation logic
The test suite uses zero-byte files to simulate your media library structure, making it fast and resource-efficient while still testing all critical code paths.
To run the S.A.R.A. test suite, ensure you have pytest installed and execute the following command in your terminal from the root of the project:
pytest tests/test_sara_automatic.py -vFor more detailed output with S.A.R.A.'s transmission logs:
pytest tests/test_sara_automatic.py -v -sS.A.R.A. requires a sample.txt file that defines your simulated media library structure. This file should be placed at tests/fixtures/sample.txt.
The sample.txt file contains a hierarchical listing of your media library structure. You can generate this from an existing media library:
On macOS/Linux:
# Navigate to your media library root
cd /path/to/your/media/library
# Generate the file listing
tree -fi > sample.txt
# Or if tree is not installed, use find:
find . -type f -name "*.mkv" | sort > sample.txtOn Windows:
# PowerShell command
Get-ChildItem -Path "C:\path\to\your\media\library" -Recurse -File -Filter "*.mkv" |
ForEach-Object { $_.FullName.Replace("C:\path\to\your\media\library\", ".\") } |
Sort-Object | Out-File sample.txtYour sample.txt should follow this format:
.
./Anime
./Anime/Death Note
./Anime/Death Note/Season 1
./Anime/Death Note/Season 1/Death Note - S01E01 - Rebirth.mkv
./Anime/Death Note/Season 1/Death Note - S01E02 - Confrontation.mkv
./Anime/Death Note/Season 1/Death Note - S01E03 - Dealings.mkv
./Anime/Attack on Titan/Season 1
./Anime/Attack on Titan/Season 1/Attack on Titan - S01E01 - To You, in 2000 Years - The Fall of Shiganshina (1).mkv
./Anime/Attack on Titan/Season 1/Attack on Titan - S01E02 - That Day - The Fall of Shiganshina (2).mkv
The fixture system (conftest.py) will automatically create zero-byte files matching this structure in a temporary directory during test execution.
-
Setup: Creates a temporary file structure based on
sample.txt - Content Preparation: Simulates content filtering and selection
-
Commercial Detection: Uses
FakeCommercialDetectorto generate realistic timestamp files - Cut List Processing: Tests the cutless mode workflow and verifies the final database entries
- Timing Information: Records and reports the duration of each major step
- Cleanup: Removes temporary files and resets state
S.A.R.A. validates:
- ✅ File system operations
- ✅ Database creation and queries
- ✅ Content filtering logic
- ✅ Commercial detection integration
- ✅ Cut list processing
- ✅ Error handling
- ✅ Final database state
- ✅ Status update propagation
- ✅ Multi-threaded operations
To add new test scenarios:
- Create additional test methods in
TestSaraAutomatic - Use the
self._log_progress()method for S.A.R.A.-themed logging - Leverage the existing fixtures and helper methods
- Follow the pattern of checking status updates with
wait_for_status()
Example:
def test_specific_feature(self):
self._log_progress("Testing specific feature...")
# Your test logic here
assert self.wait_for_status("Expected Status", "Feature Name", timeout=30)If S.A.R.A. tests fail:
- Check that
sample.txtexists and is properly formatted - Ensure you have write permissions in the test directory
- Verify no leftover test databases exist though they should be cleaned up automatically
- Run with
-sflag to see detailed S.A.R.A. transmissions - Check for filename length limitations on your OS though S.A.R.A. should skip excessively long paths by default
S.A.R.A. is designed to run in CI/CD pipelines. The test suite:
- Requires no external dependencies beyond Python packages
- Creates and cleans up its own test data
- Provides clear pass/fail results clearly marked where the point of failure occurred