1FSWEBCAM(1) User Commands FSWEBCAM(1)
2
6 fswebcam - Small and simple webcam for *nix.
7
9 fswebcam [<options>] <filename> [[<options>] <filename> ... ]
10
12 fswebcam is a small and simple webcam app for *nix. It can capture
13 images from a number of different sources and perform simple manipula‐
14 tion on the captured image. The image can be saved as one or more PNG,
15 JPEG or WEBP files.
16 The image can be sent to stdio using the filename "-". The output file‐
18 name is formatted by strftime.
19
22 Configuration File
23 Config files use the long version of options without the "--" prefix.
24 Comments start with a # symbol at the beginning of the line.
25 General Options
28 -?, --help
29 Show a usage summary.
30 -c, --config
33 Load options from a file. You can load more than one config
34 file, and can mix them with command-line arguments.
35 Note: This option can not be used from within a configuration
37 file.
38 -q, --quiet
41 Hides all messages except errors.
42 -v, --verbose
45 Print extra information during the capture process.
46 --version
49 Print the version number and exit.
50 -l, --loop <frequency>
53 Continually capture images. The time between images is specified
54 in seconds.
55 Default behaviour is to capture a single image and exit.
57 Note: The time to capture the next image is calculated relative
59 to the epoch, so an image will not be captured immediately when
60 the program is first started.
61 --offset <seconds>
64 Sets the offset to use when calculating when the next image is
65 due in loop mode. Value can be positive or negative.
66 --count <number>
69 Sets the number of times to capture an image in loop mode before
70 exiting.
71 Default is 0, loop forever.
73 -b, --background
76 Run in the background. In this mode stdout and console logging
77 are unavailable.
78 --pid <filename>
81 Saves the PID of the background process to the specified file.
82 Ignored when not using background mode.
83 -L, --log [file/syslog:]<filename>
86 Redirect log messages to a file or syslog. For example
87 --log output.log
89 --log file:output.log
90 --log syslog
91 --gmt Use GMT instead of the local timezone when formatting text with
94 strftime.
95 Capture Options
98 -d, --device [<prefix>:]<device name>
99 Set the source or device to use. The source module is selected
100 automatically unless specified in the prefix.
101 Default is /dev/video0.
103 Available source modules, in order of preference:
105 V4L2 - Capture images from a V4L2 compatible video device.
107 V4L1 - Capture images from a V4L1 compatible video device.
108 FILE - Capture an image from a JPEG or PNG image file.
109 RAW - Reads images straight from a device or file.
110 TEST - Draws colour bars.
111 -i, --input <input number or name>
114 Set the input to use. You may select an input by either it's
115 number or name.
116 Default is "0".
118 --list-inputs
121 List available inputs for the selected source or device.
122 fswebcam -d v4l2:/dev/video1 --list-inputs
124 -t, --tuner <tuner number>
127 Set the tuner to use.
128 -f, --frequency <frequency>
131 Set the frequency of the selected input or tuner. The value may
132 be read as KHz or MHz depending on the input or tuner.
133 -p, --palette <name>
136 Try to use the specified image format when capturing the image.
137 Default is to select one automatically.
139 Supported formats:
141 PNG
143 JPEG
144 MJPEG
145 S561
146 RGB32
147 RGB24
148 BGR32
149 BGR24
150 YUYV
151 UYVY
152 YUV420P
153 BAYER
154 SBGGR8
155 SRGGB8
156 SGBRG8
157 SGRBG8
158 RGB565
159 RGB555
160 Y16
161 GREY
162 -r, --resolution <dimensions>
165 Set the image resolution of the source or device. The actual
166 resolution used may differ if the source or device cannot cap‐
167 ture at the specified resolution.
168 Default is "384x288".
170 --fps <frames per second>
173 Sets the frame rate of the capture device. This currently only
174 works with certain V4L2 devices.
175 Default is "0", let the device decide.
177 -F, --frames <number>
180 Set the number of frames to capture. More frames mean less noise
181 in the final image, however capture times will be longer and
182 moving objects may appear blurred.
183 Default is "1".
185 -S, --skip <number>
188 Set the number of frames to skip. These frames will be captured
189 but won't be use. Use this option if your camera sends some bad
190 or corrupt frames when it first starts capturing.
191 Default is "0".
193 -D, --delay <delay>
196 Inserts a delay after the source or device has been opened and
197 initialised, and before the capture begins. Some devices need
198 this delay to let the image settle after a setting has changed.
199 The delay time is specified in seconds.
200 -T, --timeout <seconds>
203 Adjusts the timeout period in seconds for frame capture. This
204 should be increased for exposures longer than 10 seconds.
205 Default is "10".
207 -R, --read
210 Use read() to capture images. This can be slower but more stable
211 with some devices.
212 Default is to use mmap(), falling back on read() if mmap() is
214 unavailable.
215 -s, --set <name=value>
218 Set a control. These are used by the source modules to control
219 image or device parameters. Numeric values can be expressed as a
220 percentage of there maximum range or a literal value, for exam‐
221 ple:
222 --set brightness=50% --set framerate=5
224 Non-numeric controls are also supported:
226 --set lights=on
228 V4L2 features a type of control called a 'button'. These con‐
230 trols do not take any value, but trigger an action. For example:
231 --set "Restore Factory Settings"
233 Control names and values are not case sensitive.
235 Note: Available controls will vary depending in the source mod‐
237 ule and devices used. For more information see the --list-con‐
238 trols option.
239 --list-controls
242 List available controls and their current values for the
243 selected source module and device. For example:
244 fswebcam -d v4l2:/dev/video2 --list-controls
246 Output Options
249 These options are performed in the order they appear on the command
250 line, only effecting images output later on the command line. For exam‐
251 ple:
252 fswebcam -r 640x480 output1.jpeg --scale 320x240 output2.jpeg
254 Will create two images, "output1.jpeg" containing a full resolu‐
256 tion copy of the captured image and "output2.jpeg" containing
257 the same captured image but scaled to half the size.
258 --no-banner
261 Disable the banner.
262 --top-banner
265 Position the banner at the top of the image.
266 --bottom-banner
269 Position the banner at the bottom of the image.
270 This is the default.
272 --banner-colour <#AARRGGBB>
275 Set the colour of the banner. Uses the web-style hexadecimal
276 format (#RRGGBB) to describe the colour, and can support an
277 alpha channel (#AARRGGBB). Examples:
278 "#FF0000" is pure red.
280 "#80000000" is semi-transparent black.
281 "#FF000000" is invisible (alpha channel is at maximum).
282 Default is "#40263A93".
283 --line-colour <#AARRGGBB>
286 Set the colour of the divider line. See --banner-colour for more
287 information.
288 Default is "#00FF0000".
290 --text-colour <#AARRGGBB>
293 Set the colour of the text. See --banner-colour for more infor‐
294 mation.
295 Default is "#00FFFFFF".
297 --font <[file or font name]:[font size]>
300 Set the font used in the banner. If no path is specified the
301 path in the GDFONTPATH environment variable is searched for the
302 font. Fontconfig names may also be used if the GD library has
303 support.
304 If no font size is specified the default of "10" will be used.
306 Default is "sans:10".
308 --no-shadow
311 Disable the text shadow.
312 --shadow
315 Enable the text shadow.
316 This is the default behaviour.
318 --title <text>
321 Set the main text, located in the top left of the banner.
322 --no-title
325 Clear the main text.
326 --subtitle <text>
329 Set the sub-title text, located in the bottom left of the ban‐
330 ner.
331 --no-subtitle
334 Clear the sub-title text.
335 --timestamp <text>
338 Set the timestamp text, located in the top right of the banner.
339 This string is formatted by strftime.
340 Default is "%Y-%m-%d %H:%M (%Z)".
342 --no-timestamp
345 Clear the timestamp text.
346 --info <text>
349 Set the info text, located in the bottom right of the banner.
350 --no-info
353 Clear the info text.
354 --underlay <filename>
357 Load a PNG image and overlay it on the image, below the banner.
358 The image is aligned to the top left.
359 Note: The underlay is only applied when saving an image and is
361 not modified by any of the image options or effects.
362 --no-underlay
365 Clear the underlay image.
366 --overlay <filename>
369 Load a PNG image and overlay on the image, above the banner. The
370 image is aligned to the top left.
371 Note: The overlay is only applied when saving an image and is
373 not modified by any of the image options or effects.
374 --no-overlay
377 Remove the overlay image.
378 --jpeg <factor>
381 Set JPEG as the output image format. The compression factor is a
382 value between 0 and 95, or -1 for automatic.
383 This is the default format, with a factor of "-1".
385 --png <factor>
388 Set PNG as the output image format. The compression factor can
389 be a value between 0 and 9, or -1 for automatic.
390 --webp <factor>
393 Set WEBP as the output image format. The compression factor is a
394 value between 0 and 100, or -1 for automatic.
395 Requires WEBP support in libgd.
397 --save <filename>
400 Saves the image to the specified filename.
401 Note: This isn't necessary on the command-line where a filename
403 alone is enough to save an image.
404 --revert
407 Revert to the original captured image and resolution. This
408 undoes all previous effects on the image.
409 Note: This only reverts the image itself, and not options such
411 as font, colours and overlay.
412 --flip <direction[,direction]>
415 Flips the image. Direction can be (h)orizontal or (v)ertical.
416 Example:
417 --flip h Flips the image horizontally.
419 --flip h,v Flips the image both horizontally and vertically.
420 --crop <dimensions[,offset]>
423 Crop the image. With no offset the cropped area will be the cen‐
424 ter of the image. Example:
425 --crop 320x240 Crops the center 320x240 area of the image.
427 --crop 10x10,0x0 Crops the 10x10 area at the top left corner of
428 the image.
429 --scale <dimensions>
432 Scale the image.
433 Example: "--scale 640x480" scales the image up or down to
435 640x480.
436 Note: The aspect ratio of the image is not maintained.
438 --rotate <angle>
441 Rotate the image in right angles (90, 180 and 270 degrees).
442 Note: Rotating the image 90 or 270 degrees will swap the dimen‐
444 sions.
445 --deinterlace
448 Apply a simple deinterlacer to the image.
449 --invert
452 Invert all the colours in the image, creating a negative.
453 --greyscale
456 Remove all colour from the image.
457 --swapchannels <c1c2>
460 Swap colour channels c1 and c2. Valid channels are R, G and B --
461 for Red, Green and Blue channels respectively.
462 Example: "--swapchannels RB" will swap the red and blue chan‐
464 nels.
465 --exec <command>
468 Executes the specified command and waits for it to complete
469 before continuing. The command line is formatted by strftime.
470
473 SIGHUP This causes fswebcam to reload it's configuration.
474 SIGUSR1
477 Causes fswebcam to capture an image immediately without waiting
478 on the timer in loop mode.
479
482 The spacing between letters may be incorrect. This is an issue with the
483 GD library.
484
487 Please report bugs to <phil@sanslogic.co.uk>.
488
491 ncftpput(1), strftime(3)
492
495 Written by Philip Heron <phil@sanslogic.co.uk>.
496fswebcam 20200725 25 July 2020 FSWEBCAM(1)