Module 3: Playback
In this module, we will be describing how to build iOS and Android mobile players by adding video and audio playback functionality to Wowza GoCoder SDK-based applications. With the described steps, GoCoder-based apps will have the ability to play both ultra low latency and Apple HLS streams.
Before you begin, you will need:
- A GoCoder SDK license (paid or trial) that includes access to playback functionality.
- An existing GoCoder SDK project, to which you will be adding player functionality. If you do not have one, follow the steps for creating a project in Module 1: Publishing.
Adding Video Playback to an iOS App
Adding Player View to an iOS App
In this section we will use the WZPlayer and WZStatusCallback classes to add a player view to an app.
- Begin by creating configuration and player properties.
#pragma mark - GoCoder SDK Components
@property (nonatomic, strong) WowzaConfig *goCoderConfig;
@property (nonatomic, strong) WZPlayer *player;
Next, create a WZPlayer object.
// 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"];
}
Then 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;
}
}
Now use your configuration property to start playing streams.
#pragma mark - UI Action Methods
- (IBAction) didTapPlaybackButton:(id)sender {
if (!self.player.playing) {
[self.player play:self.goCoderConfig callback:self];
}
else {
[self.player stop];
}
}
Adding Stream Connection Properties to an iOS App
In this section we will be adding the properties to our iOS app that facilitate handling specific streams for playback.
First, 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;
}
Next, call the configuration method.
- (void)viewDidLoad {
[super viewDidLoad];
[self setupConfig];
Then configure the self.player object to play with the configuration method and self-register as a delegate for callbacks.
- (IBAction) didTapPlaybackButton:(id)sender {
if (!self.player.playing) {
[self.player play:self.goCoderConfig callback:self];
}
else {
[self.player stop];
}
}
Adding AppleHLS Playback Within the App#### We will now configure the app with the capability to play AppleHLS streams.1. Set the WowzaConfig element to use the allowHLSPlayback boolean to a value of “true.”
- Set the WowzaConfig element to use the hlsURL NSString object.
The example below demonstrates how to verify that Apple HLS playback is properly configured by retrieving 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];
Using Playback Appearance and Control Properties
The following properties are available for basic control as well as fine tuning playback appearance.
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];
}
}
Volume
- (IBAction)didChangeVolume:(id)sender {
UISlider *slider = (UISlider *)sender;
self.player.volume = slider.value;
}
Mute
- (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;
}
Playback Start Buffering (prerollDuration)
The prerollDuration option is used to to set the time, in seconds, that the stream should buffer before playing.
self.player.prerollDuration = 3; //3 second buffer.
Video and Audio Playback Dynamic Sync (syncOffset)
-(IBAction)syncSliderChanged:(id)sender {
UISlider *slider = (UISlider *)sender;
Float32 value = slider.value;
self.player.syncOffset = value;
}
Adding Video Playback to an Android App
Adding Player View to an Android App
In this section, we will use the WZPlayerView class to add a player view to an app.
- First begin by creating configuration and player properties.
- In your PlayerActivity layout resource file, add the WZPlayerView construct.
<com.wowza.gocoder.sdk.api.player.WZPlayerView
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:id="@+id/vwStreamPlayer"
android:layout_alignParentStart="false"
android:layout_centerInParent="true" />
Get a reference to your resource object.
mStreamPlayerView = (WZPlayerView) findViewById(R.id.vwStreamPlayer);
Adding Stream Connection Properties to an Android App
In this section, we will be adding the properties to our Android app that facilitate handling specific streams for playback.
Use the WZPlayerConfig object to specify the streaming server connection properties.
mStreamPlayerConfig = new WZPlayerConfig();
mStreamPlayerConfig.setIsPlayback(true);
mStreamPlayerConfig.setHostAddress("your-server-ip");
mStreamPlayerConfig.setApplicationName("live");
mStreamPlayerConfig.setStreamName("myStream");
mStreamPlayerConfig.setPortNumber(1935);
Then pass the WZPlayerConfig object with the server information as well as a callback status object to the WZPlayerView class.
class StatusCallback implements WZStatusCallback{
@Override
public void onWZStatus(WZStatus wzStatus) {
}
@Override
public void onWZError(WZStatus wzStatus) {
}
}
Adding AppleHLS Playback Within the App
We will now configure the app with the capability to play AppleHLS streams using the following properties:
setHLSEnabled(boolean):
Set to “true” to force your player to use Apple HLS instead of the default, WOWZ. This is for all situations, not just fallback.
mStreamPlayerConfig.setHLSEnabled(true);
setHLSBackupURL(string): The .m3u8 playlist URL. When specified, the player will switch to the Apple HLS URL after three failed attempts to play over the primary protocol.
mStreamPlayerConfig.setHLSBackupURL("http://[wowza-server-ip]:1935/[application]/[streamName]/pla
ylist.m3u8");
Optional Configurations
If you want to configure a enable or disable audio for the stream, use the setAudioEnabled parameter in the WZPlayerConfig class. Similarly, if you want to enable or disable video for the stream, use the setVideoEnabled parameter in the WZPlayerConfig class.
To enable:
mStreamPlayerConfig.setAudioEnabled(true);
mStreamPlayerConfig.setVideoEnabled(true);
To disable:
mStreamPlayerConfig.setAudioEnabled(false);
mStreamPlayerConfig.setVideoEnabled(false);
To control the volume, use the setVolume method in the WZPlayerView class:
mStreamPlayerView.setVolume(3);
To configure the scale mode, use the setScaleMode method of the WZPlayerView class:
// WZMediaConfig.FILL_VIEW : WZMediaConfig.RESIZE_TO_ASPECT;
mStreamPlayerView.setScaleMode(WZMediaConfig.FILL_VIEW);
Play a Live Stream
Use the play() method in the WZPlayerView class to play a live stream from the specified server.
WZStatusCallback statusCallback = new StatusCallback();
mStreamPlayerView.play(mStreamPlayerConfig, statusCallback);