Metadata-Version: 2.4
Name: trueframe
Version: 0.1.0
Summary: A high-performance, latency-free RTSP stream reader for real-time AI inference.
Author-email: "ytcalifax (98w)" <hello@98w.eu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ytcalifax/trueframe
Project-URL: Repository, https://github.com/ytcalifax/trueframe.git
Keywords: rtsp,opencv,streaming,computer-vision,yolo,latency-free
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Video :: Capture
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=1.26.0
Requires-Dist: opencv-python>=4.8.0
Dynamic: license-file

# 📹 TrueFrame

> **A robust, latency-free RTSP stream reader for Python, designed to fetch the absolute latest frame.**

TrueFrame gives you a clean, dependency-light Python interface to any RTSP stream. It intelligently handles connection drops and buffer management, ensuring you always get the most recent frame without smearing, artifacting, or latency buildup.

## ✨ Features

- **🚀 Zero Latency**: Uses a background thread to continuously flush the stream buffer, so `read()` always returns the latest frame.
- **🔌 Robust Reconnects**: Automatically handles stream interruptions and attempts to reconnect without user intervention.
- **🖼️ Simple & Clean API**: An intuitive interface that's easy to integrate. Use it as a context manager for automatic resource cleanup.
- **🗂️ Modular Design**: A clean, SOLID-based architecture (`Camera`, `FrameGrabber`, `Stream`) for better maintainability.
- **⚡ Minimal Dependencies**: Only needs `opencv-python` and `numpy`.
- **🐍 Context Manager**: Built-in `__enter__` and `__exit__` for safe and easy resource management.

## 📥 Installation

```bash
pip install trueframe
```

Or, to install directly from source:

```bash
pip install .
```

## 🚀 Quick Start

```python
import cv2
from trueframe import TrueFrame

# Replace with your RTSP stream URL
RTSP_URL = 'rtsp://user:pass@192.168.1.100:554/stream'

def main():
    # Use a 'with' statement for automatic resource management
    with TrueFrame(RTSP_URL) as stream:
        print(f"Connecting to {RTSP_URL}...")
        
        while True:
            # Read the latest frame
            frame = stream.read()

            # If a frame was received, display it
            if frame is not None:
                cv2.imshow("TrueFrame RTSP Stream", frame)

            # Press 'q' to exit the loop
            if cv2.waitKey(1) & 0xFF == ord('q'):
                break

    # Clean up
    cv2.destroyAllWindows()
    print("Stream stopped.")

if __name__ == "__main__":
    main()
```

## ⚙️ Core Components

| Class          | Description                                                                    |
|----------------|--------------------------------------------------------------------------------|
| `TrueFrame`    | The main, user-facing class that provides the simple `read()`/`stop()` API.    |
| `Stream`       | A facade that coordinates the `Camera` and `FrameGrabber` components.          |
| `Camera`       | A low-level wrapper around `cv2.VideoCapture` for connecting and grabbing.     |
| `FrameGrabber` | The background worker that runs in a separate thread to continuously fetch frames. |

## 🐍 Requirements

- Python **3.8+**
- `opencv-python`
- `numpy`

## 🤝 Contributing

Issues and pull requests are welcome! Please file an issue if you encounter any problems or have suggestions for improvements.

---
*Built with ❤️ for smooth video streaming. MIT Licensed.*
