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.

Built-in models

• webcam: USB cameras and built-in laptop cameras. Auto-detects available devices.
• ffmpeg: a camera device, video file, or stream that ffmpeg can read. For RTSP IP cameras, prefer the viam:viamrtsp registry module listed under Registry modules.
• transform: applies transformations (crop, resize, rotate, overlay) to another camera’s output.
• fake: a camera model for testing.
• image_file: serves color or depth image frames from a file path.

For Micro-RDK, see Micro-RDK camera models.

Registry modules

Viam-maintained camera modules:

For cameras not covered above, browse all camera modules 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 rtsp and pick one of the viam:viamrtsp models (rtsp autodetects codec; specific codecs like rtsp-h264 or rtsp-h265 are also available).
   • 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. Open the refresh-interval dropdown and select Live 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 API keys. Copy the API key and API key ID. Copy the machine address from the Connection details section on the same tab.

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

sudo reboot

Related

• 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.