📹 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

pip install trueframe

Or, to install directly from source:

pip install .

🚀 Quick Start

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.