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