mod_video was created in order for me to be able to check on my apartment while on holiday using a camcorder hooked up to my Linux machine.

A few months earlier I had picked up a BTTV-based (Bt848) frame grabber card from the leftovers bin, and although I was able to make it work I can't say that it was very impressive. The software that came with it just locked up my machine under Windows, and the software available under Linux wasn't too hot either. The image quality can at best be described as questionable.

The module was written the night before I was leaving for my holiday, and being the first time I had used the video4linux API, I had to pick apart a few programs written by other people in order to figure out how to make things work. The documentation I was able to find on the net didn't really answer all my questions and at times it was just confusing.

I hadn't written anything that encodes JPG or PNG images before either, so I had to figure out how libpng and libjpeg work as well. Hopefully I didn't screw up too badly.

Hopefully some of you might be able to help develop this module furter so it can be useful to more people. Please see the section on contributing for more information.




The module was developed and tested on a machine running Apache 2.0.52 under Linux 2.6.12 with modules se401, ov411 and compiled-in support for BT848 cards. It uses the video4linux API in order to perform the actual grabbing, and since I have very little experience with frame-grabbing software I have no idea if it will work with various cards.

In order to compile and link the module you need to install the following libraries in a place where the C-preprocessor and linker can find them:

Compiling Apache with the module

Start by downloading and unpacking the latest Apache 1.3 source. Unpack it the usual way:
  tar xvfz apache_1.3.11.tar.gz
  cd cd apache_1.3.11
Now there are two ways you can build Apache with the video module.

The first way we describe is the one you might want to use the first time you try out the module.

  ./configure --add-module=/path/to/mod_video.c 
  make install
This will copy your module to the src/modules/extra directory, build the Apache webserver with the video module and install it. (Be sure to specify a proper --prefix argument to configure so your server will be installed where you want it).

The second way you can build mod_video assumes that you have already copied mod_video.c to src/modules/extra (which --add-module will do) , and is well suited if you want to run configure again later to change some of the other parameters.

  ./configure --activate-module=src/modules/extra/mod_video.c
  make install

Actually, I usually skip the make install command and copy the httpd binary directly to its target dir to avoid messing up what else is there. (Be sure to stop Apache before attempting to overwrite the old binary).

Installing as a DSO

You can also install mod_video as a DSO by using apxs. This is the easiest method to get the module installed. Note that this requires you to install Apache first so that apxs will work:
  apxs -i -a -c -l png -l jpeg -l z mod_video.c

Many thanks to David E. Weekly for this tip

Configuring the module

The video module is a handler, so the way to set it up is to configure it to use a Location section in the Apache configuration file. Here's an example:
  LoadModule video_module modules/
  <Location /camera>
     SetHandler   mod_video
     video_device /dev/video
     video_format jpeg
     video_input  0 
     video_width  640
     video_height 480
     video_jpeg_quality 90
     video_unavailable_image /var/www/html/images/videoSourceUnavail.jpg
     video_palette 4

The configuration commands available are:

video_device device-name
Chooses the video device to be used

video_format (jpeg|png|raw)
The format used for sending the image to the client

video_input video-input
Selects the video channel (see video4linux docs)

video_width width in pixels
Determines the width of the image

video_height height in pixels
Determines the height of the image

video_jpeg_quality number
The JPEG quality used when encoding JPEGS

video_unavailable_image file path
An image file to be sent when the video device is not available. Needs to be readable by the apache user.

video_palette number
Sets the pallet of the video device. Right now all image functions only work with rgb.


As I mentioned earlier, the current implementation was something I hacked up rather quickly in order to be able to grab pictures from a video camera, and since I have no prior experience with writing frame-grabbing software the implementation probably leaves a lot to be desired.

This is where you come into the picture. If you can contribute anything to this module, please do. The more configurations it can be made to work with the more useful it will be for all of us. If you make improvements to this module please share them with me so I can put them back into the module.

Some of the things that I am interested in are:

Support for more hardware

Right now it works with the hardware I had available: an old BT848 frame grabber that I found in the leftovers bin. There are probably more interesting frame-grabbers available for Linux, as well as for other hardware platforms.

Better configurability

I didn't try to play with the tuner since I have no antenna or cable connected to my computer, so the options for selecting the input is rather limited at this time. It would be great if the module could be made to support this, as well as having the option of grabbing from several sources with one frame-grabber.

Better image encoding support

My knowledge of the JPEG and PNG libraries is somewhat limited. I am sure the use of this libraries can be optimized a lot. For instance there should be a way around temporary files for JPEG (...other than the ugly hack I tried by having the library write directly to the client connection).

Also, it would be interesting to explore the possiblily of streaming video by sending the client a row of frames much like the fish-tank demo Netscape had a few years ago. Then again, for streaming video you probably want to use a different system architecture.


mod_video is released under the GNU General Public License, version 2. The reason for choosing this license is that I'd like to see this module evolve into something useful.


The source code can be downloaded here


People participating in this project (not complete):

Other sites where this project is entered

Bjorn Borud, <>