AutoSkipYT

AutoSkipYT is visual desktop automation. It watches a region of your screen for a button you configure (using OpenCV template matching), clicks it when it appears, and then returns your mouse cursor to where it was — unless you moved the cursor yourself in the meantime.

The engine is generic: it can detect and click any configured on-screen target. The first use case is a "Skip Ad"-style button, but nothing in the code is specific to any particular website or application.

⚠️ You are responsible for complying with the terms of service of any software or website you interact with. AutoSkipYT is a general-purpose visual automation tool. It does not bypass, defeat, or circumvent any protection mechanism, and it ships with no copyrighted logos or screenshots.

What it does

• Captures a configurable screen region quickly with mss.
• Matches one or more template images with OpenCV's cv2.matchTemplate.
• Clicks the center of a detected match with pyautogui.
• Restores the cursor to its previous position — only when it is safe to do so.
• Applies a per-target cooldown so it does not click repeatedly.

Installation

Requires Python 3.11+.

pip install autoskipYT

On Linux, OpenCV needs a couple of system libraries:

sudo apt-get install -y libgl1 libglib2.0-0

Quick start

Command line

autoskipyt run        # start the detection loop (Ctrl+C to stop)
autoskipyt test       # capture one frame and report confidence per target
autoskipyt calibrate  # pick a display, scan region, and capture a template
autoskipyt templates  # list installed templates
autoskipyt --version

Python

from autoskipyt import AutoSkipper, Target

target = Target(
    name="skip-ad",
    templates=["skip-ad-dark.png", "skip-ad-light.png"],
    confidence=0.86,
    cooldown_seconds=3.0,
)

skipper = AutoSkipper(
    targets=[target],
    interval_seconds=0.4,
    restore_cursor=True,
)

skipper.run()

With no arguments, AutoSkipper() uses the built-in default configuration.

Configuration

Configuration is stored as TOML in a platform-appropriate directory chosen by platformdirs. Find the exact path (and your template directory) by running autoskipyt templates or autoskipyt calibrate.

interval_seconds = 0.4
confidence = 0.86
restore_cursor = true
grayscale = true
cooldown_seconds = 3.0
display = 1

[region]
left_percent = 0.55
top_percent = 0.45
width_percent = 0.45
height_percent = 0.55

[[targets]]
name = "skip-ad"
templates = ["skip-ad-dark.png", "skip-ad-light.png"]
confidence = 0.86
cooldown_seconds = 3.0

• display is a 1-based index (1 is your first monitor).
• The [region] percentages are fractions of the selected display. The default scans the lower-right portion of the screen.
• Scan only the smallest region you need — smaller regions are faster and use less CPU.

Templates

A template is a tightly cropped PNG of the button you want to detect.

1. Take a screenshot of the button.
2. Crop it to just the button (minimal surrounding background).
3. Save it as a PNG.
4. Put it in your user template directory (shown by autoskipyt templates) or capture one interactively with autoskipyt calibrate.

Tips:

• Provide several templates per target (e.g. dark and light themes).
• Templates may be different sizes; each is matched independently.
• Capture templates at your own resolution and scaling for best results.

How confidence thresholds work

Each match produces a confidence score between 0.0 and 1.0 (from OpenCV's normalized correlation). AutoSkipYT clicks only when the best match for a target meets or exceeds that target's confidence threshold.

• Higher threshold (e.g. 0.92) → fewer false positives, more missed buttons.
• Lower threshold (e.g. 0.80) → catches more variations, risks false clicks.

Use autoskipyt test to see the actual scores for your templates and tune the threshold accordingly.

PyAutoGUI fail-safe

PyAutoGUI's fail-safe is enabled and never disabled. If automation ever behaves unexpectedly, slam your mouse cursor into a corner of the screen to immediately abort with a FailSafeException. This is your emergency stop.

Cursor restoration

AutoSkipYT records the cursor position before clicking, performs the click, then checks where the cursor ended up. It restores the original position only if the cursor is still at (or very near) the click location — meaning you did not touch the mouse. If you moved the cursor during the click, AutoSkipYT leaves it where you put it. Movements are effectively instantaneous.

Linux display-server limitations (important)

AutoSkipYT relies on global screen capture and global mouse control.

• X11: fully supported.
• Wayland: not supported. For security, Wayland restricts applications from capturing arbitrary screen contents and synthesizing global input, so mss and pyautogui cannot see the whole screen or move the global cursor.

To use AutoSkipYT on Linux, run an X11 session (often selectable as "Xorg" or "X11" on your login screen). You can check your session type with:

echo $XDG_SESSION_TYPE   # "x11" works; "wayland" does not

On Windows, no special configuration is required.

Troubleshooting

• "No displays were detected" / capture fails on Linux: you are likely on Wayland or have no DISPLAY. Switch to an X11 session.
• Nothing gets clicked: run autoskipyt test. If confidence is below your threshold, re-crop the template, capture it at your own resolution, or lower the threshold.
• It clicks the wrong place: your template probably includes too much background, or the scan region excludes the button. Re-crop and re-check the region with autoskipyt calibrate.
• libGL.so.1 import error on Linux: install libgl1 and libglib2.0-0.
• High CPU usage: increase interval_seconds and/or shrink [region].
• The cursor keeps snapping back: set restore_cursor = false (or pass --no-restore) if you prefer to keep the cursor at the clicked location.

Development

git clone https://github.com/your-org/autoskipyt
cd autoskipyt
python -m pip install -e ".[dev]"

ruff check .
ruff format --check .
mypy
pytest

Unit tests do not require a real display: screen capture and mouse operations are mocked, and template-matching tests use synthetic images.

License

MIT.