SmartSlide AI

A browser-based, gesture-controlled presentation player. It uses your webcam and MediaPipe's Gesture Recognizer (running entirely on-device, in JavaScript) to detect hand gestures and drive slide navigation — no backend, no uploads of your video anywhere.

Everything runs client-side. The only network calls at runtime are to fetch the MediaPipe model file and the pdf.js library from their public CDNs the first time the page loads (after that, browsers typically cache them).

---

1. Files in this project

smartslide-ai/
├── index.html      ← page structure (slide viewer, camera panel, settings)
├── style.css       ← all visual styling
├── script.js       ← camera + gesture recognition + slide logic
└── README.md       ← this file (also doubles as Hugging Face Space config)

That's it — three files make the app, and this README's top section (the part between the --- lines) is what tells Hugging Face how to run the Space. You do not need Node.js, Python, or any build step.

---

2. Gesture reference

Why a "master switch"? Requiring the ✌️ Victory gesture before any navigation gesture is armed means the app won't start flipping slides just because you're talking with your hands. Show ✌️ once to arm it, and again to disarm it. The on-screen "Smart Control" chip and manual buttons work as a backup at all times.

Every gesture needs to be held steady for a fraction of a second before it triggers (this is the "sensitivity" setting), and after any action there's a short cooldown before the next one can fire, so one motion can't skip multiple slides.

---

3. Running it locally

Browsers block camera access and ES module imports on file:// pages, so you need a tiny local web server — no installation of frameworks required.

Option A — Python (already on most machines):

cd smartslide-ai
python3 -m http.server 8080

Then open http://localhost:8080 in Chrome or Edge.

Option B — Node.js:

cd smartslide-ai
npx serve .

Option C — VS Code: Install the "Live Server" extension, right-click index.html, choose "Open with Live Server."

⚠️ Use Chrome, Edge, or another Chromium-based browser for the most reliable WebGL/GPU support that MediaPixe's gesture model relies on. Safari and Firefox generally work too, but slightly slower (CPU delegate).

On first load, click "Enable Camera" and allow the browser's camera permission prompt. Grant it over localhost or https:// — camera access is blocked on plain http:// for any address other than localhost.

---

4. Deploying to Hugging Face Spaces

Hugging Face Spaces can host this as a Static Space — it just serves the files as-is, which is exactly what this project needs.

Option A — via the website (easiest)

1. Go to https://huggingface.co/new-space
2. Pick a name, choose Static as the Space SDK, and create it.
3. On the new Space's page, click "Files" → "Add file" → "Upload files".
4. Upload index.html, style.css, script.js, and README.md (this file — its front matter is what tells the Space to use the static SDK; if you already picked "Static" when creating the Space, Hugging Face will keep using its own generated README config unless you overwrite it with this one, which is fine either way).
5. Wait for the Space to build (a few seconds for a static Space) and open the app from the Space's "App" tab.

Option B — via git

git clone https://huggingface.co/spaces/<your-username>/<your-space-name>
cd <your-space-name>
# copy index.html, style.css, script.js, README.md into this folder
git add .
git commit -m "Add SmartSlide AI"
git push

Important note about camera permissions on Spaces

Hugging Face Spaces are served over HTTPS, so camera access works exactly like it does on any other secure website — no extra configuration needed. The first time a visitor opens your Space, their browser will ask them to allow camera access.

---

5. Using the app

1. Upload slides — click "Choose files" (or the "Upload" button in the stage controls) and select image files (.jpg, .png, etc.) and/or a .pdf deck. PDF pages are automatically rendered as individual slides, in order.
2. Enable the camera — click "Enable Camera" in the side panel.
3. Arm Smart Control — click the "Smart Control" chip at the top, or show a ✌️ Victory sign to the camera.
4. Navigate — swipe your hand left/right, or use the on-screen ‹ Prev / Next › buttons at any time as a manual backup.
5. Open the ⚙ Settings panel to adjust gesture sensitivity, cooldown time, pick a different camera, or turn individual gestures on/off.

---

6. Testing instructions

You don't need slides loaded to test gesture recognition — the camera panel, skeleton overlay, detected-gesture readout, and confidence bar all work as soon as the camera is on.

1. Hand detection sanity check: Enable the camera and hold your hand up. You should see an amber/blue skeleton overlay tracking your hand in the camera preview, and the "Confidence" bar in the top bar should rise.
2. Arm/disarm: Show a ✌️ Victory sign and hold it steady. After roughly half a second the "Smart Control" chip should switch to ON and a "SMART CONTROL ON" flash should appear over the slide area. Show ✌️ again to disarm it.
3. Swipe navigation: With Smart Control armed and at least two slides uploaded, move your open hand steadily to the right across the camera's view — the slide should advance, with a "NEXT ▸" flash. Swipe left to go back.
4. Pause: Show an open palm 🖐️ — the "Paused" row in the "Modes" panel should switch to "Yes," and swiping/fist/pointer gestures should stop doing anything until you show 🖐️ again.
5. Presentation mode + confirmation: Make a fist ✊ — presentation mode starts immediately. Make a fist ✊ again — instead of stopping right away, a banner appears asking you to show 👍 to confirm. Show 👍 to actually stop it, or click "Cancel" in the banner.
6. Pointer mode: Point up ☝️ — a small amber dot should appear on the slide, following your index fingertip. Point up again to turn it off.
7. Settings: Open the settings drawer and drag "Gesture cooldown" to its minimum — gestures should now be able to fire more rapidly. Uncheck a gesture (e.g. "Swipe next / previous") and confirm swiping no longer changes slides while it's unchecked.
8. Manual fallback: With the camera off entirely, confirm the ‹ Prev / Next › buttons, "Start/Stop Presentation" buttons, and the "Smart Control" / "Presentation" chips still work by mouse click, and that the left/right arrow keys change slides.

---

7. How the gesture pipeline works (for the curious)

• Hand detection & static gestures — MediaPipe's GestureRecognizer (from @mediapipe/tasks-vision) runs on every video frame and returns 21 hand landmarks plus a built-in gesture classification (Closed_Fist, Open_Palm, Pointing_Up, Thumb_Up, Victory, etc.) with a confidence score.
• Debouncing — a gesture must be classified consistently for several consecutive frames (the "hold" count, tuned by the sensitivity setting) before it's treated as intentional, and a cooldown timer blocks new actions for a short window afterward.
• Swipes are detected separately from static gestures: the wrist landmark's horizontal position is tracked over a short rolling time window, and a swipe fires once it moves far enough, fast enough, in one direction.
• Everything is on-device. No frame, image, or slide ever leaves the browser — the only external requests are the one-time downloads of the MediaPipe model/WASM runtime and the pdf.js library from their CDNs.

---

8. Troubleshooting