X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Findevs.texi;h=868329799f0eff7a6c2dc13801ef1eab1fce666c;hb=6ed9fc44badb256bdf235e700702bee46a9f6527;hp=cf3d68c14e47862eba27e68599f14bda75a22f2d;hpb=4419c8bf25a724776680de4bdd0ce97c69550c1e;p=ffmpeg diff --git a/doc/indevs.texi b/doc/indevs.texi index cf3d68c14e4..868329799f0 100644 --- a/doc/indevs.texi +++ b/doc/indevs.texi @@ -1,12 +1,12 @@ -@chapter Devices +@chapter Input Devices @c man begin INPUT DEVICES -Input devices are configured elements in FFmpeg which allow to access +Input devices are configured elements in Libav which allow to access the data coming from a multimedia device attached to your system. -When you configure your FFmpeg build, all the supported input devices -are enabled by default. You can list them using the configure option -"--list-indevs". +When you configure your Libav build, all the supported input devices +are enabled by default. You can list all available ones using the +configure option "--list-indevs". You can disable all the input devices using the configure option "--disable-indevs", and selectively enable an input device using the @@ -25,7 +25,7 @@ ALSA (Advanced Linux Sound Architecture) input device. To enable this input device during configuration you need libasound installed on your system. -This device allows to capture from an ALSA device. The name of the +This device allows capturing from an ALSA device. The name of the device to capture has to be an ALSA card identifier. An ALSA identifier has the syntax: @@ -42,19 +42,15 @@ specify card number or identifier, device number and subdevice number To see the list of cards currently recognized by your system check the files @file{/proc/asound/cards} and @file{/proc/asound/devices}. -For example to capture with @file{ffmpeg} from an alsa device with +For example to capture with @command{avconv} from an ALSA device with card id 0, you may run the command: @example -ffmpeg -f alsa -i hw:0 alsaout.wav +avconv -f alsa -i hw:0 alsaout.wav @end example For more information see: @url{http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html} -@section audio_beos - -BeOS audio input device. - @section bktr BSD video input device. @@ -63,50 +59,75 @@ BSD video input device. Linux DV 1394 input device. +@section fbdev + +Linux framebuffer input device. + +The Linux framebuffer is a graphic hardware-independent abstraction +layer to show graphics on a computer monitor, typically on the +console. It is accessed through a file device node, usually +@file{/dev/fb0}. + +For more detailed information read the file +Documentation/fb/framebuffer.txt included in the Linux source tree. + +To record from the framebuffer device @file{/dev/fb0} with +@command{avconv}: +@example +avconv -f fbdev -r 10 -i /dev/fb0 out.avi +@end example + +You can take a single screenshot image with the command: +@example +avconv -f fbdev -frames:v 1 -r 1 -i /dev/fb0 screenshot.jpeg +@end example + +See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1). + @section jack -Jack input device. +JACK input device. To enable this input device during configuration you need libjack installed on your system. -A jack input device creates one or more jack writable clients, one for +A JACK input device creates one or more JACK writable clients, one for each audio channel, with name @var{client_name}:input_@var{N}, where @var{client_name} is the name provided by the application, and @var{N} is a number which identifies the channel. -Each writable client will send the acquired data to the FFmpeg input +Each writable client will send the acquired data to the Libav input device. -Once you have created one or more jack readable clients, you need to -connect them to one or more jack writable clients. +Once you have created one or more JACK readable clients, you need to +connect them to one or more JACK writable clients. -To connect or disconnect jack clients you can use the +To connect or disconnect JACK clients you can use the @file{jack_connect} and @file{jack_disconnect} programs, or do it through a graphical interface, for example with @file{qjackctl}. -To list the jack clients and their properties you can invoke the command +To list the JACK clients and their properties you can invoke the command @file{jack_lsp}. -Follows an example which shows how to capture a jack readable client -with @file{ffmpeg}. +Follows an example which shows how to capture a JACK readable client +with @command{avconv}. @example -# create a jack writable client with name "ffmpeg" -$ ffmpeg -f jack -i ffmpeg -y out.wav +# Create a JACK writable client with name "libav". +$ avconv -f jack -i libav -y out.wav -# start the sample jack_metro readable client +# Start the sample jack_metro readable client. $ jack_metro -b 120 -d 0.2 -f 4000 -# list the current jack clients +# List the current JACK clients. $ jack_lsp -c system:capture_1 system:capture_2 system:playback_1 system:playback_2 -ffmpeg:input_1 +libav:input_1 metro:120_bpm -# connect metro to the ffmpeg writable client -$ jack_connect metro:120_bpm ffmpeg:input_1 +# Connect metro to the avconv writable client. +$ jack_connect metro:120_bpm libav:input_1 @end example For more information read: @@ -122,54 +143,149 @@ Open Sound System input device. The filename to provide to the input device is the device node representing the OSS input device, and is usually set to -@file{/dev/dsp/}. +@file{/dev/dsp}. -For example to grab from @file{/dev/dsp/} using @file{ffmpeg} use the +For example to grab from @file{/dev/dsp} using @command{avconv} use the command: @example -ffmpeg -f oss -i /dev/dsp /tmp/oss.wav +avconv -f oss -i /dev/dsp /tmp/oss.wav @end example For more information about OSS see: @url{http://manuals.opensound.com/usersguide/dsp.html} -@section video4linux and video4linux2 +@section pulse + +pulseaudio input device. + +To enable this input device during configuration you need libpulse-simple +installed in your system. + +The filename to provide to the input device is a source device or the +string "default" + +To list the pulse source devices and their properties you can invoke +the command @file{pactl list sources}. + +@example +avconv -f pulse -i default /tmp/pulse.wav +@end example + +@subsection @var{server} AVOption + +The syntax is: +@example +-server @var{server name} +@end example + +Connects to a specific server. + +@subsection @var{name} AVOption + +The syntax is: +@example +-name @var{application name} +@end example + +Specify the application name pulse will use when showing active clients, +by default it is "libav" + +@subsection @var{stream_name} AVOption + +The syntax is: +@example +-stream_name @var{stream name} +@end example + +Specify the stream name pulse will use when showing active streams, +by default it is "record" + +@subsection @var{sample_rate} AVOption + +The syntax is: +@example +-sample_rate @var{samplerate} +@end example + +Specify the samplerate in Hz, by default 48kHz is used. + +@subsection @var{channels} AVOption + +The syntax is: +@example +-channels @var{N} +@end example -Video4Linux and Video4Linux2 input video devices. +Specify the channels in use, by default 2 (stereo) is set. + +@subsection @var{frame_size} AVOption + +The syntax is: +@example +-frame_size @var{bytes} +@end example + +Specify the number of byte per frame, by default it is set to 1024. + +@subsection @var{fragment_size} AVOption + +The syntax is: +@example +-fragment_size @var{bytes} +@end example + +Specify the minimal buffering fragment in pulseaudio, it will affect the +audio latency. By default it is unset. + +@section sndio + +sndio input device. + +To enable this input device during configuration you need libsndio +installed on your system. + +The filename to provide to the input device is the device node +representing the sndio input device, and is usually set to +@file{/dev/audio0}. + +For example to grab from @file{/dev/audio0} using @command{avconv} use the +command: +@example +avconv -f sndio -i /dev/audio0 /tmp/oss.wav +@end example + +@section video4linux2 + +Video4Linux2 input video device. The name of the device to grab is a file device node, usually Linux systems tend to automatically create such nodes when the device -(e.g. an USB webcam) is plugged to the system, and has a name of the +(e.g. an USB webcam) is plugged into the system, and has a name of the kind @file{/dev/video@var{N}}, where @var{N} is a number associated to the device. -Video4Linux and Video4Linux2 devices only support a limited set of +Video4Linux2 devices usually support a limited set of @var{width}x@var{height} sizes and framerates. You can check which are -supported for example using the command @file{dov4l} for Video4Linux -devices, and the command @file{v4l-info} for Video4Linux2 devices. +supported using @command{-list_formats all} for Video4Linux2 devices. -If the size for the device is set to 0x0, the input device will -try to autodetect the size to use. +Some usage examples of the video4linux2 devices with avconv and avplay: -Video4Linux support is deprecated since Linux 2.6.30, and will be -dropped in later versions. - -Follow some usage examples of the video4linux devices with the ff* -tools. @example -# grab and show the input of a video4linux device -ffplay -s 320x240 -f video4linux /dev/video0 - -# grab and show the input of a video4linux2 device, autoadjust size -ffplay -f video4linux2 /dev/video0 +# Grab and show the input of a video4linux2 device. +avplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0 -# grab and record the input of a video4linux2 device, autoadjust size -ffmpeg -f video4linux2 -i /dev/video0 out.mpeg +# Grab and record the input of a video4linux2 device, leave the +framerate and size as previously set. +avconv -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg @end example @section vfwcap -VFW (Video For Window) catpure input device. +VfW (Video for Windows) capture input device. + +The filename passed as input is the capture driver number, ranging from +0 to 9. You may use "list" as filename to print a list of drivers. Any +other filename will be interpreted as device number 0. @section x11grab @@ -177,32 +293,70 @@ X11 video input device. This device allows to capture a region of an X11 display. -The filename passed in input has the syntax: +The filename passed as input has the syntax: @example [@var{hostname}]:@var{display_number}.@var{screen_number}[+@var{x_offset},@var{y_offset}] @end example @var{hostname}:@var{display_number}.@var{screen_number} specifies the -X11 display name of the screen to grab from. @var{hostname} can be not -specified, and defaults to "localhost". The environment variable +X11 display name of the screen to grab from. @var{hostname} can be +omitted, and defaults to "localhost". The environment variable @env{DISPLAY} contains the default display name. @var{x_offset} and @var{y_offset} specify the offsets of the grabbed -area with respect to the top/left border of the X11 screen image. They +area with respect to the top-left border of the X11 screen. They default to 0. Check the X11 documentation (e.g. man X) for more detailed information. Use the @file{dpyinfo} program for getting basic information about the -properties of your X11 display screen (e.g. grep for "name" or -"dimensions"). +properties of your X11 display (e.g. grep for "name" or "dimensions"). + +For example to grab from @file{:0.0} using @command{avconv}: +@example +avconv -f x11grab -r 25 -s cif -i :0.0 out.mpg + +# Grab at position 10,20. +avconv -f x11grab -r 25 -s cif -i :0.0+10,20 out.mpg +@end example + +@subsection @var{follow_mouse} AVOption + +The syntax is: +@example +-follow_mouse centered|@var{PIXELS} +@end example + +When it is specified with "centered", the grabbing region follows the mouse +pointer and keeps the pointer at the center of region; otherwise, the region +follows only when the mouse pointer reaches within @var{PIXELS} (greater than +zero) to the edge of region. + +For example: +@example +avconv -f x11grab -follow_mouse centered -r 25 -s cif -i :0.0 out.mpg + +# Follows only when the mouse pointer reaches within 100 pixels to edge +avconv -f x11grab -follow_mouse 100 -r 25 -s cif -i :0.0 out.mpg +@end example + +@subsection @var{show_region} AVOption + +The syntax is: +@example +-show_region 1 +@end example + +If @var{show_region} AVOption is specified with @var{1}, then the grabbing +region will be indicated on screen. With this option, it's easy to know what is +being grabbed if only a portion of the screen is grabbed. -For example to grab from @file{:0.0} using @file{ffmpeg}: +For example: @example -ffmpeg -f x11grab -r 25 -s cif -i :0.0 out.mpg +avconv -f x11grab -show_region 1 -r 25 -s cif -i :0.0+10,20 out.mpg -# grab at position 10,20 -ffmpeg -f x11grab -25 -s cif -i :0.0+10,20 out.mpg +# With follow_mouse +avconv -f x11grab -follow_mouse centered -show_region 1 -r 25 -s cif -i :0.0 out.mpg @end example @c man end INPUT DEVICES