wcggrabber − grab (capture) a frame from a video4linux (version 1) device


wcggrabber [OPTION]...


wcggrabber grabs one frame from a video4linux (version 1) device and writes it as an image in ppm(5) or pgm(5) format to standard output. The video4linux device can be specified via an option, the default device is /dev/video0. If the device is set to a not supported colour space (palette), wcggrabber tries to set one of the supported palettes. Image parameters can be controlled via options, otherwise the current device settings are used.


wcggrabber supports the following palettes:

4, 6 and 8 bit GREY













If the video4linux device cannot work with one of the supported palettes, wcggrabber cannot convert the frame to ppm(5) or pgm(5) format. A frame can be captured in the raw format of the device with the appropriate command line option.


-h, --help

Write a help message to standard error. The default settings are shown as well.

-V, --version

Write version information to standard error.

-v, --verbose

Print information about the program execution to standard error.

-q, --quiet

Do not print error or warning messages.

-i, --info-only

Query the video4linux device capabilites, write them to standard error, and exit.

-s, --set-only

Set the video4linux device parameters given on the command line, and exit.

-f, --file, -o, --out-file FILE

Write the image data to the specified FILE instead of standard output. You can use - to specify standard output.

-d, --device DEVICE

Use the specified video4linux DEVICE instead of the default /dev/video0.


Set the size of the captured image. The size can be specified by giving the WIDTH and HEIGHT in pixels or by using a special KEYWORD. Use --size help to get a list of supported keywords printed to standard error. Query the device capabilities to get the usable range.

-M, --max-size

Use the maximum supported image size of the video4linux device. This option has been superseded by --size max.

-I, --min-size

Use the minimum supported image size of the video4linux device. This option has been superseded by --size min.

-b, --brightness BRIGHTNESS

Set the brightness parameter of the video4linux device to BRIGHTNESS.

-H, --hue HUE

Set the hue parameter of the video4linux device to HUE.

-c, --colour COLOUR

Set the colour parameter of the video4linux device to COLOUR.

-C, --contrast CONTRAST

Set the contrast parameter of the video4linux device to CONTRAST.

-w, --whiteness WHITENESS

Set the whiteness parameter of the video4linux device to WHITENESS. This parameter is relevant for the GREY palettes only.

-p, --palette PALETTE

Set the palette of the video4linux device to PALETTE. Use --palette help to get a list of keywords to be used as values for PALETTE printed to standard error.

Note that any video4linux palette can be set, but image capturing in ppm(5) or pgm(5) format is only possible for the supported palettes (see SUPPORTED PALETTES above). The pixel depth of the palette is set as well.

-D, --depth DEPTH

Sets the pixel depth of the palette to DEPTH.

Note that the pixel depth is automatically set, this option can be used to manually override this. You are on you’re own if you use this option. This option can be useful to overwrite wrong default values.

-n, --channel NUMBER

Set the channel parameter of the video4linux device to NUMBER. Query the device capabilites to find out about the channels of your video4linux device.

-a, --auto-bright

Use the algorithm from vgrabber.c to automatically adjust the image brightness. This works with RGB palettes only and is intended for RGB24 and RGB32, you should not expect it to be usable with RGB565, RGB555, or GREY palettes.

Note that some video4linux devices have an automatic brightness adjustment that does not work well with this option.

-t, --max-tries NUMBER

Set the maximum number of tries to find a suitable brightness setting with vgrabber.c’s automatic brightness adjustment. The default value is 100.

-R, --rgb-map MAP

Map the values of red, green and blue, represented by RGB, to one of RGB, RBG, GRB, GBR, BGR, or BRG.

Note that the RGB24 and RGB32 palettes are sometimes BGR palettes (at least they are on my bttv card) and therefore need the option --rgb-map BGR.

-g, --swap-gb

Swap the green and blue bytes in output. This option has been superseded by --rgb-map RBG.

-r, --swap-rb

Swap the red and blue bytes in output. This option has been superseded by --rgb-map BGR.

-l, --ignore-lsb

Ignore the least significant bit of the 16bit value of the RGB555 palette. If the colours of an image captured using this palette seem wrong, try this option.

-m, --ignore-msb

Ignore the most significant bit of the 16bit value of the RGB555 palette. This is the default operation and works with my bttv card.

-W, --write-raw

Write the raw video4linux data as output instead of a ppm(5) or pgm(5) format image. This can be useful to get one frame from a video4linux device that does not support any of the palettes supported by wcggrabber. You could use dd(1) instead, but you would have to compute the exact frame size yourself.

-Y, --lum-only

Write a greyscale image in pgm(5) format using only the Y (luma) values. This works for the YUV palettes only, i.e. UYVY, YUYV, and YUV422. The result is not very good, you should use some image processing tool, e.g. netpbm(1) or ImageMagick(1), to convert colour images to greyscale.

-A, --wait-after-open SECONDS

Wait SECONDS after opening the video device. This gives the device some time for e.g. automatic brightness adjustment or sensor initialization. This option should not be needed, it is a workaround for buggy drivers. This might help if you sometimes get just a blue (or red) image after accesing the video device the first time.

-z, --discard-frames NUMBER

Grab and discard NUMBER frames before grabbing the frame used for output or (with --auto-bright) brightness adjustment. Some video4linux devices change sensor settings during image grabbing. Use this option to ignore image frames during this phase.


Capture a frame from the default device using the current device settings and use display(1) from ImageMagick(1) to display the image:

wcggrabber | display -

Query the capabilities of the video4linux device /dev/video1:

wcggrabber --info-only --device /dev/video1

Set the default video4linux device /dev/video0 to the maximum supported image size and the RGB24 palette:

wcggrabber --set-only --size max --palette rgb24

Capture a frame from /dev/video1 in VGA resolution using the UYVY palette and write it to the file image.ppm:

wcggrabber -d /dev/video1 -S vga -p uyvy -o image.ppm


wcggrabber uses the obsolete video4linux version 1 API.

wcggrabber works on little endian systems only.

The YUV to RGB conversion uses arbitrary values and does not conform to any standard. The RGB values do not conform to the CIE Rec. 709 gamma transfer function as required by the ppm(5) resp. pgm(5) definition.

Only a subset of the video4linux palettes is supported.

Capturing colour images using the YUV411P palette does not always work correctly.

The options to query and set device settings should be seperate programs.


wcggrabber was written by Erik Auerswald <auerswal@unix-ag.uni-kl.de> based on vgrabber.c written by Phil Blundell <philb@gnu.org> and yuv2ppm.c written by Scott Scriven <toykeeper@cheerful.com>.


netpbm(1), ppm(5), pgm(5), dd(1), ImageMagick(1), display(1),