CirCall

Overview

StraaS CirCall SDK provides a easy way to establish a video conferencing to StraaS CirCall service!

Getting Started

This shows you how to start a CirCall video calling step by step. You could read javadoc for more detail about the code 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'

Permission

Before using CircallManager, you have to get permission of camera and microphone for CircallManager prepare.

Credential

Fulfill StraaS SDK-Credential to enable StraaS CirCall SDK.

Initialize CircallManager

• CircallManager is the main class to use CirCall service. It can be used to connect to a room, publish and subscribe streams, 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 -> {
    // handle error
});

Prepare

• After getting a CircallManager, you can use prepare to put local media configuration in CircallManager and then initialize them.

CircallConfig config = new CircallConfig()
                .camera(CircallConfig.CAMERA_FRONT)
                .videoResolution(1280, 720)
                .build();

mCircallManager.prepare(config, playerView, playConfig).addOnSuccessListener(task -> {
    // Keep your local CircallStream
    mLocalCircallStream = task.getResult();
    ...
}).addOnFailureListener(task -> {
    // Handle error
});

• circallConfig allows you to specify configuration for your local media.
• playerView is a TextureView wrapper class where you want to preview on. After prepare succeeds, you will get a CircallStream to get stream ID, setRenderer, get current video frame, etc, please refer the CircallStream section for more details.
• playConfig allows you to specify scaling mode for your playerview.

Set listener

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

Start CirCall

After prepare succeeds, you will be able to start CirCall video calling by the two steps below:

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

mCircallManager.connect(token).continueWithTask(task -> {
    if (!task.isSuccessful()) {
        Log.e(TAG, "join fails: " + task.getException());
        return Tasks.forException(task.getException());
    }
}

• Then use publish to start publishing your local stream to room and update UI(we use Data Binding Library for CirCall samples):

if (mCircallManager != null && mCircallManager.getCircallState() == CircallManager.STATE_CONNECTED) {
    mCircallManager.publish(getPublishConfig()).addOnCompleteListener(task -> {
        // update UI accordingly
        mBinding.setState(STATE_CONNECTED);
        mBinding.setShowActionButtons(true);
    });
}

• publishConfig allows you to specify audio and video bitrate for your publish streaming.

After the operation succeeds, it means you are connected with StraaS CirCall room and publishing your local stream to everyone in the same room.

• Optionally use subscribe to start subscribing remote stream and add its video streaming into your UI:

@Override
public void onStreamAdded(CircallStream stream) {
    Log.d(TAG, "onStreamAdded: " + stream);
    if (mCircallManager != null && stream != null) {
        mCircallManager.subscribe(stream);
    }
}

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

Disconnect / destroy CirCall

• To disconnect CircallManager, you can call disconnect to disconnect from CirCall room and still got previewing.

mCircallManager.disconnect().addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        // success handling
    } else {  
       // error handling
    }
});

• To destroy CircallManager, you can call destroy to stop CirCall and previewing.

mCircallManager.destroy().addOnCompleteListener(task -> {
    // Handle result
});

Events

• The following list shows what events you'll receive during ongoing video calling, you could register event handlers from Set listener section:

  • onStreamAdded: for remote stream published to the room recently, you could use the passed CircallStream to subscribe that new remote stream
  • onStreamSubscribed: for subscribed remote stream, you could use the CircallStream to setRenderer to your customized view
  • onStreamRemoved: for remote stream unpublished from the room, you should remove or hide that corresponding view
  • onError: could be one of NetworkException, PublishStreamException or SubscribeStreamException you could visit CircallException for more details.

you can ref EventListener docs for more details.

CircallStream

• Local CircallStream can be obtained by CircallManager.prepare, while remote streams can be obtained by onStreamAdded or onStreamSubscribed for subscribe and setRenderer operation respectively. You should keep CircallStream from onStreamSubscribed for the following operation, such as getVideoFrame, etc.

• CircallStream related callbacks from EventListener during ongoing video calling: onStreamAdded, onStreamSubscribed and onStreamRemoved, see doc for more detail

Configs

We provide three configs for different purposes:

• CircallConfig allows you to specify configs for preparing local streams , it determines including front/back camera and targeting camera video size, etc.
• CircallPlayConfig allows you to specify configs for rendering(playing) local or remote streams, it determines how video stream scaled on your renderer view, etc.
• CircallPublishConfig allows you to specify configs for publishing the local streams, it determines max video and audio bitrate, etc.

Error Codes

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

• As for the onError events you listening from addEventListener, you could visit CircallException for more details.

Overall flow

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

1. CircallManager.initialize: call this to get a CircallManager instance.
2. CircallManager.prepare: prepare you local media if you have permission granted.
3. CircallManager.connect: connect to CirCall room.
4. CircallManager.publish: publish your local media streaming to CirCall room.
5. CircallManager.subscribe & CircallStream.setRenderer: subscribe and setRenderer upon onStreamAdded and onStreamSubscribed respectively to view remote subscribed stream.

Build CirCall demo app

# ./gradlew :circallDemo:assembleDebug

You can see API document for more details.