Circall Publish with URL

Overview

StraaS CirCall SDK provides an easy way for streaming video from the IPCam to audiences. There are two types of characters in this scenario.

• Host: The host can pass the RTSP URL to the room for triggering the room to receive the video stream from the IPCam.
• Viewer: Viewers can subscribe the stream from the room, then they can watch the video from the IPCam in real time.

Flow

The figure below shows the overall CirCall sample app usage flow:

1. CircallManager.initialize: call this to get a CircallManager instance.
2. CircallManager.prepareForUrl: prepare something before you connect to a CirCall room.
3. CircallManager.connect: connect to a CirCall room.
4. CircallManager.publishWithUrl: publish the remote source(Should be RTSP, e.g. RTSP stream from a IPCam) to the CirCall room.
5. CircallManager.subscribe & CircallStream.setRenderer: subscribe and setRenderer upon onStreamAdded/onStreamPublished and onStreamSubscribed respectively to view remote subscribed stream.

Build CirCall demo app

You can use this command to build a demo app of our sample.

# ./gradlew :circallDemo:assembleDebug

Getting Started

This shows you how to start step by step.
You could read javadoc for more detail about the codes this page mentions below.

Include

Add dependency on jCenter using Gradle.

X.X.X is your preferred version, CirCall Android SDK starting from StraaS SDK version 0.10.0. For the version information, see CHANGELOG

compile 'io.straas.android.sdk:straas-circall:X.X.X'

Credential

Fulfill StraaS SDK-Credential to enable StraaS CirCall SDK.

Initialize CircallManager

• CircallManager is the main class to use CirCall service. You can use it to connect to a room, publish and subscribe streams, and start and stop recording for a specific stream with a specified CirCall token. To get a CircallManager, you should call CircallManager#initialize. You will get a CircallManager if task succeeds.

CircallManager.initialize().addOnSuccessListener(task -> {
    // Keep your CircallManager
    mCircallManager = task.getResult();
}).addOnFailureListener(task -> {
    // Error handle
});

Prepare

• After getting a CircallManager, you can use prepareForUrl to prepare and change the Circall state to STATE_PREPARED.

mCircallManager.prepareForUrl(context).addOnSuccessListener(task -> {
    ...
}).addOnFailureListener(task -> {
    // Error handle 
});

Set listener

You can use addEventListener to add listener about error and other room related events, see the Events section for more details.

Connect to a room

After prepareForUrl succeeds, you will be able to connect to a room. Then, you can interactive with other people in the same room.

• Use connect to connect to room with your CirCall token.

CircallToken token = new CircallToken("<token>");
mCircallManager.connect(token).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        // Success
    } else {
        // Error handle
    }
});

Publish

If you are in a room already, you can use publishWithUrl to publish the remote source(Should be RTSP, e.g. RTSP stream from an IPCam).

• We use Data Binding Library for CirCall samples:

CircallPublishWithUrlConfig config = new CircallPublishWithUrlConfig.Builder().url("<RTSP URL>").build()

mCircallManager.publishWithUrl(config).addOnCompleteListener(task -> {
    // Update UI accordingly
    mBinding.setState(STATE_CONNECTED);
    mBinding.setShowActionButtons(true);
});

Subscribe

After publish succeeds, it means you are publishing the RTSP source as a stream to the room.
Then, everyone in the same room, including you, can subscribe the stream:

• If you are the one who publishes the stream.

@Override
public void onStreamPublished(CircallStream stream) {
    if (mCircallManager != null && stream != null) {
        mCircallManager.subscribe(stream);
    }
}

• If you are not the one who publishes the stream.

@Override
public void onStreamAdded(CircallStream stream) {
    if (mCircallManager != null && stream != null) {
        mCircallManager.subscribe(stream);
    }
}

Moreover, remember to add this video stream into your UI after the subscription succeeds.

• Use CircallStream#setRenderer to do this:

@Override
public void onStreamSubscribed(CircallStream stream) {
    mBinding.fullscreenVideoView.setVisibility(View.VISIBLE);
    stream.setRenderer(mBinding.fullscreenVideoView, CircallPlayConfig.ASPECT_FILL);
    mRemoteCircallStream = stream;
}

Disconnect / destroy CirCallManager

Call disconnect when you want to leave the room.
But before you disconnect, remember to call unsubscribe for all CircallStreams you are subscribing and unpublish if you are publishing.

• Unsubscribe

mCircallManager.unsubscribe(mSubscribedCircallStream);

• Unpublish

mCircallManager.unpublish();

• Disconnect

mCircallManager.disconnect();

• If you don't use CircallManager any more, call CircallManager#destroy;

mCircallManager.destroy();

Events

The following list shows what events you are able to receive in a room.
You could read Set listener to know how to register events.

• onStreamAdded: Received when other people publish a stream to the room. You could subscribe the CircallStream if you want.
• onStreamPublished: Received when your publishing succeeds and and the CircallStream is ready for subscribing.
• onStreamSubscribed: Received when your subscription succeeds. It means you can add this video streaming into your UI.
• onStreamUpdated: Received when the information of a remote stream is updated.
• onStreamRemoved: Received when someone unpublishes a remote stream from the room. It means you can't receive this remote stream anymore.
• onError: Received when an error happens. The error could be one of NetworkException, PublishStreamException or SubscribeStreamException. Visit CircallException for more details.

You can refer to EventListener docs for more details.

Error Codes

• All async operations of StraaS Android CirCall SDK return google gms task. When an error occurs, task will be returned with an Exception. Please check Circall.exception to do error handling.

• As for the onError events you receive from EventListener, you could visit CircallException for error handling.

API document

You can refer to API document for more details.