Signal quality in ppg-js
Learn the ppg-js quality contract, stable reason codes, signal indices, and withheld-reading behavior.
Signal quality contract
quality.good is true only when every check below passes. Checks run in this order. reason and code identify the first failure.
| Order | Check | Failure code |
|---|---|---|
| 1 | fingerState === 'MEASURING' | no_finger, settling |
| 2 | Clipped-pixel fraction is 5% or less | saturated |
| 3 | Motion is below the threshold when a source is attached | motion |
| 4 | Pulsatile AC/DC is at least 0.2% | weak_pulse |
| 5 | No more than 20% of candidate intervals are rejected over 60 seconds | irregular |
| 6 | At least 8 accepted intervals exist over 60 seconds | collecting |
| 7 | Median template correlation is at least 0.6 | morphology |
| 8 | Interval and spectral heart rate agree within 25% | double_count, missed_beats, fft_disagree |
heartRate, rmssd, and sdnn are 0 whenever quality.good is false. heartRateRaw remains populated.
Withheld readings
ppg.addEventListener('metrics', ({ detail: metrics }) => {
if (!metrics.quality.good) {
console.log(metrics.quality.code, metrics.quality.reason);
return;
}
renderReading(metrics);
});The contract prevents a UI from accidentally presenting an untrusted value as a measurement.
Signal quality indices
Every window includes metrics.sqi:
| Field | Definition |
|---|---|
score | 0 to 1 geometric mean of bounded sub-scores |
skewness, kurtosis | Shape statistics of the bandpassed pulse |
perfusion | Pulsatile amplitude divided by DC, as a percentage |
relativePower, snrDb | Cardiac-band power over total power |
zeroCrossingRate | Zero crossings per second of the bandpassed pulse |
templateCorrelation | Median beat correlation with the mean beat |
detectorAgreement | Agreement between interval and spectral heart rates |
artifactRatio, clippedFraction, motion | Quality-gate inputs |
Each beat and tachogram point also carries sqi, its template correlation. The composite score supports ranking and display. The accept or reject decision remains quality.good.