iSponsorBlockTV

iSponsorBlockTV is a self‑hosted service that augments the YouTube TV experience by programmatically skipping undesirable video segments—such as sponsor slots, intros, or ads—on a wide range of smart‑TV platforms. The application acts as an intermediary between the device’s YouTube client and the public SponsorBlock API, translating segment data into playback commands. From a developer standpoint, it presents a clean asynchronous architecture built in Python 3.11+, leveraging modern libraries to handle network communication, device discovery, and user interaction.

Technical Stack & Architecture

• Language: Python 3.11+, chosen for its async capabilities and mature ecosystem.
• Core Libraries:
  • pyytlounge – a community‑maintained wrapper that exposes the YouTube TV API for remote control of devices.
  • asyncio & aiohttp – provide non‑blocking HTTP requests to the SponsorBlock service and device endpoints.
  • async-cache – in‑memory caching of segment data to reduce API calls during long sessions.
  • ssdp – implements Simple Service Discovery Protocol for auto‑detecting devices on the local network.
  • Textual – a TUI framework that powers an interactive configuration wizard, enabling developers to tweak settings without editing YAML or JSON.
• Data Flow:
  1. Device discovery via SSDP or manual code entry registers a device session.
  2. The application polls the YouTube TV client for current playback metadata.
  3. When a segment is detected, the SponsorBlock API is queried for relevant timestamps.
  4. Commands (seek, mute, or click “Skip Ad”) are sent back to the device through pyytlounge.

The architecture is modular: each component (discovery, API client, command executor) runs in its own coroutine, allowing horizontal scaling by spawning multiple instances behind a reverse proxy if needed.

Core Capabilities & APIs

• Segment Detection: Supports all SponsorBlock categories (sponsor, intro, outro, etc.) with configurable filters.
• Playback Control: Executes precise seek operations and toggles mute, leveraging the native YouTube TV controls.
• Ad Skipping: Detects ad overlays and programmatically presses the “Skip Ad” button as soon as it appears.
• RESTful API: Exposes a lightweight HTTP interface for external tools to query current status, list connected devices, or trigger manual skips.
• Webhooks: Optional webhook support allows external services (e.g., Home Assistant) to react to skip events or device state changes.

Deployment & Infrastructure

iSponsorBlockTV is distributed as a Docker image (ghcr.io/dmunozv04/isponsorblocktv), simplifying containerized deployment across Raspberry Pi, NAS devices, or cloud VMs. The service requires:

• Network access to youtube.com and the local network for SSDP discovery.
• Python runtime (or Docker) with at least 512 MiB RAM; a single instance comfortably handles dozens of devices.
• Optional reverse proxy (Traefik, Nginx) for secure HTTPS endpoints and rate limiting.

For high‑availability setups, the application can be orchestrated with Docker Compose or Kubernetes. The stateless nature of the API client and caching layer makes scaling trivial—multiple replicas can share a Redis backend for cache persistence if needed.

Integration & Extensibility

Developers can extend iSponsorBlockTV through:

• Custom Plugins: The TUI framework accepts plugin modules, enabling new command sets or UI widgets without modifying core code.
• Webhook Hooks: External systems can subscribe to skip events, making it a first‑class component in home automation stacks (e.g., Home Assistant add‑on).
• API Clients: The exposed REST API can be consumed by mobile apps, browser extensions, or other automation tools to trigger skips programmatically.

The open‑source license (GPLv3) encourages derivative works, and the active community contributes bug fixes and feature enhancements, as evidenced by the growing list of contributors.

Use Cases

• Home Automation: Integrate with Home Assistant to mute TV audio during ads or automatically skip sponsor segments when a user starts a show.
• Media Centers: Deploy on a Raspberry Pi that also runs Plex or Kodi, providing a unified “ad‑free” viewing experience across devices.
• Enterprise Streaming: Large venues or classrooms can host a single instance that manages multiple YouTube TV devices, ensuring consistent playback control.
• Developer Testing: QA teams can simulate ad‑free scenarios by programmatically skipping segments during automated UI tests.

Advantages for Developers

• Performance: Asynchronous design minimizes latency; skips occur within milliseconds of detection.
• Flexibility: Full control over segment categories and playback behavior; no vendor lock‑in.
• Licensing: GPLv3 guarantees that improvements remain open, fostering a collaborative ecosystem.
• Community & Documentation: Comprehensive wiki and active issue tracker reduce onboarding time for new contributors.

In summary, iSponsorBlockTV offers a robust, extensible platform for developers who need fine‑grained control over YouTube TV playback across diverse hardware, all while staying within the bounds of an open‑source license and modern Python tooling.