Add a camera

Add a camera to your machine’s configuration so you can capture images and video from the Viam app and from code.

Concepts

The camera API gives you GetImages (capture frames), GetPointCloud (depth data), and stream access regardless of the underlying hardware. Common models include:

• webcam (built-in): USB cameras and built-in laptop cameras. Auto-detects available devices.
• ffmpeg (built-in): IP cameras and RTSP streams.
• realsense: Intel RealSense depth cameras (module).
• transform: Applies transformations (crop, resize, overlay) to another camera’s output.

Browse all available camera models in the Viam registry.

Steps

1. Open your machine in the Viam app

Go to app.viam.com and navigate to your machine. Confirm it shows as Live in the upper left. If it shows as offline, verify that viam-server is running on your machine.

2. Add a camera component

1. Click the + button.
2. Select Configuration block.
3. Search for the model that matches your camera:
   • For a USB webcam or built-in laptop camera, search for webcam.
   • For an IP camera that supports RTSP, search for ffmpeg.
   • For an Intel RealSense depth camera, search for realsense.
4. Name your camera (this guide uses my-camera) and click Create.

3. Configure camera attributes

After creating the component, you’ll see its configuration panel.

For a USB webcam (webcam model):

Most USB webcams work with no additional configuration. If you have multiple cameras connected, specify which one to use:

{
  "video_path": "video0"
}

To find available video devices on Linux:

ls /dev/video*

You can also set resolution and frame rate:

{
  "width_px": 640,
  "height_px": 480,
  "frame_rate": 30
}

4. Save the configuration

Click Save in the upper right of the configuration panel.

When you save, viam-server automatically reloads the configuration and initializes the new component. You do not need to restart anything.

5. Test the camera

Every component in Viam has a built-in test panel in the Configure tab. The test panel uses the exact same APIs your code will use, so if the camera works here, it will work in your programs.

1. Find your camera component in the configuration view.
2. Expand the Test section at the bottom of the component panel.
3. Click Toggle stream to see a live video feed from the camera.
4. Click Get image to capture a single frame.

You should see a live feed from the camera.

Try it

Capture an image from your camera programmatically.

To get the credentials for the code below, go to your machine’s page in the Viam app, click the CONNECT tab, and select SDK code sample. Toggle Include API key on. Copy the machine address, API key, and API key ID from the code sample.

When you run the code below, it saves an image file to your current directory. Check that the image shows what the camera sees.

pip install viam-sdk

import asyncio
from io import BytesIO
from PIL import Image as PILImage
from viam.robot.client import RobotClient
from viam.components.camera import Camera


async def main():
    opts = RobotClient.Options.with_api_key(
        api_key="YOUR-API-KEY",
        api_key_id="YOUR-API-KEY-ID"
    )
    robot = await RobotClient.at_address("YOUR-MACHINE-ADDRESS", opts)

    camera = Camera.from_robot(robot, "my-camera")
    images, metadata = await camera.get_images()
    image = PILImage.open(BytesIO(images[0].data))
    image.save("test-capture.png")
    print(f"Captured {image.size[0]}x{image.size[1]} image")

    await robot.close()

if __name__ == "__main__":
    asyncio.run(main())

python camera_test.py

Captured 640x480 image

mkdir camera-test && cd camera-test
go mod init camera-test
go get go.viam.com/rdk

package main

import (
    "context"
    "fmt"
    "image/png"
    "os"

    "go.viam.com/rdk/components/camera"
    "go.viam.com/rdk/logging"
    "go.viam.com/rdk/robot/client"
    "go.viam.com/rdk/utils"
)

func main() {
    ctx := context.Background()
    logger := logging.NewLogger("camera-test")

    robot, err := client.New(ctx, "YOUR-MACHINE-ADDRESS", logger,
        client.WithCredentials(utils.Credentials{
            Type:    utils.CredentialsTypeAPIKey,
            Payload: "YOUR-API-KEY",
        }),
        client.WithAPIKeyID("YOUR-API-KEY-ID"),
    )
    if err != nil {
        logger.Fatal(err)
    }
    defer robot.Close(ctx)

    cam, err := camera.FromProvider(robot, "my-camera")
    if err != nil {
        logger.Fatal(err)
    }

    img, _, err := cam.Images(ctx, nil, nil)
    if err != nil {
        logger.Fatal(err)
    }

    f, err := os.Create("test-capture.png")
    if err != nil {
        logger.Fatal(err)
    }
    defer f.Close()

    image, err := img[0].Image(ctx)
    if err != nil {
        logger.Fatal(err)
    }

    if err := png.Encode(f, image); err != nil {
        logger.Fatal(err)
    }

    fmt.Printf("Captured image and saved to test-capture.png\n")
}

go run main.go

Troubleshooting

What’s next

• Camera API reference: full method documentation.
• Capture and Sync Data: configure your camera to automatically capture images and sync them to the cloud.
• Add Computer Vision: run ML models on your camera feed to detect or classify objects.