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