iSponsorBlockTV: SponsorBlock for YouTube TV Clients, Paired Over the Lounge API

What iSponsorBlockTV is for, and who it is aimed at

SponsorBlock is a crowdsourced database of video segments (sponsor reads, intros, outros, self-promotion) that a browser extension can skip. That extension does not exist inside a television. iSponsorBlockTV fills that gap: it runs on a computer with network access, connects to the YouTube TV app on your device, and issues skip commands when playback enters a segment recorded in the SponsorBlock database. The README also states it can auto mute and press the "Skip Ad" button as soon as that button appears.

The target user is someone who watches YouTube on a living-room device and already tolerates running a small always-on service. The project's own compatibility table lists Apple TV, Samsung TV (Tizen), LG TV (WebOS), Android TV, Chromecast, Google TV, Roku, Fire TV, CCwGTV, Nintendo Switch, Xbox One and Series, and Playstation 4 and 5 as working. That breadth is the point: one service, many clients, because they all speak the same Lounge protocol underneath.

How it works: Lounge pairing, SponsorBlock lookups, and skip commands

The README names pyytlounge as the library used to interact with the device. That is the mechanism: YouTube TV clients expose a pairing flow, and iSponsorBlockTV acts as a second screen on the same session. The README states the device can be added manually with a YouTube TV code found in the settings page of the YouTube TV application, and that auto discovery requires the computer to be on the same network as the device during setup. Once paired, the computer only needs access to youtube.com; it does not need to stay on the same LAN.

Segment data comes from the SponsorBlock API at sponsor.ajay.app. The v2.10.0 release notes state that alternative SponsorBlock API URLs are supported, which matters if the public instance is slow or you want to point at a mirror. Auto discovery uses the ssdp library, and pychromecast and zeroconf appear in requirements.txt. The v2.11.0 release notes describe fixing a blind SSRF on DIAL auto discovery, which is a useful reminder that discovery accepts network input and has needed hardening.

One operational detail from the README deserves attention: YouTube changed the screen ID code format and is revoking existing codes, so devices must be paired again. Pairing is not a one-time cost.

Installing iSponsorBlockTV with Docker Compose

The README points to the wiki for installation and does not inline the steps, so the most concrete path in the repository is the compose file. It references the image ghcr.io/dmunozv04/isponsorblocktv, sets the container name to iSponsorBlockTV, restarts unless stopped, and mounts a host directory at /app/data. Replace the placeholder with a real path before running it.

First run: pairing a device and editing config.json

Bring the stack up with the repository's docker-compose.yml in place. The image entrypoint is python3 -u main.pyc, and the Dockerfile sets iSPBTV_docker=True and iSPBTV_data_dir=data, so the container writes its state under /app/data, which is the directory you mounted.

docker compose up -d
docker compose logs -f iSponsorBlockTV

The repository ships config.json.template at the top level, and the data directory is where the running service keeps its configuration. The README describes two ways to register a device: auto discovery, which needs the host on the same network as the TV during setup, or a manual YouTube TV code taken from the settings page of the YouTube TV app. After pairing, the README states the host only needs access to youtube.com, so you can move the container to a different network or a remote server once setup is done.

The project also ships a graphical configurator built on Textual, listed in the README's libraries section. If you prefer not to hand-edit JSON, that is the intended interface for the configuration file rather than editing keys blind.

Where iSponsorBlockTV breaks down

Shorts. The README states Shorts are not fully supported due to limitations on YouTube's side, and it describes a workaround: either choose the "Disconnect" option in the warning shown, or long press the thumbnail to open the menu and play from there. If Shorts are a large part of your viewing, this project will frustrate you.

Apple TV has a documented caveat. The compatibility table marks it working with an asterisk, and the note says ad muting will not work when AirPlay is sending audio to another speaker.

Pairing fragility is the third failure mode. The README's warning about YouTube revoking screen ID codes means a working setup can stop working without any change on your side, and the fix is to pair again. Treat pairing as maintenance, not installation.

Finally, the README does not document rollback, version pinning, or a migration path between configuration formats. If you need a documented upgrade procedure before you deploy, the repository does not currently provide one.

The alternative, and the actual difference in approach

The obvious alternative is the SponsorBlock browser extension. The difference is architectural, not cosmetic: the extension runs inside the page, reads the video element directly, and seeks the player. iSponsorBlockTV runs outside the device entirely, pairs as a Lounge client, and sends remote-control commands to the TV app. That is why it works on a Playstation or a Roku where you cannot install an extension, and why it depends on pairing staying valid, on the Lounge protocol not changing, and on the network path to youtube.com. If your viewing happens in a browser, the extension is simpler and has fewer moving parts. iSponsorBlockTV earns its place only when the player is a television.

The README also notes a Home Assistant addon maintained separately by bertybuttface. That is a packaging difference rather than a different mechanism, and it is worth knowing if you already run Home Assistant and would rather not maintain a second compose stack.

Maintenance cost, licence, and what to check before deploying

The repository is not archived, and the last push was on 2026-10-20. Releases have been frequent: v2.9.0 improved pairing, v2.10.0 added alternative SponsorBlock API URLs, and v2.11.0 fixed a blind SSRF on DIAL auto discovery. That release cadence tells you the maintainer is reacting to breakage, which is the realistic expectation for a project that depends on an undocumented client protocol.

The licence is GPL-3.0, per both the repository and the pyproject classifier. If you fork it, modify it, or ship it inside a product, the copyleft terms apply to the distributed work. If you run it at home for your own television, that is the ordinary use case the project is built for. This is not legal advice; read LICENSE.md.

The upgrade path is the container image. The compose file does not pin a tag, so pulling the image gets you the latest build. If you want to avoid a surprise pairing change, pin the image tag yourself, because the repository does not document downgrade steps.

Editorial conclusion

Adopt iSponsorBlockTV if your household watches YouTube through a TV app (Apple TV, Tizen, WebOS, Android TV, Chromecast, Roku, Fire TV, consoles) and you want SponsorBlock behaviour without a browser extension. Skip it if you only watch YouTube in a desktop browser, where the official SponsorBlock extension already covers you, or if you need Shorts handled cleanly, because the README states Shorts are not fully supported. Before committing, verify three things: that you can re-pair the device after YouTube revokes its screen ID code, that your config.json holds the device you expect, and that the container can reach youtube.com from wherever you host it.

Frequently asked questions

Official sources

1. dmunozv04/iSponsorBlockTV on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases