media-devices 0.4.0 → 0.5.0

package/src/__tests__/device-manager.test.ts

@@ -1,234 +0,0 @@
-import DeviceManager, { OperationType } from '../device-manager';
-import { setDeviceList } from '../test-utils';
-import { getMediaDevicesApi } from '../support-detection';
-
-describe('DeviceManager', () => {
-  beforeEach(() => {
-    (getMediaDevicesApi() as any).removeAllListeners('devicechange');
-    (getMediaDevicesApi() as any).enumerateDevices.mockClear();
-    setDeviceList([]);
-  });
-
-  const setup = () => {
-    const handler = jest.fn();
-    const devices = new DeviceManager();
-    devices.ondevicechange = handler;
-
-    return {
-      handler,
-      devices,
-    };
-  };
-
-  it('returns the full list of devices when queried', async () => {
-    const { devices } = setup();
-    const expectedDevices = setDeviceList([{ label: 'telescreen' }]);
-
-    await expect(devices.enumerateDevices()).resolves.toEqual(expectedDevices);
-  });
-
-  it('detects device changes between queries', async () => {
-    const { handler, devices } = setup();
-    setDeviceList([{}]);
-
-    const [device] = await devices.enumerateDevices();
-
-    expect(handler).toHaveBeenCalledWith({
-      changes: [{ type: OperationType.Add, device }],
-      devices: [device],
-    });
-  });
-
-  it('does not duplicate change notifications to subscribers', async () => {
-    const { handler, devices } = setup();
-    setDeviceList([{}]);
-
-    await devices.enumerateDevices();
-    await devices.enumerateDevices();
-
-    expect(handler).toHaveBeenCalledTimes(1);
-  });
-
-  it('detects removed devices', async () => {
-    setDeviceList([{}]);
-    const { devices, handler } = setup();
-
-    const [device] = await devices.enumerateDevices();
-    setDeviceList([]);
-
-    handler.mockClear();
-    await devices.enumerateDevices();
-
-    expect(handler).toHaveBeenCalledWith({
-      changes: [{ type: OperationType.Remove, device }],
-      devices: expect.any(Array),
-    });
-  });
-
-  it('correlates identical devices between calls', async () => {
-    const [device] = setDeviceList([{ label: 'first' }]);
-    const { handler, devices } = setup();
-    await devices.enumerateDevices();
-    setDeviceList([device, { label: 'second' }]);
-
-    handler.mockClear();
-    const [, secondDevice] = await devices.enumerateDevices();
-
-    expect(handler).toHaveBeenCalledWith({
-      changes: [{ type: OperationType.Add, device: secondDevice }],
-      devices: expect.any(Array),
-    });
-  });
-
-  it('infers device relationships when the ID was just added', async () => {
-    const { handler, devices } = setup();
-    const kind = 'videoinput' as const;
-    const groupId = 'group-id';
-    const redactedDevice = { label: '', deviceId: '', groupId, kind };
-    const device = {
-      ...redactedDevice,
-      label: 'Creepy Shelf Elf',
-      deviceId: "sh'elf",
-    };
-
-    // Simulates fingerprinting countermeasures.
-    setDeviceList([redactedDevice]);
-    await devices.enumerateDevices();
-
-    // Same device after the first approved `getUserMedia(...)` request.
-    setDeviceList([device]);
-
-    handler.mockClear();
-    await devices.enumerateDevices();
-
-    // It should detect that it's the same device.
-    expect(handler).toHaveBeenCalledWith({
-      devices: expect.any(Array),
-      changes: [
-        {
-          type: OperationType.Update,
-          oldInfo: { ...device, deviceId: null, label: null },
-          newInfo: device,
-        },
-      ],
-    });
-  });
-
-  // *scowls at Safari*
-  it('infers similarity between devices with omitted group IDs', async () => {
-    const redactedDevice = {
-      label: '',
-      deviceId: '',
-      groupId: '',
-      kind: 'audioinput' as const,
-    };
-
-    const device = {
-      ...redactedDevice,
-      label: '3D Scanner',
-      deviceId: 'wec3d',
-    };
-
-    setDeviceList([redactedDevice]);
-    const { handler, devices } = setup();
-    await devices.enumerateDevices();
-
-    setDeviceList([device]);
-    handler.mockClear();
-    await devices.enumerateDevices();
-
-    // It should detect that it's the same device.
-    expect(handler).toHaveBeenCalledWith({
-      devices: expect.any(Array),
-      changes: [
-        {
-          type: OperationType.Update,
-          oldInfo: { ...device, deviceId: null, groupId: null, label: null },
-          newInfo: { ...device, groupId: null },
-        },
-      ],
-    });
-  });
-
-  it('watches the device list for changes at the OS level', async () => {
-    const { handler, devices } = setup();
-    await devices.enumerateDevices();
-
-    handler.mockClear();
-    setDeviceList([{ label: 'Telescope' }]);
-    const [listener] = (getMediaDevicesApi() as any).listeners('devicechange');
-
-    await listener();
-
-    expect(handler).toHaveBeenCalledWith({
-      changes: [expect.objectContaining({ type: OperationType.Add })],
-      devices: expect.any(Array),
-    });
-  });
-
-  it('only watches the device list if there are subscribers', async () => {
-    new DeviceManager();
-
-    setDeviceList([{}]);
-    const [listener] = (getMediaDevicesApi() as any).listeners('devicechange');
-
-    await listener();
-
-    expect(getMediaDevicesApi().enumerateDevices).not.toHaveBeenCalled();
-  });
-
-  it('refreshes the device list after a successful GUM query', async () => {
-    setDeviceList([{ label: '' }]);
-    const { devices } = setup();
-    await devices.getUserMedia({ video: true });
-
-    expect(getMediaDevicesApi().enumerateDevices).toHaveBeenCalled();
-  });
-
-  it('returns the supported constraints when requested', () => {
-    (getMediaDevicesApi() as any).getSupportedConstraints.mockReturnValue({
-      mock: 'supported-constraints',
-    });
-
-    const { devices } = setup();
-    const constraints = devices.getSupportedConstraints();
-
-    expect(constraints).toEqual(
-      navigator.mediaDevices.getSupportedConstraints()
-    );
-  });
-
-  it('returns the display media stream when requested', async () => {
-    const stream = new MediaStream();
-    (getMediaDevicesApi() as any).getDisplayMedia.mockResolvedValue(stream);
-
-    const { devices } = setup();
-
-    await expect(devices.getDisplayMedia()).resolves.toBe(stream);
-  });
-
-  it('refreshes the device list after a successful display query', async () => {
-    setDeviceList([{ label: '' }]);
-    const { devices } = setup();
-    await devices.getDisplayMedia({ video: true });
-
-    expect(getMediaDevicesApi().enumerateDevices).toHaveBeenCalled();
-  });
-
-  it('only refreshes the device list after the first successful GDM', async () => {
-    setDeviceList([{ label: '' }]);
-    const { devices } = setup();
-
-    await devices.getDisplayMedia({ video: true });
-    await devices.getDisplayMedia({ video: true });
-    await devices.getDisplayMedia({ video: true });
-
-    expect(getMediaDevicesApi().enumerateDevices).toHaveBeenCalledTimes(1);
-  });
-
-  it('survives even if the media devices API is unsupported', () => {
-    delete (navigator as any).mediaDevices;
-
-    expect(setup).not.toThrow();
-  });
-});

package/src/__tests__/enumerate-devices.test.ts

@@ -1,58 +0,0 @@
-import enumerateDevices from '../enumerate-devices';
-import { setDeviceList } from '../test-utils';
-
-describe('Device enumeration', () => {
-  beforeEach(() => {
-    setDeviceList([]);
-  });
-
-  it('returns a list of devices', async () => {
-    const device = { label: 'Selfie Stick' };
-    setDeviceList([device]);
-
-    const devices = await enumerateDevices();
-
-    expect(devices).toHaveLength(1);
-    expect(devices[0]).toMatchObject(device);
-  });
-
-  it('explicitly represents obfuscated fields', async () => {
-    setDeviceList([{ label: '', deviceId: '', groupId: '' }]);
-    const [device] = await enumerateDevices();
-
-    expect(device).toMatchObject({
-      label: null,
-      deviceId: null,
-      groupId: null,
-    });
-  });
-
-  it('adds device metadata', async () => {
-    const device = {
-      kind: 'audioinput' as const,
-      label: 'Nest Thermostat',
-      deviceId: 'device-id',
-      groupId: 'group-id',
-    };
-
-    setDeviceList([device]);
-
-    const devices = await enumerateDevices();
-
-    expect(devices[0]).toMatchObject(device);
-  });
-
-  it('strips default meta-devices', async () => {
-    const device = {
-      label: 'Surveillance Camera #451',
-      deviceId: 'device-id',
-    };
-
-    setDeviceList([device, { ...device, deviceId: 'default' }]);
-
-    const devices = await enumerateDevices();
-
-    expect(devices).toHaveLength(1);
-    expect(devices[0]).toMatchObject({ deviceId: device.deviceId });
-  });
-});

package/src/__tests__/get-user-media.test.ts

@@ -1,16 +0,0 @@
-import getUserMedia from '../get-user-media';
-import { getMediaDevicesApi } from '../support-detection';
-
-describe('getUserMedia()', () => {
-  beforeEach(() => {
-    (getMediaDevicesApi() as any).getUserMedia.mockResolvedValue(
-      new MediaStream()
-    );
-  });
-
-  it('returns the media stream', async () => {
-    const stream = await getUserMedia({ video: true });
-
-    expect(stream).toBeInstanceOf(MediaStream);
-  });
-});

package/src/__tests__/support-detection.test.ts

@@ -1,33 +0,0 @@
-import { supportsMediaDevices, getMediaDevicesApi } from '../support-detection';
-
-describe('Support detection', () => {
-  const mockMediaDevices = <T>(MediaDevices: T) => {
-    (navigator as any).mediaDevices = MediaDevices;
-  };
-
-  beforeEach(() => {
-    mockMediaDevices({ mock: 'MediaDevices' });
-  });
-
-  describe('supportsMediaDevices()', () => {
-    it('returns false with no support', () => {
-      mockMediaDevices(null);
-      expect(supportsMediaDevices()).toBe(false);
-    });
-
-    it('returns true when the object exists', () => {
-      expect(supportsMediaDevices()).toBe(true);
-    });
-  });
-
-  describe('getMediaDevicesApi', () => {
-    it('throws if the API is unsupported', () => {
-      (navigator as any).mediaDevices = undefined;
-      expect(getMediaDevicesApi).toThrow(/media ?devices/i);
-    });
-
-    it('returns the media devices API', () => {
-      expect(getMediaDevicesApi()).toBe(navigator.mediaDevices);
-    });
-  });
-});

package/src/device-manager.ts

@@ -1,240 +0,0 @@
-import enumerateDevices, { DeviceInfo } from './enumerate-devices';
-import { getMediaDevicesApi, supportsMediaDevices } from './support-detection';
-import getUserMedia from './get-user-media';
-
-/**
- * Monitors the set of devices for changes and calculates convenient diffs
- * between updates. Steps are taken to handle cross-browser quirks and
- * attempts graceful integration with browser fingerprinting countermeasures.
- */
-export default class DeviceManager {
-  private _knownDevices: Array<DeviceInfo> = [];
-  private _gainedScreenAccessOnce = false;
-
-  /**
-   * 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 = null;
-
-  constructor() {
-    // Listen for changes at the OS level. If the device list changes and
-    // someone's around to see it, refresh the device list. Refreshing has
-    // a side effect of performing a diff and telling all subscribers about
-    // the change.
-    if (supportsMediaDevices()) {
-      getMediaDevicesApi().addEventListener('devicechange', () => {
-        if (this.ondevicechange) {
-          return this.enumerateDevices();
-        }
-
-        return Promise.resolve();
-      });
-    }
-  }
-
-  /**
-   * 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 = async (constraints: MediaStreamConstraints) => {
-    const stream = await getUserMedia(constraints);
-
-    // The browser considers us trusted after the first approved GUM query and
-    // allows access to more information in the device list, which is an
-    // implicit device change event. Refresh to update the cache.
-    //
-    // We do this for every GUM request because some browsers only allow
-    // access to the subset of devices you've been approved for. While
-    // reasonable from a security perspective, it means we're never sure if
-    // the cache is stale.
-    this.enumerateDevices();
-
-    return stream;
-  };
-
-  /**
-   * 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 = async (
-    constraints?: MediaStreamConstraints
-  ): Promise<MediaStream> => {
-    const stream = await getMediaDevicesApi().getDisplayMedia(constraints);
-
-    // Similar to `getUserMedia(...)`, granting access to your screen implies
-    // a certain level of trust. Some browsers will remove the fingerprinting
-    // protections after the first successful call. However, it's unlikely
-    // that another will tell us anything more, so we only refresh devices
-    // after the first success.
-    if (!this._gainedScreenAccessOnce) {
-      this._gainedScreenAccessOnce = true;
-      this.enumerateDevices();
-    }
-
-    return stream;
-  };
-
-  /**
-   * Lists every available hardware device, including microphones, cameras,
-   * and speakers (depending on browser support). May contain redacted
-   * information depending on application permissions.
-   */
-  enumerateDevices = async (): Promise<Array<DeviceInfo>> => {
-    const devices = await enumerateDevices();
-    this._checkForDeviceChanges(devices);
-
-    return devices;
-  };
-
-  /**
-   * 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 => {
-    return getMediaDevicesApi().getSupportedConstraints();
-  };
-
-  private _checkForDeviceChanges(newDevices: Array<DeviceInfo>) {
-    const oldDevices = this._knownDevices;
-    this._knownDevices = newDevices; // Replace the old devices.
-
-    const changes: Array<DeviceChange> = this._calculateDeviceDiff(
-      newDevices,
-      oldDevices
-    );
-
-    if (changes.length) {
-      this.ondevicechange?.({ changes, devices: newDevices });
-    }
-  }
-
-  /**
-   * Note: The device enumeration API may return null values for device IDs
-   * and labels. To avoid creating erroneous "Device Added" notifications,
-   * a best effort should be made to detect when devices are identical.
-   *
-   * Order is significant. Preferred devices are listed first, which helps
-   * correlate devices from permissioned requests with unpermissioned
-   * requests.
-   */
-  private _calculateDeviceDiff(
-    newDevices: Array<DeviceInfo>,
-    oldDevices: Array<DeviceInfo>
-  ): Array<DeviceChange> {
-    const removals = oldDevices.slice();
-    const updates: Array<DeviceChange> = [];
-
-    // If a "new" device exists in the list of old devices, then it obviously
-    // wasn't just added and clearly we haven't removed it either. It's the
-    // same device.
-    const additions = newDevices.filter((newDevice) => {
-      const oldDeviceIndex = removals.findIndex((oldDevice) => {
-        return isIdenticalDevice(newDevice, oldDevice);
-      });
-
-      // Note: Nasty state mutation hides here.
-      // Maps/Sets are out of the question due to poor TS support. Plus IDs
-      // are far too unreliable in this context. Iteration and splice() are
-      // ugly and gross, but they work.
-      if (oldDeviceIndex > -1) {
-        const [oldDevice] = removals.splice(oldDeviceIndex, 1);
-
-        if (newDevice.label !== oldDevice.label) {
-          const update: DeviceUpdateEvent = {
-            type: OperationType.Update,
-            newInfo: newDevice,
-            oldInfo: oldDevice,
-          };
-
-          updates.push(update);
-        }
-      }
-
-      // Only count it as an "addition" if we couldn't find the same device in
-      // the older set.
-      return oldDeviceIndex === -1;
-    });
-
-    return [
-      ...updates,
-
-      // A device was just removed.
-      ...removals.map((device) => {
-        return { type: OperationType.Remove, device } as DeviceRemoveEvent;
-      }),
-
-      // A device was just plugged in.
-      ...additions.map((device) => {
-        return { type: OperationType.Add, device } as DeviceAddEvent;
-      }),
-    ];
-  }
-}
-
-/**
- * Due to fingerprinting countermeasures, the device ID might be an empty
- * string. We have to resort to vague comparisons. After the first successful
- * `getUserMedia(...)` query, the device ID for all related device kinds
- * should be revealed. In that case the new device will have an ID but the old
- * device won't. It should be safe to assume the inverse never happens.
- *
- * Note: Chromium browsers take a private stance by hiding your extra devices.
- * Even if you have a hundred cameras plugged in, until that first GUM query,
- * you'll only see the preferred one. Same for microphones and output devices.
- */
-function isIdenticalDevice(newDevice: DeviceInfo, oldDevice: DeviceInfo) {
-  if (oldDevice.deviceId) {
-    return newDevice.deviceId === oldDevice.deviceId;
-  }
-
-  // These are the only credible fields we have to go on. It may yield a false
-  // positive if you're changing devices before the first GUM query, but since
-  // the lists are ordered by priority, that should be unlikely. It's
-  // certainly preferable to "new device" false positives.
-  function toCrudeId(device: DeviceInfo) {
-    return `${device.kind}:${device.groupId}`;
-  }
-
-  return toCrudeId(newDevice) === toCrudeId(oldDevice);
-}
-
-export type DeviceChange =
-  | DeviceAddEvent
-  | DeviceRemoveEvent
-  | DeviceUpdateEvent;
-
-interface DeviceAddEvent {
-  type: OperationType.Add;
-  device: DeviceInfo;
-}
-
-interface DeviceRemoveEvent {
-  type: OperationType.Remove;
-  device: DeviceInfo;
-}
-
-interface DeviceUpdateEvent {
-  type: OperationType.Update;
-  newInfo: DeviceInfo;
-  oldInfo: DeviceInfo;
-}
-
-export enum OperationType {
-  Add = 'add',
-  Remove = 'remove',
-  Update = 'update',
-}
-
-interface DeviceChangeListener {
-  (update: {
-    changes: Array<DeviceChange>;
-    devices: Array<DeviceInfo>;
-  }): unknown;
-}

package/src/enumerate-devices.ts

@@ -1,72 +0,0 @@
-import { getMediaDevicesApi } from './support-detection';
-
-/**
- * A normalization layer over `MediaDevices.enumerateDevices()`:
- * https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo
- *
- * The API is fraught with cross-browser quirks and fingerprinting blocks.
- * This interface seeks to normalize some of those quirks and make the
- * security tradeoffs obvious.
- */
-export default async function enumerateDevices(): Promise<Array<DeviceInfo>> {
-  const devices = await getMediaDevicesApi().enumerateDevices();
-  return devices.filter(isPhysicalDevice).map(normalizeDeviceInfo);
-}
-
-/**
- * Chromium does this really annoying thing where it duplicates preferred
- * devices by substituting the ID with "default". No other browser does this,
- * and preferred devices are already represented by list order.
- *
- * Since those meta-devices don't add relevant information and risk confusing
- * device UIs, I simply remove them.
- */
-function isPhysicalDevice(device: MediaDeviceInfo) {
-  return device.deviceId !== 'default';
-}
-
-// Make nullable fields explicit.
-function normalizeDeviceInfo(device: MediaDeviceInfo): DeviceInfo {
-  return {
-    label: device.label || null,
-    kind: device.kind as DeviceKind,
-    deviceId: device.deviceId || null,
-    groupId: device.groupId || null,
-  };
-}
-
-export interface DeviceInfo {
-  /**
-   * The device list is obfuscated until you gain elevated permissions.
-   * Browsers will use an empty string for the device label until the first
-   * successful `getUserMedia(...)` request.
-   */
-  label: null | string;
-
-  /**
-   * A unique identifier persistent across sessions. Note: In Chromium
-   * browsers, this can be unset if you haven't received permission for the
-   * media resource yet.
-   */
-  deviceId: null | string;
-
-  /**
-   * 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. Note: Safari
-   * doesn't support group IDs.
-   */
-  groupId: null | string;
-
-  /**
-   * Declares the type of media provided. This covers microphones, cameras,
-   * and speakers.
-   */
-  kind: DeviceKind;
-}
-
-export enum DeviceKind {
-  VideoInput = 'videoinput',
-  AudioInput = 'audioinput',
-  AudioOutput = 'audiooutput',
-}

package/src/get-user-media.ts

@@ -1,7 +0,0 @@
-import { getMediaDevicesApi } from './support-detection';
-
-export default async function getUserMedia(
-  constraints: MediaStreamConstraints
-): Promise<MediaStream> {
-  return getMediaDevicesApi().getUserMedia(constraints);
-}

package/src/index.ts

@@ -1,10 +0,0 @@
-import DeviceManager from './device-manager';
-
-export { supportsMediaDevices } from './support-detection';
-export { DeviceKind } from './enumerate-devices';
-export { OperationType } from './device-manager';
-
-export type { DeviceInfo } from './enumerate-devices';
-export type { DeviceChange } from './device-manager';
-
-export default new DeviceManager();

package/src/support-detection.ts

@@ -1,16 +0,0 @@
-/**
- * Not all browsers support media devices, and some restrict access for
- * insecure sites and private contexts. This is often reflected by removing
- * the `mediaDevices` API entirely.
- */
-export function supportsMediaDevices() {
-  return typeof navigator !== 'undefined' && !!navigator.mediaDevices;
-}
-
-export function getMediaDevicesApi() {
-  if (!supportsMediaDevices()) {
-    throw new Error(`The media devices API isn't supported here.`);
-  }
-
-  return navigator.mediaDevices;
-}