indevs.texi 48 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611
  1. @chapter Input Devices
  2. @c man begin INPUT DEVICES
  3. Input devices are configured elements in FFmpeg which enable accessing
  4. the data coming from a multimedia device attached to your system.
  5. When you configure your FFmpeg build, all the supported input devices
  6. are enabled by default. You can list all available ones using the
  7. configure option "--list-indevs".
  8. You can disable all the input devices using the configure option
  9. "--disable-indevs", and selectively enable an input device using the
  10. option "--enable-indev=@var{INDEV}", or you can disable a particular
  11. input device using the option "--disable-indev=@var{INDEV}".
  12. The option "-devices" of the ff* tools will display the list of
  13. supported input devices.
  14. A description of the currently available input devices follows.
  15. @section alsa
  16. ALSA (Advanced Linux Sound Architecture) input device.
  17. To enable this input device during configuration you need libasound
  18. installed on your system.
  19. This device allows capturing from an ALSA device. The name of the
  20. device to capture has to be an ALSA card identifier.
  21. An ALSA identifier has the syntax:
  22. @example
  23. hw:@var{CARD}[,@var{DEV}[,@var{SUBDEV}]]
  24. @end example
  25. where the @var{DEV} and @var{SUBDEV} components are optional.
  26. The three arguments (in order: @var{CARD},@var{DEV},@var{SUBDEV})
  27. specify card number or identifier, device number and subdevice number
  28. (-1 means any).
  29. To see the list of cards currently recognized by your system check the
  30. files @file{/proc/asound/cards} and @file{/proc/asound/devices}.
  31. For example to capture with @command{ffmpeg} from an ALSA device with
  32. card id 0, you may run the command:
  33. @example
  34. ffmpeg -f alsa -i hw:0 alsaout.wav
  35. @end example
  36. For more information see:
  37. @url{http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html}
  38. @subsection Options
  39. @table @option
  40. @item sample_rate
  41. Set the sample rate in Hz. Default is 48000.
  42. @item channels
  43. Set the number of channels. Default is 2.
  44. @end table
  45. @section android_camera
  46. Android camera input device.
  47. This input devices uses the Android Camera2 NDK API which is
  48. available on devices with API level 24+. The availability of
  49. android_camera is autodetected during configuration.
  50. This device allows capturing from all cameras on an Android device,
  51. which are integrated into the Camera2 NDK API.
  52. The available cameras are enumerated internally and can be selected
  53. with the @var{camera_index} parameter. The input file string is
  54. discarded.
  55. Generally the back facing camera has index 0 while the front facing
  56. camera has index 1.
  57. @subsection Options
  58. @table @option
  59. @item video_size
  60. Set the video size given as a string such as 640x480 or hd720.
  61. Falls back to the first available configuration reported by
  62. Android if requested video size is not available or by default.
  63. @item framerate
  64. Set the video framerate.
  65. Falls back to the first available configuration reported by
  66. Android if requested framerate is not available or by default (-1).
  67. @item camera_index
  68. Set the index of the camera to use. Default is 0.
  69. @item input_queue_size
  70. Set the maximum number of frames to buffer. Default is 5.
  71. @end table
  72. @section avfoundation
  73. AVFoundation input device.
  74. AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS.
  75. The input filename has to be given in the following syntax:
  76. @example
  77. -i "[[VIDEO]:[AUDIO]]"
  78. @end example
  79. The first entry selects the video input while the latter selects the audio input.
  80. The stream has to be specified by the device name or the device index as shown by the device list.
  81. Alternatively, the video and/or audio input device can be chosen by index using the
  82. @option{
  83. -video_device_index <INDEX>
  84. }
  85. and/or
  86. @option{
  87. -audio_device_index <INDEX>
  88. }
  89. , overriding any
  90. device name or index given in the input filename.
  91. All available devices can be enumerated by using @option{-list_devices true}, listing
  92. all device names and corresponding indices.
  93. There are two device name aliases:
  94. @table @code
  95. @item default
  96. Select the AVFoundation default device of the corresponding type.
  97. @item none
  98. Do not record the corresponding media type.
  99. This is equivalent to specifying an empty device name or index.
  100. @end table
  101. @subsection Options
  102. AVFoundation supports the following options:
  103. @table @option
  104. @item -list_devices <TRUE|FALSE>
  105. If set to true, a list of all available input devices is given showing all
  106. device names and indices.
  107. @item -video_device_index <INDEX>
  108. Specify the video device by its index. Overrides anything given in the input filename.
  109. @item -audio_device_index <INDEX>
  110. Specify the audio device by its index. Overrides anything given in the input filename.
  111. @item -pixel_format <FORMAT>
  112. Request the video device to use a specific pixel format.
  113. If the specified format is not supported, a list of available formats is given
  114. and the first one in this list is used instead. Available pixel formats are:
  115. @code{monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0,
  116. bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10,
  117. yuv420p, nv12, yuyv422, gray}
  118. @item -framerate
  119. Set the grabbing frame rate. Default is @code{ntsc}, corresponding to a
  120. frame rate of @code{30000/1001}.
  121. @item -video_size
  122. Set the video frame size.
  123. @item -capture_cursor
  124. Capture the mouse pointer. Default is 0.
  125. @item -capture_mouse_clicks
  126. Capture the screen mouse clicks. Default is 0.
  127. @item -capture_raw_data
  128. Capture the raw device data. Default is 0.
  129. Using this option may result in receiving the underlying data delivered to the AVFoundation framework. E.g. for muxed devices that sends raw DV data to the framework (like tape-based camcorders), setting this option to false results in extracted video frames captured in the designated pixel format only. Setting this option to true results in receiving the raw DV stream untouched.
  130. @end table
  131. @subsection Examples
  132. @itemize
  133. @item
  134. Print the list of AVFoundation supported devices and exit:
  135. @example
  136. $ ffmpeg -f avfoundation -list_devices true -i ""
  137. @end example
  138. @item
  139. Record video from video device 0 and audio from audio device 0 into out.avi:
  140. @example
  141. $ ffmpeg -f avfoundation -i "0:0" out.avi
  142. @end example
  143. @item
  144. Record video from video device 2 and audio from audio device 1 into out.avi:
  145. @example
  146. $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi
  147. @end example
  148. @item
  149. Record video from the system default video device using the pixel format bgr0 and do not record any audio into out.avi:
  150. @example
  151. $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi
  152. @end example
  153. @item
  154. Record raw DV data from a suitable input device and write the output into out.dv:
  155. @example
  156. $ ffmpeg -f avfoundation -capture_raw_data true -i "zr100:none" out.dv
  157. @end example
  158. @end itemize
  159. @section bktr
  160. BSD video input device.
  161. @subsection Options
  162. @table @option
  163. @item framerate
  164. Set the frame rate.
  165. @item video_size
  166. Set the video frame size. Default is @code{vga}.
  167. @item standard
  168. Available values are:
  169. @table @samp
  170. @item pal
  171. @item ntsc
  172. @item secam
  173. @item paln
  174. @item palm
  175. @item ntscj
  176. @end table
  177. @end table
  178. @section decklink
  179. The decklink input device provides capture capabilities for Blackmagic
  180. DeckLink devices.
  181. To enable this input device, you need the Blackmagic DeckLink SDK and you
  182. need to configure with the appropriate @code{--extra-cflags}
  183. and @code{--extra-ldflags}.
  184. On Windows, you need to run the IDL files through @command{widl}.
  185. DeckLink is very picky about the formats it supports. Pixel format of the
  186. input can be set with @option{raw_format}.
  187. Framerate and video size must be determined for your device with
  188. @command{-list_formats 1}. Audio sample rate is always 48 kHz and the number
  189. of channels can be 2, 8 or 16. Note that all audio channels are bundled in one single
  190. audio track.
  191. @subsection Options
  192. @table @option
  193. @item list_devices
  194. If set to @option{true}, print a list of devices and exit.
  195. Defaults to @option{false}. This option is deprecated, please use the
  196. @code{-sources} option of ffmpeg to list the available input devices.
  197. @item list_formats
  198. If set to @option{true}, print a list of supported formats and exit.
  199. Defaults to @option{false}.
  200. @item format_code <FourCC>
  201. This sets the input video format to the format given by the FourCC. To see
  202. the supported values of your device(s) use @option{list_formats}.
  203. Note that there is a FourCC @option{'pal '} that can also be used
  204. as @option{pal} (3 letters).
  205. Default behavior is autodetection of the input video format, if the hardware
  206. supports it.
  207. @item raw_format
  208. Set the pixel format of the captured video.
  209. Available values are:
  210. @table @samp
  211. @item auto
  212. This is the default which means 8-bit YUV 422 or 8-bit ARGB if format
  213. autodetection is used, 8-bit YUV 422 otherwise.
  214. @item uyvy422
  215. 8-bit YUV 422.
  216. @item yuv422p10
  217. 10-bit YUV 422.
  218. @item argb
  219. 8-bit RGB.
  220. @item bgra
  221. 8-bit RGB.
  222. @item rgb10
  223. 10-bit RGB.
  224. @end table
  225. @item teletext_lines
  226. If set to nonzero, an additional teletext stream will be captured from the
  227. vertical ancillary data. Both SD PAL (576i) and HD (1080i or 1080p)
  228. sources are supported. In case of HD sources, OP47 packets are decoded.
  229. This option is a bitmask of the SD PAL VBI lines captured, specifically lines 6
  230. to 22, and lines 318 to 335. Line 6 is the LSB in the mask. Selected lines
  231. which do not contain teletext information will be ignored. You can use the
  232. special @option{all} constant to select all possible lines, or
  233. @option{standard} to skip lines 6, 318 and 319, which are not compatible with
  234. all receivers.
  235. For SD sources, ffmpeg needs to be compiled with @code{--enable-libzvbi}. For
  236. HD sources, on older (pre-4K) DeckLink card models you have to capture in 10
  237. bit mode.
  238. @item channels
  239. Defines number of audio channels to capture. Must be @samp{2}, @samp{8} or @samp{16}.
  240. Defaults to @samp{2}.
  241. @item duplex_mode
  242. Sets the decklink device duplex/profile mode. Must be @samp{unset}, @samp{half}, @samp{full},
  243. @samp{one_sub_device_full}, @samp{one_sub_device_half}, @samp{two_sub_device_full},
  244. @samp{four_sub_device_half}
  245. Defaults to @samp{unset}.
  246. Note: DeckLink SDK 11.0 have replaced the duplex property by a profile property.
  247. For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2
  248. sub-devices that utilize the same connectors. For the DeckLink 8K Pro, a profile
  249. is shared between all 4 sub-devices. So DeckLink 8K Pro support four profiles.
  250. Valid profile modes for DeckLink 8K Pro(with DeckLink SDK >= 11.0):
  251. @samp{one_sub_device_full}, @samp{one_sub_device_half}, @samp{two_sub_device_full},
  252. @samp{four_sub_device_half}
  253. Valid profile modes for DeckLink Quad 2 and DeckLink Duo 2:
  254. @samp{half}, @samp{full}
  255. @item timecode_format
  256. Timecode type to include in the frame and video stream metadata. Must be
  257. @samp{none}, @samp{rp188vitc}, @samp{rp188vitc2}, @samp{rp188ltc},
  258. @samp{rp188hfr}, @samp{rp188any}, @samp{vitc}, @samp{vitc2}, or @samp{serial}.
  259. Defaults to @samp{none} (not included).
  260. In order to properly support 50/60 fps timecodes, the ordering of the queried
  261. timecode types for @samp{rp188any} is HFR, VITC1, VITC2 and LTC for >30 fps
  262. content. Note that this is slightly different to the ordering used by the
  263. DeckLink API, which is HFR, VITC1, LTC, VITC2.
  264. @item video_input
  265. Sets the video input source. Must be @samp{unset}, @samp{sdi}, @samp{hdmi},
  266. @samp{optical_sdi}, @samp{component}, @samp{composite} or @samp{s_video}.
  267. Defaults to @samp{unset}.
  268. @item audio_input
  269. Sets the audio input source. Must be @samp{unset}, @samp{embedded},
  270. @samp{aes_ebu}, @samp{analog}, @samp{analog_xlr}, @samp{analog_rca} or
  271. @samp{microphone}. Defaults to @samp{unset}.
  272. @item video_pts
  273. Sets the video packet timestamp source. Must be @samp{video}, @samp{audio},
  274. @samp{reference}, @samp{wallclock} or @samp{abs_wallclock}.
  275. Defaults to @samp{video}.
  276. @item audio_pts
  277. Sets the audio packet timestamp source. Must be @samp{video}, @samp{audio},
  278. @samp{reference}, @samp{wallclock} or @samp{abs_wallclock}.
  279. Defaults to @samp{audio}.
  280. @item draw_bars
  281. If set to @samp{true}, color bars are drawn in the event of a signal loss.
  282. Defaults to @samp{true}.
  283. @item queue_size
  284. Sets maximum input buffer size in bytes. If the buffering reaches this value,
  285. incoming frames will be dropped.
  286. Defaults to @samp{1073741824}.
  287. @item audio_depth
  288. Sets the audio sample bit depth. Must be @samp{16} or @samp{32}.
  289. Defaults to @samp{16}.
  290. @item decklink_copyts
  291. If set to @option{true}, timestamps are forwarded as they are without removing
  292. the initial offset.
  293. Defaults to @option{false}.
  294. @item timestamp_align
  295. Capture start time alignment in seconds. If set to nonzero, input frames are
  296. dropped till the system timestamp aligns with configured value.
  297. Alignment difference of up to one frame duration is tolerated.
  298. This is useful for maintaining input synchronization across N different
  299. hardware devices deployed for 'N-way' redundancy. The system time of different
  300. hardware devices should be synchronized with protocols such as NTP or PTP,
  301. before using this option.
  302. Note that this method is not foolproof. In some border cases input
  303. synchronization may not happen due to thread scheduling jitters in the OS.
  304. Either sync could go wrong by 1 frame or in a rarer case
  305. @option{timestamp_align} seconds.
  306. Defaults to @samp{0}.
  307. @item wait_for_tc (@emph{bool})
  308. Drop frames till a frame with timecode is received. Sometimes serial timecode
  309. isn't received with the first input frame. If that happens, the stored stream
  310. timecode will be inaccurate. If this option is set to @option{true}, input frames
  311. are dropped till a frame with timecode is received.
  312. Option @var{timecode_format} must be specified.
  313. Defaults to @option{false}.
  314. @item enable_klv(@emph{bool})
  315. If set to @option{true}, extracts KLV data from VANC and outputs KLV packets.
  316. KLV VANC packets are joined based on MID and PSC fields and aggregated into
  317. one KLV packet.
  318. Defaults to @option{false}.
  319. @end table
  320. @subsection Examples
  321. @itemize
  322. @item
  323. List input devices:
  324. @example
  325. ffmpeg -sources decklink
  326. @end example
  327. @item
  328. List supported formats:
  329. @example
  330. ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro'
  331. @end example
  332. @item
  333. Capture video clip at 1080i50:
  334. @example
  335. ffmpeg -format_code Hi50 -f decklink -i 'Intensity Pro' -c:a copy -c:v copy output.avi
  336. @end example
  337. @item
  338. Capture video clip at 1080i50 10 bit:
  339. @example
  340. ffmpeg -raw_format yuv422p10 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
  341. @end example
  342. @item
  343. Capture video clip at 1080i50 with 16 audio channels:
  344. @example
  345. ffmpeg -channels 16 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -c:a copy -c:v copy output.avi
  346. @end example
  347. @end itemize
  348. @section dshow
  349. Windows DirectShow input device.
  350. DirectShow support is enabled when FFmpeg is built with the mingw-w64 project.
  351. Currently only audio and video devices are supported.
  352. Multiple devices may be opened as separate inputs, but they may also be
  353. opened on the same input, which should improve synchronism between them.
  354. The input name should be in the format:
  355. @example
  356. @var{TYPE}=@var{NAME}[:@var{TYPE}=@var{NAME}]
  357. @end example
  358. where @var{TYPE} can be either @var{audio} or @var{video},
  359. and @var{NAME} is the device's name or alternative name..
  360. @subsection Options
  361. If no options are specified, the device's defaults are used.
  362. If the device does not support the requested options, it will
  363. fail to open.
  364. @table @option
  365. @item video_size
  366. Set the video size in the captured video.
  367. @item framerate
  368. Set the frame rate in the captured video.
  369. @item sample_rate
  370. Set the sample rate (in Hz) of the captured audio.
  371. @item sample_size
  372. Set the sample size (in bits) of the captured audio.
  373. @item channels
  374. Set the number of channels in the captured audio.
  375. @item list_devices
  376. If set to @option{true}, print a list of devices and exit.
  377. @item list_options
  378. If set to @option{true}, print a list of selected device's options
  379. and exit.
  380. @item video_device_number
  381. Set video device number for devices with the same name (starts at 0,
  382. defaults to 0).
  383. @item audio_device_number
  384. Set audio device number for devices with the same name (starts at 0,
  385. defaults to 0).
  386. @item pixel_format
  387. Select pixel format to be used by DirectShow. This may only be set when
  388. the video codec is not set or set to rawvideo.
  389. @item audio_buffer_size
  390. Set audio device buffer size in milliseconds (which can directly
  391. impact latency, depending on the device).
  392. Defaults to using the audio device's
  393. default buffer size (typically some multiple of 500ms).
  394. Setting this value too low can degrade performance.
  395. See also
  396. @url{http://msdn.microsoft.com/en-us/library/windows/desktop/dd377582(v=vs.85).aspx}
  397. @item video_pin_name
  398. Select video capture pin to use by name or alternative name.
  399. @item audio_pin_name
  400. Select audio capture pin to use by name or alternative name.
  401. @item crossbar_video_input_pin_number
  402. Select video input pin number for crossbar device. This will be
  403. routed to the crossbar device's Video Decoder output pin.
  404. Note that changing this value can affect future invocations
  405. (sets a new default) until system reboot occurs.
  406. @item crossbar_audio_input_pin_number
  407. Select audio input pin number for crossbar device. This will be
  408. routed to the crossbar device's Audio Decoder output pin.
  409. Note that changing this value can affect future invocations
  410. (sets a new default) until system reboot occurs.
  411. @item show_video_device_dialog
  412. If set to @option{true}, before capture starts, popup a display dialog
  413. to the end user, allowing them to change video filter properties
  414. and configurations manually.
  415. Note that for crossbar devices, adjusting values in this dialog
  416. may be needed at times to toggle between PAL (25 fps) and NTSC (29.97)
  417. input frame rates, sizes, interlacing, etc. Changing these values can
  418. enable different scan rates/frame rates and avoiding green bars at
  419. the bottom, flickering scan lines, etc.
  420. Note that with some devices, changing these properties can also affect future
  421. invocations (sets new defaults) until system reboot occurs.
  422. @item show_audio_device_dialog
  423. If set to @option{true}, before capture starts, popup a display dialog
  424. to the end user, allowing them to change audio filter properties
  425. and configurations manually.
  426. @item show_video_crossbar_connection_dialog
  427. If set to @option{true}, before capture starts, popup a display
  428. dialog to the end user, allowing them to manually
  429. modify crossbar pin routings, when it opens a video device.
  430. @item show_audio_crossbar_connection_dialog
  431. If set to @option{true}, before capture starts, popup a display
  432. dialog to the end user, allowing them to manually
  433. modify crossbar pin routings, when it opens an audio device.
  434. @item show_analog_tv_tuner_dialog
  435. If set to @option{true}, before capture starts, popup a display
  436. dialog to the end user, allowing them to manually
  437. modify TV channels and frequencies.
  438. @item show_analog_tv_tuner_audio_dialog
  439. If set to @option{true}, before capture starts, popup a display
  440. dialog to the end user, allowing them to manually
  441. modify TV audio (like mono vs. stereo, Language A,B or C).
  442. @item audio_device_load
  443. Load an audio capture filter device from file instead of searching
  444. it by name. It may load additional parameters too, if the filter
  445. supports the serialization of its properties to.
  446. To use this an audio capture source has to be specified, but it can
  447. be anything even fake one.
  448. @item audio_device_save
  449. Save the currently used audio capture filter device and its
  450. parameters (if the filter supports it) to a file.
  451. If a file with the same name exists it will be overwritten.
  452. @item video_device_load
  453. Load a video capture filter device from file instead of searching
  454. it by name. It may load additional parameters too, if the filter
  455. supports the serialization of its properties to.
  456. To use this a video capture source has to be specified, but it can
  457. be anything even fake one.
  458. @item video_device_save
  459. Save the currently used video capture filter device and its
  460. parameters (if the filter supports it) to a file.
  461. If a file with the same name exists it will be overwritten.
  462. @item use_video_device_timestamps
  463. If set to @option{false}, the timestamp for video frames will be
  464. derived from the wallclock instead of the timestamp provided by
  465. the capture device. This allows working around devices that
  466. provide unreliable timestamps.
  467. @end table
  468. @subsection Examples
  469. @itemize
  470. @item
  471. Print the list of DirectShow supported devices and exit:
  472. @example
  473. $ ffmpeg -list_devices true -f dshow -i dummy
  474. @end example
  475. @item
  476. Open video device @var{Camera}:
  477. @example
  478. $ ffmpeg -f dshow -i video="Camera"
  479. @end example
  480. @item
  481. Open second video device with name @var{Camera}:
  482. @example
  483. $ ffmpeg -f dshow -video_device_number 1 -i video="Camera"
  484. @end example
  485. @item
  486. Open video device @var{Camera} and audio device @var{Microphone}:
  487. @example
  488. $ ffmpeg -f dshow -i video="Camera":audio="Microphone"
  489. @end example
  490. @item
  491. Print the list of supported options in selected device and exit:
  492. @example
  493. $ ffmpeg -list_options true -f dshow -i video="Camera"
  494. @end example
  495. @item
  496. Specify pin names to capture by name or alternative name, specify alternative device name:
  497. @example
  498. $ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@@device_pnp_\\?\pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#@{65e8773d-8f56-11d0-a3b9-00a0c9223196@}\@{ca465100-deb0-4d59-818f-8c477184adf6@}":audio="Microphone"
  499. @end example
  500. @item
  501. Configure a crossbar device, specifying crossbar pins, allow user to adjust video capture properties at startup:
  502. @example
  503. $ ffmpeg -f dshow -show_video_device_dialog true -crossbar_video_input_pin_number 0
  504. -crossbar_audio_input_pin_number 3 -i video="AVerMedia BDA Analog Capture":audio="AVerMedia BDA Analog Capture"
  505. @end example
  506. @end itemize
  507. @section fbdev
  508. Linux framebuffer input device.
  509. The Linux framebuffer is a graphic hardware-independent abstraction
  510. layer to show graphics on a computer monitor, typically on the
  511. console. It is accessed through a file device node, usually
  512. @file{/dev/fb0}.
  513. For more detailed information read the file
  514. Documentation/fb/framebuffer.txt included in the Linux source tree.
  515. See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1).
  516. To record from the framebuffer device @file{/dev/fb0} with
  517. @command{ffmpeg}:
  518. @example
  519. ffmpeg -f fbdev -framerate 10 -i /dev/fb0 out.avi
  520. @end example
  521. You can take a single screenshot image with the command:
  522. @example
  523. ffmpeg -f fbdev -framerate 1 -i /dev/fb0 -frames:v 1 screenshot.jpeg
  524. @end example
  525. @subsection Options
  526. @table @option
  527. @item framerate
  528. Set the frame rate. Default is 25.
  529. @end table
  530. @section gdigrab
  531. Win32 GDI-based screen capture device.
  532. This device allows you to capture a region of the display on Windows.
  533. There are two options for the input filename:
  534. @example
  535. desktop
  536. @end example
  537. or
  538. @example
  539. title=@var{window_title}
  540. @end example
  541. The first option will capture the entire desktop, or a fixed region of the
  542. desktop. The second option will instead capture the contents of a single
  543. window, regardless of its position on the screen.
  544. For example, to grab the entire desktop using @command{ffmpeg}:
  545. @example
  546. ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg
  547. @end example
  548. Grab a 640x480 region at position @code{10,20}:
  549. @example
  550. ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg
  551. @end example
  552. Grab the contents of the window named "Calculator"
  553. @example
  554. ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg
  555. @end example
  556. @subsection Options
  557. @table @option
  558. @item draw_mouse
  559. Specify whether to draw the mouse pointer. Use the value @code{0} to
  560. not draw the pointer. Default value is @code{1}.
  561. @item framerate
  562. Set the grabbing frame rate. Default value is @code{ntsc},
  563. corresponding to a frame rate of @code{30000/1001}.
  564. @item show_region
  565. Show grabbed region on screen.
  566. If @var{show_region} is specified with @code{1}, then the grabbing
  567. region will be indicated on screen. With this option, it is easy to
  568. know what is being grabbed if only a portion of the screen is grabbed.
  569. Note that @var{show_region} is incompatible with grabbing the contents
  570. of a single window.
  571. For example:
  572. @example
  573. ffmpeg -f gdigrab -show_region 1 -framerate 6 -video_size cif -offset_x 10 -offset_y 20 -i desktop out.mpg
  574. @end example
  575. @item video_size
  576. Set the video frame size. The default is to capture the full screen if @file{desktop} is selected, or the full window size if @file{title=@var{window_title}} is selected.
  577. @item offset_x
  578. When capturing a region with @var{video_size}, set the distance from the left edge of the screen or desktop.
  579. Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned to the left of your primary monitor, you will need to use a negative @var{offset_x} value to move the region to that monitor.
  580. @item offset_y
  581. When capturing a region with @var{video_size}, set the distance from the top edge of the screen or desktop.
  582. Note that the offset calculation is from the top left corner of the primary monitor on Windows. If you have a monitor positioned above your primary monitor, you will need to use a negative @var{offset_y} value to move the region to that monitor.
  583. @end table
  584. @section iec61883
  585. FireWire DV/HDV input device using libiec61883.
  586. To enable this input device, you need libiec61883, libraw1394 and
  587. libavc1394 installed on your system. Use the configure option
  588. @code{--enable-libiec61883} to compile with the device enabled.
  589. The iec61883 capture device supports capturing from a video device
  590. connected via IEEE1394 (FireWire), using libiec61883 and the new Linux
  591. FireWire stack (juju). This is the default DV/HDV input method in Linux
  592. Kernel 2.6.37 and later, since the old FireWire stack was removed.
  593. Specify the FireWire port to be used as input file, or "auto"
  594. to choose the first port connected.
  595. @subsection Options
  596. @table @option
  597. @item dvtype
  598. Override autodetection of DV/HDV. This should only be used if auto
  599. detection does not work, or if usage of a different device type
  600. should be prohibited. Treating a DV device as HDV (or vice versa) will
  601. not work and result in undefined behavior.
  602. The values @option{auto}, @option{dv} and @option{hdv} are supported.
  603. @item dvbuffer
  604. Set maximum size of buffer for incoming data, in frames. For DV, this
  605. is an exact value. For HDV, it is not frame exact, since HDV does
  606. not have a fixed frame size.
  607. @item dvguid
  608. Select the capture device by specifying its GUID. Capturing will only
  609. be performed from the specified device and fails if no device with the
  610. given GUID is found. This is useful to select the input if multiple
  611. devices are connected at the same time.
  612. Look at /sys/bus/firewire/devices to find out the GUIDs.
  613. @end table
  614. @subsection Examples
  615. @itemize
  616. @item
  617. Grab and show the input of a FireWire DV/HDV device.
  618. @example
  619. ffplay -f iec61883 -i auto
  620. @end example
  621. @item
  622. Grab and record the input of a FireWire DV/HDV device,
  623. using a packet buffer of 100000 packets if the source is HDV.
  624. @example
  625. ffmpeg -f iec61883 -i auto -dvbuffer 100000 out.mpg
  626. @end example
  627. @end itemize
  628. @section jack
  629. JACK input device.
  630. To enable this input device during configuration you need libjack
  631. installed on your system.
  632. A JACK input device creates one or more JACK writable clients, one for
  633. each audio channel, with name @var{client_name}:input_@var{N}, where
  634. @var{client_name} is the name provided by the application, and @var{N}
  635. is a number which identifies the channel.
  636. Each writable client will send the acquired data to the FFmpeg input
  637. device.
  638. Once you have created one or more JACK readable clients, you need to
  639. connect them to one or more JACK writable clients.
  640. To connect or disconnect JACK clients you can use the @command{jack_connect}
  641. and @command{jack_disconnect} programs, or do it through a graphical interface,
  642. for example with @command{qjackctl}.
  643. To list the JACK clients and their properties you can invoke the command
  644. @command{jack_lsp}.
  645. Follows an example which shows how to capture a JACK readable client
  646. with @command{ffmpeg}.
  647. @example
  648. # Create a JACK writable client with name "ffmpeg".
  649. $ ffmpeg -f jack -i ffmpeg -y out.wav
  650. # Start the sample jack_metro readable client.
  651. $ jack_metro -b 120 -d 0.2 -f 4000
  652. # List the current JACK clients.
  653. $ jack_lsp -c
  654. system:capture_1
  655. system:capture_2
  656. system:playback_1
  657. system:playback_2
  658. ffmpeg:input_1
  659. metro:120_bpm
  660. # Connect metro to the ffmpeg writable client.
  661. $ jack_connect metro:120_bpm ffmpeg:input_1
  662. @end example
  663. For more information read:
  664. @url{http://jackaudio.org/}
  665. @subsection Options
  666. @table @option
  667. @item channels
  668. Set the number of channels. Default is 2.
  669. @end table
  670. @section kmsgrab
  671. KMS video input device.
  672. Captures the KMS scanout framebuffer associated with a specified CRTC or plane as a
  673. DRM object that can be passed to other hardware functions.
  674. Requires either DRM master or CAP_SYS_ADMIN to run.
  675. If you don't understand what all of that means, you probably don't want this. Look at
  676. @option{x11grab} instead.
  677. @subsection Options
  678. @table @option
  679. @item device
  680. DRM device to capture on. Defaults to @option{/dev/dri/card0}.
  681. @item format
  682. Pixel format of the framebuffer. This can be autodetected if you are running Linux 5.7
  683. or later, but needs to be provided for earlier versions. Defaults to @option{bgr0},
  684. which is the most common format used by the Linux console and Xorg X server.
  685. @item format_modifier
  686. Format modifier to signal on output frames. This is necessary to import correctly into
  687. some APIs. It can be autodetected if you are running Linux 5.7 or later, but will need
  688. to be provided explicitly when needed in earlier versions. See the libdrm documentation
  689. for possible values.
  690. @item crtc_id
  691. KMS CRTC ID to define the capture source. The first active plane on the given CRTC
  692. will be used.
  693. @item plane_id
  694. KMS plane ID to define the capture source. Defaults to the first active plane found if
  695. neither @option{crtc_id} nor @option{plane_id} are specified.
  696. @item framerate
  697. Framerate to capture at. This is not synchronised to any page flipping or framebuffer
  698. changes - it just defines the interval at which the framebuffer is sampled. Sampling
  699. faster than the framebuffer update rate will generate independent frames with the same
  700. content. Defaults to @code{30}.
  701. @end table
  702. @subsection Examples
  703. @itemize
  704. @item
  705. Capture from the first active plane, download the result to normal frames and encode.
  706. This will only work if the framebuffer is both linear and mappable - if not, the result
  707. may be scrambled or fail to download.
  708. @example
  709. ffmpeg -f kmsgrab -i - -vf 'hwdownload,format=bgr0' output.mp4
  710. @end example
  711. @item
  712. Capture from CRTC ID 42 at 60fps, map the result to VAAPI, convert to NV12 and encode as H.264.
  713. @example
  714. ffmpeg -crtc_id 42 -framerate 60 -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,scale_vaapi=w=1920:h=1080:format=nv12' -c:v h264_vaapi output.mp4
  715. @end example
  716. @item
  717. To capture only part of a plane the output can be cropped - this can be used to capture
  718. a single window, as long as it has a known absolute position and size. For example, to
  719. capture and encode the middle quarter of a 1920x1080 plane:
  720. @example
  721. ffmpeg -f kmsgrab -i - -vf 'hwmap=derive_device=vaapi,crop=960:540:480:270,scale_vaapi=960:540:nv12' -c:v h264_vaapi output.mp4
  722. @end example
  723. @end itemize
  724. @section lavfi
  725. Libavfilter input virtual device.
  726. This input device reads data from the open output pads of a libavfilter
  727. filtergraph.
  728. For each filtergraph open output, the input device will create a
  729. corresponding stream which is mapped to the generated output. Currently
  730. only video data is supported. The filtergraph is specified through the
  731. option @option{graph}.
  732. @subsection Options
  733. @table @option
  734. @item graph
  735. Specify the filtergraph to use as input. Each video open output must be
  736. labelled by a unique string of the form "out@var{N}", where @var{N} is a
  737. number starting from 0 corresponding to the mapped input stream
  738. generated by the device.
  739. The first unlabelled output is automatically assigned to the "out0"
  740. label, but all the others need to be specified explicitly.
  741. The suffix "+subcc" can be appended to the output label to create an extra
  742. stream with the closed captions packets attached to that output
  743. (experimental; only for EIA-608 / CEA-708 for now).
  744. The subcc streams are created after all the normal streams, in the order of
  745. the corresponding stream.
  746. For example, if there is "out19+subcc", "out7+subcc" and up to "out42", the
  747. stream #43 is subcc for stream #7 and stream #44 is subcc for stream #19.
  748. If not specified defaults to the filename specified for the input
  749. device.
  750. @item graph_file
  751. Set the filename of the filtergraph to be read and sent to the other
  752. filters. Syntax of the filtergraph is the same as the one specified by
  753. the option @var{graph}.
  754. @item dumpgraph
  755. Dump graph to stderr.
  756. @end table
  757. @subsection Examples
  758. @itemize
  759. @item
  760. Create a color video stream and play it back with @command{ffplay}:
  761. @example
  762. ffplay -f lavfi -graph "color=c=pink [out0]" dummy
  763. @end example
  764. @item
  765. As the previous example, but use filename for specifying the graph
  766. description, and omit the "out0" label:
  767. @example
  768. ffplay -f lavfi color=c=pink
  769. @end example
  770. @item
  771. Create three different video test filtered sources and play them:
  772. @example
  773. ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3
  774. @end example
  775. @item
  776. Read an audio stream from a file using the amovie source and play it
  777. back with @command{ffplay}:
  778. @example
  779. ffplay -f lavfi "amovie=test.wav"
  780. @end example
  781. @item
  782. Read an audio stream and a video stream and play it back with
  783. @command{ffplay}:
  784. @example
  785. ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]"
  786. @end example
  787. @item
  788. Dump decoded frames to images and closed captions to a file (experimental):
  789. @example
  790. ffmpeg -f lavfi -i "movie=test.ts[out0+subcc]" -map v frame%08d.png -map s -c copy -f rawvideo subcc.bin
  791. @end example
  792. @end itemize
  793. @section libcdio
  794. Audio-CD input device based on libcdio.
  795. To enable this input device during configuration you need libcdio
  796. installed on your system. It requires the configure option
  797. @code{--enable-libcdio}.
  798. This device allows playing and grabbing from an Audio-CD.
  799. For example to copy with @command{ffmpeg} the entire Audio-CD in @file{/dev/sr0},
  800. you may run the command:
  801. @example
  802. ffmpeg -f libcdio -i /dev/sr0 cd.wav
  803. @end example
  804. @subsection Options
  805. @table @option
  806. @item speed
  807. Set drive reading speed. Default value is 0.
  808. The speed is specified CD-ROM speed units. The speed is set through
  809. the libcdio @code{cdio_cddap_speed_set} function. On many CD-ROM
  810. drives, specifying a value too large will result in using the fastest
  811. speed.
  812. @item paranoia_mode
  813. Set paranoia recovery mode flags. It accepts one of the following values:
  814. @table @samp
  815. @item disable
  816. @item verify
  817. @item overlap
  818. @item neverskip
  819. @item full
  820. @end table
  821. Default value is @samp{disable}.
  822. For more information about the available recovery modes, consult the
  823. paranoia project documentation.
  824. @end table
  825. @section libdc1394
  826. IIDC1394 input device, based on libdc1394 and libraw1394.
  827. Requires the configure option @code{--enable-libdc1394}.
  828. @subsection Options
  829. @table @option
  830. @item framerate
  831. Set the frame rate. Default is @code{ntsc}, corresponding to a frame
  832. rate of @code{30000/1001}.
  833. @item pixel_format
  834. Select the pixel format. Default is @code{uyvy422}.
  835. @item video_size
  836. Set the video size given as a string such as @code{640x480} or @code{hd720}.
  837. Default is @code{qvga}.
  838. @end table
  839. @section openal
  840. The OpenAL input device provides audio capture on all systems with a
  841. working OpenAL 1.1 implementation.
  842. To enable this input device during configuration, you need OpenAL
  843. headers and libraries installed on your system, and need to configure
  844. FFmpeg with @code{--enable-openal}.
  845. OpenAL headers and libraries should be provided as part of your OpenAL
  846. implementation, or as an additional download (an SDK). Depending on your
  847. installation you may need to specify additional flags via the
  848. @code{--extra-cflags} and @code{--extra-ldflags} for allowing the build
  849. system to locate the OpenAL headers and libraries.
  850. An incomplete list of OpenAL implementations follows:
  851. @table @strong
  852. @item Creative
  853. The official Windows implementation, providing hardware acceleration
  854. with supported devices and software fallback.
  855. See @url{http://openal.org/}.
  856. @item OpenAL Soft
  857. Portable, open source (LGPL) software implementation. Includes
  858. backends for the most common sound APIs on the Windows, Linux,
  859. Solaris, and BSD operating systems.
  860. See @url{http://kcat.strangesoft.net/openal.html}.
  861. @item Apple
  862. OpenAL is part of Core Audio, the official Mac OS X Audio interface.
  863. See @url{http://developer.apple.com/technologies/mac/audio-and-video.html}
  864. @end table
  865. This device allows one to capture from an audio input device handled
  866. through OpenAL.
  867. You need to specify the name of the device to capture in the provided
  868. filename. If the empty string is provided, the device will
  869. automatically select the default device. You can get the list of the
  870. supported devices by using the option @var{list_devices}.
  871. @subsection Options
  872. @table @option
  873. @item channels
  874. Set the number of channels in the captured audio. Only the values
  875. @option{1} (monaural) and @option{2} (stereo) are currently supported.
  876. Defaults to @option{2}.
  877. @item sample_size
  878. Set the sample size (in bits) of the captured audio. Only the values
  879. @option{8} and @option{16} are currently supported. Defaults to
  880. @option{16}.
  881. @item sample_rate
  882. Set the sample rate (in Hz) of the captured audio.
  883. Defaults to @option{44.1k}.
  884. @item list_devices
  885. If set to @option{true}, print a list of devices and exit.
  886. Defaults to @option{false}.
  887. @end table
  888. @subsection Examples
  889. Print the list of OpenAL supported devices and exit:
  890. @example
  891. $ ffmpeg -list_devices true -f openal -i dummy out.ogg
  892. @end example
  893. Capture from the OpenAL device @file{DR-BT101 via PulseAudio}:
  894. @example
  895. $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg
  896. @end example
  897. Capture from the default device (note the empty string '' as filename):
  898. @example
  899. $ ffmpeg -f openal -i '' out.ogg
  900. @end example
  901. Capture from two devices simultaneously, writing to two different files,
  902. within the same @command{ffmpeg} command:
  903. @example
  904. $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg
  905. @end example
  906. Note: not all OpenAL implementations support multiple simultaneous capture -
  907. try the latest OpenAL Soft if the above does not work.
  908. @section oss
  909. Open Sound System input device.
  910. The filename to provide to the input device is the device node
  911. representing the OSS input device, and is usually set to
  912. @file{/dev/dsp}.
  913. For example to grab from @file{/dev/dsp} using @command{ffmpeg} use the
  914. command:
  915. @example
  916. ffmpeg -f oss -i /dev/dsp /tmp/oss.wav
  917. @end example
  918. For more information about OSS see:
  919. @url{http://manuals.opensound.com/usersguide/dsp.html}
  920. @subsection Options
  921. @table @option
  922. @item sample_rate
  923. Set the sample rate in Hz. Default is 48000.
  924. @item channels
  925. Set the number of channels. Default is 2.
  926. @end table
  927. @section pulse
  928. PulseAudio input device.
  929. To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}.
  930. The filename to provide to the input device is a source device or the
  931. string "default"
  932. To list the PulseAudio source devices and their properties you can invoke
  933. the command @command{pactl list sources}.
  934. More information about PulseAudio can be found on @url{http://www.pulseaudio.org}.
  935. @subsection Options
  936. @table @option
  937. @item server
  938. Connect to a specific PulseAudio server, specified by an IP address.
  939. Default server is used when not provided.
  940. @item name
  941. Specify the application name PulseAudio will use when showing active clients,
  942. by default it is the @code{LIBAVFORMAT_IDENT} string.
  943. @item stream_name
  944. Specify the stream name PulseAudio will use when showing active streams,
  945. by default it is "record".
  946. @item sample_rate
  947. Specify the samplerate in Hz, by default 48kHz is used.
  948. @item channels
  949. Specify the channels in use, by default 2 (stereo) is set.
  950. @item frame_size
  951. This option does nothing and is deprecated.
  952. @item fragment_size
  953. Specify the size in bytes of the minimal buffering fragment in PulseAudio, it
  954. will affect the audio latency. By default it is set to 50 ms amount of data.
  955. @item wallclock
  956. Set the initial PTS using the current time. Default is 1.
  957. @end table
  958. @subsection Examples
  959. Record a stream from default device:
  960. @example
  961. ffmpeg -f pulse -i default /tmp/pulse.wav
  962. @end example
  963. @section sndio
  964. sndio input device.
  965. To enable this input device during configuration you need libsndio
  966. installed on your system.
  967. The filename to provide to the input device is the device node
  968. representing the sndio input device, and is usually set to
  969. @file{/dev/audio0}.
  970. For example to grab from @file{/dev/audio0} using @command{ffmpeg} use the
  971. command:
  972. @example
  973. ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
  974. @end example
  975. @subsection Options
  976. @table @option
  977. @item sample_rate
  978. Set the sample rate in Hz. Default is 48000.
  979. @item channels
  980. Set the number of channels. Default is 2.
  981. @end table
  982. @section video4linux2, v4l2
  983. Video4Linux2 input video device.
  984. "v4l2" can be used as alias for "video4linux2".
  985. If FFmpeg is built with v4l-utils support (by using the
  986. @code{--enable-libv4l2} configure option), it is possible to use it with the
  987. @code{-use_libv4l2} input device option.
  988. The name of the device to grab is a file device node, usually Linux
  989. systems tend to automatically create such nodes when the device
  990. (e.g. an USB webcam) is plugged into the system, and has a name of the
  991. kind @file{/dev/video@var{N}}, where @var{N} is a number associated to
  992. the device.
  993. Video4Linux2 devices usually support a limited set of
  994. @var{width}x@var{height} sizes and frame rates. You can check which are
  995. supported using @command{-list_formats all} for Video4Linux2 devices.
  996. Some devices, like TV cards, support one or more standards. It is possible
  997. to list all the supported standards using @command{-list_standards all}.
  998. The time base for the timestamps is 1 microsecond. Depending on the kernel
  999. version and configuration, the timestamps may be derived from the real time
  1000. clock (origin at the Unix Epoch) or the monotonic clock (origin usually at
  1001. boot time, unaffected by NTP or manual changes to the clock). The
  1002. @option{-timestamps abs} or @option{-ts abs} option can be used to force
  1003. conversion into the real time clock.
  1004. Some usage examples of the video4linux2 device with @command{ffmpeg}
  1005. and @command{ffplay}:
  1006. @itemize
  1007. @item
  1008. List supported formats for a video4linux2 device:
  1009. @example
  1010. ffplay -f video4linux2 -list_formats all /dev/video0
  1011. @end example
  1012. @item
  1013. Grab and show the input of a video4linux2 device:
  1014. @example
  1015. ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
  1016. @end example
  1017. @item
  1018. Grab and record the input of a video4linux2 device, leave the
  1019. frame rate and size as previously set:
  1020. @example
  1021. ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
  1022. @end example
  1023. @end itemize
  1024. For more information about Video4Linux, check @url{http://linuxtv.org/}.
  1025. @subsection Options
  1026. @table @option
  1027. @item standard
  1028. Set the standard. Must be the name of a supported standard. To get a
  1029. list of the supported standards, use the @option{list_standards}
  1030. option.
  1031. @item channel
  1032. Set the input channel number. Default to -1, which means using the
  1033. previously selected channel.
  1034. @item video_size
  1035. Set the video frame size. The argument must be a string in the form
  1036. @var{WIDTH}x@var{HEIGHT} or a valid size abbreviation.
  1037. @item pixel_format
  1038. Select the pixel format (only valid for raw video input).
  1039. @item input_format
  1040. Set the preferred pixel format (for raw video) or a codec name.
  1041. This option allows one to select the input format, when several are
  1042. available.
  1043. @item framerate
  1044. Set the preferred video frame rate.
  1045. @item list_formats
  1046. List available formats (supported pixel formats, codecs, and frame
  1047. sizes) and exit.
  1048. Available values are:
  1049. @table @samp
  1050. @item all
  1051. Show all available (compressed and non-compressed) formats.
  1052. @item raw
  1053. Show only raw video (non-compressed) formats.
  1054. @item compressed
  1055. Show only compressed formats.
  1056. @end table
  1057. @item list_standards
  1058. List supported standards and exit.
  1059. Available values are:
  1060. @table @samp
  1061. @item all
  1062. Show all supported standards.
  1063. @end table
  1064. @item timestamps, ts
  1065. Set type of timestamps for grabbed frames.
  1066. Available values are:
  1067. @table @samp
  1068. @item default
  1069. Use timestamps from the kernel.
  1070. @item abs
  1071. Use absolute timestamps (wall clock).
  1072. @item mono2abs
  1073. Force conversion from monotonic to absolute timestamps.
  1074. @end table
  1075. Default value is @code{default}.
  1076. @item use_libv4l2
  1077. Use libv4l2 (v4l-utils) conversion functions. Default is 0.
  1078. @end table
  1079. @section vfwcap
  1080. VfW (Video for Windows) capture input device.
  1081. The filename passed as input is the capture driver number, ranging from
  1082. 0 to 9. You may use "list" as filename to print a list of drivers. Any
  1083. other filename will be interpreted as device number 0.
  1084. @subsection Options
  1085. @table @option
  1086. @item video_size
  1087. Set the video frame size.
  1088. @item framerate
  1089. Set the grabbing frame rate. Default value is @code{ntsc},
  1090. corresponding to a frame rate of @code{30000/1001}.
  1091. @end table
  1092. @section x11grab
  1093. X11 video input device.
  1094. To enable this input device during configuration you need libxcb
  1095. installed on your system. It will be automatically detected during
  1096. configuration.
  1097. This device allows one to capture a region of an X11 display.
  1098. The filename passed as input has the syntax:
  1099. @example
  1100. [@var{hostname}]:@var{display_number}.@var{screen_number}[+@var{x_offset},@var{y_offset}]
  1101. @end example
  1102. @var{hostname}:@var{display_number}.@var{screen_number} specifies the
  1103. X11 display name of the screen to grab from. @var{hostname} can be
  1104. omitted, and defaults to "localhost". The environment variable
  1105. @env{DISPLAY} contains the default display name.
  1106. @var{x_offset} and @var{y_offset} specify the offsets of the grabbed
  1107. area with respect to the top-left border of the X11 screen. They
  1108. default to 0.
  1109. Check the X11 documentation (e.g. @command{man X}) for more detailed
  1110. information.
  1111. Use the @command{xdpyinfo} program for getting basic information about
  1112. the properties of your X11 display (e.g. grep for "name" or
  1113. "dimensions").
  1114. For example to grab from @file{:0.0} using @command{ffmpeg}:
  1115. @example
  1116. ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg
  1117. @end example
  1118. Grab at position @code{10,20}:
  1119. @example
  1120. ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
  1121. @end example
  1122. @subsection Options
  1123. @table @option
  1124. @item select_region
  1125. Specify whether to select the grabbing area graphically using the pointer.
  1126. A value of @code{1} prompts the user to select the grabbing area graphically
  1127. by clicking and dragging. A single click with no dragging will select the
  1128. whole screen. A region with zero width or height will also select the whole
  1129. screen. This option overwrites the @var{video_size}, @var{grab_x}, and
  1130. @var{grab_y} options. Default value is @code{0}.
  1131. @item draw_mouse
  1132. Specify whether to draw the mouse pointer. A value of @code{0} specifies
  1133. not to draw the pointer. Default value is @code{1}.
  1134. @item follow_mouse
  1135. Make the grabbed area follow the mouse. The argument can be
  1136. @code{centered} or a number of pixels @var{PIXELS}.
  1137. When it is specified with "centered", the grabbing region follows the mouse
  1138. pointer and keeps the pointer at the center of region; otherwise, the region
  1139. follows only when the mouse pointer reaches within @var{PIXELS} (greater than
  1140. zero) to the edge of region.
  1141. For example:
  1142. @example
  1143. ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg
  1144. @end example
  1145. To follow only when the mouse pointer reaches within 100 pixels to edge:
  1146. @example
  1147. ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg
  1148. @end example
  1149. @item framerate
  1150. Set the grabbing frame rate. Default value is @code{ntsc},
  1151. corresponding to a frame rate of @code{30000/1001}.
  1152. @item show_region
  1153. Show grabbed region on screen.
  1154. If @var{show_region} is specified with @code{1}, then the grabbing
  1155. region will be indicated on screen. With this option, it is easy to
  1156. know what is being grabbed if only a portion of the screen is grabbed.
  1157. @item region_border
  1158. Set the region border thickness if @option{-show_region 1} is used.
  1159. Range is 1 to 128 and default is 3 (XCB-based x11grab only).
  1160. For example:
  1161. @example
  1162. ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
  1163. @end example
  1164. With @var{follow_mouse}:
  1165. @example
  1166. ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg
  1167. @end example
  1168. @item window_id
  1169. Grab this window, instead of the whole screen. Default value is 0, which maps to
  1170. the whole screen (root window).
  1171. The id of a window can be found using the @command{xwininfo} program, possibly with options -tree and
  1172. -root.
  1173. If the window is later enlarged, the new area is not recorded. Video ends when
  1174. the window is closed, unmapped (i.e., iconified) or shrunk beyond the video
  1175. size (which defaults to the initial window size).
  1176. This option disables options @option{follow_mouse} and @option{select_region}.
  1177. @item video_size
  1178. Set the video frame size. Default is the full desktop or window.
  1179. @item grab_x
  1180. @item grab_y
  1181. Set the grabbing region coordinates. They are expressed as offset from
  1182. the top left corner of the X11 window and correspond to the
  1183. @var{x_offset} and @var{y_offset} parameters in the device name. The
  1184. default value for both options is 0.
  1185. @end table
  1186. @c man end INPUT DEVICES