Commit | Line | Data |
---|---|---|
2ba45a60 DM |
1 | @chapter Input Devices |
2 | @c man begin INPUT DEVICES | |
3 | ||
4 | Input devices are configured elements in FFmpeg which allow to access | |
5 | the data coming from a multimedia device attached to your system. | |
6 | ||
7 | When you configure your FFmpeg build, all the supported input devices | |
8 | are enabled by default. You can list all available ones using the | |
9 | configure option "--list-indevs". | |
10 | ||
11 | You can disable all the input devices using the configure option | |
12 | "--disable-indevs", and selectively enable an input device using the | |
13 | option "--enable-indev=@var{INDEV}", or you can disable a particular | |
14 | input device using the option "--disable-indev=@var{INDEV}". | |
15 | ||
16 | The option "-devices" of the ff* tools will display the list of | |
17 | supported input devices. | |
18 | ||
19 | A description of the currently available input devices follows. | |
20 | ||
21 | @section alsa | |
22 | ||
23 | ALSA (Advanced Linux Sound Architecture) input device. | |
24 | ||
25 | To enable this input device during configuration you need libasound | |
26 | installed on your system. | |
27 | ||
28 | This device allows capturing from an ALSA device. The name of the | |
29 | device to capture has to be an ALSA card identifier. | |
30 | ||
31 | An ALSA identifier has the syntax: | |
32 | @example | |
33 | hw:@var{CARD}[,@var{DEV}[,@var{SUBDEV}]] | |
34 | @end example | |
35 | ||
36 | where the @var{DEV} and @var{SUBDEV} components are optional. | |
37 | ||
38 | The three arguments (in order: @var{CARD},@var{DEV},@var{SUBDEV}) | |
39 | specify card number or identifier, device number and subdevice number | |
40 | (-1 means any). | |
41 | ||
42 | To see the list of cards currently recognized by your system check the | |
43 | files @file{/proc/asound/cards} and @file{/proc/asound/devices}. | |
44 | ||
45 | For example to capture with @command{ffmpeg} from an ALSA device with | |
46 | card id 0, you may run the command: | |
47 | @example | |
48 | ffmpeg -f alsa -i hw:0 alsaout.wav | |
49 | @end example | |
50 | ||
51 | For more information see: | |
52 | @url{http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html} | |
53 | ||
54 | @section avfoundation | |
55 | ||
56 | AVFoundation input device. | |
57 | ||
58 | AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS. | |
59 | The older QTKit framework has been marked deprecated since OSX version 10.7. | |
60 | ||
f6fa7814 DM |
61 | The input filename has to be given in the following syntax: |
62 | @example | |
63 | -i "[[VIDEO]:[AUDIO]]" | |
64 | @end example | |
65 | The first entry selects the video input while the latter selects the audio input. | |
66 | The stream has to be specified by the device name or the device index as shown by the device list. | |
67 | Alternatively, the video and/or audio input device can be chosen by index using the | |
68 | @option{ | |
69 | -video_device_index <INDEX> | |
70 | } | |
71 | and/or | |
72 | @option{ | |
73 | -audio_device_index <INDEX> | |
74 | } | |
75 | , overriding any | |
76 | device name or index given in the input filename. | |
77 | ||
78 | All available devices can be enumerated by using @option{-list_devices true}, listing | |
79 | all device names and corresponding indices. | |
80 | ||
81 | There are two device name aliases: | |
82 | @table @code | |
83 | ||
84 | @item default | |
85 | Select the AVFoundation default device of the corresponding type. | |
86 | ||
87 | @item none | |
88 | Do not record the corresponding media type. | |
89 | This is equivalent to specifying an empty device name or index. | |
90 | ||
91 | @end table | |
92 | ||
93 | @subsection Options | |
94 | ||
95 | AVFoundation supports the following options: | |
96 | ||
97 | @table @option | |
98 | ||
99 | @item -list_devices <TRUE|FALSE> | |
100 | If set to true, a list of all available input devices is given showing all | |
101 | device names and indices. | |
102 | ||
103 | @item -video_device_index <INDEX> | |
104 | Specify the video device by its index. Overrides anything given in the input filename. | |
105 | ||
106 | @item -audio_device_index <INDEX> | |
107 | Specify the audio device by its index. Overrides anything given in the input filename. | |
108 | ||
109 | @item -pixel_format <FORMAT> | |
110 | Request the video device to use a specific pixel format. | |
111 | If the specified format is not supported, a list of available formats is given | |
112 | und the first one in this list is used instead. Available pixel formats are: | |
113 | @code{monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0, | |
2ba45a60 | 114 | bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10, |
f6fa7814 | 115 | yuv420p, nv12, yuyv422, gray} |
2ba45a60 | 116 | |
f6fa7814 DM |
117 | @end table |
118 | ||
119 | @subsection Examples | |
120 | ||
121 | @itemize | |
122 | ||
123 | @item | |
124 | Print the list of AVFoundation supported devices and exit: | |
2ba45a60 | 125 | @example |
f6fa7814 | 126 | $ ffmpeg -f avfoundation -list_devices true -i "" |
2ba45a60 DM |
127 | @end example |
128 | ||
f6fa7814 DM |
129 | @item |
130 | Record video from video device 0 and audio from audio device 0 into out.avi: | |
2ba45a60 | 131 | @example |
f6fa7814 | 132 | $ ffmpeg -f avfoundation -i "0:0" out.avi |
2ba45a60 DM |
133 | @end example |
134 | ||
f6fa7814 DM |
135 | @item |
136 | Record video from video device 2 and audio from audio device 1 into out.avi: | |
2ba45a60 | 137 | @example |
f6fa7814 | 138 | $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi |
2ba45a60 DM |
139 | @end example |
140 | ||
f6fa7814 DM |
141 | @item |
142 | Record video from the system default video device using the pixel format bgr0 and do not record any audio into out.avi: | |
2ba45a60 | 143 | @example |
f6fa7814 | 144 | $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi |
2ba45a60 DM |
145 | @end example |
146 | ||
f6fa7814 DM |
147 | @end itemize |
148 | ||
2ba45a60 DM |
149 | @section bktr |
150 | ||
151 | BSD video input device. | |
152 | ||
153 | @section dshow | |
154 | ||
155 | Windows DirectShow input device. | |
156 | ||
157 | DirectShow support is enabled when FFmpeg is built with the mingw-w64 project. | |
158 | Currently only audio and video devices are supported. | |
159 | ||
160 | Multiple devices may be opened as separate inputs, but they may also be | |
161 | opened on the same input, which should improve synchronism between them. | |
162 | ||
163 | The input name should be in the format: | |
164 | ||
165 | @example | |
166 | @var{TYPE}=@var{NAME}[:@var{TYPE}=@var{NAME}] | |
167 | @end example | |
168 | ||
169 | where @var{TYPE} can be either @var{audio} or @var{video}, | |
170 | and @var{NAME} is the device's name. | |
171 | ||
172 | @subsection Options | |
173 | ||
174 | If no options are specified, the device's defaults are used. | |
175 | If the device does not support the requested options, it will | |
176 | fail to open. | |
177 | ||
178 | @table @option | |
179 | ||
180 | @item video_size | |
181 | Set the video size in the captured video. | |
182 | ||
183 | @item framerate | |
184 | Set the frame rate in the captured video. | |
185 | ||
186 | @item sample_rate | |
187 | Set the sample rate (in Hz) of the captured audio. | |
188 | ||
189 | @item sample_size | |
190 | Set the sample size (in bits) of the captured audio. | |
191 | ||
192 | @item channels | |
193 | Set the number of channels in the captured audio. | |
194 | ||
195 | @item list_devices | |
196 | If set to @option{true}, print a list of devices and exit. | |
197 | ||
198 | @item list_options | |
199 | If set to @option{true}, print a list of selected device's options | |
200 | and exit. | |
201 | ||
202 | @item video_device_number | |
203 | Set video device number for devices with same name (starts at 0, | |
204 | defaults to 0). | |
205 | ||
206 | @item audio_device_number | |
207 | Set audio device number for devices with same name (starts at 0, | |
208 | defaults to 0). | |
209 | ||
210 | @item pixel_format | |
211 | Select pixel format to be used by DirectShow. This may only be set when | |
212 | the video codec is not set or set to rawvideo. | |
213 | ||
214 | @item audio_buffer_size | |
215 | Set audio device buffer size in milliseconds (which can directly | |
216 | impact latency, depending on the device). | |
217 | Defaults to using the audio device's | |
218 | default buffer size (typically some multiple of 500ms). | |
219 | Setting this value too low can degrade performance. | |
220 | See also | |
221 | @url{http://msdn.microsoft.com/en-us/library/windows/desktop/dd377582(v=vs.85).aspx} | |
222 | ||
223 | @end table | |
224 | ||
225 | @subsection Examples | |
226 | ||
227 | @itemize | |
228 | ||
229 | @item | |
230 | Print the list of DirectShow supported devices and exit: | |
231 | @example | |
232 | $ ffmpeg -list_devices true -f dshow -i dummy | |
233 | @end example | |
234 | ||
235 | @item | |
236 | Open video device @var{Camera}: | |
237 | @example | |
238 | $ ffmpeg -f dshow -i video="Camera" | |
239 | @end example | |
240 | ||
241 | @item | |
242 | Open second video device with name @var{Camera}: | |
243 | @example | |
244 | $ ffmpeg -f dshow -video_device_number 1 -i video="Camera" | |
245 | @end example | |
246 | ||
247 | @item | |
248 | Open video device @var{Camera} and audio device @var{Microphone}: | |
249 | @example | |
250 | $ ffmpeg -f dshow -i video="Camera":audio="Microphone" | |
251 | @end example | |
252 | ||
253 | @item | |
254 | Print the list of supported options in selected device and exit: | |
255 | @example | |
256 | $ ffmpeg -list_options true -f dshow -i video="Camera" | |
257 | @end example | |
258 | ||
259 | @end itemize | |
260 | ||
261 | @section dv1394 | |
262 | ||
263 | Linux DV 1394 input device. | |
264 | ||
265 | @section fbdev | |
266 | ||
267 | Linux framebuffer input device. | |
268 | ||
269 | The Linux framebuffer is a graphic hardware-independent abstraction | |
270 | layer to show graphics on a computer monitor, typically on the | |
271 | console. It is accessed through a file device node, usually | |
272 | @file{/dev/fb0}. | |
273 | ||
274 | For more detailed information read the file | |
275 | Documentation/fb/framebuffer.txt included in the Linux source tree. | |
276 | ||
277 | To record from the framebuffer device @file{/dev/fb0} with | |
278 | @command{ffmpeg}: | |
279 | @example | |
280 | ffmpeg -f fbdev -r 10 -i /dev/fb0 out.avi | |
281 | @end example | |
282 | ||
283 | You can take a single screenshot image with the command: | |
284 | @example | |
285 | ffmpeg -f fbdev -frames:v 1 -r 1 -i /dev/fb0 screenshot.jpeg | |
286 | @end example | |
287 | ||
288 | See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1). | |
289 | ||
290 | @section gdigrab | |
291 | ||
292 | Win32 GDI-based screen capture device. | |
293 | ||
294 | This device allows you to capture a region of the display on Windows. | |
295 | ||
296 | There are two options for the input filename: | |
297 | @example | |
298 | desktop | |
299 | @end example | |
300 | or | |
301 | @example | |
302 | title=@var{window_title} | |
303 | @end example | |
304 | ||
305 | The first option will capture the entire desktop, or a fixed region of the | |
306 | desktop. The second option will instead capture the contents of a single | |
307 | window, regardless of its position on the screen. | |
308 | ||
309 | For example, to grab the entire desktop using @command{ffmpeg}: | |
310 | @example | |
311 | ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg | |
312 | @end example | |
313 | ||
314 | Grab a 640x480 region at position @code{10,20}: | |
315 | @example | |
316 | ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg | |
317 | @end example | |
318 | ||
319 | Grab the contents of the window named "Calculator" | |
320 | @example | |
321 | ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg | |
322 | @end example | |
323 | ||
324 | @subsection Options | |
325 | ||
326 | @table @option | |
327 | @item draw_mouse | |
328 | Specify whether to draw the mouse pointer. Use the value @code{0} to | |
329 | not draw the pointer. Default value is @code{1}. | |
330 | ||
331 | @item framerate | |
332 | Set the grabbing frame rate. Default value is @code{ntsc}, | |
333 | corresponding to a frame rate of @code{30000/1001}. | |
334 | ||
335 | @item show_region | |
336 | Show grabbed region on screen. | |
337 | ||
338 | If @var{show_region} is specified with @code{1}, then the grabbing | |
339 | region will be indicated on screen. With this option, it is easy to | |
340 | know what is being grabbed if only a portion of the screen is grabbed. | |
341 | ||
342 | Note that @var{show_region} is incompatible with grabbing the contents | |
343 | of a single window. | |
344 | ||
345 | For example: | |
346 | @example | |
347 | ffmpeg -f gdigrab -show_region 1 -framerate 6 -video_size cif -offset_x 10 -offset_y 20 -i desktop out.mpg | |
348 | @end example | |
349 | ||
350 | @item video_size | |
351 | 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. | |
352 | ||
353 | @item offset_x | |
354 | When capturing a region with @var{video_size}, set the distance from the left edge of the screen or desktop. | |
355 | ||
356 | 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. | |
357 | ||
358 | @item offset_y | |
359 | When capturing a region with @var{video_size}, set the distance from the top edge of the screen or desktop. | |
360 | ||
361 | 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. | |
362 | ||
363 | @end table | |
364 | ||
365 | @section iec61883 | |
366 | ||
367 | FireWire DV/HDV input device using libiec61883. | |
368 | ||
369 | To enable this input device, you need libiec61883, libraw1394 and | |
370 | libavc1394 installed on your system. Use the configure option | |
371 | @code{--enable-libiec61883} to compile with the device enabled. | |
372 | ||
373 | The iec61883 capture device supports capturing from a video device | |
374 | connected via IEEE1394 (FireWire), using libiec61883 and the new Linux | |
375 | FireWire stack (juju). This is the default DV/HDV input method in Linux | |
376 | Kernel 2.6.37 and later, since the old FireWire stack was removed. | |
377 | ||
378 | Specify the FireWire port to be used as input file, or "auto" | |
379 | to choose the first port connected. | |
380 | ||
381 | @subsection Options | |
382 | ||
383 | @table @option | |
384 | ||
385 | @item dvtype | |
386 | Override autodetection of DV/HDV. This should only be used if auto | |
387 | detection does not work, or if usage of a different device type | |
388 | should be prohibited. Treating a DV device as HDV (or vice versa) will | |
389 | not work and result in undefined behavior. | |
390 | The values @option{auto}, @option{dv} and @option{hdv} are supported. | |
391 | ||
392 | @item dvbuffer | |
393 | Set maxiumum size of buffer for incoming data, in frames. For DV, this | |
394 | is an exact value. For HDV, it is not frame exact, since HDV does | |
395 | not have a fixed frame size. | |
396 | ||
397 | @item dvguid | |
398 | Select the capture device by specifying it's GUID. Capturing will only | |
399 | be performed from the specified device and fails if no device with the | |
400 | given GUID is found. This is useful to select the input if multiple | |
401 | devices are connected at the same time. | |
402 | Look at /sys/bus/firewire/devices to find out the GUIDs. | |
403 | ||
404 | @end table | |
405 | ||
406 | @subsection Examples | |
407 | ||
408 | @itemize | |
409 | ||
410 | @item | |
411 | Grab and show the input of a FireWire DV/HDV device. | |
412 | @example | |
413 | ffplay -f iec61883 -i auto | |
414 | @end example | |
415 | ||
416 | @item | |
417 | Grab and record the input of a FireWire DV/HDV device, | |
418 | using a packet buffer of 100000 packets if the source is HDV. | |
419 | @example | |
420 | ffmpeg -f iec61883 -i auto -hdvbuffer 100000 out.mpg | |
421 | @end example | |
422 | ||
423 | @end itemize | |
424 | ||
425 | @section jack | |
426 | ||
427 | JACK input device. | |
428 | ||
429 | To enable this input device during configuration you need libjack | |
430 | installed on your system. | |
431 | ||
432 | A JACK input device creates one or more JACK writable clients, one for | |
433 | each audio channel, with name @var{client_name}:input_@var{N}, where | |
434 | @var{client_name} is the name provided by the application, and @var{N} | |
435 | is a number which identifies the channel. | |
436 | Each writable client will send the acquired data to the FFmpeg input | |
437 | device. | |
438 | ||
439 | Once you have created one or more JACK readable clients, you need to | |
440 | connect them to one or more JACK writable clients. | |
441 | ||
442 | To connect or disconnect JACK clients you can use the @command{jack_connect} | |
443 | and @command{jack_disconnect} programs, or do it through a graphical interface, | |
444 | for example with @command{qjackctl}. | |
445 | ||
446 | To list the JACK clients and their properties you can invoke the command | |
447 | @command{jack_lsp}. | |
448 | ||
449 | Follows an example which shows how to capture a JACK readable client | |
450 | with @command{ffmpeg}. | |
451 | @example | |
452 | # Create a JACK writable client with name "ffmpeg". | |
453 | $ ffmpeg -f jack -i ffmpeg -y out.wav | |
454 | ||
455 | # Start the sample jack_metro readable client. | |
456 | $ jack_metro -b 120 -d 0.2 -f 4000 | |
457 | ||
458 | # List the current JACK clients. | |
459 | $ jack_lsp -c | |
460 | system:capture_1 | |
461 | system:capture_2 | |
462 | system:playback_1 | |
463 | system:playback_2 | |
464 | ffmpeg:input_1 | |
465 | metro:120_bpm | |
466 | ||
467 | # Connect metro to the ffmpeg writable client. | |
468 | $ jack_connect metro:120_bpm ffmpeg:input_1 | |
469 | @end example | |
470 | ||
471 | For more information read: | |
472 | @url{http://jackaudio.org/} | |
473 | ||
474 | @section lavfi | |
475 | ||
476 | Libavfilter input virtual device. | |
477 | ||
478 | This input device reads data from the open output pads of a libavfilter | |
479 | filtergraph. | |
480 | ||
481 | For each filtergraph open output, the input device will create a | |
482 | corresponding stream which is mapped to the generated output. Currently | |
483 | only video data is supported. The filtergraph is specified through the | |
484 | option @option{graph}. | |
485 | ||
486 | @subsection Options | |
487 | ||
488 | @table @option | |
489 | ||
490 | @item graph | |
491 | Specify the filtergraph to use as input. Each video open output must be | |
492 | labelled by a unique string of the form "out@var{N}", where @var{N} is a | |
493 | number starting from 0 corresponding to the mapped input stream | |
494 | generated by the device. | |
495 | The first unlabelled output is automatically assigned to the "out0" | |
496 | label, but all the others need to be specified explicitly. | |
497 | ||
498 | If not specified defaults to the filename specified for the input | |
499 | device. | |
500 | ||
501 | @item graph_file | |
502 | Set the filename of the filtergraph to be read and sent to the other | |
503 | filters. Syntax of the filtergraph is the same as the one specified by | |
504 | the option @var{graph}. | |
505 | ||
506 | @end table | |
507 | ||
508 | @subsection Examples | |
509 | ||
510 | @itemize | |
511 | @item | |
512 | Create a color video stream and play it back with @command{ffplay}: | |
513 | @example | |
514 | ffplay -f lavfi -graph "color=c=pink [out0]" dummy | |
515 | @end example | |
516 | ||
517 | @item | |
518 | As the previous example, but use filename for specifying the graph | |
519 | description, and omit the "out0" label: | |
520 | @example | |
521 | ffplay -f lavfi color=c=pink | |
522 | @end example | |
523 | ||
524 | @item | |
525 | Create three different video test filtered sources and play them: | |
526 | @example | |
527 | ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3 | |
528 | @end example | |
529 | ||
530 | @item | |
531 | Read an audio stream from a file using the amovie source and play it | |
532 | back with @command{ffplay}: | |
533 | @example | |
534 | ffplay -f lavfi "amovie=test.wav" | |
535 | @end example | |
536 | ||
537 | @item | |
538 | Read an audio stream and a video stream and play it back with | |
539 | @command{ffplay}: | |
540 | @example | |
541 | ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]" | |
542 | @end example | |
543 | ||
544 | @end itemize | |
545 | ||
546 | @section libcdio | |
547 | ||
548 | Audio-CD input device based on cdio. | |
549 | ||
550 | To enable this input device during configuration you need libcdio | |
551 | installed on your system. Requires the configure option | |
552 | @code{--enable-libcdio}. | |
553 | ||
554 | This device allows playing and grabbing from an Audio-CD. | |
555 | ||
556 | For example to copy with @command{ffmpeg} the entire Audio-CD in /dev/sr0, | |
557 | you may run the command: | |
558 | @example | |
559 | ffmpeg -f libcdio -i /dev/sr0 cd.wav | |
560 | @end example | |
561 | ||
562 | @section libdc1394 | |
563 | ||
564 | IIDC1394 input device, based on libdc1394 and libraw1394. | |
565 | ||
566 | Requires the configure option @code{--enable-libdc1394}. | |
567 | ||
568 | @section openal | |
569 | ||
570 | The OpenAL input device provides audio capture on all systems with a | |
571 | working OpenAL 1.1 implementation. | |
572 | ||
573 | To enable this input device during configuration, you need OpenAL | |
574 | headers and libraries installed on your system, and need to configure | |
575 | FFmpeg with @code{--enable-openal}. | |
576 | ||
577 | OpenAL headers and libraries should be provided as part of your OpenAL | |
578 | implementation, or as an additional download (an SDK). Depending on your | |
579 | installation you may need to specify additional flags via the | |
580 | @code{--extra-cflags} and @code{--extra-ldflags} for allowing the build | |
581 | system to locate the OpenAL headers and libraries. | |
582 | ||
583 | An incomplete list of OpenAL implementations follows: | |
584 | ||
585 | @table @strong | |
586 | @item Creative | |
587 | The official Windows implementation, providing hardware acceleration | |
588 | with supported devices and software fallback. | |
589 | See @url{http://openal.org/}. | |
590 | @item OpenAL Soft | |
591 | Portable, open source (LGPL) software implementation. Includes | |
592 | backends for the most common sound APIs on the Windows, Linux, | |
593 | Solaris, and BSD operating systems. | |
594 | See @url{http://kcat.strangesoft.net/openal.html}. | |
595 | @item Apple | |
596 | OpenAL is part of Core Audio, the official Mac OS X Audio interface. | |
597 | See @url{http://developer.apple.com/technologies/mac/audio-and-video.html} | |
598 | @end table | |
599 | ||
600 | This device allows one to capture from an audio input device handled | |
601 | through OpenAL. | |
602 | ||
603 | You need to specify the name of the device to capture in the provided | |
604 | filename. If the empty string is provided, the device will | |
605 | automatically select the default device. You can get the list of the | |
606 | supported devices by using the option @var{list_devices}. | |
607 | ||
608 | @subsection Options | |
609 | ||
610 | @table @option | |
611 | ||
612 | @item channels | |
613 | Set the number of channels in the captured audio. Only the values | |
614 | @option{1} (monaural) and @option{2} (stereo) are currently supported. | |
615 | Defaults to @option{2}. | |
616 | ||
617 | @item sample_size | |
618 | Set the sample size (in bits) of the captured audio. Only the values | |
619 | @option{8} and @option{16} are currently supported. Defaults to | |
620 | @option{16}. | |
621 | ||
622 | @item sample_rate | |
623 | Set the sample rate (in Hz) of the captured audio. | |
624 | Defaults to @option{44.1k}. | |
625 | ||
626 | @item list_devices | |
627 | If set to @option{true}, print a list of devices and exit. | |
628 | Defaults to @option{false}. | |
629 | ||
630 | @end table | |
631 | ||
632 | @subsection Examples | |
633 | ||
634 | Print the list of OpenAL supported devices and exit: | |
635 | @example | |
636 | $ ffmpeg -list_devices true -f openal -i dummy out.ogg | |
637 | @end example | |
638 | ||
639 | Capture from the OpenAL device @file{DR-BT101 via PulseAudio}: | |
640 | @example | |
641 | $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg | |
642 | @end example | |
643 | ||
644 | Capture from the default device (note the empty string '' as filename): | |
645 | @example | |
646 | $ ffmpeg -f openal -i '' out.ogg | |
647 | @end example | |
648 | ||
649 | Capture from two devices simultaneously, writing to two different files, | |
650 | within the same @command{ffmpeg} command: | |
651 | @example | |
652 | $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg | |
653 | @end example | |
654 | Note: not all OpenAL implementations support multiple simultaneous capture - | |
655 | try the latest OpenAL Soft if the above does not work. | |
656 | ||
657 | @section oss | |
658 | ||
659 | Open Sound System input device. | |
660 | ||
661 | The filename to provide to the input device is the device node | |
662 | representing the OSS input device, and is usually set to | |
663 | @file{/dev/dsp}. | |
664 | ||
665 | For example to grab from @file{/dev/dsp} using @command{ffmpeg} use the | |
666 | command: | |
667 | @example | |
668 | ffmpeg -f oss -i /dev/dsp /tmp/oss.wav | |
669 | @end example | |
670 | ||
671 | For more information about OSS see: | |
672 | @url{http://manuals.opensound.com/usersguide/dsp.html} | |
673 | ||
674 | @section pulse | |
675 | ||
676 | PulseAudio input device. | |
677 | ||
678 | To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}. | |
679 | ||
680 | The filename to provide to the input device is a source device or the | |
681 | string "default" | |
682 | ||
683 | To list the PulseAudio source devices and their properties you can invoke | |
684 | the command @command{pactl list sources}. | |
685 | ||
686 | More information about PulseAudio can be found on @url{http://www.pulseaudio.org}. | |
687 | ||
688 | @subsection Options | |
689 | @table @option | |
690 | @item server | |
691 | Connect to a specific PulseAudio server, specified by an IP address. | |
692 | Default server is used when not provided. | |
693 | ||
694 | @item name | |
695 | Specify the application name PulseAudio will use when showing active clients, | |
696 | by default it is the @code{LIBAVFORMAT_IDENT} string. | |
697 | ||
698 | @item stream_name | |
699 | Specify the stream name PulseAudio will use when showing active streams, | |
700 | by default it is "record". | |
701 | ||
702 | @item sample_rate | |
703 | Specify the samplerate in Hz, by default 48kHz is used. | |
704 | ||
705 | @item channels | |
706 | Specify the channels in use, by default 2 (stereo) is set. | |
707 | ||
708 | @item frame_size | |
709 | Specify the number of bytes per frame, by default it is set to 1024. | |
710 | ||
711 | @item fragment_size | |
712 | Specify the minimal buffering fragment in PulseAudio, it will affect the | |
713 | audio latency. By default it is unset. | |
714 | @end table | |
715 | ||
716 | @subsection Examples | |
717 | Record a stream from default device: | |
718 | @example | |
719 | ffmpeg -f pulse -i default /tmp/pulse.wav | |
720 | @end example | |
721 | ||
722 | @section qtkit | |
723 | ||
724 | QTKit input device. | |
725 | ||
726 | The filename passed as input is parsed to contain either a device name or index. | |
727 | The device index can also be given by using -video_device_index. | |
728 | A given device index will override any given device name. | |
729 | If the desired device consists of numbers only, use -video_device_index to identify it. | |
730 | The default device will be chosen if an empty string or the device name "default" is given. | |
731 | The available devices can be enumerated by using -list_devices. | |
732 | ||
733 | @example | |
734 | ffmpeg -f qtkit -i "0" out.mpg | |
735 | @end example | |
736 | ||
737 | @example | |
738 | ffmpeg -f qtkit -video_device_index 0 -i "" out.mpg | |
739 | @end example | |
740 | ||
741 | @example | |
742 | ffmpeg -f qtkit -i "default" out.mpg | |
743 | @end example | |
744 | ||
745 | @example | |
746 | ffmpeg -f qtkit -list_devices true -i "" | |
747 | @end example | |
748 | ||
749 | @section sndio | |
750 | ||
751 | sndio input device. | |
752 | ||
753 | To enable this input device during configuration you need libsndio | |
754 | installed on your system. | |
755 | ||
756 | The filename to provide to the input device is the device node | |
757 | representing the sndio input device, and is usually set to | |
758 | @file{/dev/audio0}. | |
759 | ||
760 | For example to grab from @file{/dev/audio0} using @command{ffmpeg} use the | |
761 | command: | |
762 | @example | |
763 | ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav | |
764 | @end example | |
765 | ||
766 | @section video4linux2, v4l2 | |
767 | ||
768 | Video4Linux2 input video device. | |
769 | ||
770 | "v4l2" can be used as alias for "video4linux2". | |
771 | ||
772 | If FFmpeg is built with v4l-utils support (by using the | |
773 | @code{--enable-libv4l2} configure option), it is possible to use it with the | |
774 | @code{-use_libv4l2} input device option. | |
775 | ||
776 | The name of the device to grab is a file device node, usually Linux | |
777 | systems tend to automatically create such nodes when the device | |
778 | (e.g. an USB webcam) is plugged into the system, and has a name of the | |
779 | kind @file{/dev/video@var{N}}, where @var{N} is a number associated to | |
780 | the device. | |
781 | ||
782 | Video4Linux2 devices usually support a limited set of | |
783 | @var{width}x@var{height} sizes and frame rates. You can check which are | |
784 | supported using @command{-list_formats all} for Video4Linux2 devices. | |
785 | Some devices, like TV cards, support one or more standards. It is possible | |
786 | to list all the supported standards using @command{-list_standards all}. | |
787 | ||
788 | The time base for the timestamps is 1 microsecond. Depending on the kernel | |
789 | version and configuration, the timestamps may be derived from the real time | |
790 | clock (origin at the Unix Epoch) or the monotonic clock (origin usually at | |
791 | boot time, unaffected by NTP or manual changes to the clock). The | |
792 | @option{-timestamps abs} or @option{-ts abs} option can be used to force | |
793 | conversion into the real time clock. | |
794 | ||
795 | Some usage examples of the video4linux2 device with @command{ffmpeg} | |
796 | and @command{ffplay}: | |
797 | @itemize | |
798 | @item | |
799 | Grab and show the input of a video4linux2 device: | |
800 | @example | |
801 | ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0 | |
802 | @end example | |
803 | ||
804 | @item | |
805 | Grab and record the input of a video4linux2 device, leave the | |
806 | frame rate and size as previously set: | |
807 | @example | |
808 | ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg | |
809 | @end example | |
810 | @end itemize | |
811 | ||
812 | For more information about Video4Linux, check @url{http://linuxtv.org/}. | |
813 | ||
814 | @subsection Options | |
815 | ||
816 | @table @option | |
817 | @item standard | |
818 | Set the standard. Must be the name of a supported standard. To get a | |
819 | list of the supported standards, use the @option{list_standards} | |
820 | option. | |
821 | ||
822 | @item channel | |
823 | Set the input channel number. Default to -1, which means using the | |
824 | previously selected channel. | |
825 | ||
826 | @item video_size | |
827 | Set the video frame size. The argument must be a string in the form | |
828 | @var{WIDTH}x@var{HEIGHT} or a valid size abbreviation. | |
829 | ||
830 | @item pixel_format | |
831 | Select the pixel format (only valid for raw video input). | |
832 | ||
833 | @item input_format | |
834 | Set the preferred pixel format (for raw video) or a codec name. | |
835 | This option allows one to select the input format, when several are | |
836 | available. | |
837 | ||
838 | @item framerate | |
839 | Set the preferred video frame rate. | |
840 | ||
841 | @item list_formats | |
842 | List available formats (supported pixel formats, codecs, and frame | |
843 | sizes) and exit. | |
844 | ||
845 | Available values are: | |
846 | @table @samp | |
847 | @item all | |
848 | Show all available (compressed and non-compressed) formats. | |
849 | ||
850 | @item raw | |
851 | Show only raw video (non-compressed) formats. | |
852 | ||
853 | @item compressed | |
854 | Show only compressed formats. | |
855 | @end table | |
856 | ||
857 | @item list_standards | |
858 | List supported standards and exit. | |
859 | ||
860 | Available values are: | |
861 | @table @samp | |
862 | @item all | |
863 | Show all supported standards. | |
864 | @end table | |
865 | ||
866 | @item timestamps, ts | |
867 | Set type of timestamps for grabbed frames. | |
868 | ||
869 | Available values are: | |
870 | @table @samp | |
871 | @item default | |
872 | Use timestamps from the kernel. | |
873 | ||
874 | @item abs | |
875 | Use absolute timestamps (wall clock). | |
876 | ||
877 | @item mono2abs | |
878 | Force conversion from monotonic to absolute timestamps. | |
879 | @end table | |
880 | ||
881 | Default value is @code{default}. | |
882 | @end table | |
883 | ||
884 | @section vfwcap | |
885 | ||
886 | VfW (Video for Windows) capture input device. | |
887 | ||
888 | The filename passed as input is the capture driver number, ranging from | |
889 | 0 to 9. You may use "list" as filename to print a list of drivers. Any | |
890 | other filename will be interpreted as device number 0. | |
891 | ||
892 | @section x11grab | |
893 | ||
894 | X11 video input device. | |
895 | ||
896 | Depends on X11, Xext, and Xfixes. Requires the configure option | |
897 | @code{--enable-x11grab}. | |
898 | ||
899 | This device allows one to capture a region of an X11 display. | |
900 | ||
901 | The filename passed as input has the syntax: | |
902 | @example | |
903 | [@var{hostname}]:@var{display_number}.@var{screen_number}[+@var{x_offset},@var{y_offset}] | |
904 | @end example | |
905 | ||
906 | @var{hostname}:@var{display_number}.@var{screen_number} specifies the | |
907 | X11 display name of the screen to grab from. @var{hostname} can be | |
908 | omitted, and defaults to "localhost". The environment variable | |
909 | @env{DISPLAY} contains the default display name. | |
910 | ||
911 | @var{x_offset} and @var{y_offset} specify the offsets of the grabbed | |
912 | area with respect to the top-left border of the X11 screen. They | |
913 | default to 0. | |
914 | ||
915 | Check the X11 documentation (e.g. man X) for more detailed information. | |
916 | ||
917 | Use the @command{dpyinfo} program for getting basic information about the | |
918 | properties of your X11 display (e.g. grep for "name" or "dimensions"). | |
919 | ||
920 | For example to grab from @file{:0.0} using @command{ffmpeg}: | |
921 | @example | |
922 | ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg | |
923 | @end example | |
924 | ||
925 | Grab at position @code{10,20}: | |
926 | @example | |
927 | ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg | |
928 | @end example | |
929 | ||
930 | @subsection Options | |
931 | ||
932 | @table @option | |
933 | @item draw_mouse | |
934 | Specify whether to draw the mouse pointer. A value of @code{0} specify | |
935 | not to draw the pointer. Default value is @code{1}. | |
936 | ||
937 | @item follow_mouse | |
938 | Make the grabbed area follow the mouse. The argument can be | |
939 | @code{centered} or a number of pixels @var{PIXELS}. | |
940 | ||
941 | When it is specified with "centered", the grabbing region follows the mouse | |
942 | pointer and keeps the pointer at the center of region; otherwise, the region | |
943 | follows only when the mouse pointer reaches within @var{PIXELS} (greater than | |
944 | zero) to the edge of region. | |
945 | ||
946 | For example: | |
947 | @example | |
948 | ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg | |
949 | @end example | |
950 | ||
951 | To follow only when the mouse pointer reaches within 100 pixels to edge: | |
952 | @example | |
953 | ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg | |
954 | @end example | |
955 | ||
956 | @item framerate | |
957 | Set the grabbing frame rate. Default value is @code{ntsc}, | |
958 | corresponding to a frame rate of @code{30000/1001}. | |
959 | ||
960 | @item show_region | |
961 | Show grabbed region on screen. | |
962 | ||
963 | If @var{show_region} is specified with @code{1}, then the grabbing | |
964 | region will be indicated on screen. With this option, it is easy to | |
965 | know what is being grabbed if only a portion of the screen is grabbed. | |
966 | ||
967 | For example: | |
968 | @example | |
969 | ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg | |
970 | @end example | |
971 | ||
972 | With @var{follow_mouse}: | |
973 | @example | |
974 | ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg | |
975 | @end example | |
976 | ||
977 | @item video_size | |
978 | Set the video frame size. Default value is @code{vga}. | |
979 | ||
980 | @item use_shm | |
981 | Use the MIT-SHM extension for shared memory. Default value is @code{1}. | |
982 | It may be necessary to disable it for remote displays. | |
983 | @end table | |
984 | ||
f6fa7814 DM |
985 | @section decklink |
986 | ||
987 | The decklink input device provides capture capabilities for Blackmagic | |
988 | DeckLink devices. | |
989 | ||
990 | To enable this input device, you need the Blackmagic DeckLink SDK and you | |
991 | need to configure with the appropriate @code{--extra-cflags} | |
992 | and @code{--extra-ldflags}. | |
993 | On Windows, you need to run the IDL files through @command{widl}. | |
994 | ||
995 | DeckLink is very picky about the formats it supports. Pixel format is always | |
996 | uyvy422, framerate and video size must be determined for your device with | |
997 | @command{-list_formats 1}. Audio sample rate is always 48 kHz and the number | |
998 | of channels currently is limited to 2 (stereo). | |
999 | ||
1000 | @subsection Options | |
1001 | ||
1002 | @table @option | |
1003 | ||
1004 | @item list_devices | |
1005 | If set to @option{true}, print a list of devices and exit. | |
1006 | Defaults to @option{false}. | |
1007 | ||
1008 | @item list_formats | |
1009 | If set to @option{true}, print a list of supported formats and exit. | |
1010 | Defaults to @option{false}. | |
1011 | ||
1012 | @end table | |
1013 | ||
1014 | @subsection Examples | |
1015 | ||
1016 | @itemize | |
1017 | ||
1018 | @item | |
1019 | List input devices: | |
1020 | @example | |
1021 | ffmpeg -f decklink -list_devices 1 -i dummy | |
1022 | @end example | |
1023 | ||
1024 | @item | |
1025 | List supported formats: | |
1026 | @example | |
1027 | ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro' | |
1028 | @end example | |
1029 | ||
1030 | @item | |
1031 | Capture video clip at 1080i50 (format 11): | |
1032 | @example | |
1033 | ffmpeg -f decklink -i 'Intensity Pro@@11' -acodec copy -vcodec copy output.avi | |
1034 | @end example | |
1035 | ||
1036 | @end itemize | |
1037 | ||
1038 | ||
2ba45a60 | 1039 | @c man end INPUT DEVICES |