StraaSCircallSDK

Overview

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

Getting Started

This shows you how to start a CirCall step by step. You could read StraaS CirCall guides for CirCall basic concept first.

CirCall is a video conferencing API which provides the following functionalities:

• different people count video conferencing
  • 2p80v: 2 publishers, 80 viewers (reference for publisher and viewer ). For interactive broadcasting use case.
  • 4p: 4 publishers. For small meetings, card games.
  • 2p: 2 publishers. 1 to 1 meeting.
• record video on the cloud

When you start to use CirCall, you need to setup SDK with Auth.

After you setup SDK, CirCall would need to go through this flow:

• initialize: call this to get a STSCircallManager instance.
• prepare: prepare your local media if you have permission granted.
• connect: connect to CirCall room.
• publish: publish your local media streaming to CirCall room.
• subscribe & CircallStream set stream: subscribe and set stream upon to view remote stream.

Installation

Requires Swift 4.0/Xcode 9.3 or later.

Set Build Active Architecture Only to "Yes": CirCall supports x86_64, armv7, arm64, but not i386, so for runing on simulator, you might need to set Build Active Architecture Only to "Yes". If you don't use CirCall module, then you can set it to "NO".

CocoaPods

Add following lines to your Podfile:

  pod 'StraaS-iOS-SDK/Circall'

Then run pod install in the command line.
(You might need to do pod repo update before pod install.)

Auth

You need to get app token and CirCall token from Authentication. And then fulfill client_id on Xcode to enable StraaS CirCall SDK.

Initial

• To get a CircallManager, you should call [[CircallManager alloc] init] or [CircallManager new].
• You have to get the permission of camera and microphone for CircallManager first, too.

Prepare

• After getting a CircallManager, you can use preapare to put configuration in CircallManager to create a local stream that you can publish later. For users who subscribe stream only, it's not necessary to call prepare.

STSCircallStreamConfig * streamConfig = [STSCircallStreamConfig new];
streamConfig.minVideoSize = CGSizeMake(640, 360);
    
[self.circallManager prepareForCameraCaptureWithStreamConfig:streamConfig success:^(STSCircallStream * stream) {
    weakSelf.pictureInPictureVideoView.stream = stream;
    // success callback
} failure:^(NSError *error) {
    // failure callback
}];

• STSCircallStreamConfig: It is for setting max video size and mix video size while publishing or subscribing.
• STSCircallStream: You would need to use the stream in the callback to render on STSCircallPlayerView by setting the stream.
• You can set up delegate STSCircallManagerDelegate to receive delegate callback from STSCircallManager, too.

Connect

You would need to connect to a "room" to publish your local stream or subscribe to streams in the room. Here is a snippet for showing how to connect to a room.

[self.circallManager connectWithCircallToken:circallToken success:^{
    // success callback
} failure:^(NSError * _Nonnull error) {
    // failure callback
}];

circallToken is a token for accessing CirCall API, you would need to get it with CirCall token API from your backend.

Publish

You would need corresponding role to publish your stream.
To publish your local stream, you would need to prepare STSCircallPublishConfig to set up the max video and audio bit rate.

STSCircallPublishConfig * config = [STSCircallPublishConfig new];
config.maxVideoBitrate = @(600000);
config.maxAudioBitrate = @(64000);
[weakSelf.circallManager publishWithConfig:config success:^{
    NSLog(@"publishWithConfig success");
} failure:^(NSError * _Nonnull error) {
    NSLog(@"publishWithConfig failure");
}];

STSCircallPublishConfig 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.

Subscribe

Users in a room can subscribe published streams in the room. You may find the newly added stream from STSCircallManagerDelegate, and then you can subscribe to it.

- (void)circallManager:(STSCircallManager *)manager didAddStream:(STSCircallStream *)stream {
    __weak STSCircallSingleVideoCallViewController *weakSelf = self;
    [manager subscribeStream:stream success:^(STSCircallStream * _Nonnull stream) {
        weakSelf.fullScreenVideoView.stream = stream;
    } failure:^(STSCircallStream * _Nonnull stream, NSError * _Nonnull error) {
        weakSelf.viewControllerState = STSCircallSingleVideoCallViewControllerStateConnected;
        weakSelf.fullScreenVideoView.stream = stream;
    }];
}

Reder stream on STSCircallPlayerView

Just set stream property on STSCircallPlayerView to render stream on STSCircallPlayerView.
You can change STSCircallScalingMode to have different scaling mode, too.

self.fullScreenVideoView.stream = stream;

Recording

You would need the corresponding role to record self or other people's stream.

[self.circallManager startRecordingStream:self.fullScreenVideoView.stream success:^{
    weakSelf.recordingState = STSCircallSingleVideoCallViewControllerRecordingStateRecording;
} failure:^(NSError * _Nonnull error) {
    weakSelf.recordingState = STSCircallSingleVideoCallViewControllerRecordingStateIdel;
    [weakSelf showAlertWithTitle:@"Error" message:[NSString stringWithFormat:@"start record failed with error:%@",error]];
}];

Error Codes

You might get the errors from the STSCircallManagerDelegate delegate method - (void)circallManager:(STSCircallManager *)manager onError:(NSError *)error;.
The file NSError+StraaSCircallSDK.h lists the CirCall errors.

Configs

We provide three configs for different purposes:

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

getVideoFrame in STSCircallPlayerView

You can get an image out of the view and save it to the album. Notice: the image you get is slightly bigger than the actual stream size. The behavior now is different from Android, which will get the image from the stream.