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 GUI/FrontEndLogic.py serves as the API layer for all user interfaces:
┌─────────────────┬─────────────────┬─────────────────┐
│ TOM.py │ Absolution.py │ clydes.py │
│ (Tkinter) │ (Web/REMI) │ (CLI) │
└─────────┬───────┴─────────┬───────┴─────────┬───────┘
│ │ │
└─────────────────┼─────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ FrontEndLogic.py (Orchestrator) │
│ • LogicController class │
│ • State management via SQLite │
│ • Real-time communication (Redis/PubSub) │
│ • Threading for background operations │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ToonamiTools & ComBreak 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
- 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
├── GUI/ # User interfaces
│ ├── FrontEndLogic.py # Central orchestrator API
│ ├── TOM.py # Primary Tkinter GUI
│ ├── Absolution.py # Web interface (REMI)
│ ├── CommercialBreaker.py # Standalone GUI for ComBreak
│ └── FlagManager.py # Global flag management
├── 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:
# GUI/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:
# For TOM (Tkinter)
class NewPage(ttk.Frame):
def __init__(self, parent, controller, logic):
self.logic = logic # LogicController instance
# Subscribe to updates
self.logic.subscribe_to_status_updates(self.update_status)
# Button handler
button = ttk.Button(self, command=self.logic.new_feature)
# For Absolution (Web)
class NewPage(BasePage, RedisListenerMixin):
def __init__(self, app, *args, **kwargs):
self.logic = LogicController()
# Redis listener for real-time updates
self.start_redis_listener_thread(self.redis_queue)
# Same API call
button.onclick.connect(self.logic.new_feature)Provide user feedback for all operations:
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:
# GUI/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 Redis vs PubSub 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.