The MediaPipe Hand Landmarker task lets you detect the landmarks of the hands in an image.
You can use this task to locate key points of hands and render visual effects on
them. This task operates on image data with a machine learning (ML) model as
static data or a continuous stream and outputs hand landmarks in image
coordinates, hand landmarks in world coordinates, and handedness (left or right
hand) of multiple detected hands.
[Open in Web Demos](https://google-ai-edge.github.io/mediapipe-samples-web/#/vision/hand_landmarker)[Edit in StackBlitz](https://stackblitz.com/github/google-ai-edge/mediapipe-samples-web?file=src/tasks/hand-landmarker.ts)
## Quickstart
Install the SDK for your platform,
[prepare input data](https://developers.google.com/edge/mediapipe/solutions/prepare_data.md.txt#vision), choose a
running mode, and run inference.
### Web
npm`npm install @mediapipe/tasks-vision`[Web demo](https://google-ai-edge.github.io/mediapipe-samples-web/#/vision/hand_landmarker)·[Edit in StackBlitz](https://stackblitz.com/github/google-ai-edge/mediapipe-samples-web?file=src/tasks/hand-landmarker.ts)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_web.md.txt)
#### Image
`IMAGE`Stateless · single frameSynchronous call on independent still images. Resets temporal tracking state on every call.
```typescript
import { FilesetResolver, HandLandmarker } from "@mediapipe/tasks-vision";
const vision = await FilesetResolver.forVisionTasks(
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(vision, {
baseOptions: { modelAssetPath: "hand_landmarker.task", delegate: "GPU" },
runningMode: "IMAGE",
numHands: 2,
});
// Synchronous single-frame call (stateless across images)
const image = document.getElementById("image") as HTMLImageElement;
const result = handLandmarker.detect(image);
```
#### Video
`VIDEO`Every frame · no dropsSynchronous tracking across decoded video frames with monotonic timestamps. Processes every frame in order and never drops frames.
```typescript
import { FilesetResolver, HandLandmarker } from "@mediapipe/tasks-vision";
const vision = await FilesetResolver.forVisionTasks(
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(vision, {
baseOptions: { modelAssetPath: "hand_landmarker.task", delegate: "GPU" },
runningMode: "VIDEO",
numHands: 2,
});
// Synchronous across decoded frames with monotonic timestamps (never drops frames)
for (const { frame, timestampMs } of decodedVideoFrames) {
const result = handLandmarker.detectForVideo(frame, timestampMs);
}
```
#### Livestream
`VIDEO + rAF`Live camera · latest frameWeb tasks run synchronously---pair `runningMode: "VIDEO"` with `requestAnimationFrame` so each paint inspects only the latest camera frame (skipping intermediate frames when busy).
```typescript
import { FilesetResolver, HandLandmarker } from "@mediapipe/tasks-vision";
const vision = await FilesetResolver.forVisionTasks(
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
// On Web, live camera loops pair runningMode: "VIDEO" with requestAnimationFrame
const handLandmarker = await HandLandmarker.createFromOptions(vision, {
baseOptions: { modelAssetPath: "hand_landmarker.task", delegate: "GPU" },
runningMode: "VIDEO",
numHands: 2,
});
const video = document.getElementById("webcam") as HTMLVideoElement;
video.srcObject = await navigator.mediaDevices.getUserMedia({ video: true });
await video.play();
let lastVideoTime = -1;
function renderLoop() {
if (video.readyState >= 2 && video.currentTime !== lastVideoTime) {
lastVideoTime = video.currentTime;
const result = handLandmarker.detectForVideo(video, performance.now());
console.log(result.landmarks, result.handedness);
}
requestAnimationFrame(renderLoop);
}
renderLoop();
```
### Android (Kotlin)
Gradle`implementation("com.google.mediapipe:tasks-vision:latest.release")`[Sample code](https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/hand_landmarker/android)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_android.md.txt)
#### Image
`IMAGE`Stateless · single frameSynchronous call on independent still images. Resets temporal tracking state on every call.
```kotlin
import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage
import com.google.mediapipe.tasks.core.BaseOptions
import com.google.mediapipe.tasks.vision.core.RunningMode
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarker
val baseOptions = BaseOptions.builder()
.setModelAssetPath("hand_landmarker.task")
.build()
val options = HandLandmarker.HandLandmarkerOptions.builder()
.setBaseOptions(baseOptions)
.setRunningMode(RunningMode.IMAGE)
.setNumHands(2)
.build()
val handLandmarker = HandLandmarker.createFromOptions(context, options)
// Synchronous single-image call (no temporal tracking across calls)
val mpImage = BitmapImageBuilder(bitmap).build()
val result = handLandmarker.detect(mpImage)
```
#### Video
`VIDEO`Every frame · no dropsSynchronous tracking across decoded video frames with monotonic timestamps. Processes every frame in order and never drops frames.
```kotlin
import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage
import com.google.mediapipe.tasks.core.BaseOptions
import com.google.mediapipe.tasks.vision.core.RunningMode
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarker
val baseOptions = BaseOptions.builder()
.setModelAssetPath("hand_landmarker.task")
.build()
val options = HandLandmarker.HandLandmarkerOptions.builder()
.setBaseOptions(baseOptions)
.setRunningMode(RunningMode.VIDEO)
.setNumHands(2)
.build()
val handLandmarker = HandLandmarker.createFromOptions(context, options)
// Synchronous: processes every frame in order with monotonic timestamps (no frame drops)
val mpImage = BitmapImageBuilder(frameBitmap).build()
val result = handLandmarker.detectForVideo(mpImage, frameTimestampMs)
```
#### Livestream
`LIVE_STREAM`Async · drops frames when busyAsynchronous camera pipeline with a result callback. Automatically drops incoming frames when busy so results stay current with low latency.
```kotlin
import android.os.SystemClock
import android.util.Log
import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage
import com.google.mediapipe.tasks.core.BaseOptions
import com.google.mediapipe.tasks.vision.core.RunningMode
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarker
val baseOptions = BaseOptions.builder()
.setModelAssetPath("hand_landmarker.task")
.build()
val options = HandLandmarker.HandLandmarkerOptions.builder()
.setBaseOptions(baseOptions)
.setRunningMode(RunningMode.LIVE_STREAM)
.setNumHands(2)
.setResultListener { result, _ -> val hands = result.landmarks() }
.setErrorListener { error -> Log.e("MediaPipe", error.message.orEmpty()) }
.build()
val handLandmarker = HandLandmarker.createFromOptions(context, options)
// Async: automatically drops incoming camera frames when busy so results stay current
handLandmarker.detectAsync(mpImage, SystemClock.uptimeMillis())
```
### Android (Java)
Gradle`implementation 'com.google.mediapipe:tasks-vision:latest.release'`[Sample code](https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/hand_landmarker/android)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_android.md.txt)
#### Image
`IMAGE`Stateless · single frameSynchronous call on independent still images. Resets temporal tracking state on every call.
```java
import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;
import com.google.mediapipe.tasks.core.BaseOptions;
import com.google.mediapipe.tasks.vision.core.RunningMode;
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarker;
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarkerResult;
BaseOptions baseOptions = BaseOptions.builder()
.setModelAssetPath("hand_landmarker.task")
.build();
HandLandmarker.HandLandmarkerOptions options = HandLandmarker.HandLandmarkerOptions.builder()
.setBaseOptions(baseOptions)
.setRunningMode(RunningMode.IMAGE)
.setNumHands(2)
.build();
HandLandmarker handLandmarker = HandLandmarker.createFromOptions(context, options);
// Synchronous single-image call (no temporal tracking across calls)
MPImage mpImage = new BitmapImageBuilder(bitmap).build();
HandLandmarkerResult result = handLandmarker.detect(mpImage);
```
#### Video
`VIDEO`Every frame · no dropsSynchronous tracking across decoded video frames with monotonic timestamps. Processes every frame in order and never drops frames.
```java
import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;
import com.google.mediapipe.tasks.core.BaseOptions;
import com.google.mediapipe.tasks.vision.core.RunningMode;
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarker;
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarkerResult;
BaseOptions baseOptions = BaseOptions.builder()
.setModelAssetPath("hand_landmarker.task")
.build();
HandLandmarker.HandLandmarkerOptions options = HandLandmarker.HandLandmarkerOptions.builder()
.setBaseOptions(baseOptions)
.setRunningMode(RunningMode.VIDEO)
.setNumHands(2)
.build();
HandLandmarker handLandmarker = HandLandmarker.createFromOptions(context, options);
// Synchronous: processes every frame in order with monotonic timestamps (no frame drops)
MPImage mpImage = new BitmapImageBuilder(frameBitmap).build();
HandLandmarkerResult result = handLandmarker.detectForVideo(mpImage, frameTimestampMs);
```
#### Livestream
`LIVE_STREAM`Async · drops frames when busyAsynchronous camera pipeline with a result callback. Automatically drops incoming frames when busy so results stay current with low latency.
```java
import android.os.SystemClock;
import android.util.Log;
import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;
import com.google.mediapipe.tasks.core.BaseOptions;
import com.google.mediapipe.tasks.vision.core.RunningMode;
import com.google.mediapipe.tasks.vision.handlandmarker.HandLandmarker;
BaseOptions baseOptions = BaseOptions.builder()
.setModelAssetPath("hand_landmarker.task")
.build();
HandLandmarker.HandLandmarkerOptions options = HandLandmarker.HandLandmarkerOptions.builder()
.setBaseOptions(baseOptions)
.setRunningMode(RunningMode.LIVE_STREAM)
.setNumHands(2)
.setResultListener((result, inputImage) -> { var hands = result.landmarks(); })
.setErrorListener(error -> Log.e("MediaPipe", String.valueOf(error.getMessage())))
.build();
HandLandmarker handLandmarker = HandLandmarker.createFromOptions(context, options);
// Async: automatically drops incoming camera frames when busy so results stay current
handLandmarker.detectAsync(mpImage, SystemClock.uptimeMillis());
```
### iOS
SwiftPM`https://github.com/google-ai-edge/mediapipe → MediaPipeTasksVision`[Package.swift](https://developers.google.com/edge/mediapipe/solutions/setup_ios.md.txt#package_swift)·[Sample code](https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/hand_landmarker/ios)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_ios.md.txt)
#### Image
`IMAGE`Stateless · single frameSynchronous call on independent still images. Resets temporal tracking state on every call.
```swift
import Foundation
import MediaPipeTasksVision
guard let modelPath = Bundle.main.path(forResource: "hand_landmarker", ofType: "task") else { return }
let options = HandLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.numHands = 2
let handLandmarker = try HandLandmarker(options: options)
// Synchronous single-image call (stateless across images)
let mpImage = try MPImage(uiImage: image)
let result = try handLandmarker.detect(image: mpImage)
```
#### Video
`VIDEO`Every frame · no dropsSynchronous tracking across decoded video frames with monotonic timestamps. Processes every frame in order and never drops frames.
```swift
import Foundation
import MediaPipeTasksVision
guard let modelPath = Bundle.main.path(forResource: "hand_landmarker", ofType: "task") else { return }
let options = HandLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.numHands = 2
let handLandmarker = try HandLandmarker(options: options)
// Synchronous: processes every frame in order with monotonic timestamps (no frame drops)
let mpImage = try MPImage(pixelBuffer: pixelBuffer)
let result = try handLandmarker.detect(videoFrame: mpImage, timestampInMilliseconds: timestampMs)
```
#### Livestream
`LIVE_STREAM`Async · drops frames when busyAsynchronous camera pipeline with a result callback. Automatically drops incoming frames when busy so results stay current with low latency.
```swift
import Foundation
import MediaPipeTasksVision
final class HandLandmarkerStreamService: NSObject {
private var handLandmarker: HandLandmarker?
func setUp() throws {
guard let modelPath = Bundle.main.path(forResource: "hand_landmarker", ofType: "task") else { return }
let options = HandLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.numHands = 2
options.handLandmarkerLiveStreamDelegate = self
handLandmarker = try HandLandmarker(options: options)
}
func detectAsync(mpImage: MPImage, timestampMs: Int) throws {
// Async: automatically drops incoming camera frames when busy so results stay current
try handLandmarker?.detectAsync(image: mpImage, timestampInMilliseconds: timestampMs)
}
}
extension HandLandmarkerStreamService: HandLandmarkerLiveStreamDelegate {
func handLandmarker(
_ handLandmarker: HandLandmarker,
didFinishDetection result: HandLandmarkerResult?,
timestampInMilliseconds: Int,
error: (any Error)?
) {
guard let result else { return }
DispatchQueue.main.async {
let hands = result.landmarks
}
}
}
```
### Python
pip`pip install mediapipe`[Sample code](https://colab.research.google.com/github/google-ai-edge/mediapipe-samples/blob/main/examples/hand_landmarker/python/hand_landmarker.ipynb)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_python.md.txt)
#### Image
`IMAGE`Stateless · single frameSynchronous call on independent still images. Resets temporal tracking state on every call.
```python
import mediapipe as mp
BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode
options = HandLandmarkerOptions(
base_options=BaseOptions(model_asset_path="hand_landmarker.task"),
running_mode=VisionRunningMode.IMAGE,
num_hands=2,
)
with HandLandmarker.create_from_options(options) as landmarker:
# Synchronous single-image call (stateless across images)
mp_image = mp.Image.create_from_file("input.jpg")
result = landmarker.detect(mp_image)
```
#### Video
`VIDEO`Every frame · no dropsSynchronous tracking across decoded video frames with monotonic timestamps. Processes every frame in order and never drops frames.
```python
import mediapipe as mp
BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode
options = HandLandmarkerOptions(
base_options=BaseOptions(model_asset_path="hand_landmarker.task"),
running_mode=VisionRunningMode.VIDEO,
num_hands=2,
)
with HandLandmarker.create_from_options(options) as landmarker:
# Synchronous: processes every frame in order with monotonic timestamps (no frame drops)
for mp_image, timestamp_ms in decoded_video_frames:
result = landmarker.detect_for_video(mp_image, timestamp_ms)
```
#### Livestream
`LIVE_STREAM`Async · drops frames when busyAsynchronous camera pipeline with a result callback. Automatically drops incoming frames when busy so results stay current with low latency.
```python
import mediapipe as mp
BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode
def on_result(result, output_image: mp.Image, timestamp_ms: int):
print(f"Detected {len(result.hand_landmarks)} hand(s) at {timestamp_ms} ms")
options = HandLandmarkerOptions(
base_options=BaseOptions(model_asset_path="hand_landmarker.task"),
running_mode=VisionRunningMode.LIVE_STREAM,
num_hands=2,
result_callback=on_result,
)
with HandLandmarker.create_from_options(options) as landmarker:
# Async: automatically drops incoming camera frames when busy so results stay current
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb_frame)
landmarker.detect_async(mp_image, timestamp_ms)
```
### Flutter
pub`flutter pub add mediapipe_vision`[Live gallery](https://google.github.io/flutter-mediapipe/)·[Sample code](https://github.com/google/flutter-mediapipe/tree/main/samples/vision/hand_landmarker)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_flutter.md.txt)
#### Image
`RunningMode.image`Stateless · single frameOne call per independent still image. No tracking state carries over between calls.
```dart
import 'package:mediapipe_vision/mediapipe_vision.dart';
Future findHands(VisionImage image) async {
final landmarker = await HandLandmarker.create(
HandLandmarkerOptions(model: VisionModels.handLandmarker, numHands: 2),
);
try {
final result = await landmarker.detect(image);
for (var i = 0; i < result.handLandmarks.length; i++) {
final side = result.handedness[i].first.categoryName;
final wrist = result.handLandmarks[i].first;
print('$side hand, wrist at ${wrist.x}, ${wrist.y}');
}
} finally {
await landmarker.dispose();
}
}
```
#### Video
`RunningMode.video`Every frame · no dropsTracking across decoded video frames with strictly increasing timestamps. Processes every frame in order and never drops frames.
```dart
import 'dart:typed_data';
import 'package:mediapipe_vision/mediapipe_vision.dart';
typedef Frame = ({Uint8List rgba, int width, int height, int milliseconds});
Future findHandsInVideo(Stream frames) async {
final landmarker = await HandLandmarker.create(
HandLandmarkerOptions(
model: VisionModels.handLandmarker,
runningMode: RunningMode.video,
numHands: 2,
),
);
try {
await for (final frame in frames) {
final result = await landmarker.detectForVideo(
VisionImage.fromPixels(
pixels: frame.rgba,
width: frame.width,
height: frame.height,
format: VisionPixelFormat.rgba,
),
timestampMilliseconds: frame.milliseconds,
);
final ms = result.timestampMilliseconds;
for (var i = 0; i < result.handLandmarks.length; i++) {
final side = result.handedness[i].first.categoryName;
final wrist = result.handLandmarks[i].first;
print('$ms ms: $side hand, wrist at ${wrist.x}, ${wrist.y}');
}
}
} finally {
await landmarker.dispose();
}
}
```
#### Livestream
`RunningMode.liveStream`Async · drops frames when busyEach call returns at once and results arrive on the task's `results` stream. One frame runs at a time; a newer frame replaces one that's waiting, so results stay current.
```dart
import 'dart:typed_data';
import 'package:mediapipe_vision/mediapipe_vision.dart';
typedef Frame = ({Uint8List rgba, int width, int height, int milliseconds});
Future findHandsLive(Stream frames) async {
final landmarker = await HandLandmarker.create(
HandLandmarkerOptions(
model: VisionModels.handLandmarker,
runningMode: RunningMode.liveStream,
numHands: 2,
),
);
// Listen before the first frame, as Google requires a result listener.
final results = landmarker.results.listen((result) {
final ms = result.timestampMilliseconds;
for (var i = 0; i < result.handLandmarks.length; i++) {
final side = result.handedness[i].first.categoryName;
final wrist = result.handLandmarks[i].first;
print('$ms ms: $side hand, wrist at ${wrist.x}, ${wrist.y}');
}
});
try {
await for (final frame in frames) {
landmarker.detectAsync(
VisionImage.fromPixels(
pixels: frame.rgba,
width: frame.width,
height: frame.height,
format: VisionPixelFormat.rgba,
),
timestampMilliseconds: frame.milliseconds,
);
}
} finally {
// Runs the frame in flight and the waiting one, then closes results.
await landmarker.dispose();
await results.cancel();
print('${landmarker.droppedFrames} frames dropped');
}
}
```
On Web, you can use `DrawingUtils(ctx).drawConnectors(landmarks, HandLandmarker.HAND_CONNECTIONS)` and `drawLandmarks(landmarks)` from `@mediapipe/tasks-vision` to render hand skeletons on an HTML `