Metadata-Version: 2.4
Name: autoskipYT
Version: 0.1.0
Summary: Visual desktop automation that watches the screen for a configured button and clicks it.
Project-URL: Homepage, https://github.com/your-org/autoskipyt
Project-URL: Repository, https://github.com/your-org/autoskipyt
Project-URL: Changelog, https://github.com/your-org/autoskipyt/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/your-org/autoskipyt/issues
Author: AutoSkipYT contributors
License: MIT
License-File: LICENSE
Keywords: automation,desktop,opencv,pyautogui,screen,template-matching
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mss>=9.0
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python>=4.8
Requires-Dist: platformdirs>=3.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](https://pypi.org/project/mss/).
- Matches one or more template images with OpenCV's `cv2.matchTemplate`.
- Clicks the center of a detected match with [`pyautogui`](https://pypi.org/project/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+**.

```bash
pip install autoskipYT
```

On Linux, OpenCV needs a couple of system libraries:

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

## Quick start

### Command line

```bash
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

```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`](https://pypi.org/project/platformdirs/). Find the exact path
(and your template directory) by running `autoskipyt templates` or
`autoskipyt calibrate`.

```toml
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:

```bash
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

```bash
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](LICENSE).
