pulse: introduce pulseaudio input
[libav.git] / doc / indevs.texi
CommitLineData
c32ccf7c 1@chapter Input Devices
4419c8bf
SS
2@c man begin INPUT DEVICES
3
f8a45fa1 4Input devices are configured elements in Libav which allow to access
4419c8bf
SS
5the data coming from a multimedia device attached to your system.
6
f8a45fa1 7When you configure your Libav build, all the supported input devices
2f6bc4e7
SS
8are enabled by default. You can list all available ones using the
9configure option "--list-indevs".
4419c8bf
SS
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 "-formats" of the ff* tools will display the list of
17supported input devices (amongst the demuxers).
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
2f6bc4e7 28This device allows capturing from an ALSA device. The name of the
4419c8bf
SS
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
2f6bc4e7 45For example to capture with @file{ffmpeg} from an ALSA device with
4419c8bf
SS
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
4419c8bf
SS
54@section bktr
55
56BSD video input device.
57
58@section dv1394
59
60Linux DV 1394 input device.
61
c6f95144
SS
62@section fbdev
63
64Linux framebuffer input device.
65
66The Linux framebuffer is a graphic hardware-independent abstraction
67layer to show graphics on a computer monitor, typically on the
68console. It is accessed through a file device node, usually
69@file{/dev/fb0}.
70
71For more detailed information read the file
72Documentation/fb/framebuffer.txt included in the Linux source tree.
73
74To record from the framebuffer device @file{/dev/fb0} with
75@file{ffmpeg}:
76@example
77ffmpeg -f fbdev -r 10 -i /dev/fb0 out.avi
78@end example
79
80You can take a single screenshot image with the command:
81@example
82ffmpeg -f fbdev -vframes 1 -r 1 -i /dev/fb0 screenshot.jpeg
83@end example
84
85See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1).
86
4419c8bf
SS
87@section jack
88
2f6bc4e7 89JACK input device.
4419c8bf
SS
90
91To enable this input device during configuration you need libjack
92installed on your system.
93
2f6bc4e7 94A JACK input device creates one or more JACK writable clients, one for
4419c8bf
SS
95each audio channel, with name @var{client_name}:input_@var{N}, where
96@var{client_name} is the name provided by the application, and @var{N}
97is a number which identifies the channel.
f8a45fa1 98Each writable client will send the acquired data to the Libav input
4419c8bf
SS
99device.
100
2f6bc4e7
SS
101Once you have created one or more JACK readable clients, you need to
102connect them to one or more JACK writable clients.
4419c8bf 103
2f6bc4e7 104To connect or disconnect JACK clients you can use the
4419c8bf
SS
105@file{jack_connect} and @file{jack_disconnect} programs, or do it
106through a graphical interface, for example with @file{qjackctl}.
107
2f6bc4e7 108To list the JACK clients and their properties you can invoke the command
4419c8bf
SS
109@file{jack_lsp}.
110
2f6bc4e7 111Follows an example which shows how to capture a JACK readable client
4419c8bf
SS
112with @file{ffmpeg}.
113@example
2f6bc4e7 114# Create a JACK writable client with name "ffmpeg".
4419c8bf
SS
115$ ffmpeg -f jack -i ffmpeg -y out.wav
116
2f6bc4e7 117# Start the sample jack_metro readable client.
4419c8bf
SS
118$ jack_metro -b 120 -d 0.2 -f 4000
119
2f6bc4e7 120# List the current JACK clients.
4419c8bf
SS
121$ jack_lsp -c
122system:capture_1
123system:capture_2
124system:playback_1
125system:playback_2
126ffmpeg:input_1
127metro:120_bpm
128
2f6bc4e7 129# Connect metro to the ffmpeg writable client.
4419c8bf
SS
130$ jack_connect metro:120_bpm ffmpeg:input_1
131@end example
132
133For more information read:
134@url{http://jackaudio.org/}
135
136@section libdc1394
137
138IIDC1394 input device, based on libdc1394 and libraw1394.
139
140@section oss
141
142Open Sound System input device.
143
144The filename to provide to the input device is the device node
145representing the OSS input device, and is usually set to
2f6bc4e7 146@file{/dev/dsp}.
4419c8bf 147
2f6bc4e7 148For example to grab from @file{/dev/dsp} using @file{ffmpeg} use the
4419c8bf
SS
149command:
150@example
151ffmpeg -f oss -i /dev/dsp /tmp/oss.wav
152@end example
153
154For more information about OSS see:
155@url{http://manuals.opensound.com/usersguide/dsp.html}
156
15d59d2c
B
157@section sndio
158
159sndio input device.
160
161To enable this input device during configuration you need libsndio
162installed on your system.
163
164The filename to provide to the input device is the device node
165representing the sndio input device, and is usually set to
166@file{/dev/audio0}.
167
168For example to grab from @file{/dev/audio0} using @file{ffmpeg} use the
169command:
170@example
171ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
172@end example
173
4419c8bf
SS
174@section video4linux and video4linux2
175
176Video4Linux and Video4Linux2 input video devices.
177
178The name of the device to grab is a file device node, usually Linux
179systems tend to automatically create such nodes when the device
2f6bc4e7 180(e.g. an USB webcam) is plugged into the system, and has a name of the
4419c8bf
SS
181kind @file{/dev/video@var{N}}, where @var{N} is a number associated to
182the device.
183
184Video4Linux and Video4Linux2 devices only support a limited set of
185@var{width}x@var{height} sizes and framerates. You can check which are
2f6bc4e7
SS
186supported for example with the command @file{dov4l} for Video4Linux
187devices and the command @file{v4l-info} for Video4Linux2 devices.
4419c8bf
SS
188
189If the size for the device is set to 0x0, the input device will
190try to autodetect the size to use.
8621a37d
SS
191Only for the video4linux2 device, if the frame rate is set to 0/0 the
192input device will use the frame rate value already set in the driver.
4419c8bf
SS
193
194Video4Linux support is deprecated since Linux 2.6.30, and will be
195dropped in later versions.
196
197Follow some usage examples of the video4linux devices with the ff*
198tools.
199@example
8621a37d
SS
200# Grab and show the input of a video4linux device, frame rate is set
201# to the default of 25/1.
266463da 202avplay -s 320x240 -f video4linux /dev/video0
4419c8bf 203
2f6bc4e7 204# Grab and show the input of a video4linux2 device, autoadjust size.
266463da 205avplay -f video4linux2 /dev/video0
4419c8bf 206
8621a37d
SS
207# Grab and record the input of a video4linux2 device, autoadjust size,
208# frame rate value defaults to 0/0 so it is read from the video4linux2
209# driver.
4419c8bf
SS
210ffmpeg -f video4linux2 -i /dev/video0 out.mpeg
211@end example
212
213@section vfwcap
214
52c55330 215VfW (Video for Windows) capture input device.
4419c8bf 216
fbd4a07d
RP
217The filename passed as input is the capture driver number, ranging from
2180 to 9. You may use "list" as filename to print a list of drivers. Any
219other filename will be interpreted as device number 0.
220
4419c8bf
SS
221@section x11grab
222
223X11 video input device.
224
225This device allows to capture a region of an X11 display.
226
2f6bc4e7 227The filename passed as input has the syntax:
4419c8bf
SS
228@example
229[@var{hostname}]:@var{display_number}.@var{screen_number}[+@var{x_offset},@var{y_offset}]
230@end example
231
232@var{hostname}:@var{display_number}.@var{screen_number} specifies the
2f6bc4e7
SS
233X11 display name of the screen to grab from. @var{hostname} can be
234ommitted, and defaults to "localhost". The environment variable
4419c8bf
SS
235@env{DISPLAY} contains the default display name.
236
237@var{x_offset} and @var{y_offset} specify the offsets of the grabbed
2f6bc4e7 238area with respect to the top-left border of the X11 screen. They
4419c8bf
SS
239default to 0.
240
241Check the X11 documentation (e.g. man X) for more detailed information.
242
243Use the @file{dpyinfo} program for getting basic information about the
2f6bc4e7 244properties of your X11 display (e.g. grep for "name" or "dimensions").
4419c8bf
SS
245
246For example to grab from @file{:0.0} using @file{ffmpeg}:
247@example
248ffmpeg -f x11grab -r 25 -s cif -i :0.0 out.mpg
249
2f6bc4e7 250# Grab at position 10,20.
085791a9
YJL
251ffmpeg -f x11grab -r 25 -s cif -i :0.0+10,20 out.mpg
252@end example
253
254@subsection @var{follow_mouse} AVOption
255
256The syntax is:
257@example
258-follow_mouse centered|@var{PIXELS}
259@end example
260
261When it is specified with "centered", the grabbing region follows the mouse
262pointer and keeps the pointer at the center of region; otherwise, the region
263follows only when the mouse pointer reaches within @var{PIXELS} (greater than
264zero) to the edge of region.
265
266For example:
267@example
268ffmpeg -f x11grab -follow_mouse centered -r 25 -s cif -i :0.0 out.mpg
269
270# Follows only when the mouse pointer reaches within 100 pixels to edge
271ffmpeg -f x11grab -follow_mouse 100 -r 25 -s cif -i :0.0 out.mpg
4419c8bf
SS
272@end example
273
1442d295
YJL
274@subsection @var{show_region} AVOption
275
276The syntax is:
277@example
278-show_region 1
279@end example
280
281If @var{show_region} AVOption is specified with @var{1}, then the grabbing
282region will be indicated on screen. With this option, it's easy to know what is
283being grabbed if only a portion of the screen is grabbed.
284
285For example:
286@example
287ffmpeg -f x11grab -show_region 1 -r 25 -s cif -i :0.0+10,20 out.mpg
288
289# With follow_mouse
290ffmpeg -f x11grab -follow_mouse centered -show_region 1 -r 25 -s cif -i :0.0 out.mpg
291@end example
292
4419c8bf 293@c man end INPUT DEVICES