Control a slide deck with your hand. PresentoVision reads your webcam, tracks a hand with MediaPipe (21 landmarks, in real time), and turns simple gestures into keyboard shortcuts for whatever presentation app is in focus: PowerPoint, Google Slides, Canva, Keynote, LibreOffice Impress or a PDF viewer. A small always-on-top overlay shows what the system sees, and YOLOv8n adds person detection as scene context.
- Hands-free slide control: next / previous slide, pause, fullscreen and screenshot from one hand.
- Works with any app: it sends standard key presses (
Right,Left,Space,F5,Esc), so there are no plugins or per-app integrations. - Reliable triggering: a majority-vote buffer removes single-frame noise and a cooldown stops one gesture firing twice.
- Live HUD: raw vs. confirmed gesture, FPS, last action, slide counter, status and a cooldown bar, on a window that stays above your slides.
- Easy to tune: every threshold lives in
config/settings.py.
| Gesture | Hand | Action |
|---|---|---|
| Open palm | Right | Next slide |
| Open palm | Left | Previous slide |
| Fist | Either | Pause / resume autoplay (Space) |
| One finger (index) | Either | Save a screenshot |
| Two fingers (index + middle) | Either | Fullscreen on / off (alternates) |
| Three fingers (index + middle + ring) | Either | Quit the app |
The camera image is mirrored, so "Left" and "Right" refer to your own hands.
webcam frame ──► mirror
│
┌───────────┴─────────────┐
▼ ▼
YOLOv8n (every 4th frame) MediaPipe Hands
person boxes (overlay) 21 landmarks
│ ▼
│ FingerState [thumb, index, middle, ring, pinky]
│ ▼
│ Gesture.classify
│ ▼
│ GestureBuffer (majority vote)
│ ▼
│ cooldown ──► SlideController ──► key press (pyautogui)
│ │
└──────────► HUD renderer ◄┘
- Capture: OpenCV grabs a frame and mirrors it.
- Hand tracking: MediaPipe returns 21 landmarks and which hand it is.
FingerStatemarks each finger as extended or folded (fingertip above its PIP joint; the thumb uses horizontal displacement). - Classification: the five booleans map to a gesture. The thumb is ignored for "one finger" and "two fingers" so they are easy to make.
- Smoothing: a gesture only counts once it wins the majority (4 of the last 6 frames).
- Dispatch: after a 1 second cooldown,
SlideControllersends the matching key press withpyautogui. - Feedback: the HUD draws the landmarks, person boxes, state and a flash border on each action.
YOLOv8n is a visual aid; gesture recognition does not depend on it.
| Area | Tools |
|---|---|
| Hand tracking | MediaPipe Hands (legacy mp.solutions API) |
| Object detection | Ultralytics YOLOv8n |
| Video + HUD | OpenCV, NumPy |
| Input automation | PyAutoGUI |
| Always-on-top | OpenCV window property, pywin32 (Windows), wmctrl (Linux) |
| Quality | pytest, Ruff, GitHub Actions |
PresentoVision/
├── main.py ← entry point
├── requirements.txt ← runtime dependencies
├── requirements-dev.txt ← adds pytest and ruff
├── pyproject.toml ← pytest + ruff config
│
├── config/
│ ├── settings.py ← runtime tuning knobs (cooldown, FPS, paths …)
│ └── theme.py ← colors, fonts, gesture guide rows
│
├── core/
│ ├── gesture.py ← FingerState decoder + Gesture classifier
│ ├── buffer.py ← majority-vote smoothing buffer
│ └── controller.py ← SlideController (platform-aware keyboard actions)
│
├── ui/
│ ├── hud.py ← HUD renderer (side panel, landmarks, flash border)
│ └── topmost.py ← always-on-top window enforcement
│
├── app/
│ └── engine.py ← PresentoVision main loop + GestureEngine dispatcher
│
└── tests/ ← unit tests for gesture logic and smoothing
Requirements: Python 3.9 – 3.12 and a webcam.
git clone https://github.com/Ryzuuuu/PresentoVision.git
cd PresentoVision
python -m venv venv
# Windows: venv\Scripts\activate
# macOS/Linux: source venv/bin/activate
pip install -r requirements.txt- The first run downloads the YOLOv8n weights (
yolov8n.pt, about 6 MB) into the current directory. - Windows:
pywin32is installed automatically for stronger always-on-top behaviour. - Linux: optionally install
wmctrl(sudo apt install wmctrl) for the same effect. - macOS: allow your terminal under Privacy & Security for Camera and Accessibility (needed to send key presses).
MediaPipe is pinned below 0.10.30 because later releases removed the mp.solutions API this project uses.
python main.py- Open your presentation and put it in focus.
- The PresentoVision overlay opens in the top-right corner, always on top.
- Show your hand to the camera and use the gestures above.
- Press Q or Esc in the overlay window, or show three fingers, to quit.
Screenshots are saved to ~/Desktop/PresentoVision_Shots/ by default. Set the PRESENTOVISION_SHOTS_DIR environment variable (or edit SCREENSHOTS_DIR) to change the folder.
All knobs live in config/settings.py:
| Variable | Default | Effect |
|---|---|---|
COOLDOWN_SEC |
1.0 |
Min seconds between triggers |
CONFIRM_FRAMES |
6 |
Size of the majority-vote window (a gesture needs more than half of it) |
YOLO_SKIP |
4 |
Run YOLO every N frames |
MP_DETECT_CONF / MP_TRACK_CONF |
0.80 |
MediaPipe detection / tracking thresholds |
CAM_INDEX |
0 |
Which camera to use |
CAM_FPS |
60 |
Camera target FPS |
| Problem | Fix |
|---|---|
Could not open camera 0 |
Close other apps using the webcam, or set CAM_INDEX to another device. |
AttributeError: module 'mediapipe' has no attribute 'solutions' |
You have MediaPipe 0.10.30 or newer. Run pip install -r requirements.txt to get the pinned version. |
| Gestures fire twice or not at all | Raise CONFIRM_FRAMES / COOLDOWN_SEC, or improve lighting and keep your hand fully in frame. |
| Low FPS | Raise YOLO_SKIP, or lower CAM_W / CAM_H. |
| Key presses go to the wrong window | Click your presentation first so it has focus, then use gestures. |
pip install -r requirements-dev.txt
pytest # gesture classification + smoothing tests
ruff check . # lintCI runs both on every push and pull request.
Released under the MIT License.