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