media-devices 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,12 +1,53 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2021-12-04
+
+### Added
+
+- Export `DeviceChange` type which describes each object in a device change set.
+- New `mediaDevices.ondevicechange` mutable field for listeners.
+- Public methods are bound, no longer depending on implicit `this` context.
+
+### Fixed
+
+- Querying `getDisplayMedia(...)` now refreshes the device cache for cases where browsers loosen fingerprinting countermeasures.
+
+### Deprecated
+
+- Using the event emitter interface is no longer advised. It will be removed in a future release. Use the `ondevicechange` field instead:
+  ```diff
+  -mediaDevices.on('devicechange', handler)
+  +mediaDevices.ondevicechange = handler
+  ```
+
+## [0.2.0] - 2021-02-23
+
+### Added
+
+- Another parameter added to the `devicechange` listener containing the entire list of known devices.
+- Enum and type exports for `DeviceKind`, `DeviceInfo`, and `OperationType`.
+
+### Changed
+
+- Made `device.groupId` a nullable field because [Safari is a monster](https://github.com/PsychoLlama/media-devices/issues/3).
+
+### Fixed
+
+- No longer throws an error if you try to import in an unsupported environment.
+
 ## [0.1.0] - 2021-02-21
+
 ### Added
+
 - Initial API compatible with `navigator.mediaDevices`.
 - A device list-diffing implementation of `ondevicechange`.
 - Support detection via `supportsMediaDevices()`.
 
+[Unreleased]: https://github.com/PsychoLlama/media-devices/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/PsychoLlama/media-devices/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/PsychoLlama/media-devices/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/PsychoLlama/media-devices/releases/tag/v0.1.0

package/README.md

@@ -1,6 +1,16 @@
 <div align="center">
   <h1>Media Devices</h1>
   <p>Easily manage media devices in the browser</p>
+  
+  <div>
+    <a href="https://github.com/PsychoLlama/media-devices/actions/workflows/main.yml">
+      <img src="https://img.shields.io/github/workflow/status/PsychoLlama/media-devices/CI/main" alt="Build status" />
+    </a>
+    <img src="https://img.shields.io/npm/types/media-devices" alt="Build status" />
+    <a href="https://www.npmjs.com/package/media-devices">
+      <img src="https://img.shields.io/npm/v/media-devices" alt="npm version" />
+    </a>
+  </div>
 </div>
 
 ## Purpose
@@ -9,7 +19,7 @@
 ## API
 The API is a carbon copy of [`navigator.mediaDevices`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/mediaDevices), with the exception of `ondevicechange` which was replaced for more bells and whistles.
 
-Here's an overview:
+Here's the gist:
 
 ```js
 import MediaDevices from 'media-devices'
@@ -24,43 +34,61 @@ await MediaDevices.getUserMedia({ video: true, audio: true })
 await MediaDevices.getDisplayMedia()
 
 // Listen for changes in available devices
-MediaDevices.on('devicechange', changes => {
+MediaDevices.ondevicechange = ({ changes }) => {
   // [{ type: 'add', ... }, { type: 'update', ... }]
-})
+}
 ```
 
-### `on('devicechange')`
-Notifies you whenever the device list is updated and passes you a list of changes. Each change is an update, removal, or addition.
+### `supportsMediaDevices()`
+Exported as a separate utility function, this helps determine if your browser supports the `navigator.mediaDevices` API. Be aware that some browsers only expose it on secure sites.
 
 ```js
-interface DeviceAddEvent {
-  type: 'add';
-  device: DeviceInfo;
-}
+import { supportsMediaDevices } from 'media-devices'
 
-interface DeviceRemoveEvent {
-  type: 'remove';
-  device: DeviceInfo;
+if (supportsMediaDevices()) {
+  // yey
 }
+```
+
+### `ondevicechange`
+`MediaDevices` emits this event whenever the list of devices changes. It passes two things:
 
-interface DeviceUpdateEvent {
-  type: 'update';
-  newInfo: DeviceInfo;
-  oldInfo: DeviceInfo;
+1. A list of changes
+1. The full list of devices
+
+```js
+MediaDevices.ondevicechange = ({ changes, devices }) => {
+  // ...
 }
 ```
 
-### `supportsMediaDevices()`
-Exported as a separate utility function, this helps determine if your browser supports the `navigator.mediaDevices` API. Be aware that some browsers only expose it on secure sites.
+The list of devices is exactly what you'd get from `enumerateDevices()`. The changes are a diff between this list and the last, showing which devices were added, which were removed, and which were updated.
 
 ```js
-import { supportsMediaDevices } from 'media-devices'
-
-if (supportsMediaDevices()) {
-  // ... party
-}
+[
+  // A device was just plugged in.
+  {
+    type: 'add',
+    device: DeviceInfo,
+  },
+
+  // A device was disconnected.
+  {
+    type: 'remove',
+    device: DeviceInfo,
+  },
+
+  // The browser gave us more information about a device.
+  {
+    type: 'update',
+    oldInfo: DeviceInfo,
+    newInfo: DeviceInfo,
+  },
+]
 ```
 
+Update events are odd. Browsers redact information until the user explicitly grants trust, so things like labels and device IDs might start off null. [Another quirk](#speaker-replacement) regarding speakers may cause the device to update in-place.
+
 ---------------
 
 ## Known Quirks
@@ -85,8 +113,13 @@ That makes it hard to tell whether the device list actually changed. This librar
 
 Device IDs are set to `null` in this case.
 
+### Missing Group IDs
+As of Safari v14, even with permissions, the browser doesn't provide group IDs. Why? Because they're monsters.
+
+Group IDs are `null` in Safari.
+
 ### Hidden Devices
-Chrome only shows the first of each device type (mic, camera, speakers) until `getUserMedia(...)` is approved. Other options are hidden. If you have 10 cameras, you'll only see the first until you're authorized. Even then, it only shows you cameras, microphones are still hidden.
+Chrome and Safari only show the first of each device type (mic, camera, speakers) until `getUserMedia(...)` is approved. Other options are hidden. If you have 10 cameras, you'll only see the first until you're authorized. Even then, Chrome only shows you cameras, microphones are still hidden.
 
 While we can't work around it, we can automatically identify that old camera in the list of 10 and show the other 9 as added devices.
 

package/dist/device-manager.d.ts

@@ -7,33 +7,42 @@ import { DeviceInfo } from './enumerate-devices';
  * attempts graceful integration with browser fingerprinting countermeasures.
  */
 export default class DeviceManager extends EventEmitter {
-    _knownDevices: Array<DeviceInfo>;
+    private _knownDevices;
+    private _gainedScreenAccessOnce;
+    /**
+     * Specifies a function to be called whenever the list of available devices
+     * changes.
+     *
+     * Note: this is different from the native event. It passes the changeset
+     * and full list of devices as a parameter.
+     */
+    ondevicechange: null | DeviceChangeListener;
     constructor();
     /**
      * Request a live media stream from audio and/or video devices. Streams are
      * configurable through constraints.
      * See: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia
      */
-    getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream>;
+    getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
     /**
      * Ask the user to share their screen. Resolves with a media stream carrying
      * video, and potentially audio from the application window.
      * See: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia
      */
-    getDisplayMedia(constraints?: MediaStreamConstraints): Promise<MediaStream>;
+    getDisplayMedia: (constraints?: MediaStreamConstraints | undefined) => Promise<MediaStream>;
     /**
      * Lists every available hardware device, including microphones, cameras,
      * and speakers (depending on browser support). May contain redacted
      * information depending on application permissions.
      */
-    enumerateDevices(): Promise<Array<DeviceInfo>>;
+    enumerateDevices: () => Promise<Array<DeviceInfo>>;
     /**
      * Returns an object containing every media constraint supported by the
      * browser.
      * See: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getSupportedConstraints
      */
-    getSupportedConstraints(): MediaTrackSupportedConstraints;
-    _checkForDeviceChanges(newDevices: Array<DeviceInfo>): void;
+    getSupportedConstraints: () => MediaTrackSupportedConstraints;
+    private _checkForDeviceChanges;
     /**
      * Note: The device enumeration API may return null values for device IDs
      * and labels. To avoid creating erroneous "Device Added" notifications,
@@ -43,30 +52,31 @@ export default class DeviceManager extends EventEmitter {
      * correlate devices from permissioned requests with unpermissioned
      * requests.
      */
-    _calculateDeviceDiff(newDevices: Array<DeviceInfo>, oldDevices: Array<DeviceInfo>): Array<DeviceChange>;
+    private _calculateDeviceDiff;
 }
-declare type DeviceChange = DeviceAddEvent | DeviceRemoveEvent | DeviceUpdateEvent;
+export declare type DeviceChange = DeviceAddEvent | DeviceRemoveEvent | DeviceUpdateEvent;
 interface DeviceAddEvent {
-    type: DeviceChangeType.Add;
+    type: OperationType.Add;
     device: DeviceInfo;
 }
 interface DeviceRemoveEvent {
-    type: DeviceChangeType.Remove;
+    type: OperationType.Remove;
     device: DeviceInfo;
 }
 interface DeviceUpdateEvent {
-    type: DeviceChangeType.Update;
+    type: OperationType.Update;
     newInfo: DeviceInfo;
     oldInfo: DeviceInfo;
 }
-export declare enum DeviceChangeType {
+export declare enum OperationType {
     Add = "add",
     Remove = "remove",
     Update = "update"
 }
-declare global {
-    interface MediaDevices {
-        getDisplayMedia(constraints?: MediaStreamConstraints): Promise<MediaStream>;
-    }
+interface DeviceChangeListener {
+    (update: {
+        changes: Array<DeviceChange>;
+        devices: Array<DeviceInfo>;
+    }): unknown;
 }
 export {};

package/dist/enumerate-devices.d.ts

@@ -23,9 +23,10 @@ export interface DeviceInfo {
     /**
      * A unique identifier grouping one or more devices together. Two devices
      * with the same group ID symbolise that both devices belong to the same
-     * hardware, e.g. a webcam with an integrated microphone.
+     * hardware, e.g. a webcam with an integrated microphone. Note: Safari
+     * doesn't support group IDs.
      */
-    groupId: string;
+    groupId: null | string;
     /**
      * Declares the type of media provided. This covers microphones, cameras,
      * and speakers.

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import DeviceManager from './device-manager';
 export { supportsMediaDevices } from './support-detection';
+export { DeviceInfo, DeviceKind } from './enumerate-devices';
+export { OperationType, DeviceChange } from './device-manager';
 declare const _default: DeviceManager;
 export default _default;