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