GitHub - garagehq/Minus-streaming-stick: Minus is a plug-and-play HDMI accessory that stops ads from your streaming devices and swaps them for content you choose. 100% open source—hardware, firmware, and tools included.

Video Demo

Slides From HOPE Talk

Minus is an open-source HDMI box that sits between your streaming device and your TV. It watches the video feed, detects ads with ML models running locally on its own NPUs, then mutes and covers them until your show comes back. Instead of the ad you get something useful, like a Spanish vocabulary card.

Nothing leaves your living room. There is no cloud service, no subscription, and no account. The OCR, the vision model, and the speech recognition all run on the device. The one exception is something you have to switch on yourself: you can choose to share anonymous snapshots of blocked ads to help train the next model. It's off by default; see docs/PRIVACY.md.

An ad break as seen through Minus. The ad is muted and covered by a vocabulary card, with a small greyscale preview in the corner so you can tell when it's over.

How it works

Minus is a 4K@60fps HDMI passthrough. Your Roku, Fire TV, or Google TV plugs into Minus, and Minus plugs into your TV. Three detectors watch the stream and vote on whether an ad is playing:

┌──────────────┐     ┌────────────────────┐     ┌─────────────────────┐
│   HDMI IN    │────▶│     ustreamer      │────▶│  HDMI OUT to TV     │
│ (Roku, etc.) │     │ (MPP hw encoding)  │     │  (DRM/KMS, 60fps)   │
└──────────────┘     └────────┬───────────┘     └─────────────────────┘
                              │ snapshots + audio
              ┌───────────────┼────────────────┐
              ▼               ▼                ▼
     ┌────────────────┐ ┌──────────────┐ ┌──────────────┐
     │  PaddleOCR     │ │  minus-v0.1  │ │  Moonshine   │
     │  RK3588 NPU    │ │  (VLM)       │ │  ASR (CPU)   │
     │  reads ad UI   │ │  Axera NPU   │ │  hears ad    │
     │  text ~200ms   │ │  ~370ms      │ │  language    │
     └────────────────┘ └──────────────┘ └──────────────┘
              └───────────────┼────────────────┘
                              ▼
                    blocking decision engine
              (mute + overlay, typically < 2s to react)

• OCR (PaddleOCR PP-OCRv6 on the RK3588's NPU, ~200ms a frame) reads on-screen ad UI like "Skip in 5", "Ad 2 of 3", and countdown timers, including the character misreads OCR makes on real TVs. When an ad shows its own countdown, Minus reads the number and counts it down in real time, so it knows the ad is still running even while OCR briefly loses the text. That clock only ever helps hold a block that the detectors already started. On its own it never starts one.
• minus-v0.1, a 450M-parameter vision-language model fine-tuned for this exact job, looks at the raw frame and answers "is this an advertisement?" in about 370ms on an Axera AX8850 NPU. It needs no text on screen to work.
• ASR (Moonshine tiny-en on CPU) transcribes the audio and listens for marketing language as a confirmation signal.

When the votes say "ad", audio mutes immediately and the screen switches to an overlay rendered at 60fps inside the hardware JPEG encoder (no desktop stack, no X11). When the ad ends the show comes back after a few seconds, about 5 in practice. Minus waits for several clean frames and a short floor before it lets go, because OCR routinely loses an ad's text for a few seconds mid-ad, and releasing on the first gap would flash the ad back on screen.

The model

minus-v0.1 is published on Hugging Face: TheGarageDev/Minus-v0.1.

It's a fine-tune of LiquidAI's LFM2.5-VL-450M trained on frames captured from real TV streams and compiled into fused-layer models for the Axera NPU. Inference is prefill-only: the yes/no answer is read straight from the logits without generating any tokens, so latency is deterministic.

The same model also classifies screen state (playing / paused / menu / dialog / screensaver) for autonomous mode.

What ships where

The two models are distributed differently, which trips people up when setting up a new board:

OCR needs three files per generation, all present in the repo: a detection model that finds text regions, a recognition model that reads each region, and the character dictionary the output is decoded through. Each generation has its own dictionary, and the two are not interchangeable. MINUS_OCR_MODEL_VERSION picks one: v6 (the default) or v3. The loader keeps each model paired with its own dictionary and thresholds, so they can't be mixed up. v6 was chosen on latency: 183ms p50 and 274ms p90 in production, and a tighter tail that keeps text-heavy ad frames under the hard timeout. A rotated-text classifier is also included, but Minus doesn't load it, since TV overlay text is never upside down. models/paddleocr/README.md has the details and checksums.

Features

• Real-time ad blocking via OCR + VLM + ASR triangulation. The decision engine handles the ugly cases: flicker between ads, paused screens that look like ads, black transition frames, frozen streams.
• Reads an ad's own countdown ("Skip in 12", "Ad 0:15") and counts it down to know how much of the ad is left. It's an extra signal on top of the detectors, never a trigger by itself. It lets go if the countdown freezes or the audio goes silent, which is what a paused video looks like.
• Ads get replaced, not just blacked out. Choose Spanish vocabulary cards (750+ entries), trivia facts, or a photo screensaver of your own pictures.
• 4K@60fps passthrough with a zero-copy VPU/RGA pipeline in a patched ustreamer, around 5% CPU.
• Audio mutes the instant a block starts, with watchdogs that recover the pipeline if anything wedges, including re-initialising the HDMI output when the TV comes back so sound isn't left silent.
• Thermal-adaptive: if the SoC holds at 83 °C, Minus caps the display at a steady 30fps and makes blocking stickier until it cools below 75 °C, rather than letting the frame rate collapse under throttling.
• Web UI with the live feed, pause controls, detection history, screenshot review, and settings, usable from any device on your network.
• Remote control integration for Fire TV (ADB), Roku (ECP), and Google TV (ADB), including pressing "Skip Ad" for you.
• Autonomous mode keeps YouTube playing unattended to collect training data, midnight to 9am by default, using the VLM to navigate. It stands down the moment the TV is turned on so it never fights you for the remote, and if the streaming stick has put itself to sleep it presses Home to wake it. A music-video mode steers toward music, which carries far more ads per hour.
• Odds and ends: IR blaster for HDMI switches, WS2812B status LED strip, WiFi captive portal for first-time setup, HDCP 1.4 capture support.

Web UI

Desktop	Mobile

The web UI is served by the device itself (Flask). Live feed, block/pause controls, per-detection history, a swipe-based screenshot review flow for cleaning up training data, device remotes, and every setting. A status row shows OCR, VLM and ASR state alongside CPU, memory, temperature, disk and HDMI signal, and turns amber or red as things get tight. No app to install.

Hardware

Roughly $350-$450 in parts. Full bill of materials, part links, and sizing notes: docs/HARDWARE.md.

Operating system: Debian 12 (bookworm) on Radxa's BSP 6.1 kernel, which is what their official ROCK 5B/5B+ images ship. This is not interchangeable with a mainline kernel: the HDMI receiver (rk_hdmirx), the Rockchip MPP encoder, RGA, and the RKNN NPU runtime all live in Rockchip's 6.1 tree. On a mainline kernel the board boots fine and /dev/video0 simply never appears. Either the KDE or the CLI image works; there is no display server or desktop environment involved at runtime, since Minus talks straight to DRM/KMS and the hardware encoders.

Getting started

git clone https://github.com/garagehq/Minus-streaming-stick.git /home/radxa/Minus
cd /home/radxa/Minus

# Install system + Python dependencies (GStreamer, fonts, rknnlite, axengine, ...)
# then build the patched ustreamer:
git clone https://github.com/garagehq/ustreamer.git /home/radxa/ustreamer-garagehq
cd /home/radxa/ustreamer-garagehq && make WITH_MPP=1
cp ustreamer /home/radxa/ustreamer-patched

# Install as a service that starts on boot. This also downloads the vision
# model (~740 MB from Hugging Face; the OCR models already ship in this repo):
cd /home/radxa/Minus && sudo ./install.sh

# ...or run directly (fetch the model first if install.sh hasn't):
sudo python3 tools/minus_update.py --install-model
sudo python3 minus.py

Staying up to date

Settings → Minus Updates in the web UI shows whether this box is current and updates it with one button:

• Minus — on a published release, compared with the latest GitHub release; running from source, compared with the latest commit on your branch (normally main).
• ustreamer — the /home/radxa/ustreamer-garagehq checkout against its branch; rebuilt when it changes.
• Vision model — the files in /home/radxa/axera_models/ against the model the code asks for on Hugging Face (models/vlm_model.json). A new model (for example Minus v0.2) arrives the same way: after the code update, the new model is downloaded, checked and swapped in.

Update now pulls what's new (fast-forward only — it never overwrites local changes; a branch with local commits or no upstream is reported but left alone), rebuilds ustreamer if needed, downloads the model if needed, and restarts Minus, about a minute without picture. Minus has to come back up within four minutes and stay up (30 seconds on the same process, so a crash loop doesn't pass), and if the vision model was loaded before the update it has to load again; otherwise the code, ustreamer and model are all rolled back and it restarts on the previous version. Only one update can run at a time, and an update that was cut off (power cut) shows as interrupted instead of blocking the button. The previous model is kept next to the new one as <model dir>.prev. A check runs five minutes after startup and at most hourly after that while the page is open; nothing updates without the button. From a shell: sudo python3 tools/minus_update.py does the same thing.

Releases are cut by hand with tools/release.sh — see docs/RELEASING.md. A box on a release is only ever moved to a newer release; a box running from source follows its branch.

Automatic security updates

install.sh installs Debian's unattended-upgrades, and Minus turns it on by default (Settings → System Updates in the web UI toggles it, or set "unattended_upgrades": false in ~/.minus_system_settings.json). Only bookworm-security fixes are applied, it never reboots by itself, and the packages the video path depends on (kernel, u-boot, Rockchip MPP/RGA, GStreamer, Mesa, RKNN, Tailscale) are blacklisted so a routine run can't swap a driver the pipeline was validated against — update those deliberately with apt when you choose to. Policy lives in /etc/apt/apt.conf.d/52minus-unattended-upgrades (written by the service); history is in /var/log/unattended-upgrades/. If the web UI says the package is missing: sudo apt-get install unattended-upgrades.

The full dependency list and deployment walkthrough are in docs/DEPLOYMENT.md. Model paths, the OCR generation and detection thresholds are set with environment variables (MINUS_VLM_MODEL_DIR, MINUS_OCR_MODEL_DIR, MINUS_OCR_MODEL_VERSION, etc.); CLAUDE.md documents all of them.

Minus auto-detects the connected HDMI output, resolution, DRM plane, and audio device at startup, and works with both 4K and 1080p displays.

Documentation

Related projects

• Minus-chrome-extension: the same idea for your browser, as a Chrome extension.
• garagehq/ustreamer: our ustreamer fork with RK3588 MPP hardware encoding, NV12/NV24/BGR24 capture, and the 60fps blocking-overlay compositor.
• TheGarageDev/Minus-v0.1: the model, on Hugging Face.

Support

Minus is free, open-source, and runs entirely on your own hardware. No ads, no tracking, no server bills passed on to you. If it has saved you from a few unskippable ad breaks, you can buy me a coffee ☕:

buymeacoffee.com/cyrilengmann

License

• Code: GPL-3.0
• Documentation: CC BY-SA 4.0
• Hardware designs: CERN-OHL-S-2.0