FSWEBCAM(1)

📦
this version · 2 versions
, in epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

👑 FSWEBCAM 👑

okay bestie, welcome to the manual page for fswebcam — that's section 1, the User Commands corner of the manual, and it's giving tiny-but-mighty. Let's get into it 💖

✨ NAME ✨

fswebcam — small and simple webcam for *nix. literally the whole point. 🎀

🌸 SYNOPSIS 🌸

fswebcam [<options>] <filename> [[<options>] <filename> ... ]

🦋 DESCRIPTION 🦋

so fswebcam is a small and simple webcam app for *nix, and no cap it really does keep it simple. it can capture images from a whole bunch of different sources, and then it'll do some simple manipulation on the image it grabbed.

the image can be saved as one or more PNG, JPEG or WEBP files. iconic 💅

you can also send the image straight to stdio — just use the filename "-". and the output filename gets formatted by strftime, so you can put date/time stuff in there and it'll do the thing. ✨

🎀 CONFIGURATION 🎀

💜 Configuration File

config files use the long version of options, without the -- prefix. no dashes, bestie, just the word.

comments start with a # symbol — and it has to be at the beginning of the line, not just vibing somewhere in the middle.

🌈 General Options

  • -?, --help — shows a usage summary. the little cheat sheet 🫶
  • -c, --config — load options from a file. you can load more than one config file, and you can mix them with command-line arguments, go off.
⚠️ Note: this option can not be used from within a configuration file. so don't try it, it's not the vibe.
  • -q, --quiet — hides all messages except errors. silence, but make it stylish 🤫
  • -v, --verbose — prints extra information during the capture process. she's chatty now 💬
  • --version — prints the version number and exits. bye 👋
  • -l, --loop <frequency> — continually captures images. the time between images is specified in seconds. default behaviour is to capture a single image and exit.
⚠️ Note: the time to capture the next image is calculated relative to the epoch, so an image will not be captured immediately when the program is first started. like, she needs a sec. 😭
  • --offset <seconds> — sets the offset to use when calculating when the next image is due in loop mode. the value can be positive or negative.
  • --count <number> — sets the number of times to capture an image in loop mode before exiting. default is 0, which means loop forever. forever and ever bestie ♾️
  • -b, --background — run in the background. in this mode stdout and console logging are unavailable. she's busy, don't @ her.
  • --pid <filename> — saves the PID of the background process to the specified file. ignored when you're not using background mode.
  • -L, --log [file/syslog:]<filename> — redirect log messages to a file or syslog. for example:
--log output.log
--log file:output.log
--log syslog
  • --gmt — use GMT instead of the local timezone when formatting text with strftime. 🌍

🔥 Capture Options

  • -d, --device [<prefix>:]<device name> — set the source or device to use. the source module is selected automatically unless you specify it in the prefix. default is /dev/video0.

available source modules, in order of preference:

  • V4L2 — capture images from a V4L2 compatible video device.
  • V4L1 — capture images from a V4L1 compatible video device.
  • FILE — capture an image from a JPEG or PNG image file.
  • RAW — reads images straight from a device or file.
  • TEST — draws colour bars. 🌈 yes the test pattern, she's serving
  • -i, --input <input number or name> — set the input to use. you can pick an input by either its number or its name, your choice bestie. default is "0".
  • --list-inputs — list available inputs for the selected source or device.
fswebcam -d v4l2:/dev/video1 --list-inputs
  • -t, --tuner <tuner number> — set the tuner to use.
  • -f, --frequency <frequency> — set the frequency of the selected input or tuner. the value may be read as KHz or MHz depending on the input or tuner.
  • -p, --palette <name> — try to use the specified image format when capturing the image. default is to select one automatically.

supported formats:

  • PNG
  • JPEG
  • MJPEG
  • S561
  • RGB32
  • RGB24
  • BGR32
  • BGR24
  • YUYV
  • UYVY
  • YUV420P
  • BAYER
  • SBGGR8
  • SRGGB8
  • SGBRG8
  • SGRBG8
  • RGB565
  • RGB555
  • Y16
  • GREY
  • -r, --resolution <dimensions> — set the image resolution of the source or device. the actual resolution used may differ if the source or device cannot capture at the specified resolution. so don't be pressed if it negotiates, okay? 🙈 default is "384x288".
  • --fps <frames per second> — sets the frame rate of the capture device. this currently only works with certain V4L2 devices. default is "0", which lets the device decide. she's independent 💅
  • -F, --frames <number> — set the number of frames to capture. more frames mean less noise in the final image, however capture times will be longer and moving objects may appear blurred. trade-offs, bestie, trade-offs. default is "1".
  • -S, --skip <number> — set the number of frames to skip. these frames will be captured but won't be used. use this option if your camera sends some bad or corrupt frames when it first starts capturing. default is "0".
  • -D, --delay <delay> — inserts a delay after the source or device has been opened and initialised, and before the capture begins. some devices need this delay to let the image settle after a setting has changed. the delay time is specified in seconds. let her breathe 😌
  • -T, --timeout <seconds> — adjusts the timeout period in seconds for frame capture. this should be increased for exposures longer than 10 seconds. default is "10".
  • -R, --read — use read() to capture images. this can be slower but more stable with some devices. default is to use mmap(), falling back on read() if mmap() is unavailable.
  • -s, --set <name=value> — set a control. these are used by the source modules to control image or device parameters. numeric values can be expressed as a percentage of their maximum range or a literal value, for example:
--set brightness=50% --set framerate=5

non-numeric controls are also supported:

--set lights=on

V4L2 features a type of control called a 'button'. these controls do not take any value, but trigger an action. for example:

--set "Restore Factory Settings"

control names and values are not case sensitive. so scream them if you want, she doesn't care 💅

⚠️ Note: available controls will vary depending on the source module and devices used. for more information see the --list-controls option.
  • --list-controls — list available controls and their current values for the selected source module and device. for example:
fswebcam -d v4l2:/dev/video2 --list-controls

🧚 Output Options

these options are performed in the order they appear on the command line, only effecting images output later on the command line. so like, position matters, it's giving main character energy for whatever comes after it ✨ for example:

fswebcam -r 640x480 output1.jpeg --scale 320x240 output2.jpeg

will create two images — "output1.jpeg" containing a full resolution copy of the captured image, and "output2.jpeg" containing the same captured image but scaled to half the size. two for one, ate. 🔥

  • --no-banner — disable the banner. 🚫
  • --top-banner — position the banner at the top of the image. ⬆️
  • --bottom-banner — position the banner at the bottom of the image. this is the default.
  • --banner-colour <#AARRGGBB> — set the colour of the banner. uses the web-style hexadecimal format (#RRGGBB) to describe the colour, and can support an alpha channel (#AARRGGBB). examples:
"#FF0000" is pure red.
"#80000000" is semi-transparent black.
"#FF000000" is invisible (alpha channel is at maximum).

default is "#40263A93".

  • --line-colour <#AARRGGBB> — set the colour of the divider line. see --banner-colour for more information. default is "#00FF0000".
  • --text-colour <#AARRGGBB> — set the colour of the text. see --banner-colour for more information. default is "#00FFFFFF".
  • --font <[file or font name]:[font size]> — set the font used in the banner. if no path is specified the path in the GDFONTPATH environment variable is searched for the font. Fontconfig names may also be used if the GD library has support. if no font size is specified the default of "10" will be used. default is "sans:10". cute and legible 🎀
  • --no-shadow — disable the text shadow.
  • --shadow — enable the text shadow. this is the default behaviour.
  • --title <text> — set the main text, located in the top left of the banner.
  • --no-title — clear the main text.
  • --subtitle <text> — set the sub-title text, located in the bottom left of the banner.
  • --no-subtitle — clear the sub-title text.
  • --timestamp <text> — set the timestamp text, located in the top right of the banner. this string is formatted by strftime. default is "%Y-%m-%d %H:%M (%Z)".
  • --no-timestamp — clear the timestamp text.
  • --info <text> — set the info text, located in the bottom right of the banner.
  • --no-info — clear the info text.
  • --underlay <filename> — load a PNG image and overlay it on the image, below the banner. the image is aligned to the top left.
⚠️ Note: the underlay is only applied when saving an image and is not modified by any of the image options or effects.
  • --no-underlay — clear the underlay image.
  • --overlay <filename> — load a PNG image and overlay on the image, above the banner. the image is aligned to the top left.
⚠️ Note: the overlay is only applied when saving an image and is not modified by any of the image options or effects.
  • --no-overlay — remove the overlay image.
  • --jpeg <factor> — set JPEG as the output image format. the compression factor is a value between 0 and 95, or -1 for automatic. this is the default format, with a factor of "-1".
  • --png <factor> — set PNG as the output image format. the compression factor can be a value between 0 and 9, or -1 for automatic.
  • --webp <factor> — set WEBP as the output image format. the compression factor is a value between 0 and 100, or -1 for automatic.
⚠️ requires WEBP support in libgd. no support, no webp, sorry bestie 😭
  • --save <filename> — saves the image to the specified filename.
⚠️ Note: this isn't necessary on the command-line where a filename alone is enough to save an image.
  • --revert — revert to the original captured image and resolution. this undoes all previous effects on the image.
⚠️ Note: this only reverts the image itself, and not options such as font, colours and overlay.
  • --flip <direction[,direction]> — flips the image, bestie. direction can be h (horizontal) or v (vertical), and yeah you can stack two of them with a comma. Example:
--flip h    Flips the image horizontally.
--flip h,v  Flips the image both horizontally and vertically.
  • --crop <dimensions[,offset]> — crops the image down to a region. No offset? The cropped area lands right in the center of the image, main character energy. Examples:
--crop 320x240    Crops the center 320x240 area of the image.
--crop 10x10,0x0  Crops the 10x10 area at the top left corner of the image.
  • --scale <dimensions> — scales the image, up or down, whatever it takes. Example: --scale 640x480 scales the image to 640x480.
Heads up bestie: the aspect ratio of the image is not maintained. It will absolutely stretch. It's giving squish. 🫠
  • --rotate <angle> — rotates the image in right angles only: 90, 180 and 270 degrees.
Note: rotating the image 90 or 270 degrees will swap the dimensions. Not a bug, just math being math. ✨
  • --deinterlace — applies a simple deinterlacer to the image. That's it, that's the whole thing.
  • --invert — inverts all the colours in the image, creating a negative. Goth mode unlocked. 🖤
  • --greyscale — removes all colour from the image. Sad beige aesthetic, but make it pixels. 🌫️
  • --swapchannels <c1c2> — swaps colour channels c1 and c2. Valid channels are R, G and B — for Red, Green and Blue channels respectively.

Example: --swapchannels RB will swap the red and blue channels. 🎀

  • --exec <command> — executes the specified command and waits for it to complete before continuing. The command line is formatted by strftime. So yes, you can put all your fancy time placeholders in there. 💅

🚨 SIGNALS 🚨

  • SIGHUP — this causes fswebcam to reload its configuration. Fresh start, new you. 🌸
  • SIGUSR1 — causes fswebcam to capture an image immediately, without waiting on the timer in loop mode. Instant. No thoughts, just capture. 📸

💀 KNOWN BUGS 💀

The spacing between letters may be incorrect. This is an issue with the GD library — not us, not our fault, we're just the messenger. 😭

🐛 REPORTING BUGS 🐛

Please report bugs to <phil@sanslogic.co.uk>. Be nice, be specific, include the details. 🫶

👀 SEE ALSO 👀

ncftpput(1), strftime(3)

👑 AUTHOR 👑

Written by Philip Heron <phil@sanslogic.co.uk>. Iconic. Periodt. ✨

And that's a wrap on the whole page, bestie! This is fswebcam version 20200725, dated 25 July 2020, and you just read the one and only FSWEBCAM(1) man page. Go take some pictures, you absolute legend. 💖🎀🦋🌸

📦 where this page comes from