1. Introduction 1.1 Overview 1.2 Features 1.3 Sytem Requirements 1.4 Performance 1.5 License 1.6 Kind donators 2. Running the server 2.1 Overview 2.2 Parameters 2.3 Admin console 2.4 Unit test 2.5 Unit test 3. Programming the server 3.1 Overview 3.2 IApplication 3.3 Client class 3.4 Stream class 3.5 Wrapper classes 3.6 InvokeEvent 3.7 StreamEvent 3.8 StatusEvent 3.9 Utilities 4. Development howtos 4.1 How to create a Custom Application? 4.2 How to embed Milenia in my package? 4.3 How to recompile Milenia? 1. Introduction 1.1 Overview Milenia Grafter Server is an open source flash media server that just works. With Milenia you don't have to know dozens of frameworks and tricks to create custom applications, you don't have to read up thousands of lines of configuration xml's to configure your server properly, you don't have to tear your hair off because of magic mistakes and unexpected errors coming from a closed source application, you don't have to wait for the never-coming answers of water-headed corporations, you don't have to pay thousands of dollars/euros for poorly performing enterprise level products. Simplicity was the only keyword during its creation, so i have not implemented any useless features from other flash media server implementations. 1.2 Features Live Audio/Video streaming Live Audio/Video recording Video on demand ( VP6 and H264 support is coming ) FLV playback speed set - slow/fast, forward/reverse Stream access control based on stream events Simple and fast custom application deployment Lightweight data communication Client mode - you can connect Milenia to any kind of flash media server Stream pushing/pulling to/from other servers Built-in bandwidth test - bidirectional and accurate Sample access enabled Admin console Stress tester Unit tester Future Features: Adobe live encoder integration ( 0.9 ) VP6, H264 capability ( 0.9 ) RTMPE support ( 1.0 ) 1.3 System Requirements: Any system with Java Virtual Machine 1.5 1.4 Performance Under construction. 1.5 The license Milenia Grafter Server is licensed under General Public License v2. Copyright (c) 2007-2008 by Milan Toth. All rights reserved. This program is free software; you can redistribute it and/ormodify it under the terms of the GNU General Public Licenseas published by the Free Software Foundation; either version 2of the License, or ( at your option ) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public Licensealong with this program; if not, write to the Free SoftwareFoundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 1.6 Kind donators Apakian Pty.Ltd Reinhard & Löw GbR Thank you guys! :) 2. Running the server 2.1 Overview Milenia doesn't need installation, since it's one single java jar file, you simply execute it with the java virtual machine. First you have to be sure that your system has Java Runtime Environment 1.5 or higher. If not, download it from sun. If you have it, simply type java -jar milgra.jar in the command line, and it should show up the version info and the parameter hints. The basic server package looks like this : applications streams sources milgra.jar license.txt "applications" is the default custom application directory for the server. You have to copy your custom application jars here. "streams" is the default directory for streams, Milenia saves recorded streams here. "sources" contains the sources and the compiled admin application also. "milgra.jar" is the server itself, "license.txt" is the GPL v2 license. 2.2 Parameters start starts the server on the default port ( 1935 ) stop stops the server on the default port ( 1935 ) port [number] sets the listener port to given number iostep [number] sets the io process stepping delay in milisecs. Default is 15 iothreads [number] sets the thread counts of process groups. If your server isn't under a heavy load, or you want other services to run on your machine, one thread is enough. But if you have a multi-processored multi-cored monster, you can start experimenting with this setting and the stress tester. It won't speed up data throughput since only one process can reach the system bus and the sockets at a time, but it fastens stream pushing between threads, and data processing also. streams [directory] sets the stream directory where milenia stores/reads up streams. The directory will be created under the directory where milgra.jar is. applications [directory] sets the custom application directory where milenia looks for custm applications. The directory will be created under the directory where milgra.jar is. examples: The following command starts the server listeneing on port 80, with 20 milliseconds of io stepping and with the default stream directory "mystreams" java -jar milgra.jar start port 80 iostep 20 streams mystreams The following command stops the server listening on port 80 java -jar milgra.jar stop port 80 For performance tuning you may have to use additional java virtual machine switches, for example, -server or if jvm runs out of memory -Xmn -Xms -Xmx to set memory size. The following command starts Milenia with default settings with 500 megabytes of maximum memory usage. java -Xmx500M -jar milgra.jar start 2.3 Admin Console To use the admin console, ensure that the server-side admin application ( admin.jar ) is under the Milenia's custom application directory, and the server is running. Open admin.swf ( under sources directory by default ) in a web browser having Flash Player 9. For the first run type "admin" for both username and password. Admin application creates a fourth directory called "admin" in Milenia's root for its config file and logs. I recommend to immediately set a new username/password in admin/config.xml, and you may define allowed ip addresses also. In the console, you will see two main tabs. Graphs tab After a succesful login, you will find yourself at the graphs tab. These graphs shows the i/o states of the server. "Bandwidth" shows the overall, incoming, and outgoing bandwidth in Megabits/second. "Connected Clients" shows the overall, passive and active client count on the server. Active clients are the clients created by a custom application to connect to other servers. "Processing Threads" shows socket, client and stream pool processing thread count, "Execution Times" show the average process execution times of the different thread pools. Applications tab You can check the available applications here. They consists of the custom applications under Milenia Grafter Server / applications directory, and the running applications ( if custom application jar has been removed from the directory, but the application hasn't been unloaded ). You can check the status, connected clients and bandwidth info of an application. You can refresh application list any time, this case Milenia will reread the applicaitons directory. You have to wait for the next refresh event to see the new list. You can unload/load applications by pressing load/unload buttons. Under applications tab, it will show one connected client ( you ) and one running application ( the admin application ). I also encourage the use of jconsole if you want to receive really detailed information about your machine and jvm health status. 2.4 Unit tester You can test all of the server's functions with this application, and also you can perform stress test on a server with this. The other purpose of the stress tester is the API showcase for developers, both server and client side code is well commented, and covers all possibilities of Milenia. Client-Server Connection Performs various connection tests, tests all possible connection events between the client and the server. Client-Server Data Communication Performs Data Exchange tests. Tests invoke calls from client to server and back, and tests exchange of AMF0 types. Client-Server Live Streaming Performs live streaming tests between client and server. Publishes the camera and mic input to server, and plays it. Tests stream events, and enable/disable functionality. Client-Server Recorded Streaming Performs recorded stream ( non vp6 flv ) testing. Plays an individual stream from the server, and also plays a TV-stream set up on the server. Client-Server Stream Recording Tests stream recording capabilities of the server. Server-Server Connection Performs various connection tests between two servers. Server-Server Data Communication Tests invokes and AMF0 data exchange between two servers. Server-Server Live Streaming Publishes Camera and Microphone input to the host server, the server publishes the stream to the secondary server, then pulls it under a new name, and the client shows that stream. Server-Server Recorded Streaming Under construction. Multi-Stream Test Tests playing multiple streams from the server ( > 20 ). Tests rtmp channel overload, and rtmp channel page switching. FMS Compatibilty tests Connects Milenia to an FMS. There is also a sample fms application ( main.asc ) under sources, with you can test fms to milenia connection. Bandwidth check Tests download and upload bandwidth between client and server. These values will never be the maximum values of your connection, the maximum values are depending on the stepping time and buffer size of the server. For example, if io stepping is 20 millisecs and io ( socket ) buffer is 8192 bytes, then the maximum data troughput per second is ( 1000 / 20 ) * 8192 = 409600 bytes / s, or 400 K/s. Stress Test Stress test performs load test on the secondary server. It starts pushing a live stream to the server, and through multiple connections it pulls them from the server testing stream distribution and data throughput capabilities. 3. Programming the server 3.1 Overview You can create custom applications or application packages for Milenia Grafter Server in Java. You simply have to create a jar package from your compiled classes / packages, and copy it under Milenia's custom application folder, and they are ready to use. Custom applications are dynamically loaded at startup or on the fly triggered from the admin console. Custom applications must not be in the classpath, otherwise jvm cannot reload them. Development tip : always create a startup script, which compiles/packs your custom application in your workspace, then copies it under milenia, and starts up the server. To reach Milenia's API, you have to use the API classes packed in Milenia. There are three main rules for a custom application: 1. The main class of your application must be called Application 2. The main class of your application must be in a package called application 3. The main class of your application must implement IApplication interface You have to be careful on the server with threads, because various events can come from various threads, use synchronization when there can be concurrencies. There is also an important thing for the client side : never forget to set AMF object encoding to AMF0 on the client side, because Milenia uses AMF0. 3.2 IApplication interface - com.milgra.server.api.IApplication You have to implement IApplication interface in the main class of your custom application. IApplication contains three main controller methods: onStart ( String nameX ) Milenia triggers this function when an application is loaded. It receives the application's name with scope ( if it has one ). You can put initialization here, but its also good within the custom applications constructor. onClose ( ) The server will call it when the admin unloads this application from admin console during runtime. You have to define a complete cleanup code here to avoid memory leaks. onEnter ( Client clientX , WrapperList argumentsX ) Client entering point, clientX is the client instance, messageX is the wrapperlist containing the arguments passed by the client. clientX will be in idle state, until you call the clientX.accept( ) or clientX.reject( ) methods. onLeave ( Client clientX ); Client leaving point, do client-related cleanup here. 3.3 Client class - com.milgra.server.api.Client You can control connected ( passive ), and remote ( active ) client behaviour with this class. Constructor public Client ( IApplication applicationX ) You can create a new remote client instance with the constrcutor, attached to the given application. After creation, you can connect the client to a remote server, and exchange data , pull / push streams. Getter/Setters public long getId ( ) Returns the unique identifier number of the client. public long getPing( ) The ping rountrip time of the client. public long getBytesIn( ) The received byte count by the server from this client public long getBytesOut( ) The sent byte count to this client public double getBandIn( ) The actual incoming bandwidth of the client in bytes per second. public double getBandOut( ) The actual outgoing bandwidth of the client in bytes per second. public String getIp( ) Returns the ip address of the client. public String getAgent( ) The player / server info of the client. public String getReferrer( ) The referrer of the client. Passive mode only methods : public void accept ( ) Accepts the client public void accept ( Wrapper wrapperX ) Accepts the client with a wrapper as acception info, the client receives it as the NetStatus event's info.applicaiton parameter public void reject ( Wrapper wrapperX ) Rejects the client, you can pass a wrapper as rejection info, the client receives it as the NetStatus event's info.application parameter public void detach ( ) Detaches the client from the server Active mode only methods : public void connect ( String uriX , Wrapper argumentsX ) Connects the client to a remote server with address uriX, passing argumentX as connection object public void connect ( String uriX , WrapperList argumentsX ) Connects the client to a remote server with address uriX, passing argumentsX as connection object Common Methods public void call ( String invokeID ) Invokes a method on client side without arguments public void call ( String invokeID , Wrapper argumentX ) Invokes a method on client side with a wrapper as arguments public void call ( String invokeID , WrapperList argumentX ) Invokes a method on client side with an wrapperlist as argument public void callResult ( String invokeID , Wrapper argumentX ) If a responder for a specific function is defined on client side, you may pass back a result with this function public void callResult ( String invokeID , WrapperList argumentsX ) If a responder for a specific function is defined on client side, you may pass back a result with this function with a wrapperlist as an arguments public void addStreamEventListener ( EventListener listenerX ) You may add a stream event listener object to the client with this method. public void addInvokeEventListener ( EventListener listenerX ) You may add an invoke event listener object to the client with this method. public void addStatusEventListener ( EventListener listenerX ) You may add a status event listener object to the client with this method. public HashMap < Double , String > getPlayers ( ) Returns the list of streams played by the client public HashMap < Double , String >getRouters ( ) Returns the list of streams published by the client 3.4 Stream class - com.milgra.server.api.stream Stream class contains stream related properties and methods. There are two types of stream on Milenia : incoming streams, which is published by clients or other servers, and outgoing streams, which are played by clients or pulled by other server. Incoming streams are represented by stream routers, outgoing streams by stream players. Both of them are represented by the stream class. However if stream instance is a stream player, you can only enable/disable/delete it, other methods aren't working on it. Mileania's stream pool is shared, so every applicaiton can reach every stream published to the server. You can publihs/record/play streams from clients without access control by default. If you want to control stream access, you have to define a stream event listener in your custom application, and register it with addStreamEventListener( ). After this you will be notified about every NetStream.play and NetStream.publish event, and you have to enable or disable these requests. Properties public static final String PLAYER; player type identifier public static final String ROUTER; router type identifier public String type; type of the stream, can be PLAYER or ROUTER public String name; name of the played/routed stream. router names are unique, but multiple players can have the same name, when they are playing the same stream. public String mode; if type is router, then recording mode. can be live, record, append public Client client; owner of the stream, if stream has no owner, then null Methods public Stream ( String nameX ) creates a stream on local server under the given name public Stream ( String nameX , Client clientX ) creates a stream on remote server defined by clientX. public void play ( String nameX ) starts playing the given stream. if given stream doesn't exist, it waits for its appereance. If stream name ends with ".flv", it tries to play a recorded stream with that name from the default stream directory. public void publish ( String nameX , String modeX ) publishes the given stream to the remote server, if stream is an active stream, with the given mode. public void delete ( ) deletes the stream from the server, if its a live stream, its broadcasting is stopped public void enable ( ) enables a stream route/play request. if you have defined a stream event listener for a client, you have to enable/disable streams related to incoming events public void disable ( ) disables a stream route/play request, the client will receive a NetStream.Publish.Failed or NetStream.Play.Failed event. if you have defined a stream event listener for a client, you have to enabled/disable streams related to incoming events. public void enableAudio ( boolean stateX ) enables/disables audio transfer in the specific stream public void enableVideo ( boolean stateX ) enables/disables video transfer in the specific streams public void pause ( boolean stateX ) pauses/resumes stream playing public void record ( boolean stateX ) starts/stops recording the specific streams public void seek ( int positionX ) seeks in vod stream public void speed ( double multiplierX ) sets speed of vod stream public double getSpeed ( ) returns the speed of the vod player public double getPosition ( ) returns position of vod public double getDuration ( ) returns duration of stream public String getType ( ) returns type of stream public String getName ( ) returns name of stream public String getMode ( ) returns mode of stream Static Methods public static ArrayList < String > getStreamNames ( ) returns streams avaliable on server 3.5 Wrapper classes Wrapper classes are a simple value wrappers, but most of your time programming Milenia Grafter Server you will use wrappers. As you know, java is a strictly typed language and actionscript is weakly typed. During data exchange flash can send objects and arrays containing mixed data types, and on the java side after deserialization we have to keep this state somehow in the strictly typed environment. That's why Wrapper class was born. AMF deserializer wraps data in Wrapper objects, and serializer uses Wrappers for input also. public class Wrapper wraps a java data type Properties public String type contains the type of the wrapped value public double doubleValue the value of a wrapped double public String stringValue the value of a wrapped string public boolean booleanValue the value of a wrapped boolean public WrapperMap mapValue the value of a wrapped WrapperMap public WrapperList listValue the value of a wrapped WrapperList Static properties public static final String MAP HashMap type identifier constant public static final String NULL Null type identifier constant public static final String LIST ArrayList type identifier constant public static final String DOUBLE Double type identifier constant public static final String STRING String type identifier constant public static final String BOOLEAN Boolean type identifier constant Methods public Wrapper ( ) createw a wrapper containing NULL public Wrapper ( valueX ) the constructor of Wrapper, accepts double, boolean, string, hashmap, arraylist as parameters, if it receives no parameter, then wrapped type will be null. public class WrapperList wraps an ArrayList of wrapper objects Methods public WrapperList ( ) creates an empty wrapperlist public WrapperList ( Wrapper itemX ) creates a wrapperlist with itemX a first element public WrapperList ( List < Wrapper > sourceX ) creates a wrapperlist containing sourceX public void add ( ) adds a wrapped null to the list public void add ( String stringX ) adds a wrapped string to the list public void add ( double doubleX ) adds a wrapped double to the list public void add ( boolean booleanX ) adds a wrapped boolean to the list public void add ( WrapperMap mapX ) adds a wrapped wrappermap to the list public void add ( WrapperList listX ) adds a wrapped wrapperlist to the list public String getType ( int indexX ) returns the type of the specific element public String getString ( int indexX ) returns the string value of the specific element public double getDouble ( int indexX ) returns the double value of the specific element public boolean getBoolean ( int indexX ) returns the boolean value of the specific element public WrapperMap getMap ( int indexX ) returns the wrappermap value of the specific element public WrapperList getList ( int indexX ) returns the wrapperlist value of the specific element public class WrapperMap wraps a HashMap of wrapper objects Methods public WrapperMap ( ) creates an empty wrappermap public WrapperMap ( Map < String , Wrapper > sourceX ) creates a wrappermap containing the given map public WrapperMap ( String [ ] keysX , Object [ ] valuesX ) creates a wrappermap with the given key-value pairs public void put ( String keyX ) puts a null value in WrapperMap with the given key public void put ( String keyX , String stringX ) puts a String value in map under key public void put ( String keyX , double doubleX ) puts a double value in map under key public void put ( String keyX , boolean booleanX ) puts a boolean value in map under key public void put ( String keyX , WrapperMap mapX ) puts a map value in map under key public void put ( String keyX , WrapperList listX ) puts a list value in map under key public String getType ( String keyX ) returns type of the stored wrapper under key public String getString ( String keyX ) return string value of the wrapper at key public double getDouble ( String keyX ) returns double value of the wrapper at key public boolean getBoolean ( String keyX ) returns boolean value of the wrapper at key public WrapperMap getMap ( String keyX ) returns map value of the wrapper at key public WrapperList getList ( String keyX ) returns list value of the wrapper at key 3.6 InvokeEvent InvokeEvent is an event information holder for invoke calls. It is dispatched by client instances. To watch for invoke events, first you have to create an instance of the EventListener class, and redefine its onEvent function where you define what to do with the event, then you have to add this eventlistener instance to a client by calling Client.addInvokeEventListener. Properties public String id identifier of the call, this is what you pass on the client side with NetConnection.call( identifier ... ) public Client client the client instance where this event is coming from public WrapperList arguments the arguments related to this call 3.7 Stream Events StreamEvent is an event information holder for stream events. It is dispatched by client instances To watch for stream events, first you have to create an instance of the EventListener class, and redefine its onEvent function where you define what to do with the event, then you have to add this eventlistener instance to a client by calling Client.addStreamEventListener. Properties public Client client the client instance where this event is coming from public Stream stream the stream instance related to this stream. you may check the type of the instance first with Stream.type, then the name with Stream.name, then you have to enable or disable this request with Stream.enable( ) or Stream.disable( ). you can event store the stream instance, and enable/disable it later, the stream will be in idle state till that, and wont transfer any data. 3.8 Status Events StatusEvent is an event information holder for client's status or stream events. It is dispatched by client instances To watch for status events, first you have to create an instance of the EventListener class, and redefine its onEvent function where you define what to do with the event, then you have to add this eventlistener instance to a client by calling Client.addStatusEventListener. Properties public String code the code word for the actual event public Client client the client instance where this event is coming from public WrapperMap info the information map related to the event Static Properties public static final String FAILURE connection failure event code word container. public static final String CLOSURE connection closure event code word container public static final String SUCCESS connection success event code word container. the info property of the event may contain additional information about the success in the "application" key public static final String REJECTION connection rejection event code word container. the info property of the event may contain additional information about the rejection in the "application" key public static final String PLAYSTART stream play reset notify public static final String PLAYRESET stream play start notify public static final String PLAYFAILED stream play failed notify public static final String PUBLISHSTART stream publish start notify public static final String RECORDNOACCESS stream publish failed notify public static final String UNPUBLISHSUCCESS stream unpublish notify 3.9 Utilities Timer - com.milgra.server.api.Timer Simple timer. You have to define an EventListener first, then instantiate the timer with an arbitray interval in milliseconds, and the eventlistener. Example: LogWriter - com.milgra.server.util.LogWriter Log writer. Instantiate it with the log file name, then call addLog( String log ) to add new entry. Close it with close( ). Example: 4. Extra Documentation 4.1 How to create a Custom Application? Donwload and unzip Milenia Grafter Server. Download and install the latest Eclipse for you platform. Ensure that you have JRE 1.5 or higher on your system, and JRE executables are in the execution path. Start Eclipse. File menuitem -> New -> Project, select Java project, click Next, type your desired project name as project name. If JRE 1.5 is not the default, select it under JRE. Click next. For default output folder, type YourProjectName/bin , so Eclipse will compile classes under a separate "bin" directory, and it will be easier for us to pack our classes into jar. Click on libraries tab, click Add External JARs, choose Milenia Grafter's folder, and select milenia.jar, click Open. That's all for project setup, click Finish. YourProjectName project appeared in Package Explorer. File menuitem -> New -> Class.For class name, type Application ( first letter uppercase ), and in the package field, type application ( all lowercase ). Every main custom application class must be application.Application. Click finish. The class is created. Every main application class must implement Milenia Grafter's IApplication interface. So, under package name type "import com.milgra.server.IApplication;" Now you have to create the four implemented functions: onEnter, onLeave, onStart, onClose, and add wanted functionality. If Eclipse shows no compiler errors/warnings, you are ready to pack your application into jar. Open a terminal, go in your Eclipse workspace directory, go under YourProject/bin. You see an "application" directory, where eclipse compiled our application classes. Type jar -cf yourappname.jar application And a yourappname.jar file appears in the directory. Copy this file under Milenia Grafter Server/applications. Start the server if it's not running, or load the application with MilGraAdmin under applications tab. ( refresh - load ). The application is ready to use. Check ut the sources of MilGraUnit, everything is there you want to use in your app deployment. 4.2 How to embed Milenia in my application package? You can easily embed the server in your package, simply set Library values to your hearts content, then instantiate the server, like its in Server class main function. There is also a shutdown hook in Server class, called shutdown, it kills the server and cleans up everything. 4.3 How to recompile Milenia? It's very simple. If you are using Eclipse, it places the compiled classes under bin folder, and to make a jar from Milenia, you simply have to go to bin folder, and type "jar -cmf manifest.txt milgra.jar bin" from the command line, and of course manifest.txt has to be there also, and it's ready.