Skip to content

devices.rst

Latest commit

 

History

History
109 lines (74 loc) · 3.41 KB

devices.rst

File metadata and controls

109 lines (74 loc) · 3.41 KB

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. :py:mod:`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, :py:mod:`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 :py:mod:`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

.. autosummary::
   :nosignatures:
   :recursive:

   ffmpegio.devices.scan
   ffmpegio.devices.list_sources
   ffmpegio.devices.list_sinks
   ffmpegio.devices.list_source_options
   ffmpegio.devices.list_sink_options
   ffmpegio.devices.resolve_source
   ffmpegio.devices.resolve_sink
.. autofunction:: ffmpegio.devices.scan
.. autofunction:: ffmpegio.devices.list_sources
.. autofunction:: ffmpegio.devices.list_sinks
.. autofunction:: ffmpegio.devices.list_source_options
.. autofunction:: ffmpegio.devices.list_sink_options
.. autofunction:: ffmpegio.devices.resolve_source
.. autofunction:: ffmpegio.devices.resolve_sink