bookswipe

English | 한국어

Hands-free page turning with nothing but your webcam.

Swipe your hand. Turn the page. Keep reading.

Quick Start · Gestures · Permissions · Troubleshooting

---

What Is Bookswipe?

Bookswipe is a tiny Python app that detects hand swipes through your webcam and sends keyboard arrow presses.

It is built for simple hands-free reading:

• Swipe your right hand to the left → press Right Arrow
• Swipe your left hand to the right → press Left Arrow
• Press ESC → quit

No account. No server. No setup dashboard. Just one Python file.

Quick Start

Step 1: Clone or open the project

If you already have this project locally:

cd /Users/hani/Projects/bookswipe

If you downloaded it somewhere else:

cd path/to/bookswipe

Step 2: Check Python

python3.12 --version

Python 3.12 is recommended and tested. The dependency versions in requirements.txt are pinned from a working Python 3.12.13 setup.

If Python is not installed on macOS, install it with Homebrew:

brew install python@3.12

Step 3: Create a virtual environment

python3.12 -m venv .venv

Step 4: Activate it

source .venv/bin/activate

You should now see (.venv) at the beginning of your terminal prompt.

Step 5: Install dependencies

python -m pip install --upgrade pip
pip install -r requirements.txt

Step 6: Run Bookswipe

python main.py

That's it. A camera window should open.

Gestures

Gesture	Result
Right hand swipes left	Presses Right Arrow
Left hand swipes right	Presses Left Arrow
ESC in the camera window	Quits the app

Tip: keep your hand visible to the webcam and make a clear horizontal swipe.

macOS Permissions

Bookswipe needs two macOS permissions because it uses your webcam and sends keyboard input.

Camera

Open:

System Settings > Privacy & Security > Camera

Allow the app you use to run python main.py.

Common examples:

• Cursor
• VSCode
• Terminal
• iTerm

Accessibility

Open:

System Settings > Privacy & Security > Accessibility

Allow the app you use to run python main.py.

Common examples:

• Cursor
• VSCode
• Terminal
• iTerm

After changing permissions, fully quit and reopen your terminal or editor.

iPhone Continuity Camera

If your iPhone camera opens instead of the MacBook camera, macOS is selecting Continuity Camera as the default webcam.

To use the MacBook camera, turn off Continuity Camera on your iPhone:

iPhone Settings > General > AirPlay & Continuity > Continuity Camera

Then quit and reopen Cursor, VSCode, Terminal, or iTerm before running Bookswipe again.

Re-run Later

After the first setup, you only need:

cd path/to/bookswipe
source .venv/bin/activate
python main.py

Troubleshooting

The camera window does not open

Check macOS camera permission:

System Settings > Privacy & Security > Camera

Also close other apps that may already be using the camera.

Hands are detected, but arrow keys do not work

Check macOS Accessibility permission:

System Settings > Privacy & Security > Accessibility

Then fully quit and reopen Cursor, VSCode, Terminal, or iTerm.

ModuleNotFoundError

Your virtual environment is probably not active, or dependencies were not installed.

source .venv/bin/activate
pip install -r requirements.txt
python main.py

zsh: command not found: python

Use python3.12 directly:

python3.12 main.py

Or activate the virtual environment first:

source .venv/bin/activate
python main.py

How It Works

Bookswipe uses:

• opencv-python to read webcam frames
• mediapipe to detect hands
• pyautogui to press arrow keys

The app keeps a short history of each hand's horizontal position. When the movement passes the swipe threshold, it sends the matching arrow key and plays sound.wav.

Project Shape

bookswipe/
├── main.py
├── sound.wav
├── requirements.txt
├── README.md
└── README.ko.md

One file runs the app. The README files explain how to run it.