How dmunozv04/isponsorblocktv works
Project Type and Purpose
• iSponsorBlockTV is a networked, asynchronous Python service that:
• Discovers YouTube‑TV capable devices on the LAN (via SSDP/DIAL)
• Monitors playback on those devices (via pyytlounge)
• Queries the SponsorBlock API for skip segments (with caching)
• Commands the device to skip/mute segments
• Provides a CLI and Textual TUI for configuration
File Structure
Top‑level artifacts:
• Dockerfile & docker‑compose.yml – container build & deployment
• config.json.template – schema for persistent device + user config
• pyproject.toml / requirements.txt – language and dependency declarations
• src/main.py & src/main_tui.py – entry points (daemon vs config UI)
• src/iSponsorBlockTV/ – core library modules
Core modules inside src/iSponsorBlockTV:
• config_setup.py & setup_wizard.py (+ style.tcss) – configuration UI logic
• dial_client.py & ytlounge.py – network protocols for device control
• api_helpers.py – SponsorBlock API client
• conditional_ttl_cache.py – caching layer for API results
• main.py – orchestrator: discovery, monitoring, skip‑logic
• helpers.py, constants.py – utility functions & values
Extract Insights From the README
• Async Python + aiohttp + async-cache + SSDP + Textual
• Two modes:
– Daemon mode (main.py invoked via src/main.py)
– Config mode (main_tui.py invoked via src/main_tui.py)
• External systems: SponsorBlock API, YouTube‑TV devices (over network)
• Deployment via Docker
Components & Relationships
a. Main Components
1. Configuration Layer
– CLI (main.py)
– Textual TUI (main_tui.py & setup_wizard.py)
– config.json (persistent store)
2. Discovery & Registration
– SSDP module (ssdp library)
– Manual code entry from TUI
3. Device Communication
– DIAL Client (dial_client.py)
– pyytlounge Client (ytlounge.py)
4. Core Orchestrator (main.py)
– Event Loop (asyncio)
– Monitor tasks per device
– Skip logic coordinator
5. SponsorBlock API
– api_helpers.py (HTTP via aiohttp)
– conditional_ttl_cache.py (cache layer)
6. Action Executor
– Commands devices to skip/mute segments
7. Infrastructure & Deployment
– Docker / docker‑compose
– Logging / Error handling (helpers.py)
b. Data Flows & Interactions
1. Startup
– CLI/TUI reads config.json → User config entry (if first run)
– TUI writes config.json via config_setup
2. Discovery
– Orchestrator triggers SSDP → Discovers device IPs & capabilities
– or Accepts manual codes → Populates device registry
3. Monitoring Loop (per device)
– pyytlounge WebSocket connection → emits playback events
– Orchestrator sees “new video” or “seek” events
4. Skip Lookup
– On event, Orchestrator calls api_helpers → SponsorBlock API
– utilises conditional_ttl_cache to avoid repeated calls
5. Execute Skip
– Orchestrator sends skip commands via dial_client or ytlounge
6. Logging & Metrics
– helpers.log() captures success/failure, metrics
c. Architectural Patterns / Design Principles
• Asynchronous, event‑driven core using asyncio
• Layered design: UI → Orchestrator → Protocol clients → External APIs
• Single process, modular library + entry‑point scripts
• Configuration as code / persistent JSON + interactive setup
d. Key Technologies & Frameworks
• Python 3.x, asyncio, aiohttp
• async-cache
• ssdp (for discovery)
• pyytlounge (WebSocket control of YouTube‑TV devices)
• Textual (TUI configuration wizard)
• Docker / Docker‑Compose for containerization
Detail
– Capture each module if space allows (or group by layer)
– Show the caching layer sitting between API calls and orchestrator
– Highlight async event loop as the backbone