O-Hands User Guide

Getting Started

Quick Start (5 Minutes)

1. Launch O-Hands and allow camera access when prompted
2. Select your webcam from the dropdown in the header
3. Position your hand in front of the camera — you should see a skeleton overlay
4. Select a MIDI device in Settings → MIDI
5. Create a mapping: Click + Add in the Mappings panel
6. Choose a feature (e.g., Palm Y) and a MIDI CC number
7. Move your hand — your DAW should respond!

System Requirements

Interface Overview

Main Window Layout

┌─────────────────────────────────────────────────────────┐
│  O-Hands          [Camera ▼] [Refresh]     [⚙ Settings] │
├─────────────────────────────────────────────────────────┤
│                                        │                │
│                                        │   SETTINGS     │
│         HAND TRACKING AREA             │    PANEL       │
│      (Camera + Hand Skeleton)          │                │
│                                        ├────────────────┤
│                                        │                │
│                                        │   PRESETS      │
│                                        │    PANEL       │
├────────────────────────────────────────┴────────────────┤
│                    MAPPINGS PANEL                       │
│         Direct Mappings    |    Gesture Mappings        │
└─────────────────────────────────────────────────────────┘

Panel Overview

Camera Setup

Selecting a Camera

1. Click the camera dropdown in the header
2. Select your webcam from the list
3. Click Refresh if your camera doesn't appear

Optimizing Tracking

For best results:

• Lighting: Face a light source (window or lamp) — avoid backlight
• Background: Plain backgrounds work best
• Distance: Keep your hand 1-3 feet from the camera
• Position: Center your hand in the frame

Settings for Better Tracking

Creating Direct Mappings

Direct mappings connect a single hand feature to a MIDI/OSC output.

Creating a Mapping

1. Click + Add in the Direct Mappings section
2. Select Left or Right hand
3. Choose a Feature from the dropdown
4. Select an Output Type (CC, Note, Pitch Bend, Aftertouch, or OSC)
5. Configure the output settings
6. Click Save

Available Features

Palm Position

Finger Curl (0 = straight, 1 = curled)

Hand State

Rotation

Velocity

Output Types

CC (Control Change)

Standard MIDI continuous controller messages.

• CC Number: 0-127 (check your synth's MIDI implementation)
• Range: Set min/max output values (default 0-127)
• Response Curve: Shape the output response
• Channel: MIDI channel 1-16

Note

Trigger MIDI notes based on hand position.

• Mode: Trigger (single note) or Repeater (continuous)
• Threshold: Feature value that triggers the note
• Note Source: Fixed note, feature-based, or random from scale
• Velocity: Fixed, trigger speed, or feature-based

Pitch Bend

14-bit pitch bend messages for smooth pitch control.

• Neutral Zone: Deadzone around center (prevents unwanted bend)
• Curve Strength: Response curve intensity

Aftertouch

Channel pressure messages for expressive control.

• Range: Min/max pressure values
• Response Curve: Shape the pressure response

OSC

Send Open Sound Control messages over UDP.

• Address: OSC address pattern (e.g., /synth/filter/cutoff)
• IP: Target IP address (use 127.0.0.1 for local)
• Port: UDP port number (common: 9000, 8000, 57120)
• Value Type: Float or Integer

Response Curves

Tracking Loss Behavior

Configure what happens when your hand leaves the camera view:

Settings:

• Timeout: How long before hand is considered "lost" (50-500ms)
• Fade Duration: Time to reach the target value
• Re-entry Blend: Smoothing when hand returns

Creating Gesture Mappings

Gesture mappings let you capture specific hand poses and interpolate between them for expressive control.

How It Works

1. Capture 2-10 hand poses (called "anchors")
2. Assign output values to each anchor
3. Perform: O-Hands smoothly interpolates between anchors based on your current hand position

Creating a Gesture Mapping

1. Click + Add in the Gesture Mappings section
2. Select Left or Right hand
3. Click Capture Pose
4. Hold your hand steady during the 3-second countdown
5. Repeat for each pose you want to capture
6. Click Add Output to define what this gesture controls
7. Set target values for each anchor
8. Click Save

Anchor Management

• Single-click a thumbnail to edit its target values
• Double-click to view an enlarged preview
• Drag thumbnails to reorder
• Delete anchors you don't need

Gesture Settings

Example: Filter Control with Hand Open/Closed

1. Capture Pose 1: Hand fully open → Set filter cutoff to 127
2. Capture Pose 2: Hand closed (fist) → Set filter cutoff to 0
3. Capture Pose 3: Half-open hand → Set filter cutoff to 64
4. Move your hand between poses — the filter smoothly follows!

MIDI Configuration

Selecting a MIDI Device

1. Open Settings (gear icon)
2. Find the MIDI section
3. Select your MIDI output from the dropdown
4. The status shows "Connected to: [device name]"

Testing MIDI Output

Click Test CC to send a test message (CC#1, value 64, Channel 1). If your DAW receives it, MIDI is working.

Virtual MIDI Drivers

If you don't have a hardware MIDI interface, use a virtual MIDI driver:

Refreshing MIDI Devices

Click the refresh button next to the MIDI dropdown if you connect a new device while O-Hands is running.

OSC Configuration

O-Hands can send OSC messages to creative applications like:

• Max/MSP
• TouchDesigner
• Pure Data
• SuperCollider
• Resolume
• Processing

Setting Up OSC

1. Create a mapping with OSC output type
2. Set the Address (e.g., /hand/x)
3. Set the Target IP (use 127.0.0.1 for same computer)
4. Set the Port (must match your receiving app)
5. Choose Value Type (float or integer)

Common OSC Ports

Presets

Presets save all your mappings so you can switch between configurations.

Saving a Preset

1. Configure your mappings
2. Click Save As in the Presets panel
3. Enter a name
4. Click Save

Loading a Preset

Click any preset in the list to load it. If you have unsaved changes, you'll be asked to confirm.

Managing Presets

Performance Mode

O-Hands offers three view modes for different situations:

Full UI (Cmd/Ctrl+1)

All panels visible — for setup and configuration.

Performance Mode (Cmd/Ctrl+2)

Minimal interface — for live performance.

Toggle what's visible:

• Cmd+C: Show/hide camera
• Cmd+H: Show/hide hand skeleton
• Cmd+M: Show/hide mappings panel

Blackout Mode (Cmd/Ctrl+3)

App hidden — mappings continue running. Perfect for live shows where you don't want the app visible.

Overlay Mode (Cmd/Ctrl+Shift+O)

Combines fullscreen + transparency + click-through. The app floats over other windows and clicks pass through — great for overlaying on video or other apps.

Customizing the Display

Background Color

Choose from preset colors or pick a custom color:

1. Open Settings → Appearance
2. Click a color swatch, or
3. Click the color picker for custom colors
4. Recent colors are saved automatically

Skeleton Appearance

Customize the hand visualization:

Transparency Mode

Make the app window see-through:

1. Enable Transparency in Settings → Appearance
2. Use Cmd/Ctrl+Shift+T to toggle on/off
3. Enable Click-through to let mouse clicks pass to apps behind

Fullscreen

• Cmd/Ctrl+Shift+F: Toggle fullscreen
• Settings → Display: Choose which monitor for fullscreen
• Launch in Fullscreen: Start the app fullscreen automatically

Keyboard Shortcuts

Global Shortcuts

Performance Mode

Troubleshooting

Camera Issues

Camera not detected

• Check if another app is using the camera
• Click the Refresh button next to the camera dropdown
• Try unplugging and reconnecting USB cameras

Poor tracking

• Improve lighting (face a light source)
• Use a plain background
• Enable Video Enhancement in Settings
• Move closer to the camera

Jittery output

• Increase Smoothing in Settings
• Reduce sudden hand movements
• Check lighting conditions

MIDI Issues

No MIDI output

• Verify your MIDI device is connected
• Click Refresh in the MIDI section
• Check that your DAW is receiving on the correct channel
• Use Test CC to verify the connection

Wrong values

• Check the output range in your mapping
• Try a different response curve
• Verify the CC number matches your synth

OSC Issues

App not receiving OSC

• Verify the IP address (use 127.0.0.1 for local)
• Check the port number matches your app
• Ensure no firewall is blocking UDP
• Try a different port if 9000 is in use

Performance Issues

Low frame rate

• Close other camera-using apps
• Reduce video resolution in your camera settings
• Close resource-intensive applications

License Issues

License won't activate

• Check your internet connection
• Verify the license key format (OUA-XXXX-XXXX-XXXX)
• Contact [email protected] if problems persist

Offline activation

• Export your Machine ID from Settings → License
• Email it to [email protected]
• Import the license file you receive