1@chapter Output Devices 2@c man begin OUTPUT DEVICES 3 4Output devices are configured elements in FFmpeg that can write 5multimedia data to an output device attached to your system. 6 7When you configure your FFmpeg build, all the supported output devices 8are enabled by default. You can list all available ones using the 9configure option "--list-outdevs". 10 11You can disable all the output devices using the configure option 12"--disable-outdevs", and selectively enable an output device using the 13option "--enable-outdev=@var{OUTDEV}", or you can disable a particular 14input device using the option "--disable-outdev=@var{OUTDEV}". 15 16The option "-devices" of the ff* tools will display the list of 17enabled output devices. 18 19A description of the currently available output devices follows. 20 21@section alsa 22 23ALSA (Advanced Linux Sound Architecture) output device. 24 25@subsection Examples 26 27@itemize 28@item 29Play a file on default ALSA device: 30@example 31ffmpeg -i INPUT -f alsa default 32@end example 33 34@item 35Play a file on soundcard 1, audio device 7: 36@example 37ffmpeg -i INPUT -f alsa hw:1,7 38@end example 39@end itemize 40 41@section AudioToolbox 42 43AudioToolbox output device. 44 45Allows native output to CoreAudio devices on OSX. 46 47The output filename can be empty (or @code{-}) to refer to the default system output device or a number that refers to the device index as shown using: @code{-list_devices true}. 48 49Alternatively, the audio input device can be chosen by index using the 50@option{ 51 -audio_device_index <INDEX> 52} 53, overriding any device name or index given in the input filename. 54 55All available devices can be enumerated by using @option{-list_devices true}, listing 56all device names, UIDs and corresponding indices. 57 58@subsection Options 59 60AudioToolbox supports the following options: 61 62@table @option 63 64@item -audio_device_index <INDEX> 65Specify the audio device by its index. Overrides anything given in the output filename. 66 67@end table 68 69@subsection Examples 70 71@itemize 72 73@item 74Print the list of supported devices and output a sine wave to the default device: 75@example 76$ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -list_devices true - 77@end example 78 79@item 80Output a sine wave to the device with the index 2, overriding any output filename: 81@example 82$ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -audio_device_index 2 - 83@end example 84 85@end itemize 86 87@section caca 88 89CACA output device. 90 91This output device allows one to show a video stream in CACA window. 92Only one CACA window is allowed per application, so you can 93have only one instance of this output device in an application. 94 95To enable this output device you need to configure FFmpeg with 96@code{--enable-libcaca}. 97libcaca is a graphics library that outputs text instead of pixels. 98 99For more information about libcaca, check: 100@url{http://caca.zoy.org/wiki/libcaca} 101 102@subsection Options 103 104@table @option 105 106@item window_title 107Set the CACA window title, if not specified default to the filename 108specified for the output device. 109 110@item window_size 111Set the CACA window size, can be a string of the form 112@var{width}x@var{height} or a video size abbreviation. 113If not specified it defaults to the size of the input video. 114 115@item driver 116Set display driver. 117 118@item algorithm 119Set dithering algorithm. Dithering is necessary 120because the picture being rendered has usually far more colours than 121the available palette. 122The accepted values are listed with @code{-list_dither algorithms}. 123 124@item antialias 125Set antialias method. Antialiasing smoothens the rendered 126image and avoids the commonly seen staircase effect. 127The accepted values are listed with @code{-list_dither antialiases}. 128 129@item charset 130Set which characters are going to be used when rendering text. 131The accepted values are listed with @code{-list_dither charsets}. 132 133@item color 134Set color to be used when rendering text. 135The accepted values are listed with @code{-list_dither colors}. 136 137@item list_drivers 138If set to @option{true}, print a list of available drivers and exit. 139 140@item list_dither 141List available dither options related to the argument. 142The argument must be one of @code{algorithms}, @code{antialiases}, 143@code{charsets}, @code{colors}. 144@end table 145 146@subsection Examples 147 148@itemize 149@item 150The following command shows the @command{ffmpeg} output is an 151CACA window, forcing its size to 80x25: 152@example 153ffmpeg -i INPUT -c:v rawvideo -pix_fmt rgb24 -window_size 80x25 -f caca - 154@end example 155 156@item 157Show the list of available drivers and exit: 158@example 159ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_drivers true - 160@end example 161 162@item 163Show the list of available dither colors and exit: 164@example 165ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_dither colors - 166@end example 167@end itemize 168 169@section decklink 170 171The decklink output device provides playback capabilities for Blackmagic 172DeckLink devices. 173 174To enable this output device, you need the Blackmagic DeckLink SDK and you 175need to configure with the appropriate @code{--extra-cflags} 176and @code{--extra-ldflags}. 177On Windows, you need to run the IDL files through @command{widl}. 178 179DeckLink is very picky about the formats it supports. Pixel format is always 180uyvy422, framerate, field order and video size must be determined for your 181device with @command{-list_formats 1}. Audio sample rate is always 48 kHz. 182 183@subsection Options 184 185@table @option 186 187@item list_devices 188If set to @option{true}, print a list of devices and exit. 189Defaults to @option{false}. This option is deprecated, please use the 190@code{-sinks} option of ffmpeg to list the available output devices. 191 192@item list_formats 193If set to @option{true}, print a list of supported formats and exit. 194Defaults to @option{false}. 195 196@item preroll 197Amount of time to preroll video in seconds. 198Defaults to @option{0.5}. 199 200@item duplex_mode 201Sets the decklink device duplex mode. Must be @samp{unset}, @samp{half} or @samp{full}. 202Defaults to @samp{unset}. 203 204@item timing_offset 205Sets the genlock timing pixel offset on the used output. 206Defaults to @samp{unset}. 207 208@end table 209 210@subsection Examples 211 212@itemize 213 214@item 215List output devices: 216@example 217ffmpeg -sinks decklink 218@end example 219 220@item 221List supported formats: 222@example 223ffmpeg -i test.avi -f decklink -list_formats 1 'DeckLink Mini Monitor' 224@end example 225 226@item 227Play video clip: 228@example 229ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 'DeckLink Mini Monitor' 230@end example 231 232@item 233Play video clip with non-standard framerate or video size: 234@example 235ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 -s 720x486 -r 24000/1001 'DeckLink Mini Monitor' 236@end example 237 238@end itemize 239 240@section fbdev 241 242Linux framebuffer output device. 243 244The Linux framebuffer is a graphic hardware-independent abstraction 245layer to show graphics on a computer monitor, typically on the 246console. It is accessed through a file device node, usually 247@file{/dev/fb0}. 248 249For more detailed information read the file 250@file{Documentation/fb/framebuffer.txt} included in the Linux source tree. 251 252@subsection Options 253@table @option 254 255@item xoffset 256@item yoffset 257Set x/y coordinate of top left corner. Default is 0. 258@end table 259 260@subsection Examples 261Play a file on framebuffer device @file{/dev/fb0}. 262Required pixel format depends on current framebuffer settings. 263@example 264ffmpeg -re -i INPUT -c:v rawvideo -pix_fmt bgra -f fbdev /dev/fb0 265@end example 266 267See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1). 268 269@section opengl 270OpenGL output device. 271 272To enable this output device you need to configure FFmpeg with @code{--enable-opengl}. 273 274This output device allows one to render to OpenGL context. 275Context may be provided by application or default SDL window is created. 276 277When device renders to external context, application must implement handlers for following messages: 278@code{AV_DEV_TO_APP_CREATE_WINDOW_BUFFER} - create OpenGL context on current thread. 279@code{AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER} - make OpenGL context current. 280@code{AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER} - swap buffers. 281@code{AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER} - destroy OpenGL context. 282Application is also required to inform a device about current resolution by sending @code{AV_APP_TO_DEV_WINDOW_SIZE} message. 283 284@subsection Options 285@table @option 286 287@item background 288Set background color. Black is a default. 289@item no_window 290Disables default SDL window when set to non-zero value. 291Application must provide OpenGL context and both @code{window_size_cb} and @code{window_swap_buffers_cb} callbacks when set. 292@item window_title 293Set the SDL window title, if not specified default to the filename specified for the output device. 294Ignored when @option{no_window} is set. 295@item window_size 296Set preferred window size, can be a string of the form widthxheight or a video size abbreviation. 297If not specified it defaults to the size of the input video, downscaled according to the aspect ratio. 298Mostly usable when @option{no_window} is not set. 299 300@end table 301 302@subsection Examples 303Play a file on SDL window using OpenGL rendering: 304@example 305ffmpeg -i INPUT -f opengl "window title" 306@end example 307 308@section oss 309 310OSS (Open Sound System) output device. 311 312@section pulse 313 314PulseAudio output device. 315 316To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}. 317 318More information about PulseAudio can be found on @url{http://www.pulseaudio.org} 319 320@subsection Options 321@table @option 322 323@item server 324Connect to a specific PulseAudio server, specified by an IP address. 325Default server is used when not provided. 326 327@item name 328Specify the application name PulseAudio will use when showing active clients, 329by default it is the @code{LIBAVFORMAT_IDENT} string. 330 331@item stream_name 332Specify the stream name PulseAudio will use when showing active streams, 333by default it is set to the specified output name. 334 335@item device 336Specify the device to use. Default device is used when not provided. 337List of output devices can be obtained with command @command{pactl list sinks}. 338 339@item buffer_size 340@item buffer_duration 341Control the size and duration of the PulseAudio buffer. A small buffer 342gives more control, but requires more frequent updates. 343 344@option{buffer_size} specifies size in bytes while 345@option{buffer_duration} specifies duration in milliseconds. 346 347When both options are provided then the highest value is used 348(duration is recalculated to bytes using stream parameters). If they 349are set to 0 (which is default), the device will use the default 350PulseAudio duration value. By default PulseAudio set buffer duration 351to around 2 seconds. 352 353@item prebuf 354Specify pre-buffering size in bytes. The server does not start with 355playback before at least @option{prebuf} bytes are available in the 356buffer. By default this option is initialized to the same value as 357@option{buffer_size} or @option{buffer_duration} (whichever is bigger). 358 359@item minreq 360Specify minimum request size in bytes. The server does not request less 361than @option{minreq} bytes from the client, instead waits until the buffer 362is free enough to request more bytes at once. It is recommended to not set 363this option, which will initialize this to a value that is deemed sensible 364by the server. 365 366@end table 367 368@subsection Examples 369Play a file on default device on default server: 370@example 371ffmpeg -i INPUT -f pulse "stream name" 372@end example 373 374@section sdl 375 376SDL (Simple DirectMedia Layer) output device. 377 378"sdl2" can be used as alias for "sdl". 379 380This output device allows one to show a video stream in an SDL 381window. Only one SDL window is allowed per application, so you can 382have only one instance of this output device in an application. 383 384To enable this output device you need libsdl installed on your system 385when configuring your build. 386 387For more information about SDL, check: 388@url{http://www.libsdl.org/} 389 390@subsection Options 391 392@table @option 393 394@item window_title 395Set the SDL window title, if not specified default to the filename 396specified for the output device. 397 398@item icon_title 399Set the name of the iconified SDL window, if not specified it is set 400to the same value of @var{window_title}. 401 402@item window_size 403Set the SDL window size, can be a string of the form 404@var{width}x@var{height} or a video size abbreviation. 405If not specified it defaults to the size of the input video, 406downscaled according to the aspect ratio. 407 408@item window_x 409@item window_y 410Set the position of the window on the screen. 411 412@item window_fullscreen 413Set fullscreen mode when non-zero value is provided. 414Default value is zero. 415 416@item window_enable_quit 417Enable quit action (using window button or keyboard key) 418when non-zero value is provided. 419Default value is 1 (enable quit action) 420@end table 421 422@subsection Interactive commands 423 424The window created by the device can be controlled through the 425following interactive commands. 426 427@table @key 428@item q, ESC 429Quit the device immediately. 430@end table 431 432@subsection Examples 433 434The following command shows the @command{ffmpeg} output is an 435SDL window, forcing its size to the qcif format: 436@example 437ffmpeg -i INPUT -c:v rawvideo -pix_fmt yuv420p -window_size qcif -f sdl "SDL output" 438@end example 439 440@section sndio 441 442sndio audio output device. 443 444@section v4l2 445 446Video4Linux2 output device. 447 448@section xv 449 450XV (XVideo) output device. 451 452This output device allows one to show a video stream in a X Window System 453window. 454 455@subsection Options 456 457@table @option 458@item display_name 459Specify the hardware display name, which determines the display and 460communications domain to be used. 461 462The display name or DISPLAY environment variable can be a string in 463the format @var{hostname}[:@var{number}[.@var{screen_number}]]. 464 465@var{hostname} specifies the name of the host machine on which the 466display is physically attached. @var{number} specifies the number of 467the display server on that host machine. @var{screen_number} specifies 468the screen to be used on that server. 469 470If unspecified, it defaults to the value of the DISPLAY environment 471variable. 472 473For example, @code{dual-headed:0.1} would specify screen 1 of display 4740 on the machine named ``dual-headed''. 475 476Check the X11 specification for more detailed information about the 477display name format. 478 479@item window_id 480When set to non-zero value then device doesn't create new window, 481but uses existing one with provided @var{window_id}. By default 482this options is set to zero and device creates its own window. 483 484@item window_size 485Set the created window size, can be a string of the form 486@var{width}x@var{height} or a video size abbreviation. If not 487specified it defaults to the size of the input video. 488Ignored when @var{window_id} is set. 489 490@item window_x 491@item window_y 492Set the X and Y window offsets for the created window. They are both 493set to 0 by default. The values may be ignored by the window manager. 494Ignored when @var{window_id} is set. 495 496@item window_title 497Set the window title, if not specified default to the filename 498specified for the output device. Ignored when @var{window_id} is set. 499@end table 500 501For more information about XVideo see @url{http://www.x.org/}. 502 503@subsection Examples 504 505@itemize 506@item 507Decode, display and encode video input with @command{ffmpeg} at the 508same time: 509@example 510ffmpeg -i INPUT OUTPUT -f xv display 511@end example 512 513@item 514Decode and display the input video to multiple X11 windows: 515@example 516ffmpeg -i INPUT -f xv normal -vf negate -f xv negated 517@end example 518@end itemize 519 520@c man end OUTPUT DEVICES 521