| 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><ph conkeyref="vbox-conkeyref-phrases/product-name"/> includes a feature called <i>webcam passthrough</i>, which
|
|---|
| 8 | enables a guest to use a host webcam. This complements the general USB passthrough support which was the typical
|
|---|
| 9 | way of using host webcams in legacy releases. The webcam passthrough support can handle non-USB video sources in
|
|---|
| 10 | theory, but this is completely untested. </p>
|
|---|
| 11 | <note>
|
|---|
| 12 | <p>The webcam passthrough module is shipped as part of the <ph conkeyref="vbox-conkeyref-phrases/vbox-ext"/>,
|
|---|
| 13 | which must be installed separately. See <xref href="intro-installing.dita">Installing <ph
|
|---|
| 14 | conkeyref="vbox-conkeyref-phrases/product-name"/> and Extension Packs</xref>. </p>
|
|---|
| 15 | </note>
|
|---|
| 16 | <p>The host webcam can be attached to the VM using the <b outputclass="bold">Devices</b> menu in the VM menu bar.
|
|---|
| 17 | The <b outputclass="bold">Webcams</b> menu contains a list of available video input devices on the host. Clicking
|
|---|
| 18 | on a webcam name attaches or detaches the corresponding host device. </p>
|
|---|
| 19 | <p>The <userinput>VBoxManage</userinput> command line tool can be used to enable webcam passthrough. Please see the
|
|---|
| 20 | host-specific sections below for additional details. The following commands are available: </p>
|
|---|
| 21 | <ul>
|
|---|
| 22 | <li>
|
|---|
| 23 | <p>Get a list of host webcams, or other video input devices: </p>
|
|---|
| 24 | <pre xml:space="preserve">$ VBoxManage list webcams</pre>
|
|---|
| 25 | <p>
|
|---|
| 26 | The output format is as follows:
|
|---|
| 27 | </p>
|
|---|
| 28 | <pre xml:space="preserve">alias "user friendly name"
|
|---|
| 29 | host path or identifier</pre>
|
|---|
| 30 | <p>The alias can be used as a shortcut in other commands. Alias '.0' means the default video input device on the
|
|---|
| 31 | host. Alias '.1', '.2'means first, second video input device, and so on. The device order is host-specific. </p>
|
|---|
| 32 | </li>
|
|---|
| 33 | <li>
|
|---|
| 34 | <p>Attach a webcam to a running VM, as follows: </p>
|
|---|
| 35 | <pre xml:space="preserve">VBoxManage controlvm <varname>VM name</varname> webcam attach [<varname>host_path</varname>|<varname>alias</varname> [<varname>settings</varname>]]</pre>
|
|---|
| 36 | <p>This attaches a USB webcam device to the guest. </p>
|
|---|
| 37 | <p>The <codeph>settings</codeph> parameter is a string <codeph>Setting1=Value1;Setting2=Value2</codeph>, which
|
|---|
| 38 | enables you to configure the emulated webcam device. The following settings are supported: </p>
|
|---|
| 39 | <ul>
|
|---|
| 40 | <li>
|
|---|
| 41 | <p><codeph>MaxFramerate</codeph>: The highest rate at
|
|---|
| 42 | which video frames are sent to the guest. A higher frame
|
|---|
| 43 | rate requires more CPU power. Therefore sometimes it is
|
|---|
| 44 | useful to set a lower limit. Default is no limit and
|
|---|
| 45 | allow the guest to use all frame rates supported by the
|
|---|
| 46 | host webcam.
|
|---|
| 47 | </p>
|
|---|
| 48 | </li>
|
|---|
| 49 | <li>
|
|---|
| 50 | <p><codeph>MaxPayloadTransferSize</codeph>: How many
|
|---|
| 51 | bytes the emulated webcam can send to the guest at a
|
|---|
| 52 | time. Default value is 3060 bytes, which is used by some
|
|---|
| 53 | webcams. Higher values can slightly reduce CPU load, if
|
|---|
| 54 | the guest is able to use larger buffers. However, a high
|
|---|
| 55 | <codeph>MaxPayloadTransferSize</codeph> might be not
|
|---|
| 56 | supported by some guests.
|
|---|
| 57 | </p>
|
|---|
| 58 | </li>
|
|---|
| 59 | </ul>
|
|---|
| 60 | </li>
|
|---|
| 61 | <li>
|
|---|
| 62 | <p>Detach a webcam from a running VM, as follows: </p>
|
|---|
| 63 | <pre xml:space="preserve">VBoxManage controlvm <varname>VM-name</varname> webcam detach [<varname>host_path</varname>|<varname>alias</varname>]</pre>
|
|---|
| 64 | </li>
|
|---|
| 65 | <li>
|
|---|
| 66 | <p>List the webcams attached to a running VM, as follows: </p>
|
|---|
| 67 | <pre xml:space="preserve">VBoxManage controlvm <varname>VM-name</varname> webcam list</pre>
|
|---|
| 68 | <p>The output contains the path or alias which was used in the <userinput>webcam attach</userinput> command for
|
|---|
| 69 | each attached webcam. </p>
|
|---|
| 70 | </li>
|
|---|
| 71 | </ul>
|
|---|
| 72 | </body>
|
|---|
| 73 |
|
|---|
| 74 | </topic>
|
|---|
