Streaming - Straas/Straas-iOS-sdk GitHub Wiki

Overview

StraaS Streaming SDK provides an easy way to establish a Real-Time streaming to StraaS!

Installation

Requires Swift 4.0/Xcode 9.3 or later.

If you need Swift 3.x/Xcode 9.2(or eariler) use the v0.13.0.

CocoaPods

Add following lines to your Podfile:

pod 'StraaS-iOS-SDK/Streaming'

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

Getting Started

Note: Before using the SDK, you need to configuration your application first.

Permission

StraaS Streaming SDK needs the permission of the camera and the microphone. You must add the NSCameraUsageDescription and NSMicrophoneUsageDescription key in your app's Info.plist to access the device's camera in iOS 10.0 and later.

Initialize

After successfully configured application, create an STSStreamingManager instance directly.

NSString * JWT;
STSStreamingManager *streamingManager = [STSStreamingManager streamingManagerWithJWT:JWT];

JWT is the broadcaster's member token. Each logged-in StraaS member has a JWT as user identity. (How to get a JWT)

STSStreamingManager instance methods execute asynchronously. Delegate method or handler block will be called when operation completed.

Preparation

After getting a streaming manager, you should call prepareWithPreviewView:configuration:success:failure: method to put configuration in the streaming manager before starting to stream.

UIView *yourPreviewView = [UIView view];

UIInterfaceOrientation theOrientationYouWant = UIDeviceOrientationPortrait;
STSStreamingPrepareConfig * configuration = [STSStreamingPrepareConfig new];
config.outputImageOrientation = theOrientationYouWant;
config.targetOutputSize = CGSizeMake(kSTSStreamingVideoWidth, kSTSStreamingVideoHeight);
[self.streamingManager prepareWithPreviewView:self.previewView
                                configuration:configuration
                                      success:^(CGSize outputVideoSize){
                                      }
                                      failure:^(NSError * error) {
                                      }];

previewView is a UIView where you want to preview the live stream.

If you do not want to set outputSize directly, you can set fitAllCamera and maxResolution instead. The streaming manager will auto calculate the output size according to the aspect ratio of the preview view and these parameters.

UIView *yourPreviewView = [UIView view];

UIInterfaceOrientation theOrientationYouWant = UIDeviceOrientationPortrait;
STSStreamingPrepareConfig * configuration = [STSStreamingPrepareConfig new];
config.fitAllCamera = YES;
config.maxResolution = STSStreamingResolution720p;
config.targetOutputSize = CGSizeMake(kSTSStreamingVideoWidth, kSTSStreamingVideoHeight);
[self.streamingManager prepareWithPreviewView:yourPreviewView
                                configuration:configuration
                                      success:^(CGSize outputVideoSize){
                                      }
                                      failure:^(NSError * error) {
                                      }];

Start streaming

After successfully preparing, you will be able to start your stream.

One-Step Flow

NSString *title = @"The title of the live event";
NSString *synopsis = @"The synopsis of the live event";
NSString *JWT = @"The member token you get from the server."

STSStreamingLiveEventConfig * configuration =
[STSStreamingLiveEventConfig liveEventConfigWithTitle:title listed:YES];
confguration.synopsis = synopsis;
// Set the live event category.
// confguration.categoryId = <#CATEGORY_ID_OF_LIVE_EVET#>
// Set the tags of the live event.
// confguration.tags = @[@"<#ANY_TAGS#>"];
[self.streamingManager startStreamingWithConfguration:configuration success:^(NSString * liveId) {
} failure:^(NSError * error, NSString * liveId){
}];

Two-Step Flow

If you need to get the live event id before streaming starts, you can create a live by calling createLiveEventConfguration:success:failure: method first.

NSString *title = @"The title of the live event";
NSString *synopsis = @"The synopsis of the live event";
NSString *JWT = @"The member token you get from sever."

STSStreamingLiveEventConfig * configuration =
[STSStreamingLiveEventConfig liveEventConfigWithTitle:title listed:YES];
confguration.synopsis = synopsis;
// Set the live event category.
// confguration.categoryId = <#CATEGORY_ID_OF_LIVE_EVET#>
// Set the tags of the live event.
// confguration.tags = @[@"<#ANY_TAGS#>"];

[self.streamingManager createLiveEventConfguration:configuration success:^(NSString * liveId) {
} failure:^(NSError * error, NSString * liveId){
}];

Then start streaming by calling startStreamingWithliveId:success:failure: method.

NSString * liveId; //The liveId you get from the success block of `createLiveEventConfguration:success:failure:`.
[self.streamingManager startStreamingWithliveId:liveId success:^ {
} failure:^(NSError * error){
}];

Stop streaming

You can call stopStreaming to stop streaming and preview.

[streamingManager stopStreamingWithSuccess:^(NSString * liveId) {
} failure:^(NSError * error, NSString * liveId) {
}];

See API Document for more details.

Conforms to `STSStreamingManagerDelegate`

You can observe the streaming statistics and errors by STSStreamingManagerDelegate. In some bad network situations, if the bitrate is too low, then the player may not receive enough video frames to display.

Here is the sample code to adopt the protocol:

#pragma mark - STSStreamingManagerDelegate

- (void)streamingManager:(STSStreamingManager *)streamingManager
                 onError:(NSError *)error
                  liveId:(NSString * _Nullable)liveId
{
    NSString * errorTitle = @"STSStreamingManager encounters an error.";
    NSString * errorMsg = [NSString stringWithFormat: @"Error: %@.\nLive id = %@", error, liveId];
    [self onErrorWithTitle:errorTitle message:errorMsg]; // show the error on UI
}

- (void)streamingManager:(STSStreamingManager *)streamingManager didUpdateStreamingStatsReport:(STSStreamingStatsReport *)statsReport {
    dispatch_async(dispatch_get_main_queue(), ^{
        [self updateUIWithBitrate:statsReport.currentBitrate]; // show the bitrate on UI
        [self updateUIWithFPS:statsReport.currentFPS]; // show the current FPS on UI
    });
}

SkinBeautifyFilter

Streaming module is able to smooth and whitening faces on video. For beautifying skin, you can use the class STSSkinBeautifyFilter or create your own filter, and then set it on property GPUImageFilterGroup *filterGroup in STSStreamingManager.h.

This is an example of initializing a proper STSSkinBeautifyFilter and GPUImageFilterGroup.

// STSStreamingViewController.m
self.skinBeautifyFilter = [STSSkinBeautifyFilter filter];

GPUImageFilterGroup *filterGroup = [[GPUImageFilterGroup alloc] init];
[filterGroup addFilter:self.skinBeautifyFilter];
[filterGroup setInitialFilters:@[self.skinBeautifyFilter]];
[filterGroup setTerminalFilter:self.skinBeautifyFilter];
self.skinBeautifyFilterGroup = filterGroup;