git.sesse.net Git - ffmpeg/blob - 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 "-formats" of the ff* tools will display the list of
  17 enabled output devices (amongst the muxers).
  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 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 fbdev
 124
 125 Linux framebuffer output device.
 126
 127 The Linux framebuffer is a graphic hardware-independent abstraction
 128 layer to show graphics on a computer monitor, typically on the
 129 console. It is accessed through a file device node, usually
 130 @file{/dev/fb0}.
 131
 132 For more detailed information read the file
 133 @file{Documentation/fb/framebuffer.txt} included in the Linux source tree.
 134
 135 @subsection Options
 136 @table @option
 137
 138 @item xoffset
 139 @item yoffset
 140 Set x/y coordinate of top left corner. Default is 0.
 141 @end table
 142
 143 @subsection Examples
 144 Play a file on framebuffer device @file{/dev/fb0}.
 145 Required pixel format depends on current framebuffer settings.
 146 @example
 147 ffmpeg -re -i INPUT -vcodec rawvideo -pix_fmt bgra -f fbdev /dev/fb0
 148 @end example
 149
 150 See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1).
 151
 152 @section opengl
 153 OpenGL output device.
 154
 155 To enable this output device you need to configure FFmpeg with @code{--enable-opengl}.
 156
 157 Device allows to render to OpenGL context.
 158 Context may be provided by application or default SDL window is created.
 159
 160 When device renders to external context, application must implement handlers for following messages:
 161 @code{AV_CTL_MESSAGE_CREATE_WINDOW_BUFFER} - create OpenGL context on current thread.
 162 @code{AV_CTL_MESSAGE_PREPARE_WINDOW_BUFFER} - make OpenGL context current.
 163 @code{AV_CTL_MESSAGE_DISPLAY_WINDOW_BUFFER} - swap buffers.
 164 @code{AV_CTL_MESSAGE_DESTROY_WINDOW_BUFFER} - destroy OpenGL context.
 165 Application is also required to inform a device about current resolution by sending @code{AV_DEVICE_WINDOW_RESIZED} message.
 166
 167 @subsection Options
 168 @table @option
 169
 170 @item background
 171 Set background color. Black is a default.
 172 @item no_window
 173 Disables default SDL window when set to non-zero value.
 174 Application must provide OpenGL context and both @code{window_size_cb} and @code{window_swap_buffers_cb} callbacks when set.
 175 @item window_title
 176 Set the SDL window title, if not specified default to the filename specified for the output device.
 177 Ignored when @option{no_window} is set.
 178
 179 @end table
 180
 181 @subsection Examples
 182 Play a file on SDL window using OpenGL rendering:
 183 @example
 184 ffmpeg  -i INPUT -f opengl "window title"
 185 @end example
 186
 187 @section oss
 188
 189 OSS (Open Sound System) output device.
 190
 191 @section pulse
 192
 193 PulseAudio output device.
 194
 195 To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}.
 196
 197 More information about PulseAudio can be found on @url{http://www.pulseaudio.org}
 198
 199 @subsection Options
 200 @table @option
 201
 202 @item server
 203 Connect to a specific PulseAudio server, specified by an IP address.
 204 Default server is used when not provided.
 205
 206 @item name
 207 Specify the application name PulseAudio will use when showing active clients,
 208 by default it is the @code{LIBAVFORMAT_IDENT} string.
 209
 210 @item stream_name
 211 Specify the stream name PulseAudio will use when showing active streams,
 212 by default it is set to the specified output name.
 213
 214 @item device
 215 Specify the device to use. Default device is used when not provided.
 216 List of output devices can be obtained with command @command{pactl list sinks}.
 217
 218 @item buffer_size
 219 @item buffer_duration
 220 Control the size and duration of the PulseAudio buffer. A small buffer
 221 gives more control, but requires more frequent updates.
 222
 223 @option{buffer_size} specifies size in bytes while
 224 @option{buffer_duration} specifies duration in milliseconds.
 225
 226 When both options are provided then the highest value is used
 227 (duration is recalculated to bytes using stream parameters). If they
 228 are set to 0 (which is default), the device will use the default
 229 PulseAudio duration value. By default PulseAudio set buffer duration
 230 to around 2 seconds.
 231 @end table
 232
 233 @subsection Examples
 234 Play a file on default device on default server:
 235 @example
 236 ffmpeg  -i INPUT -f pulse "stream name"
 237 @end example
 238
 239 @section sdl
 240
 241 SDL (Simple DirectMedia Layer) output device.
 242
 243 This output device allows to show a video stream in an SDL
 244 window. Only one SDL window is allowed per application, so you can
 245 have only one instance of this output device in an application.
 246
 247 To enable this output device you need libsdl installed on your system
 248 when configuring your build.
 249
 250 For more information about SDL, check:
 251 @url{http://www.libsdl.org/}
 252
 253 @subsection Options
 254
 255 @table @option
 256
 257 @item window_title
 258 Set the SDL window title, if not specified default to the filename
 259 specified for the output device.
 260
 261 @item icon_title
 262 Set the name of the iconified SDL window, if not specified it is set
 263 to the same value of @var{window_title}.
 264
 265 @item window_size
 266 Set the SDL window size, can be a string of the form
 267 @var{width}x@var{height} or a video size abbreviation.
 268 If not specified it defaults to the size of the input video,
 269 downscaled according to the aspect ratio.
 270
 271 @item window_fullscreen
 272 Set fullscreen mode when non-zero value is provided.
 273 Default value is zero.
 274 @end table
 275
 276 @subsection Interactive commands
 277
 278 The window created by the device can be controlled through the
 279 following interactive commands.
 280
 281 @table @key
 282 @item q, ESC
 283 Quit the device immediately.
 284 @end table
 285
 286 @subsection Examples
 287
 288 The following command shows the @command{ffmpeg} output is an
 289 SDL window, forcing its size to the qcif format:
 290 @example
 291 ffmpeg -i INPUT -vcodec rawvideo -pix_fmt yuv420p -window_size qcif -f sdl "SDL output"
 292 @end example
 293
 294 @section sndio
 295
 296 sndio audio output device.
 297
 298 @section xv
 299
 300 XV (XVideo) output device.
 301
 302 This output device allows to show a video stream in a X Window System
 303 window.
 304
 305 @subsection Options
 306
 307 @table @option
 308 @item display_name
 309 Specify the hardware display name, which determines the display and
 310 communications domain to be used.
 311
 312 The display name or DISPLAY environment variable can be a string in
 313 the format @var{hostname}[:@var{number}[.@var{screen_number}]].
 314
 315 @var{hostname} specifies the name of the host machine on which the
 316 display is physically attached. @var{number} specifies the number of
 317 the display server on that host machine. @var{screen_number} specifies
 318 the screen to be used on that server.
 319
 320 If unspecified, it defaults to the value of the DISPLAY environment
 321 variable.
 322
 323 For example, @code{dual-headed:0.1} would specify screen 1 of display
 324 0 on the machine named ``dual-headed''.
 325
 326 Check the X11 specification for more detailed information about the
 327 display name format.
 328
 329 @item window_size
 330 Set the created window size, can be a string of the form
 331 @var{width}x@var{height} or a video size abbreviation. If not
 332 specified it defaults to the size of the input video.
 333
 334 @item window_x
 335 @item window_y
 336 Set the X and Y window offsets for the created window. They are both
 337 set to 0 by default. The values may be ignored by the window manager.
 338
 339 @item window_title
 340 Set the window title, if not specified default to the filename
 341 specified for the output device.
 342 @end table
 343
 344 For more information about XVideo see @url{http://www.x.org/}.
 345
 346 @subsection Examples
 347
 348 @itemize
 349 @item
 350 Decode, display and encode video input with @command{ffmpeg} at the
 351 same time:
 352 @example
 353 ffmpeg -i INPUT OUTPUT -f xv display
 354 @end example
 355
 356 @item
 357 Decode and display the input video to multiple X11 windows:
 358 @example
 359 ffmpeg -i INPUT -f xv normal -vf negate -f xv negated
 360 @end example
 361 @end itemize
 362
 363 @c man end OUTPUT DEVICES