VGRABBJ.CONF(5)

📦 version 0.9.9, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 VGRABBJ.CONF(5) 🎀

ok so bestie, you found the File Formats Manual page for vgrabbj.conf and honestly? iconic. let's get into it 💅

✨ NAME ✨

vgrabbj.conf — the configuration file for vgrabbj 🫶

🌸 OVERVIEW 🌸

so here's the vibe: vgrabbj's whole purpose is to read data from a v4l-device and put it into a file, formatted as jpeg, png, or pnm. literally everything except the ftp-options described below can also be handled right there on the commandline. this page is where we spill the tea on the configuration statements.

the syntax is <keyword> <value>. comments start with a ; or a #, and those lines just get ignored by vgrabbj. the case of the keywords and named options doesn't matter — EXCEPT for the timestamp option and any filename. those are case-sensitive, no cap. 😤

the configuration file gets parsed line by line. and if any keyword shows up twice or more often? the last one wins. periodt.

on startup, the pre-defined configuration file /etc/vgrabbj.conf is read first. then commandline parameters get evaluated one by one, and the last one is the most significant if an option is provided twice or more. same energy applies for the commandline parameter -c <config-file>. 💫

👑 GENERAL OPTIONS 👑

  • DaemonSeconds seconds — daemonize & loop with seconds intervals (min. 1). ⏰
  • Daemon microseconds — daemonize & loop microseconds intervals (min. 1). same as -l except you get to control it way more precisely. 💅
  • AutoBrightness On|Off — defines if vgrabbj's brightness adjustment gets used. this option only works if the device supports data fetch via read and the RGB24 videopalette. see ForcePalette for how-to set RGB24. some devices just do not support RGB24, so like, Brightness gets ignored. 🙈
  • ImageQuality quality — sets the quality of a jpeg output to quality (1-100, default: 75). ✨
  • ImageSize imagesize — sets the imagesize of the input device, where imagesize is one of:
sqcif= 128x96,     qsif = 160x120,
qcif = 176x144,    sif  = 320x240,
cif  = 352x288,    vga  = 640x480,
svga = 800x600,    xga  = 1024x768,
sxga = 1280x1024,  uxga = 1600x1200,

(default: cif)

  • ImageWidth width — sets the width of the image to width. needs -H. the v4l-device has to actually support the image width you set with this option. 🤝
  • ImageHeight height — sets the height of the image to height. needs -w. the v4l-device has to support the image height you set with this option. 🤝
  • OutputFormat format — sets the output to format (either jpeg, png, or pnm, default: jpeg). alternatively you may provide jpg for jpeg. 🌈
  • OutputFile <filename> — output is written to filename (default: /dev/stdout). 💖
  • Archive <path/filename> — additional output is written to path/filename (default: not set), and the path-filename can include any strftime component. the path-filename must not be on a different filesystem as the output defined above. also, you need to take care of the number of files stored yourself — there is no upper ceiling for archiving. 😭
  • VideoDevice <device> — sets the input device to device (default: /dev/video). 🎥
  • OpenOnce On|Off — defines if vgrabbj opens the device only while image data is grabbed (Off) or keeps it opened while it is running (On). setting it to Off is helpful if you need access to the device besides vgrabbj. this use is discouraged though, due to possible problems with memory fragmentation. default is On. ⚠️
  • SetImageSize On|Off — defines if the image size (see -i, -H, and -w) of the device is set by vgrabbj. necessary for certain v4l-devices which do not support being set to a particular image size (e.g. IBM-usb-cam, QuickCam). for these devices you have to specify the size at module load time. default is On. 💫
  • SwitchColor On|Off — switches colormap from BGR to RGB (or vice versa) if set to On. default is Off. use if you have odd colors. 🌈
  • SwapRL On|Off — swaps left and right of the image like a mirror. default: Off. is Off. 🪞
  • SwapTB On|Off — swaps top and bottom of the image like a mirror. default: Off. is Off. 🪞
  • NoUseMmap On|Off — turns off the use of mmap'ed (better) memory allocation for grabbing frames. some (very rare) cams cannot use mmap'ed memory and have to use read. if you want to switch easily, use this switch. if you don't know what I'm talking about, leafe it like it is: default is Off. 🍓
  • DebugLevel value — sets the loglevel of vgrabbj. valid for value are 0, 2, 3, 4, 6, 7 (default: 4). 0 means no messages at all, 7 is debug. don't use 7 if you are running vgrabbj in daemon mode, it'll surely fill your syslog. be aware, that loglevel 7 will also post you ftp-password (if defined) in the logfile! 💀
  • UseTmpOut On|Off — sets the use of the temporary outputfile. default is On. ignored in case the default output (/dev/stdout) is used. if set to Off, the data is written directly to the file defined by OutputFile.

if filename is different from /dev/stdout (given via -f parameter or OutputFile), vgrabbj defaults to use a temporary file called filename.tmp to write the image. this file is then renamed to filename to shorten the time period corrupt data may be read from filename. 🎀

  • Exec commands — ask vgrabbj to launch an external program. may be used to pass the picture through ImageMagick or other filters. the first %s instance in the command line will be replaced with filename. if UseTmpOut is On, commands will be run before the file is renamed. 🧚
  • ForcePalette palette — force the usage of the specified palette. if palette is not supported by either vgrabbj or the v4l-device, fallback to a palette supported by both is provided. if no common denominator is available, vgrabbj exits. supported palettes are marked with * below. possible values are (copy from videodev.h):
 1  VIDEO_PALETTE_GREY      Linear greyscale
 2  VIDEO_PALETTE_HI240     High 240 cube (BT848)
 3  VIDEO_PALETTE_RGB565    565 16 bit RGB
 4 *VIDEO_PALETTE_RGB24     24bit RGB
 5 *VIDEO_PALETTE_RGB32     32bit RGB
 6  VIDEO_PALETTE_RGB555    555 15bit RGB
 7 *VIDEO_PALETTE_YUV422    YUV422 capture
 8 *VIDEO_PALETTE_YUYV
 9 *VIDEO_PALETTE_UYVY
 10*VIDEO_PALETTE_YUV420
 10 VIDEO_PALETTE_YUV411    YUV411 capture
 11 VIDEO_PALETTE_RAW       RAW capture (BT848)
 12 VIDEO_PALETTE_YUV422P   YUV 4:2:2 Planar
 13 VIDEO_PALETTE_YUV411P   YUV 4:1:1 Planar
 14*VIDEO_PALETTE_YUV420P   YUV 4:2:0 Planar
 15 VIDEO_PALETTE_YUV410P   YUV 4:1:0 Planar
 16 VIDEO_PALETTE_PLANAR
 17 VIDEO_PALETTE_COMPONENT

(no default, depends on v4l-device). 🌸

  • DiscardFrames value — value images are grabbed and immediately discarded. only the last image is written to the output. this might be helpful if your v4l-device needs to take a couple of images to auto-adjust to the current light. 💡

📦 ARCHIVE OPTIONS 📦

the following options are useful if you want to keep a certain amount of images in an archive. currently, the archive is only supported if kept on the same filesystem as the images taken. 💾

  • Archive <archive-filename-pattern> — the archive-filename-pattern is evaluated as a timestring, hence the same applies as to TimeStamp (see below, default: /tmp/arch/cam-%Y-%d-%m-%H-%M-%S.jpg). ✨
  • ArchiveEach <value> — defines how many images have to be taken before a copy is made for the archive. e.g. if defined 1, each image is put in the archive; if defined 5 every fifth image is put in the archive. 🔢
  • ArchiveMax <value> — sets the maximum number of images to be put in the archive. 🛑

🕐 TIMESTAMP OPTIONS 🕐

the following options are available only if vgrabbj was compiled with the freetype library available. the timestamp will only be enabled if all values evaluated (including defaults) lead to a valid configuration and UseTimestamp is set to On. 👑

  • UseTimestamp On|Off — this is the essential setting to enable timestamps if defined in the config file. without this being set to On, it just won't work (although, if there are options set to have an invalid configuration, it won't work either). this is different to the handling on the commandline. 😤
  • FontFile filename — the TrueType font to be used for the timestamp (default /usr/X11R6/lib/X11/fonts/TrueType/Arialn.ttf). 🔤
  • FontSize size — set the fontsize to size for timestamp (3-100, default: 12). 💅
  • TimeStamp format-str — defines the timestamp. format-str can be plain text or any strftime format. any "" at the beginning or the end will be eliminated for compatibility reasons, i.e. they are not necessary (default: "%a, %e. %B %Y - %T" — see strftime(3) for details). 🗓️
  • Position value — alignment of the timestamp in the image. possible value:
ul = upper left,    ur = upper right,
ll = lower left,    lr = lower right,
uc = upper center,  lc = lower center

(default: upper right). you can use either the short or the long version. 📍

  • Blend value — defines the blend between font background and image (1-100, default: 60). 🎨
  • BorderSize value — value pixels will be used as border around the timestamp string (1-255, default: 2). 🖼️

🔥 FTP OPTIONS 🔥

okay so real talk bestie: there are no options for ftp-upload on the command line. none. zero. and it's for a very good reason — you'd have to put your password on the command line, and then literally anyone could see it with the ps(1) command. so no, we're not doing that. 🙈

  • EnableFtp On|Off — the Ftp-Connection only gets opened if this is set to On. heads up though: this might bring up a dial-up connection, so watch yourself. see also KeepAlive. (default: Off)
  • RemoteHost hostname — the host that a ftp-connection will be established to every single time an image has been written. (see also: Daemon, DaemonSeconds, KeepAlive, default: camimage.jpg)
  • RemoteDir path — this path is the full path on the remote host that you defined with RemoteHost. (default: /)
  • RemoteImageName filename — the filename here is the full path and filename on the remote host defined by RemoteHost. (default: foo.bar.com)
  • Username username — the name of the user you log on the remote ftp-server as. (default: foo)
  • Password password — the password of the user logging on to the remote ftp-server. (default: bar)
⚠️ be aware, that the password is kept unencrypted in memory, and it might be read by others. no cap, keep that in mind.
  • KeepAlive On|Off — if set to On, the connection stays up. which means your dial-up line is up all the time, which in turn may cost a LOT of money! 😭 if set to Off, the connection gets established after an image was written to the OutputFile, and after transmission the ftp-connection gets ended. this may also result in phone charges, for which the Author takes no responsibility. see License.
  • Passive On|Off — if set to On, passive ftp will be used. this can genuinely help with connecting to ftp servers from the inside of a NAT-ed network. slay 🦋
  • TryHarder On|Off — not implemented, yet. 💀

✨ HARDWARE SETTINGS ✨

with the following options you may alter the settings of your hardware (the cam), if it's supported by the cam. 🎀

🚨 okay this is the scary part: be aware, this might break your hardware, because there are no checks if the values you supply are valid, allowed, or supported! periodt.
  • -W <value> — whiteness definition.
  • -r <value> — color definition.
  • -x <value> — contrast definition.
  • -b <value> — brightness definition.
  • -u <value> — hue definition.

🐛 BUGS 🐛

ngl, on the author's own machine running vgrabbj, the %F in a Archive-Filename causes memory corruption. 💀 this is not validated by any other machine. no further bugs are known at this time.

👀 SEE ALSO 👀

vgrabbj(1), strftime(3), ps(1)

👑 AUTHOR 👑

this manual page was originally written by Michael Janssen <janssen@cns.uni.edu>, for the Debian GNU/Linux system, and enhanced by Jens Gecius <devel@gecius.de>. icons, both of them. 💅

and that's the whole page bestie!! this one's from February 24, 2002, VGRABBJ.CONF(5) — yes it's giving vintage but it still ate, fr fr. go forth and configure responsibly, mwah 🫶✨💖

📦 where this page comes from