Merge commit '72a19f4013ec2c7f8581416f8ad4bf81df163fb6'
[ffmpeg.git] / doc / indevs.texi
1 @chapter Input Devices
2 @c man begin INPUT DEVICES
3
4 Input devices are configured elements in FFmpeg which enable accessing
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 @subsection Options
55
56 @table @option
57
58 @item sample_rate
59 Set the sample rate in Hz. Default is 48000.
60
61 @item channels
62 Set the number of channels. Default is 2.
63
64 @end table
65
66 @section avfoundation
67
68 AVFoundation input device.
69
70 AVFoundation is the currently recommended framework by Apple for streamgrabbing on OSX >= 10.7 as well as on iOS.
71 The older QTKit framework has been marked deprecated since OSX version 10.7.
72
73 The input filename has to be given in the following syntax:
74 @example
75 -i "[[VIDEO]:[AUDIO]]"
76 @end example
77 The first entry selects the video input while the latter selects the audio input.
78 The stream has to be specified by the device name or the device index as shown by the device list.
79 Alternatively, the video and/or audio input device can be chosen by index using the
80 @option{
81     -video_device_index <INDEX>
82 }
83 and/or
84 @option{
85     -audio_device_index <INDEX>
86 }
87 , overriding any
88 device name or index given in the input filename.
89
90 All available devices can be enumerated by using @option{-list_devices true}, listing
91 all device names and corresponding indices.
92
93 There are two device name aliases:
94 @table @code
95
96 @item default
97 Select the AVFoundation default device of the corresponding type.
98
99 @item none
100 Do not record the corresponding media type.
101 This is equivalent to specifying an empty device name or index.
102
103 @end table
104
105 @subsection Options
106
107 AVFoundation supports the following options:
108
109 @table @option
110
111 @item -list_devices <TRUE|FALSE>
112 If set to true, a list of all available input devices is given showing all
113 device names and indices.
114
115 @item -video_device_index <INDEX>
116 Specify the video device by its index. Overrides anything given in the input filename.
117
118 @item -audio_device_index <INDEX>
119 Specify the audio device by its index. Overrides anything given in the input filename.
120
121 @item -pixel_format <FORMAT>
122 Request the video device to use a specific pixel format.
123 If the specified format is not supported, a list of available formats is given
124 and the first one in this list is used instead. Available pixel formats are:
125 @code{monob, rgb555be, rgb555le, rgb565be, rgb565le, rgb24, bgr24, 0rgb, bgr0, 0bgr, rgb0,
126  bgr48be, uyvy422, yuva444p, yuva444p16le, yuv444p, yuv422p16, yuv422p10, yuv444p10,
127  yuv420p, nv12, yuyv422, gray}
128
129 @item -framerate
130 Set the grabbing frame rate. Default is @code{ntsc}, corresponding to a
131 frame rate of @code{30000/1001}.
132
133 @item -video_size
134 Set the video frame size.
135
136 @item -capture_cursor
137 Capture the mouse pointer. Default is 0.
138
139 @item -capture_mouse_clicks
140 Capture the screen mouse clicks. Default is 0.
141
142 @end table
143
144 @subsection Examples
145
146 @itemize
147
148 @item
149 Print the list of AVFoundation supported devices and exit:
150 @example
151 $ ffmpeg -f avfoundation -list_devices true -i ""
152 @end example
153
154 @item
155 Record video from video device 0 and audio from audio device 0 into out.avi:
156 @example
157 $ ffmpeg -f avfoundation -i "0:0" out.avi
158 @end example
159
160 @item
161 Record video from video device 2 and audio from audio device 1 into out.avi:
162 @example
163 $ ffmpeg -f avfoundation -video_device_index 2 -i ":1" out.avi
164 @end example
165
166 @item
167 Record video from the system default video device using the pixel format bgr0 and do not record any audio into out.avi:
168 @example
169 $ ffmpeg -f avfoundation -pixel_format bgr0 -i "default:none" out.avi
170 @end example
171
172 @end itemize
173
174 @section bktr
175
176 BSD video input device.
177
178 @subsection Options
179
180 @table @option
181
182 @item framerate
183 Set the frame rate.
184
185 @item video_size
186 Set the video frame size. Default is @code{vga}.
187
188 @item standard
189
190 Available values are:
191 @table @samp
192 @item pal
193
194 @item ntsc
195
196 @item secam
197
198 @item paln
199
200 @item palm
201
202 @item ntscj
203
204 @end table
205
206 @end table
207
208 @section decklink
209
210 The decklink input device provides capture capabilities for Blackmagic
211 DeckLink devices.
212
213 To enable this input device, you need the Blackmagic DeckLink SDK and you
214 need to configure with the appropriate @code{--extra-cflags}
215 and @code{--extra-ldflags}.
216 On Windows, you need to run the IDL files through @command{widl}.
217
218 DeckLink is very picky about the formats it supports. Pixel format is
219 uyvy422 or v210, framerate and video size must be determined for your device with
220 @command{-list_formats 1}. Audio sample rate is always 48 kHz and the number
221 of channels can be 2, 8 or 16. Note that all audio channels are bundled in one single
222 audio track.
223
224 @subsection Options
225
226 @table @option
227
228 @item list_devices
229 If set to @option{true}, print a list of devices and exit.
230 Defaults to @option{false}.
231
232 @item list_formats
233 If set to @option{true}, print a list of supported formats and exit.
234 Defaults to @option{false}.
235
236 @item format_code <FourCC>
237 This sets the input video format to the format given by the FourCC. To see
238 the supported values of your device(s) use @option{list_formats}.
239 Note that there is a FourCC @option{'pal '} that can also be used
240 as @option{pal} (3 letters).
241
242 @item bm_v210
243 If set to @samp{1}, video is captured in 10 bit v210 instead
244 of uyvy422. Not all Blackmagic devices support this option.
245
246 @item teletext_lines
247 If set to nonzero, an additional teletext stream will be captured from the
248 vertical ancillary data. This option is a bitmask of the VBI lines checked,
249 specifically lines 6 to 22, and lines 318 to 335. Line 6 is the LSB in the mask.
250 Selected lines which do not contain teletext information will be ignored. You
251 can use the special @option{all} constant to select all possible lines, or
252 @option{standard} to skip lines 6, 318 and 319, which are not compatible with all
253 receivers. Capturing teletext only works for SD PAL sources in 8 bit mode.
254 To use this option, ffmpeg needs to be compiled with @code{--enable-libzvbi}.
255
256 @item channels
257 Defines number of audio channels to capture. Must be @samp{2}, @samp{8} or @samp{16}.
258 Defaults to @samp{2}.
259
260 @item duplex_mode
261 Sets the decklink device duplex mode. Must be @samp{unset}, @samp{half} or @samp{full}.
262 Defaults to @samp{unset}.
263
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
269 @item audio_input
270 Sets the audio input source. Must be @samp{unset}, @samp{embedded},
271 @samp{aes_ebu}, @samp{analog}, @samp{analog_xlr}, @samp{analog_rca} or
272 @samp{microphone}. Defaults to @samp{unset}.
273
274 @item video_pts
275 Sets the video packet timestamp source. Must be @samp{video}, @samp{audio},
276 @samp{reference} or @samp{wallclock}. Defaults to @samp{video}.
277
278 @item audio_pts
279 Sets the audio packet timestamp source. Must be @samp{video}, @samp{audio},
280 @samp{reference} or @samp{wallclock}. Defaults to @samp{audio}.
281
282 @item draw_bars
283 If set to @samp{true}, color bars are drawn in the event of a signal loss.
284 Defaults to @samp{true}.
285
286 @end table
287
288 @subsection Examples
289
290 @itemize
291
292 @item
293 List input devices:
294 @example
295 ffmpeg -f decklink -list_devices 1 -i dummy
296 @end example
297
298 @item
299 List supported formats:
300 @example
301 ffmpeg -f decklink -list_formats 1 -i 'Intensity Pro'
302 @end example
303
304 @item
305 Capture video clip at 1080i50:
306 @example
307 ffmpeg -format_code Hi50 -f decklink -i 'Intensity Pro' -acodec copy -vcodec copy output.avi
308 @end example
309
310 @item
311 Capture video clip at 1080i50 10 bit:
312 @example
313 ffmpeg -bm_v210 1 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -acodec copy -vcodec copy output.avi
314 @end example
315
316 @item
317 Capture video clip at 1080i50 with 16 audio channels:
318 @example
319 ffmpeg -channels 16 -format_code Hi50 -f decklink -i 'UltraStudio Mini Recorder' -acodec copy -vcodec copy output.avi
320 @end example
321
322 @end itemize
323
324 @section dshow
325
326 Windows DirectShow input device.
327
328 DirectShow support is enabled when FFmpeg is built with the mingw-w64 project.
329 Currently only audio and video devices are supported.
330
331 Multiple devices may be opened as separate inputs, but they may also be
332 opened on the same input, which should improve synchronism between them.
333
334 The input name should be in the format:
335
336 @example
337 @var{TYPE}=@var{NAME}[:@var{TYPE}=@var{NAME}]
338 @end example
339
340 where @var{TYPE} can be either @var{audio} or @var{video},
341 and @var{NAME} is the device's name or alternative name..
342
343 @subsection Options
344
345 If no options are specified, the device's defaults are used.
346 If the device does not support the requested options, it will
347 fail to open.
348
349 @table @option
350
351 @item video_size
352 Set the video size in the captured video.
353
354 @item framerate
355 Set the frame rate in the captured video.
356
357 @item sample_rate
358 Set the sample rate (in Hz) of the captured audio.
359
360 @item sample_size
361 Set the sample size (in bits) of the captured audio.
362
363 @item channels
364 Set the number of channels in the captured audio.
365
366 @item list_devices
367 If set to @option{true}, print a list of devices and exit.
368
369 @item list_options
370 If set to @option{true}, print a list of selected device's options
371 and exit.
372
373 @item video_device_number
374 Set video device number for devices with the same name (starts at 0,
375 defaults to 0).
376
377 @item audio_device_number
378 Set audio device number for devices with the same name (starts at 0,
379 defaults to 0).
380
381 @item pixel_format
382 Select pixel format to be used by DirectShow. This may only be set when
383 the video codec is not set or set to rawvideo.
384
385 @item audio_buffer_size
386 Set audio device buffer size in milliseconds (which can directly
387 impact latency, depending on the device).
388 Defaults to using the audio device's
389 default buffer size (typically some multiple of 500ms).
390 Setting this value too low can degrade performance.
391 See also
392 @url{http://msdn.microsoft.com/en-us/library/windows/desktop/dd377582(v=vs.85).aspx}
393
394 @item video_pin_name
395 Select video capture pin to use by name or alternative name.
396
397 @item audio_pin_name
398 Select audio capture pin to use by name or alternative name.
399
400 @item crossbar_video_input_pin_number
401 Select video input pin number for crossbar device. This will be
402 routed to the crossbar device's Video Decoder output pin.
403 Note that changing this value can affect future invocations
404 (sets a new default) until system reboot occurs.
405
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
412 @item show_video_device_dialog
413 If set to @option{true}, before capture starts, popup a display dialog
414 to the end user, allowing them to change video filter properties
415 and configurations manually.
416 Note that for crossbar devices, adjusting values in this dialog
417 may be needed at times to toggle between PAL (25 fps) and NTSC (29.97)
418 input frame rates, sizes, interlacing, etc.  Changing these values can
419 enable different scan rates/frame rates and avoiding green bars at
420 the bottom, flickering scan lines, etc.
421 Note that with some devices, changing these properties can also affect future
422 invocations (sets new defaults) until system reboot occurs.
423
424 @item show_audio_device_dialog
425 If set to @option{true}, before capture starts, popup a display dialog
426 to the end user, allowing them to change audio filter properties
427 and configurations manually.
428
429 @item show_video_crossbar_connection_dialog
430 If set to @option{true}, before capture starts, popup a display
431 dialog to the end user, allowing them to manually
432 modify crossbar pin routings, when it opens a video device.
433
434 @item show_audio_crossbar_connection_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 crossbar pin routings, when it opens an audio device.
438
439 @item show_analog_tv_tuner_dialog
440 If set to @option{true}, before capture starts, popup a display
441 dialog to the end user, allowing them to manually
442 modify TV channels and frequencies.
443
444 @item show_analog_tv_tuner_audio_dialog
445 If set to @option{true}, before capture starts, popup a display
446 dialog to the end user, allowing them to manually
447 modify TV audio (like mono vs. stereo, Language A,B or C).
448
449 @item audio_device_load
450 Load an audio capture filter device from file instead of searching
451 it by name. It may load additional parameters too, if the filter
452 supports the serialization of its properties to.
453 To use this an audio capture source has to be specified, but it can
454 be anything even fake one.
455
456 @item audio_device_save
457 Save the currently used audio capture filter device and its
458 parameters (if the filter supports it) to a file.
459 If a file with the same name exists it will be overwritten.
460
461 @item video_device_load
462 Load a video capture filter device from file instead of searching
463 it by name. It may load additional parameters too, if the filter
464 supports the serialization of its properties to.
465 To use this a video capture source has to be specified, but it can
466 be anything even fake one.
467
468 @item video_device_save
469 Save the currently used video capture filter device and its
470 parameters (if the filter supports it) to a file.
471 If a file with the same name exists it will be overwritten.
472
473 @end table
474
475 @subsection Examples
476
477 @itemize
478
479 @item
480 Print the list of DirectShow supported devices and exit:
481 @example
482 $ ffmpeg -list_devices true -f dshow -i dummy
483 @end example
484
485 @item
486 Open video device @var{Camera}:
487 @example
488 $ ffmpeg -f dshow -i video="Camera"
489 @end example
490
491 @item
492 Open second video device with name @var{Camera}:
493 @example
494 $ ffmpeg -f dshow -video_device_number 1 -i video="Camera"
495 @end example
496
497 @item
498 Open video device @var{Camera} and audio device @var{Microphone}:
499 @example
500 $ ffmpeg -f dshow -i video="Camera":audio="Microphone"
501 @end example
502
503 @item
504 Print the list of supported options in selected device and exit:
505 @example
506 $ ffmpeg -list_options true -f dshow -i video="Camera"
507 @end example
508
509 @item
510 Specify pin names to capture by name or alternative name, specify alternative device name:
511 @example
512 $ 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"
513 @end example
514
515 @item
516 Configure a crossbar device, specifying crossbar pins, allow user to adjust video capture properties at startup:
517 @example
518 $ ffmpeg -f dshow -show_video_device_dialog true -crossbar_video_input_pin_number 0
519      -crossbar_audio_input_pin_number 3 -i video="AVerMedia BDA Analog Capture":audio="AVerMedia BDA Analog Capture"
520 @end example
521
522 @end itemize
523
524 @section dv1394
525
526 Linux DV 1394 input device.
527
528 @subsection Options
529
530 @table @option
531
532 @item framerate
533 Set the frame rate. Default is 25.
534
535 @item standard
536
537 Available values are:
538 @table @samp
539 @item pal
540
541 @item ntsc
542
543 @end table
544
545 Default value is @code{ntsc}.
546
547 @end table
548
549 @section fbdev
550
551 Linux framebuffer input device.
552
553 The Linux framebuffer is a graphic hardware-independent abstraction
554 layer to show graphics on a computer monitor, typically on the
555 console. It is accessed through a file device node, usually
556 @file{/dev/fb0}.
557
558 For more detailed information read the file
559 Documentation/fb/framebuffer.txt included in the Linux source tree.
560
561 See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1).
562
563 To record from the framebuffer device @file{/dev/fb0} with
564 @command{ffmpeg}:
565 @example
566 ffmpeg -f fbdev -framerate 10 -i /dev/fb0 out.avi
567 @end example
568
569 You can take a single screenshot image with the command:
570 @example
571 ffmpeg -f fbdev -framerate 1 -i /dev/fb0 -frames:v 1 screenshot.jpeg
572 @end example
573
574 @subsection Options
575
576 @table @option
577
578 @item framerate
579 Set the frame rate. Default is 25.
580
581 @end table
582
583 @section gdigrab
584
585 Win32 GDI-based screen capture device.
586
587 This device allows you to capture a region of the display on Windows.
588
589 There are two options for the input filename:
590 @example
591 desktop
592 @end example
593 or
594 @example
595 title=@var{window_title}
596 @end example
597
598 The first option will capture the entire desktop, or a fixed region of the
599 desktop. The second option will instead capture the contents of a single
600 window, regardless of its position on the screen.
601
602 For example, to grab the entire desktop using @command{ffmpeg}:
603 @example
604 ffmpeg -f gdigrab -framerate 6 -i desktop out.mpg
605 @end example
606
607 Grab a 640x480 region at position @code{10,20}:
608 @example
609 ffmpeg -f gdigrab -framerate 6 -offset_x 10 -offset_y 20 -video_size vga -i desktop out.mpg
610 @end example
611
612 Grab the contents of the window named "Calculator"
613 @example
614 ffmpeg -f gdigrab -framerate 6 -i title=Calculator out.mpg
615 @end example
616
617 @subsection Options
618
619 @table @option
620 @item draw_mouse
621 Specify whether to draw the mouse pointer. Use the value @code{0} to
622 not draw the pointer. Default value is @code{1}.
623
624 @item framerate
625 Set the grabbing frame rate. Default value is @code{ntsc},
626 corresponding to a frame rate of @code{30000/1001}.
627
628 @item show_region
629 Show grabbed region on screen.
630
631 If @var{show_region} is specified with @code{1}, then the grabbing
632 region will be indicated on screen. With this option, it is easy to
633 know what is being grabbed if only a portion of the screen is grabbed.
634
635 Note that @var{show_region} is incompatible with grabbing the contents
636 of a single window.
637
638 For example:
639 @example
640 ffmpeg -f gdigrab -show_region 1 -framerate 6 -video_size cif -offset_x 10 -offset_y 20 -i desktop out.mpg
641 @end example
642
643 @item video_size
644 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.
645
646 @item offset_x
647 When capturing a region with @var{video_size}, set the distance from the left edge of the screen or desktop.
648
649 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.
650
651 @item offset_y
652 When capturing a region with @var{video_size}, set the distance from the top edge of the screen or desktop.
653
654 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.
655
656 @end table
657
658 @section iec61883
659
660 FireWire DV/HDV input device using libiec61883.
661
662 To enable this input device, you need libiec61883, libraw1394 and
663 libavc1394 installed on your system. Use the configure option
664 @code{--enable-libiec61883} to compile with the device enabled.
665
666 The iec61883 capture device supports capturing from a video device
667 connected via IEEE1394 (FireWire), using libiec61883 and the new Linux
668 FireWire stack (juju). This is the default DV/HDV input method in Linux
669 Kernel 2.6.37 and later, since the old FireWire stack was removed.
670
671 Specify the FireWire port to be used as input file, or "auto"
672 to choose the first port connected.
673
674 @subsection Options
675
676 @table @option
677
678 @item dvtype
679 Override autodetection of DV/HDV. This should only be used if auto
680 detection does not work, or if usage of a different device type
681 should be prohibited. Treating a DV device as HDV (or vice versa) will
682 not work and result in undefined behavior.
683 The values @option{auto}, @option{dv} and @option{hdv} are supported.
684
685 @item dvbuffer
686 Set maximum size of buffer for incoming data, in frames. For DV, this
687 is an exact value. For HDV, it is not frame exact, since HDV does
688 not have a fixed frame size.
689
690 @item dvguid
691 Select the capture device by specifying its GUID. Capturing will only
692 be performed from the specified device and fails if no device with the
693 given GUID is found. This is useful to select the input if multiple
694 devices are connected at the same time.
695 Look at /sys/bus/firewire/devices to find out the GUIDs.
696
697 @end table
698
699 @subsection Examples
700
701 @itemize
702
703 @item
704 Grab and show the input of a FireWire DV/HDV device.
705 @example
706 ffplay -f iec61883 -i auto
707 @end example
708
709 @item
710 Grab and record the input of a FireWire DV/HDV device,
711 using a packet buffer of 100000 packets if the source is HDV.
712 @example
713 ffmpeg -f iec61883 -i auto -hdvbuffer 100000 out.mpg
714 @end example
715
716 @end itemize
717
718 @section jack
719
720 JACK input device.
721
722 To enable this input device during configuration you need libjack
723 installed on your system.
724
725 A JACK input device creates one or more JACK writable clients, one for
726 each audio channel, with name @var{client_name}:input_@var{N}, where
727 @var{client_name} is the name provided by the application, and @var{N}
728 is a number which identifies the channel.
729 Each writable client will send the acquired data to the FFmpeg input
730 device.
731
732 Once you have created one or more JACK readable clients, you need to
733 connect them to one or more JACK writable clients.
734
735 To connect or disconnect JACK clients you can use the @command{jack_connect}
736 and @command{jack_disconnect} programs, or do it through a graphical interface,
737 for example with @command{qjackctl}.
738
739 To list the JACK clients and their properties you can invoke the command
740 @command{jack_lsp}.
741
742 Follows an example which shows how to capture a JACK readable client
743 with @command{ffmpeg}.
744 @example
745 # Create a JACK writable client with name "ffmpeg".
746 $ ffmpeg -f jack -i ffmpeg -y out.wav
747
748 # Start the sample jack_metro readable client.
749 $ jack_metro -b 120 -d 0.2 -f 4000
750
751 # List the current JACK clients.
752 $ jack_lsp -c
753 system:capture_1
754 system:capture_2
755 system:playback_1
756 system:playback_2
757 ffmpeg:input_1
758 metro:120_bpm
759
760 # Connect metro to the ffmpeg writable client.
761 $ jack_connect metro:120_bpm ffmpeg:input_1
762 @end example
763
764 For more information read:
765 @url{http://jackaudio.org/}
766
767 @subsection Options
768
769 @table @option
770
771 @item channels
772 Set the number of channels. Default is 2.
773
774 @end table
775
776 @section lavfi
777
778 Libavfilter input virtual device.
779
780 This input device reads data from the open output pads of a libavfilter
781 filtergraph.
782
783 For each filtergraph open output, the input device will create a
784 corresponding stream which is mapped to the generated output. Currently
785 only video data is supported. The filtergraph is specified through the
786 option @option{graph}.
787
788 @subsection Options
789
790 @table @option
791
792 @item graph
793 Specify the filtergraph to use as input. Each video open output must be
794 labelled by a unique string of the form "out@var{N}", where @var{N} is a
795 number starting from 0 corresponding to the mapped input stream
796 generated by the device.
797 The first unlabelled output is automatically assigned to the "out0"
798 label, but all the others need to be specified explicitly.
799
800 The suffix "+subcc" can be appended to the output label to create an extra
801 stream with the closed captions packets attached to that output
802 (experimental; only for EIA-608 / CEA-708 for now).
803 The subcc streams are created after all the normal streams, in the order of
804 the corresponding stream.
805 For example, if there is "out19+subcc", "out7+subcc" and up to "out42", the
806 stream #43 is subcc for stream #7 and stream #44 is subcc for stream #19.
807
808 If not specified defaults to the filename specified for the input
809 device.
810
811 @item graph_file
812 Set the filename of the filtergraph to be read and sent to the other
813 filters. Syntax of the filtergraph is the same as the one specified by
814 the option @var{graph}.
815
816 @item dumpgraph
817 Dump graph to stderr.
818
819 @end table
820
821 @subsection Examples
822
823 @itemize
824 @item
825 Create a color video stream and play it back with @command{ffplay}:
826 @example
827 ffplay -f lavfi -graph "color=c=pink [out0]" dummy
828 @end example
829
830 @item
831 As the previous example, but use filename for specifying the graph
832 description, and omit the "out0" label:
833 @example
834 ffplay -f lavfi color=c=pink
835 @end example
836
837 @item
838 Create three different video test filtered sources and play them:
839 @example
840 ffplay -f lavfi -graph "testsrc [out0]; testsrc,hflip [out1]; testsrc,negate [out2]" test3
841 @end example
842
843 @item
844 Read an audio stream from a file using the amovie source and play it
845 back with @command{ffplay}:
846 @example
847 ffplay -f lavfi "amovie=test.wav"
848 @end example
849
850 @item
851 Read an audio stream and a video stream and play it back with
852 @command{ffplay}:
853 @example
854 ffplay -f lavfi "movie=test.avi[out0];amovie=test.wav[out1]"
855 @end example
856
857 @item
858 Dump decoded frames to images and closed captions to a file (experimental):
859 @example
860 ffmpeg -f lavfi -i "movie=test.ts[out0+subcc]" -map v frame%08d.png -map s -c copy -f rawvideo subcc.bin
861 @end example
862
863 @end itemize
864
865 @section libcdio
866
867 Audio-CD input device based on libcdio.
868
869 To enable this input device during configuration you need libcdio
870 installed on your system. It requires the configure option
871 @code{--enable-libcdio}.
872
873 This device allows playing and grabbing from an Audio-CD.
874
875 For example to copy with @command{ffmpeg} the entire Audio-CD in @file{/dev/sr0},
876 you may run the command:
877 @example
878 ffmpeg -f libcdio -i /dev/sr0 cd.wav
879 @end example
880
881 @subsection Options
882 @table @option
883 @item speed
884 Set drive reading speed. Default value is 0.
885
886 The speed is specified CD-ROM speed units. The speed is set through
887 the libcdio @code{cdio_cddap_speed_set} function. On many CD-ROM
888 drives, specifying a value too large will result in using the fastest
889 speed.
890
891 @item paranoia_mode
892 Set paranoia recovery mode flags. It accepts one of the following values:
893
894 @table @samp
895 @item disable
896 @item verify
897 @item overlap
898 @item neverskip
899 @item full
900 @end table
901
902 Default value is @samp{disable}.
903
904 For more information about the available recovery modes, consult the
905 paranoia project documentation.
906 @end table
907
908 @section libdc1394
909
910 IIDC1394 input device, based on libdc1394 and libraw1394.
911
912 Requires the configure option @code{--enable-libdc1394}.
913
914 @section openal
915
916 The OpenAL input device provides audio capture on all systems with a
917 working OpenAL 1.1 implementation.
918
919 To enable this input device during configuration, you need OpenAL
920 headers and libraries installed on your system, and need to configure
921 FFmpeg with @code{--enable-openal}.
922
923 OpenAL headers and libraries should be provided as part of your OpenAL
924 implementation, or as an additional download (an SDK). Depending on your
925 installation you may need to specify additional flags via the
926 @code{--extra-cflags} and @code{--extra-ldflags} for allowing the build
927 system to locate the OpenAL headers and libraries.
928
929 An incomplete list of OpenAL implementations follows:
930
931 @table @strong
932 @item Creative
933 The official Windows implementation, providing hardware acceleration
934 with supported devices and software fallback.
935 See @url{http://openal.org/}.
936 @item OpenAL Soft
937 Portable, open source (LGPL) software implementation. Includes
938 backends for the most common sound APIs on the Windows, Linux,
939 Solaris, and BSD operating systems.
940 See @url{http://kcat.strangesoft.net/openal.html}.
941 @item Apple
942 OpenAL is part of Core Audio, the official Mac OS X Audio interface.
943 See @url{http://developer.apple.com/technologies/mac/audio-and-video.html}
944 @end table
945
946 This device allows one to capture from an audio input device handled
947 through OpenAL.
948
949 You need to specify the name of the device to capture in the provided
950 filename. If the empty string is provided, the device will
951 automatically select the default device. You can get the list of the
952 supported devices by using the option @var{list_devices}.
953
954 @subsection Options
955
956 @table @option
957
958 @item channels
959 Set the number of channels in the captured audio. Only the values
960 @option{1} (monaural) and @option{2} (stereo) are currently supported.
961 Defaults to @option{2}.
962
963 @item sample_size
964 Set the sample size (in bits) of the captured audio. Only the values
965 @option{8} and @option{16} are currently supported. Defaults to
966 @option{16}.
967
968 @item sample_rate
969 Set the sample rate (in Hz) of the captured audio.
970 Defaults to @option{44.1k}.
971
972 @item list_devices
973 If set to @option{true}, print a list of devices and exit.
974 Defaults to @option{false}.
975
976 @end table
977
978 @subsection Examples
979
980 Print the list of OpenAL supported devices and exit:
981 @example
982 $ ffmpeg -list_devices true -f openal -i dummy out.ogg
983 @end example
984
985 Capture from the OpenAL device @file{DR-BT101 via PulseAudio}:
986 @example
987 $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out.ogg
988 @end example
989
990 Capture from the default device (note the empty string '' as filename):
991 @example
992 $ ffmpeg -f openal -i '' out.ogg
993 @end example
994
995 Capture from two devices simultaneously, writing to two different files,
996 within the same @command{ffmpeg} command:
997 @example
998 $ ffmpeg -f openal -i 'DR-BT101 via PulseAudio' out1.ogg -f openal -i 'ALSA Default' out2.ogg
999 @end example
1000 Note: not all OpenAL implementations support multiple simultaneous capture -
1001 try the latest OpenAL Soft if the above does not work.
1002
1003 @section oss
1004
1005 Open Sound System input device.
1006
1007 The filename to provide to the input device is the device node
1008 representing the OSS input device, and is usually set to
1009 @file{/dev/dsp}.
1010
1011 For example to grab from @file{/dev/dsp} using @command{ffmpeg} use the
1012 command:
1013 @example
1014 ffmpeg -f oss -i /dev/dsp /tmp/oss.wav
1015 @end example
1016
1017 For more information about OSS see:
1018 @url{http://manuals.opensound.com/usersguide/dsp.html}
1019
1020 @subsection Options
1021
1022 @table @option
1023
1024 @item sample_rate
1025 Set the sample rate in Hz. Default is 48000.
1026
1027 @item channels
1028 Set the number of channels. Default is 2.
1029
1030 @end table
1031
1032
1033 @section pulse
1034
1035 PulseAudio input device.
1036
1037 To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}.
1038
1039 The filename to provide to the input device is a source device or the
1040 string "default"
1041
1042 To list the PulseAudio source devices and their properties you can invoke
1043 the command @command{pactl list sources}.
1044
1045 More information about PulseAudio can be found on @url{http://www.pulseaudio.org}.
1046
1047 @subsection Options
1048 @table @option
1049 @item server
1050 Connect to a specific PulseAudio server, specified by an IP address.
1051 Default server is used when not provided.
1052
1053 @item name
1054 Specify the application name PulseAudio will use when showing active clients,
1055 by default it is the @code{LIBAVFORMAT_IDENT} string.
1056
1057 @item stream_name
1058 Specify the stream name PulseAudio will use when showing active streams,
1059 by default it is "record".
1060
1061 @item sample_rate
1062 Specify the samplerate in Hz, by default 48kHz is used.
1063
1064 @item channels
1065 Specify the channels in use, by default 2 (stereo) is set.
1066
1067 @item frame_size
1068 Specify the number of bytes per frame, by default it is set to 1024.
1069
1070 @item fragment_size
1071 Specify the minimal buffering fragment in PulseAudio, it will affect the
1072 audio latency. By default it is unset.
1073
1074 @item wallclock
1075 Set the initial PTS using the current time. Default is 1.
1076
1077 @end table
1078
1079 @subsection Examples
1080 Record a stream from default device:
1081 @example
1082 ffmpeg -f pulse -i default /tmp/pulse.wav
1083 @end example
1084
1085 @section qtkit
1086
1087 QTKit input device.
1088
1089 The filename passed as input is parsed to contain either a device name or index.
1090 The device index can also be given by using -video_device_index.
1091 A given device index will override any given device name.
1092 If the desired device consists of numbers only, use -video_device_index to identify it.
1093 The default device will be chosen if an empty string  or the device name "default" is given.
1094 The available devices can be enumerated by using -list_devices.
1095
1096 @example
1097 ffmpeg -f qtkit -i "0" out.mpg
1098 @end example
1099
1100 @example
1101 ffmpeg -f qtkit -video_device_index 0 -i "" out.mpg
1102 @end example
1103
1104 @example
1105 ffmpeg -f qtkit -i "default" out.mpg
1106 @end example
1107
1108 @example
1109 ffmpeg -f qtkit -list_devices true -i ""
1110 @end example
1111
1112 @subsection Options
1113
1114 @table @option
1115
1116 @item frame_rate
1117 Set frame rate. Default is 30.
1118
1119 @item list_devices
1120 If set to @code{true}, print a list of devices and exit. Default is
1121 @code{false}.
1122
1123 @item video_device_index
1124 Select the video device by index for devices with the same name (starts at 0).
1125
1126 @end table
1127
1128 @section sndio
1129
1130 sndio input device.
1131
1132 To enable this input device during configuration you need libsndio
1133 installed on your system.
1134
1135 The filename to provide to the input device is the device node
1136 representing the sndio input device, and is usually set to
1137 @file{/dev/audio0}.
1138
1139 For example to grab from @file{/dev/audio0} using @command{ffmpeg} use the
1140 command:
1141 @example
1142 ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
1143 @end example
1144
1145 @subsection Options
1146
1147 @table @option
1148
1149 @item sample_rate
1150 Set the sample rate in Hz. Default is 48000.
1151
1152 @item channels
1153 Set the number of channels. Default is 2.
1154
1155 @end table
1156
1157 @section video4linux2, v4l2
1158
1159 Video4Linux2 input video device.
1160
1161 "v4l2" can be used as alias for "video4linux2".
1162
1163 If FFmpeg is built with v4l-utils support (by using the
1164 @code{--enable-libv4l2} configure option), it is possible to use it with the
1165 @code{-use_libv4l2} input device option.
1166
1167 The name of the device to grab is a file device node, usually Linux
1168 systems tend to automatically create such nodes when the device
1169 (e.g. an USB webcam) is plugged into the system, and has a name of the
1170 kind @file{/dev/video@var{N}}, where @var{N} is a number associated to
1171 the device.
1172
1173 Video4Linux2 devices usually support a limited set of
1174 @var{width}x@var{height} sizes and frame rates. You can check which are
1175 supported using @command{-list_formats all} for Video4Linux2 devices.
1176 Some devices, like TV cards, support one or more standards. It is possible
1177 to list all the supported standards using @command{-list_standards all}.
1178
1179 The time base for the timestamps is 1 microsecond. Depending on the kernel
1180 version and configuration, the timestamps may be derived from the real time
1181 clock (origin at the Unix Epoch) or the monotonic clock (origin usually at
1182 boot time, unaffected by NTP or manual changes to the clock). The
1183 @option{-timestamps abs} or @option{-ts abs} option can be used to force
1184 conversion into the real time clock.
1185
1186 Some usage examples of the video4linux2 device with @command{ffmpeg}
1187 and @command{ffplay}:
1188 @itemize
1189 @item
1190 List supported formats for a video4linux2 device:
1191 @example
1192 ffplay -f video4linux2 -list_formats all /dev/video0
1193 @end example
1194
1195 @item
1196 Grab and show the input of a video4linux2 device:
1197 @example
1198 ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
1199 @end example
1200
1201 @item
1202 Grab and record the input of a video4linux2 device, leave the
1203 frame rate and size as previously set:
1204 @example
1205 ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
1206 @end example
1207 @end itemize
1208
1209 For more information about Video4Linux, check @url{http://linuxtv.org/}.
1210
1211 @subsection Options
1212
1213 @table @option
1214 @item standard
1215 Set the standard. Must be the name of a supported standard. To get a
1216 list of the supported standards, use the @option{list_standards}
1217 option.
1218
1219 @item channel
1220 Set the input channel number. Default to -1, which means using the
1221 previously selected channel.
1222
1223 @item video_size
1224 Set the video frame size. The argument must be a string in the form
1225 @var{WIDTH}x@var{HEIGHT} or a valid size abbreviation.
1226
1227 @item pixel_format
1228 Select the pixel format (only valid for raw video input).
1229
1230 @item input_format
1231 Set the preferred pixel format (for raw video) or a codec name.
1232 This option allows one to select the input format, when several are
1233 available.
1234
1235 @item framerate
1236 Set the preferred video frame rate.
1237
1238 @item list_formats
1239 List available formats (supported pixel formats, codecs, and frame
1240 sizes) and exit.
1241
1242 Available values are:
1243 @table @samp
1244 @item all
1245 Show all available (compressed and non-compressed) formats.
1246
1247 @item raw
1248 Show only raw video (non-compressed) formats.
1249
1250 @item compressed
1251 Show only compressed formats.
1252 @end table
1253
1254 @item list_standards
1255 List supported standards and exit.
1256
1257 Available values are:
1258 @table @samp
1259 @item all
1260 Show all supported standards.
1261 @end table
1262
1263 @item timestamps, ts
1264 Set type of timestamps for grabbed frames.
1265
1266 Available values are:
1267 @table @samp
1268 @item default
1269 Use timestamps from the kernel.
1270
1271 @item abs
1272 Use absolute timestamps (wall clock).
1273
1274 @item mono2abs
1275 Force conversion from monotonic to absolute timestamps.
1276 @end table
1277
1278 Default value is @code{default}.
1279
1280 @item use_libv4l2
1281 Use libv4l2 (v4l-utils) conversion functions. Default is 0.
1282
1283 @end table
1284
1285 @section vfwcap
1286
1287 VfW (Video for Windows) capture input device.
1288
1289 The filename passed as input is the capture driver number, ranging from
1290 0 to 9. You may use "list" as filename to print a list of drivers. Any
1291 other filename will be interpreted as device number 0.
1292
1293 @subsection Options
1294
1295 @table @option
1296
1297 @item video_size
1298 Set the video frame size.
1299
1300 @item framerate
1301 Set the grabbing frame rate. Default value is @code{ntsc},
1302 corresponding to a frame rate of @code{30000/1001}.
1303
1304 @end table
1305
1306 @section x11grab
1307
1308 X11 video input device.
1309
1310 To enable this input device during configuration you need libxcb
1311 installed on your system. It will be automatically detected during
1312 configuration.
1313
1314 This device allows one to capture a region of an X11 display.
1315
1316 The filename passed as input has the syntax:
1317 @example
1318 [@var{hostname}]:@var{display_number}.@var{screen_number}[+@var{x_offset},@var{y_offset}]
1319 @end example
1320
1321 @var{hostname}:@var{display_number}.@var{screen_number} specifies the
1322 X11 display name of the screen to grab from. @var{hostname} can be
1323 omitted, and defaults to "localhost". The environment variable
1324 @env{DISPLAY} contains the default display name.
1325
1326 @var{x_offset} and @var{y_offset} specify the offsets of the grabbed
1327 area with respect to the top-left border of the X11 screen. They
1328 default to 0.
1329
1330 Check the X11 documentation (e.g. @command{man X}) for more detailed
1331 information.
1332
1333 Use the @command{xdpyinfo} program for getting basic information about
1334 the properties of your X11 display (e.g. grep for "name" or
1335 "dimensions").
1336
1337 For example to grab from @file{:0.0} using @command{ffmpeg}:
1338 @example
1339 ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0 out.mpg
1340 @end example
1341
1342 Grab at position @code{10,20}:
1343 @example
1344 ffmpeg -f x11grab -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
1345 @end example
1346
1347 @subsection Options
1348
1349 @table @option
1350 @item draw_mouse
1351 Specify whether to draw the mouse pointer. A value of @code{0} specifies
1352 not to draw the pointer. Default value is @code{1}.
1353
1354 @item follow_mouse
1355 Make the grabbed area follow the mouse. The argument can be
1356 @code{centered} or a number of pixels @var{PIXELS}.
1357
1358 When it is specified with "centered", the grabbing region follows the mouse
1359 pointer and keeps the pointer at the center of region; otherwise, the region
1360 follows only when the mouse pointer reaches within @var{PIXELS} (greater than
1361 zero) to the edge of region.
1362
1363 For example:
1364 @example
1365 ffmpeg -f x11grab -follow_mouse centered -framerate 25 -video_size cif -i :0.0 out.mpg
1366 @end example
1367
1368 To follow only when the mouse pointer reaches within 100 pixels to edge:
1369 @example
1370 ffmpeg -f x11grab -follow_mouse 100 -framerate 25 -video_size cif -i :0.0 out.mpg
1371 @end example
1372
1373 @item framerate
1374 Set the grabbing frame rate. Default value is @code{ntsc},
1375 corresponding to a frame rate of @code{30000/1001}.
1376
1377 @item show_region
1378 Show grabbed region on screen.
1379
1380 If @var{show_region} is specified with @code{1}, then the grabbing
1381 region will be indicated on screen. With this option, it is easy to
1382 know what is being grabbed if only a portion of the screen is grabbed.
1383
1384 @item region_border
1385 Set the region border thickness if @option{-show_region 1} is used.
1386 Range is 1 to 128 and default is 3 (XCB-based x11grab only).
1387
1388 For example:
1389 @example
1390 ffmpeg -f x11grab -show_region 1 -framerate 25 -video_size cif -i :0.0+10,20 out.mpg
1391 @end example
1392
1393 With @var{follow_mouse}:
1394 @example
1395 ffmpeg -f x11grab -follow_mouse centered -show_region 1 -framerate 25 -video_size cif -i :0.0 out.mpg
1396 @end example
1397
1398 @item video_size
1399 Set the video frame size. Default value is @code{vga}.
1400
1401 @item grab_x
1402 @item grab_y
1403 Set the grabbing region coordinates. They are expressed as offset from
1404 the top left corner of the X11 window and correspond to the
1405 @var{x_offset} and @var{y_offset} parameters in the device name. The
1406 default value for both options is 0.
1407 @end table
1408
1409 @c man end INPUT DEVICES