How to play an ultra low latency live stream with Wowza GoCoder SDK for iOS

Learn how to add a player view and play a live stream with Wowza GoCoder™ SDK for iOS.

Note: The Wowza GoCoder SDK iOS playback feature is in private preview release. Participation is by invitation only and is subject to the terms of the Wowza Preview End User License Agreement.

Contents


Add a player view to an application
Specify the streaming server
Configure an Apple HLS fallback URL
Play a live stream

Add a player view to an app


Use the WZPlayer and WZStatusCallback classes to add a player view to an app.

  1. Create configuration and player properties.
    #pragma mark - GoCoder SDK Components
    @property (nonatomic, strong) WowzaConfig *goCoderConfig;
    @property (nonatomic, strong) WZPlayer *player;
  2. Create a WZPlayer object and, if desired, register it for data events.
    // Register the GoCoder SDK license key
      NSError *goCoderLicensingError = [WowzaGoCoder registerLicenseKey:SDKSampleAppLicenseKey];
      if (goCoderLicensingError != nil) {
        // Handle license key registration failure
    
      }
      else {
        self.player = [WZPlayer new];
        //Set default preroll buffer duration
         self.player.prerollDuration = [[NSUserDefaults standardUserDefaults] floatForKey:PlaybackPrerollKey];
        //Optionally set up data sink to handle in-stream events
        [self.player registerDataSink:self eventName:@"onTextData"];
      }
    
  3. Implement the WZStatusCallback methods to respond and assign your player view.
    #pragma mark - WZStatusCallback Protocol Instance Methods
    
    - (void) onWZStatus:(WZStatus *) goCoderStatus {
      // A successful status transition has been reported by the GoCoder SDK
      
      switch (goCoderStatus.state) {
          
        case WZStateIdle:
                break;
          
        case WZStateStarting:
          // A streaming broadcast session is starting up
          self.player.playerView = self.view;
    
          break;
          
        case WZStateRunning:
          
          break;
          
        case WZStateStopping:
                 break;
          
        case WZStateBuffering:
              break;
          
        default:
          break;
      }
    }
  4. Use your configuration property to start playing the stream.
    #pragma mark - UI Action Methods
    
    - (IBAction) didTapPlaybackButton:(id)sender {
      if (!self.player.playing) {
        [self.player play:self.goCoderConfig callback:self];
      }
      else {
        [self.player stop];
      }
    }

Specify the streaming server


Specify the streaming server connection properties.

  1. Write a configuration method that instantiates and assigns a configuration object to your property.
    -(void)setupConfig{
      WowzaConfig *config = [WowzaConfig new];
      config.hostAddress = @"your_server_ip"
      config.portNumber = 1935
      config.streamName = @"a_stream_name"
      config.applicationName = @"your_application_name";
      config.audioEnabled = YES;
      config.videoEnabled = YES;
      
      //If authentication is required
      config.username = @"someusername";
      config.password = @"somepass";
      
      self.goCoderConfig = config;
    }
  2. Call the configuration method.
    - (void)viewDidLoad {
      [super viewDidLoad];
      [self setupConfig];
  3. Instruct your self.player object to play with the configuration method and register self as a delegate for callbacks.
    - (IBAction) didTapPlaybackButton:(id)sender {
      if (!self.player.playing) {
        [self.player play:self.goCoderConfig callback:self];
      }
      else {
        [self.player stop];
      }
    }

Configure an Apple HLS fallback URL


If you enabled HLS playback for your Wowza Streaming Cloud™ ultra low latency stream target, you can configure your app to use the returned Apple HLS playback URL if the app fails to play the stream over the primary protocol.

Use the following properties in WowzaConfig:

Property Type Description
allowHLSPlayback Boolean Set to true to enable Apple HLS fallback. When enabled, the player will switch to the Apple HLS URL after three failed attempts to play over the primary protocol.
hlsURL string The .m3u8 playlist URL. This is an NSString object.

The following example demonstrates how to verify that Apple HLS fallback is configured. It retrieves the allowHLSPlayback and hlsURL property values from your NSUserDefaults or from your configuration file. 

- (void) viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];
    
    NSData *savedConfigData = [NSKeyedArchiver archivedDataWithRootObject:self.goCoderConfig];
    [[NSUserDefaults standardUserDefaults] setObject:savedConfigData forKey:SDKSampleSavedConfigKey];
    [[NSUserDefaults standardUserDefaults] synchronize];
	
		//because of the custom SettingsViewModel we constructed we pull the hls value from NSUserDefaults
    self.goCoderConfig.allowHLSPlayback = [[NSUserDefaults standardUserDefaults] boolForKey:AllowHLSKey];
		self.goCoderConfig.hlsURL = [[NSUserDefaults standardUserDefaults] stringForKey:HLSURLKey];

Play a live stream


Use the following options to play a live stream from the specified server.

syncOffset

If your source stream has a constant audio/video sync offset, use the syncOffset option to adjust how the audio/video sync is constantly set.

-(IBAction)syncSliderChanged:(id)sender {
  UISlider *slider = (UISlider *)sender;
  Float32 value = slider.value;
  self.player.syncOffset = value;
  
}

prerollDuration

Use the prerollDuration option to set the time, in seconds, that the stream should buffer before playing.

self.player.prerollDuration = 3;  //3 second buffer.

play and stop

Use play to start playing the stream and stop to stop playing the stream.

- (IBAction) didTapPlaybackButton:(id)sender {
  if (!self.player.playing) {
    [self.player play:self.goCoderConfig callback:self];
  }
  else {
    [self.player stop];
  }
}

mute

Use the mute option to silence the audio of the stream.

- (IBAction)didTapMuteButton:(id)sender {
  self.player.muted = !self.player.muted;
  UIImage *muteButtonImage = [UIImage imageNamed:self.player.muted ? @"volume_mute" : @"volume_unmute"];
  [self.muteButton setImage:muteButtonImage forState:UIControlStateNormal];
  self.volumeSlider.enabled = !self.player.muted;
}

volume

Use the volume option to adjust the audio volume of the stream.

- (IBAction)didChangeVolume:(id)sender {
  UISlider *slider = (UISlider *)sender;
  self.player.volume = slider.value;
}

playerViewGravity

Use the playerViewGravity property to specify how the player preview should be displayed. The following modes are available:

WZPlayerViewGravityResizeAspect Scale the camera preview to fit within the view surface. Note that letterboxing may be applied to maintain the proper aspect ratio.
WZPlayerViewGravityResizeAspectFitFill Scale the camera preview to fill the entire view surface. Note that the preview may be cropped to maintain the proper aspect ratio.

Use the following command to set the previewGravity mode.

self.player.playerViewGravity = WZPlayerViewGravityResizeAspect;