2.6. Webcam Passthrough

2.6.1. Using a Host Webcam in the Guest

Oracle VM VirtualBox includes a feature called webcam passthrough, which enables a guest to use a host webcam. This complements the general USB passthrough support which was the typical way of using host webcams in legacy releases. The webcam passthrough support can handle non-USB video sources in theory, but this is completely untested.

Note

The webcam passthrough module is shipped as part of the Oracle VM VirtualBox extension pack, which must be installed separately. See Installing Oracle VM VirtualBox and Extension Packs.

The host webcam can be attached to the VM using the Devices menu in the VM menu bar. The Webcams menu contains a list of available video input devices on the host. Clicking on a webcam name attaches or detaches the corresponding host device.

The VBoxManage command line tool can be used to enable webcam passthrough. Please see the host-specific sections below for additional details. The following commands are available:

Get a list of host webcams, or other video input devices:
```
$ VBoxManage list webcams
```
The output format is as follows:
```
alias "user friendly name"
host path or identifier
```
The alias can be used as a shortcut in other commands. Alias '.0' means the default video input device on the host. Alias '.1', '.2'means first, second video input device, and so on. The device order is host-specific.
Attach a webcam to a running VM, as follows:
```
VBoxManage controlvm VM name webcam attach [host_path|alias [settings]]
```
This attaches a USB webcam device to the guest.
The settings parameter is a string Setting1=Value1;Setting2=Value2, which enables you to configure the emulated webcam device. The following settings are supported:
- MaxFramerate: The highest rate at which video frames are sent to the guest. A higher frame rate requires more CPU power. Therefore sometimes it is useful to set a lower limit. Default is no limit and allow the guest to use all frame rates supported by the host webcam.
- MaxPayloadTransferSize: How many bytes the emulated webcam can send to the guest at a time. Default value is 3060 bytes, which is used by some webcams. Higher values can slightly reduce CPU load, if the guest is able to use larger buffers. However, a high MaxPayloadTransferSize might be not supported by some guests.

Detach a webcam from a running VM, as follows:

VBoxManage controlvm VM-name webcam detach [host_path|alias]

List the webcams attached to a running VM, as follows:
```
VBoxManage controlvm VM-name webcam list
```
The output contains the path or alias which was used in the webcam attach command for each attached webcam.

2.6.2. Windows Hosts

When the webcam device is detached from the host, the emulated webcam device is automatically detached from the guest.

2.6.3. Mac OS X Hosts

Mac OS X version 10.9 or later is required.

When the webcam device is detached from the host, the emulated webcam device remains attached to the guest and must be manually detached using the VBoxManage controlvm VM-name webcam detach command.

2.6.4. Linux and Oracle Solaris Hosts

When the webcam is detached from the host the emulated webcam device is automatically detached from the guest only if the webcam is streaming video. If the emulated webcam is inactive it should be manually detached using the VBoxManage controlvm VM-name webcam detach command.

Aliases .0 and .1 are mapped to /dev/video0, alias .2 is mapped to /dev/video1 and so forth.