# webcam
`webcam` is the general camera model. If the camera drivers are among those in [this mediadevices repository](https://github.com/pion/mediadevices), the camera will work with the webcam model.
## Configuration
- [JSON Template](https://docs.viam.com/reference/components/camera/webcam/#configure-a-webcam-0)
- [JSON Example](https://docs.viam.com/reference/components/camera/webcam/#configure-a-webcam-1)
```json
```
Copy
```json
```
Copy
## Attributes
| Name | Type | Required? | Description |
|--------------------------|---------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `video_path` | string | Optional | The ID of or the path to the webcam. If you don’t provide a `video_path`, it defaults to the first valid video path it finds. Using the ID of a webcam is more consistent than the path. See [Using `video_path`](https://docs.viam.com/reference/components/camera/webcam/#using-video_path). |
| `format` | string | Optional | The camera image format, used with `video_path` to find the camera. See [Using `format`](https://docs.viam.com/reference/components/camera/webcam/#using-format). |
| `width_px` | int | Optional | The camera image width in pixels, used with `video_path` to find a camera with this resolution. Negative values are silently ignored and result in the default being used.
Default: Closest possible value to `480` |
| `height_px` | int | Optional | The camera image height in pixels, used with `video_path` to find a camera with this resolution. Negative values are silently ignored and result in the default being used.
Default: Closest possible value to `640` |
| `frame_rate` | float | Optional | The camera capture frequency as frames per second, used with `video_path` to find a camera with this throughput.
Default: Closest possible value to `30.0` |
| `intrinsic_parameters` | object | Optional | The intrinsic parameters of the camera used to do 2D <-> 3D projections:
- `width_px`: The expected width of the aligned image in pixels.
- `height_px`: The expected height of the aligned image in pixels.
- `fx`: The image center x point.
- `fy`: The image center y point.
- `ppx`: The image focal x.
- `ppy`: The image focal y. |
| `distortion_parameters` | object | Optional | Modified Brown-Conrady parameters used to correct for distortions caused by the shape of the camera lens:
- `rk1`: The radial distortion x.
- `rk2`: The radial distortion y.
- `rk3`: The radial distortion z.
- `tp1`: The tangential distortion x.
- `tp2`: The tangential distortion y. |
## Using `video_path`
### Find a video path using a discovery service
The [`viam:find-webcams:webcam-discovery`](https://app.viam.com/module/viam/find-webcams) service helps you identify path options. To add and use the service:
01. Navigate to the **CONFIGURE** tab of your machine’s page.
02. Click the **+** icon next to your machine part in the left-hand menu and select **Service**.
03. Search for `find-webcams` and select the `discovery / find-webcams:webcam-discovery` service.
04. Click **Add module**.
05. Enter a name or use the suggested name for your camera and click **Add to machine**.
06. Save your configuration, and wait a moment for the service to start.
07. Click **Test** to see the available `video_path`s.
08. Click the **Copy attributes** button for the camera you want to use.
09. Click the **{}** icon in the upper right corner of the camera component configuration.
10. Paste the copied attributes.
11. Click **Save**.
12. You can now delete the discovery service and the module that provides it from your machine.
### Find a video path using the command line
To list available `video_path`s use the following command:
- [Linux](https://docs.viam.com/reference/components/camera/webcam/#find-video-devices-0)
- [Mac](https://docs.viam.com/reference/components/camera/webcam/#find-video-devices-1)
```sh
ls /dev/v4l/by-id/
```
Copy
To find the `path`s of all connected video devices, run the following command:
```sh
v4l2-ctl --list-devices
```
Copy
The `id` listed by `ls /dev/v4l/by-id/` is a more consistent way to refer to the webcam.
```sh
system_profiler SPCameraDataType
```
Copy
The Unique ID displayed for each camera is the `video_path`.
## Using `format`
Viam supports the following pixel formats:
- I420
- I444
- MJPEG / MJPG
- NV12
- NV21
- RGBA
- UYVY / Y422
- YUY2 / YUYV / V422
- Z16
If your machine is connected to Viam, the available pixel formats supported by your camera automatically appear in the **Format** dropdown menu, which is visible when you click the **Show more** button.
On Linux, you can also manually determine which pixel formats your camera supports by running the following command on the machine your camera is connected to. Replace `/dev/video0` with the video path you [determined for your video device above](https://docs.viam.com/reference/components/camera/webcam/#using-video_path), if different:
```sh
v4l2-ctl --list-formats-ext --device /dev/video0
```
Copy
## Troubleshooting
##### Cannot open webcam or found no webcams
When working with a webcam camera on the Linux platform, your Linux OS must be able to access the camera properly, and the camera must be configured to use a pixel format that Viam supports.
On your Linux system, verify each of the following:
- Ensure that your Linux OS is able to access your camera:
1. Run the following command to list compatible camera devices on your system:
```sh
v4l2-ctl --list-devices
```
Copy
In the list of camera devices returned, find the entry for your camera. For example, the webcam on a rover may appear as follows:
```sh
GENERAL WEBCAM: GENERAL WEBCAM (usb-0000:01:00.0-1.4):
/dev/video0
/dev/video1
/dev/media4
```
Copy
The video path for your camera device is the first path listed under that camera, in this case `/dev/video0`.
2. Then, stop `viam-server`, and verify that your Linux OS is able to access that video device properly:
```sh
v4l2-ctl --stream-count 1 --device /dev/video0
```
Copy
Replace `/dev/video0` in the above command with the video path you determined for your video device above, if different.
The command returns successfully (with no output) if Linux is able to successfully communicate with the camera, or errors with `Cannot open device` if there was a problem communicating. If this command errors, you should consult the documentation for your camera and Linux distribution to troubleshoot. If you receive the error `Device or resource busy` instead, be sure you have stopped `viam-server` first, then re-run the command above.
- Ensure that your camera uses a supported pixel format:
1. First, determine your video path, like `/dev/video0`, following the instructions above.
2. Then, run the following command:
```sh
v4l2-ctl --list-formats-ext --device /dev/video0
```
Copy
Replace `/dev/video0` in the above command with the video path you determined for your video device above, if different.
The command will return a list of pixel formats your camera supports, such as `MJPG` (also notated as `MJPEG`) or `YUYV` (also notated as `YUY2`). In order to use a camera device with Viam, it must support at least one of the pixel formats listed in [Using `format`](https://docs.viam.com/reference/components/camera/webcam/#using-format). If your camera does not support any of these formats, it cannot be used with Viam.
If you are still having issues with your camera component on the Linux platform, and would like to [file an issue](https://github.com/viamrobotics/rdk), include your machine’s camera debug file contained in the /root/.viam/debug/components/camera directory. If you are running `viam-server` as a different user, find the .viam/debug/components/camera directory in that user’s home directory instead. This file contains basic diagnostic and configuration information about your camera that helps to quickly troubleshoot issues.
##### macOS camera permissions issues
On macOS, if you’re having trouble accessing your webcam, you may need to grant camera permissions for the application that you use to run `viam-server`.
**Resetting camera permissions:**
If `viam-server` is not prompting for camera permissions or you need to re-grant permissions, you can reset the camera permissions for all applications using the following command:
```sh
tccutil reset Camera
```
Copy
If you know the macOS bundle ID of the application that you use to run `viam-server`, you can pass the bundle ID to limit the camera permissions reset to only that application. For instance, you can reset camera permissions for the built-in Terminal app with `tccutil reset Camera com.apple.Terminal`. If the command was successful, you should see output similar to the following:
```sh
Successfully reset Camera approval status for com.apple.Terminal
```
Copy
After running this command, restart `viam-server` and it should prompt for camera permissions again.
**Checking camera permissions:**
To verify camera permissions, go to **System Settings** \> **Privacy & Security** \> **Camera**. Find the application `viam-server` is running in (such as Terminal or VS Code). Ensure that your terminal application has camera access enabled.