vitallens-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.monotonic())
    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.11 and ffmpeg installed 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.