tgq: convert to bytestream2 API.
[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
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
4419c8bf
SS
257@section video4linux and video4linux2
258
259Video4Linux and Video4Linux2 input video devices.
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
267Video4Linux and Video4Linux2 devices only support a limited set of
268@var{width}x@var{height} sizes and framerates. You can check which are
2f6bc4e7 269supported for example with the command @file{dov4l} for Video4Linux
a6a4793d 270devices and using @command{-list_formats all} for Video4Linux2 devices.
4419c8bf
SS
271
272If the size for the device is set to 0x0, the input device will
273try to autodetect the size to use.
8621a37d
SS
274Only for the video4linux2 device, if the frame rate is set to 0/0 the
275input device will use the frame rate value already set in the driver.
4419c8bf
SS
276
277Video4Linux support is deprecated since Linux 2.6.30, and will be
278dropped in later versions.
279
280Follow some usage examples of the video4linux devices with the ff*
281tools.
282@example
8621a37d
SS
283# Grab and show the input of a video4linux device, frame rate is set
284# to the default of 25/1.
266463da 285avplay -s 320x240 -f video4linux /dev/video0
4419c8bf 286
2f6bc4e7 287# Grab and show the input of a video4linux2 device, autoadjust size.
266463da 288avplay -f video4linux2 /dev/video0
4419c8bf 289
8621a37d
SS
290# Grab and record the input of a video4linux2 device, autoadjust size,
291# frame rate value defaults to 0/0 so it is read from the video4linux2
292# driver.
d5837d7f 293avconv -f video4linux2 -i /dev/video0 out.mpeg
4419c8bf
SS
294@end example
295
296@section vfwcap
297
52c55330 298VfW (Video for Windows) capture input device.
4419c8bf 299
fbd4a07d
RP
300The filename passed as input is the capture driver number, ranging from
3010 to 9. You may use "list" as filename to print a list of drivers. Any
302other filename will be interpreted as device number 0.
303
4419c8bf
SS
304@section x11grab
305
306X11 video input device.
307
308This device allows to capture a region of an X11 display.
309
2f6bc4e7 310The filename passed as input has the syntax:
4419c8bf
SS
311@example
312[@var{hostname}]:@var{display_number}.@var{screen_number}[+@var{x_offset},@var{y_offset}]
313@end example
314
315@var{hostname}:@var{display_number}.@var{screen_number} specifies the
2f6bc4e7
SS
316X11 display name of the screen to grab from. @var{hostname} can be
317ommitted, and defaults to "localhost". The environment variable
4419c8bf
SS
318@env{DISPLAY} contains the default display name.
319
320@var{x_offset} and @var{y_offset} specify the offsets of the grabbed
2f6bc4e7 321area with respect to the top-left border of the X11 screen. They
4419c8bf
SS
322default to 0.
323
324Check the X11 documentation (e.g. man X) for more detailed information.
325
326Use the @file{dpyinfo} program for getting basic information about the
2f6bc4e7 327properties of your X11 display (e.g. grep for "name" or "dimensions").
4419c8bf 328
d5837d7f 329For example to grab from @file{:0.0} using @command{avconv}:
4419c8bf 330@example
d5837d7f 331avconv -f x11grab -r 25 -s cif -i :0.0 out.mpg
4419c8bf 332
2f6bc4e7 333# Grab at position 10,20.
d5837d7f 334avconv -f x11grab -r 25 -s cif -i :0.0+10,20 out.mpg
085791a9
YJL
335@end example
336
337@subsection @var{follow_mouse} AVOption
338
339The syntax is:
340@example
341-follow_mouse centered|@var{PIXELS}
342@end example
343
344When it is specified with "centered", the grabbing region follows the mouse
345pointer and keeps the pointer at the center of region; otherwise, the region
346follows only when the mouse pointer reaches within @var{PIXELS} (greater than
347zero) to the edge of region.
348
349For example:
350@example
d5837d7f 351avconv -f x11grab -follow_mouse centered -r 25 -s cif -i :0.0 out.mpg
085791a9
YJL
352
353# Follows only when the mouse pointer reaches within 100 pixels to edge
d5837d7f 354avconv -f x11grab -follow_mouse 100 -r 25 -s cif -i :0.0 out.mpg
4419c8bf
SS
355@end example
356
1442d295
YJL
357@subsection @var{show_region} AVOption
358
359The syntax is:
360@example
361-show_region 1
362@end example
363
364If @var{show_region} AVOption is specified with @var{1}, then the grabbing
365region will be indicated on screen. With this option, it's easy to know what is
366being grabbed if only a portion of the screen is grabbed.
367
368For example:
369@example
d5837d7f 370avconv -f x11grab -show_region 1 -r 25 -s cif -i :0.0+10,20 out.mpg
1442d295
YJL
371
372# With follow_mouse
d5837d7f 373avconv -f x11grab -follow_mouse centered -show_region 1 -r 25 -s cif -i :0.0 out.mpg
1442d295
YJL
374@end example
375
4419c8bf 376@c man end INPUT DEVICES