All downloads and project-version information can be found on the sourceforge project page, here [sourceforge.net].README.txt
DISCLAIMER (READ FIRST!) ------------------------ I, the author, am not responsible for any damages that running, using, or even downloading this program incurs. If your toaster explodes killing your dog, that's real tough luck, and i'm simply not repsonsible. By downloading this program you agree to read this file first; by reading this file you agree to be bound by the terms outlined in this paragraph before you use the program; by using this program you free me of any liability towards you, the user. License-wise this software is protected by the GNU Public License (GPL), see LICENSE.txt for more information. I am in no way affiliated with webcamXP, webcamXP-PRO, tanukisoftware; these are names copyrighted and trademarked by their respective owners. WTF IS wxpRelay ?! ------------------ Good question. Brief terminology: - the "cam PC" is the computer that has the webcam attached to it with a legal version of webcamXP-PRO (or any program that serves a series of JPGs on a given port in HTTP) - the "server PC" is a computer that is either connected directly to the internet (not behind a hardware firewall/router of any sort), or is behind a firewall/router that you have administrative access to. wxpRelay is for anyone who doesn't have control of the router that their cam PC is behind, but who do have control of another computer that fits the description of the server PC. Say you have a laptop with a webcam, and you go off for a vacation in New Brunswick to the town of Fredericton, where there is bountiful free wireless internet. You could easily run webCamXP on your laptop and have it upload pictures to your website via HTTP POST or FTP, no problemo. But, if you wanted to allow people to see live video, how would you do it? You don't have access to the City of Fredericton's wireless routers, so you can't forward any ports through to you -- no one can make an incoming connection to you, your laptop has to make the outgoing connection first. That's where wxpRelay comes in; wxpRelay allows you to have incoming connections for video even in situations like the above. One of the really useful features of wxpRelay is that all bandwidth is used at the server, ie. if three people are requesting video all at the same time when wxpRelay is being used, the video is replicated on the server PC, so only one connection to the cam PC is ever used. This is good because if the cam PC is wirelessly roaming as above, it'll probably have reduced bandwidth so you don't want any more than 1 stream of video emanating from it. REQUIREMENTS ------------ - a webcam program that provides quickly changing jpgs and has its own web-server; webcamXP is recommended but many programs do this - Java. I use J2SE 5.0 update 1 but only JRE 1.2 is required; see the how to run section for more info if you don't understand what I mean. The class files the package comes with have been compiled with backwards compatibility for Java JRE 1.2, so you don't have to upgrade on my behalf. HOW DOES wxpRelay WORK? ----------------------- wxpRelay is comprised of three parts: 1. the HttpServer, which runs on the server PC 2. the ControlServer, which runs on the server PC 3. the client, which runs on the cam/client PC These roles are described as follows: - the HttpServer takes incoming requests from the internet when Joe Schmoe says "gimme your video feed" by using his browser (Internet Explorer, Firefix, etc), and gives back a series of JPGs that create video. This is pretty much exactly the same thing that webCamXP PRO's web-server does. By default the HttpServer runs on port 8080 (just like webCamXP PRO's web-server does), but you can change this (read on) - the ControlServer receives the stream of JPGs directly from the client, and brokers them to the HttpServer. As mentioned earlier, there's only ever one stream of video going from the client to the ControlServer - the client sits on the cam PC, repeatedly grabbing pictures from webCamXP-PRO's internal server, and sending them to the ControlServer. Now for some nitty gritty details; let's talk about a request for video from the internet and how things happen. First, even before the request, the server and client get started up. When the server starts, it starts the ControlServer and HttpServer, each listening on a separate port. The HttpServer will take an incoming HTTP request, and give back a JPG: if the client hasn't connected yet then it'll send the offline jpg; if the client is connected it'll first send the loading jpg and then start sending live jpgs. It does this by telling the ControlServer that someone is requesting video, so the ControlServer tells the client to start sending jpgs. Since there's no way with HTTP to know when people have stopped requesting video, there's a timer that goes off every 5 seconds; if it detects that no one has requested a jpg in that time it sets the state as unrequested, which means that the ControlServer drops the connection to the client. The client will immediately reconnect. If at any point something goes wrong (say the cam PC is a laptop and loses WiFi connectivity), then the ControlServer goes back to waiting for a connection, and the client tries to initiate an outgoing connection to the ControlServer every 60 seconds. LIMITATIONS ----------- The HttpServer is not a real HTTP server. It only sends jpgs, it doesn't actually understand the HTTP protocol -- it doesn't even bother understanding the HTTP text that a web-browser sends it. You have to use wxpRelay with a webcam program that has its own HTTP server built-in, and serves up jpgs (not some other kind of video like MPEG video or whatever). I use webcamXP-PRO, a fantastic program you can try/buy from http://www.webcamxp.com No sound - wxpRelay doesn't do audio of any sort. Maybe in a later version if enough people request it. HOW TO RUN / USE ---------------- PART A: GETTING JAVA First, if you don't hava Java, get Sun's implementation of Java. A quick explanation of terms that Sun uses: - J2SE - the Java 2 Standard Edition, which is what you want. Ignore the '2'. - JRE - Java Runtime Environment - A distribution of the J2SE, this is what you want if you're running compiled java code, not compiling your own. So, if you're just using wxpRelay but not making any changes to the .java files, then this is the one for you. - JDK - Java Development Kit - A distribution of the J2SE, this is what you want if you're compiling any java code, like changing wxpRelay's .java files. Note that the JDK contains the JRE so you don't need both. So, go grab the newest version of the JRE or JDK as you see fit, which are free from http://java.sun.com . Install it as per Sun's instructions, and then make sure it's in the path; to test this start a command prompt in Windows or a shell in Linux, and type "java". If you get java's cmd-line options, you have it in the path. Note that versions before 1.5 (aka 5.0) of Java didn't add themselves to the path, but it seems like 1.5 (aka 5.) does, nice. PART B: RUNNING wxpRelay **IMPORTANT: READ THIS BEFORE ATTEMPTING TO RUN wxpRelay!** There are two ways to run wxpRelay: from the cmd-line, or as a Windows service. The latter is accomplished by using "Wrapper", an open-source program found here: http://wrapper.tanukisoftware.org I have spent painstaking hours setting up wrapper for you. Granted it should have been easy but I made a stupid mistake and it took ages to figure out how to configure it properly :) Needless to say, it's all done for you. So, here's how you do either: 1) RUNNING wxpRelay FROM THE CMD-LINE I'm guessing that the majority of you aren't familiar with Java, so i've created batch and shell files you can run. You absolutely must run them from the directory they are in (this must be their "start dir"), and they assume that the executable "java" is in the path. If you're in Windows you can type either: CMD-LINE: STARTING THE CLIENT startClient.bat myhost.dyndns.org 8071 true localhost:8080 ... where: myhost.dyndns.org is the IP of the Server (computer w/ Control+HtppServers) 8071 is the ControlServer port (chosen when you start the Server) true is the debugging level, either "true" or "false"; false will report only errors and serious things that go wrong, true gives enough to debug localhost:8080 is the IP and port (must be in IP:port form) of the webCamXP or other JPG-serving webcam HTTP server. Note that you could have this residing on a machine other than where the Client runs, but I don't see why you'd want to do this. CMD-LINE: STARTING THE SERVER (ControlServer, HttpServer, all Server components) startServer.bat 8070 8071 true ... where: 8070 is the port the HttpServer listens on, ie. where you're going to direct incoming requests from the internet to (you are choosing it here) 8071 is the ControlServer port (you are choosing it here) true is the debugging level, as explained above If you're in Linux (java must still be in the path!), then the commands are exactly the same, except replace .bat with .sh By default the output of wxpRelay is to standard output (stdout); if you want this to go to a file "wxpOutput.txt", overwrite Logger.java with Logger.java.toFile and re- compile. 2) USING WRAPPER TO RUN wxpRelay AS A WINDOWS SERVICE ** If you use this, please consider a donation to the Wrapper project! See http://wrapper.tanukisoftware.org for details. Note that this probably requires Windows NT/2000/XP/2003 or newer. I recommend you get things working from the cmd-line first! Then try the service... - First you have to configure the settings properly. Go into the conf/ directory, and you'll find two files, one obviously for the server, the other for the client. Open the appropriate one in a text-editor, and find the clearly spaced section that has # wxpRelay users ... ... as the comment. You need to set the options here; they are exactly the same as the options when you run wxpRelay from the cmd-line, so refer above to see what all the parameters are/do. - Next you need to install the service itself. Go into the bin/ directory and execute the appropriate Install-wxpRelay-service-* batch file. That'll make your service. - Now you can try starting the service. In Windows XP (and possibly 2k?) go start, run, and type in "services.msc". Up pops the services window. Start up the service you've just installed, which will be wxpRelay(client or server). The output is going to logs/wrapper.log ! If things start going wrong, that's where to look. An important note: should you want to change the files in conf/ and you've already installed the service(s), it is VITAL that you uninstall the service(s) first BEFORE modifying the conf files! To do this, use the Uninstall-wxpRelay-service-* batch files. After you've uninstalled the service(s) you can modify the conf/ files, and reinstall if desired. Don't pester me with wxpRelay-running-as-a-windows-service problems, it'll be a Wrapper related issue. You can check their website for help (address above). PART C: TRYING IT OUT! So you've got the client hooked up with webcamXP on one computer and the server running on another, and you want to try it out? I've included a modified version of an HTML file that webcamXP comes with, which you can use as a starting point. It's in the resources/ directory and it's called wxpRelaySampleHTML.html, and you need to change one thing in it. Change the localhost:8070 part on this line: var wxpHost = "http://localhost:8070/"; ... to reflect the Server IP:port of the machine the Server is running on. Then, try loading this up in your browser, from any machine you want. If everything works you should see some jpg-video ! If not take a look at the output from the Client and Server, and see if you can spot anything you missed. You can use the jpg stream any way you see fit. One way (like the sample html talked about above) has an HTML file repeatedly pulling jpg data, another would be to write your own front-end that uses HTTP to grab the jpgs whenever you need; this method is simpler than it sounds, because the HttpServer isn't actually doing real HTTP, it's sending the same jpg response every time (see limitations section for more details). Experiment! CONFIGURABLE THINGS (COMPILE-TIME SETTINGS) ------------------------------------------- There are a few things that are configurable other than the options taken as runtime parameters (see how to run section). They are broken up into the files they are found in. Note that if you change any of 'em, you've gotta recompile (out of scope of this document) ControlServer.java: public final static long CAM_TIMEOUT_MILLIS = 5000; This is the timeout in milliseconds after the last person requests a jpg from the HttpServer that the system drops the connection to the client (stops receiving jpgs) public final static int KEEPALIVE_TIMEOUT = 5; The number of seconds until a keepalive packet is sent from the ControlServer to the client, to make sure the connection isn't dropped public final static int MAX_JPG_SIZE = 20000; This is the largest size jpg that the system will deal with. There is about 1k of overhead, so add 1k to what you'd put here. My webcam using webcamXP-PRO takes jpgs that are about 10k or less in size, so 20k is a safe setting. The only benefit of setting this as low as possible is a slight memory efficiency (only 3 or 4 times this amount are ever allocated simultaneously). Messages.java: public static final int BUFFER_SIZE = 1024; This is the amount of data that's sent in a single TCP packet from the client to the ControlServer or from the HttpServer to someone's browser. ClientMain.java: public static final int RANDOM_SEED = 12745; A seed for the random number generator, no need to change this public static final int ERROR_THRESHOLD = 10; The number of socket recv/send errors before dropping the connection By default the output of wxpRelay is to standard output (stdout); if you want this to go to a file "wxpOutput.txt", overwrite Logger.java with Logger.java.toFile and re- compile. DONATIONS --------- If you find this software useful, feel free to make a donation to help me pay off my student loans. If you're a student, I forbid you from doing so :) Any size donation is welcome and appreciated! You can donate to me using PayPal, my email/userid is email@example.com (note the double-underscore). Or, you can find a link to do so directly from my website on the USB keyfob page: http://fuzzymunchkin.dyndns.org/tdot/usbkeyfob/index.php3 Thanks! TROUBLESHOOTING --------------- Q: On Windows, why do I get "Address already in use: connect" and/or "received was <=0 (end of stream) in receiveString()" ? A: Because you are probably using the program on a LAN, and getting very fast speeds; this uses ports faster than Windows can handle. Windows will be using ephemeral ports (temp ones) between 1024-5000, and those ports have a default timeout after they are closed of 4 minutes; therefore if you exhaust those ~4k ports in < 4 minutes (very easy, I do so on my Windows machine in <1min!) then you start getting these errors. The solution, if necessary for further testing on the LAN, is to either change what constitutes an ephemeral port, or making the timeout shorter. For testing purposes I set the timeout on my Windows XP computer to 30 seconds, and this problem was fixed. You can find out how to do those things here: http://support.microsoft.com/default.aspx?scid=kb;EN-US;196271 http://support.microsoft.com/kb/149532/EN-US/ Q: I get the same picture again and again / the video isn't changing A: Probably because webcamXP has gone wrong. Ensure that your cam is properly connected to webcamXP; try restarting webcamXP. For example, disconnecting your cam and reconnecting it will cause this to happen on my version of webcamXP Q: Help ! It just doesn't work for me ! A: You can try emailing me. Remember to include all the relevant info, such as version of webcamXP or other program, the logs of wxpRelay (have it write to wxpOutput.txt and send me that), the detailed explanation of what you think should happen that doesn't, or what is happening that shouldn't, etc. My address is rush2112 at gmail DDDDOT com.
Excellent! Please do as many of the following as you wish: