Metadata-Version: 2.4
Name: rtspkit
Version: 1.0.0
Summary: RTSPKit is a powerful vulnerable CCTV & WebCam finder, stream validator, and exposer.
Home-page: https://github.com/babaralijamali/rtspkit
Author: Babar Ali Jamali
Author-email: Babar Ali Jamali <babar994@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/babaralijamali/rtspkit
Project-URL: Repository, https://github.com/babaralijamali/rtspkit
Keywords: rtsp,camera,ip-camera,scanner,opencv,stream-viewer,bruteforce,pip-grid
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Multimedia :: Video :: Display
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: colorama>=0.4.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# RTSP Kit (`rtspkit`)

[![PyPI Version](https://img.shields.io/pypi/v/rtspkit.svg)](https://pypi.org/project/rtspkit/)
[![Python Versions](https://img.shields.io/pypi/pyversions/rtspkit.svg)](https://pypi.org/project/rtspkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**RTSPKit is a powerful vulnerable CCTV & WebCam finder, stream validator, and exposer.** It is a high-performance network scanner designed to discover, validate, audit credentials, render multi-camera video feeds, and record live RTSP video streams across IP networks.

---

## Key Features

- **Parallel Port & Stream Validation**: High-concurrency network socket scan and RTSP stream verification.
- **RTSP Subpath Probing**: Automatic route scanning for popular IP camera routes (`/h264`, `/live/ch0`, `/stream1`, `/onvif1`, etc.).
- **Credential Brute-Forcing**: Custom credential pair testing and dictionary attack modes for locked camera streams.
- **Non-Blocking Multi-Camera Grid View**: Real-time Picture-in-Picture (PiP) layout renderer powered by background frame readers.
- **Stream Recording Mode**: Timed or manual on-demand recording of live RTSP streams to `.mp4` video files.
- **VLC Integration**: Launch streams directly inside external VLC Media Player.
- **Metadata Extraction & Export**: Automatically logs video resolution and FPS metadata to JSON, CSV, or TXT formats.
- **CLI & Python API**: Fully operational as both a command-line tool (`rtspkit`) and a Python library module (`import rtspkit`).

---

## Installation

Install `rtspkit` directly from PyPI using `pip`:

```bash
pip install rtspkit
```

---

## Quickstart & Usage

### 1. Command Line Interface (CLI)

#### Interactive Mode (Wizard)
Run `rtspkit` without positional parameters to open the step-by-step interactive setup wizard:
```bash
rtspkit
```

#### Basic Subnet Scan & Multi-Camera Grid View
Scan a `/24` subnet and launch a 3-column PiP video grid:
```bash
rtspkit 192.168.1.0/24
```

#### Path Probing & Dictionary Brute-Force
Probe common RTSP paths and execute credential brute-forcing:
```bash
rtspkit 192.168.1.0/24 --probe-paths -b -U usernames.txt -P passwords.txt -o results.json
```

#### Single Camera Inspector Mode
Interactive stream reader (`n` = next, `p` = previous, `s` = screenshot, `r` = record, `q` = quit):
```bash
rtspkit 192.168.1.0/24 --mode single
```

#### Record Live Streams
Record active streams for 30 seconds:
```bash
rtspkit 192.168.1.50 --mode record --rec-duration 30
```

---

### 2. Programmatic Python API

You can also import and use `rtspkit` inside your own Python projects:

```python
from rtspkit import RTSPScanner, GridRenderer, SingleStreamViewer

# Initialize scanner
scanner = RTSPScanner(port=554, timeout=3.0, threads=50)

# Scan target IP network or host list
cameras = scanner.run_scan(targets=["192.168.1.100"], paths=["", "/live/ch0"])

for cam in cameras:
    if cam.working:
        print(f"Found camera at {cam.ip}: {cam.url} ({cam.width}x{cam.height})")

# Launch PiP Grid view if cameras found
working = [c for c in cameras if c.working]
if working:
    grid = GridRenderer(working, cols=3)
    grid.start_preview()
```

---

## Command Line Flags Reference

| Flag | Long Flag | Description | Default |
| --- | --- | --- | --- |
| `target` | Positional | Target IP, CIDR subnet (`192.168.1.0/24`), range (`192.168.1.1-50`), or target file | Interactive |
| `-f` | `--targets-file` | File containing batch list of target IPs/subnets | `None` |
| `-p` | `--port` | Target RTSP TCP port | `554` |
| `-t` | `--threads` | Number of concurrent worker threads | `50` |
| `--timeout` | `--timeout` | Network socket and stream timeout (seconds) | `3.0` |
| `-c` | `--credentials` | Single `user:pass` authentication pair | `None` |
| `-b` | `--brute` | Enable dictionary brute-forcing for LOCKED streams | `False` |
| `-U` | `--user-file` | Path to custom usernames list | Built-in list |
| `-P` | `--pass-file` | Path to custom passwords list | Built-in list |
| `--probe-paths` | `--probe-paths` | Probe popular RTSP camera paths (`/h264`, `/live/ch0`, etc.) | `False` |
| `-o` | `--output` | Save results to file (`.json`, `.csv`, `.txt`) | `None` |
| `--mode` | `--mode` | Execution mode (`grid`, `single`, `record`, `scan-only`) | `grid` |
| `--grid-cols` | `--grid-cols` | Number of columns in PiP grid preview | `3` |
| `--rec-duration`| `--rec-duration`| Duration in seconds for stream recording | `30` |

---

## Step-by-Step PyPI Publishing Guide

Follow these steps to publish `rtspkit` to the Python Package Index (PyPI):

### 1. Prerequisites
Ensure you have `build` and `twine` installed:
```bash
pip install --upgrade build twine
```

### 2. Create a PyPI Account & API Token
1. Register an account on [PyPI (pypi.org)](https://pypi.org/account/register/).
2. Go to **Account Settings** -> **API Tokens** and generate a new API token with `Entire account` or `Project` scope.
3. Copy your generated token (starts with `pypi-`).

### 3. Build Source & Wheel Packages
Navigate into the `rtspkit` root directory containing `pyproject.toml` and run:
```bash
python -m build
```
*(Or legacy build command: `python setup.py sdist bdist_wheel`)*

This creates distribution files in the `dist/` directory:
- `dist/rtspkit-1.0.0-py3-none-any.whl`
- `dist/rtspkit-1.0.0.tar.gz`

### 4. Verify Package Build Integrity
Run `twine check` to ensure your README, metadata, and license format correctly:
```bash
twine check dist/*
```

### 5. Test Upload to TestPyPI (Optional but Recommended)
Publish to TestPyPI first to verify package rendering:
```bash
twine upload --repository testpypi dist/*
```
- **Username**: `__token__`
- **Password**: `pypi-your-testpypi-api-token`

Test installation from TestPyPI:
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple rtspkit
```

### 6. Publish Package to Official PyPI
Publish your package live on PyPI:
```bash
twine upload dist/*
```
- **Username**: `__token__`
- **Password**: `pypi-your-live-pypi-api-token`

Once complete, your package will be live on PyPI and installable globally via:
```bash
pip install rtspkit
```

---

## License

This project is licensed under the [MIT License](LICENSE).
