README.md

---
license: apache-2.0
pipeline_tag: video-classification
---

# Visual Chronometer

**Visual Chronometer** is a model that predicts the **Physical Frames Per Second (PhyFPS)** of a video — the true temporal scale implied by its visual motion, independent of container metadata.

- **Paper:** [The Pulse of Motion: Measuring Physical Frame Rate from Visual Dynamics](https://huggingface.co/papers/2603.14375)
- **Project Page:** [https://xiangbogaobarry.github.io/Pulse-of-Motion/](https://xiangbogaobarry.github.io/Pulse-of-Motion/)
- **Repository:** [https://github.com/taco-group/Pulse-of-Motion](https://github.com/taco-group/Pulse-of-Motion)

## Installation

```bash
git clone https://github.com/taco-group/Pulse-of-Motion.git
cd Pulse-of-Motion/inference
pip install -r requirements.txt
```

## Usage

### Predict PhyFPS for a single video

```bash
cd inference
python predict.py --video_path path/to/your_video.mp4
```

### Predict PhyFPS for a directory of videos

```bash
cd inference
python predict.py --video_dir path/to/videos/ --output_csv results.csv
```

## Citation

```bibtex
@article{gao2026pulse,
  title={The Pulse of Motion: Measuring Physical Frame Rate from Visual Dynamics},
  author={Gao, Xiangbo and Wu, Mingyang and Yang, Siyuan and Yu, Jiongze and Taghavi, Pardis and Lin, Fangzhou and Tu, Zhengzhong},
  journal={arXiv preprint arXiv:2603.14375},
  year={2026}
}
```