Deploying iSponsorBlockTV

Introduction

iSponsorBlockTV is an innovative tool that brings SponsorBlock functionality to YouTube on smart TVs and other devices that don’t support browser extensions. It monitors YouTube playback on your TV and automatically skips sponsor segments, intros, outros, and other user-submitted segments using the crowdsourced SponsorBlock database.

The application works by connecting to your TV’s YouTube app through the local network, detecting when videos play, and sending skip commands at the appropriate timestamps. This seamless integration means you get an ad-free-like experience without modifying your TV’s software.

Key highlights of iSponsorBlockTV:

• Automatic Skipping: Seamlessly skips sponsors, intros, outros, and more without user intervention
• SponsorBlock Integration: Leverages the massive crowdsourced database of segment timestamps
• Multi-Device Support: Works with smart TVs, Chromecast, Apple TV, and other casting devices
• Customizable Categories: Choose which segment types to skip (sponsors, self-promo, interaction reminders, etc.)
• Local Network Operation: Runs on your network without sending data to external servers
• Low Resource Usage: Lightweight application with minimal system requirements
• Web Interface: Easy configuration through a browser-based setup wizard
• Docker Support: Simple containerized deployment for reliable operation
• 100% Open Source: Community-driven development with transparent codebase

This guide walks through deploying iSponsorBlockTV on Klutch.sh using Docker, configuring device pairing, and setting up automatic sponsor skipping.

Why Deploy iSponsorBlockTV on Klutch.sh

Deploying iSponsorBlockTV on Klutch.sh provides several advantages:

Always-On Operation: Your sponsor skipper runs 24/7 without requiring a local computer or server to stay powered on.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds iSponsorBlockTV without manual server configuration.

Persistent Configuration: Device pairings and settings survive container restarts and redeployments.

HTTPS by Default: Secure access to the web configuration interface from anywhere.

GitHub Integration: Updates to your configuration trigger automatic redeployments.

Scalable Resources: Allocate minimal resources for this lightweight application.

Environment Variable Management: Store device tokens securely through Klutch.sh’s environment system.

Prerequisites

Before deploying iSponsorBlockTV on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A smart TV or casting device with YouTube app installed
• Both devices on the same network for initial pairing
• Basic familiarity with Docker

Understanding iSponsorBlockTV Architecture

iSponsorBlockTV operates through a simple but effective architecture:

Device Discovery: The application discovers YouTube-capable devices on your local network using mDNS/DIAL protocols.

Pairing Process: Once paired with a device, iSponsorBlockTV receives a token that allows it to monitor playback and send commands.

Playback Monitoring: The app continuously monitors the current video and playback position.

SponsorBlock API: When a video starts, it queries the SponsorBlock API for community-submitted segment timestamps.

Skip Commands: At segment boundaries, it sends skip commands to the TV to jump past unwanted content.

Preparing Your Repository

Create a GitHub repository for your iSponsorBlockTV deployment.

Repository Structure

isponsorblocktv-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/dmunozv04/isponsorblocktv:latest

# Configuration is handled through config.json
# which is persisted in a volume

# Expose the web interface port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

Advanced Dockerfile with Custom Settings

For more control over your deployment:

FROM ghcr.io/dmunozv04/isponsorblocktv:latest

# Set environment variables for configuration
ENV ANTHROPIC_SKIP_CATEGORIES=${SKIP_CATEGORIES:-sponsor,selfpromo,interaction,intro,outro}

# Create config directory
RUN mkdir -p /app/data

# Expose web interface
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

Skip Categories Reference

Category	Description
sponsor	Paid product placements and sponsorships
selfpromo	Self-promotion, merchandise, and channel plugs
interaction	Subscribe reminders, like requests, engagement prompts
intro	Intro animations and sequences
outro	End cards, credits, and outros
preview	Preview of upcoming content
filler	Tangents and off-topic content
music_offtopic	Non-music sections in music videos

Deploying iSponsorBlockTV on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial iSponsorBlockTV deployment configuration"
git remote add origin https://github.com/yourusername/isponsorblocktv-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “isponsorblocktv” or “youtube-skipper”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select the repository containing your Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Attach Persistent Volumes

Add a volume for configuration persistence:

Mount Path	Recommended Size	Purpose
/app/data	100 MB	Device tokens and configuration

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build and start your iSponsorBlockTV instance.

Access the Web Interface

Once deployed, access the configuration interface at https://your-app-name.klutch.sh.

Pair Your Devices

From the web interface:

1. Click Add Device
2. Ensure your TV and the server can communicate (may require VPN for cloud deployment)
3. Follow the on-screen pairing instructions
4. Enter the pairing code shown on your TV

Configure Skip Categories

Select which segment types you want to skip:

1. Go to Settings
2. Enable or disable each category
3. Save your preferences

Network Considerations

Since iSponsorBlockTV needs to communicate with your TV on the local network, cloud deployment requires network connectivity between Klutch.sh and your home network:

VPN Solution: Set up a VPN (like WireGuard or Tailscale) to connect your Klutch.sh deployment to your home network.

Local Deployment Alternative: For simpler setups, run iSponsorBlockTV on a local device like a Raspberry Pi.

Port Forwarding: Not recommended due to security concerns.

Configuration Options

Adjusting Skip Behavior

Fine-tune how segments are skipped:

• Skip Delay: Add a small delay before skipping to see segment start
• Minimum Duration: Only skip segments longer than a specified duration
• Channel Whitelist: Disable skipping for favorite creators

Multiple Device Support

Add multiple TVs and devices:

1. Each device needs separate pairing
2. All devices share the same skip settings
3. Monitor all devices from the web interface

Troubleshooting

Device Not Found

• Ensure the TV is on and YouTube app is running
• Verify network connectivity between server and TV
• Check that mDNS/DIAL discovery is working

Segments Not Skipping

• Verify the video has segments in SponsorBlock database
• Check that the desired categories are enabled
• Review application logs for errors

Pairing Fails

• Ensure the pairing code is entered correctly
• Try restarting the YouTube app on your TV
• Check for firewall blocking the connection

Additional Resources

• iSponsorBlockTV GitHub Repository
• SponsorBlock Website
• SponsorBlock Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying iSponsorBlockTV on Klutch.sh enables automatic sponsor skipping for YouTube on your smart TV. With persistent configuration and the web-based interface, you can enjoy uninterrupted YouTube viewing without manual intervention.

While network connectivity between your cloud deployment and home TV requires additional setup like a VPN, the always-on nature of Klutch.sh ensures your sponsor skipper is ready whenever you want to watch YouTube.