media-devices-util
What is this package for? To get info about available media devices and work with them. You can:
- list available devices
- get default devices
- get audio/video/screen permissions (
mac) - request for audio/video/screen permissions (
mac)
How to use it
Install
npm i -S media-devices-utilUse
Get devices list
const mediaDevicesUtil = require("media-devices-util");
const videoDevices = mediaDevicesUtil.getVideoDevices();
const audioDevices = mediaDevicesUtil.getAudioDevices();
console.log({ audioDevices, videoDevices });
// output on mac:
// {
// audioDevices: [
// {
// id: 'AppleHDAEngineInput:1F,3,0,1,0:1',
// label: 'Built-in Microphone'
// }
// ],
// videoDevices: [
// {
// id: '0x1420000005ac8600',
// label: 'FaceTime HD Camera (Built-in)'
// },
// {
// id: '69733382',
// label: 'Capture screen 0'
// }
// ]
// }
//
// output on windows:
// {
// audioDevices: [
// {
// id: '0',
// label: 'Microphone (High Definition Audio Device)',
// alternativeName: '@device_cm_{33D9A762-90C8-11D0-BD43-00A0C911CE86}\\wave_{B073E9D3-C0A7-4CB0-84E0-F829B281F95F}'
// }
// ],
// videoDevices: [
// {
// id: '\\\\?\\usb#vid_203a&pid_fff9&mi_00#6&fafa70b&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global',
// label: 'FaceTime HD Camera (Built-in)'',
// alternativeName: '@device_pnp_\\\\?\\usb#vid_203a&pid_fff9&mi_00#6&fafa70b&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global'
// }
// ]
// }Request for Camera permissions
const mediaDevicesUtil = require("media-devices-util");
mediaDevicesUtil.requestMediaAuthorization("camera").then((status) => {
if ("AUTHORIZED" === status) {
// permissions granted!
}
});API
media-devices-util object has the following API:
type TDevice = {
// For mac:
// audio/video devices are using the 'uniqueID' property - https://developer.apple.com/documentation/avfoundation/avcapturedevice/1390477-uniqueid
// screen devices are using the 'CGDirectDisplayID' property - https://developer.apple.com/documentation/coregraphics/cgdirectdisplayid
// For win:
// audio devices are using the 'WaveInID' property - https://docs.microsoft.com/en-us/windows/win32/directshow/selecting-a-capture-device
// video devices are using the 'DevicePath' property - https://docs.microsoft.com/en-us/windows/win32/directshow/selecting-a-capture-device
id: string;
// For mac:
// audio/video devices are using the 'localizedName' property - https://developer.apple.com/documentation/avfoundation/avcapturedevice/1388222-localizedname
// screen devices are using the 'Capture screen ' prefix plus device id in 'CGGetActiveDisplayList' - https://developer.apple.com/documentation/coregraphics/1454603-cggetactivedisplaylist
// For win:
// using the 'FriendlyName' property - https://docs.microsoft.com/en-us/windows/win32/directshow/selecting-a-capture-device
label: string;
// For win:
// using the 'GetDisplayName' method's return value - https://docs.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-imoniker-getdisplayname
alternativeName?: string;
}
// AUTHORIZED - permissions granted
// DENIED - permissions denied
// NOT_DETERMINED - permissions not set
declare type TAuthorization = "AUTHORIZED" | "DENIED" | "NOT_DETERMINED";
declare type TMediaType = "camera" | "microphone";
type TMediaDevicesUtil = {
getDefaultVideoDevice(): TDevice;
getDefaultAudioDevice(): TDevice;
getVideoDevices(): TDevice[];
getAudioDevices(): TDevice[];
getScreenAuthorizationStatus(): TAuthorization;
getMediaAuthorizationStatus(mediaType: TMediaType): TAuthorization;
getMediaAuthorizationStatus(): {
camera: TAuthorization;
microphone: TAuthorization;
};
requestScreenAuthorization(): TAuthorization;
requestMediaAuthorization(mediaType: TMediaType): Promise<TAuthorization>;
}getDefaultVideoDevice
Return type: TDevice
Retrieve the default video input device (camera).
For win, taking the first entry of the IEnumMoniker with the CLSID_VideoInputDeviceCategory parameter.
For mac, using the defaultDeviceWithMediaType:AVMediaTypeVideo method for audio/video devices.
getDefaultAudioDevice
Return type: TDevice
Retrieve the default audio input device (microphone).
For win, using the GetDefaultAudioEndpoint method.
For mac, using the defaultDeviceWithMediaType:AVMediaTypeAudio method.
getVideoDevices
Return type: TDevice[]
Retrieve the default video input devices list (cameras, screens, etc.).
For mac, using the devicesWithMediaType:AVMediaTypeVideo method, and the CGGetActiveDisplayList method for screens.
For win, using the IEnumMoniker with the CLSID_VideoInputDeviceCategory parameter.
getAudioDevices
Return type: TDevice[]
Retrieve the default audio input devices list (microphones, virtual devices, etc.).
For mac, using the devicesWithMediaType:AVMediaTypeAudio method.
For win, using the IEnumMoniker with the CLSID_AudioInputDeviceCategory parameter.
getScreenAuthorizationStatus
Return type: TAuthorization
Retrieve current permissions for screen recording.
For mac, using the CGPreflightScreenCaptureAccess method (>=11.0), or will try to match window processes ids (>=10.15), or will return AUTHORIZED.
For win, will always return AUTHORIZED.
getMediaAuthorizationStatus
Return type: TAuthorization | { camera: TAuthorization; microphone: TAuthorization; }
Arguments: (mediaType?: TMediaType)
Retrieve current permissions for audio and/or video usage. If no args passed - will return authorization status for both audio/video.
For mac, using the authorizationStatusForMediaType method.
For win, will always return AUTHORIZED for any type of media.
requestScreenAuthorization
Return type: TAuthorization
Request for screen recording permissions. Will prompt user to modify screen recording permissions config, if possible, otherwise - will open the System Preferences window with Screen Recording tab opened.
For mac, using the CGRequestScreenCaptureAccess method (>=11.0), or will try to use CGDisplayStreamCreate method (>=10.15), or will return AUTHORIZED.
For win, will always return AUTHORIZED.
requestMediaAuthorization
Return type: Promise<TAuthorization>
Arguments: (mediaType: TMediaType)
Request for microphone or camera recording permissions. Will prompt user to modify screen recording permissions config, if possible, otherwise - will open the System Preferences window with Camera or Microphone tab opened.
For mac, using the requestAccessForMediaType method (>=10.14), or will return AUTHORIZED.
For win, will always return AUTHORIZED for any type of media.
FFMPEG
When using an ffmpeg or other libs to capture audio/video devices, you first need to obtain a list of available devices and their labels (IDs).
And when running ffmpeg to just get the devices list - it takes too long, because a lot of overhead ffmpeg lib actions are taken.
Using media-devices-util is much, much faster.
Usage example
Let's imagine, that we want to capture the default audio and default video device with ffmpeg:
const spawn = require("child_process").spawn;
const mediaDevicesUtil = require("media-devices-util");
const defaultVideoDevice = mediaDevicesUtil.getDefaultVideoDevice();
const defaultAudioDevice = mediaDevicesUtil.getDefaultAudioDevice();
// for MacOS, you can use the 'label' prop, and the item's index (if used with getVideoDevices/getAudioDevices):
const ffmpegWinProcess = spawn("ffmpeg", ["-f", "avfoundation", "-i", `${defaultVideoDevice.label}:${defaultAudioDevice.label}`, "video.mkv"]);
// for Windows, you should use the 'label' or the 'alternativeName' prop:
const ffmpegMacProcess = spawn("ffmpeg", ["-f", "dshow", "-i", `video="${defaultVideoDevice.label}":audio="${defaultAudioDevice.alternativeName}"`, "video.mkv"]);Alternatives
You can use the ffmpeg's list_devices option (for mac or win), and parse it's output to get the list itself.
Also, you can use other ffmpeg command abstractions (like ffmpeg and fluent-ffmpeg).
In any case, the list_devices in ffmpeg lib is something like a crunch, and the lib itself doesn't provide a programmatic way to enumerate devices.
Or use other ffmpeg nodejs bindings lib.
Next Steps
- Improve Windows API (especially permissions), if possible
- Add listeners for devices and/or permissions