ppg-js API reference
Reference for the PPG facade, events, methods, options, errors, engine, and exported types.
API reference
new PPG(options?)
The typed, headless camera facade. It renders no UI.
Events
| Event | Detail |
|---|---|
ready | Capture is initialized |
state | Finger-state transition and reason |
beat | Beat time, IBI, validity, quality, SQI, reason, and heart rate |
metrics | Current heart rate, HRV, diagnostics, and quality verdict |
quality | Per-window quality result |
waveform | Waveform sample on every frame |
respiration | Rate, confidence, and basis |
error | A typed PPGError |
Methods and getters
Methods: start(abortSignal?), stop(), destroy(), getMetrics(), getTachogram({ goodOnly, hrvOnly }), getSessionSummary(), exportDebugLog(), downloadDebugLog(prefix?), and getConfig().
Getters: state, capabilities, and engine.
new PPGMonitor(container, options?)
The callback-style class wrapped by PPG. container is accepted for compatibility and ignored. Callbacks are onReady, onState, onQualityUpdate, onSignalUpdate, onFrame, and onError. It also exposes getDebugLog(), copyDebugLogToClipboard(), getEngine(), and the video element.
Options
{
signal: {
windowSec: 5,
hopSec: 5,
contextSec: 3,
gridHz: 60,
hrSlewPerWindow: 8,
recoverMissedBeats: true,
cardiacBandLow: 0.75,
cardiacBandHigh: 4.0,
quality: {
minAcDc: 0.002,
maxArtifactRatio: 0.2,
minIbiCount60s: 8,
maxClippedFraction: 0.05,
maxMotion: 1.5,
minTemplateSqi: 0.6,
},
fingerState: {
settleSec: 6,
driftEnterFraction: 0.03,
driftExitFraction: 0.06,
presence: { minRed: 60, minRedShare: 0.5 },
},
respiration: true,
templateSqi: true,
},
camera: {
width: { ideal: 640 },
height: { ideal: 480 },
frameRate: { ideal: 60 },
facingMode: 'environment',
torch: true,
lockExposure: 'measuring',
zoom: null,
},
roi: { widthFraction: 0.3, heightFraction: 0.3 },
wakeLock: true,
motion: false,
debug: {
persistLastSession: false,
includeUserAgent: false,
sampleCap: 36000,
},
video: null,
}lockExposure accepts measuring, start, or never. See EngineOptions in the package types for every signal option.
Errors
start() rejects with a PPGError. Codes are insecure_context, unsupported, permission_denied, no_camera, camera_busy, overconstrained, aborted, and unknown. Each error has a guidance sentence suitable for display.
PpgEngine
Import from @sontakey/ppg-js/engine. engine.push({ t, r, g, b, clipped?, motion? }) returns { state, stateChanged, stateReason, present, waveform, window }. window is null except every hopSec.
Types
The package is typed. Event details, metrics, options, quality results, beats, session summaries, HRV reports, engine samples, and errors are exported through the package entry points.