Metadata-Version: 2.4
Name: watch-cast
Version: 0.1.0
Summary: 25 surveillance and security camera overlay styles — CCTV, bodycam, dashcam, drone, thermal, night vision, motion detection, face blur, and evidence overlays
Project-URL: Homepage, https://github.com/tomastimelock/watch-cast
Project-URL: Issues, https://github.com/tomastimelock/watch-cast/issues
Project-URL: Source, https://github.com/tomastimelock/watch-cast
Author-email: Trollfabriken AITrix AB <dev@trollfabriken.se>
License: MIT License
        
        Copyright (c) 2026 Trollfabriken AITrix AB
        
        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.
License-File: LICENSE
Keywords: bodycam,cctv,night-vision,overlay,security,surveillance,thermal,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.10
Requires-Dist: ffmpeg-python>=0.2
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python-headless>=4.8
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.5
Requires-Dist: video-fx>=0.1
Provides-Extra: all
Requires-Dist: video-arrange>=0.1; extra == 'all'
Requires-Dist: web-overlay>=0.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: multicam
Requires-Dist: video-arrange>=0.1; extra == 'multicam'
Provides-Extra: overlay
Requires-Dist: web-overlay>=0.1; extra == 'overlay'
Description-Content-Type: text/markdown

# 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

```python
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:

```python
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:

```python
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:

```python
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

```bash
# 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 <dev@trollfabriken.se>
GitHub: tomastimelock
PyPI:   watch-cast
```
