SFS2X Docs / GettingStarted / redbox
» The RedBox 2X
The RedBox is a free add-on for SmartFoxServer 2X that adds audio and video streaming capabilities to the server, making it possible to integrate such features in any existing ActionScript3 application.
The RedBox is made of three main components:
- the open-source Red5 Media Server for the audio/video streaming and recording;
- a dedicated set of client-side ActionScript3 API offering high level functionalities to start one-to-one video chats, create live events (one broadcaster, many subscribers), retrieve media files, perform remote a/v recording, etc;
- a server-side SFS2X Extension which takes care of the requests and events generated during the interaction with the client API and which integrates the SmartFoxServer capabilities with Red5 server.
Additionally, four complete examples are provided for reference: they demonstrate all the features made available by the RedBox to create video chats, video conferences and more.
IMPORTANT NOTE
The SmartFoxServer Team provides help for all the RedBox components except the Red5 server. Anyway, even if we don't offer specific Red5 technical support, you can find it for any Red5 related problem in the official Red5 website linked above.
» The components
The RedBox is distributed as a single package containing the components described in detail below. It can be downloaded from the main SmartFoxServer 2X download page.
The Client and Server folders in the package contain all you need to setup the RedBox and test it using the provided examples; they also contain the libraries you will need to start developing your own applications.
The Sources folder contains the source code of all the RedBox components (except the Red5 server) and the provided examples, in case you need to add your own features or customize the existing ones. See the Source code setup paragraph below for more informations.
» Client
- API_AS3 folder: contains the SFS2X_RedBox.swc library containing the RedBox API to be used in Flash / Flash Builder projects (see Red5 installation and Creating your own RedBox applications paragraphs below).
- Examples_AS3 folder: contains the compiled examples to immediately start playing with the RedBox after installation (see Running the examples paragraph below).
» Server
- Red5 folder: contains the Red5 Media Server 1.0 RC to be installed on your server (see Red5 installation paragraph below).
- redBox folder: contains the jar file of the RedBox Extension for SmartFoxServer 2X and the redbox.properties file which is required to configure a few RedBox settings (see Creating your own RedBox applications paragraph below).
- zones folder: contains the SmartFoxServer 2X Zones definitions for the provided examples (see Running the examples paragraph below).
» Red5 installation
The RedBox requires a Red5 Media Server instance to be up and running. In order to install the Red5 version provided in the RedBox package, simply copy the /Server/Red5 folder from the unzipped package to your SmartFoxServer 2X installation folder. Make sure that the Red5 folder is at the same level of the SFS2X folder.
In order to start Red5 double click red5.bat (Windows) or launch the red5.sh script (OSX/Linux/Unix). In case of OSX, Linux or Unix systems you might have permission problems: just enable execution on the Red5.sh file.
NOTE
We have removed all unnecessary files and folders from the Red5 version provided in the RedBox package, to make it less cluttered and ready for production.
Also, our Red5 distribution comes with a preinstalled server-side application called SFS_RedBox, which can be found under Red5/webapps. This application is very simple and does nothing except providing an access point for the RedBox API to the streaming capabilities of Red5.
Additionally it contains the streams folder, which is used by Red5 to store recorded clips and temporary live streams. By default this folder comes with four videoclips used by the Video Clip Player example: they can be deleted when installing Red5 in a production environment.
» Upgrading Red5
The RedBox works with Red5 1.0 RC and previous releases. It is highly likely that it will continue to work with the new releases, but we cannot guarantee it.
In case you want to upgrade Red5, make sure you copy the SFS_RedBox folder contained under Red5/webapps to the same location of the new Red5 folder.
» Moving Red5
You can move Red5 to a different folder or even a dedicated server by following these steps:
- copy the Red5 folder to the new location or your dedicated server;
- in case of a separate server, share the Red5 folder in your local network so that it can be accessed by the machine running SmartFoxServer;
- edit the redbox.properties file located side-by-side with the RedBox Extension (see Creating your own RedBox applications paragraph below) and point the red5Path value to the Red5 folder;
- start both Red5 and SmartFoxServer 2X.
» Using a different Media Server
In theory it is possible to use Adobe Flash Media Server or Wowza Media Server instead of Red5, because they all speak the same protocol (RTMP). The RedBox however makes use of a Red5 server-side application (see box above) that should translated for the alternative RTMP server of choice. Being a very simple application it shouldn't be too difficult to translate (source code is available in the RedBox package).
NOTE
We have been reported that Wowza 3.6.3 works out of the box with SmartFoxServer 2X. The only additional setup needed was to add the empty application directory under [WowzaDir]/applications/SFS_RedBox.
» Running the examples
The RedBox package contains four examples showing the features offered by its API. The examples are described in detail in this document. In order to run them, first of all you have to setup the server-side part:
- install Red5 as described in the previous paragraph;
- install the RedBox Extension for SFS2X by copying the /Server/redBox folder from the RedBox package to your SFS2X/extensions folder;
- configure the SFS2X Zones used by the examples by copying the files contained in the /Server/zones folder from the RedBox package to your SFS2X/zones folder; only three zones are configured because one of the examples uses the BasicExamples Zone provided by default in SFS2X (if you removed it simply configure the example to use an existing Zone).
Once the server is ready, launch Red5 and SmartFoxServer 2X, and make sure no errors are logged by SmartFoxServer during the startup process. Now go to the /Client/Examples_AS3 folder in the RedBox package, open one of the subfolders and launch the example in your browser by double-clicking the html file.
If you have a SFS2X setup different from the default one, you may need to change the client-side configuration by editing the sfs-config.xml file provided with each example.
» Creating your own RedBox applications
Adding live audio/video streams to your existing or brand new applications is very simple. On the client-side all you have to do is:
- copy the SFS2X_RedBox.swc library file from the /Client/API_AS3 folder in the RedBox package to any location on your computer;
- reference the SWC library (which contains the RedBox API classes) in your Flash / Flash Builder project (the requirements are the same of the SmartFoxServer API – see this document);
- import the proper RedBox class(es) you need based on what your application will do.
The Rebdox API has been split into the following main classes; you should check the API documentation section in the left sidebar for detailed informations.
- AVChatManager
This class is responsible for audio/video chat implementation through the connection to the Red5 server. The AVChatManager handles the chat workflow (send request, accept or refuse it, establish or stop connection, etc) and the live streaming to/from the Red5 server.
- AVClipManager
This class is responsible for audio/video clip recording & playback through the connection to the Red5 server. The AVClipManager handles the list of available a/v clips, their custom additional properties and the streaming to/from the Red5 server.
- AVCastManager
This class is responsible for managing audio/video live casts inside the SmartFoxServer Room joined by the user, making it possible to create live web events or a/v conferences. The AVCastManager handles the live cast publishing/playing to/from the Red5 server. Unlike the other RedBox classes, the AVCastManager works on a Room basis to take advantage of the access control and moderation features of SFS Rooms.
On the server side, the RedBox API requires the RedBox Extension to be assigned to the application's Zone. In case your application doesn't need custom server-side coding at Zone level (in other words it doesn't feature its own Extension), you can use the Extension provided in the RedBox package directly by doing the following:
- copy the /Server/redBox folder from the RedBox package to your SFS2X/extensions folder;
- configure your Zone's Extension in the Administration Tool (see this document): select redBox in the Name dropdown and RedBoxExtension in the Main class dropdown (type is Java of course).
In case you need to write your own server-side Extension, as SFS2X doesn't allow more than one Extension to be assigned to the same Zone, you can follow the default Extension creation process (described here) but instead of making your main class extend SFSExtension, make it extend the RedBoxExtension class. In order to be able to do this, you will need to reference the RedBoxExtension.jar file provided in the /Server/redBox folder of the RedBox package in your server-side project.
As it regards the deployment, you will need to deploy the RedBoxExtension.jar file and the redbox.properties file (again available in the /Server/redBox folder of the RedBox package) together with your own Extension's jar file.
In both cases (using the RedBox Extension directly or creating your own child class), the redbox.properties file is used to configure some RedBox settings:
- log: if set to 1, enables the RedBox server-side logging (messages starting with "[RedBox]...")
- enableAVClipManager: if set to 1, enables the server-side handler for requests coming from the client-side AVClipManager class (see above)
- enableAVChatManager: if set to 1, enables the server-side handler for requests coming from the client-side AVChatManager class (see above)
- red5Path: absolute or relative path to the Red5 folder location; if relative, it must be relative to the SmartFoxServer's SFS2X folder
lastModifiedFormat: specifies the "Last modified" date format in the a/v clip data (see the java.text.SimpleDateFormat class constructor documentation for format codes)
» Source code setup
The RedBox package includes the source code, allowing developers to further expand its functionalities if needed. All source files are available in the /Sources folder of the package.
- API_AS3 folder: it contains the ActionScript3 classes of the RedBox API. You can reference them in your application project directly or you can create a new Flex Library Project in Flex/Flash Builder and add the content of this folder to the project's src folder to create your own SWC file. You will also need to reference the SmartFoxServer client API to be able to compile the project.
- Examples_AS3 folder: it contains the MXML and ActionScript3 source files of the provided examples. For each one, create a separate project in Flex/Flash Builder and substitute the src and libs folders of the project with those in this folder.
- Red5WebApp folder: it contains the Java class representing the Red5 server-side application (see the box in the Red5 installation paragraph). This might be useful in case new versions of Red5 require changes to the application for compatibility.
To setup the development environment, create a new project in your Jave IDE of choice and add the content of this folder to the project's src folder. You will also need to reference the red5.jar library contained in the Red5 main folder.
To deploy this application, copy the compiled class(es) to the Red5/webapps/SFS_RedBox/WEB-INF/classes folder. Refer to the Red5 documentation for more information on the other files contained in the WEB-INF folder. - RedBoxExtension folder: it contains the Java classes of the RedBox Extension. Please read the available documentation (starting from this page) for more informations on Extensions development and deployment.
» Frequently Asked Questions
» What is the advantage of using SmartFoxServer + RedBox, instead of using Red5 or Flash Media Server directly?
The RedBox offers a tight integration with the SmartFoxServer 2X API, providing an extremely powerful environment for
developing multiplayer applications with embedded a/v capabilities.
With the only use of Red5 or FMS you don't get any advanced Room management, Buddy Lists, chat filters, security, etc.
The synergy between the two servers can literally save months of development!
» Does the RedBox use a second connection for audio/video streaming?
Yes. The RTMP protocol used to communicate with the Red5 server works on port 1935 and its data traffic is separated from the SmartFoxServer 2X protocol.
There are many advantages with this approach, the main one is that you can even dedicate one server machine for the Red5 server,
if you have very high a/v traffic.
» Is Red5 started when SmartFoxServer boots?
No. You have to start it separately if your application needs the RedBox streaming services.
» Which version of Red5 is distributed with the RedBox?
Currently the RedBox includes a "light-weight" version of Red5 1.0 RC, which has been cleaned of the default examples and a few other files.
If you need the original additional examples you can visit the Red5 website and download the full release.
» Is the RedBox add-on compatible with Flash Media Server?
Yes, the RedBox is based on the Red5 Media Server, an open-source alternative to Adobe Flash Media Server, which implements the Adobe RTMP protocol.
» Would it be possible to use Flash Media Server or Wowza Media Server instead of Red5?
In theory yes. Please read the Using a different Media Server paragraph here.
» Where does the RedBox keep the recorded media files?
The files are located in the webapps/SFS_RedBox/streams folder inside your Red5 installation directory.
» Can I run the RedBox add-on on a separate dedicated server?
Yes. Please read the Moving Red5 paragraph here.
» Is the RedBox project open source?
Yes it is. The source code is distributed as a downloadable package under the BSD license.
You can learn more about the license here.
» Do you offer specific Red5 support?
We provide help for the RedBox API but we don't offer specific Red5 technical help.
You can find help for any Red5 related problem in the official Red5 website.