Submit Hint Search The Forums LinksStatsPollsHeadlinesRSS
14,000 hints and counting!

Use a webcam from the terminal Apps
The goal was to figure out a way to capture images from a USB-webcam from the terminal. If all you want a simple point-and-click webcam app that runs on a host machine all the time, there are several very nice free and commercial apps out there (listed in the "References" section at the end of this article). In my case, I just wanted to grab an occasional image of our server room while logged in remotely to an OSX box located there.

There doesn't appear to be any purely command-line driven image capture apps for OSX at this time. At first I'd considered a quick AppleScript hack to launch and control one of the many GUI-based webcam apps from the terminal, but it bothered me that there wasn't a cleaner way to do this. Another possibility was to modify an existing webcam app, removing all the GUI-specific code and turning it into a command-line tool -- not pleasant a prospect, particularly if it meant mutilating someone else's code. Also, the 'just for fun' aspect of the project suspiciously began to sound like real work.

The approach I eventually took involves using a webcam-aware image processing package that happens to command-line component. Read the rest of the article for the how-to...

INGREDIENTSThere are a few problems using this specific camera with the macam driver; see below for details.


It seems that there are very few cheap, off-the-shelf webcams for OSX at the moment. There are several excellent FireWire-based models that work great under OSX, but they were all outside of my price range for this project. Also, since OSX-native driver support is still lacking for many devices, I decided to first find a working OSX webcam driver and see what cameras it supported, rather than the other way around.

Matthias Krauss' macam is an excellent, free USB webcam driver that currently supports about a dozen different cameras which he lists on his site. Armed with the list, I went to a local computer superstore to see what I could find. By now, it should be apparent that this project was more of the 'weekend' variety than one that was methodically planned and researched!

As it happens, the ONLY camera that I could find on the list was the Logitech QuickCam Express. It's a small, ball-shaped camera that sits on a
triangular base. (It resembles the original Connectix QuickCam that early Mac users may remember, except that it now has a USB connection) The macam author warns that Logitech apparently makes several different versions of this product, not all of which work properly with his driver. To further complicate things, there doesn't appear to be a definite way to tell the difference.

I bought the QuickCam Express anyway and it worked fine. If you decide to take the same gamble, you might want to check the store's return policy ahead of time. Here's some info about the unit I got:

Logitech QuickCam Express - UPC code: QC-XPRS US 961183-0403 / 9785501198

A few comments about the macam driver: The current version of macam is 0.6 (as of July 2002), but I'm using a beta version 0.71 which supposedly has better support for the QuickCam Express. Both versions are available for download at the macam site. What I find really neat is that most hardware device drivers traditionally affect an OS at a fairly deep level. The macam driver is written as a QuickTime component. What this means is that the driver installs easily (just copy it to /Library/QuickTime), much like how you'd install an a 3rd party software codec. Equally important, this implies that the driver runs entirely in userspace and doesn't offer the potential risk of crashing your system the way traditional device drivers might.

Once the macam driver is installed, it will work with any app that looks for a standard QuickTime VDIG source. The macam package thoughtfully includes an app that allows you to quickly determine if the camera and driver are working properly. If you only want to use the webcam with GUI-type apps (see References for a list), this is as far as you need to go. However, the goal was to figure out a way to capture an image from the terminal, so we'll next look at VideoScript.

The second important discovery was a package called VideoScript, which is actually a complete language for doing automated image processing. It reminds me of ImageAlchemy on the PC or NIHImage for Classic. The good news is that VideoScript runs under OSX and is able to use the VDIG input from a webcam. The main VS package runs as a GUI-based app that opens a text editor much like other development environments. Yet the real trick is a client version of VideoScript that will run scripts files from the command-line. The client version is still in beta and can be downloaded here. There are actually several versions of VideoScript offered: A free 'lite' version which I'm using, and a full-featured commercial 'pro' version. Actually, VideoScript does a lot much more than the simple image captures described here. I encourage anyone interested to take a look at the company's site which has downloadable documentation and an online language reference. There's an interesting example of how to use VideoScript to write a motion-detection routine for surveillance cameras.

Here are the VideoScript commands to take a picture from the webcam and save it somewhere:
set v to videosource;
set i to frame of v;
set window "view" to i;
set file "OSXRoot:Users:myname:Sites:webcam.jpeg" to i;
One odd feature is that even under OSX, VideoScript still uses traditional Mac-style pathnames like 'MyHD:subdir1:subdir2:file' instead of '/Volumes/MyHD/subdir1/subdir2/file'.

You can enter and run these instructions right from the main window of the VideoScript app or you can save them text file that and tell the command-line client to run it from the terminal. Thus, if you saved the preceding code snippet to a file called watchit.vs, from the
terminal you could:
videoscript -f watchit.vs
which would grab a picture and save it to /Users/myname/Sites/webcam.jpeg. If you had webserving enabled on this machine, you could even view the captured image elsewhere from a browser (i.e 'http://my-webcam-address/~myname/webcam.jpeg'). Naturally, this works equally well from a local terminal window or from a remote session via SSH.

  • The 'lite' version of VideoScript only saves JPGs at a 50% quality factor. Still, considering the relatively poor image quality of most cheap webcams, this isn't a big issue. The pro version of VideoScript allows you to specify the quality factor.

  • The GUI-based VideoScript app creates and saves Mac-style text files. The client version will read either Mac (CR) or Unix (LF) style files. I prefer to use the Unix-style which allows me to make quick, on-the-fly tweaks with vi or pico. From the shell, an easy way to convert Mac to Unix text files is cat mymacfile.txt | tr \\r \\n > myunixfile.txt

  • The VideoScript example shown earlier just grabs a raw picture from the webcam. You can tweak the image a bit with VideoScript's image-processing commands such as:
    set v to videosource;
    set i to frame of v;

    set brightness of v to 0.65;
    set contrast of v to 0.85;
    set gamma of v to 0.9;

    set window "view" to i;
    set file "OSXRoot:Users:myname:Sites:webcam.jpeg" to i;
    Consult the VideoScript documentation for more parameters and details.

  • An obvious next step would be to add a date/time stamp to the captured image. VideoScript has the ability to overlay text by means of a plugin extension module, except that plugin support appears to be broken in the command-line client version! So while the following works just fine when run from the full VideoScript app:
    set v to videosource;
    set i to frame of v;
    set window "view" to i;

    set now to date as text;
    Draw.Text(&i,5,5,"MyCam - "+now,
    obj_color->{1,1,1} as color);

    set file "OSXRoot:Users:myname:Sites:webcam.jpeg" to i;
    It DOESN'T work when run from the command-line client. However, the app is free and listed as a beta, so I really can't complain too much.

  • If you're thinking of using atrun or cron to do a timed-webcam, you're are probably just as well off using one of the
    GUI-based apps.

  • This method may seem like a lot of extra work when one could easily use TB2, ARD or VNC to do a remote login with and control a regular webcam app. While this is true, I prefer this way because it allows me to do remote monitoring using only a plain terminal session, even over a relatively slow link.
  • If your webcam manufacturer doesn't provide OSX drivers and freeware efforts (such as macam) doesn't support your model, you might check with companies such as IOXperts who do commercial OSX driver development for various 3rd party webcams.

  • For a basic app to test your camera with (it doesn't do automated image capture, etc), you might try the carbonized version of Apple's venerable HackTV or the nice freeware app Video Viewer

  • For full-featured GUI-based webcam apps, you might look at MWebCam, BTV or see what places like VersionTracker lists.
  • Currently 1.00 / 5
  • 1
  • 2
  • 3
  • 4
  • 5
  (2 votes cast)

Use a webcam from the terminal | 5 comments | Create New Account
Click here to return to the 'Use a webcam from the terminal' hint
The following comments are owned by whoever posted them. This site is not responsible for what they say.
It works!
Authored by: mschaff on Aug 20, '02 01:01:56PM

I got a free "PC-only" QuickCam Express from Verizon when I signed up for DSL. It was worthless until I tried this hint. While the mcam and VideoScript commandline drivers are still a little buggy (both beta), they do work pretty well.

Does anyone know if it is possible to grab shots from the camera when nobody is logged in (i.e. sitting at the OS X login screen)?

Also, I made a shell script to grab the current image and ran it as a cgi. It doesn't seem to update the image (although it does correctly generate the html) when accessed via a web page, but it does update the image if I run it on the command line...Any guesses why this doesn't work properly? Is it because Apache is running as "nobody"?

[ Reply to This | # ]
It works!
Authored by: r2d2mac on Aug 20, '02 08:02:04PM
it probably is the nobody problem. check the rights of the folder in which you save the image
# ls -la /webcam/image/folder
If security is not an issue on that mac, and you want to make things easy, just make sure that it is read-writeable to all users...

# sudo chmod o+rw /webcam/image/folder
(make sure all the folders above have the 'x' bit on for others).

Also, if you currently launch the videoscript command line tool as a command (just the name), try launching it with the full path to it (e.g. /usr/bin/videoscript -f ....).

good luck

[ Reply to This | # ]
It works! (eh, kinda)
Authored by: sgecko on Apr 04, '03 04:57:22PM
I've been trying out this hint, and have run across a couple of different results, neither of which is the one I want.

The first is if I'm at home, sitting at my machine and run the command line, I get an all black .jpg file with white text that says "USB Connection Error" on it. No picture at all. I had an IOX driver installed, and thought it was that conflicting with macam, so removed it (IOX) but still get the error. The camera (Logitech Pro 3000) works fine with macam's gui app. Though, I also get USB Connection Errors every once in awhile through that, as well (USB ports shot?).

When I try to run the script from a command line remotely (at work, for instance) I get the following error:

KCGErrorIllegalArgument : initCGDisplayState: cannot map display interlocks.
KCGEErrorIllegalArgument : CGSGetDisplayBounds (display 0)
Those are followed by a message that says the script compiled fine, and then it just hangs. I have to Ctrl-Z to suspend the process and then kill it.

I'm still hacking away at it, and will post any results I come up with. Just thought I'd share my experience.

[ Reply to This | # ]

It works! (eh, kinda)
Authored by: osxpounder on May 23, '03 11:06:30AM

sgecko, did you ever find a solution to this? The same things happened to me, too, on two freshly set up 10.2.5 boxes. My main box will let me run VNC remotely, but not these two other boxes, and all have the same OS version.

Could it be that I'm an admin user on my box, but only a regular joe-user without admin rights is logged in on these two problem boxes?


[ Reply to This | # ]
It works!
Authored by: Engelx on Jan 02, '04 06:05:58PM

holy shit
i cant do it...
i need some help.. please email me... this shitty cam crashes all my apps.. i have 10.3 OS so i think this is the problem
even on vpc crashes when i try to use the cam... first was so so .. now it crash...

on system profiler appears an attached cam on usb port... so i dunno what is it..

[ Reply to This | # ]