darvision 1.0.0__tar.gz

darvision-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Lint with ruff
+        run: ruff check src/
+
+      - name: Format check with black
+        run: black --check src/ tests/
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

darvision-1.0.0/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "python.defaultInterpreterPath": "${workspaceFolder}\\.venv\\Scripts\\python.exe",
+    "python.analysis.extraPaths": [
+        "${workspaceFolder}\\src",
+        "${workspaceFolder}\\.venv\\Lib\\site-packages"
+    ],
+    "python.analysis.venvPath": "${workspaceFolder}",
+    "python.analysis.venv": ".venv",
+    "pyrefly.pythonInterpreter": "${workspaceFolder}\\.venv\\Scripts\\python.exe",
+    "pyrefly.projectRoots": ["${workspaceFolder}/src"]
+}

darvision-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to DarVision
+
+Thank you for your interest in contributing!
+
+## Getting Started
+
+1. Fork the repository and clone it.
+2. Create a virtual environment:
+   ```bash
+   python -m venv .venv
+   .\.venv\Scripts\pip install -e .[dev]
+   ```
+3. Run the test suite to make sure everything works:
+   ```bash
+   .\.venv\Scripts\pytest tests/ -v
+   ```
+
+## Development Guidelines
+
+- **No `print()` in library code.** Use Python's `logging` module.
+- **No Base64 for frames.** Binary WebSocket messages only.
+- **New camera sources** must inherit from `CameraSource`.
+- **New AI plugins** must inherit from `DarVisionPlugin`.
+- **New transport implementations** must inherit from `Transport`.
+
+## Submitting a Pull Request
+
+1. Create a branch: `git checkout -b feature/my-feature`
+2. Make your changes with tests.
+3. Run `ruff check src/` and `black --check src/`.
+4. Open a pull request with a clear description.

darvision-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DarVision 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, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

darvision-1.0.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: darvision
+Version: 1.0.0
+Summary: A Python framework that lets any computer stream its webcam to a remote viewer over WebSockets.
+Author: Darshan Kerkar
+License: MIT
+License-File: LICENSE
+Keywords: computer-vision,opencv,remote,streaming,webcam,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Requires-Dist: websockets>=11.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: ngrok
+Requires-Dist: pyngrok>=7.0.0; extra == 'ngrok'
+Description-Content-Type: text/markdown
+
+# DarVision
+
+> **Stream any webcam to you — from anywhere in the world.**
+>
+> Created by [Darshan Kerkar](https://pypi.org/user/darshan-kerkar/)
+
+---
+
+## What is DarVision?
+
+DarVision is a Python framework that turns any computer into a webcam streaming server.
+
+The person on the **other side of the world** installs DarVision, runs one command, and their webcam is live. **You connect and watch.**
+
+```
+Their Computer                   Your Computer (Darshan)
+──────────────                   ───────────────────────
+pip install darvision
+darvision host --public   ──►    darvision connect wss://xxxx.ngrok-free.app
+(their webcam streams)           (you watch their stream)
+```
+
+---
+
+## Installation
+
+```bash
+pip install darvision
+```
+
+With ngrok (for public streaming over the Internet):
+```bash
+pip install darvision[ngrok]
+```
+
+---
+
+## Usage
+
+### They host — you watch
+
+**Step 1 — Remote person (the host):**
+```bash
+pip install darvision[ngrok]
+darvision host --public
+```
+
+They will see:
+```
+──────────────────────────────────────────────────
+  🎥  DarVision Host is running
+──────────────────────────────────────────────────
+  Local  :  ws://192.168.x.x:8765
+  Public :  wss://abcd1234.ngrok-free.app
+──────────────────────────────────────────────────
+```
+
+**Step 2 — They send you the `wss://` URL.**
+
+**Step 3 — You connect (Darshan):**
+```bash
+darvision connect wss://abcd1234.ngrok-free.app
+```
+
+A window opens showing their live webcam.
+
+---
+
+### Local preview (host can see their own stream)
+```bash
+darvision host --preview
+```
+
+---
+
+### Health check
+```bash
+darvision doctor
+```
+
+---
+
+## Python API
+
+**Host (remote machine):**
+```python
+from darvision import Host
+Host().start()
+```
+
+**Client (your machine):**
+```python
+from darvision import Client
+Client().connect("wss://abcd1234.ngrok-free.app")
+```
+
+---
+
+## Roadmap
+
+| Version | Feature |
+|---------|---------|
+| v1.0 | ✅ Webcam streaming over LAN / Internet |
+| v1.1 | Camera source abstraction (video files, RTSP) |
+| v1.2 | MediaPipe Pose plugin |
+| v1.3 | Hand tracking plugin |
+| v1.4 | YOLO object detection plugin |
+| v1.5 | OCR plugin |
+| v2.0 | Multi-client, browser viewer, recording |
+
+---
+
+## Author
+
+**Darshan Kerkar**
+MIT License

darvision-1.0.0/README.md

@@ -0,0 +1,116 @@
+# DarVision
+
+> **Stream any webcam to you — from anywhere in the world.**
+>
+> Created by [Darshan Kerkar](https://pypi.org/user/darshan-kerkar/)
+
+---
+
+## What is DarVision?
+
+DarVision is a Python framework that turns any computer into a webcam streaming server.
+
+The person on the **other side of the world** installs DarVision, runs one command, and their webcam is live. **You connect and watch.**
+
+```
+Their Computer                   Your Computer (Darshan)
+──────────────                   ───────────────────────
+pip install darvision
+darvision host --public   ──►    darvision connect wss://xxxx.ngrok-free.app
+(their webcam streams)           (you watch their stream)
+```
+
+---
+
+## Installation
+
+```bash
+pip install darvision
+```
+
+With ngrok (for public streaming over the Internet):
+```bash
+pip install darvision[ngrok]
+```
+
+---
+
+## Usage
+
+### They host — you watch
+
+**Step 1 — Remote person (the host):**
+```bash
+pip install darvision[ngrok]
+darvision host --public
+```
+
+They will see:
+```
+──────────────────────────────────────────────────
+  🎥  DarVision Host is running
+──────────────────────────────────────────────────
+  Local  :  ws://192.168.x.x:8765
+  Public :  wss://abcd1234.ngrok-free.app
+──────────────────────────────────────────────────
+```
+
+**Step 2 — They send you the `wss://` URL.**
+
+**Step 3 — You connect (Darshan):**
+```bash
+darvision connect wss://abcd1234.ngrok-free.app
+```
+
+A window opens showing their live webcam.
+
+---
+
+### Local preview (host can see their own stream)
+```bash
+darvision host --preview
+```
+
+---
+
+### Health check
+```bash
+darvision doctor
+```
+
+---
+
+## Python API
+
+**Host (remote machine):**
+```python
+from darvision import Host
+Host().start()
+```
+
+**Client (your machine):**
+```python
+from darvision import Client
+Client().connect("wss://abcd1234.ngrok-free.app")
+```
+
+---
+
+## Roadmap
+
+| Version | Feature |
+|---------|---------|
+| v1.0 | ✅ Webcam streaming over LAN / Internet |
+| v1.1 | Camera source abstraction (video files, RTSP) |
+| v1.2 | MediaPipe Pose plugin |
+| v1.3 | Hand tracking plugin |
+| v1.4 | YOLO object detection plugin |
+| v1.5 | OCR plugin |
+| v2.0 | Multi-client, browser viewer, recording |
+
+---
+
+## Author
+
+**Darshan Kerkar**
+MIT License

darvision-1.0.0/docs/architecture.md

@@ -0,0 +1,62 @@
+# DarVision Architecture
+
+## Pipeline Overview
+
+```
+Camera Source (Thread 1)
+        │
+   FrameQueue (bounded, drop-oldest)
+        │
+Plugin Manager (Thread 2)
+        │
+  FrameEncoder (JPEG → binary)
+        │
+ Transport.send_bytes() ─── asyncio event loop (Thread 3)
+        │
+     Internet / LAN
+        │
+ Transport.on_bytes() ─── asyncio event loop
+        │
+  FrameDecoder (binary → numpy)
+        │
+   Renderer (Thread 4)
+```
+
+## Key Design Decisions
+
+### Binary WebSocket (no Base64)
+Frames are sent as raw JPEG bytes prefixed with a small JSON header.
+This is ~33% smaller and faster than Base64-encoded JSON.
+
+### Bounded FrameQueue
+The camera never blocks on a slow network. When the queue is full,
+the oldest frame is dropped. This keeps latency low under load.
+
+### Abstract Interfaces
+Every major component is behind an interface:
+- `CameraSource` — swap webcam/video/RTSP
+- `Transport` — swap WebSocket/WebRTC/Cloudflare
+- `TunnelProvider` — swap ngrok/Cloudflare Tunnel
+- `Renderer` — swap OpenCV/Qt/Browser
+- `DarVisionPlugin` — add any AI model
+
+### Thread Model
+| Thread | Responsibility |
+|--------|---------------|
+| Camera | Read frames from hardware |
+| Plugin | Process frames through AI plugins |
+| Network | asyncio event loop (send/receive) |
+| Renderer | Display frames in GUI window |
+
+## Protocol Wire Format
+
+Binary frame message:
+```
+[4 bytes: header length (big-endian uint32)]
+[N bytes: JSON header]
+[M bytes: raw JPEG]
+```
+
+JSON header contains: `version`, `type`, `timestamp`, `width`, `height`, `size`.
+
+Text messages (heartbeat, events): plain JSON.

darvision-1.0.0/docs/quickstart.md

@@ -0,0 +1,70 @@
+# DarVision Quickstart
+
+## Installation
+
+```bash
+pip install darvision
+```
+
+With ngrok tunnel support:
+```bash
+pip install darvision[ngrok]
+```
+
+## Stream your webcam over LAN
+
+**On the host machine:**
+```bash
+darvision host
+```
+
+You'll see:
+```
+──────────────────────────────────────────────────
+  🎥  DarVision Host is running
+──────────────────────────────────────────────────
+  Local  :  ws://192.168.1.15:8765
+  Public :  (use --public to enable ngrok tunnel)
+──────────────────────────────────────────────────
+```
+
+**On the client machine:**
+```bash
+darvision connect ws://192.168.1.15:8765
+```
+
+A window will pop up showing the host's webcam feed in real time. Press `q` to quit.
+
+## Stream over the Internet (ngrok)
+
+```bash
+darvision host --public
+```
+
+This starts an ngrok tunnel and prints a public URL:
+```
+  Public :  wss://abcd1234.ngrok-free.app
+```
+
+The client can then connect from anywhere:
+```bash
+darvision connect wss://abcd1234.ngrok-free.app
+```
+
+## Python API
+
+```python
+from darvision import Host, Client
+
+# Host
+Host().start()
+
+# Client
+Client().connect("ws://192.168.1.15:8765")
+```
+
+## Check your setup
+
+```bash
+darvision doctor
+```

darvision-1.0.0/examples/camera_stream_client.py

@@ -0,0 +1,22 @@
+"""
+camera_stream_client.py — Connect to a DarVision host and display its webcam.
+
+Run this after starting the host:
+    .\.venv\Scripts\python examples\camera_stream_client.py ws://localhost:8765
+
+Or with a public ngrok URL:
+    .\.venv\Scripts\python examples\camera_stream_client.py wss://xxxx.ngrok-free.app
+
+Press 'q' in the video window to exit.
+"""
+
+import sys
+from darvision import Client
+from darvision.config import setup_logging
+
+setup_logging("INFO")
+
+address = sys.argv[1] if len(sys.argv) > 1 else "ws://localhost:8765"
+
+client = Client()
+client.connect(address)

darvision-1.0.0/examples/camera_stream_host.py

@@ -0,0 +1,23 @@
+"""
+camera_stream_host.py — Start the DarVision host (local LAN streaming).
+
+Run this on the machine that has the webcam:
+    .\.venv\Scripts\python examples\camera_stream_host.py
+
+Then on a second machine (or terminal), run:
+    .\.venv\Scripts\darvision connect ws://<your-ip>:8765
+"""
+
+from darvision import Host
+from darvision.config import DarVisionConfig, setup_logging
+
+setup_logging("INFO")
+
+cfg = DarVisionConfig()
+cfg.camera.width = 640
+cfg.camera.height = 480
+cfg.camera.fps = 30
+cfg.network.port = 8765
+
+host = Host(config=cfg)
+host.start()

darvision-1.0.0/examples/minimal_client.py

@@ -0,0 +1,6 @@
+"""
+minimal_client.py — Absolute minimum code to connect a DarVision client.
+"""
+from darvision import Client
+
+Client().connect("ws://localhost:8765")

darvision-1.0.0/examples/minimal_host.py

@@ -0,0 +1,6 @@
+"""
+minimal_host.py — Absolute minimum code to start a DarVision host.
+"""
+from darvision import Host
+
+Host().start()

darvision-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "darvision"
+version = "1.0.0"
+description = "A Python framework that lets any computer stream its webcam to a remote viewer over WebSockets."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Darshan Kerkar" }
+]
+keywords = ["computer-vision", "webcam", "streaming", "websocket", "opencv", "remote"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+
+dependencies = [
+    "opencv-python>=4.8.0",
+    "numpy>=1.24.0",
+    "fastapi>=0.100.0",
+    "uvicorn[standard]>=0.23.0",
+    "websockets>=11.0",
+    "click>=8.0.0",
+    "pydantic>=2.0.0",
+    "Pillow>=10.0.0",
+    "PyYAML>=6.0.0",
+]
+
+[project.optional-dependencies]
+ngrok = ["pyngrok>=7.0.0"]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "black>=23.0.0",
+]
+
+[project.scripts]
+darvision = "darvision.cli:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/darvision"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

darvision-1.0.0/src/darvision/__init__.py

@@ -0,0 +1,10 @@
+"""
+DarVision — Real-time computer vision streaming framework.
+"""
+
+from darvision.host.host import Host
+from darvision.client.client import Client
+from darvision.plugins.base import DarVisionPlugin
+
+__version__ = "1.0.0"
+__all__ = ["Host", "Client", "DarVisionPlugin", "__version__"]

darvision-1.0.0/src/darvision/camera/__init__.py

@@ -0,0 +1,6 @@
+"""DarVision Camera package."""
+from darvision.camera.base import CameraSource
+from darvision.camera.webcam import WebcamSource
+from darvision.camera.queue import FrameQueue
+
+__all__ = ["CameraSource", "WebcamSource", "FrameQueue"]

darvision-1.0.0/src/darvision/camera/base.py

@@ -0,0 +1,59 @@
+"""
+Abstract camera source interface.
+All camera implementations must inherit from CameraSource.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import numpy as np
+
+
+class CameraSource(ABC):
+    """
+    Abstract base class for all DarVision camera sources.
+
+    Supported sources (v1: WebcamSource only):
+      - WebcamSource   — USB or built-in webcam via OpenCV
+      - VideoSource    — video file (future v1.1)
+      - RTSPSource     — IP/RTSP camera (future v1.1)
+    """
+
+    @abstractmethod
+    def open(self) -> None:
+        """Open and initialize the camera source. Raises CameraError on failure."""
+        pass
+
+    @abstractmethod
+    def read(self) -> Optional[np.ndarray]:
+        """
+        Read the next frame.
+        Returns a BGR numpy array, or None if no frame is available.
+        """
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release the camera source and any associated resources."""
+        pass
+
+    @property
+    @abstractmethod
+    def is_open(self) -> bool:
+        """True if the source is currently open and ready to read."""
+        pass
+
+    @property
+    @abstractmethod
+    def width(self) -> int:
+        pass
+
+    @property
+    @abstractmethod
+    def height(self) -> int:
+        pass
+
+    @property
+    @abstractmethod
+    def fps(self) -> float:
+        pass