README.md

metadata

title: PhysMamba rPPG – Real-Time Heart Rate
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: true

PhysMamba rPPG – Real-Time Heart Rate Estimation

This project is a Hugging Face Spaces demo for real-time remote photoplethysmography (rPPG) using PhysMamba, built on top of the rPPG-Toolbox.

It allows users to:

Detect heart rate using a live webcam feed
Upload recorded videos to extract rPPG/BVP heart-rate signals
Visualize pulse waveform, heart rate trends, ROI heatmaps
Download a ZIP file and run everything locally if webcam access is blocked

---

Live Demo Link

Once deployed, your Hugging Face Space will be available at:

https://huggingface.co/spaces/swetchareddytukkani/demo-space

If your browser blocks camera access (Safari/iOS or corporate networks), switch to Upload Video Mode or download the ZIP to run locally.

---

Project Structure

demo-space/
 ├── app.py                 # Main Gradio interface
 ├── requirements.txt       # Dependencies for automatic install
 ├── models/                # Pretrained PhysMamba checkpoint(s)
 └── README.md

---

How to Use the App

1. Live Camera Mode

1. Click “Live Webcam”
2. Select a model from the dropdown
3. Allow camera permission
4. The interface will show:
   • Face detection + ROI selection
   • Real-time BVP signal extraction
   • Heart rate (BPM) estimation

Note: If the webcam doesn’t load, use “Upload Video” instead.

---

2. Video Upload Mode

1. Click “Upload Video”
2. Upload a face video (.mp4, .mov, .avi, .mkv)
3. Select desired model + FPS + ROI
4. Click Start Processing
5. The app will display:
   • Heart rate vs. time
   • Raw and filtered rPPG/BVP signal
   • Optional ground-truth overlay (if available)
   • Downloadable CSV + PNG results

---

Local Usage (ZIP Included)

Because some browsers or Spaces environments block webcam access, you can run this locally.

Steps to Run Locally:

# 1. Download PhysMamba.zip from the Hugging Face Space
# 2. Extract it and open a terminal inside the folder

pip install -r requirements.txt
python app.py

Then open your browser and go to:

http://127.0.0.1:7860

---

System Requirements

Component	Hugging Face (CPU)	Local (optional GPU)
Python	3.9 / 3.10	3.9+
Torch	CPU build	CUDA 11.8+ (if using GPU)
RAM	4 GB minimum	8 GB+ recommended

---

Reference

@inproceedings{luo2024physmamba,
  title={PhysMamba: Efficient remote physiological measurement with SlowFast temporal difference mamba},
  author={Luo, Chaoqi and Xie, Yiping and Yu, Zitong},
  booktitle={Chinese Conference on Biometric Recognition},
  pages={248--259},
  year={2024},
  organization={Springer}
}

@article{liu2022rppg,
  title={rPPG-Toolbox: Deep Remote PPG Toolbox},
  author={Liu, Xin and Narayanswamy, Girish and Paruchuri, Akshay and Zhang, Xiaoyu and Tang, Jiankai and Zhang, Yuzhe and Wang, Yuntao and Sengupta, Soumyadip and Patel, Shwetak and McDuff, Daniel},
  journal={arXiv preprint arXiv:2210.00716},
  year={2022}
}

---