1camserv - A streaming camera server.
2Copyright (C) 1999-2002 Jon Travis
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
17
18
19-------------------------------------------------------------
20
21Now that all that stuff is out of the way. Welcome to one of my baby
22projects -- a streaming webcam server. The idea behind this project is to
23allow as many people as possible (with all kinds of different cameras and
24platforms) to be able to stream their webcam pictures on the web.
25
26
27==============
28What you need:
29==============
30
311) If you want to run the camera server program:
32 You must either be running on a Linux system with a supported
33 Video4Linux device (and have the correct kernel setup)
34 See: http://roadrunner.swansea.linux.org.uk/v4l.shtml
35
36 Or you must be running on FreeBSD with a bttv card installed.
37 (NetBSD, and BSDi 4.0 have also been reported to work well)
38
39 You can also use the video_basic module for pretty much any UNIX,
40 however this module is mostly for demonstration of how to port
41 video drivers.
42
43 In addition you will need a rather recent version of the libjpeg
44 library.
45
46 Most Redhat distributions should be fine.
47
482) If you only want to function as a relay:
49 This should be able to compile on most unices, with solely this
50 package.
51
52==============
53Setup:
54==============
55
561) To use the camserv software:
57
58 o Configure and build the system. You should be able to type
59 ./configure in the toplevel camserv directory, and have it build
60 just fine.
61
62 o Next type `make install`. If you did not use any flags to the configure
63 program, it should default to installing everything in /usr/local/bin,
64 /usr/local/lib, and /usr/local/share. If not, it will install where
65 you told it to.
66
67 -- Important notes:
68 Installed in /usr/local/lib are the filters and the video server
69 libraries that the camserv uses.
70
71 Installed in /usr/local/bin is the camera server binary
72
73 Installed in /usr/local/share is the default camserv.cfg configuration
74 file.
75
76
77 o Setup a web page to reference the camera. Any web page should work fine.
78 You will need to add an image reference of the form:
79
80 <IMG SRC=http://machinename.com:9192>
81
82 or alternatively
83
84 <IMG SRC=http://machinename.com:9192/singleframe>
85 (to only give out 1 frame, and then disconnect the client)
86
87 where machinename.com is the address of the machine running the
88 camserv software. If you change the port number in the camserv config
89 file, you must also change this HTML tag.
90
91 o Alternatively you may use the included 'javascript.txt' file which gives
92 a simple example of how to use JavaScript to make pseudo-streaming
93 JPG stream for IE users. Netscape users will be able to handle the real,
94 non-javascript streamer however (and should use this).
95
96 o Edit the camera configuration file. By default this is installed in
97 /usr/local/share/camserv.cfg. You can either edit this file, or copy
98 it to a location you prefer. There are reasonable defaults there,
99 but if you changed the default installation directories in the configure
100 script, you will need to modify paths.
101
102 o run camserv. I do NOT suggest you run this as root! Instead, chown
103 the /dev/video0 device, or whichever device you plan on using, to your
104 user name. Without any arguments, camserv will use the camserv.cfg
105 that was installed in /usr/local/share. If you use an argument it
106 will use that one instead.
107
108 o Load the web page with the <IMG> tag that you created earlier into your
109 web browser. You should see the image as seen by your camera.
110
111
1122) To use the relay software:
113
114 o Locate the port number of the remote camera server or other relay which
115 you wish to connect to. (Also the IP)
116
117 o Setup a web page similar to the camserv with an HTML tag such as:
118
119 <IMG SRC=http://machinename.com:9192>
120
121 where machinename.com is the machine runing the relay and 9192 is the
122 localport you wish to use on the relay.
123
124 o run `relay localport REMOTEIP REMOTEPORT`.
125
126 o Load the web page with the <IMG> tag you created, to test it out. The
127 remote camserv program must be running for all of this to work -- if it
128 does, you will see the image as seen by camserv.
129
130
131============
132Important information about relays
133============
134
135The relay program is a little utility to offload your camera server! This
136can be handy if:
137
138 - You want to service a LOT of people
139 - You have a wimpy connection to the internet
140 - You camera server is being masqueraded by another machine.
141
142
143The traditional webcams on the internet have the following configuration:
144
145Client0 ---------
146 \
147Client1 ----------+---- (your poor 28.8 link) [Your webserver ]
148 /
149Client2 ---------
150
151
152
153With the relay, you can offload your poor link to some other machine with
154a fast connection. Such as the following:
155
156Client0 ---
157 \
158Client1 ----+--- (beasty fat pipe ) [University] ---- (28.8) -> [ Your home ]
159 /
160Client2 ---
161
162
163This will allow you to service all of the clients that you want by really
164only sending out 1 clients worth of packets!
165
166NOTE: Relays can also be attached to other relays. Note that the latency
167 between the snapped picture and the time it arrives on the remote
168 machine will grow a lot with each relay you add. You can add as
169 many relays as you want onto any camserv.
170
171
172WARNING: If the camserv is set to braodcast at maximum frames per second,
173 this will probably saturate small connections. It would be a wise
174 thing to TWEAK the max frames per second that you send to your
175 relays. This will not flood your connection and the relays so
176 badly, and will give you a much smoother, consistent picture.
177
178============
179Modification
180============
181
182Examine the camserv.cfg configuration file to make any changes you feel
183like. It should be fairly explanitory.
184
185===================================
186MAIN PROGRAM INFORMATION && OPTIONS
187===================================
188
189The camserv.cfg file is used to configure the way camserv behaves. If
190certain options are not specified, then camserv will warn you before using its
191default values. Here are the currently supported camserv fixed sections
192and options. Note: These sections must be in camserv.cfg for it to function
193properly.
194
195
196------------------------------
197socket: The socket section is for providing information about how connection
198 making && managing should be done.
199
200Variables listen_port = The socket # that the camserv program listens on.
201 max_frames = Max frames to send to a client before
202 disconnecting them. 0 disables this functionality
203 max_bytes = Max # of bytes to send to a client before
204 disconnecting them. 0 disables this functionality
205 max_seconds = Max # of seconds to allow a client connection
206 before disconnecting them. 0 disables this
207 functionality.
208
209------------------------------
210filters: Probably one of the more interesting && useful sections of the
211 camserv configuration. The filters section allows you to setup how
212 the image should be processed before it is sent to the remote
213 client. The filters each get their chance to manipulate the image
214 before sending it on to the next filter, so the order definitely
215 matters.
216
217Variables num_filters = The number of filters that are in the filters
218 section. There should always be at least 1 filter
219 (namely the jpg_filter), for changing the image
220 from the internal RGB representation to the
221 jpg stream.
222 filter#_section = Where # is anywhere from 0-> num_filters-1,
223 this designates which filter is to be applied
224 at which stage. For instance:
225 filter0_section time_stamp
226 Will look at the [time_stamp] section of the
227 configuration file for processing the image.
228-------------------------------
229main: Provides information about how the main program should be run. This
230 affects the program as a whole
231
232Variables output_snapfile = A filename to output the image to. If this
233 option is specified, a picture will be taken,
234 placed in this file, and then camserv will
235 exit.
236 output_presnaps = A number of pictures to take before finally
237 taking the 'snapfile' snapshot. This only
238 has any meaning when output_snapfile is
239 given.
240 shm_alloc = Amount of memory to allocate for shared
241 memory. This defaults to the largest
242 potential memory that a picture may need when
243 being processed, but if you feel that you
244 can safely limit this, it is up to you.
245 ** WARNING ** -- this is dangerous to change!
246------------------------------
247
248==============================
249MODULE INFORMATION && OPTIONS
250==============================
251
252The following are flags for the different modules and filters
253that are distributed with the camserv package:
254
255
256----------------
257video_basic: This module is mostly intended to give people who want to port
258 video modules for a given interface. It currently just cycles
259 through some colours.
260
261Variables width = Width the video device should assume.
262 height = Height the video device should assume.
263
264
265----------------
266video_v4l: This module is intended for use on Linux systems with the
267 Video4Linux kernel options compiled in (and obviously some
268 imput device). This module supports both color and B&W devices.
269
270Variables: device_path = Path to the device file to use for the camera.
271 width = Requested width from the video device (can change)
272 height = Requested height from the video device (can change)
273 brightness, hue, color, contrast, whiteness: Params from 0->60000
274 port = Input port to take data from. Often cards such as
275 the bttv cards have multiple inputs such as RCA, etc.
276 frequency = On cards with a tuner, this option will set the
277 frequency that it is tuned to.
278 brightmean = When using autobright, this is the mean value of
279 a pixel that the camera attempts to attain.
280 brightx1,y1,x2,y2 = Coordinates of the region to gauge the
281 brightness measurements.
282 autobright = Autobrightness adjustment variable. A value of 0
283 disables the feature, else the value represents the
284 number of frames to wait in-between checking the
285 picture for brightness balance. When the picture is
286 checked it will be brightneed or darkened depending
287 on the pixel values & the brightmean.
288 mode = Mode for the camera to use. 0 == PAL, 1 == NTSC,
289 2 == SECAM, 3 == AUTO.
290-----------------
291video_fbsd_bttv: This module is for people with cameras attached to BTTV
292 devices under FreeBSD.
293
294Variables: device_path = Device path of the actual brooktree device.
295 Defaults to /dev/bktr0.
296 tuner_path = Path to the tuner device.
297 Defaults to /dev/tuner0
298 width,height = Requested width & height of the camera pictures.
299 port = Port number of the card input (0-4)
300 brightness = Initial brightness of the camera.
301 chroma = Initial chroma saturation axxion
302 contrast = Initial contrast of the device.
303 autobright = If 0, this functionality will be disabled. Else
304 it represents the number of frames until the
305 brightness and the contrast will be auto-adjusted.
306 channelset = Channelset to use (nabscst=1, cableirc=2,
307 cablehrc=3, weurope=4, jpnbcst=5, jpncable=6,
308 xussr=7, australia=8)
309 channel = Channel # to view
310
311-----------------
312rand_filter: A filter which should provide a basic example of how to do
313 filter programming. This one will throw random dots all over
314 the picture.
315
316Variables: num_perline = Random modifier for how many pixels to put on each
317 scanline
318 coloredpix = 1 if colored pixels are to be used, else 0.
319
320------------------
321text_filter: This filter will display text at arbitrary locations on the
322 picture.
323
324Variables: bg = Backgound color for the text. If B&W camera, then the
325 value is #cc, with a hex value representing the 'blackness'
326 of the background. If instead of #CC it is the string
327 transparent, the background will be transparent.
328 fg = Same as BG except for the foreground.
329 x,y= Pixel Coordinates to place the text bo.
330 mangle = 1 if the system should 'mangle' the text, else 0.
331 text = Text to display on the screen. If mangle == 1, then the
332 text has special metacharacters "$X", etc which are
333 replaced each time the filter is run. Currently only a
334 few metachars are supported -- (from the date command)
335 (additionally $v == the current version of camserv)
336 fontname = Font to put the text in (either 6x11 or 8x8)
337
338--------------------
339jpg_filter: Probably the most important filter, this one takes input of
340 either RGB or B&W values, and outputs a jpeg. This is generally
341 the last filter in the chain.
342
343Variable: quality = A value from 0->100 representing the quality of the
344 jpeg
345
346--------------------
347imlib2_filter: A preliminary test of this filter. This filter will take an
348 image, import it and plaster it onto the output -- It will
349 respect the alpha values, so semi-transparency can be
350 achieved. Available by CVS from enlightenment.org.
351
352Variables: file = File of the image to import
353 x = X location to place the image
354 y = Y location to place the image.
355
356---------------------
357
358
359======================
360Getting Camserv
361======================
362Camserv is currently available from:
363 http://cserv.sourceforge.net
364
365
366=======================
367Bug reports & Additions
368=======================
369
370This is a work in progress! If you have decided to make any new filters,
371video input libraries, or modifications, please send patches to me for
372inclusion into the program. If you have any bugs, please also feel free to
373send me an email. jtravis@cse.unl.edu
374
375
376
377=======================
378Mad Props:
379=======================
380
381Merc (merc1@home.com) -
382 For testing of the installation and the B&W quickcam
383 code.
384
385Kaz Kylheku (kaz@ashi.footprints.net) -
386 For not making me re-write hashing
387 and linked list code for the 3 millionth time, and
388 doing so in a free fashion.
389
390Gary Lawrence Murphy (garym@canada.com) -
391 For providing lots of ideas for the overall product,
392 patches for brightness modifications, and testing.
393
394Joerg Henne (jh@cogito.de) -
395 For patches for non-NTSC inputs as well as resource management
396 routines & single snapshot routines.
397
398Andreas Wrede (andreas@planix.com) -
399 For testing && patches for NetBSD/i386 (patches for multiple processes
400 accessing multiple cards)
401
402Scott Presnell (srp@zgi.com) -
403 Mods for {Free,Net}BSD video server code to support tuning and
404 channel sets.
405
406Torsten Mueller (archesoft@pc.mdlink.de) -
407 Javascript examples for IE users.
408
409Barak Pearlmutter (bap@cs.unm.edu) -
410 Lots of code cleanups including YUV->RGB
411
412Walter Haidinger (walter.haidinger@gmx.at) -
413 YUV->RGB as well as other patches
414
415