Metadata-Version: 2.4
Name: previewier
Version: 0.1.0
Summary: Lightweight remote image/video preview server for Python scripts
Author: previewier contributors
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: opencv
Requires-Dist: opencv-python>=4.8; extra == "opencv"
Provides-Extra: pillow
Requires-Dist: Pillow>=10.0; extra == "pillow"
Provides-Extra: av
Requires-Dist: av>=12.0; extra == "av"
Requires-Dist: numpy>=1.24; extra == "av"
Provides-Extra: full
Requires-Dist: opencv-python>=4.8; extra == "full"
Requires-Dist: Pillow>=10.0; extra == "full"
Requires-Dist: av>=12.0; extra == "full"
Requires-Dist: numpy>=1.24; extra == "full"
Provides-Extra: dev
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# previewier

[![CI](https://github.com/JooudDoo/Previewier/actions/workflows/ci.yml/badge.svg)](https://github.com/<OWNER>/<REPO>/actions/workflows/ci.yml)

Lightweight Python 3.10+ library for remote preview of images/video from scripts running on servers.

## Goals

- Minimal integration into existing scripts.
- Lightweight HTTP preview (MJPEG) without heavy web frameworks.
- Optional RTSP stream for standard players.
- Optional recording to file with PyAV and configurable codec/container.

## Install

Base package:

```bash
pip install -e .
```

With optional features:

```bash
pip install -e ".[opencv,av]"
```

## Quick start (minimal code changes)

```python
from previewier import PreviewServer

server = PreviewServer(
    host="0.0.0.0",
    http_port=8080,
    enable_http=True,
    enable_rtsp=True,
    rtsp_port=8554,
    rtsp_path="/preview",
    rtsp_codec="libx264",
    save_path="recordings/out.mp4",
    save_codec="libx264",
    fps=25,
)
server.start()

# In your frame loop:
# frame: numpy ndarray, BGR, shape [H, W, 3]
server.publish_frame(frame)

# On shutdown:
server.stop()
```

Context manager mode:

```python
from previewier import PreviewServer

with PreviewServer(host="0.0.0.0", http_port=8080) as server:
    # frame loop
    server.publish_frame(frame)
```

HTTP preview URL:

- `http://<server-ip>:8080/` (live MJPEG page)
- `http://<server-ip>:8080/snapshot.jpg` (latest frame)

RTSP URL:

- `rtsp://<server-ip>:8554/preview`

## API

`PreviewServer(...)` key options:

- `enable_http=True`: enable built-in MJPEG HTTP server.
- `enable_rtsp=False`: enable RTSP publish via PyAV.
- `rtsp_codec="libx264"`: RTSP codec, e.g. `libx264`, `libx265`, `mpeg4`.
- `save_path=None`: if set, writes video using PyAV.
- `save_codec="libx264"`: recording codec, e.g. `libx264`, `libx265`, `mpeg4`, `mjpeg`.
- `save_pix_fmt="yuv420p"`: output pixel format for recorder.

Methods:

- `start() / stop()`
- `publish_frame(frame)` for ndarray BGR frame
- `publish_jpeg(jpeg_bytes)` if you already have JPEG bytes

## Notes

- For `publish_frame`, install at least one JPEG backend:
  - OpenCV: `pip install previewier[opencv]`
  - Pillow: `pip install previewier[pillow]`
- RTSP mode requires PyAV: `pip install previewier[av]`.
- RTSP mode publishes to an external RTSP server endpoint (for example MediaMTX).
- If `host="0.0.0.0"`, RTSP publish target is normalized to `127.0.0.1`.
- Recording requires PyAV: `pip install previewier[av]`.

## Example

See `examples/basic_cv2.py`.

## Development

Install dev tools in your `.venv`:

```bash
python -m pip install -e ".[dev]"
```

Enable git hooks:

```bash
pre-commit install --hook-type pre-commit --hook-type pre-push
pre-commit run --all-files
```

Test coverage is enforced by pytest config:

- minimum total coverage: `80%`
- command: `python -m pytest --cov=previewier --cov-report=term-missing --cov-fail-under=80`
