README.md

metadata

title: PulseCam
emoji: 💓
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
license: mit
short_description: Contactless heart rate monitoring via webcam

PulseCam 💓

Your Pulse, From Your Camera

🎯 The Problem

Measuring heart rate traditionally requires dedicated hardware like smartwatches, chest straps, or pulse oximeters. This limits accessibility for quick, everyday health monitoring, especially for telehealth integrations or fitness apps where users might not have specialized devices on hand.

✨ What PulseCam Does

PulseCam turns your standard webcam into a contactless heart rate monitor. Using remote photoplethysmography (rPPG), it detects micro-variations in skin color caused by blood flow with each heartbeat.

Simply sit in front of your camera, and PulseCam tracks your face, isolates the optimal regions of interest (cheeks), and processes the subtle color changes in real-time to calculate your heart rate (BPM).

🛠️ Tech Stack & Core Libraries

• Frontend: React, TypeScript, Vite, Framer Motion, WebGL (for stunning shader backgrounds)
• Backend: Python, FastAPI, WebSockets
• Core Models & Algorithms:
  • MediaPipe FaceLandmarker: Real-time facial landmark detection to isolate stable regions of interest (forehead + cheeks).
  • SciPy & NumPy: 5 parallel rPPG extractors (Green, CHROM, POS, GR, GRGB), background-reference exposure cancellation, 6th-order Butterworth bandpass (0.65–4.0 Hz), Welch's PSD with Harmonic Product Spectrum + parabolic peak interpolation, autocorrelation with global-peak detection, and artifact-aware fusion across methods.

🚀 Live Demo

Try it out directly in your browser without installing anything! 👉 PulseCam on Hugging Face (or view the Space)

⚙️ Installation & Local Setup

Prerequisites

• Node.js (via Bun or npm)
• Python 3.11+

Steps

1. Clone the repository:

   git clone git@github.com:volfiros/pulsecam.git
   cd pulsecam
   

2. Start the Backend:

   cd backend
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   uvicorn main:app --reload
   

3. Start the Frontend:

   cd frontend
   bun install
   bun run dev
   

4. Open http://localhost:5173 in your browser.

📌 Best Results

Webcam rPPG is sensitive to ambient conditions. For accurate readings:

• Sit in steady, even lighting (face a window or a stable lamp). Avoid overhead fluorescents or PWM-flickering LEDs.
• Hold still for the first ~15 seconds while the algorithm calibrates against ambient noise.
• On Apple silicon, Continuity Camera (iPhone as webcam) dramatically outperforms the built-in MacBook camera — the iPhone exposes manual exposure controls, which most webcams (including M-series Macs in Chrome) do not.

📈 Future Improvements

• Motion Artifact Reduction: Implement better independent component analysis (ICA) to separate motion from the pulse signal.
• Mobile Optimization: Enhance camera access and processing efficiency on mobile devices.
• HRV (Heart Rate Variability): Extract inter-beat intervals to measure stress levels.

See the Architecture Document for a deep dive into how the signal processing pipeline works.