rtspkit 1.0.0__py3-none-any.whl

rtspkit/__init__.py

@@ -0,0 +1,35 @@
+"""
+RTSP Kit (rtspkit)
+------------------
+Enhanced RTSP Scanner, Stream Validator, Credential Brute-Forcer, and Multi-Camera Viewer.
+"""
+
+from .rtspkit import (
+    CameraResult,
+    RTSPScanner,
+    AsyncFrameReader,
+    GridRenderer,
+    SingleStreamViewer,
+    record_stream,
+    main,
+    DEFAULT_USERNAMES,
+    DEFAULT_PASSWORDS,
+    DEFAULT_RTSP_PATHS,
+)
+
+__version__ = "1.0.0"
+__author__ = "Developer"
+
+__all__ = [
+    "CameraResult",
+    "RTSPScanner",
+    "AsyncFrameReader",
+    "GridRenderer",
+    "SingleStreamViewer",
+    "record_stream",
+    "main",
+    "DEFAULT_USERNAMES",
+    "DEFAULT_PASSWORDS",
+    "DEFAULT_RTSP_PATHS",
+    "__version__",
+]

rtspkit/__main__.py

@@ -0,0 +1,8 @@
+"""
+Main entry point for executing rtspkit as a module (python -m rtspkit).
+"""
+import sys
+from .rtspkit import main
+
+if __name__ == "__main__":
+    sys.exit(main())

rtspkit/rtspkit.py

@@ -0,0 +1,998 @@
+#!/usr/bin/env python3
+"""
+RTSP Kit (rtspkit) - Enhanced RTSP Scanner, Validator, Multi-Camera Viewer, and Recorder
+"""
+
+import argparse
+import csv
+import ipaddress
+import json
+import os
+import queue
+import socket
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from typing import List, Optional, Tuple
+
+# --- Suppress C-level FFMPEG / OpenCV log noise process-wide ---
+os.environ["OPENCV_FFMPEG_LOGLEVEL"] = "-8"
+os.environ["OPENCV_LOG_LEVEL"] = "OFF"
+os.environ["FFMPEG_LOGLEVEL"] = "quiet"
+
+# Thread-safe console printing lock
+print_lock = threading.Lock()
+
+def safe_print(*args, **kwargs):
+    with print_lock:
+        print(*args, **kwargs, flush=True)
+
+# --- Auto Dependency Installer ---
+REQUIRED_PACKAGES = {
+    "cv2": "opencv-python",
+    "numpy": "numpy",
+    "colorama": "colorama",
+}
+
+def ensure_dependencies():
+    """Checks for required 3rd-party dependencies and auto-installs any missing packages."""
+    missing = []
+    for module_name, package_name in REQUIRED_PACKAGES.items():
+        try:
+            __import__(module_name)
+        except ImportError:
+            missing.append(package_name)
+
+    if missing:
+        safe_print(f"\n[*] Missing required package(s): {', '.join(missing)}")
+        safe_print("[*] Automatically installing missing dependencies via pip...\n")
+        try:
+            subprocess.check_call([sys.executable, "-m", "pip", "install", *missing])
+            safe_print("[✓] Dependencies successfully installed!\n")
+        except Exception as e:
+            safe_print(f"[!] Auto-installation failed: {e}")
+            safe_print(f"[!] Please manually run: {sys.executable} -m pip install {' '.join(missing)}")
+            sys.exit(1)
+
+ensure_dependencies()
+
+# Import 3rd-party modules after ensuring installation
+import cv2
+try:
+    cv2.setLogLevel(0)
+except AttributeError:
+    pass
+
+import numpy as np
+import colorama
+from colorama import Fore, Style
+
+colorama.init(autoreset=True)
+
+class Color:
+    """Terminal color constants for stylized output."""
+    SUCCESS = Fore.GREEN + Style.BRIGHT
+    INFO = Fore.CYAN + Style.BRIGHT
+    WARN = Fore.YELLOW + Style.BRIGHT
+    ERROR = Fore.RED + Style.BRIGHT
+    MAGENTA = Fore.MAGENTA + Style.BRIGHT
+    BLUE = Fore.BLUE + Style.BRIGHT
+    HEADER = Fore.MAGENTA + Style.BRIGHT
+    DIM = Style.DIM
+    RESET = Style.RESET_ALL
+
+# Common RTSP paths used by IP camera manufacturers (Hikvision, Dahua, Axis, Reolink, etc.)
+DEFAULT_RTSP_PATHS = [
+    "",
+    "/",
+    "/h264",
+    "/live/ch0",
+    "/stream1",
+    "/onvif1",
+    "/ch0",
+    "/11",
+    "/12",
+    "/h264Preview_01_main",
+]
+
+DEFAULT_USERNAMES = ["admin", "user", "root", "service", "support", "operator", "guest"]
+DEFAULT_PASSWORDS = ["admin", "12345", "123456", "pass", "password", "1234", "0000", "", "admin123", "camera", "888888", "666666"]
+
+@dataclass
+class CameraInfo:
+    ip: str
+    port: int
+    url: str
+    path: str
+    working: bool
+    auth_status: str  # "OPEN", "LOCKED", "UNLOCKED"
+    width: int = 0
+    height: int = 0
+    fps: float = 0.0
+    error: Optional[str] = None
+
+# Alias for backwards compatibility / public API
+CameraResult = CameraInfo
+
+def load_wordlist(file_path: Optional[str], default_list: List[str]) -> List[str]:
+    """Loads wordlist from a file path if provided, otherwise returns default list."""
+    if file_path and os.path.isfile(file_path):
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+                lines = [line.strip() for line in f if line.strip() and not line.strip().startswith("#")]
+                return lines if lines else default_list
+        except Exception as e:
+            print(f"{Color.WARN}[!] Failed to read wordlist file {file_path}: {e}. Using defaults.{Color.RESET}")
+    return default_list
+
+class AsyncStreamReader:
+    """Non-blocking RTSP stream reader running in a dedicated thread to prevent UI stutter."""
+    def __init__(self, camera: CameraInfo, target_size: Tuple[int, int] = (320, 240)):
+        self.camera = camera
+        self.target_size = target_size
+        self.running = False
+        self.thread: Optional[threading.Thread] = None
+        self.frame_queue: queue.Queue = queue.Queue(maxsize=2)
+        self.last_frame: Optional[np.ndarray] = None
+        self.connected = False
+
+    def start(self):
+        self.running = True
+        self.thread = threading.Thread(target=self._update_loop, daemon=True)
+        self.thread.start()
+
+    def _update_loop(self):
+        cap = cv2.VideoCapture(self.camera.url, cv2.CAP_FFMPEG)
+        if not cap.isOpened():
+            self.connected = False
+            return
+
+        self.connected = True
+        while self.running:
+            ret, frame = cap.read()
+            if not ret or frame is None:
+                self.connected = False
+                time.sleep(0.1)
+                continue
+
+            self.connected = True
+            resized_frame = cv2.resize(frame, self.target_size)
+            
+            if self.frame_queue.full():
+                try:
+                    self.frame_queue.get_nowait()
+                except queue.Empty:
+                    pass
+            self.frame_queue.put(resized_frame)
+
+        cap.release()
+
+    def get_frame(self) -> np.ndarray:
+        w, h = self.target_size
+        try:
+            self.last_frame = self.frame_queue.get_nowait()
+        except queue.Empty:
+            pass
+
+        if self.last_frame is not None and self.connected:
+            frame = self.last_frame.copy()
+            cv2.putText(frame, self.camera.ip, (10, h - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)
+            return frame
+        else:
+            frame = np.zeros((h, w, 3), dtype=np.uint8)
+            cv2.putText(frame, "NO SIGNAL", (w // 4, h // 2), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 255), 2)
+            cv2.putText(frame, self.camera.ip, (10, h - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
+            return frame
+
+    def stop(self):
+        self.running = False
+        if self.thread and self.thread.is_alive():
+            self.thread.join(timeout=1.0)
+
+# Alias for API export
+AsyncFrameReader = AsyncStreamReader
+
+@contextmanager
+def suppress_c_stderr():
+    """Cross-platform suppressor for C/C++ native DLL stderr logs (FFMPEG 401 Unauthorized messages)."""
+    old_stderr_fd = None
+    null_fd = None
+    old_std_handle = None
+    kernel32 = None
+
+    try:
+        null_fd = os.open(os.devnull, os.O_WRONLY)
+        old_stderr_fd = os.dup(2)
+        os.dup2(null_fd, 2)
+
+        if sys.platform == "win32":
+            import ctypes
+            import msvcrt
+            kernel32 = ctypes.windll.kernel32
+            STD_ERROR_HANDLE = -12
+            old_std_handle = kernel32.GetStdHandle(STD_ERROR_HANDLE)
+            devnull_handle = msvcrt.get_osfhandle(null_fd)
+            kernel32.SetStdHandle(STD_ERROR_HANDLE, devnull_handle)
+
+        yield
+    except Exception:
+        yield
+    finally:
+        if sys.platform == "win32" and kernel32 and old_std_handle is not None:
+            kernel32.SetStdHandle(-12, old_std_handle)
+
+        if old_stderr_fd is not None:
+            try:
+                os.dup2(old_stderr_fd, 2)
+                os.close(old_stderr_fd)
+            except Exception:
+                pass
+        if null_fd is not None:
+            try:
+                os.close(null_fd)
+            except Exception:
+                pass
+
+class RTSPScanner:
+    """Parallel scanner for detecting open ports, validating RTSP streams, and brute-forcing credentials."""
+    def __init__(
+        self,
+        port: int = 554,
+        timeout: float = 3.0,
+        threads: int = 50,
+        credentials: Optional[str] = None,
+        user_list: Optional[List[str]] = None,
+        pass_list: Optional[List[str]] = None,
+        enable_brute: bool = False
+    ):
+        self.port = port
+        self.timeout = timeout
+        self.threads = threads
+        self.credentials = credentials
+        self.user_list = user_list or DEFAULT_USERNAMES
+        self.pass_list = pass_list or DEFAULT_PASSWORDS
+        self.enable_brute = enable_brute
+
+    def is_port_open(self, ip: str) -> bool:
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                sock.settimeout(self.timeout)
+                return sock.connect_ex((ip, self.port)) == 0
+        except Exception:
+            return False
+
+    def _test_single_url(self, url: str) -> Tuple[bool, int, int, float, Optional[str]]:
+        """Helper to test connecting to an RTSP URL and reading a single frame."""
+        result = {"success": False, "width": 0, "height": 0, "fps": 0.0, "error": None}
+
+        def try_connect():
+            try:
+                with suppress_c_stderr():
+                    cap = cv2.VideoCapture(url, cv2.CAP_FFMPEG)
+                    if not cap.isOpened():
+                        result["error"] = "Connection failed / Auth required"
+                        return
+
+                    start_time = time.time()
+                    while time.time() - start_time < self.timeout:
+                        ret, frame = cap.read()
+                        if ret and frame is not None:
+                            result["success"] = True
+                            result["width"] = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+                            result["height"] = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+                            result["fps"] = float(cap.get(cv2.CAP_PROP_FPS))
+                            break
+                    cap.release()
+            except Exception as e:
+                result["error"] = str(e)
+
+        thread = threading.Thread(target=try_connect, daemon=True)
+        thread.start()
+        thread.join(self.timeout + 1.0)
+
+        return result["success"], result["width"], result["height"], result["fps"], result["error"]
+
+    def probe_rtsp_stream(self, ip: str, paths: List[str]) -> CameraInfo:
+        """Test RTSP URL paths: checks OPEN unauthenticated first, then attempts auth/brute force."""
+        for path in paths:
+            clean_path = path if path.startswith("/") or not path else f"/{path}"
+            url_open = f"rtsp://{ip}:{self.port}{clean_path}"
+            
+            success, w, h, fps, err = self._test_single_url(url_open)
+            if success and w > 0 and h > 0:
+                return CameraInfo(
+                    ip=ip,
+                    port=self.port,
+                    url=url_open,
+                    path=clean_path,
+                    working=True,
+                    auth_status="OPEN",
+                    width=w,
+                    height=h,
+                    fps=fps
+                )
+
+        if self.credentials:
+            auth_prefix = f"{self.credentials}@"
+            for path in paths:
+                clean_path = path if path.startswith("/") or not path else f"/{path}"
+                url_auth = f"rtsp://{auth_prefix}{ip}:{self.port}{clean_path}"
+                success, w, h, fps, err = self._test_single_url(url_auth)
+                if success:
+                    return CameraInfo(
+                        ip=ip,
+                        port=self.port,
+                        url=url_auth,
+                        path=clean_path,
+                        working=True,
+                        auth_status=f"UNLOCKED ({self.credentials})",
+                        width=w,
+                        height=h,
+                        fps=fps
+                    )
+
+        if self.enable_brute:
+            print(f"{Color.INFO}[*] Running credential brute-force on {ip}...{Color.RESET}")
+            for u in self.user_list:
+                for p in self.pass_list:
+                    cred_pair = f"{u}:{p}"
+                    auth_prefix = f"{cred_pair}@"
+                    for path in paths[:2]:
+                        clean_path = path if path.startswith("/") or not path else f"/{path}"
+                        url_brute = f"rtsp://{auth_prefix}{ip}:{self.port}{clean_path}"
+                        success, w, h, fps, err = self._test_single_url(url_brute)
+                        if success:
+                            return CameraInfo(
+                                ip=ip,
+                                port=self.port,
+                                url=url_brute,
+                                path=clean_path,
+                                working=True,
+                                auth_status=f"UNLOCKED ({cred_pair})",
+                                width=w,
+                                height=h,
+                                fps=fps
+                            )
+
+        return CameraInfo(
+            ip=ip,
+            port=self.port,
+            url=f"rtsp://{ip}:{self.port}/",
+            path="/",
+            working=False,
+            auth_status="LOCKED",
+            error="Port 554 open but camera stream requires authentication (LOCKED)"
+        )
+
+    def scan_host(self, ip: str, paths: List[str]) -> Tuple[str, bool, Optional[CameraInfo]]:
+        if not self.is_port_open(ip):
+            return ip, False, None
+        
+        safe_print(f"{Color.INFO}[+] Port {self.port} OPEN on {ip} - testing RTSP stream...{Color.RESET}")
+        cam_info = self.probe_rtsp_stream(ip, paths)
+        
+        if cam_info.auth_status == "OPEN":
+            res_str = f" ({cam_info.width}x{cam_info.height})" if cam_info.width else ""
+            safe_print(f"{Color.SUCCESS}[OPEN] {ip}{res_str} -> {cam_info.url}{Color.RESET}")
+        elif cam_info.auth_status.startswith("UNLOCKED"):
+            res_str = f" ({cam_info.width}x{cam_info.height})" if cam_info.width else ""
+            safe_print(f"{Color.INFO}[{cam_info.auth_status}] {ip}{res_str} -> {cam_info.url}{Color.RESET}")
+        else:
+            safe_print(f"{Color.WARN}[LOCKED] {ip} - Port 554 open (Authentication required){Color.RESET}")
+            
+        return ip, True, cam_info
+
+    def parse_targets(self, target_input: str) -> List[str]:
+        """Parses CIDR subnets, IP ranges, comma-separated IPs, or file paths."""
+        targets = []
+        target_input = target_input.strip()
+
+        if os.path.isfile(target_input):
+            with open(target_input, "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#"):
+                        targets.extend(self.parse_targets(line))
+            return targets
+
+        if "," in target_input:
+            for part in target_input.split(","):
+                targets.extend(self.parse_targets(part))
+            return targets
+
+        if "-" in target_input and "/" not in target_input:
+            try:
+                start_ip_str, end_ip_str = target_input.split("-")
+                start_ip = ipaddress.ip_address(start_ip_str.strip())
+                if "." not in end_ip_str:
+                    prefix = ".".join(start_ip_str.split(".")[:3])
+                    end_ip_str = f"{prefix}.{end_ip_str.strip()}"
+                end_ip = ipaddress.ip_address(end_ip_str.strip())
+                
+                curr = int(start_ip)
+                end = int(end_ip)
+                while curr <= end:
+                    targets.append(str(ipaddress.ip_address(curr)))
+                    curr += 1
+                return targets
+            except ValueError:
+                pass
+
+        try:
+            net = ipaddress.ip_network(target_input, strict=False)
+            if net.num_addresses == 1:
+                targets.append(str(net.network_address))
+            else:
+                targets.extend([str(ip) for ip in net.hosts()])
+        except ValueError:
+            print(f"{Color.WARN}[!] Warning: Unable to parse target '{target_input}'{Color.RESET}")
+
+        return targets
+
+    def run_scan(self, target_input: str, paths: Optional[List[str]] = None) -> List[CameraInfo]:
+        if paths is None:
+            paths = DEFAULT_RTSP_PATHS
+        ip_list = self.parse_targets(target_input)
+        if not ip_list:
+            print(f"{Color.ERROR}[!] No valid target IP addresses to scan.{Color.RESET}")
+            return []
+
+        print(f"\n{Color.INFO}[*] Starting RTSP scan on {Color.SUCCESS}{len(ip_list)}{Color.INFO} target host(s) (Port {self.port}, Threads {self.threads})...{Color.RESET}\n")
+
+        all_discovered = []
+        with ThreadPoolExecutor(max_workers=self.threads) as executor:
+            futures = {executor.submit(self.scan_host, ip, paths): ip for ip in ip_list}
+            for future in as_completed(futures):
+                try:
+                    _, port_open, cam_info = future.result()
+                    if port_open and cam_info:
+                        all_discovered.append(cam_info)
+                except Exception:
+                    pass
+
+        return all_discovered
+
+
+class GridRenderer:
+    """Multi-camera Picture-in-Picture grid display with auto-padding and background thread streaming."""
+    def __init__(self, cameras: List[CameraInfo], cols: int = 3, frame_size: Tuple[int, int] = (320, 240)):
+        self.cameras = cameras
+        self.cols = max(1, cols)
+        self.frame_size = frame_size
+
+    def start_preview(self, duration_sec: Optional[int] = None):
+        if not self.cameras:
+            print(f"{Color.WARN}[!] No working cameras available to render.{Color.RESET}")
+            return
+
+        print(f"\n{Color.INFO}[▶] Starting async PiP grid view for {Color.SUCCESS}{len(self.cameras)}{Color.INFO} camera(s)...{Color.RESET}")
+        print(f"{Color.DIM}[i] Press 'q' or 'ESC' to exit preview | Press 's' to save grid screenshot.{Color.RESET}\n")
+
+        readers = [AsyncStreamReader(cam, target_size=self.frame_size) for cam in self.cameras]
+        for reader in readers:
+            reader.start()
+
+        start_time = time.time()
+        cell_w, cell_h = self.frame_size
+
+        try:
+            while True:
+                if duration_sec and (time.time() - start_time > duration_sec):
+                    break
+
+                frames = [reader.get_frame() for reader in readers]
+
+                remainder = len(frames) % self.cols
+                if remainder != 0:
+                    pad_count = self.cols - remainder
+                    for _ in range(pad_count):
+                        empty_cell = np.zeros((cell_h, cell_w, 3), dtype=np.uint8)
+                        cv2.putText(empty_cell, "EMPTY", (cell_w // 3, cell_h // 2), 
+                                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (100, 100, 100), 1)
+                        frames.append(empty_cell)
+
+                rows = []
+                for i in range(0, len(frames), self.cols):
+                    row = np.hstack(frames[i:i + self.cols])
+                    rows.append(row)
+                grid_image = np.vstack(rows)
+
+                window_name = "RTSP Kit - PiP Multi-Camera Grid"
+                cv2.imshow(window_name, grid_image)
+
+                key = cv2.waitKey(30) & 0xFF
+                if key in (ord('q'), ord('Q'), 27):
+                    break
+                if cv2.getWindowProperty(window_name, cv2.WND_PROP_VISIBLE) < 1:
+                    break
+
+                if key == ord('s') or key == ord('S'):
+                    filename = f"rtsp_grid_{int(time.time())}.png"
+                    cv2.imwrite(filename, grid_image)
+                    print(f"{Color.SUCCESS}[✓] Saved grid screenshot to {filename}{Color.RESET}")
+
+        finally:
+            print(f"{Color.INFO}[*] Closing stream readers...{Color.RESET}")
+            for reader in readers:
+                reader.stop()
+            cv2.destroyAllWindows()
+            print(f"{Color.SUCCESS}[✓] Grid preview finished.{Color.RESET}")
+
+
+class SingleStreamViewer:
+    """Interactive single-camera viewer with next/previous camera switching."""
+    def __init__(self, cameras: List[CameraInfo]):
+        self.cameras = cameras
+
+    def start_viewing(self, initial_index: int = 0):
+        if not self.cameras:
+            print(f"{Color.WARN}[!] No cameras available for single view.{Color.RESET}")
+            return
+
+        current_idx = initial_index % len(self.cameras)
+        
+        while True:
+            cam = self.cameras[current_idx]
+            print(f"\n{Color.INFO}[▶] Streaming [{current_idx + 1}/{len(self.cameras)}]: {Color.SUCCESS}{cam.url}{Color.RESET}")
+            print(f"{Color.DIM}[i] Controls: 'n'=Next camera | 'p'=Previous camera | 's'=Screenshot | 'q'=Quit{Color.RESET}\n")
+
+            cap = cv2.VideoCapture(cam.url, cv2.CAP_FFMPEG)
+            if not cap.isOpened():
+                print(f"{Color.ERROR}[!] Failed to connect to RTSP stream: {cam.url}{Color.RESET}")
+                current_idx = (current_idx + 1) % len(self.cameras)
+                time.sleep(1)
+                continue
+
+            switch_action = None
+            recording = False
+            rec_writer = None
+            rec_filename = None
+
+            while True:
+                ret, frame = cap.read()
+                if not ret or frame is None:
+                    print(f"{Color.WARN}[!] Stream interrupted.{Color.RESET}")
+                    break
+
+                if recording and rec_writer:
+                    rec_writer.write(frame)
+
+                display_frame = cv2.resize(frame, (500, 500))
+
+                overlay_text = f"{cam.ip} ({cam.width}x{cam.height})" if cam.width else cam.ip
+                if recording:
+                    cv2.circle(display_frame, (30, 30), 10, (0, 0, 255), -1)
+                    cv2.putText(display_frame, f"REC {overlay_text}", (50, 38), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 255), 2)
+                else:
+                    cv2.putText(display_frame, overlay_text, (20, 40), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2)
+
+                cv2.imshow("RTSP Kit - Single Stream Viewer", display_frame)
+
+                key = cv2.waitKey(1) & 0xFF
+                if key in (ord('q'), ord('Q'), 27):
+                    switch_action = 'quit'
+                    break
+                elif key == ord('n') or key == ord('N'):
+                    switch_action = 'next'
+                    break
+                elif key == ord('p') or key == ord('P'):
+                    switch_action = 'prev'
+                    break
+                elif key == ord('s') or key == ord('S'):
+                    fn = f"rtsp_cam_{cam.ip}_{int(time.time())}.png"
+                    cv2.imwrite(fn, display_frame)
+                    print(f"{Color.SUCCESS}[✓] Saved screenshot: {fn}{Color.RESET}")
+                elif key == ord('r') or key == ord('R'):
+                    if not recording:
+                        rec_filename = f"record_{cam.ip}_{int(time.time())}.mp4"
+                        w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) or 1280
+                        h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) or 720
+                        fps = float(cap.get(cv2.CAP_PROP_FPS)) or 20.0
+                        fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+                        rec_writer = cv2.VideoWriter(rec_filename, fourcc, fps, (w, h))
+                        recording = True
+                        print(f"\n{Color.SUCCESS}[● STARTED RECORDING] Saving stream to {rec_filename}{Color.RESET}")
+                    else:
+                        recording = False
+                        if rec_writer:
+                            rec_writer.release()
+                            rec_writer = None
+                        print(f"\n{Color.SUCCESS}[■ STOPPED RECORDING] Saved to {rec_filename}{Color.RESET}")
+
+            if rec_writer:
+                rec_writer.release()
+            cap.release()
+            cv2.destroyAllWindows()
+
+            if switch_action == 'quit' or switch_action is None:
+                break
+            elif switch_action == 'next':
+                current_idx = (current_idx + 1) % len(self.cameras)
+            elif switch_action == 'prev':
+                current_idx = (current_idx - 1) % len(self.cameras)
+
+
+def record_stream(camera: CameraInfo, duration_sec: Optional[int] = None, output_filename: Optional[str] = None):
+    """Records live RTSP stream to a local MP4 video file."""
+    if not output_filename:
+        output_filename = f"record_{camera.ip}_{int(time.time())}.mp4"
+
+    cap = cv2.VideoCapture(camera.url, cv2.CAP_FFMPEG)
+    if not cap.isOpened():
+        print(f"{Color.ERROR}[!] Failed to open RTSP stream for recording: {camera.url}{Color.RESET}")
+        return
+
+    w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) or 1280
+    h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) or 720
+    fps = float(cap.get(cv2.CAP_PROP_FPS)) or 20.0
+
+    fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+    writer = cv2.VideoWriter(output_filename, fourcc, fps, (w, h))
+
+    dur_str = f"for {duration_sec}s" if duration_sec else "continuously (press 'q' or ESC to stop)"
+    print(f"\n{Color.SUCCESS}[● RECORDING] Recording camera {camera.ip} to '{output_filename}' {dur_str}...{Color.RESET}")
+
+    start_time = time.time()
+    frame_count = 0
+    try:
+        while True:
+            if duration_sec and (time.time() - start_time > duration_sec):
+                break
+
+            ret, frame = cap.read()
+            if not ret or frame is None:
+                print(f"{Color.WARN}[!] Stream ended or interrupted during recording.{Color.RESET}")
+                break
+
+            writer.write(frame)
+            frame_count += 1
+
+            preview = cv2.resize(frame, (500, 500))
+            elapsed = int(time.time() - start_time)
+            cv2.circle(preview, (30, 30), 10, (0, 0, 255), -1)
+            cv2.putText(preview, f"REC {elapsed}s | {camera.ip}", (50, 38), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 255), 2)
+            
+            window_name = f"RTSP Recorder - {camera.ip}"
+            cv2.imshow(window_name, preview)
+
+            key = cv2.waitKey(1) & 0xFF
+            if key in (ord('q'), ord('Q'), 27) or cv2.getWindowProperty(window_name, cv2.WND_PROP_VISIBLE) < 1:
+                break
+    finally:
+        writer.release()
+        cap.release()
+        cv2.destroyAllWindows()
+        print(f"{Color.SUCCESS}[✓] Saved recorded video ({frame_count} frames) to '{output_filename}'{Color.RESET}")
+
+
+def launch_vlc(rtsp_url: str) -> bool:
+    """Attempts to open an RTSP stream using external VLC media player."""
+    vlc_paths = [
+        "vlc",
+        r"C:\Program Files\VideoLAN\VLC\vlc.exe",
+        r"C:\Program Files (x86)\VideoLAN\VLC\vlc.exe",
+        "/usr/bin/vlc",
+        "/Applications/VLC.app/Contents/MacOS/VLC",
+    ]
+    for vlc_bin in vlc_paths:
+        try:
+            subprocess.Popen([vlc_bin, rtsp_url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            print(f"{Color.SUCCESS}[✓] Launched VLC with stream: {rtsp_url}{Color.RESET}")
+            return True
+        except FileNotFoundError:
+            continue
+        except Exception as e:
+            print(f"{Color.WARN}[!] Failed to launch VLC ({vlc_bin}): {e}{Color.RESET}")
+            break
+
+    print(f"{Color.ERROR}[!] VLC media player not found on system PATH or default directories.{Color.RESET}")
+    return False
+
+def open_single_camera_by_id(working_cameras: List[CameraInfo]):
+    """Prompts user to select a camera ID, viewing duration, recording, or launch VLC player, and saves opened camera to file."""
+    if not working_cameras:
+        print(f"{Color.WARN}[!] No open/accessible cameras available to view.{Color.RESET}")
+        return
+
+    print(f"\n{Color.MAGENTA}Available Accessible Camera(s):{Color.RESET}")
+    for idx, cam in enumerate(working_cameras, 1):
+        res = f" ({cam.width}x{cam.height})" if cam.width else ""
+        print(f"  [{idx}] {cam.ip}{res} -> {cam.url} [{cam.auth_status}]")
+
+    cam_choice = input(f"\n{Color.INFO}Enter Camera ID to open (1-{len(working_cameras)}): {Color.RESET}").strip()
+    if not cam_choice.isdigit() or not (1 <= int(cam_choice) <= len(working_cameras)):
+        print(f"{Color.ERROR}[!] Invalid Camera ID selection.{Color.RESET}")
+        return
+
+    selected_cam = working_cameras[int(cam_choice) - 1]
+
+    save_filename = "opened_cameras.txt"
+    try:
+        with open(save_filename, "a") as f:
+            f.write(f"{selected_cam.url}\n")
+        print(f"{Color.SUCCESS}[✓] Saved opened camera URL to '{save_filename}'{Color.RESET}")
+    except Exception as e:
+        print(f"{Color.WARN}[!] Failed to save opened camera to file: {e}{Color.RESET}")
+
+    print(f"\n{Color.MAGENTA}Select Viewing / Recording Option:{Color.RESET}")
+    print("1. View for 10 seconds")
+    print("2. View for 30 seconds")
+    print("3. View for 1 minute (60 seconds)")
+    print("4. View continuously (Press 'q' or ESC to stop, 'r' to record)")
+    print("5. Record video stream to MP4 file")
+    print("6. Open stream in VLC Player")
+    dur_choice = input(f"{Color.INFO}Choice (1-6) [Default: 4]: {Color.RESET}").strip()
+
+    duration_map = {"1": 10, "2": 30, "3": 60, "4": None}
+
+    if dur_choice == "6":
+        launch_vlc(selected_cam.url)
+    elif dur_choice == "5":
+        rec_dur_str = input(f"{Color.INFO}Enter recording duration in seconds [Press Enter for continuous]: {Color.RESET}").strip()
+        rec_dur = int(rec_dur_str) if rec_dur_str.isdigit() else None
+        record_stream(selected_cam, duration_sec=rec_dur)
+    else:
+        duration_sec = duration_map.get(dur_choice, None)
+        dur_str = f"for {duration_sec}s" if duration_sec else "continuously"
+        print(f"\n{Color.INFO}[▶] Playing camera {selected_cam.ip} {dur_str}...{Color.RESET}")
+
+        cap = cv2.VideoCapture(selected_cam.url, cv2.CAP_FFMPEG)
+        if not cap.isOpened():
+            print(f"{Color.ERROR}[!] Failed to open RTSP stream at {selected_cam.url}{Color.RESET}")
+            return
+
+        start_time = time.time()
+        recording = False
+        rec_writer = None
+        rec_filename = None
+
+        while True:
+            if duration_sec and (time.time() - start_time > duration_sec):
+                break
+
+            ret, frame = cap.read()
+            if not ret or frame is None:
+                print(f"{Color.WARN}[!] Stream ended or interrupted.{Color.RESET}")
+                break
+
+            if recording and rec_writer:
+                rec_writer.write(frame)
+
+            display_frame = cv2.resize(frame, (500, 500))
+
+            overlay_text = f"{selected_cam.ip} ({selected_cam.width}x{selected_cam.height})" if selected_cam.width else selected_cam.ip
+            if recording:
+                cv2.circle(display_frame, (30, 30), 10, (0, 0, 255), -1)
+                cv2.putText(display_frame, f"REC {overlay_text}", (50, 38), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 255), 2)
+            else:
+                cv2.putText(display_frame, overlay_text, (20, 40), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2)
+
+            window_name = f"RTSP Stream - {selected_cam.ip}"
+            cv2.imshow(window_name, display_frame)
+
+            key = cv2.waitKey(30) & 0xFF
+            if key in (ord('q'), ord('Q'), 27) or cv2.getWindowProperty(window_name, cv2.WND_PROP_VISIBLE) < 1:
+                break
+            elif key == ord('s') or key == ord('S'):
+                fn = f"rtsp_cam_{selected_cam.ip}_{int(time.time())}.png"
+                cv2.imwrite(fn, display_frame)
+                print(f"{Color.SUCCESS}[✓] Saved screenshot: {fn}{Color.RESET}")
+            elif key == ord('r') or key == ord('R'):
+                if not recording:
+                    rec_filename = f"record_{selected_cam.ip}_{int(time.time())}.mp4"
+                    w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) or 1280
+                    h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) or 720
+                    fps = float(cap.get(cv2.CAP_PROP_FPS)) or 20.0
+                    fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+                    rec_writer = cv2.VideoWriter(rec_filename, fourcc, fps, (w, h))
+                    recording = True
+                    print(f"\n{Color.SUCCESS}[● STARTED RECORDING] Saving stream to {rec_filename}{Color.RESET}")
+                else:
+                    recording = False
+                    if rec_writer:
+                        rec_writer.release()
+                        rec_writer = None
+                    print(f"\n{Color.SUCCESS}[■ STOPPED RECORDING] Saved to {rec_filename}{Color.RESET}")
+
+        if rec_writer:
+            rec_writer.release()
+        cap.release()
+        cv2.destroyAllWindows()
+        print(f"{Color.SUCCESS}[✓] Playback finished.{Color.RESET}")
+
+
+def export_results(cameras: List[CameraInfo], output_path: str):
+    """Exports discovered working camera details to JSON, CSV, or TXT."""
+    if not output_path:
+        return
+
+    ext = os.path.splitext(output_path)[1].lower()
+    cam_dicts = [asdict(c) for c in cameras]
+
+    try:
+        if ext == ".json":
+            with open(output_path, "w") as f:
+                json.dump(cam_dicts, f, indent=4)
+        elif ext == ".csv":
+            if cam_dicts:
+                with open(output_path, "w", newline="") as f:
+                    writer = csv.DictWriter(f, fieldnames=cam_dicts[0].keys())
+                    writer.writeheader()
+                    writer.writerows(cam_dicts)
+        else:
+            with open(output_path, "w") as f:
+                for cam in cameras:
+                    f.write(f"{cam.url}\n")
+
+        print(f"{Color.SUCCESS}[✓] Successfully exported {len(cameras)} camera record(s) to '{output_path}'{Color.RESET}")
+    except Exception as e:
+        print(f"{Color.ERROR}[!] Error exporting results to {output_path}: {e}{Color.RESET}")
+
+
+def interactive_menu():
+    """Interactive CLI menu when no command line arguments are supplied."""
+    print(f"{Color.BLUE}{'=' * 60}")
+    print(f"{Color.MAGENTA}      RTSP Kit - Advanced Scanner & Multi-Camera Viewer")
+    print(f"{Color.BLUE}{'=' * 60}{Color.RESET}")
+
+    target = input(f"\n{Color.INFO}Enter target IP, Range, CIDR, or batch text file (e.g. 192.168.1.0/24 or targets.txt): {Color.RESET}").strip()
+    if not target:
+        print(f"{Color.ERROR}[!] Target required. Exiting.{Color.RESET}")
+        return
+
+    port = 554
+    paths = DEFAULT_RTSP_PATHS
+
+    enable_brute_input = input(f"{Color.INFO}Enable credential brute-force for locked cameras? (y/N): {Color.RESET}").strip().lower()
+    enable_brute = (enable_brute_input == 'y')
+
+    user_file = None
+    pass_file = None
+    if enable_brute:
+        uf = input(f"{Color.INFO}Path to username wordlist file [Press Enter for defaults]: {Color.RESET}").strip()
+        user_file = uf if uf else None
+        pf = input(f"{Color.INFO}Path to password wordlist file [Press Enter for defaults]: {Color.RESET}").strip()
+        pass_file = pf if pf else None
+
+    creds = None
+    if not enable_brute:
+        creds = input(f"{Color.INFO}Enter specific RTSP credentials user:pass (Press Enter to skip): {Color.RESET}").strip() or None
+
+    user_list = load_wordlist(user_file, DEFAULT_USERNAMES)
+    pass_list = load_wordlist(pass_file, DEFAULT_PASSWORDS)
+
+    scanner = RTSPScanner(
+        port=port,
+        timeout=3.0,
+        threads=50,
+        credentials=creds,
+        user_list=user_list,
+        pass_list=pass_list,
+        enable_brute=enable_brute
+    )
+    all_cameras = scanner.run_scan(target, paths)
+    working_cameras = [c for c in all_cameras if c.working]
+
+    print(f"\n{Color.HEADER}====== Scan Complete: Discovered {len(all_cameras)} Camera Host(s) ======{Color.RESET}")
+    for i, cam in enumerate(all_cameras, 1):
+        res = f" ({cam.width}x{cam.height})" if cam.width else ""
+        if cam.auth_status == "OPEN":
+            print(f"{i}. {Color.SUCCESS}[OPEN] {cam.ip}{res} -> {cam.url}{Color.RESET}")
+        elif cam.auth_status.startswith("UNLOCKED"):
+            print(f"{i}. {Color.INFO}[{cam.auth_status}] {cam.ip}{res} -> {cam.url}{Color.RESET}")
+        else:
+            print(f"{i}. {Color.WARN}[LOCKED] {cam.ip} -> Authentication required{Color.RESET}")
+
+    if not working_cameras:
+        print(f"\n{Color.WARN}No accessible (OPEN/UNLOCKED) RTSP streams found for video preview.{Color.RESET}")
+        return
+
+    export_ans = input(f"\n{Color.INFO}Save results to file? (e.g. cameras.json, cameras.txt, cameras.csv) [Enter to skip]: {Color.RESET}").strip()
+    if export_ans:
+        export_results(all_cameras, export_ans)
+
+    print(f"\n{Color.MAGENTA}Select Viewer Mode:{Color.RESET}")
+    print("1. Open Camera by ID (Timed 10s/30s/1m preview or VLC Player)")
+    print("2. PiP Multi-Camera Grid View")
+    print("3. Interactive Cycle Stream Viewer (Next/Prev)")
+    print("4. Exit")
+    choice = input(f"{Color.INFO}Choice (1-4) [Default: 1]: {Color.RESET}").strip()
+
+    if choice == "2":
+        grid = GridRenderer(working_cameras, cols=3)
+        grid.start_preview()
+    elif choice == "3":
+        viewer = SingleStreamViewer(working_cameras)
+        viewer.start_viewing()
+    elif choice == "4":
+        print(f"{Color.INFO}Exiting RTSP Kit.{Color.RESET}")
+    else:
+        open_single_camera_by_id(working_cameras)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="RTSP Kit - High-performance RTSP scanner, stream validator, brute-forcer, multi-camera viewer, and recorder."
+    )
+    parser.add_argument("target", nargs="*", help="IP(s), CIDR ranges (e.g. 192.168.1.0/24), IP ranges, or text files")
+    parser.add_argument("-f", "--targets-file", type=str, help="Batch file containing target IPs/subnets (one per line)")
+    parser.add_argument("-p", "--port", type=int, default=554, help="RTSP target port (default: 554)")
+    parser.add_argument("-t", "--threads", type=int, default=50, help="Concurrent scanner threads (default: 50)")
+    parser.add_argument("--timeout", type=float, default=3.0, help="Socket & RTSP connection timeout (default: 3.0s)")
+    parser.add_argument("-c", "--credentials", type=str, help="Single RTSP authentication pair user:pass")
+    parser.add_argument("-b", "--brute", action="store_true", help="Enable credential brute-forcing for LOCKED streams")
+    parser.add_argument("-U", "--user-file", type=str, help="File containing usernames for brute forcing")
+    parser.add_argument("-P", "--pass-file", type=str, help="File containing passwords for brute forcing")
+    parser.add_argument("--probe-paths", action="store_true", help="Probe popular camera RTSP subpaths (/h264, /live/ch0, etc.)")
+    parser.add_argument("-o", "--output", type=str, help="Output file path (.json, .csv, or .txt)")
+    parser.add_argument("--mode", choices=["grid", "single", "record", "scan-only"], default="grid", help="Execution mode (default: grid)")
+    parser.add_argument("--rec-duration", type=int, help="Recording duration in seconds for record mode")
+    parser.add_argument("--grid-cols", type=int, default=3, help="Number of columns for PiP grid (default: 3)")
+
+    args = parser.parse_args()
+
+    if not args.target and not args.targets_file:
+        interactive_menu()
+        return 0
+
+    targets_input_list = list(args.target) if args.target else []
+    if args.targets_file:
+        targets_input_list.append(args.targets_file)
+
+    combined_targets = ",".join(targets_input_list)
+
+    paths = DEFAULT_RTSP_PATHS if args.probe_paths else ["", "/"]
+    user_list = load_wordlist(args.user_file, DEFAULT_USERNAMES)
+    pass_list = load_wordlist(args.pass_file, DEFAULT_PASSWORDS)
+
+    enable_brute = args.brute or bool(args.user_file or args.pass_file)
+
+    scanner = RTSPScanner(
+        port=args.port,
+        timeout=args.timeout,
+        threads=args.threads,
+        credentials=args.credentials,
+        user_list=user_list,
+        pass_list=pass_list,
+        enable_brute=enable_brute
+    )
+    all_cameras = scanner.run_scan(combined_targets, paths)
+    working_cameras = [c for c in all_cameras if c.working]
+
+    print(f"\n{Color.BLUE}====== Scan Complete: Discovered {len(all_cameras)} Camera Host(s) ======{Color.RESET}")
+    for cam in all_cameras:
+        res = f" ({cam.width}x{cam.height})" if cam.width else ""
+        if cam.auth_status == "OPEN":
+            print(f"{Color.SUCCESS}[OPEN] {cam.ip}{res} -> {cam.url}{Color.RESET}")
+        elif cam.auth_status.startswith("UNLOCKED"):
+            print(f"{Color.INFO}[{cam.auth_status}] {cam.ip}{res} -> {cam.url}{Color.RESET}")
+        else:
+            print(f"{Color.WARN}[LOCKED] {cam.ip} -> Authentication required{Color.RESET}")
+
+    if args.output and all_cameras:
+        export_results(all_cameras, args.output)
+
+    if not working_cameras:
+        print(f"{Color.WARN}[!] No accessible (OPEN/UNLOCKED) RTSP video streams found.{Color.RESET}")
+        return 0
+
+    if args.mode == "grid":
+        grid = GridRenderer(working_cameras, cols=args.grid_cols)
+        grid.start_preview()
+    elif args.mode == "single":
+        viewer = SingleStreamViewer(working_cameras)
+        viewer.start_viewing()
+    elif args.mode == "record":
+        for cam in working_cameras:
+            record_stream(cam, duration_sec=args.rec_duration)
+    elif args.mode == "scan-only":
+        print(f"{Color.SUCCESS}[*] Scan complete.{Color.RESET}")
+
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

rtspkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+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).

rtspkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+rtspkit/__init__.py,sha256=W5_gJQcUvIFoxPXEraG8ZX445KMWis9x8Qb-HmVC1JE,661
+rtspkit/__main__.py,sha256=34eYCObEbNX6Fw8UgQMhT6WNmHb7OgJwbpikjIdb23Y,166
+rtspkit/rtspkit.py,sha256=Q9kci9GFxbLk5oYNCdqvhhCQwTzgz9rErMAfTwIyOLA,41243
+rtspkit-1.0.0.dist-info/licenses/LICENSE,sha256=u7e5MOnru6PmYQa53c_nsnDesQeSKKYX-EADgoJwRKI,1079
+rtspkit-1.0.0.dist-info/METADATA,sha256=bUoMyAm5MLKxNWlw3NsK7UfcZYaj6si4DNYt9lFEL0U,7974
+rtspkit-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rtspkit-1.0.0.dist-info/entry_points.txt,sha256=C3kbPBNQb8J10ZQc5uRC_PuvG9YSpJ0MpIBNeh5ajQs,49
+rtspkit-1.0.0.dist-info/top_level.txt,sha256=0rnUIeAQI0ON4tmcU6c_rwIhSdmXETsOnEUSTXzvAac,8
+rtspkit-1.0.0.dist-info/RECORD,,

rtspkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rtspkit-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rtspkit = rtspkit.rtspkit:main

rtspkit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RTSP Kit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT,Bridge OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rtspkit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rtspkit