Skip to main content
Read the 21 joints of every hand in each frame, over one WebSocket, with geopavlakos/hamer. Each hand comes back with 2D joints on the image and 3D joints in meters, so you can measure the hand itself, not only its picture. This guide draws each hand on a 4 s clip of hands tying a box, and detects a pinch from the 3D gap between thumb and index finger.
Three video frames with hand skeletons drawn over hands tying a cake box

Frames 9, 17, and 26 of the output. Red is a right hand, blue is a left hand.

1. Cut the clip

That writes 32 frames of 640 x 360 pixels from 24 s to 28 s of the video. Hands move fast, so this guide reads 8 frames per second. hamer allows up to 20.

2. Stream and detect a pinch

Python
The sample draws each hand’s bones on its frame, writes the frame to tracked/, and prints the thumb-to-index gap of every hand. A gap under 3 cm counts as a pinch.
Output
All 32 frames were read, with a median read of 31 ms. The session was open about 4 s, which bills $0.0034 at $3 / hour.

3. Read a hand

Look joints up by name with kpts_labels, not by a fixed index. The full schema is in world.pose.kpts.
A frame with no hands returns {"object": "world.pose.kpts", "items": []} with no kpts_labels. Check items before you read the labels. Hands also have no id: their order in items can change between frames, so match hands across frames by label and box position.

4. The first session after idle

When hamer has no running replica, session.create is refused while the Gateway starts one. The session gets an error event, then close 1013:
Wait retry_after seconds, then open a new session. In the first session after start-up, the first 4 reads took about 2 s each and 13 of 32 frames were dropped as busy. Later sessions read every frame. To avoid this at a live event, open a short session a few minutes before you need the model.

Webcam from the Browser

Run a session on a user’s camera.

Masks per Frame

Segment every frame by a text prompt.

Response Types

The world.pose.kpts schema in JSON, Pydantic, and Zod.

Realtime

Session lifecycle, close codes, and billing.