man > ffmpeg-devices(1)

man perldoc info pydoc3 ri search

📘 NAME

ffmpeg-devices - FFmpeg devices

🚀 Quick Reference

Use Case	Command	Description
🎥 Capture from ALSA audio device	ffmpeg -f alsa -i hw:0 output.wav	Record audio from ALSA card 0
📷 List input devices (decklink)	ffmpeg -sources decklink	Show available DeckLink input devices
🖥️ Capture X11 screen region	ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg	Grab X11 display area
🎬 Record from DirectShow (Windows)	ffmpeg -f dshow -i video="Camera":audio="Microphone" out.avi	Capture video and audio from named devices
🔊 Play audio to ALSA output	ffmpeg -i INPUT -f alsa default	Play audio on default ALSA device
🖼️ Show video in SDL window	ffmpeg -i INPUT -f sdl "SDL output"	Display video in an SDL window

📋 DESCRIPTION

This document describes the input and output devices provided by the libavdevice library.

⚙️ DEVICE OPTIONS

The libavdevice library provides the same interface as libavformat. Namely, an input device is considered like a demuxer, and an output device like a muxer, and the interface and generic device options are the same provided by libavformat (see the ffmpeg-formats manual).

In addition each input or output device may support so-called private options, which are specific for that component.

Options may be set by specifying -option value in the FFmpeg tools, or by setting the value explicitly in the device "AVFormatContext" options or using the libavutil/opt.h API for programmatic use.

🎥 INPUT DEVICES

Input devices are configured elements in FFmpeg which enable accessing the data coming from a multimedia device attached to your system.

When you configure your FFmpeg build, all the supported input devices are enabled by default. You can list all available ones using the configure option "--list-indevs".

You can disable all the input devices using the configure option "--disable-indevs", and selectively enable an input device using the option "--enable-indev=INDEV", or you can disable a particular input device using the option "--disable-indev=INDEV".

The option "-devices" of the ff* tools will display the list of supported input devices.

🔊 alsa

ALSA (Advanced Linux Sound Architecture) input device.

To enable this input device during configuration you need libasound installed on your system.

This device allows capturing from an ALSA device. The name of the device to capture has to be an ALSA card identifier.

An ALSA identifier has the syntax:

hw:<CARD>[,<DEV>[,<SUBDEV>]]

where the DEV and SUBDEV components are optional.

The three arguments (in order: CARD,DEV,SUBDEV) specify card number or identifier, device number and subdevice number (-1 means any).

To see the list of cards currently recognized by your system check the files /proc/asound/cards and /proc/asound/devices.

For example to capture with ffmpeg from an ALSA device with card id 0, you may run the command:

ffmpeg -f alsa -i hw:0 alsaout.wav

For more information see: http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html

Options

• sample_rate 🎶 Set the sample rate in Hz. Default is 48000.
• channels 🔊 Set the number of channels. Default is 2.

📱 android_camera

Android camera input device.

This input devices uses the Android Camera2 NDK API which is available on devices with API level 24+. The availability of android_camera is autodetected during configuration.

This device allows capturing from all cameras on an Android device, which are integrated into the Camera2 NDK API.

The available cameras are enumerated internally and can be selected with the camera_index parameter. The input file string is discarded.

Generally the back facing camera has index 0 while the front facing camera has index 1.

Options

• video_size 📐 Set the video size given as a string such as 640x480 or hd720. Falls back to the first available configuration reported by Android if requested video size is not available or by default.
• framerate ⏱️ Set the video framerate. Falls back to the first available configuration reported by Android if requested framerate is not available or by default (-1).
• camera_index 📷 Set the index of the camera to use. Default is 0.
• input_queue_size 📦 Set the maximum number of frames to buffer. Default is 5.

🍎 avfoundation

AVFoundation input device.

AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS.

The input filename has to be given in the following syntax:

-i "[[VIDEO]:[AUDIO]]"

The first entry selects the video input while the latter selects the audio input. The stream has to be specified by the device name or the device index as shown by the device list. Alternatively, the video and/or audio input device can be chosen by index using the

-video_device_index <INDEX>

and/or

-audio_device_index <INDEX>

overriding any device name or index given in the input filename.

All available devices can be enumerated by using -list_devices true, listing all device names and corresponding indices.

There are two device name aliases:

• default 🏠 Select the AVFoundation default device of the corresponding type.
• none 🚫 Do not record the corresponding media type. Equivalent to specifying an empty device name or index.

Options

• -list_devices <TRUE|FALSE> 📋 If set to true, a list of all available input devices is given.
• -video_device_index <INDEX> 🎬 Specify the video device by its index.
• -audio_device_index <INDEX> 🎤 Specify the audio device by its index.
• -pixel_format <FORMAT> 🖼️ Request the video device to use a specific pixel format. Available: monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0, bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10, yuv420p, nv12, yuyv422, gray.
• -framerate ⏱️ Set the grabbing frame rate. Default is "ntsc" (30000/1001).
• -video_size 📐 Set the video frame size.
• -capture_cursor 🖱️ Capture the mouse pointer. Default is 0.
• -capture_mouse_clicks 🖱️ Capture the screen mouse clicks. Default is 0.
• -capture_raw_data 📦 Capture the raw device data. Default is 0.

Examples

• 📋 Print list of devices and exit:

  $ ffmpeg -f avfoundation -list_devices true -i ""

• 🎥 Record video from device 0 and audio from device 0:

  $ ffmpeg -f avfoundation -i "0:0" out.avi

• 📹 Record video from device 2 and audio from device 1:

  $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi

• 🖼️ Record with pixel format bgr0, no audio:

  $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi

• 📦 Record raw DV data:

  $ ffmpeg -f avfoundation -capture_raw_data true -i "zr100:none" out.dv

🖥️ bktr

BSD video input device.

Options

• framerate ⏱️ Set the frame rate.
• video_size 📐 Set the video frame size. Default is "vga".
• standard 📺 Available values: pal, ntsc, secam, paln, palm, ntscj.

🎬 decklink (input)

The decklink input device provides capture capabilities for Blackmagic DeckLink devices.

To enable this input device, you need the Blackmagic DeckLink SDK and you need to configure with the appropriate "--extra-cflags" and "--extra-ldflags". On Windows, you need to run the IDL files through widl.

DeckLink is very picky about the formats it supports. Pixel format of the input can be set with raw_format. Framerate and video size must be determined for your device with -list_formats 1. Audio sample rate is always 48 kHz and the number of channels can be 2, 8 or 16. Note that all audio channels are bundled in one single audio track.

Options

• list_devices 📋 If set to true, print a list of devices and exit. Deprecated, use "-sources".
• list_formats 📋 If set to true, print a list of supported formats and exit.
• format_code <FourCC> 🎥 Sets the input video format by FourCC. Use list_formats to see supported values.
• raw_format 🖼️ Sets the pixel format of captured video. Values: auto, uyvy422, yuv422p10, argb, bgra, rgb10.
• teletext_lines 📄 If nonzero, capture teletext stream from VBI. Bitmask of lines 6-22,318-335. Special values: all, standard.
• channels 🔊 Number of audio channels (2, 8, or 16). Default 2.
• duplex_mode 🔄 Duplex mode: unset, half, full.
• timecode_format ⏱️ Timecode type: none, rp188vitc, rp188vitc2, rp188ltc, rp188hfr, rp188any, vitc, vitc2, serial.
• video_input 📹 Source: unset, sdi, hdmi, optical_sdi, component, composite, s_video.
• audio_input 🎤 Source: unset, embedded, aes_ebu, analog, analog_xlr, analog_rca, microphone.
• video_pts ⏲️ Timestamp source: video, audio, reference, wallclock, abs_wallclock.
• audio_pts ⏲️ Timestamp source: video, audio, reference, wallclock, abs_wallclock.
• draw_bars 🟦 Draw color bars on signal loss (default true).
• queue_size 📦 Max input buffer size in bytes (default 1073741824).
• audio_depth 🎚️ Audio sample bit depth: 16 or 32 (default 16).
• decklink_copyts 📋 Forward timestamps without removing offset (default false).
• timestamp_align ⏲️ Capture start time alignment in seconds (default 0).
• wait_for_tc (bool) ⏳ Drop frames until timecode received (default false).
• enable_klv(bool) 📄 Extract KLV data from VANC (default false).

Examples

• 📋 List input devices:

  ffmpeg -sources decklink

• 📋 List supported formats:

  ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro'

• 🎥 Capture 1080i50:

  ffmpeg -format_code Hi50 -f decklink -i 'Intensity Pro' -c:a copy -c:v copy output.avi

• 🎥 Capture 1080i50 10 bit:

  ffmpeg -raw_format yuv422p10 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi

• 🎥 Capture with 16 audio channels:

  ffmpeg -channels 16 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi

🪟 dshow

Windows DirectShow input device.

DirectShow support is enabled when FFmpeg is built with the mingw-w64 project. Currently only audio and video devices are supported.

Multiple devices may be opened as separate inputs, but they may also be opened on the same input, which should improve synchronism between them.

The input name should be in the format:

<TYPE>=<NAME>[:<TYPE>=<NAME>]

where TYPE can be either audio or video, and NAME is the device's name or alternative name.

Options

• video_size 📐 Set the video size.
• framerate ⏱️ Set the frame rate.
• sample_rate 🎶 Set the sample rate (Hz) of captured audio.
• sample_size 🎚️ Set the sample size (bits) of captured audio.
• channels 🔊 Set the number of channels.
• list_devices 📋 If set to true, print a list of devices and exit.
• list_options 📋 If set to true, print a list of selected device's options and exit.
• video_device_number 🔢 Set video device number for devices with same name (starts at 0).
• audio_device_number 🔢 Set audio device number for devices with same name.
• pixel_format 🖼️ Select pixel format for raw video.
• audio_buffer_size 📦 Set audio device buffer size in milliseconds.
• video_pin_name 📌 Select video capture pin by name.
• audio_pin_name 📌 Select audio capture pin by name.
• crossbar_video_input_pin_number 🔌 Select video input pin number for crossbar device.
• crossbar_audio_input_pin_number 🔌 Select audio input pin number for crossbar device.
• show_video_device_dialog 🖥️ Popup dialog to change video filter properties.
• show_audio_device_dialog 🎛️ Popup dialog to change audio filter properties.
• show_video_crossbar_connection_dialog 🔌 Popup dialog to modify crossbar pin routings for video.
• show_audio_crossbar_connection_dialog 🔌 Popup dialog to modify crossbar pin routings for audio.
• show_analog_tv_tuner_dialog 📺 Popup dialog to modify TV channels and frequencies.
• show_analog_tv_tuner_audio_dialog 🎛️ Popup dialog to modify TV audio.
• audio_device_load 📂 Load audio capture filter device from file.
• audio_device_save 💾 Save audio capture filter device to file.
• video_device_load 📂 Load video capture filter device from file.
• video_device_save 💾 Save video capture filter device to file.

Examples

• 📋 Print list of devices:

  $ ffmpeg -list_devices true -f dshow -i dummy

• 📹 Open video device "Camera":

  $ ffmpeg -f dshow -i video="Camera"

• 📹 Open second video device "Camera":

  $ ffmpeg -f dshow -video_device_number 1 -i video="Camera"

• 🔊 Open video and audio:

  $ ffmpeg -f dshow -i video="Camera":audio="Microphone"

• 📋 Print options for selected device:

  $ ffmpeg -list_options true -f dshow -i video="Camera"

• 📌 Specify pin names and alternative device name:

  $ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@device_pnp_\\?\pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\{ca465100-deb0-4d59-818f-8c477184adf6}":audio="Microphone"

• 🔄 Configure crossbar device:

  $ ffmpeg -f dshow -show_video_device_dialog true -crossbar_video_input_pin_number 0 -crossbar_audio_input_pin_number 3 -i video="AVerMedia BDA Analog Capture":audio="AVerMedia BDA Analog Capture"

🖥️ fbdev (input)

Linux framebuffer input device.

The Linux framebuffer is a graphic hardware-independent abstraction layer to show graphics on a computer monitor, typically on the console. It is accessed through a file device node, usually /dev/fb0.

For more detailed information read the file Documentation/fb/framebuffer.txt included in the Linux source tree.

See also http://linux-fbdev.sourceforge.net/, and fbset(1).

To record from the framebuffer device /dev/fb0 with ffmpeg:

ffmpeg -f fbdev -framerate 10 -i /dev/fb0 out.avi

You can take a single screenshot image with the command:

ffmpeg -f fbdev -framerate 1 -i /dev/fb0 -frames:v 1 screenshot.jpeg

Options

• framerate ⏱️ Set the frame rate. Default is 25.

🖥️ gdigrab

Win32 GDI-based screen capture device.

This device allows you to capture a region of the display on Windows.

There are two options for the input filename:

desktop

or

title=<window_title>

The first option will capture the entire desktop, or a fixed region of the desktop. The second option will instead capture the contents of a single window, regardless of its position on the screen.

For example, to grab the entire desktop using ffmpeg:

ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg

Grab a 640x480 region at position "10,20":

ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg

Grab the contents of the window named "Calculator"

ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg

Options

• draw_mouse 🖱️ Specify whether to draw the mouse pointer. Use 0 to not draw. Default is 1.
• framerate ⏱️ Set the grabbing frame rate. Default is "ntsc" (30000/1001).
• show_region 📍 Show grabbed region on screen (1 to enable). Incompatible with window capture.
• video_size 📐 Set the video frame size. Default is full screen or window.
• offset_x ↔️ Set horizontal offset from left edge of screen.
• offset_y ↕️ Set vertical offset from top edge of screen.

🔥 iec61883

FireWire DV/HDV input device using libiec61883.

To enable this input device, you need libiec61883, libraw1394 and libavc1394 installed on your system. Use the configure option "--enable-libiec61883" to compile with the device enabled.

The iec61883 capture device supports capturing from a video device connected via IEEE1394 (FireWire), using libiec61883 and the new Linux FireWire stack (juju). This is the default DV/HDV input method in Linux Kernel 2.6.37 and later, since the old FireWire stack was removed.

Specify the FireWire port to be used as input file, or "auto" to choose the first port connected.

Options

• dvtype 📼 Override autodetection of DV/HDV. Values: auto, dv, hdv.
• dvbuffer 📦 Set maximum size of buffer for incoming data, in frames.
• dvguid 🔑 Select the capture device by specifying its GUID.

Examples

• 📺 Grab and show input:

  ffplay -f iec61883 -i auto

• 🎥 Grab and record with packet buffer 100000 for HDV:

  ffmpeg -f iec61883 -i auto -dvbuffer 100000 out.mpg

🎵 jack

JACK input device.

To enable this input device during configuration you need libjack installed on your system.

A JACK input device creates one or more JACK writable clients, one for each audio channel, with name client_name:input_N, where client_name is the name provided by the application, and N is a number which identifies the channel. Each writable client will send the acquired data to the FFmpeg input device.

Once you have created one or more JACK readable clients, you need to connect them to one or more JACK writable clients.

To connect or disconnect JACK clients you can use the jack_connect and jack_disconnect programs, or do it through a graphical interface, for example with qjackctl.

To list the JACK clients and their properties you can invoke the command jack_lsp.

Follows an example which shows how to capture a JACK readable client with ffmpeg.

# Create a JACK writable client with name "ffmpeg".
$ ffmpeg -f jack -i ffmpeg -y out.wav

# Start the sample jack_metro readable client.
$ jack_metro -b 120 -d 0.2 -f 4000

# List the current JACK clients.
$ jack_lsp -c
system:capture_1
system:capture_2
system:playback_1
system:playback_2
ffmpeg:input_1
metro:120_bpm

# Connect metro to the ffmpeg writable client.
$ jack_connect metro:120_bpm ffmpeg:input_1

For more information read: http://jackaudio.org/

Options

• channels 🔊 Set the number of channels. Default is 2.

🖥️ kmsgrab

KMS video input device.

Captures the KMS scanout framebuffer associated with a specified CRTC or plane as a DRM object that can be passed to other hardware functions.

Requires either DRM master or CAP_SYS_ADMIN to run.

If you don't understand what all of that means, you probably don't want this. Look at x11grab instead.

Options

• device 💻 DRM device to capture on. Defaults to /dev/dri/card0.
• format 🖼️ Pixel format of the framebuffer. Defaults to bgr0.
• format_modifier 🖼️ Format modifier to signal on output frames.
• crtc_id 🆔 KMS CRTC ID to define the capture source.
• plane_id 🆔 KMS plane ID to define the capture source.
• framerate ⏱️ Framerate to capture at. Defaults to 30.

Examples

• 📹 Capture from first active plane, download to frames:

  ffmpeg -f kmsgrab -i - -vf 'hwdownload,format=bgr0' output.mp4

• 🎥 Capture from CRTC ID 42 at 60fps, map to VAAPI, encode H.264:

  ffmpeg -crtc_id 42 -framerate 60 -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,scale_vaapi=w=1920:h=1080:format=nv12' -c:v h264_vaapi output.mp4

• ✂️ Capture and crop middle quarter of 1920x1080:

  ffmpeg -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,crop=960:540:480:270,scale_vaapi=960:540:nv12' -c:v h264_vaapi output.mp4

🎨 lavfi

Libavfilter input virtual device.

This input device reads data from the open output pads of a libavfilter filtergraph.

For each filtergraph open output, the input device will create a corresponding stream which is mapped to the generated output. Currently only video data is supported. The filtergraph is specified through the option graph.

Options

• graph 🧩 Specify the filtergraph to use as input. Each video open output must be labelled by a unique string of the form "outN". The suffix "+subcc" can be appended to create an extra stream with closed captions.
• graph_file 📄 Set the filename of the filtergraph to be read.
• dumpgraph 🐛 Dump graph to stderr.

Examples

• 🎨 Create color video stream and play:

  ffplay -f lavfi -graph "color=c=pink [out0]" dummy

• 🎨 Same using filename:

  ffplay -f lavfi color=c=pink

• 🔀 Three different test sources:

  ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3

• 🎵 Read audio from file:

  ffplay -f lavfi "amovie=test.wav"

• 📽️ Read audio and video:

  ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]"

• 📄 Dump frames and closed captions:

  ffmpeg -f lavfi -i "movie=test.ts[out0+subcc]" -map v frame%08d.png -map s -c copy -f rawvideo subcc.bin

💿 libcdio

Audio-CD input device based on libcdio.

To enable this input device during configuration you need libcdio installed on your system. It requires the configure option "--enable-libcdio".

This device allows playing and grabbing from an Audio-CD.

For example to copy with ffmpeg the entire Audio-CD in /dev/sr0, you may run the command:

ffmpeg -f libcdio -i /dev/sr0 cd.wav

Options

• speed ⏩ Set drive reading speed (CD-ROM speed units). Default 0 (fastest).
• paranoia_mode 🛡️ Set paranoia recovery mode flags. Values: disable, verify, overlap, neverskip, full. Default disable.

📹 libdc1394

IIDC1394 input device, based on libdc1394 and libraw1394.

Requires the configure option "--enable-libdc1394".

Options

• framerate ⏱️ Set the frame rate. Default is "ntsc" (30000/1001).
• pixel_format 🖼️ Select the pixel format. Default is "uyvy422".
• video_size 📐 Set the video size. Default is "qvga".

🎧 openal

The OpenAL input device provides audio capture on all systems with a working OpenAL 1.1 implementation.

To enable this input device during configuration, you need OpenAL headers and libraries installed on your system, and need to configure FFmpeg with "--enable-openal".

OpenAL headers and libraries should be provided as part of your OpenAL implementation, or as an additional download (an SDK). Depending on your installation you may need to specify additional flags via the "--extra-cflags" and "--extra-ldflags" for allowing the build system to locate the OpenAL headers and libraries.

An incomplete list of OpenAL implementations follows:

• Creative 🎵 Official Windows implementation, hardware acceleration.
• OpenAL Soft 🔓 Portable, open source (LGPL) implementation.
• Apple 🍎 Part of Core Audio on Mac OS X.

This device allows one to capture from an audio input device handled through OpenAL.

You need to specify the name of the device to capture in the provided filename. If the empty string is provided, the device will automatically select the default device. You can get the list of the supported devices by using the option list_devices.

Options

• channels 🔊 Set the number of channels (1 or 2). Default 2.
• sample_size 🎚️ Set the sample size (8 or 16 bits). Default 16.
• sample_rate 🎶 Set the sample rate (Hz). Default 44.1k.
• list_devices 📋 If set to true, print a list of devices and exit.

Examples

• 📋 Print list of devices:

  $ ffmpeg -list_devices true -f openal -i dummy out.ogg

• 🎧 Capture from device:

  $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg

• 🔇 Capture from default device:

  $ ffmpeg -f openal -i '' out.ogg

• 🔀 Capture from two devices simultaneously:

  $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg

🔊 oss (input)

Open Sound System input device.

The filename to provide to the input device is the device node representing the OSS input device, and is usually set to /dev/dsp.

For example to grab from /dev/dsp using ffmpeg use the command:

ffmpeg -f oss -i /dev/dsp /tmp/oss.wav

For more information about OSS see: http://manuals.opensound.com/usersguide/dsp.html

Options

• sample_rate 🎶 Set the sample rate in Hz. Default is 48000.
• channels 🔊 Set the number of channels. Default is 2.

🎵 pulse (input)

PulseAudio input device.

To enable this output device you need to configure FFmpeg with "--enable-libpulse".

The filename to provide to the input device is a source device or the string "default"

To list the PulseAudio source devices and their properties you can invoke the command pactl list sources.

More information about PulseAudio can be found on http://www.pulseaudio.org.

Options

• server 🌐 Connect to a specific PulseAudio server (IP address). Default server used if not provided.
• name 🏷️ Specify the application name (default: "LIBAVFORMAT_IDENT").
• stream_name 🏷️ Specify the stream name (default: "record").
• sample_rate 🎶 Specify the samplerate in Hz (default 48kHz).
• channels 🔊 Specify the channels (default 2).
• frame_size 📦 Specify the number of bytes per frame (default 1024).
• fragment_size 📦 Specify the minimal buffering fragment in PulseAudio (affects latency).
• wallclock ⏲️ Set initial PTS using current time. Default is 1.

Examples

• 🔊 Record from default device:

  ffmpeg -f pulse -i default /tmp/pulse.wav

🔊 sndio (input)

sndio input device.

To enable this input device during configuration you need libsndio installed on your system.

The filename to provide to the input device is the device node representing the sndio input device, and is usually set to /dev/audio0.

For example to grab from /dev/audio0 using ffmpeg use the command:

ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav

Options

• sample_rate 🎶 Set the sample rate in Hz. Default is 48000.
• channels 🔊 Set the number of channels. Default is 2.

📹 video4linux2, v4l2

Video4Linux2 input video device.

"v4l2" can be used as alias for "video4linux2".

If FFmpeg is built with v4l-utils support (by using the "--enable-libv4l2" configure option), it is possible to use it with the "-use_libv4l2" input device option.

The name of the device to grab is a file device node, usually Linux systems tend to automatically create such nodes when the device (e.g. an USB webcam) is plugged into the system, and has a name of the kind /dev/videoN, where N is a number associated to the device.

Video4Linux2 devices usually support a limited set of widthxheight sizes and frame rates. You can check which are supported using -list_formats all for Video4Linux2 devices. Some devices, like TV cards, support one or more standards. It is possible to list all the supported standards using -list_standards all.

The time base for the timestamps is 1 microsecond. Depending on the kernel version and configuration, the timestamps may be derived from the real time clock (origin at the Unix Epoch) or the monotonic clock (origin usually at boot time, unaffected by NTP or manual changes to the clock). The -timestamps abs or -ts abs option can be used to force conversion into the real time clock.

Some usage examples of the video4linux2 device with ffmpeg and ffplay:

• 📋 List supported formats:

  ffplay -f video4linux2 -list_formats all /dev/video0

• 📺 Grab and show input:

  ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0

• 🎥 Grab and record:

  ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg

For more information about Video4Linux, check http://linuxtv.org/.

Options

• standard 📺 Set the standard. Use list_standards to get list.
• channel 📺 Set the input channel number. Default -1 (previous).
• video_size 📐 Set the video frame size.
• pixel_format 🖼️ Select the pixel format (raw video only).
• input_format 🖼️ Set the preferred pixel format or codec name.
• framerate ⏱️ Set the preferred video frame rate.
• list_formats 📋 List available formats and exit. Values: all, raw, compressed.
• list_standards 📋 List supported standards and exit. Value: all.
• timestamps, ts ⏲️ Set type of timestamps. Values: default, abs, mono2abs.
• use_libv4l2 🔧 Use libv4l2 conversion functions. Default 0.

🪟 vfwcap

VfW (Video for Windows) capture input device.

The filename passed as input is the capture driver number, ranging from 0 to 9. You may use "list" as filename to print a list of drivers. Any other filename will be interpreted as device number 0.

Options

• video_size 📐 Set the video frame size.
• framerate ⏱️ Set the grabbing frame rate. Default is "ntsc" (30000/1001).

🖥️ x11grab

X11 video input device.

To enable this input device during configuration you need libxcb installed on your system. It will be automatically detected during configuration.

This device allows one to capture a region of an X11 display.

The filename passed as input has the syntax:

[<hostname>]:<display_number>.<screen_number>[+<x_offset>,<y_offset>]

hostname:display_number.screen_number specifies the X11 display name of the screen to grab from. hostname can be omitted, and defaults to "localhost". The environment variable DISPLAY contains the default display name.

x_offset and y_offset specify the offsets of the grabbed area with respect to the top-left border of the X11 screen. They default to 0.

Check the X11 documentation (e.g. man X) for more detailed information.

Use the xdpyinfo program for getting basic information about the properties of your X11 display (e.g. grep for "name" or "dimensions").

For example to grab from :0.0 using ffmpeg:

ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg

Grab at position "10,20":

ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg

Options

• select_region 🖱️ Specify whether to select the grabbing area graphically using the pointer. 1 prompts user to select. Default 0.
• draw_mouse 🖱️ Specify whether to draw the mouse pointer. 0 to not draw. Default 1.
• follow_mouse 🖱️ Make the grabbed area follow the mouse. Can be "centered" or a number of pixels.
• framerate ⏱️ Set the grabbing frame rate. Default is "ntsc" (30000/1001).
• show_region 📍 Show grabbed region on screen. 1 to enable.
• region_border 🖼️ Set region border thickness if -show_region 1 is used. Range 1 to 128, default 3.
• window_id 🪟 Grab this window instead of the whole screen. Default 0 (root window).
• video_size 📐 Set the video frame size. Default is full desktop or window.
• grab_x ↔️ Set the grabbing region x offset.
• grab_y ↕️ Set the grabbing region y offset.

📤 OUTPUT DEVICES

Output devices are configured elements in FFmpeg that can write multimedia data to an output device attached to your system.

When you configure your FFmpeg build, all the supported output devices are enabled by default. You can list all available ones using the configure option "--list-outdevs".

You can disable all the output devices using the configure option "--disable-outdevs", and selectively enable an output device using the option "--enable-outdev=OUTDEV", or you can disable a particular input device using the option "--disable-outdev=OUTDEV".

The option "-devices" of the ff* tools will display the list of enabled output devices.

🔊 alsa (output)

ALSA (Advanced Linux Sound Architecture) output device.

Examples

• 🔊 Play on default ALSA device:

  ffmpeg -i INPUT -f alsa default

• 🔊 Play on soundcard 1, device 7:

  ffmpeg -i INPUT -f alsa hw:1,7

🍎 AudioToolbox

AudioToolbox output device.

Allows native output to CoreAudio devices on OSX.

The output filename can be empty (or "-") to refer to the default system output device or a number that refers to the device index as shown using: "-list_devices true".

Alternatively, the audio input device can be chosen by index using the

-audio_device_index <INDEX>

overriding any device name or index given in the input filename.

All available devices can be enumerated by using -list_devices true, listing all device names, UIDs and corresponding indices.

Options

• -audio_device_index <INDEX> 🎧 Specify the audio device by its index.

Examples

• 📋 Print list of devices and output sine wave:

  $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -list_devices true -

• 🎵 Output sine wave to device index 2:

  $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -audio_device_index 2 -

🖼️ caca

CACA output device.

This output device allows one to show a video stream in CACA window. Only one CACA window is allowed per application, so you can have only one instance of this output device in an application.

To enable this output device you need to configure FFmpeg with "--enable-libcaca". libcaca is a graphics library that outputs text instead of pixels.

For more information about libcaca, check: http://caca.zoy.org/wiki/libcaca

Options

• window_title 🏷️ Set the CACA window title.
• window_size 📐 Set the CACA window size (widthxheight or abbreviation).
• driver 🖥️ Set display driver.
• algorithm 🎨 Set dithering algorithm.
• antialias 🖼️ Set antialias method.
• charset 🔤 Set which characters are used.
• color 🎨 Set color to be used.
• list_drivers 📋 If set to true, print a list of available drivers and exit.
• list_dither 📋 List available dither options (argument: "algorithms", "antialiases", "charsets", "colors").

Examples

• 🖼️ Show video in CACA window (80x25):

  ffmpeg -i INPUT -c:v rawvideo -pix_fmt rgb24 -window_size 80x25 -f caca -

• 📋 List drivers:

  ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_drivers true -

• 📋 List dither colors:

  ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_dither colors -

🎬 decklink (output)

The decklink output device provides playback capabilities for Blackmagic DeckLink devices.

To enable this output device, you need the Blackmagic DeckLink SDK and you need to configure with the appropriate "--extra-cflags" and "--extra-ldflags". On Windows, you need to run the IDL files through widl.

DeckLink is very picky about the formats it supports. Pixel format is always uyvy422, framerate, field order and video size must be determined for your device with -list_formats 1. Audio sample rate is always 48 kHz.

Options

• list_devices 📋 If set to true, print a list of devices and exit. Deprecated, use "-sinks".
• list_formats 📋 If set to true, print a list of supported formats and exit.
• preroll ⏳ Amount of time to preroll video in seconds. Defaults to 0.5.
• duplex_mode 🔄 Sets the decklink device duplex mode: unset, half, full.
• timing_offset ⏲️ Sets the genlock timing pixel offset on the used output.

Examples

• 📋 List output devices:

  ffmpeg -sinks decklink

• 📋 List supported formats:

  ffmpeg -i test.avi -f decklink -list_formats 1 'DeckLink Mini Monitor'

• 🎬 Play video clip:

  ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 'DeckLink Mini Monitor'

• 🎬 Play with non-standard framerate or size:

  ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 -s 720x486 -r 24000/1001 'DeckLink Mini Monitor'

🖥️ fbdev (output)

Linux framebuffer output device.

The Linux framebuffer is a graphic hardware-independent abstraction layer to show graphics on a computer monitor, typically on the console. It is accessed through a file device node, usually /dev/fb0.

For more detailed information read the file Documentation/fb/framebuffer.txt included in the Linux source tree.

Options

• xoffset ↔️ Set x coordinate of top left corner. Default 0.
• yoffset ↕️ Set y coordinate of top left corner. Default 0.

Examples

• 🖥️ Play file on framebuffer:

  ffmpeg -re -i INPUT -c:v rawvideo -pix_fmt bgra -f fbdev /dev/fb0

See also http://linux-fbdev.sourceforge.net/, and fbset(1).

🖼️ opengl

OpenGL output device.

To enable this output device you need to configure FFmpeg with "--enable-opengl".

This output device allows one to render to OpenGL context. Context may be provided by application or default SDL window is created.

When device renders to external context, application must implement handlers for following messages: "AV_DEV_TO_APP_CREATE_WINDOW_BUFFER", "AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER", "AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER", "AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER". Application is also required to inform a device about current resolution by sending "AV_APP_TO_DEV_WINDOW_SIZE" message.

Options

• background 🎨 Set background color. Black is default.
• no_window 🚫 Disables default SDL window when set to non-zero. Application must provide OpenGL context and callbacks.
• window_title 🏷️ Set the SDL window title.
• window_size 📐 Set preferred window size (widthxheight or abbreviation).

Examples

• 🖼️ Play file on SDL window using OpenGL:

  ffmpeg -i INPUT -f opengl "window title"

🔊 oss (output)

OSS (Open Sound System) output device.

(No additional options listed in the original.)

🎵 pulse (output)

PulseAudio output device.

To enable this output device you need to configure FFmpeg with "--enable-libpulse".

More information about PulseAudio can be found on http://www.pulseaudio.org

Options

• server 🌐 Connect to a specific PulseAudio server (IP address).
• name 🏷️ Specify the application name (default: "LIBAVFORMAT_IDENT").
• stream_name 🏷️ Specify the stream name (default: output name).
• device 🔊 Specify the device to use. List with pactl list sinks.
• buffer_size 📦 Control the size of the PulseAudio buffer in bytes.
• buffer_duration ⏱️ Control the duration of the PulseAudio buffer in milliseconds.
• prebuf 📦 Specify pre-buffering size in bytes.
• minreq 📦 Specify minimum request size in bytes.

Examples

• 🔊 Play on default device:

  ffmpeg -i INPUT -f pulse "stream name"

🖼️ sdl

SDL (Simple DirectMedia Layer) output device.

"sdl2" can be used as alias for "sdl".

This output device allows one to show a video stream in an SDL window. Only one SDL window is allowed per application, so you can have only one instance of this output device in an application.

To enable this output device you need libsdl installed on your system when configuring your build.

For more information about SDL, check: http://www.libsdl.org/

Options

• window_title 🏷️ Set the SDL window title.
• icon_title 🏷️ Set the name of the iconified SDL window.
• window_size 📐 Set the SDL window size (widthxheight or abbreviation).
• window_x ↔️ Set the X position of the window on the screen.
• window_y ↕️ Set the Y position of the window on the screen.
• window_fullscreen 🖥️ Set fullscreen mode when non-zero.
• window_enable_quit 🚪 Enable quit action (default 1).

Interactive commands

• q, ESC ❌ Quit the device immediately.

Examples

• 🖼️ Show video in SDL window:

  ffmpeg -i INPUT -c:v rawvideo -pix_fmt yuv420p -window_size qcif -f sdl "SDL output"

🔊 sndio (output)

sndio audio output device.

(No additional options listed in the original.)

📹 v4l2 (output)

Video4Linux2 output device.

(No additional options listed in the original.)

🖼️ xv

XV (XVideo) output device.

This output device allows one to show a video stream in a X Window System window.

Options

• display_name 🖥️ Specify the hardware display name (e.g., "dual-headed:0.1"). Defaults to DISPLAY environment variable.
• window_id 🪟 When set to non-zero, use existing window with provided window_id.
• window_size 📐 Set the created window size (widthxheight or abbreviation).
• window_x ↔️ Set the X window offset for the created window.
• window_y ↕️ Set the Y window offset for the created window.
• window_title 🏷️ Set the window title.

Examples

• 📽️ Decode, display and encode simultaneously:

  ffmpeg -i INPUT OUTPUT -f xv display

• 🖼️ Decode and display to multiple X11 windows:

  ffmpeg -i INPUT -f xv normal -vf negate -f xv negated

📚 SEE ALSO

ffmpeg(1), ffplay(1), ffprobe(1), libavdevice(3)

👤 AUTHORS

The FFmpeg developers.

For details about the authorship, see the Git history of the project (git://source.ffmpeg.org/ffmpeg), e.g. by typing the command git log in the FFmpeg source directory, or browsing the online repository at http://source.ffmpeg.org.

Maintainers for the specific components are listed in the file MAINTAINERS in the source code tree.

📘 NAME 🚀 Quick Reference 📋 DESCRIPTION ⚙️ DEVICE OPTIONS 🎥 INPUT DEVICES 📤 OUTPUT DEVICES 📚 SEE ALSO 👤 AUTHORS