README.md

---
title: Video Human Fall Detection With TimeSformer
emoji: 🌍
colorFrom: blue
colorTo: pink
sdk: gradio
sdk_version: 5.25.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: Fall detector with TimeSformer
---

# Video Human Detection Demo using TimeSformer

This is a Hugging Face Spaces demo project that uses TimeSformer – a video transformer model – for video-based human detection (action recognition). In this demo, we use the pre-trained model `microsoft/timesformer-base-finetuned-k400` from Hugging Face, which has been fine‑tuned on the Kinetics‑400 dataset. The model is capable of classifying a video into one of 400 human action categories.

## Overview

- **Model:** We use a TimeSformer model (`microsoft/timesformer-base-finetuned-k400`) to classify video clips.
- **Feature Extractor:** The demo employs the Hugging Face `AutoFeatureExtractor` for video to process and prepare video frames.
- **Inference:** The model outputs a set of predicted action labels with scores. These predictions help detect human actions in the video.
- **Interface:** Built with Gradio, the demo lets the user upload a video file. The application extracts frames from the video, processes them with the model, and displays the top action predictions.

## Setup and Deployment

1. **Requirements:** See `requirements.txt` for the list of required packages.
2. **Run Locally:** You can run the demo locally using:
    ```bash
    python app.py
    ```
3. **Deploy on Hugging Face Spaces:**  
   Simply push these files to a new repository under HF Spaces. The app is designed to run with ZeroGPU if available and it is fully compatible with CPU-only environments.

## Notes

- **Video Preprocessing:** The demo extracts frames using OpenCV and passes them to the feature extractor. The number of frames and the resolution are set to default values that can be adjusted.
- **Model Performance:** TimeSformer is computationally heavy – for real-time use, consider using a smaller or distilled variant, or reduce the number of frames processed.
- **ZeroGPU Support:** The app uses the `@spaces.GPU` decorator (from the HF Spaces ZeroGPU environment) if available; otherwise, it will run on CPU.

Enjoy testing human detection in videos with this demo!