Hardware I/O Device Enumeration

FFmpeg supports a number of hardware I/O devices, from which video or audio data are read (sources) and to which data are written (sinks). For each device, which is specified via -f option, some of device hardware name must be obtained via FFmpeg commands:

ffmpeg -sources
ffmpeg -sinks

If devices do not support these newer interfaces, via device-specific listing commands such as

ffmpeg -f dshow -list_devices true -i dummy
ffmpeg -f avfoundation -list_devices true -i ""

Moreover, some devices provide a query interface for the capability of individual hardware:

ffmpeg -list_options true -f dshow -i video="Camera"
ffmpeg -f video4linux2 -list_formats all /dev/video0

For multi-hardware use, the hardware configuration must be scanned and chosen for each computer even within a same OS. ffmpegio.devices module is intended to abstract the hardware selection process via unified naming scheme following the stream specifiers. Device supports are implemented via plugin module, so user can implement interface for unsupported devices.

Note

Currently, only Windows DirectShow source device (-f dshow) is supported. Developing device plugins, especially those on MacOS, requires user feedback and involvement. If you want a specific device to be supported, please post an issue on GitHub to initiate the process.

How to Use

By default, ffmpegio does not scan the system for supported devices. User must initialize the enumeration:

import ffmpegio

ffmpegio.devices.scan()

Once the system is scanned, the lists of sources and sinks can be obtained:

sources = ffmpegio.devices.list_sources()

The returned variable is a dict:

{('dshow', 'a:0'): 'Microphone (Realtek High Definition Audio)',
 ('dshow', 'v:0'): 'WebCam SC-10HDP12B24N'}

Given the enumeration, the enumerated device can be used as the url in any ffmpegio functions interacting with FFmpeg. For example:

# capture 10 seconds of audio
fs, x = ffmpegio.audio.read('a:0', f_in='dshow', t_in=10)

# stream webcam video feed for
with ffmpegio.open('v:0', 'vr', f_in='dshow') as dev:
    for i, frame in enumerate(dev):
        print(f'Frame {i}: {frame.shape}')

# save video and audio to mp4 file
# - if a device support multiple streams, specify their enums separated by '|'
ffmpegio.transcode('v:0|a:0', 'captured.mp4', f_in='dshow', t_in=10)

References

`ffmpegio.devices.scan`	scans the system for input/output hardware
`ffmpegio.devices.list_sources`	list enumerated source hardware devices
`ffmpegio.devices.list_sinks`	list enumerated sink hardware devices
`ffmpegio.devices.list_source_options`	list supported options of enumerated source hardware
`ffmpegio.devices.list_sink_options`	list supported options of enumerated sink hardware
`ffmpegio.devices.resolve_source`	resolve source enumeration
`ffmpegio.devices.resolve_sink`	resolve sink enumeration

ffmpegio.devices.scan()

scans the system for input/output hardware

This function must be called by user to enable device enumeration in ffmpegio. Also, none of functions in ffmpegio.devices module will return meaningful outputs until scan is called. Likewise, scan() must run again after a change in hardware to reflect the change.

The devices are enumerated according to the outputs of outputs ffmpeg -sources and ffmpeg -sinks calls for the devices supporting this fairly new FFmpeg interface. Additional hardware configurations are detected by registered plugins with hooks device_source_api or device_sink_api.

Currently Supported Devices

Windows: dshow Mac: tbd Linux: tbd

ffmpegio.devices.list_sources(dev=None, mtype=None, return_nested=False)

list enumerated source hardware devices

Parameters:

dev ("video", "audio", optional) – ffmpeg device name, defaults to None
mtype – media type, defaults to None
return_nested (bool, optional) – True to return results in nested dict, defaults to False

Returns:

dict of names of supported hardware, keyed by a tuple of the device name and enumeration, or nested dicts. If dev is specified, dict of enumerated hardware devices and their names

Return type:

dict(tuple(str,str),str) or dict(str,dict(str,str)) or dict(str,str)

ffmpegio.devices.list_sinks(dev=None, mtype=None, return_nested=False)

list enumerated sink hardware devices

Parameters:

dev ("video", "audio", optional) – ffmpeg device name, default to None
mtype – media type, default to None
return_nested (bool, optional) – True to return results in nested dict, defaults to False

Returns:

dict of names of supported hardware, keyed by a tuple of the device name and enumeration, or nested dicts. If dev is specified, dict of enumerated hardware devices and their names

Return type:

dict(tuple(str,str),str) or dict(str,dict(str,str)) or dict(str,str)

ffmpegio.devices.list_source_options(device, enum)

list supported options of enumerated source hardware

Parameters:

device (str) – device name
enum (str) – hardware specifier, e.g., v:0, a:0

Returns:

list of supported option combinations. If option values are tuple it indicates the min and max range of the option value.

Return type:

list[dict]

ffmpegio.devices.list_sink_options(device, enum)

list supported options of enumerated sink hardware

Parameters:

device (str) – device name
enum (str) – hardware specifier, e.g., v:0, a:0

Returns:

list of supported option combinations. If option values are tuple it indicates the min and max range of the option value.

Return type:

list[dict]

ffmpegio.devices.resolve_source(url, opts)

resolve source enumeration

Parameters:

url (str) – input url, possibly device enum
opts (dict) – input options

Returns:

possibly modified url and opts

Return type:

tuple[str,dict]

This function is called by ffmpeg.compose() to convert device enumeration back to url expected by ffmpeg

The device name (-f) could be provided via opts[‘f’] or encoded as a part of enumeration

ffmpegio.devices.resolve_sink(url, opts)

resolve sink enumeration

Parameters:

url (str) – output url, possibly device enum
opts (dict) – output options

Returns:

possibly modified url and opts

Return type:

tuple[str,dict]

This function is called by ffmpeg.compose() to convert device enumeration back to url expected by ffmpeg