vitallens-python
Estimate vital signs such as heart rate, HRV, and respiratory rate from video in Python.
vitallens is the official Python client for the VitalLens API, a service for estimating physiological vital signs like heart rate (HR), respiratory rate (RR), and heart rate variability (HRV) from facial video.
The library provides:
- High-Fidelity Accuracy: A simple interface to the VitalLens API for state-of-the-art estimation (heart rate, respiratory rate, HRV).
- Local Fallbacks: Implementations of classic rPPG algorithms (
pos,chrom,g) for local, API-free processing. - Flexible Input: Support for video files and in-memory
np.ndarray. - Real-time Streaming:
stream()context manager for low-latency live inference. - Face Detection: Integrated fast face detection and ROI management.
Using a different language? Check out our JavaScript client and iOS SDK.
Installation
pip install vitallens
Quickstart
Try it instantly (No API Key)
You can test the library immediately using classic local algorithms (like pos). This runs entirely on your machine.
from vitallens import VitalLens
# Use a local method (Pulse only, no API Key required)
vl = VitalLens(method="pos")
results = vl("path/to/video.mp4")
print("Heart Rate:", results[0]['vitals']['heart_rate']['value'])
Get High-Fidelity Accuracy (with API Key)
To get improved accuracy and advanced metrics like Respiratory Rate and HRV, use the vitallens method. You can get a free key from the API Dashboard.
from vitallens import VitalLens
# Automatically selects the best model for your plan
vl = VitalLens(method="vitallens", api_key="YOUR_API_KEY")
results = vl("path/to/video.mp4")
vitals = results[0]['vitals']
print(f"Heart Rate: {vitals['heart_rate']['value']:.1f} bpm")
print(f"Respiratory Rate: {vitals['respiratory_rate']['value']:.1f} rpm")
# HRV is available on paid plans
if 'hrv_sdnn' in vitals:
print(f"HRV (SDNN): {vitals['hrv_sdnn']['value']:.1f} ms")
Real-time Streaming
Process live frames from a webcam or stream.
import time
from vitallens import VitalLens
# Process live frames
vl = VitalLens(method="vitallens", api_key="YOUR_API_KEY")
with vl.stream() as session:
# In your capture loop (e.g., OpenCV)
session.push(frame, timestamp=time.time())
results = session.get_result(block=False)
Documentation
For full API reference, advanced configuration, proxy usage, and result schemas, visit the documentation at docs.rouast.com/python.
Troubleshooting
- Prerequisites: Requires
python>=3.11andffmpeginstalled and on your$PATH. - Windows: Microsoft Visual C++ Build Tools are required.
- ONNX Runtime: If you encounter installation issues with
onnxruntime, try installing it via conda first:conda install -c conda-forge onnxruntime.
Disclaimer
vitallens provides vital sign estimates for general wellness purposes only. It is not intended for medical use. Always consult with your doctor for any health concerns or for medically precise measurement.
See also our Terms of Service for the VitalLens API and our Privacy Policy.
License
This project is licensed under the MIT License.
1 maintainer
Metadata
1 maintainer
Release files for vitallens 0.6.2
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 | |
|---|---|---|---|---|
| vitallens-0.6.2.tar.gz | 1.1 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vitallens-0.6.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.2 MB
Release files / vitallens-0.6.2.tar.gz
| Download URL | vitallens-0.6.2.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6aaa7acc5bb6e4dd86b596e2a1fa230333086a321011593cc765b35c43bc4667
|
|
BLAKE2b-256 checksum How to use checksums |
0fd128eaa0533c348056642c054d9423f172ebeaa3e35bd5aa47b69af1e8dbac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logRelease files / vitallens-0.6.2-py3-none-any.whl
| Download URL | vitallens-0.6.2-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
28206df63c0512b7915548759d7c5226c5d26b46959642ac10b6f6cfef5e3c60
|
|
BLAKE2b-256 checksum How to use checksums |
710200ebb2aa728bed1aca74532193bc71c21c4adedfdc7a8118bb90ab216166
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logSecurity for vitallens 0.6.2
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for vitallens-0.6.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logA 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.
