|
| 1 | +--- |
| 2 | +slug: /device-emulator |
| 3 | +sidebar_position: 1 |
| 4 | +keywords: [opensource] |
| 5 | +--- |
| 6 | + |
| 7 | +# Introduction |
| 8 | + |
| 9 | +For a product, integration tests are one of the crucial part that improves quality & stability. For a WebRTC based solution like Dyte, having integration tests that can test multi-user call with Audio/Video on is necessary. |
| 10 | + |
| 11 | +For an end user, sharing a camera & mic is easy. For this, browsers expose APIs such as enumerateDevices & getUserMedia on MediaDevices interface, on which user interfaces can be built easily. |
| 12 | + |
| 13 | +Access to camera & mic prompts the users to allow permissions to do so. This works great as long as an end-user is using the product and actively allowing permissions and selecting devices, However this makes it impossible to write integration tests because for integration tests there is no active user and you need to somehow allow permissions programmatically which at the moment of writing this README is not reliably supported in modern tools like Playwright. |
| 14 | + |
| 15 | +Even if we can somehow allow permissions, The next set of questions would be: What would the video & audio feed look like? Can we customize the feed? Can we use the feed to detect delays between a video feed producer and consumer? How do we test multiple devices? How do we test media ejection on the fly? How do we test addition of a new device? |
| 16 | + |
| 17 | +Dyte's Device Emulator is a solution that answers all these questions and provides a easier way to mimic, add, remove devices & their feed. |
| 18 | + |
| 19 | +## Installation |
| 20 | + |
| 21 | +<Tabs groupId="cdn-npm"> |
| 22 | + <TabItem value="cdn" label="CDN" default> |
| 23 | + |
| 24 | +To set up device-emulator add the following script tags inside |
| 25 | +the `<head />` tag. |
| 26 | + |
| 27 | +```html |
| 28 | +<script> |
| 29 | + window.addEventListener('dyte.deviceEmulatorLoaded', () => { |
| 30 | + // use device emulator methods here... |
| 31 | + }); |
| 32 | +</script> |
| 33 | +<script src="https://cdn.jsdelivr.net/npm/@dytesdk/device-emulator/dist/index.iife.js"></script> |
| 34 | +``` |
| 35 | + |
| 36 | + </TabItem> |
| 37 | + <TabItem value="npm" label="npm"> |
| 38 | + |
| 39 | +```bash |
| 40 | +npm install @dytesdk/device-emulator |
| 41 | +``` |
| 42 | + |
| 43 | +use the package like below |
| 44 | + |
| 45 | +```js |
| 46 | +import '@dytesdk/device-emulator'; |
| 47 | + |
| 48 | +// use the device emulator methods |
| 49 | +``` |
| 50 | + |
| 51 | + </TabItem> |
| 52 | + |
| 53 | + <TabItem value="yarn" label="yarn"> |
| 54 | + |
| 55 | +```bash |
| 56 | +yarn add @dytesdk/device-emulator |
| 57 | +``` |
| 58 | + |
| 59 | +use the package like below |
| 60 | + |
| 61 | +```js |
| 62 | +import '@dytesdk/device-emulator'; |
| 63 | + |
| 64 | +// use the device emulator methods |
| 65 | +``` |
| 66 | + |
| 67 | + </TabItem> |
| 68 | +</Tabs> |
| 69 | + |
| 70 | +## API reference |
| 71 | + |
| 72 | +### Add a virtual device |
| 73 | + |
| 74 | +```js {1} |
| 75 | +const virtualDeviceID = navigator.mediaDevices.addEmulatedDevice('videoinput'); |
| 76 | + |
| 77 | +// get a media track from the virtual device |
| 78 | +navigator.mediaDevices |
| 79 | + .getUserMedia({ |
| 80 | + video: { |
| 81 | + deviceId: { |
| 82 | + exact: virtualDeviceID, |
| 83 | + }, |
| 84 | + }, |
| 85 | + }) |
| 86 | + .then((mediaStream) => { |
| 87 | + const video = document.querySelector('video'); |
| 88 | + video.srcObject = mediaStream; |
| 89 | + video.onloadedmetadata = () => { |
| 90 | + video.play(); |
| 91 | + }; |
| 92 | + }) |
| 93 | + .catch((err) => { |
| 94 | + // always check for errors at the end. |
| 95 | + console.error(`${err.name}: ${err.message}`); |
| 96 | + }); |
| 97 | +``` |
| 98 | + |
| 99 | +### Remove virtual device |
| 100 | + |
| 101 | +```js |
| 102 | +navigator.mediaDevices.removeEmulatedDevice(deviceId); |
| 103 | +``` |
| 104 | + |
| 105 | +### Stop the device |
| 106 | + |
| 107 | +You can use `brickDevice` method to test scenarios where the devices stops working abruptly. |
| 108 | + |
| 109 | +```js {4} |
| 110 | +const virtualDeviceID = navigator.mediaDevices.addEmulatedDevice('videoinput'); |
| 111 | + |
| 112 | +// Stop the device from working |
| 113 | +navigator.mediaDevices.brickDevice(virtualDeviceID, true); |
| 114 | + |
| 115 | +navigator.mediaDevices |
| 116 | + .getUserMedia({ |
| 117 | + video: { |
| 118 | + deviceId: { |
| 119 | + exact: virtualDeviceID, |
| 120 | + }, |
| 121 | + }, |
| 122 | + }) |
| 123 | + .then((mediaStream) => { |
| 124 | + // This will not work |
| 125 | + const video = document.querySelector('video'); |
| 126 | + video.srcObject = mediaStream; |
| 127 | + video.onloadedmetadata = () => { |
| 128 | + video.play(); |
| 129 | + }; |
| 130 | + }) |
| 131 | + .catch((err) => { |
| 132 | + // catch `NotReadableError` thrown from the device |
| 133 | + console.error(`${err.name}: ${err.message}`); |
| 134 | + }); |
| 135 | +``` |
| 136 | + |
| 137 | +Executing the `brickDevice` after getting the tracks will stop the active tracks. |
| 138 | + |
| 139 | +### Resume the device |
| 140 | + |
| 141 | +Use `brickDevice` method to make the device work normally |
| 142 | + |
| 143 | +```js |
| 144 | +navigator.mediaDevices.unbrickDevice(deviceId, false); |
| 145 | +``` |
| 146 | + |
| 147 | +### Silence the tracks |
| 148 | + |
| 149 | +Generate tracks that are silent |
| 150 | + |
| 151 | +```js |
| 152 | +navigator.mediaDevices.silenceDevice(deviceId, true); |
| 153 | +``` |
| 154 | + |
| 155 | +### Unmute the tracks from the device |
| 156 | + |
| 157 | +Remove the silence check on the device |
| 158 | + |
| 159 | +```js |
| 160 | +navigator.mediaDevices.silenceDevice(deviceId, false); |
| 161 | +``` |
0 commit comments