Vitesse Video Feed

Stream video feeds to a Vitesse Gateway with WebRTC. Handles connection management, codec negotiation, and transport lifecycle automatically.

Installation

pip install vitesse-video-feed

Dependencies: aiortc, aiohttp, pymediasoup, numpy

Quick Start

import asyncio
from vitesse_video_feed import VideoFeedClient, VideoFeedConfig, CameraInfo

# 1. Implement your camera source
class MyCameraSource:
    def get_frame(self):
        # Return RGB numpy array (height, width, 3)
        return my_frame

    def is_active(self):
        return True

    @property
    def info(self):
        return CameraInfo(name="My Camera", resolution=(640, 480), framerate=15)

# 2. Connect and stream
async def main():
    config = VideoFeedConfig(gateway_url="192.168.1.100", use_https=True)
    client = VideoFeedClient(client_id="my-app", config=config)

    await client.connect()
    await client.add_camera("cam-1", MyCameraSource())

    # Stream until interrupted (cleanup is automatic)
    await asyncio.sleep(3600)

asyncio.run(main())

CameraSource Protocol

Your camera source must implement three things:

class CameraSource(Protocol):
    def get_frame(self) -> Optional[np.ndarray]:
        """Return RGB numpy array of shape (height, width, 3), or None."""
        ...

    def is_active(self) -> bool:
        """Return True if actively producing frames."""
        ...

    @property
    def info(self) -> CameraInfo:
        """Return camera metadata."""
        ...

CameraInfo

CameraInfo(
    name="Front Camera",           # Display name
    resolution=(1920, 1080),       # Width x Height
    framerate=30,                  # Target FPS
    description="Entrance cam",    # Optional description
    tags=["outdoor", "hd"],        # Optional tags
    location="Building A"          # Optional location
)

Configuration

VideoFeedConfig(
    gateway_url="192.168.1.100",   # Host/IP (or full URL)
    use_https=True,                # True = https://:7901, False = http://:7900
    priority_gateway_url=None,     # Optional internal URL to try first
    retry_attempts=3,              # Retries per URL
    retry_interval_s=2.0,          # Delay between retries
    reconnect_interval_s=10.0,     # Delay before full reconnection cycle
    max_reconnect_cycles=0,        # 0 = infinite reconnection
)

Event Callbacks

from vitesse_video_feed import FeedClientCallbacks

class MyCallbacks(FeedClientCallbacks):
    def on_connected(self):
        print("Connected!")

    def on_disconnected(self, reason: str):
        print(f"Disconnected: {reason}")

    def on_camera_added(self, camera_id: str):
        print(f"Camera {camera_id} streaming")

    def on_camera_removed(self, camera_id: str):
        print(f"Camera {camera_id} removed")

client = VideoFeedClient(client_id="app", config=config, callbacks=MyCallbacks())

Adapter for Existing Cameras

If you have an existing camera that doesn't match the protocol:

from vitesse_video_feed import CameraSourceAdapter, CameraInfo

source = CameraSourceAdapter(
    get_frame_fn=my_camera.read,
    is_active_fn=my_camera.is_open,
    camera_info=CameraInfo(name="Existing Cam", resolution=(640, 480))
)

await client.add_camera("cam-1", source)

Thread-Safe Scheduling

For use from synchronous code:

client.set_event_loop(loop)
client.schedule_add_camera("cam-1", source, callback=lambda ok: print(ok))
client.schedule_remove_camera("cam-1")

Automatic Cleanup

The client registers handlers for SIGINT, SIGTERM, and atexit. Resources are freed automatically even if disconnect() is not called.

License

MIT