outdevs.texi 16 KB

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