Estimated reading time: 13 minutes
Do you know this? You're sitting comfortably on the couch, you've just watched an exciting YouTube video on your smart TV, the food is ready, and as soon as you've taken the first bite, the YouTuber interrupts the content. „Before we start, I'd like to introduce you to my partner XY...“ Or even worse: in the middle of the most exciting moment, there's a three-minute monologue about VPNs, razor blades or online role-playing games. At least as annoying is the advertising at the beginning or even in the middle, which is then three times as loud as the video.
You already have a solution for this on the PC: SponsorBlock and uBlockOrigin resp. AdBlock. The ingenious browser extension that marks and automatically skips such segments thanks to a huge community. But on the television? On the Apple TV? On the Chromecast? Until now, you were often powerless and had to frantically reach for the remote control to fast-forward.
But that's over now. Today I'm going to show you a tool that will revolutionize your YouTube experience in the living room: iSponsorBlockTV.
For detailed instructions and explanations of all configuration options, I recommend watching the YouTube video linked below. This video goes into detail about each individual setting, providing you with comprehensive instructions on how to set everything up correctly. Any code from the video can be found in this article, so you can use it directly without having to type it out.
This blog post, including video, is part of a series in which we build and set up our own home server. We start with the basics, such as installing Ubuntu VM with Docker, and then move on to configuring our own domain, security measures, and, above all, lots of cool and useful self-hosted services. Whether it's media servers like Plex or Jellyfin or document management like Paperless-NGX, we'll work together to build the setup you want to see. We'll even tackle topics like single sign-on (SSO) together.
What is iSponsorBlockTV actually?
Before we type code into the terminal, we need to understand what is actually happening here. Because iSponsorBlockTV (iSBTV for short) is not an app that you install on your TV. It is also not a classic ad blocker that blocks network requests (like Pi-hole).
The functional principle: the invisible remote control robot
Imagine iSponsorBlockTV as an invisible assistant sitting next to you on the couch and also staring at your TV. This assistant has access to the SponsorBlock database. So it knows exactly: „Aha, at minute 2:30 the ad for ‚Raid Shadow Legends‘ starts and at 3:45 it's over.“
As soon as your video reaches this timestamp, the invisible assistant presses „Fast forward“ at lightning speed so that you land seamlessly at minute 3:46.
Technically speaking, iSponsorBlockTV runs on a server in your network (e.g. a Raspberry Pi, a NAS or your PC). It connects to your streaming device (Apple TV, Chromecast, Android TV) via the API and constantly asks: „What are you watching? Where are you in the video?“. If there is a match in the database, the script sends the command to jump to the TV.
The huge advantage: You don't need to hack your TV, root it or install any dubious APK files. It works with the official YouTube app!
The features: More than just „advertising gone“
You might be thinking, „Okay, it skips ads.“ But iSBTV is much more powerful. Thanks to SponsorBlock's granular database, you can decide exactly what you want to see and what you don't. Here are the categories you can control:
1. sponsors (sponsor)
This is the classic. Paid product placements that are integrated directly into the video. These segments have nothing to do with the actual content and are usually spoken by the creators themselves.
- Your action: Skip automatically.
2. self-promotion
„Buy my merch!“, „Check out my other channel!“, „I've written a book!“. Even if we want to support our favorite YouTubers - sometimes it's just annoying.
- Your action: You can skip it or leave it in if you're a fan.
3. interaction requests (interaction reminder)
„Guys, don't forget to like, subscribe and press the bell!“ - We hear this in almost every video. iSponsorBlockTV can simply cut out these annoying 10-second phrases.
- Your action: Get rid of it!
4. intro & outro
Some channels have extremely long intros (animations, music) or outros with credits. If you search through a playlist (binge-watching), this disrupts the flow massively.
- Your action: Automatic skipping for seamless enjoyment.
5. music: non-musical part (Music: Off-topic)
A blessing for music videos! Do you know this? You want to watch a music video, but the video has a 2-minute acting intro before the song even starts. iSponsorBlockTV cuts that out and starts right at the beat.
6. preview & review (preview/recap)
„What's happened so far...“ or „In the next video you'll see...“. If you watch the videos one after the other, this is redundant. The tool recognizes and removes it.
Requirements: What do you need?
To make the project a success, you need a little hardware and software. But don't worry, the hurdles are low.
Hardware
- A streaming device:
- Apple TV (tvOS)
- Google Chromecast
- Android TV / Google TV (Nvidia Shield, Sony TVs, Philips TVs, etc.)
- Amazon Fire TV (with restrictions, as Android-based)
- Smart TVs with integrated YouTube app (if they support the Cast protocol)
- A „server“: The script must always when you want to watch TV. Your laptop is unsuitable for this if you close it. Ideal are:
- Raspberry Pi (Model 3, 4 or 5 - even a Zero 2 W is easily sufficient).
- NAS (Synology, QNAP) with Docker support.
- Mini PC / Home Server (Intel NUC, old office PC with Linux).
- Server of a friendYou don't even have to have your own server, it can also be hosted by a friend or cloud provider. The tool does not need access to the local network.
Software
Here we concentrate fully on Docker. Why? Because it's the cleanest method. You don't clutter up your system with Python dependencies, and updates are a breeze.
- You should have basic knowledge of how to use the terminal.
- Docker and Docker Compose must be installed on your server.
Installation via Docker: The step-by-step guide
Now it's time to get down to business. We install iSponsorBlockTV on a Linux-based system (e.g. Raspberry Pi OS or Ubuntu).
We use Docker Compose because it allows us to save the configuration in a file. This makes updates and restarts much easier than long docker run Commands.
Create the file:
nano docker-compose-isponsorblocktv.ymlNow copy the following content into it. I have already optimized the configuration:
services:
isponsorblocktv:
image: ghcr.io/dmunozv04/isponsorblocktv
container_name: isponsorblocktv
restart: unless-stopped
# network_mode: host # to auto-discover devices
networks:
- sascha
environment:
- TZ=Europe/Berlin
volumes:
- /mnt/cache/appdata/network/isponsorblocktv:/app/data:rw
networks:
sascha:
external: trueImportant explanations for this configuration:
image: ghcr.io/dmunozv04/isponsorblocktv:latestWe always download the latest version directly from the developer.restart: unless-stoppedIf the power fails or the Pi restarts, this service also restarts automatically.network_mode: host: That is the most important point! In order for iSponsorBlockTV to find your TVs in the network (Discovery), it must have full access to the network. Without this mode, the detection of the devices often fails.volumes: /mnt/cache/appdata/network/isponsorblocktv:/app/data:rwWe save the configuration (which TVs are paired) outside the container. This means that your settings are not lost during an update.
Save the file with CTRL + O, Enter and close the editor with CTRL + X.
The first start & the setup
Now we start the container. But beware: the first time we have to intervene interactively to run through the setup wizard.
docker run --rm -it --net=host -v /mnt/cache/appdata/network/isponsorblocktv:/app/data ghcr.io/dmunozv04/isponsorblocktv --setup-clior with a graphical user interface:
docker run --rm -it --net=host -v /mnt/cache/appdata/network/isponsorblocktv:/app/data ghcr.io/dmunozv04/isponsorblocktv --setupYou will be guided through a setup guide and do not need to familiarize yourself beforehand. The instructions are self-evident.
The pairing process (The magic begins)
As soon as you execute the setup command, the wizard will welcome you in the terminal.
- YouTube API: The tool will ask you if you want to use the YouTube API. This is optional, but recommended to get better metadata. To get started, you can often skip this or use the default.
- Find devices: The tool will now scan your network. Make sure that your Smart TV / Apple TV / Shield is switched on and the YouTube app is open (or at least the device is active on the network).
- Naming: You will be asked what you want to call the device found (e.g. „Living room TV“).
Now comes the decisive moment: The tool prompts you to log in to your TV. It works in a similar way to when you pair your cell phone with the TV.
- Open the YouTube app on your TV.
- Go to Settings -> Link with TV code.
- A blue numerical code is displayed there (e.g. 123 456 789).
- Now enter this code in your terminal.
Why are we doing this? iSponsorBlockTV pretends to be a „remote control“ for your TV (similar to the YouTube app on your cell phone). Once the code is accepted, your server has permission to query the status („Which video is playing?“) and send commands („Skip to second 400“).
Repeat this process for all televisions in the house (bedroom, kitchen, etc.).
Restart and enjoy
When you are finished with the setup, a config.json in your ./data Folder created.
Open your terminal and you can then simply start the services with the following command (the name must of course be adapted):
docker compose -f "docker-compose-isponsorblocktv.yml" up -dCheck the logs:
docker compose logs -fIf you start a video on the TV now, you should see it in the log: [Living Room TV] Now playing: Linus Tech Tips - Why Windows sucks... [Living room TV] Found 3 segments to skip. [Living Room TV] Skipped Sponsor from 0:00 to 1:30.
It works! 🎉
Fine-tuning: perfecting the configuration
The default settings are good, but we want „perfect“. The file config.json in your data-folder is the key to this. You can create it with nano data/config.json edit.
Here I explain the most important parameters that you can adjust to tailor the behavior exactly to your needs.
Skip vs. mute vs. do nothing
You can define what should happen for each category (sponsor, intro, outro etc.). The modes are:
- skip: Hard skipping.
- mute: The sound is switched off, the video continues to play (good for segments that you want to see but not hear, or if skipping causes errors).
- nothing: The segment is ignored.
Example configuration in the JSON:
"categories": {
"sponsor": "skip",
"intro": "skip",
"outro": "skip",
"interaction": "mute",
"selfpromo": "nothing",
"music_offtopic": "skip"
}In this example: Sponsors are skipped. The „Like & Subscribe“ talk is only muted (maybe the visuals are funny?), and the creator can keep their own advertising.
The „Unskip“ function
Sometimes SponsorBlock skips too much or a segment is marked incorrectly. What happens then? You can set iSBTV to react to certain commands in the config. For example, if you rewind briefly on the remote control, the tool notices: „Oh, the user wants to see this“ and stops skipping this segment immediately.
Whitelisting: Support your favorite creator
This is a morally important point. If you have certain channels whose ads you'd like to watch to support them (or because their ads are actually entertaining - regards go out to Internet Historian), you can whitelist them.
Add the channel ID (not the name, but the ID you find in the URL of the channel) to the config.json under whitelist in.
Troubleshooting: When things get stuck
Technology is never error-free. Here are the most common problems with iSponsorBlockTV and how to solve them.
1. my TV cannot be found
- Cause: It is often due to the network.
- Solution: Do you have
network_mode: hostused in the Docker Compose file? Are the server and the TV in the same subnet? Some routers (FritzBox guest network) isolate devices. Check whether you can ping the TV from the server.
2. the volume fluctuates
- Cause: If you have set segments to „mute“, the tool must change the volume. Sometimes it does not reset it correctly to the original value.
- Solution: It is better to set the category to „skip“ or deactivate the mute function in the config if it is annoying.
3. it is not skipped even though a sponsor is running
- Cause: Sometimes YouTube changes internal protocols or the video ID is not transmitted correctly.
- Solution: Restart the video. Check the log (
docker compose logs) to check whether the video was recognized at all. Sometimes restarting the container helps.
4. connection expires
- Cause: The pairing codes are not valid forever, but iSBTV normally renews the tokens automatically.
- Solution: If nothing works anymore: Delete the
config.json(or the part with the tokens) and run the setup (--setup) again.
Performance & resource consumption
You may be asking yourself: „Will this bring my Raspberry Pi to its knees?“ The answer is a clear one: No.
iSponsorBlockTV is extremely lightweight. It is basically just a text processor that sends small network requests from time to time.
- CPU: Negligible (< 1%).
- RAM: A few megabytes (usually less than 50MB).
- Network: Only a few kilobytes per minute for status queries.
You can easily run this container alongside Home Assistant, Pi-hole and Plex without noticing any loss.
Comparison: SmartTube(Next) vs. iSponsorBlockTV
Many Android TV users swear by SmartTube (formerly SmartTubeNext). So why should you use iSponsorBlockTV?
Here is the comparison:
| Feature | SmartTube | iSponsorBlockTV |
| Platform | Android TV / Fire TV only | All (Apple TV, WebOS, Tizen, Chromecast, Android) |
| Installation | Sideloading (APK) | Docker on external server |
| App feeling | Own app (different interface than YouTube) | Original YouTube app |
| Security | Third-party app (login required) | Uses cast protocol (more secure) |
| Advertising | Blocks banners & sponsors | Blocks only Sponsors (banners may remain) |
YouTube video implementation
Conclusion: A must for every home cinema enthusiast
iSponsorBlockTV is one of those tools you didn't know you needed - until you've used it once. After that, you can't go back. The convenience gain is massive. It's fascinating to see how the TV skips exactly the annoying parts of a video as if by magic.
The installation via Docker may seem daunting for laypersons at first glance, but thanks to the docker-compose method in just a few minutes. Once set up, the system runs maintenance-free in the background for months („set and forget“).
Especially for owners of closed systems such as the Apple TV this is the holy grail. Finally catch up with PC users!
So, what are you waiting for? Power up the Raspberry Pi and reclaim your life!
Useful links at a glance
- GitHub Repository: dmunozv04/iSponsorBlockTV
- SponsorBlock database: sponsor.ajay.app
- Docker documentation: docs.docker.com
0 Comments