# yoloscr: Live Screen Object Detection

![PyPI Version](https://img.shields.io/pypi/v/yoloscr.svg)
![License](https://img.shields.io/pypi/l/yoloscr.svg)

![Scr](scr.png)

A simple and powerful command-line tool to run any Ultralytics YOLO model for live object detection directly on a region of your screen.

It's perfect for developers, researchers, and hobbyists who want to quickly apply object detection to videos, games, or any application window without complex code.

## Features

- **Live Detection**: Run YOLO models in real-time on your screen.
- **Customizable Region**: Specify any part of your screen for detection.
- **Model Agnostic**: Works with any `*.pt` model file from the Ultralytics ecosystem.
- **Highly Configurable**: Control confidence, FPS, window visibility, and logging via simple command-line flags.
- **Cross-Platform**: Works on macOS, Windows, and Linux (with OS-specific setup).

## Installation

You can install `yoloscr` directly from PyPI:

```bash
pip install yoloscr
```

## Crucial Operating System Setup

Because this tool needs to see your screen, you may need to grant permissions first.

### macOS (Required)

![Empty screen](empty.png)

On macOS, you **must** grant screen recording permissions to your terminal application.

![Access](access.png)

1.  Open **System Settings**.
2.  Go to **Privacy & Security** > **Screen Recording**.
3.  Find your terminal application (e.g., `Terminal`, `iTerm2`, `Visual Studio Code`) in the list.
4.  **Enable the switch** next to it.
5.  You will be prompted to **"Quit & Reopen"** the application. This is necessary for the changes to take effect.

### Windows & Linux

On most Windows and Linux systems, no special permissions are required. It should work out of the box.

## Usage

The tool is run from your terminal. The basic command requires a YOLO model file.

```bash
# Use a pre-trained model downloaded automatically
yoloscr --model yolov8n.pt

# Use your own fine-tuned model
yoloscr --model "runs/detect/train/weights/best.pt"
```

### Command-Line Arguments

You can customize the detection with the following arguments:

| Argument        | Default        | Description                                             |
| :-------------- | :------------- | :------------------------------------------------------ |
| `--model`       | `yolov8n.pt`   | Path to the YOLO `.pt` model file.                      |
| `--region`      | `0 0 960 1080` | Screen region to capture as `left top width height`.    |
| `--conf`        | `0.30`         | Confidence threshold for detection (e.g., 0.5 for 50%). |
| `--fps`         | `10`           | Frame rate to limit the capture.                        |
| `--hide-window` | (not set)      | Flag to disable the live preview window.                |
| `--verbose`     | (not set)      | Flag to print detected object logs to the terminal.     |
| `--title`       | `yoloscr...`   | Custom title for the preview window.                    |

### Practical Examples

**1. Detect on a 400x400 area at the top-left of the screen:**

```bash
yoloscr --model yolov8n.pt --region 0 0 400 400
```

**2. Use your custom model with high confidence and see logs:**
_Drag the preview window out of the capture area to avoid the "mirror" effect._

```bash
yoloscr --model path/to/my/best.pt --conf 0.75 --verbose
```

**3. Run headless (no preview) and just log detections in the terminal:**
_This is useful for running automated scripts._

```bash
yoloscr --model yolov8n.pt --hide-window --verbose
```

## License

This project is distributed under the MIT License. See the `LICENSE` file for more information.
