CirCall IPCamBroadcasting

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 ultra-low latency.

You could read StraaS CirCall guides for Circall basic concept first.

Flow

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

• initialize: Call this to get a STSCircallManager instance.
• prepare: To prepare for sending/receiving RTSP stream.
• connect: To connect to CirCall room.
• publish: The host needs to publish the RTSP streaming to the CirCall room.
• subscribe & set stream: subscribe and set stream upon to view remote stream. For the host, he/she needs to subscribe self RTSP stream also.

Getting Started

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

Installation

Circall RTSP available from v0.20.0.

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.

For IPCam broadcasting scenario, it uses the following token:

• 2p80v: 2 publishers, 80 viewers (reference for publisher and viewer ). For interactive broadcasting use case.

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

Initialize

• To get a CircallManager, you should call [[CircallManager alloc] init] or [CircallManager new].

Prepare

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

[self.circallManager prepareForUrlWithSuccess:^(STSCircallStream * stream) {
    // success callback
} failure:^(NSError *error) {
    // failure callback
}];

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.

Set STSCircallManagerDelegate

You can use STSCircallManagerDelegate to receive callbacks about error and room events (didAddStream, didRemoveStream, onError).

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 a IPCam).

STSCircallPublishWithUrlConfig *config = [[STSCircallPublishWithUrlConfig alloc] initWithUrl:weakSelf.url];
[weakSelf.circallManager publishWithUrlConfig:config success:^(STSCircallStream * _Nonnull stream) {
    // success callback
} failure:^(NSError * _Nonnull error) {
    // failure callback
}];

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, that is, host.

[weakSelf.circallManager publishWithUrlConfig:config success:^(STSCircallStream * _Nonnull stream) {
    subscribeStream(stream);
} failure:^(NSError * _Nonnull error) {
    // failure callback
}];

• If you are not the one who publishes the stream, that is, viewer.

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

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

[manager subscribeStream:stream success:^(STSCircallStream * _Nonnull stream) {
    weakSelf.hostView.stream = stream;
} failure:^(STSCircallStream * _Nonnull stream, NSError * _Nonnull error) {
    weakSelf.hostView.stream = nil;
}];

Disconnect

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, Unpublish and Disconnect

void (^disconnectCircall)() = ^() {
    [weakSelf.circallManager disconnectWithSuccess:^{
        popViewController();
    } failure:^(NSError * _Nonnull error) {
        popViewController();
    }];
};

void (^unsubscribe)() = ^() {
    [weakSelf.circallManager unpublishWithSuccess:^{
        disconnectCircall();
    } failure:^(NSError * _Nonnull error) {
        disconnectCircall();
    }];
};

[weakSelf.circallManager unsubscribeStream:self.hostView.stream success:^{
    unsubscribe();
} failure:^(NSError * _Nonnull error) {
    unsubscribe();
}];

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.

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.