@pexip/media-control 16.7.1

package/LICENSE

@@ -0,0 +1,188 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction, and
+    distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by the
+    copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all other
+    entities that control, are controlled by, or are under common control with
+    that entity. For the purposes of this definition, "control" means (i) the
+    power, direct or indirect, to cause the direction or management of such
+    entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+    (50%) or more of the outstanding shares, or (iii) beneficial ownership of
+    such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity exercising
+    permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation source, and
+    configuration files.
+
+    "Object" form shall mean any form resulting from mechanical transformation
+    or translation of a Source form, including but not limited to compiled
+    object code, generated documentation, and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or Object form,
+    made available under the License, as indicated by a copyright notice that is
+    included in or attached to the work (an example is provided in the Appendix
+    below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object form,
+    that is based on (or derived from) the Work and for which the editorial
+    revisions, annotations, elaborations, or other modifications represent, as a
+    whole, an original work of authorship. For the purposes of this License,
+    Derivative Works shall not include works that remain separable from, or
+    merely link (or bind by name) to the interfaces of, the Work and Derivative
+    Works thereof.
+
+    "Contribution" shall mean any work of authorship, including the original
+    version of the Work and any modifications or additions to that Work or
+    Derivative Works thereof, that is intentionally submitted to Licensor for
+    inclusion in the Work by the copyright owner or by an individual or Legal
+    Entity authorized to submit on behalf of the copyright owner. For the
+    purposes of this definition, "submitted" means any form of electronic,
+    verbal, or written communication sent to the Licensor or its
+    representatives, including but not limited to communication on electronic
+    mailing lists, source code control systems, and issue tracking systems that
+    are managed by, or on behalf of, the Licensor for the purpose of discussing
+    and improving the Work, but excluding communication that is conspicuously
+    marked or otherwise designated in writing by the copyright owner as "Not a
+    Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity on
+    behalf of whom a Contribution has been received by Licensor and subsequently
+    incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+   reproduce, prepare Derivative Works of, publicly display, publicly perform,
+   sublicense, and distribute the Work and such Derivative Works in Source or
+   Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+   each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+   no-charge, royalty-free, irrevocable (except as stated in this section)
+   patent license to make, have made, use, offer to sell, sell, import, and
+   otherwise transfer the Work, where such license applies only to those patent
+   claims licensable by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s) with the
+   Work to which such Contribution(s) was submitted. If You institute patent
+   litigation against any entity (including a cross-claim or counterclaim in a
+   lawsuit) alleging that the Work or a Contribution incorporated within the
+   Work constitutes direct or contributory patent infringement, then any patent
+   licenses granted to You under this License for that Work shall terminate as
+   of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+   Derivative Works thereof in any medium, with or without modifications, and in
+   Source or Object form, provided that You meet the following conditions:
+
+    (a) You must give any other recipients of the Work or Derivative Works a
+    copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices stating
+    that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works that You
+    distribute, all copyright, patent, trademark, and attribution notices from
+    the Source form of the Work, excluding those notices that do not pertain to
+    any part of the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its distribution,
+    then any Derivative Works that You distribute must include a readable copy
+    of the attribution notices contained within such NOTICE file, excluding
+    those notices that do not pertain to any part of the Derivative Works, in at
+    least one of the following places: within a NOTICE text file distributed as
+    part of the Derivative Works; within the Source form or documentation, if
+    provided along with the Derivative Works; or, within a display generated by
+    the Derivative Works, if and wherever such third-party notices normally
+    appear. The contents of the NOTICE file are for informational purposes only
+    and do not modify the License. You may add Your own attribution notices
+    within Derivative Works that You distribute, alongside or as an addendum to
+    the NOTICE text from the Work, provided that such additional attribution
+    notices cannot be construed as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and may
+    provide additional or different license terms and conditions for use,
+    reproduction, or distribution of Your modifications, or for any such
+    Derivative Works as a whole, provided Your use, reproduction, and
+    distribution of the Work otherwise complies with the conditions stated in
+    this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+   Contribution intentionally submitted for inclusion in the Work by You to the
+   Licensor shall be under the terms and conditions of this License, without any
+   additional terms or conditions. Notwithstanding the above, nothing herein
+   shall supersede or modify the terms of any separate license agreement you may
+   have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except as
+   required for reasonable and customary use in describing the origin of the
+   Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+   writing, Licensor provides the Work (and each Contributor provides its
+   Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied, including, without limitation, any
+   warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
+   FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining
+   the appropriateness of using or redistributing the Work and assume any risks
+   associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+   tort (including negligence), contract, or otherwise, unless required by
+   applicable law (such as deliberate and grossly negligent acts) or agreed to
+   in writing, shall any Contributor be liable to You for damages, including any
+   direct, indirect, special, incidental, or consequential damages of any
+   character arising as a result of this License or out of the use or inability
+   to use the Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all other
+   commercial damages or losses), even if such Contributor has been advised of
+   the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+   Derivative Works thereof, You may choose to offer, and charge a fee for,
+   acceptance of support, warranty, indemnity, or other liability obligations
+   and/or rights consistent with this License. However, in accepting such
+   obligations, You may act only on Your own behalf and on Your sole
+   responsibility, not on behalf of any other Contributor, and only if You agree
+   to indemnify, defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason of your
+   accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2023 Pexip AS
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,244 @@
+# media-control
+
+Abstract away all the quirks of handling media devices
+
+A library that will handle media by wrapping
+[`enumerateDevices`][enumeratedevices] and [`getUserMedia`][getusermedia]
+extending both functions with additional logic.
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+
+## Introduction
+
+This library is meant to extend the [`mediaDevices`][mediadevices] api methods
+such as [`getUserMedia`][getusermedia], [`enumerateDevices`][enumeratedevices]
+and events on media streams and tracks.
+
+The final goal is to have a library that gives a stable and robust way to use
+these methods while guaranteeing that the developer has better control over
+which devices are delivered, fail, or exist.
+
+## Installation
+
+The package is published to Github registry scoped with @pexip. _Access right to
+@pexip is needed in order to install the package._
+
+Here is the steps to setup Github Personal Access Token for `npm`/`yarn` in
+order to add the package.
+
+1. A Github Personal Access Token is needed to be setup in order to get the
+   @pexip/media-control package. Follow [Github's doc][github package pat] to
+   create a Personal Access Token.
+
+2. When the Personal Access Token is ready, you can set it up for `npm` or
+   `yarn` via `.npmrc`. By adding your personal access token to your `~/.npmrc`
+   file, edit the `~/.npmrc` file for your project to include the following
+   line, replacing TOKEN with your personal access token. Create a new
+   `~/.npmrc` file if one doesn't exist.
+
+   ```config
+   //npm.pkg.github.com/:_authToken=TOKEN
+   ```
+
+3. Add a local `.npmrc` file to your repository with the following lines to tell
+   the package manager, `npm` or `yarn` where the registry is for `@pexip`
+   scoped packages.
+
+   ```config
+   @pexip:registry=https://npm.pkg.github.com
+   ```
+
+4. Now it is ready to add any `@pexip/PACKAGE_NAME` package to your repository.
+
+   ```sh
+   # Use yarn
+   yarn add @pexip/media-control
+
+   # Or use npm
+   npm install @pexip/media-control
+   ```
+
+**P.S.:** _there is no polyfill added to this package, the user needs to add
+polyfill to the application, i.e. `core-js`. We leverage on
+`@babel/plugin-transform-runtime` and `@babel/runtime` to accomplish this._
+
+## Usage
+
+### Get user media
+
+Get stream with audio and video without specifying devices, let the browser
+choose the right devices.
+
+```typescript
+import {getUserMedia} from '@pexip/media-control';
+
+const stream = await getUserMedia({audio: true, video: true});
+```
+
+Only get stream with video
+
+```typescript
+import {getUserMedia} from '@pexip/media-control';
+
+// neglecting audioInput is the same as setting it explicitly to false
+const stream = await getUserMedia({video: true});
+```
+
+Get stream with the specific device only but any for audio.
+
+```typescript
+import {getUserMedia} from 'media-control';
+
+const videoInputWanted = {
+  deviceId: '0abbc454-71e5-4f7e-9c8b-9de36f1334c3',
+  kind: 'videoinput',
+  label: 'Camera',
+};
+
+const stream = await getUserMedia({
+  audio: true,
+  video: {device: {exact: videoInputWanted}},
+});
+```
+
+Get stream with specific video input and fallback if it's not available and the
+specific audio input only, no fallback
+
+```typescript
+import {getUserMedia} from 'media-control';
+
+const audioInput = {
+  deviceId: 'a373b235-3ebf-40c7-b619-a491e05e35e6',
+  label: "Rick's Microphone",
+  kind: 'audioinput',
+};
+const videoInput = {
+  deviceId: '0abbc454-71e5-4f7e-9c8b-9de36f1334c3',
+  label: "Morty's Camera",
+  kind: 'videoinput',
+};
+
+const stream = await getUserMedia({
+  audio: {device: {exact: audioInput}},
+  video: videoInput,
+});
+```
+
+Get stream with specific devices and fallback when they are not available
+
+```typescript
+import {getUserMedia} from 'media-control';
+
+const audioInput = {
+  deviceId: 'a373b235-3ebf-40c7-b619-a491e05e35e6',
+  label: "Rick's Microphone",
+  kind: 'audioinput',
+};
+const videoInput = {
+  deviceId: '0abbc454-71e5-4f7e-9c8b-9de36f1334c3',
+  label: "Morty's Camera",
+  kind: 'videoinput',
+};
+
+const stream = await getUserMedia({
+  audio: audioInput,
+  video: videoInput,
+});
+```
+
+The following requests both audio and video without any specific requirements:
+
+```typescript
+import {getUserMedia} from 'media-control';
+
+const stream = await getUserMedia({audio: true, video: true});
+```
+
+The following expresses a preference for 1280x720 camera resolution:
+
+```typescript
+import {getUserMedia} from 'media-control';
+
+const stream = await getUserMedia({
+  audio: true,
+  video: {
+    width: 1280,
+    height: 720,
+  },
+});
+```
+
+The following expresses a preference for user facing camera:
+
+```typescript
+import {getUserMedia} from 'media-control';
+
+const stream = await getUserMedia({
+  audio: true,
+  video: {facingMode: 'user'},
+});
+```
+
+### Subscribe media events
+
+```typescript
+import {MediaEventType, subscribe} from 'media-control';
+
+subscribe((event: MediaEvent) => {
+  switch (event.detail.type) {
+    case MediaEventType.Mute: // {id: string}
+      // id of the device that was muted
+      const id = event.detail.id;
+      break;
+    case MediaEventType.Unmute: // {id: string}
+      // id of the device that was unmuted
+      const id = event.detail.id;
+      break;
+    case MediaEventType.Ended: // {id: string}
+      // id of the device that ended
+      const id = event.detail.id;
+      break;
+    case MediaEventType.DevicesChanged: // {devices: MediaDeviceInfo[]}
+      // devices currently available through enumerateDevices
+      const devices = event.detail.devices;
+      break;
+    case MediaEventType.DevicesFound: // {devices: MediaDeviceInfo[], authorizedDevices: MediaDeviceInfo[]}
+      // new devices connected
+      const devices = event.detail.devices;
+      break;
+    case MediaEventType.DevicesLost: // {devices: MediaDeviceInfo[], authorizedDevices: MediaDeviceInfo[]}
+      // devices lost from the enumerateDevices list
+      const devices = event.detail.devices;
+      break;
+    case MediaEventType.DeviceLost: // {device: MediaDeviceInfo}
+      // device currently in use that was lost from the enumerateDevices list
+      const device = event.detail.device;
+      break;
+    case MediaEventType.DevicesUnauthorized: // {devices: MediaDeviceInfo[], authorizedDevices: MediaDeviceInfo[]}
+      // Unauthorized list of devices
+      const device = event.detail.devices;
+      break;
+    case MediaEventType.NoInputDevices:
+      // Indicate that there is no input devices from the machine
+      break;
+    case MediaEventType.Error: // {error: Error}
+      const error = event.detail.error;
+      break;
+  }
+});
+```
+
+[mediadevices]: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices
+[enumeratedevices]:
+  https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices
+[getusermedia]:
+  https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia
+[mediadeviceinfo]:
+  https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo
+[github package pat]:
+  https://help.github.com/en/github/managing-packages-with-github-packages/about-github-packages#about-tokens
+[parcel]: https://parceljs.org