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