media-utils/index.d.ts

Opinionated collection of user media utils by @dapotatoman

/** Stops and removes given audio stream
 * @param stream - The stream to be destoyed
 * @param emitEvent - Triggers events such as `ended` and `removetrack`
 */
declare function destroyStream(stream?: MediaStream, emitEvent?: boolean): void;
/** Stops and removes given audio streams
 * @param streams - Array of streams to be destoyed
 * @param emitEvent - Triggers events such as `ended` and `removetrack`
 */
declare function destroyStreams(streams?: MediaStream[], emitEvent?: boolean): void;
/** @returns Media stream using `getUserMedia` */
declare function getStream(constraints?: MediaStreamConstraints): Promise<MediaStream>;

/** Amplifies audio track of given stream */
declare function amplifyStream(stream: MediaStream, level: number): {
    destroy: () => void;
    setLevel: (value: number) => void;
};
/**
 * @returns New stream with all audio tracks combined in the video stream
 */
declare function muxStreams(videoStream: MediaStream, ...audioStream: MediaStream[]): MediaStream;

/** Fires when all tracks of a stream ends */
declare function onTracksEnded(stream: MediaStream, callback: () => void): void;
/**
 * Fires when any track of a stream ends
 * @param destroy Whether to destroy the stream when any track stops
 * @returns {Function} Function that stops the watcher
 */
declare function onAnyTrackEnded(stream: MediaStream, callback: () => void, destroy?: boolean): () => void;

/**
 * @returns All/Preferred devices using `enumerateDevices`
 */
declare function getDevices(kind?: MediaDeviceKind): Promise<MediaDeviceInfo[]>;
declare function getCategorizedDevices(): Promise<Record<MediaDeviceKind, MediaDeviceInfo[]>>;
/**
 * @param key - Key param to be matched
 * @param value - Value of the key param to be matched
 * @returns Filtered media devices
 */
declare function getFilteredDevices<T extends keyof MediaDeviceInfo>(key: T, value: MediaDeviceInfo[T]): Promise<MediaDeviceInfo[]>;
/**
 * Finds a device from all or provided media devices
 * @param key - Key param to be matched
 * @param value - Value of the key param to be matched
 * @param devices - If passed, device will be searched from provided devices
 * @returns Media device
 */
declare function getDevice<T extends keyof MediaDeviceInfo>(key: T, value: MediaDeviceInfo[T], devices?: MediaDeviceInfo[]): Promise<MediaDeviceInfo[]>;

declare class EventBus<Type extends string> {
    private bus;
    on(type: Type, listener: VoidFunction): void;
    once(type: Type, listener: VoidFunction): void;
    off(type: Type, listener: VoidFunction): void;
    emit(type: Type, data?: any): void;
}

/**
 * Triggers callback when a media device changes
 * @returns void function to destroy the listener
 */
declare function onDeviceChange(listener: (this: MediaDevices, ev: Event) => any, options?: boolean | AddEventListenerOptions): () => void;
declare function watchDevice<T extends keyof MediaDeviceInfo>(key: T, value: MediaDeviceInfo[T]): EventBus<"added" | "removed">;
/**
 * Triggers callback when a media device changes
 * @param immediate Triggers the `onUpdate` callback on init
 * @returns void function to destroy the listener
 */
declare function watchDevicesList(onUpdate: (data: MediaDeviceInfo[]) => void, immediate?: true): () => void;

declare type MediaPermission = 'camera' | 'microphone';
/** Requests all media permissions such as: `camera` `microphone` */
declare function requestMediaPermissions(): Promise<boolean>;
/** Requests a specific media permission */
declare function requestPermission(name: MediaPermission): Promise<boolean>;
/**
 * Watch a media permission
 * @param name Name of the permission to watch
 * @param onChange Callback function that is triggered when permission is changed
 * @param immediate Invoke `onChange` immediately on initialization
 * @returns Function that destroys the watcher when invoked
 */
declare function watchPermission(name: MediaPermission, onChange: (status: PermissionStatus) => void, immediate?: boolean): () => void;
/**
 * Watch multiple media permissions
 * @param names Names of the permissions to watch
 * @param onChange Callback function that is triggered when a permission is changed
 * @param immediate Invoke `onChange` immediately on initialization for respective permissions
 * @returns Function that destroys the watcher when invoked
 */
declare function watchPermissions(names: MediaPermission[], onChange: (name: MediaPermission, status: PermissionStatus) => void, immediate?: boolean): () => void;
/** Check if permission has been given for a media (camera/microphone) */
declare function hasPermission(name: MediaPermission): Promise<boolean>;
/** Check if both microphone and camera permissions are given */
declare function hasMediaPermissions(name: MediaPermission): Promise<boolean>;

export { MediaPermission, amplifyStream, destroyStream, destroyStreams, getCategorizedDevices, getDevice, getDevices, getFilteredDevices, getStream, hasMediaPermissions, hasPermission, muxStreams, onAnyTrackEnded, onDeviceChange, onTracksEnded, requestMediaPermissions, requestPermission, watchDevice, watchDevicesList, watchPermission, watchPermissions };