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