ffmpeg/doc/outdevs.texi

   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