iOS Streaming SDK

The Red5 Pro iOS Streaming SDK provides to ability to both broadcast and subscribe to a live stream containing audio and video.

This short tutorial will introduce you to the Red5 Pro iOS Streaming SDK API and instruct you in setting up a basic project in XCode to publish and subscribe to a stream on the Red5 Pro Server.

You will need the latest Red5 Pro iOS Streaming SDK before you begin.

Download the Red5 Pro iOS Streaming SDKs Download the latest Streaming SDK for iOS

Additionally, you will need to use the Mobile SDK License associated with your Red5 Pro Account.


Project Setup

  1. Open XCode and Create a New Project
  2. Select a Tabbed Application as the project template
  3. Fill in the appropriate values in the project options and save the project to an approriate place. For this example, we named the project Red5ProStreaming.

show view

* It is important to note that the Red5 Pro Streaming SDK currently does not work in the IOS Simulator. All deployment and testing should be done on an actual iOS device.

With the new project created in XCode:

  1. Unzip the Red5 Pro iOS Streaming SDK
  2. Drag the R5Streaming.framework folder and drop into the newly created project in XCode
  3. Be sure to select 'Copy items…' and 'Create groups…' with your project as a target in the dialog that will appear show view

    show view

  4. With the framework linked with your project, you will also need the following frameworks and libraries:

       CoreFoundation
       OpenAL
       QuartzCore
       VideoToolbox
    
       libz
       libbz2.1.0
       libstdc++
       libiconv
       libz2.1.0.tbd
       VideoToolbox
     
  5. To add these frameworks, select the Project target in XCode and focus on the General panel
  6. Find the Linked Frameworks and Libraries section and click the + button on the bottom left
  7. Select the frameworks and libraries detailed above

show view

With the project setup as a Tabbed Application and the proper libraries and frameworks defined, we can begin adding code to broadcast and subscribe to a stream.

Publisher

Included in the Red5 Pro iOS Streaming SDK is a R5VideoViewController which is an extension of the UIViewController and exposes an API to easily attach a stream for broadcasting. To complete the Publisher section of this example app, we will create an extension of the R5VideoViewController that will be responsible for creating a stream based on a custom configuration and expose an API to start and stop broadcsting.

Publisher Clean Slate

  1. Select the Main.storyboard of the project and expand the First View Controller. We will be modifying this View Controller to broadcast from the camera on the iOS device.
  2. Select the Tab Bar Item entry, and open the Attributes Inspector
  3. Give the Bar Item a title of 'Publish' show view
  4. Select all the UI content in the View of First View Controller and delete it. We will add custom UI a little later.

PublishViewController

  1. Drag a View Controller from the Object Library and drop it into the storyboard alongside the First View Controller
  2. ;With the View Controller selected, focus on the Identity Inspector and change the Custom Class field to PublishViewController
  3. ;Still within the Identity Inspector for the View Controller, assign a Storyboard ID of publishView
  4. ;From the Project Explorer Right-Click on the Red5ProStreaming folder and select New File…
  5. ;Choose Object-C class from the wizard dialog and Next
  6. ;In the Class field, set PublishViewController and choose R5VideoViewController for Subclass of field
  7. ;Select Next and add to project at current location
  8. ;Open the PublishViewController.h header, define as an R5StreamDelegate and add start and stop methods to the interface

     @interface PublishViewController : R5VideoViewController<R5StreamDelegate>
    
     -(void)start;
     -(void)stop;
    
     @end
    
  9. Open the PublishViewController.m, import the R5Streaming header and add variables to the internal interface for an R5Configuration and R5Stream instance:

     #import "PublishViewController.h"
     #import <R5Streaming/R5Streaming.h>
    
     @interface PublishViewController () {
         R5Configuration *config;
         R5Stream *stream;
     }
     @end
    

Add your SDK license key (required)

  1. In the viewDidLoad override in PublishViewController.m, create the R5Configuration that will be used in a streaming session(s).

    • Change the host attribute to point to the location of your Red5 Pro server.
    • Change the SDK license key to the one provided from your Red5 Pro Account.

      ```objective-c

    • (void)viewDidLoad { [super viewDidLoad];

      config = [R5Configuration new]; config.host = @"localhost"; config.port = 8554; config.contextName = @"live"; config.licenseKey = @"YOUR-SDK-LICENSE-KEY"; } ```

  2. Create a new method named preview: that will be responsible for setting up a stream to be shown and broadcast and access the audio and video devices that will be used in the stream

     -(void)preview {
         NSArray *cameras = [AVCaptureDevice devicesWithMediaType:AVMediaTypeVideo];
         AVCaptureDevice *cameraDevice = [cameras lastObject];
         R5Camera *camera = [[R5Camera alloc] initWithDevice:cameraDevice andBitRate:512];
    
         AVCaptureDevice *audioDevice= [AVCaptureDevice defaultDeviceWithMediaType:AVMediaTypeAudio];
         R5Microphone *microphone = [[R5Microphone new] initWithDevice:audioDevice];
     }
    
  3. Within the preview: method, establish a new R5Connection with the R5Configuration and intialize a new R5Stream instance with the connection and device references

     ...
     R5Connection *connection = [[R5Connection new] initWithConfig:config];
    
     stream = [[R5Stream new] initWithConnection:connection];
     [stream attachVideo:camera];
     [stream attachAudio:microphone];
     ...
    
  4. With a R5Stream instance created, attach as the stream for the PublishViewController and display as a preview
     [stream setDelegate:self];
     [self attachStream:stream];
     [self showPreview:YES];
    
  5. This will draw the camera stream into a context for preview before broadcasting to the Red5 Pro server. The full preview: method should look like such:

     -(void)preview {
          NSArray *cameras = [AVCaptureDevice devicesWithMediaType:AVMediaTypeVideo];
         AVCaptureDevice *cameraDevice = [cameras lastObject];
         R5Camera *camera = [[R5Camera alloc] initWithDevice:cameraDevice andBitRate:512];
    
         AVCaptureDevice *audioDevice= [AVCaptureDevice defaultDeviceWithMediaType:AVMediaTypeAudio];
         R5Microphone *microphone = [[R5Microphone new] initWithDevice:audioDevice];
    
         R5Connection *connection = [[R5Connection new] initWithConfig:config];
    
         stream = [[R5Stream new] initWithConnection:connection];
         [stream attachVideo:camera];
         [stream attachAudio:microphone];
    
         [stream setDelegate:self];
         [self attachStream:stream];
         [self showPreview:YES];
     }
    
  6. There are a few methods that are required in order to adhere to the interface contract of PublishViewController: start and stop

     -(void)start {
         [self showPreview:NO];
         [stream publish:@"red5prostream"];
     }
    
     -(void)stop {
         [stream stop];
         [stream setDelegate:nil];
         [self preview];
     }
    
  7. Note the NSString passed into the stream:publish: method. Change the publish stream name appropriately. These are the methods we defined on the interface for PublishViewController previously and will be invoked externally by UI controls in the app.
  8. Override the viewDidAppear: and viewWillDisappear: methods in order to control how the stream is maintained when changing views in our Tabbed Application

     - (void)viewDidAppear:(BOOL)animated {
         [super viewDidAppear:animated];
         [self preview];
     }
    
     - (void)viewWillDisappear:(BOOL)animated {
         [super viewWillDisappear:animated];
         [self stop];
     }
    
  9. To adhere to the contract of being a R5StreamDelegate add a onR5StreamStatus:withStatus:withMessage method
     -(void)onR5StreamStatus:(R5Stream *)stream withStatus:(int)statusCode withMessage:(NSString *)msg {
         NSLog(@"Stream: %s - %@", r5_string_for_status(statusCode), msg);
     }
    

That completes the PublishViewController implementation that will be used and interfaced with from the FirstViewController.

FirstViewController

We previously cleared out the view content of the FirstViewController in the storyboard. In this section we'll add a UIButton and TouchUpInside delegate that will interface with the start: and stop: methods defined on the PublishViewController.

  1. Select the Main.storyboard from the Project Explorer
  2. Drag a Button from the Object Library and drop it onto the View for the First View Controller
  3. Assign the Button instance as an IBOutlet in FirstViewController.h header file

     #import <UIKit/UIKit.h>
    
     @interface FirstViewController : UIViewController
    
     @property (weak, nonatomic) IBOutlet UIButton *publishButton;
    
     @end
    
  4. Define a TouchUpInside responder for the Button in FirstViewController.m
     - (IBAction)onPublishToggle:(id)sender {
     }
    
  5. With the FirstViewController.m open, import the PublishViewController.h header and assign a couple attributes on the internal interface
     @interface FirstViewController () {
         PublishViewController *publisher;
         BOOL isPublishing;
     }
     @end
    

Since the PublishViewController is not linked with the Tabbed Application we have created, we are going to pull in the View Controller and its underlying UIView to the FirstViewController so that we can view and interact with the stream.

  1. Override the viewDidLoad: method of FirstViewController, instantiate the PublishViewController add its UIView as a subview underneath the UIButton control previously added

     - (void)viewDidLoad {
         [super viewDidLoad];
    
         UIStoryboard *storyboard = [UIStoryboard storyboardWithName:@"Main" bundle:nil];
         UIViewController *controller = [storyboard instantiateViewControllerWithIdentifier:@"publishView"];
    
         CGRect frameSize = self.view.bounds;
         publisher.view.layer.frame = frameSize;
         publisher = (PublishViewController *)controller;
    
         [self.view addSubview:publisher.view];
         [self.view sendSubviewToBack:publisher.view];
     }
    
  2. If you remember from our PublishViewController when that gets attached, the stream will be created and a preview drawn to the context view. Additionally the view life cycle events will be passed down when switching between tabs in our Tab Application.
  3. Modify the onPublishToggle: button delegate to invoke the start: and stop: methods on the PublishViewController instance
     - (IBAction)onPublishToggle:(id)sender {
         if(isPublishing) {
             [publisher stop];
         }
         else {
             [publisher start];
         }
         isPublishing = !isPublishing;
         [[self publishButton] setTitle:isPublishing ? @"STOP" : @"START" forState:UIControlStateNormal];
     }
    
  4. To complete the FistViewController, override the viewDidAppear: and viewDidDisappear: methods to properly handle state

     -(void)viewDidAppear:(BOOL)animated {
         [super viewDidAppear:animated];
         [[self publishButton] setTitle:@"START" forState:UIControlStateNormal];
     }
    
     -(void)viewDidDisappear:(BOOL)animated {
         [super viewDidDisappear:animated];
         isPublishing = NO;
     }
    

Launching & Viewing Publisher

Ensure that you have a Red5 Pro Server running at the location defined in the R5Configuration of PublishViewController and select to build and deploy to a connected iOS device. When the application is launched on the device and the Publish tab is selected, you will see the stream from front-facing camera being drawn to the screen - this is currently a preview of what will be broadcst.

  1. Click the UI button and start publishing the stream
  2. Navigate to the live broadcast section of your Red5 Pro Server installation and select the stream by the name provided in the publish: call.

Subscriber

Just as we extended the R5VideoViewController of the Red5 Pro iOD Streaming SDK to create a Publisher, the R5VideoViewController exposes an API to easily attach a stream for consuming a live broadcast. To complete the Subsriber section of this example app, we will create an extension of the R5VideoViewController similar to the Publisher by adding another instance of a UIViewController to the storyboard and exposing an API to start and stop a subscriber session from the second scene of the Tabbed Application.

Subscriber Clean Slate

  1. Select the Main.storyboard of the project and expand the Second View Controller. We will be modifying this View Controller to broadcast from the camera on the iOS device.
  2. Select the Tab Bar Item entry, and open the Attributes Inspector
  3. Give the Bar Item a title of 'Subscribe' show view
  4. Select all the UI content in the View of Second View Controller and delete it. We will add custom UI a little later.

SubscribeViewController

  1. Drag a View Controller from the Object Library and drop it into the storyboard alongside the Second View Controller
  2. With the View Controller selected, focus on the Identity Inspector and change the Custom Class field to SubcribeViewController
  3. Still within the Identity Inspector for the View Controller, assign a Storyboard ID of subscribeView
  4. From the Project Explorer Right-Click on the Red5ProStreaming folder and select New File…
  5. Choose Object-C class from the wizard dialog and Next
  6. In the Class field, set SubscribeViewController and choose R5VideoViewController for Subclass of field
  7. Select Next and add to project at current location.
  8. Open the SubcribeViewController.h header and add start and stop methods to the interface

     @interface SubscribeViewController : R5VideoViewController
    
     -(void)start;
     -(void)stop;
    
     @end
    
  9. Open the SubscribeViewController.m, import the R5Streaming header and header and add variables to the internal interface for an R5Configuration and R5Stream instance:

     #import "SubscribeViewController.h"
     #import <R5Streaming/R5Streaming.h>
    
     @interface SubscribeViewController () {
         R5Configuration *config;
         R5Stream *stream;
     }
     @end
    
  10. In the viewDidLoad override in SubscribeViewController.m, create the R5Configuration that will be used in a streaming session(s).

    • Change the host attribute to point to the location of your Red5 Pro server.
    • Change the SDK license key to the one provided from your Red5 Pro Account.
    - (void)viewDidLoad {
        [super viewDidLoad];
    
        config = [R5Configuration new];
        config.host = @"localhost";
        config.port = 8554;
        config.contextName = @"live";
        config.licenseKey = @"YOUR-SDK-LICENSE-KEY";
    }
    
  11. The two methods added to the SubscribeViewController.h interface — start and stop — are all that will be needed to implement in order to interface with the Subscriber

    - (void)start {
        R5Connection *connection = [[R5Connection new] initWithConfig:config];
    
        stream = [[R5Stream new] initWithConnection:connection];
        [self attachStream:stream];
        [stream play:@"red5prostream"];
    }
    
    - (void)stop {
        [stream stop];
    }
    
  12. Note the NSString passed into the stream:play: method, this to the publish stream name appropriately. These are the methods we defined on the interface for SubscribeViewController previously and will be invoked externally by UI controls in the app.
  13. Override the viewWillDisappear:
    - (void)viewWillDisappear:(BOOL)animated {
        [super viewWillDisappear:animated];
        [self stop];
    }
    

That complete the SubscribeViewController implementation that be used and interfaced with from the SecondViewController.

SecondViewController

We previously cleared out the view content of the SecondViewController in the storyboard. In this section we'll add a UIButton and a TouchUpInside delegate that will interface with the start: and stop: methods defined on the SubscribeViewController.

  1. Select the Main.storyboard from the Project Explorer
  2. Drag Button from the Object Library and drop it onto th View for the Second View Controller
  3. Assign the Button instance as an IBOutlet in SecondViewController.h header file

     #import <UIKit/UIKit.h>
    
     @interface SecondViewController : UIViewController
    
     @property (weak, nonatomic) IBOutlet UIButton *subscribeButton;
    
     @end
    
  4. Define a TouchUpInside responder for the Button in SecondViewController.m
     - (IBAction)onSubscribeToggle:(id)sender {
     }
    
  5. With the SecondViewController.m open, import the SubscribeViewController.h header and assign a couple attributes on the internal interface
     @interface SecondViewController () {
         SubscribeViewController *subscriber;
         BOOL isSubscribing;
     }
     @end
    
  6. Since the SubscribeViewController is not linked with the Tabbed Application we have created, we are going to pull in the View Controller and its underlying UIView to the SecondViewController so that we can view and interact with the stream.
  7. Override the viewDidLoad: method of SecondViewController, instantiate the SubcribeViewController add its UIView as a subview underneath the UIButton control previously added

     - (void)viewDidLoad {
         [super viewDidLoad];
    
         UIStoryboard *storyboard = [UIStoryboard storyboardWithName:@"Main" bundle:nil];
         UIViewController *controller = [storyboard instantiateViewControllerWithIdentifier:@"subscribeView"];
    
         CGRect frameSize = self.view.bounds;
         subscriber.view.layer.frame = frameSize;
         subscriber = (SubscribeViewController *)controller;
    
         [self.view addSubview:subscriber.view];
         [self.view sendSubviewToBack:subscriber.view];
     }
    
  8. Modify the onSubscribeToggle: button delegate to invoke the start: and stop: methods on the SubscribeViewController instance
     - (IBAction)onSubscribeToggle:(id)sender {
         if(isSubscribing) {
             [subscriber stop];
         }
         else {
             [subscriber start];
         }
         isSubscribing = !isSubscribing;
         [[self subscribeButton] setTitle:isSubscribing ? @"STOP" : @"START" forState:UIControlStateNormal];
     }
    
  9. To complete the SecondViewController, override the viewDidAppear: and viewDidDisappear: methods to properly handle the state

     -(void)viewDidAppear:(BOOL)animated {
         [super viewDidAppear:animated];
         [[self subscribeButton] setTitle:@"START" forState:UIControlStateNormal];
     }
    
     -(void)viewDidDisappear:(BOOL)animated {
         [super viewDidDisappear:animated];
         isSubscribing = NO;
     }
    

Launching & Viewing Subscriber

Ensure that you have a Red5 Pro Server running at the loction defined in the R5Configuration of SubscribeViewController. From there select to build and deploy to a connection iOS device. Once the application is launched on the device and the Subscribe tab is selected:

  1. Navigate to the Red5 Pro Server in a browser and start a new broadcast with the included Flash Broadcaster using the stream name provided in the subscriber:play call
  2. Click the UI Button to start subscribing to the stream

Upgrading the SDK in Your Project

To upgrade your project with the latest version of the Red5 Pro iOS Streaming SDK:

  1. Log into Red5 Pro, and navigate to the Downloads Section.
  2. Under the Red5 Pro Streaming SDKs, download the latest streaming SDK for iOS.
  3. Unzip the streaming-ios-sdk-latest.zip file, which contains the R5Streaming.framework.
  4. Open your iOS project.
  5. Delete and then replace the R5Streaming.framework file.
  6. Rebuild your project and launch. When you publish, you should see the new SDK version listed (e.g., [R5 INFO] Starting R5Pro Client Version 1.0.0.9).

For example, if you open the Red5 Pro iOS Streaming Example App on GitHub with xcode, you can select the R5Streaming.framework file and choose "Show in Finder," which will open up a browser window. There, you can simply delete the original R5Streaming.framework and replace with the new one that you just downloaded.

xcode

finder


API Documentation

For more in-depth documentation about the structure of the iOS Streaming SDK, please visit: Red5 Pro iOS Streaming Documentation