doc/indevs.texi

   1 @chapter Input Devices
   2 @c man begin INPUT DEVICES
   3
   4 Input devices are configured elements in Libav which allow to access
   5 the data coming from a multimedia device attached to your system.
   6
   7 When you configure your Libav build, all the supported input devices
   8 are enabled by default. You can list all available ones using the
   9 configure option "--list-indevs".
  10
  11 You can disable all the input devices using the configure option
  12 "--disable-indevs", and selectively enable an input device using the
  13 option "--enable-indev=@var{INDEV}", or you can disable a particular
  14 input device using the option "--disable-indev=@var{INDEV}".
  15
  16 The option "-formats" of the ff* tools will display the list of
  17 supported input devices (amongst the demuxers).
  18
  19 A description of the currently available input devices follows.
  20
  21 @section alsa
  22
  23 ALSA (Advanced Linux Sound Architecture) input device.
  24
  25 To enable this input device during configuration you need libasound
  26 installed on your system.
  27
  28 This device allows capturing from an ALSA device. The name of the
  29 device to capture has to be an ALSA card identifier.
  30
  31 An ALSA identifier has the syntax:
  32 @example
  33 hw:@var{CARD}[,@var{DEV}[,@var{SUBDEV}]]
  34 @end example
  35
  36 where the @var{DEV} and @var{SUBDEV} components are optional.
  37
  38 The three arguments (in order: @var{CARD},@var{DEV},@var{SUBDEV})
  39 specify card number or identifier, device number and subdevice number
  40 (-1 means any).
  41
  42 To see the list of cards currently recognized by your system check the
  43 files @file{/proc/asound/cards} and @file{/proc/asound/devices}.
  44
  45 For example to capture with @command{avconv} from an ALSA device with
  46 card id 0, you may run the command:
  47 @example
  48 avconv -f alsa -i hw:0 alsaout.wav
  49 @end example
  50
  51 For more information see:
  52 @url{http://www.alsa-project.org/alsa-doc/alsa-lib/pcm.html}
  53
  54 @section bktr
  55
  56 BSD video input device.
  57
  58 @section dv1394
  59
  60 Linux DV 1394 input device.
  61
  62 @section fbdev
  63
  64 Linux framebuffer input device.
  65
  66 The Linux framebuffer is a graphic hardware-independent abstraction
  67 layer to show graphics on a computer monitor, typically on the
  68 console. It is accessed through a file device node, usually
  69 @file{/dev/fb0}.
  70
  71 For more detailed information read the file
  72 Documentation/fb/framebuffer.txt included in the Linux source tree.
  73
  74 To record from the framebuffer device @file{/dev/fb0} with
  75 @command{avconv}:
  76 @example
  77 avconv -f fbdev -r 10 -i /dev/fb0 out.avi
  78 @end example
  79
  80 You can take a single screenshot image with the command:
  81 @example
  82 avconv -f fbdev -frames:v 1 -r 1 -i /dev/fb0 screenshot.jpeg
  83 @end example
  84
  85 See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1).
  86
  87 @section jack
  88
  89 JACK input device.
  90
  91 To enable this input device during configuration you need libjack
  92 installed on your system.
  93
  94 A JACK input device creates one or more JACK writable clients, one for
  95 each 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}
  97 is a number which identifies the channel.
  98 Each writable client will send the acquired data to the Libav input
  99 device.
 100
 101 Once you have created one or more JACK readable clients, you need to
 102 connect them to one or more JACK writable clients.
 103
 104 To connect or disconnect JACK clients you can use the
 105 @file{jack_connect} and @file{jack_disconnect} programs, or do it
 106 through a graphical interface, for example with @file{qjackctl}.
 107
 108 To list the JACK clients and their properties you can invoke the command
 109 @file{jack_lsp}.
 110
 111 Follows an example which shows how to capture a JACK readable client
 112 with @command{avconv}.
 113 @example
 114 # Create a JACK writable client with name "libav".
 115 $ avconv -f jack -i libav -y out.wav
 116
 117 # Start the sample jack_metro readable client.
 118 $ jack_metro -b 120 -d 0.2 -f 4000
 119
 120 # List the current JACK clients.
 121 $ jack_lsp -c
 122 system:capture_1
 123 system:capture_2
 124 system:playback_1
 125 system:playback_2
 126 libav:input_1
 127 metro:120_bpm
 128
 129 # Connect metro to the avconv writable client.
 130 $ jack_connect metro:120_bpm libav:input_1
 131 @end example
 132
 133 For more information read:
 134 @url{http://jackaudio.org/}
 135
 136 @section libdc1394
 137
 138 IIDC1394 input device, based on libdc1394 and libraw1394.
 139
 140 @section oss
 141
 142 Open Sound System input device.
 143
 144 The filename to provide to the input device is the device node
 145 representing the OSS input device, and is usually set to
 146 @file{/dev/dsp}.
 147
 148 For example to grab from @file{/dev/dsp} using @command{avconv} use the
 149 command:
 150 @example
 151 avconv -f oss -i /dev/dsp /tmp/oss.wav
 152 @end example
 153
 154 For more information about OSS see:
 155 @url{http://manuals.opensound.com/usersguide/dsp.html}
 156
 157 @section pulse
 158
 159 pulseaudio input device.
 160
 161 To enable this input device during configuration you need libpulse-simple
 162 installed in your system.
 163
 164 The filename to provide to the input device is a source device or the
 165 string "default"
 166
 167 To list the pulse source devices and their properties you can invoke
 168 the command @file{pactl list sources}.
 169
 170 @example
 171 avconv -f pulse -i default /tmp/pulse.wav
 172 @end example
 173
 174 @subsection @var{server} AVOption
 175
 176 The syntax is:
 177 @example
 178 -server @var{server name}
 179 @end example
 180
 181 Connects to a specific server.
 182
 183 @subsection @var{name} AVOption
 184
 185 The syntax is:
 186 @example
 187 -name @var{application name}
 188 @end example
 189
 190 Specify the application name pulse will use when showing active clients,
 191 by default it is "libav"
 192
 193 @subsection @var{stream_name} AVOption
 194
 195 The syntax is:
 196 @example
 197 -stream_name @var{stream name}
 198 @end example
 199
 200 Specify the stream name pulse will use when showing active streams,
 201 by default it is "record"
 202
 203 @subsection @var{sample_rate} AVOption
 204
 205 The syntax is:
 206 @example
 207 -sample_rate @var{samplerate}
 208 @end example
 209
 210 Specify the samplerate in Hz, by default 48kHz is used.
 211
 212 @subsection @var{channels} AVOption
 213
 214 The syntax is:
 215 @example
 216 -channels @var{N}
 217 @end example
 218
 219 Specify the channels in use, by default 2 (stereo) is set.
 220
 221 @subsection @var{frame_size} AVOption
 222
 223 The syntax is:
 224 @example
 225 -frame_size @var{bytes}
 226 @end example
 227
 228 Specify the number of byte per frame, by default it is set to 1024.
 229
 230 @subsection @var{fragment_size} AVOption
 231
 232 The syntax is:
 233 @example
 234 -fragment_size @var{bytes}
 235 @end example
 236
 237 Specify the minimal buffering fragment in pulseaudio, it will affect the
 238 audio latency. By default it is unset.
 239
 240 @section sndio
 241
 242 sndio input device.
 243
 244 To enable this input device during configuration you need libsndio
 245 installed on your system.
 246
 247 The filename to provide to the input device is the device node
 248 representing the sndio input device, and is usually set to
 249 @file{/dev/audio0}.
 250
 251 For example to grab from @file{/dev/audio0} using @command{avconv} use the
 252 command:
 253 @example
 254 avconv -f sndio -i /dev/audio0 /tmp/oss.wav
 255 @end example
 256
 257 @section video4linux2
 258
 259 Video4Linux2 input video device.
 260
 261 The name of the device to grab is a file device node, usually Linux
 262 systems tend to automatically create such nodes when the device
 263 (e.g. an USB webcam) is plugged into the system, and has a name of the
 264 kind @file{/dev/video@var{N}}, where @var{N} is a number associated to
 265 the device.
 266
 267 Video4Linux2 devices usually support a limited set of
 268 @var{width}x@var{height} sizes and framerates. You can check which are
 269 supported using @command{-list_formats all} for Video4Linux2 devices.
 270
 271 Some usage examples of the video4linux2 devices with avconv and avplay:
 272
 273 @example
 274 # Grab and show the input of a video4linux2 device.
 275 avplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
 276
 277 # Grab and record the input of a video4linux2 device, leave the
 278 framerate and size as previously set.
 279 avconv -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
 280 @end example
 281
 282 @section vfwcap
 283
 284 VfW (Video for Windows) capture input device.
 285
 286 The filename passed as input is the capture driver number, ranging from
 287 0 to 9. You may use "list" as filename to print a list of drivers. Any
 288 other filename will be interpreted as device number 0.
 289
 290 @section x11grab
 291
 292 X11 video input device.
 293
 294 This device allows to capture a region of an X11 display.
 295
 296 The filename passed as input has the syntax:
 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
 302 X11 display name of the screen to grab from. @var{hostname} can be
 303 omitted, and defaults to "localhost". The environment variable
 304 @env{DISPLAY} contains the default display name.
 305
 306 @var{x_offset} and @var{y_offset} specify the offsets of the grabbed
 307 area with respect to the top-left border of the X11 screen. They
 308 default to 0.
 309
 310 Check the X11 documentation (e.g. man X) for more detailed information.
 311
 312 Use the @file{dpyinfo} program for getting basic information about the
 313 properties of your X11 display (e.g. grep for "name" or "dimensions").
 314
 315 For example to grab from @file{:0.0} using @command{avconv}:
 316 @example
 317 avconv -f x11grab -r 25 -s cif -i :0.0 out.mpg
 318
 319 # Grab at position 10,20.
 320 avconv -f x11grab -r 25 -s cif -i :0.0+10,20 out.mpg
 321 @end example
 322
 323 @subsection @var{follow_mouse} AVOption
 324
 325 The syntax is:
 326 @example
 327 -follow_mouse centered|@var{PIXELS}
 328 @end example
 329
 330 When it is specified with "centered", the grabbing region follows the mouse
 331 pointer and keeps the pointer at the center of region; otherwise, the region
 332 follows only when the mouse pointer reaches within @var{PIXELS} (greater than
 333 zero) to the edge of region.
 334
 335 For example:
 336 @example
 337 avconv -f x11grab -follow_mouse centered -r 25 -s cif -i :0.0 out.mpg
 338
 339 # Follows only when the mouse pointer reaches within 100 pixels to edge
 340 avconv -f x11grab -follow_mouse 100 -r 25 -s cif -i :0.0 out.mpg
 341 @end example
 342
 343 @subsection @var{show_region} AVOption
 344
 345 The syntax is:
 346 @example
 347 -show_region 1
 348 @end example
 349
 350 If @var{show_region} AVOption is specified with @var{1}, then the grabbing
 351 region will be indicated on screen. With this option, it's easy to know what is
 352 being grabbed if only a portion of the screen is grabbed.
 353
 354 For example:
 355 @example
 356 avconv -f x11grab -show_region 1 -r 25 -s cif -i :0.0+10,20 out.mpg
 357
 358 # With follow_mouse
 359 avconv -f x11grab -follow_mouse centered -show_region 1  -r 25 -s cif -i :0.0 out.mpg
 360 @end example
 361
 362 @c man end INPUT DEVICES