First, make sure the various modules for your TV grabber and/or webcams are loaded if necessary. Then start camstream from the command line, or add it to your menu or desktop.
Camstream first scans the available video devices (but does not open them), and starts with the main window. Camstream has a MDI (Multiple Document Interface): it shows everything in subwindows of the main window. Initially, the main window is empty, except for the menubar and a nice filler background.
You can resize the main window by grabbing one of the sides or corners with your mouse and drag it to the desired size.
There can be several types of windows displayed in CamStream. For now, there is only one type available: a Viewer.
The main menu has only two menus, which are discussed here briefly:
In order to see something, you must open a Viewer. A Viewer is just what
it name implies: a window that displays the image stream from a live video
source like a webcam or TV card.
To open a viewer, hit Ctrl-O or use the menu
. You will then see the
dialog on the left.
You can select a video device from the drop down list, and the initial size that you want to use. The device is identified either by its name or the device node. If you don't specify a size, the current size of the device will be used (whatever that is...).
(Never mind the odd colours: this is my default colour palette. CamStream will use your system palette.)
Once you have selected a device from the list, click the
This is a snapshot of CamStream with a viewer from my TV card (the black bands above and below the image are intentional, it's a widescreen transmission). As you can see the viewer is a subwindow of the main window with its own minimize, maximize and close buttons.
Although the window has a resize handle in the lower-right corner, you cannot change the image size this way. You must use the settings dialog, activated by the button on the toolbar.
Each viewer has its own toolbar (displayed at the top) and a statusbar. You can drag the toolbar around and dock it to any of the 4 sides. The titlebar of the window displays the name of the device (in this case that of my TV card).
The statusbar has only one item: a time field which shows a count down during timed snapshots. When not in use, it shows "--:--".
If you want, you can open multiple Viewers and display the results simultaneously, like this:
In fact, you can open the same device more than once! Not that it's very useful, but it's a nice demonstration of what you can do with C++ and a little bit of designing :) The devices are not completely independant, though. Changing the size of one viewer will change the size of the others too.
You can do the usual stuff with these windows: move them, hide them, etc. The
menu has a and a option, which will re-arrange the windows.Each window has its own toolbar, which is shown enlarged below:
The toolbar has 6 buttons, which are described here from left to right:
The right button of this pair (with the clock symbol) starts timed
snapshots; it will take a snapshot at regular intervals. By clicking
the button you will get this small dialog:
The maximum interval is either 60 seconds or minutes. When you click
on the interval starts. In the statusbar
you will see the remaining time countdown until the next snapshot.
You can alway click the left snapshot button to make an immediate snapshot, whether or not the timer is active.
The timer is stopped by clicking the timed snapshot button again (it remains depressed during timed snapshot mode).
You can drag the toolbar around to any of the 4 docking positions (top, left, bottom, right). The window-size will be adjusted according (Note: the docking position isn't saved yet).
This is actually a collection of dialogs, arranged as a tab-dialog. It is used for setting various parameters of the video device you are watching. The most common settings are image size, brightness, contrast, etc.
The tab-dialog consists of either 3 or 4 subdialogs. The 4th dialog is specific for the Philips USB webcams and is hidden for other types of cameras. The subdialogs are now described one by one.
In here you can select the desired image size, ranging from a stamp-sized 128x96 subQCIF to 640x480 VGA or even more, provided the video device supports this resolution of course. If a size from the list is not supported by the device, its radiobutton is disabled (grayed out).
The framerate only really applies to webcams that have such a setting (like the Philips cams). With other webcams that do no support this, this setting has no effect. This feature is simulated with TV cards (which have only one framerate: 50 resp. 59.97 Hz) by using a timer.
This is where you can manipulate the brightness, contrast, gamma (or 'whiteness') and colour (or 'saturation') settings. Not all cams support all settings, so don't be surprised if moving one of the sliders don't have any effect. Also, some settings cannot be set at all; in that case the slider will be disabled.
Nearly all devices have brightness and contrast, but the situation with gamma and colour is a bit more difficult. Originally, the V4L API defined a whiteness settings for black-and-white cameras only; but this doesn't really make sense and since the Philips cams do have a gamma parameter, I (ab)used that one.
Something similar is true for the colour setting; sometimes it modifies the hue parameter (probably affecting the PAL/NTSC decoder), and for other devices it tells how strong the colours should look: moving the slider to the left will produce black-and-white images, and to the right sickly-saturated images.
To make a long story short: there are 4 sliders, and only the first 2 have a fixed meaning; the other 2 depend a bit on the underlying hardware.
TV cards often have multiple inputs and a tuner, in contrast to webcams. This dialogs allows you to select an input and, if available, a tuner.
On the left, you see a list of available inputs. This list is queried from the device and build dynamicly; webcams usually have only one (simulated) input.
Inputs can have tuners attached to them; in theory more than one, but I have yet to see a card that has more than one. Nevertheless CamStream support a maximum of 3 tuners per input. Again the number of tuners is determined dynamicly when an input is selected. If no tuners are attached to the input, the right half of the dialog disappears.
The following section is not finished yet, and will probably be redesigned anyhow.
Finally, there's the frequency slider. Its resolution is quite coarse; it has to span a frequency range of 47 to 870 MHz with a single slider. A better approach would be to have a list of channel frequency with names (it's on my TODO list) and a fine-tuner. Right now, consider this an unfinished feature (enhancements in the form of patches are welcome :)).
Note: until you set something, the dialog looks quite uninitialized. This is because the V4L API misses some important calls to query the current state of the device, like which input is currently selected.
The name says it all: these are proprietary exensions of the Philips webcam driver; they simply did not fit into the existing V4L API or don't have an equivalent function. The full extension is described on the API for Philips webcams page.
This dialog or rather complex, but there are many features in the cam, so please bear with me.
The first box ("Exposure") contains settings that have to do with how the camera handles the lighting from the scene. AGC and Shutter have the most profound effect. They are primarely here upon request of amateur astronomers that wanted to put the high sensitivity of the CCD element to good use on their nightly hunt for planets, stars and comets.
AGC is the automatic gain control of the camera; it tells how much the (analog) signal from the sensor is being amplified or attenuated to compensate for dark/bright scenes. The Shutter slider indicates how long the senser should collect light before handing over the image to the internal processor. Note: despite claims made by some, I don't think it's possible to set the shutter to anything longer than 0.2 second.
Contour performs filtering on the image: a low value will soften the image somewhat, a high value will sharpen the edge. Note: this a software enhancement, not a real focus.
The checkboxes before the three sliders enable auto mode (the usual mode for the webcams). When auto mode is on, the AGC slider is used as an indicator and moves around according to the value reported by the cam (for example, turn on the AGC auto mode and cover the lens of the webcam with your hand; the cam will try to compensate for the darkness by increasing the AGC value and the slider will move to the right). In non-auto mode, you can move the sliders around yourself for some interesting experiments.
On the right hand side is the White balance box. Depending
on the time of day or illuminatiuon, the colors can look 'wrong'. The camera
can compensate automatically, but you can also set the values manually or
use on of the presets. The dials either show the automatic values, or you can
turn them manually. Play with them to see all colors of the rainbow :-)
The two sliders Speed and Delay determine how fast the camera
reacts to changing color conditions.
Noise reduction should be fairly obvious.
Preferred compression is not really a feature of the webcam itself, but something I built into the driver myself. The webcam uses compression; the rate is variable, and I though it might be a good idea to be able to choose between low or no compression to reduce any possible artefacts in the images, and high compression to conserve bandwidth on the USB bus.
The 3 buttons at the bottom are for saving or restoring the settings into a little EEPROM (Erasble EPROM) in the camera permanently, without requiring electricity.
stores the current brightness, contrast, etc. settings into the EEPROM; these values will then be restored when you plug the camera back in next time. retrieves these settings now, should you have messed up the controls in the "Video Controls" panel. resets all settings to a set of preprogrammed, fail-safe defaults.
This elongated dialog controls just about anything you want to do with
snapshots you take from a video device. From top to bottom:
Select the image format you want to use for saving images. This list is dynamicly queried at startup; if PNG and/or JPEG is missing, you may want to recompile the Qt library (see the Installation instructions).
Put timestamp in image will print the time and date the snapshot was taken into the image before saving. Use the two buttons to select a font and color with which to paint this timestamp. The timestamp is always printed at the bottom of the image.
The 3rd input and 4th input item determine the name of the file that will be written or FTP'd. The Basename is the first part of the filename, the second part can be one of three things:
Once you have determined how the file is going to be named, you must determine what you want to do with it. You can save it to disk, FTP it to a server, or do both (or neither, which is rather pointless :-)). So check at least one of the two checkboxes.
The save to disk option just dumps the file in your current
working directory; FTP to server enables the FTP option. By clicking
on the
This is a simple sub-dialog where you can specify where you want your images
uploaded; I think they are pretty straightforward. In the Path
entry specicy a directory on the server, not a complete filename.
In case you're behind a firewall or your FTP server is braindead (or both) you can use Passive FTP to upload images.
Upload unique is not implemented yet. (I know, I should
just remove the option, but...)
The configuration is saved as an XML file in your homedirectory, with the
name .camstream. This in itself isn't very
interesting, but in case of trouble you know where to look.
What's more interesting to know is that each device has its own
configuration. If you have 2 (different) webcams, the configuration of each
webcam is stored, including all the snapshot settings. Next time you
start the program the settings are sought with the device, even if they
have a different device node (which can happen in the case of hot-pluggable
devices like USB webcams). Only if you have 2 exactly the same devices this
logic may fail.
The file contains your FTP passwords un-encrypted or un-scrambled, so
CamStream writes the file away with mode 0600, so only your user ID may read
or write the file.