ppg-js documentation
Measure heart rate, pulse-rate variability, and respiration from a fingertip on a phone camera in the browser.
ppg-js
ppg-js measures heart rate, pulse-rate variability, and respiration from a fingertip on a phone camera. It runs in the browser, has zero runtime dependencies, ships typed APIs with no UI, and includes a signal-quality gate that explains why it withholds a reading.
60-second overview
- Install the package or load its browser-global build.
- Create a
PPGinstance. - Listen for state, metrics, quality, beat, waveform, respiration, and error events.
- Call
start()from a user gesture so the browser can grant camera, wake-lock, and motion permissions. - Put a fingertip over the rear camera and flash, then wait through
SETTLINGforMEASURING. - Use readings only when
metrics.quality.goodistrue.
Every session can be exported and replayed offline through the same signal engine. The hosted HRV Spot Check is a working example.
What it reports
| Field | Meaning |
|---|---|
heartRate | Beats per minute, cross-checked between interval and spectral estimates |
ibi, rmssd, sdnn | Latest interval and variability over 60 seconds of accepted beats |
rmssdFloorMs | Estimated variability caused by the pipeline's own beat-timing noise |
respiration | Rate, confidence, and basis from beat timing, amplitude, and baseline modulation |
quality | A verdict with stable good, reason, and code fields |