Skip to main content

tesla-clip-tools

PyPI CI

Reusable primitives for building tools that read Tesla TeslaCam, SentryClips, and SEI data — plus the same Source/Event/sampler/vlm/notify pipeline applied to Wyze, Reolink, UniFi Protect, Ring, Nest, Eufy, and Frigate.

Extracted from sentrytriage v0.2 → v0.3 so that future projects (planned: an FSD-Disengagement Studio, a Wyze/Reolink/UniFi port of sentrytriage) can share the same primitives without forking.

Install

pip install tesla-clip-tools                      # base
pip install 'tesla-clip-tools[sei]'               # adds protobuf+pandas for sei_dataframe()

Or with uv:

uv add tesla-clip-tools
uv add 'tesla-clip-tools[sei]'

Until the first PyPI release lands, install directly from GitHub:

uv add git+https://github.com/Raymondriter/tesla-clip-tools

What's inside

tesla_clip_tools/
├── sources/
│   ├── base.py          Abstract Source + Event dataclass
│   ├── tesla.py         SentryClips/<YYYY-MM-DD_HH-MM-SS>/{cam}.mp4 (HW3 4-cam + HW4 6-cam)
│   ├── wyze.py          Wyze SD-card / RTSP folder layout
│   ├── reolink.py       Reolink NVR folder layout
│   ├── unifi_protect.py UniFi Protect export layout
│   ├── ring.py          Ring downloads layout
│   ├── nest.py          Nest / Google Home downloads layout
│   ├── eufy.py          Eufy app / HomeBase NAS export layout
│   └── frigate.py       Frigate NVR clips/ layout (+ sibling .json metadata)
├── sampler.py           Frame extraction via imageio (bundled ffmpeg, no system dep)
├── vlm/
│   ├── base.py          Generic VLMBackend protocol parameterised on a Pydantic response_format
│   ├── openai.py        gpt-4o-mini default, structured outputs via beta.chat.completions.parse
│   └── ollama.py        Local Qwen2.5-VL etc. via the Ollama HTTP API + JSON-schema format
├── notify/
│   ├── base.py          Notifier protocol
│   ├── pushover.py
│   └── telegram.py
├── sei.py               SEI metadata extraction from Dashcam (Saved/Recent) clips
└── dashcam.proto        Tesla's published proto schema (vendored)

Generating the SEI protobuf module

For the SEI dataframe convenience function, you also need to generate the protobuf module once:

protoc --python_out=src/tesla_clip_tools src/tesla_clip_tools/dashcam.proto

iter_sei_payloads() works without protobuf — it just yields raw protobuf-encoded byte payloads.

Minimal example

from pathlib import Path
from tesla_clip_tools.sources.tesla import TeslaSource
from tesla_clip_tools.sampler import sample_keyframes
from tesla_clip_tools.vlm.openai import OpenAIBackend
from pydantic import BaseModel

class MyVerdict(BaseModel):
    is_interesting: bool
    why: str

source = TeslaSource(Path("~/Tesla/SentryClips"))
vlm = OpenAIBackend(model="gpt-4o-mini")

for event in source.discover():
    samples = sample_keyframes(event.cams, n_per_cam=4)
    captions = [f"[{s.cam} t={s.timestamp_seconds:.1f}s]" for s in samples]
    verdict = vlm.classify(
        images=[s.image for s in samples],
        captions=captions,
        system_prompt="Decide if this Sentry event deserves attention. Default to false.",
        response_format=MyVerdict,
    )
    print(event.id, verdict.is_interesting, verdict.why)

Design choices

  • Generic VLM API. Every backend takes a response_format: type[BaseModel] so different consumers (sentrytriage, FSD-Disengagement Studio, future tools) define their own verdict schema without forking the backend.
  • No state. No SQLite, no daemon, no notifications-orchestration. Those are application concerns; the library is just primitives. Use notify/ if you want one of the included notifiers, but it's optional.
  • No system ffmpeg required for the read path. sampler.py uses imageio[ffmpeg] which bundles its own ffmpeg binary. (Tools that build filter graphs — the highlight reel in sentrytriage, e.g. — still need system ffmpeg.)
  • Source-pluggable. tesla.py implements the canonical TeslaCam folder layout; wyze.py, reolink.py, unifi_protect.py, ring.py, nest.py, eufy.py, and frigate.py ship in 0.4. Add a new vendor by subclassing Source — the rest of the pipeline doesn't care.

Status

v0.4 — alpha, API may still change. Used in production by sentrytriage v0.3+ and fsd-disengagement-studio.

Changelog

See CHANGELOG.md for the version history. Releases are cut following the steps in RELEASE.md.

License

MIT.

CI

ci

GitHub Actions runs ruff + pytest on Python 3.12 and 3.13 against every push and PR. See .github/workflows/ci.yml. The same tests also run as part of the workspace-level monorepo CI at C:\Dev\tesla\.github\workflows\ci.yml.

Metadata

Release files for tesla-clip-tools 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tesla-clip-tools 0.6.0
File Size Uploaded Provenance Actions
tesla_clip_tools-0.6.0.tar.gz 38.7 kB Without provenance Details for tesla_clip_tools-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tesla-clip-tools 0.6.0
File Interpreter ABI Platform Actions
tesla_clip_tools-0.6.0-py3-none-any.whl Python 3 none any Details for tesla_clip_tools-0.6.0-py3-none-any.whl

Total release size: 76.0 kB

Release files / tesla_clip_tools-0.6.0.tar.gz

Download URL tesla_clip_tools-0.6.0.tar.gz
Size 38.7 kB
Tags Source
SHA-256 checksum
How to use checksums
1c3aff0cf1348637d7489a22c8dbead3b810f3b72c3288036c7765562a8a1c26
BLAKE2b-256 checksum
How to use checksums
e918044437c7129cf2aee39676acc0b188c64de24fdd0d6ef37148aa0e961f82
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.12 {"installer":{"name":"uv","version":"0.11.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / tesla_clip_tools-0.6.0-py3-none-any.whl

Download URL tesla_clip_tools-0.6.0-py3-none-any.whl
Size 37.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
94bc72ede91dd475fd7f79c0bc050c35157db77f1eadc37df94c9ee962f70608
BLAKE2b-256 checksum
How to use checksums
b5ceed2a349c750bd48089b08124d6d37e692f292e2b13915f81778c8247101e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.12 {"installer":{"name":"uv","version":"0.11.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for tesla-clip-tools 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page