| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
|---|
| 2 | <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
|
|---|
| 3 | <topic xml:lang="en-us" id="webcam-using-guest">
|
|---|
| 4 | <title>Using a Host Webcam in the Guest</title>
|
|---|
| 5 |
|
|---|
| 6 | <body>
|
|---|
| 7 | <p>
|
|---|
| 8 | Oracle VM VirtualBox includes a feature called <i>webcam
|
|---|
| 9 | passthrough</i>, which enables a guest to use a host
|
|---|
| 10 | webcam. This complements the general USB passthrough support
|
|---|
| 11 | which was the typical way of using host webcams in legacy
|
|---|
| 12 | releases. The webcam passthrough support can handle non-USB
|
|---|
| 13 | video sources in theory, but this is completely untested.
|
|---|
| 14 | </p>
|
|---|
| 15 | <note>
|
|---|
| 16 | <p>
|
|---|
| 17 | The webcam passthrough module is shipped as part of the
|
|---|
| 18 | Oracle VM VirtualBox extension pack, which must be installed
|
|---|
| 19 | separately. See <xref href="intro-installing.dita">Installing Oracle VM VirtualBox and Extension Packs</xref>.
|
|---|
| 20 | </p>
|
|---|
| 21 | </note>
|
|---|
| 22 | <p>
|
|---|
| 23 | The host webcam can be attached to the VM using the
|
|---|
| 24 | <b outputclass="bold">Devices</b> menu in the VM menu
|
|---|
| 25 | bar. The <b outputclass="bold">Webcams</b> menu contains
|
|---|
| 26 | a list of available video input devices on the host. Clicking on
|
|---|
| 27 | a webcam name attaches or detaches the corresponding host
|
|---|
| 28 | device.
|
|---|
| 29 | </p>
|
|---|
| 30 | <p>
|
|---|
| 31 | The <userinput>VBoxManage</userinput> command line tool can be used
|
|---|
| 32 | to enable webcam passthrough. Please see the host-specific
|
|---|
| 33 | sections below for additional details. The following commands
|
|---|
| 34 | are available:
|
|---|
| 35 | </p>
|
|---|
| 36 | <ul>
|
|---|
| 37 | <li>
|
|---|
| 38 | <p>
|
|---|
| 39 | Get a list of host webcams, or other video input devices:
|
|---|
| 40 | </p>
|
|---|
| 41 | <pre xml:space="preserve">$ VBoxManage list webcams</pre>
|
|---|
| 42 | <p>
|
|---|
| 43 | The output format is as follows:
|
|---|
| 44 | </p>
|
|---|
| 45 | <pre xml:space="preserve">alias "user friendly name"
|
|---|
| 46 | host path or identifier</pre>
|
|---|
| 47 | <p>
|
|---|
| 48 | The alias can be used as a shortcut in other commands. Alias
|
|---|
| 49 | '.0' means the default video input device on the host. Alias
|
|---|
| 50 | '.1', '.2'means first, second video input device, and so on.
|
|---|
| 51 | The device order is host-specific.
|
|---|
| 52 | </p>
|
|---|
| 53 | </li>
|
|---|
| 54 | <li>
|
|---|
| 55 | <p>
|
|---|
| 56 | Attach a webcam to a running VM, as follows:
|
|---|
| 57 | </p>
|
|---|
| 58 | <pre xml:space="preserve">VBoxManage controlvm <varname>VM name</varname> webcam attach [<varname>host_path</varname>|<varname>alias</varname> [<varname>settings</varname>]]</pre>
|
|---|
| 59 | <p>
|
|---|
| 60 | This attaches a USB webcam device to the guest.
|
|---|
| 61 | </p>
|
|---|
| 62 | <p>
|
|---|
| 63 | The <codeph>settings</codeph> parameter is a string
|
|---|
| 64 | <codeph>Setting1=Value1;Setting2=Value2</codeph>, which
|
|---|
| 65 | enables you to configure the emulated webcam device. The
|
|---|
| 66 | following settings are supported:
|
|---|
| 67 | </p>
|
|---|
| 68 | <ul>
|
|---|
| 69 | <li>
|
|---|
| 70 | <p><codeph>MaxFramerate</codeph>: The highest rate at
|
|---|
| 71 | which video frames are sent to the guest. A higher frame
|
|---|
| 72 | rate requires more CPU power. Therefore sometimes it is
|
|---|
| 73 | useful to set a lower limit. Default is no limit and
|
|---|
| 74 | allow the guest to use all frame rates supported by the
|
|---|
| 75 | host webcam.
|
|---|
| 76 | </p>
|
|---|
| 77 | </li>
|
|---|
| 78 | <li>
|
|---|
| 79 | <p><codeph>MaxPayloadTransferSize</codeph>: How many
|
|---|
| 80 | bytes the emulated webcam can send to the guest at a
|
|---|
| 81 | time. Default value is 3060 bytes, which is used by some
|
|---|
| 82 | webcams. Higher values can slightly reduce CPU load, if
|
|---|
| 83 | the guest is able to use larger buffers. However, a high
|
|---|
| 84 | <codeph>MaxPayloadTransferSize</codeph> might be not
|
|---|
| 85 | supported by some guests.
|
|---|
| 86 | </p>
|
|---|
| 87 | </li>
|
|---|
| 88 | </ul>
|
|---|
| 89 | </li>
|
|---|
| 90 | <li>
|
|---|
| 91 | <p>
|
|---|
| 92 | Detach a webcam from a running VM, as follows:
|
|---|
| 93 | </p>
|
|---|
| 94 | <pre xml:space="preserve">VBoxManage controlvm <varname>VM-name</varname> webcam detach [<varname>host_path</varname>|<varname>alias</varname>]</pre>
|
|---|
| 95 | </li>
|
|---|
| 96 | <li>
|
|---|
| 97 | <p>
|
|---|
| 98 | List the webcams attached to a running VM, as follows:
|
|---|
| 99 | </p>
|
|---|
| 100 | <pre xml:space="preserve">VBoxManage controlvm <varname>VM-name</varname> webcam list</pre>
|
|---|
| 101 | <p>
|
|---|
| 102 | The output contains the path or alias which was used in the
|
|---|
| 103 | <userinput>webcam attach</userinput> command for each attached
|
|---|
| 104 | webcam.
|
|---|
| 105 | </p>
|
|---|
| 106 | </li>
|
|---|
| 107 | </ul>
|
|---|
| 108 | </body>
|
|---|
| 109 |
|
|---|
| 110 | </topic>
|
|---|
