previewier 0.1.0

Lightweight remote image/video preview server for Python scripts

previewier

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:

pip install -e .

With optional features:

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

Quick start (minimal code changes)

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:

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:

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

Enable git hooks:

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