tesla-clip-tools
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.pyusesimageio[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.pyimplements the canonical TeslaCam folder layout;wyze.py,reolink.py,unifi_protect.py,ring.py,nest.py,eufy.py, andfrigate.pyship in 0.4. Add a new vendor by subclassingSource— 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.