watch-cast 0.1.0

25 surveillance and security camera overlay styles — CCTV, bodycam, dashcam, drone, thermal, night vision, motion detection, face blur, and evidence overlays

watch-cast

25 surveillance and security camera overlay styles for Python video pipelines.

What this is

watch-cast applies surveillance-aesthetic overlays to video clips: CCTV grain and timestamp burns, thermal and night-vision color treatments, bodycam and dashcam HUDs, motion-detection bounding boxes, face-blur and privacy-mask composites, drone telemetry readouts, and evidence-chain stamps. Each style is a named slug backed by a compositing pipeline that calls into video-fx for the underlying filter work.

Install

pip install watch-cast

With optional extras:

Extra	Installs	Use case
[overlay]	web-overlay	HTML/CSS overlay rendering
[multicam]	video-arrange	Split-screen security wall layouts
[dev]	pytest, ruff, build	Development and testing

Quickstart

from watch_cast import apply_overlay, SurveillanceConfig

cfg = SurveillanceConfig(
    style="bodycam_overlay",
    timestamp=True,
    blur_faces=True,
)

apply_overlay(
    input_path="interview_raw.mp4",
    output_path="interview_bodycam.mp4",
    config=cfg,
)

Render a looped security-wall feed from multiple clips:

from watch_cast import render_security_feed

render_security_feed(
    inputs=["cam_a.mp4", "cam_b.mp4", "cam_c.mp4", "cam_d.mp4"],
    output_path="security_wall.mp4",
    style="multi_cam_security_wall",
    grid=(2, 2),
)

List available styles at runtime:

from watch_cast import list_styles, get_style_info

for slug in list_styles():
    print(slug)

info = get_style_info("thermal_camera")
print(info.name, info.categories)

The 25 styles

All 25 styles belong to the surveillance_security family.

Camera treatments

Slug	Display name
surveillance_camera	Surveillance Camera
night_vision	Night Vision
thermal_camera	Thermal Camera
infrared_security	Infrared Security
fisheye_cctv	Fisheye CCTV
low_fps_cctv	Low FPS CCTV
hidden_camera	Hidden Camera
perimeter_camera	Perimeter Camera
plate_reader_camera	Plate Reader Camera
doorbell_camera	Doorbell Camera

HUD and overlay composites

Slug	Display name
security_grid_overlay	Security Grid Overlay
security_timestamp_burn	Security Timestamp Burn
motion_detection_boxes	Motion Detection Boxes
tracking_target_box	Tracking Target Box
bodycam_overlay	Bodycam Overlay
dashcam_overlay	Dashcam Overlay
drone_surveillance	Drone Surveillance
recon_scope	Recon Scope
access_control_feed	Access Control Feed
restricted_access_monitor	Restricted Access Monitor
multi_cam_security_wall	Multi-Cam Security Wall

Privacy and evidence

Slug	Display name
face_blur_overlay	Face Blur Overlay
pixelated_privacy_mask	Pixelated Privacy Mask
evidence_tape_overlay	Evidence Tape Overlay
evidence_locker_stamp	Evidence Locker Stamp

Composition with the Trollfabriken stack

watch-cast sits on top of video-fx and can receive scene cuts from cut-fx. A typical documentary evidence-treatment pipeline combines all three:

from cut_fx import detect_scenes
from video_fx import apply_effect
from watch_cast import apply_overlay, SurveillanceConfig

scenes = detect_scenes("raw_footage.mp4")
for scene in scenes:
    # Desaturate first with video-fx, then burn in evidence stamps
    apply_effect(scene.path, scene.path, effect="desaturate")
    apply_overlay(
        scene.path,
        scene.path.replace(".mp4", "_stamped.mp4"),
        config=SurveillanceConfig(style="evidence_locker_stamp"),
    )

CLI

# List all styles
watch-cast list

# Apply a style to a file
watch-cast apply --style bodycam_overlay input.mp4 output.mp4

# Apply with timestamp and face blur
watch-cast apply --style surveillance_camera --timestamp --blur-faces input.mp4 output.mp4

# Show metadata for a style
watch-cast info thermal_camera

# Render a security wall
watch-cast wall --style multi_cam_security_wall --grid 2x2 cam_a.mp4 cam_b.mp4 cam_c.mp4 cam_d.mp4 wall.mp4

Internal architecture

The package is organized into five sub-namespaces: styles (per-style compositing recipes), hud (timestamp, telemetry, reticle, and classification overlay renderers), motion_detect (background-subtraction helpers for bounding-box generation), schema (catalog loader and SurveillanceStyle model), and api (the public surface). All compositing calls go through video-fx for the pixel-level filter work.

What this is NOT

• Not a real-time camera driver or live RTSP processor
• Not a computer-vision object detector; motion_detection_boxes renders procedural or supplied bounding boxes, not detected ones
• Not a replacement for video-fx; it depends on video-fx and composes over it
• Not designed to strip or defeat actual privacy protections; face-blur is aesthetic, not certified
• Not a broadcast-safe certification tool; output timing and color accuracy are not guaranteed

Provenance

Built at Trollfabriken AITrix AB for civic-journalism evidence treatment, municipal audit video processing, and Timelock Film AB festival slate documentary and drama work.

---

Author: Trollfabriken AITrix AB <[e-mail]>
GitHub: tomastimelock
PyPI:   watch-cast