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