JUV RTMP Client Developer Guide

Version: 1.6

Copyright © 2012 Smaxe Ltd

Table of Contents

1. Introduction

2. Getting Started

3. Architecture

4. Usage examples

5. FAQ

List of Examples

4.1. Set license key

4.2. Create and configure NetConnection

4.3. Connect to the server and invoke server method

4.4. Connect to the remote shared object

4.5. Publish local FLV file as live stream

4.6. Publish audio source as live stream

Chapter 1. Introduction

JUV RTMP Client is a lightweight library that provides RTMP/RTMPT-enabled server access API for Java applications.

Features:

• RTMP/RTMPT/RTMPS/RTMPE/RTMPTE protocols support (both AMF0 and AMF3 encodings)
• remote method invocation
• remote shared object management
• play and publish audio/video streams
• ActionScript flash.net.* alike classes and methods
• Proxy support
• Java5 or later compatible

Related:
JUV RTMP Client (J2ME edition) - J2ME RTMP client
JUV RTMP Researcher - RTMP protocol debugger application
JUV RTMP Tester - RTMP functional/regression/load testing library

Chapter 2. Getting Started

JUV RTMP Client library consists of the only JAR file (no dependencies) that should be placed in the application's class path.

It requires the license key: either Evaluation Key (get it) or Developer Key (buy it).

Chapter 3.  Architecture

Java RTMP Client API is very similar to the API provided by Adobe® in the ActionScript's flash.net.* package.
There are 3 core classes defined in com.smaxe.uv.client.rtmp package:

• NetConnection is responsible for configuring/establishing the connection, remote method invocation
• NetStream is a stream management class
• SharedObject is a shared object management class

• IO_TIMEOUT - I/O timeout (default: 50 milliseconds) : library-specific value
• RECEIVE_BUFFER_SIZE - 'receive' buffer size (default: 256 * 1024 bytes) : library-specific buffer used to keep incoming rtmp data
• SEND_BUFFER_SIZE - 'send' buffer size (default: 256 * 1024 bytes) : library-specific buffer used to keep outgoing rtmp data
• STREAM_BUFFER_SIZE - stream buffer size (default: 512 * 1024 bytes) : library-specific lazily initialized buffer to store incoming audio/video packets. It is created only if a stream is played
• HANDSHAKE_TIMEOUT - timeout for the handshake phase of the protocol (in seconds) (default: 30 seconds)
• INACTIVITY_TIMEOUT - timeout for rtmp protocol connection (in seconds), i.e. if data is not received/sent during this timeout, the connection is considered disconnected (default: -1 seconds (indefinite))
• FPAD, PAGE_URL, SWF_URL, FLASH_VER, VIDEO_CODECS, AUDIO_CODECS, VIDEO_FUNCTION - configurable collection of parameters sent to the server during connection phase
• ENABLE_ACKNOWLEDGEMENT_EVENT_NOTIFICATION - 'Acknowledgement' event notification flag (default: false).
• WINDOW_ACKNOWLEDGEMENT_SIZE - server will send 'Acknowledgement' event every N read bytes (default: 128 * 1024)
• RTMPS_BASED_ON_RTMP - 'RTMPS based on RTMP protocol' flag (default: true), if false then RTMPS is based on RTMPT protocol
• RTMPS_SSL_CONTEXT - RTMPS SSL Context to use (default: null)
• METHOD_INVOKER - an instance of com.smaxe.uv.invoker.IMethodInvoker
• OBJECT_CREATOR - an instance of com.smaxe.uv.amf.IObjectCreator
• LOGGER - an instance of com.smaxe.logger.ILogger
• PROXY - an instance of java.net.Proxy

• dispatcher - It is responsible for dispatching method invocation events.
• scheduler - It must be single-threaded. It is responsible for reading socket stream (every IO_TIMEOUT milliseconds), notifying about shared object changes and stream's audio/video data.

com.smaxe.uv.invoker.IMethodInvoker

Every method invoked by the server is processed by the IMethodInvoker instance.

public interface IMethodInvoker
{
    /**
     * Invokes method with the args of the object o.
     * The result is returned through the {@link ICallback callback}.
     * 
     * @param o object which method is invoked
     * @param method method to invoke
     * @param callback callback to receive invocation result
     * @param args method arguments
     */
    public void invoke(final Object o, final String method, final ICallback callback, final Object... args);
}

com.smaxe.uv.amf.IObjectCreator

Every custom Java object that is sent/received to/from the server must be presented as ClassObject, i.e. class name + {property : property value} map. The IObjectCreator implementation is responsible for the such transformation.

public interface IObjectCreator
{
    /**
     * Converts {@link ClassObject co} to the custom type object.
     * 
     * @param co ClassObject instance
     * @return custom object
     */
    public Object toObject(final ClassObject co);
    
    /**
     * Converts {@link Object o} to the {@link ClassObject} instance.
     * 
     * @param o object to represent as ClassObject
     * @return ClassObject instance
     */
    public ClassObject toClassObject(final Object o);
}

/**
 * Simple class we want to send to the RTMP server.
 */
public class CustomClass extends Object
{
    public int field1;
    public String field2;
}

/**
 * IObjectCreator implementation.
 */
public class ObjectCreator implements IObjectCreator
{
    public ClassObject toClassObject(final Object o)
    {
        if (o instanceof CustomClass)
        {
            final CustomClass cc = (CustomClass) o;

            Map propertyValues = new HashMap();
            
            propertyValues.put("field1", cc.field1);
            propertyValues.put("field2", cc.field2);
            
            return new ClassObject("CustomClass", propertyValues);
        }
        else
        {
            // process other classes
        }
    }

    public Object toObject(final ClassObject co)
    {
        if ("CustomClass".equals(co.className))
        {
            CustomClass cc = new CustomClass();
            
            cc.field1 = (Integer) co.propertyValues.get("field1");
            cc.field2 = (String) co.propertyValues.get("field2");

            return cc;
        }
        else
        {
            // process other classes
        }
    }
    
    // other methods necessary for amf3 serializing/deserializing
}

com.smaxe.logger.ILogger

The library doesn't use any specific logging system. It provides a simple interface that lets you either integrate the library with any logging library or use ILogger implementations provided in the com.smaxe.logger.support package.

public interface ILogger
{
    /**
     * Logs the message.
     * 
     * @param level message level
     * @param message message to log
     * @param t thrown exception, null if the exception is not thrown
     * @param args optional arguments
     */
    public void log(final int level, final String message, final Throwable t, final Object... args);
}

java.net.Proxy

You can define proxy server to use. Proxy instance is used as Socket constructor parameter. The default value is Proxy.NO_PROXY.

Chapter 4. Usage examples

 
 com.smaxe.uv.client.rtmp.License.setKey("00000-00000-00000-00000-00000");
 

 
 NetConnection connection = new NetConnection();
 // configure 
 connection.configuration().put(NetConnection.Configuration.INACTIVITY_TIMEOUT, -1 /*seconds, -1 means indefinite timeout*/);
 connection.configuration().put(NetConnection.Configuration.PAGE_URL, "www.myhost.com/app");
 // etc...

 NetConnection connection = new NetConnection();

 // configure connection (if necessary)

 // set callback object
 connection.client(new Object()
 {
     // note: this method is invoked in the Dispatch-Thread
     public boolean test()
     {
         System.out.println("NetConnectionCallback#test");
         
         return true;
     }
 });
 
 // add event listener to get notified about connection status change
 connection.addEventListener(new NetConnection.ListenerAdapter()
 {
     // note: this method is invoked in the Dispatch-Thread
     public void onNetStatus(final INetConnection source, final Map info)
     {
         final Object code = info.get("code");
         
         if (NetConnection.CONNECT_SUCCESS.equals(code))
         {
             System.out.println("Connected to the server!");
         }
     }
 });
 
 connection.connect("rtmp://localhost:1935/live", "arg1", "arg2" /*arguments*/);
 
 // wait till NetConnection.CONNECT_SUCCESS message is received
 // ... waiting ...
 
 // invoke server method
 connection.call("testConnection", new com.smaxe.uv.Responder()
 {
     // note: this method is invoked in the Dispatch-Thread
     public void onResult(final Object result)
     {
         System.out.println("Method testConnection result: " + result);
     }
     
     // note: this method is invoked in the Dispatch-Thread
     public void onStatus(final Map status)
     {
         System.out.println("Method testConnection status: " + status);
     }
 }, "arg3", "arg4" /*arguments*/);
 

 
 NetConnection connection = new NetConnection();
 
 // ... configure and connect ... 
 
 SharedObject so = new SharedObject(name);
 
 so.addEventListener(new ISharedObject.ListenerAdapter()
 {
     // note: this method is invoked in the Scheduler-Thread
     public void onSync(ISharedObject source, final List changeList)
     {
         for (ISharedObject.Change change : changeList)
         {
             switch (change.code)
             {
                 case ISharedObject.Change.CONNECT:
                 {
                     // connected to the remote shared object
                 } break;
                 case ISharedObject.Change.CHANGE:
                 {
                     // change.attribute data was changed from the change.oldValue
                     // to the change.newValue
                 } break;
                 case ISharedObject.Change.STATUS:
                 {
                     // shared object status notification
                 } break;
             }
         }
     }
 });
 
 so.connect(connection, name);
 

 
 NetConnection connection = new NetConnection();
 
 // ... configure and connect ... 
 
 NetStream stream = new NetStream(connection);
 
 stream.addEventListener(new NetStream.ListenerAdapter()
 {
     @Override
     public void onNetStatus(final INetStream source, final Map info)
     {
         final String code = (String) info.get("code");
         
         if (NetStream.PUBLISH_START.equals(code))
         {
         }
         else
         if (NetStream.UNPUBLISHED_SUCCESS.equals(code))
         {
         }
     }
 });
 
 final MediaStreamController controller = new MediaStreamController();
 
 stream.attachAudio(new MediaStreamMicrophone(controller));
 stream.attachCamera(new MediaStreamCamera(controller), -1);
 
 stream.publish("streamName", NetStream.LIVE);
 
 controller.play(new FlvFileMediaStream("stream.flv"), -1 /*play the whole file*/);
 

 
 public final class MyMicrophone extends AbstractMicrophone
 {
     // starts microphone capture
     public void start()
     {
         new Thread(new Runnable()
         {
             while (true)
             {
                 byte[] data = getAudioData(); // returns audio data captured from your source
                 
                 fireOnAudioData(new MediaDataByteArray(33 /*relative time*/, new ByteArray(data)));
                 
                 try
                 {
                     Thread.sleep(33);
                 {
                 catch (Exception e) {}
             }
         }).start();
     }
 }
 
 NetConnection connection = new NetConnection();
 
 // ... configure and connect ... 
 
 NetStream stream = new NetStream(connection);
 
 stream.addEventListener(new NetStream.ListenerAdapter()
 {
     @Override
     public void onNetStatus(final INetStream source, final Map info)
     {
         final String code = (String) info.get("code");
         
         if (NetStream.PUBLISH_START.equals(code))
         {
         }
         else
         if (NetStream.UNPUBLISHED_SUCCESS.equals(code))
         {
         }
     }
 });
 
 MyMicrophone mic = new MyMicrophone();
 
 stream.attachAudio(mic);
 
 stream.publish("streamName", NetStream.LIVE);
 
 mic.start();