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