How to play a live stream with Wowza GoCoder SDK for iOS

Learn how to add a player view to a Wowza GoCoder™ SDK for iOS app and play a live stream, including an ultra low latency live stream from the Wowza Streaming Cloud™ service.

Notes:

  • Creating ultra low latency stream targets requires a separate subscription to Wowza Streaming Cloud with Ultra Low Latency.
  • Ultra low latency streams are subject to a default viewer limit of 5,000 simultaneous viewers per stream. If this limit is exceeded, new stream viewers will receive an error and won't be able to establish a connection. If you have enabled and configured HLS as a backup for playback, ultra low latency stream viewers beyond the allotted limit can view the steam via the fallback HLS connection. See Wowza Streaming Cloud REST API limits for more information about limits.
  • Playback over SSL isn't supported by GoCoder SDK at this time.

Contents


Add a player view to an app
Configure the streaming server
Configure Apple HLS fallback
Set play options
More resources

Add a player view to an app


Use the WOWZPlayer and WOWZStatusCallback 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) WOWZPlayer *player;
  2. Create a WOWZPlayer 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 = [WOWZPlayer 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 WOWZStatusCallback methods to respond and assign your player view.
     
    #pragma mark - WOWZStatusCallback Protocol Instance Methods
    
    - (void) onWOWZStatus:(WOWZStatus *) goCoderStatus {
      // A successful status transition has been reported by the GoCoder SDK
      
      switch (goCoderStatus.state) {
          
        case WOWZStateIdle:
                break;
          
        case WOWZStateStarting:
          // A streaming broadcast session is starting up
          self.player.playerView = self.view;
    
          break;
          
        case WOWZStateRunning:
          
          break;
          
        case WOWZStateStopping:
                 break;
          
        case WOWZStateBuffering:
              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];
      }
    }

Configure 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 the 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 Apple HLS fallback


You can instruct the Wowza GoCoder SDK app to play an Apple HLS stream as a fallback if the primary stream fails to connect.

Note: If you're receiving an ultra low latency stream from the Wowza Streaming Cloud REST API, the target must be configured to enable HLS fallback. For instructions, see the Wowza Streaming Cloud with Ultra Low Latency quick start guide. HLS fallback helps ensure successful playback but increases latency.

Use the following properties in WowzaConfig:

Property Type Description
allowHLSPlayback Boolean Specify 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];

Set play options


syncOffset

If your source stream has a constant audio/video sync offset, use the syncOffset option to adjust how the audio/video sync is 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 following playerViewGravity properties to specify how the player preview should display:

Property Description
WOWZPlayerViewGravityResizeAspect Scale the camera preview to fit within the screen area. Letterboxing may be applied to maintain the aspect ratio.
WOWZPlayerViewGravityResizeAspectFitFill Scale the camera preview to fill the screen area. The preview may be cropped to maintain the aspect ratio.

Set the previewGravity mode.

self.player.playerViewGravity = WOWZPlayerViewGravityResizeAspect;

More resources



If you're having problems or want to discuss this article, post in our forum.