xcbgrab: Provide better names for the y and x option
[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
202b5f6d 16The option "-formats" of the av* tools will display the list of
4419c8bf
SS
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
d5837d7f 45For example to capture with @command{avconv} from an ALSA device with
4419c8bf
SS
46card id 0, you may run the command:
47@example
d5837d7f 48avconv -f alsa -i hw:0 alsaout.wav
4419c8bf
SS
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
d5837d7f 75@command{avconv}:
c6f95144 76@example
d5837d7f 77avconv -f fbdev -r 10 -i /dev/fb0 out.avi
c6f95144
SS
78@end example
79
80You can take a single screenshot image with the command:
81@example
d5837d7f 82avconv -f fbdev -frames:v 1 -r 1 -i /dev/fb0 screenshot.jpeg
c6f95144
SS
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
d5837d7f 112with @command{avconv}.
4419c8bf 113@example
d5837d7f
LB
114# Create a JACK writable client with name "libav".
115$ avconv -f jack -i libav -y out.wav
4419c8bf 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
d5837d7f 126libav:input_1
4419c8bf
SS
127metro:120_bpm
128
d5837d7f
LB
129# Connect metro to the avconv writable client.
130$ jack_connect metro:120_bpm libav:input_1
4419c8bf
SS
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
d5837d7f 148For example to grab from @file{/dev/dsp} using @command{avconv} use the
4419c8bf
SS
149command:
150@example
d5837d7f 151avconv -f oss -i /dev/dsp /tmp/oss.wav
4419c8bf
SS
152@end example
153
154For more information about OSS see:
155@url{http://manuals.opensound.com/usersguide/dsp.html}
156
c4b97fbd
LB
157@section pulse
158
159pulseaudio input device.
160
161To enable this input device during configuration you need libpulse-simple
162installed in your system.
163
164The filename to provide to the input device is a source device or the
165string "default"
166
167To list the pulse source devices and their properties you can invoke
168the command @file{pactl list sources}.
169
170@example
171avconv -f pulse -i default /tmp/pulse.wav
172@end example
173
174@subsection @var{server} AVOption
175
176The syntax is:
177@example
178-server @var{server name}
179@end example
180
181Connects to a specific server.
182
183@subsection @var{name} AVOption
184
185The syntax is:
186@example
187-name @var{application name}
188@end example
189
190Specify the application name pulse will use when showing active clients,
191by default it is "libav"
192
193@subsection @var{stream_name} AVOption
194
195The syntax is:
196@example
197-stream_name @var{stream name}
198@end example
199
200Specify the stream name pulse will use when showing active streams,
201by default it is "record"
202
203@subsection @var{sample_rate} AVOption
204
205The syntax is:
206@example
207-sample_rate @var{samplerate}
208@end example
209
210Specify the samplerate in Hz, by default 48kHz is used.
211
212@subsection @var{channels} AVOption
213
214The syntax is:
215@example
216-channels @var{N}
217@end example
218
219Specify the channels in use, by default 2 (stereo) is set.
220
221@subsection @var{frame_size} AVOption
222
223The syntax is:
224@example
225-frame_size @var{bytes}
226@end example
227
228Specify the number of byte per frame, by default it is set to 1024.
229
230@subsection @var{fragment_size} AVOption
231
232The syntax is:
233@example
234-fragment_size @var{bytes}
235@end example
236
237Specify the minimal buffering fragment in pulseaudio, it will affect the
238audio latency. By default it is unset.
239
15d59d2c
B
240@section sndio
241
242sndio input device.
243
244To enable this input device during configuration you need libsndio
245installed on your system.
246
247The filename to provide to the input device is the device node
248representing the sndio input device, and is usually set to
249@file{/dev/audio0}.
250
d5837d7f 251For example to grab from @file{/dev/audio0} using @command{avconv} use the
15d59d2c
B
252command:
253@example
d5837d7f 254avconv -f sndio -i /dev/audio0 /tmp/oss.wav
15d59d2c
B
255@end example
256
af49e176 257@section video4linux2
4419c8bf 258
af49e176 259Video4Linux2 input video device.
4419c8bf
SS
260
261The name of the device to grab is a file device node, usually Linux
262systems tend to automatically create such nodes when the device
2f6bc4e7 263(e.g. an USB webcam) is plugged into the system, and has a name of the
4419c8bf
SS
264kind @file{/dev/video@var{N}}, where @var{N} is a number associated to
265the device.
266
af49e176 267Video4Linux2 devices usually support a limited set of
4419c8bf 268@var{width}x@var{height} sizes and framerates. You can check which are
af49e176 269supported using @command{-list_formats all} for Video4Linux2 devices.
4419c8bf 270
af49e176 271Some usage examples of the video4linux2 devices with avconv and avplay:
4419c8bf 272
4419c8bf 273@example
af49e176
LB
274# Grab and show the input of a video4linux2 device.
275avplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
4419c8bf 276
af49e176
LB
277# Grab and record the input of a video4linux2 device, leave the
278framerate and size as previously set.
279avconv -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
4419c8bf
SS
280@end example
281
282@section vfwcap
283
52c55330 284VfW (Video for Windows) capture input device.
4419c8bf 285
fbd4a07d
RP
286The filename passed as input is the capture driver number, ranging from
2870 to 9. You may use "list" as filename to print a list of drivers. Any
288other filename will be interpreted as device number 0.
289
4419c8bf
SS
290@section x11grab
291
292X11 video input device.
293
294This device allows to capture a region of an X11 display.
295
2f6bc4e7 296The filename passed as input has the syntax:
4419c8bf
SS
297@example
298[@var{hostname}]:@var{display_number}.@var{screen_number}[+@var{x_offset},@var{y_offset}]
299@end example
300
301@var{hostname}:@var{display_number}.@var{screen_number} specifies the
2f6bc4e7 302X11 display name of the screen to grab from. @var{hostname} can be
511cf612 303omitted, and defaults to "localhost". The environment variable
4419c8bf
SS
304@env{DISPLAY} contains the default display name.
305
306@var{x_offset} and @var{y_offset} specify the offsets of the grabbed
2f6bc4e7 307area with respect to the top-left border of the X11 screen. They
4419c8bf
SS
308default to 0.
309
310Check the X11 documentation (e.g. man X) for more detailed information.
311
312Use the @file{dpyinfo} program for getting basic information about the
2f6bc4e7 313properties of your X11 display (e.g. grep for "name" or "dimensions").
4419c8bf 314
d5837d7f 315For example to grab from @file{:0.0} using @command{avconv}:
4419c8bf 316@example
d5837d7f 317avconv -f x11grab -r 25 -s cif -i :0.0 out.mpg
4419c8bf 318
2f6bc4e7 319# Grab at position 10,20.
d5837d7f 320avconv -f x11grab -r 25 -s cif -i :0.0+10,20 out.mpg
085791a9
YJL
321@end example
322
323@subsection @var{follow_mouse} AVOption
324
325The syntax is:
326@example
327-follow_mouse centered|@var{PIXELS}
328@end example
329
330When it is specified with "centered", the grabbing region follows the mouse
331pointer and keeps the pointer at the center of region; otherwise, the region
332follows only when the mouse pointer reaches within @var{PIXELS} (greater than
333zero) to the edge of region.
334
335For example:
336@example
d5837d7f 337avconv -f x11grab -follow_mouse centered -r 25 -s cif -i :0.0 out.mpg
085791a9
YJL
338
339# Follows only when the mouse pointer reaches within 100 pixels to edge
d5837d7f 340avconv -f x11grab -follow_mouse 100 -r 25 -s cif -i :0.0 out.mpg
4419c8bf
SS
341@end example
342
1442d295
YJL
343@subsection @var{show_region} AVOption
344
345The syntax is:
346@example
347-show_region 1
348@end example
349
350If @var{show_region} AVOption is specified with @var{1}, then the grabbing
351region will be indicated on screen. With this option, it's easy to know what is
352being grabbed if only a portion of the screen is grabbed.
353
354For example:
355@example
d5837d7f 356avconv -f x11grab -show_region 1 -r 25 -s cif -i :0.0+10,20 out.mpg
1442d295
YJL
357
358# With follow_mouse
d5837d7f 359avconv -f x11grab -follow_mouse centered -show_region 1 -r 25 -s cif -i :0.0 out.mpg
1442d295
YJL
360@end example
361
b31328d0
LB
362@subsection @var{grab_x} @var{grab_y} AVOption
363
364The syntax is:
365@example
366-grab_x @var{x_offset} -grab_y @var{y_offset}
367@end example
368
369Set the grabing region coordinates. The are expressed as offset from the top left
370corner of the X11 window. The default value is 0.
371
4419c8bf 372@c man end INPUT DEVICES