This is the first version of the 'ENCRE project' videochat component. It is currently in alpha stage and still lacks of tons of features but it's a good starting point for distribution developper to start interact with a red5 server, ActionScript code and the API.
This repository (on GitHub) is the reference regarding code and documentation of the videochat component.
Outside the box
This small paragraph is intented for people who are not member of the ENCRE project (a french project aimed at easing meetings). On this repository you will find a simple Red5 based video conferencing system which aims are simplicity, limited use of flash technologies and ease of integration into REST-based web applications.
This code is developped on Ubuntu and Debian systems so most of the documentation will be done from the point of view of these distributions. Translating from these distributions to another should not be to hard provided you have some knowledge of the source and destinations systems.
This server-side component is not and will not be tested on Win32/64 and OSX systems, althought it might work on these platforms without much changes.
The ActionScript code contained in this repository is given as an example and for demonstration and testing purposes only. Support will be provided on it whenever possible but it is not officialy part of this component.
Directory layout and important files
Root of the project
Red5 Application code folder, see the Application subsection.
Contains tools which might help you (or not) running the server. See the Tools subsection.
Contains an example of client of the component with flash code and a tiny webapp for launching flash widgets, see the Flash subsection.
In this section i will explain, using a step-by-step procedure, how to install the component on you workstation/server, allowing you to start playing with it, integrating it and understanding its API.
As stated earlier, i recommend following this procedure on an recent Ubuntu or Debian distributions. Adapting the procedure to another distribution shouldn't be too hard but for the first time, try to use the recommended environment and settings.
Software and libraries.
Before starting to follow the installation guide, check you have the following packages installed on your system and install them if you don't:
(All the items in the list that starts with an ! are not currently required but will soon be. They are here as a reminder)
A JDK 1.6 (I will assume OpenJDK (openjdk-6-jdk) through the rest of this guide.)
build-essential (iirc, it is only for GNU Make)
The following ruby gems (install using `gem install xxx` (as root))
activerecord (< 3.0.0)
activesupport (< 3.0.0)
The latest stable OpenSource Flex SDK from Adobe (opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4)
Your favorite text editor
The component use jruby and the ability of the Red5 server to load and run Ruby code in order to ease development of the component. This is somewhat tricky to setup because in the recent binary release of Red5 it seems that there are some required java archives (jar) missing. Due to this, the current recommended way of installing the Red5 server is to use the provided archive.
You could find this archive here : github.com/epitech-labfree/encrev1/downloads Please double check you download the last version.
(Open a terminal, this guide assumes a bash compatible shell)
Installing Red5 and Flex
Fetch and unpack the Red5 server binary release into a folder of you choice. Then define the RED5_HOME environment variable to the path of the red5 folder
$ cd ~/encre_video && tar xzf red5-x.y.z-encre.tar.gz && export RED5_HOME=~/encre_video/red5-x.y.z/
Fetch and unpack the OpenSource Flex SDK, then define the FLEX_HOME environment variable to the path of the flex sdk folder
$ mkdir ~/encre_video/flex && cd ~/encre_video/flex && unzip ../flex_sdk_x.y.zip && export FLEX_HOME=~/encre_video/flex
Fetching and deploying the encre red5 application
Grab the latest source of the video component (this repository). The following command should create you a encrev1 folder in ~/encre_video containing the latest source. You could update it later by issuing the command `git pull origin master`
$ cd ~/encre_video && git clone git://github.com/epitech-labfree/encrev1.git
Install the videochat component into the Red5 Server by creating a symlink to the encrev1 folder in the red5 webapps subfolder.
$ ln -s ~/encre_video/encrev1 ~/encre_video/red5-x.y.z/webapps
You could now test that these parts are correctly installed
$ cd ~/encre_video/red5-x.y.z/ && ./red5.sh
Don't worry about the “warning: could not compile: because of: ”Illegal class name “” in class file “, this is a known Spring bug (a framework Red5 uses). If you see the following message : ”Initializing ENCRE VideoChat v1.… ..Done“, the application has been successfully installed.
Note that you could use the JAVA_OPTS environment variable to pass option to the Java VM, these one could be helpfull :
-Djruby.jit.logging.verbose=true gives a more verbose output from Jruby inside Red5
-client speeds up the start of Red5 by not compiling everything but slows the average speed of the server (usefull for tests.)
Running the Encre Platform Mock
Since the encre platform and especially the video api is not yet finished and available and because it could be handy for testing and development purpose, a small mock has been developped for the Encre Platform. It is a small web application that reproduces the (expected) behavior of the Core of the encre platform. It is currently needed if you want to user the videochat component. Tu run it, open another term and issue the following command:
$ cd ~/encre_video/encrev1/tools/ && ruby encre-platform-mock.rb
Setting up the database and running the ENCRE Api entry point
You must now setup the database used to communicate between the ENCRE Api entry point and the videochat application by issuing this command
$ ~/encre_video/encrev1/api && rake migrate #(or simply rake)
If the rake command is not found, check the rake installation documentation for your distribution or you system, or the official rake documentation on the Internet.
You may finally run the API entry point by issuing this command.
$ ~/encre_video/encrev1/api && ruby server.rb -p 9876
Building and running the demo client
Code is sometimes more helpfull to developpers than tons of pages of documentations and specifications. Following this principle, an example of flash widgets supporting the api and of a small web application powering it is provided. These will be maintained in sync with the current state of the code and of the specification.
In order to build the flash/flex clients, please check the flex sdk is correctly setup and you have set the FLEX_HOME env variable accordingly then run:
$ cd ~/encre_video/encrev1/flash && make
Finally run it with:
$ cd ~/encre_video/encrev1/flash && ruby flash_widgets_server.rb -p 1234
Using the examples
Check that Red5, Encre Platform Mock and example server are running. You could now open your flash-enabled browser and go to localhost:1234
The Red5 Application
This is mainly the code you will find here. This is the main part of the videochat component. It is responsible of managing the chat rooms and their streams. It (will) perform the control and authorization as well as the recording of the video streams.
The tool section currently only contains a mock for the Encre Platform, reproducing its expected behavior regarding auth and event passing. You can configure it simply by editing the encre-platform-mock.rb file to specify which token are authorized to do what and what do do when receiving events.
Currently, you have to run the encre-platform-mock.rb script to allow the red5 application to start. If you don't, the application won't be able to authorize itself nor the clients connections and actions and will simply refuse to start.
The flash code
The flash folder contains examples web application and flash widgets codes to help distributors and integrators to work with the videochat.
The widget folder contains two sample flash widgets implementing the (currently very simple) encre video auth api:
receive_video contains a simple player which will authorized itself on the red5 application and display the stream on the server you provided as parameters.
publish_video authorized itself and then publish the stream at the place provided as parameter.
Finaly, the small flash_widgets_server.rb web application simply provides forms to instanciate flash widgets with the correct parameters. It is kind of the simplest ditribution using the videochat component you could imagine.
In this section, most common error will be listed along with their solutions. As java error can be very (very) long and especially when the problematic code is executed in an application server, only the characteristic portion of the error will be given. It's up to you to find it! (It's generally a good idea to start reading the stack trace from the end)
- no such file to load – 'encre_auth'
The $RED_HOME environment variable is not properly set or you are not running the red5*sh scripts from the red5 directory.
- no such file to load – 'rest_client' or 'json'
The rest-client or json_pure gems are not installed or where not installed by the user who runs the applications (jruby gems are installed in ~/.gem/jruby, and on debian the systems gems are not where jruby expects them).