JW Player SDK for Android Migration from v1.x to v2.x (Nov 17 2015)

This Migration Guide will walk you through all major changes from the 1.x versions of the JW Player SDK for Android.

License Key

Your 1.x license key will not work with the JW Player SDK for Android 2.0 and above. You can get your new mobile-only license key from the JW Player Dashboard.

Added API Methods

Method Description
int getPlaylistIndex() Returns the index of the currently playing PlaylistItem.
PlaylistItem getPlaylistItem(int index) Returns the PlaylistItem at the provided index.
List<Caption> getCaptionsList() Returns the list of currently available captions tracks.
int getCurrentCaptions() Returns the index of the currently selected captions track.
setCurrentCaptions(int index) Sets which captions track to display.
setSkin(Skin skin) Sets the player skin from the stock set of skins.
setSkin(String skinUrl) Sets the player skin to the provided URL.
onDestroy() Called from Activity.onDestroy() or Fragment.onDestroy(), handles resource cleanup.

Modified API Methods

Setup is primarly used to change the player configuration programmatically. It is also possible to update the playlist and advertising settings alongside other configuration changes.

In order to get the current player configuration simply call:

getConfig() - which will return the current configuration. Modify the configuration as you see fit and then load it into the player using setup()

If you would only like to change the playlist and advertising options without affecting any other settings use the load() methods, they are as follows:

Method Description
load(List<PlaylistItem> playlist, Advertising advertising) Used to load a playlist along with advertising options and an ad schedule.
load(List<PlaylistItem> playlist) Used to load a playlist, note that each playlist item can have an advertising schedule.
load(PlaylistItem playlistItem) Used to load a single playlist item.

Return Types for Getters

Method Description
public List<QualityLevel> getQualityLevels() Switched to List from array.
public List<PlaylistItem> getPlayList() Removed Playlist object in favor of List
List<AudioTrack> getAudioTracks() Switched to List from array.
long getPosition() getPosition now returns a long instead of an int.
long getDuration() getDuration now returns a long instead of an int.

Renamed Methods

Method Description
public void setControls(boolean controls) Method name changed from setControlBarVisibility()

Method Signature Changes

Method Description
playAd(String... vasts) playAd() can now take multiple ad tags, if one ad tag fails to load the next will be attempted.

Removed API Methods

Method Description
setEnableSetSystemUiVisibility(boolean enableSetSystemUiVisibility) Replaced with extending FullscreenHandler and setFullscreenHandler().
boolean isAutoStart() AutoStart is now controlled at the Playlist level.
setAutoStart(boolean autoStart) AutoStart is now controlled at the Playlist level.
boolean isRepeat() AutoRepeat is not controlled at the Playlist level.
setRepeat(boolean repeat) AutoRepeat is not controlled at the Playlist level.
release() No longer necessary, use onPause(), onResume(), and, onDestroy()

Changes to Media Classes

The names of some media classes have changed and some of their structures have been altered. The new names are:

1.x 2.x Description of Changes
PlayerConfig This is a new class, it represents a player configuration and can include: controlbar, caption styling, logo, skin, and advertising settings.
SingleSource and MultipleQualityMediaSource PlaylistItem This is the root class for a single piece of media in JW Player. It can contain URLs to captions tracks, media sources, and an ad schedule for this playlist item.
MediaSource Used for multiple-source media, any number of these can be assigned to a single PlaylistItem
Subtitle Caption Represents a caption track, any number of these can be assigned to a single PlaylistItem
AdBreak AdBreak Represents an advertising break, contains a playback offset (pre, post, static midroll, or midroll %) and an Ad.
Ad Has an AdSource of either VAST or IMA and contains any number of tags. Multiple tags are waterfalled - if one fails the next is attempted.
Advertising Advertising or VMAPAdvertising these classes contain advertising-related settings (e.g. skip message) and can contain an advertising schedule that is applied to the entire playlist.

Builders

It is now possible to instantiate JWPlayerView and other Media Classes via a builder. Builders cover all of the configuration options that are possible for a class. And in case of the JWPlayerView the builder also supports all the possible XML attributes.

Example:

PlayerConfig playerConfig = new PlayerConfig.Builder()
    .logoFile("jw_logo.png")
    .logoLink("http://jwplayer.com")
    .autostart(true)
    .repeat(true)
    .build();
JWPlayerView p = new JWPlayerView(this, playerConfig);

Will create a JW Player instance with a clickable logo, and autostart and autorepeat enabled.

There are also builders for the Caption, MediaSource, and PlaylistItem classes.

Added Callbacks

Callback Description
onCaptionsList(List<Caption> tracks) Fired when captions tracks are available.
onSetupError(String message) Fired when an error occurs during player setup.
onPlaylist(List<PlaylistItem> playlist) Fired when a Playlist is loaded into the player.
onPlaylistItem(int index, PlaylistItem playlistItem) Fired when a PlaylistItem begins playing.
onPlaylistComplete() Fired when the last item in a playlist finishes playing.
onBeforePlay() Fired immediately after the user clicks Play but before playback begins.
onBeforeComplete() Fired immediately before content finishes playing.

Modified Callbacks

1.x 2.x Description of Changes
onQualityLevels(QualityLevel[] levels) onQualityLevels(final List<QualityLevel> levels) Quality levels changed from array to List.
onQualityChange(QualityLevel currentQuality) onQualityChange(int currentQuality) Quality level parameter changed from QualityLevel to index.
onAudioTracks(AudioTrackLevel[] tracksLevels) onAudioTracks(final List<AudioTrack> audioTracks) Audio tracks changed from array to List.
onAudioTrackChange(AudioTrackLevel currentAudioTrackLevel) onAudioTrackChange(int currentTrack) Audio track parameter changed from track to index.
onSubtitleSelected(Subtitle subtitle) onCaptionsChange(int track, List<Caption> captions) Name changed from onSubtitleSelected(), track index added.
onTime(int position, int duration) onTime(long position, long duration) Position and duration types changed from int to long.
onFullscreen(boolean state, boolean userRequest) onFullscreen(boolean fullscreen) userRequest parameter removed.
onMeta(Map<String, String> metaMap) onMeta(Metadata meta) Metadata is now returned using the Metadata class.
onAdTime(String adTag, int position, int duration) onAdTime(String tag, long position, long duration, int sequence) Position and duration types changed from int to long. Sequence parameter added.
onAdImpression(String adTag) onAdImpression(String tag, String creativeType, String adPosition) Added creativeType and adPosition parameters.
onAdClick(String adTag, String url) onAdClick(String tag) Removed the URL parameter.
onBuffer() onBuffer(PlayerState oldState) onBuffer now reports the state the player switched from.
onIdle() onIdle(PlayerState oldState) onIdle now reports the state the player switched from.
onPause() onPause(PlayerState oldState) onPause now reports the state the player switched from.
onPlay() onPlay(PlayerState oldState) onPlay now reports the state the player switched from.
onAdPlay(String adTag) onAdPlay(String tag, PlayerState oldState) onAdPlay now reports the state the player switched from.
onAdPause(String adTag) onAdPause(String tag, PlayerState oldState) onAdPause now reports the state the player switched from.

Removed Callbacks

Callback Description
onSubtitle(String subtitle) Display of individual subtitles is no longer reported.
onAdFullscreen(boolean state, boolean userRequest) All fullscreen state changes are now reported through onFullscreen()
onAdMeta(Map<String, String> metaMap) All metadata is now reported through onMeta()
onAdBuffer(String adTag)
onAdIdle(String adTag)
onMediaSelected()

Added Configuration Options

XML Attribute Description
jw_captions_color Hex color of the captions text. Is ffffff by default.
jw_captions_fontSize Size of the captions text. Is 15 points by default.
jw_captions_fontFamily Family of the captions text. Is sans by default.
jw_captions_fontOpacity Alpha value of the captions text. Is 100 by default.
jw_captions_backgroundColor Hex color of the caption characters background. Is 000000 by default.
jw_captions_backgroundOpacity Alpha value of the caption characters background. Is 75 by default.
jw_captions_edgeStyle Method by which the captions characters are separated from their background.
jw_captions_windowColor Hex color of the background of the entire captions area. Is 000000 by default.
jw_captions_windowOpacity Alpha value of the background of the entire captions area. Is 0 by default.
jw_logo_file Location of an external JPG, PNG or GIF image to be used as watermark. We recommend using 24 bit PNG images with transparency, since they blend nicely with the video.
jw_logo_hide By default (false), the logo remains visible all the time. When this option is set to true, the logo will automatically show and hide along with the other player controls.
jw_logo_link HTTP URL to jump to when the watermark image is clicked (e.g. http://example.com/). If it is not set, a click on the watermark does nothing in particular.
jw_logo_margin The distance of the logo from the edges of the display. The default is 8 pixels.
jw_logo_position This sets the corner in which to display the watermark. Uses an enum that can be TOP_RIGHT (the default), TOP_LEFT, BOTTOM_RIGHT or BOTTOM_LEFT. Note the default position is preferred, since the logo won't interfere with the controlbar, captions, overlay ads and dock buttons.
jw_skin_name The skin to use for styling the player. If not configured, we'll default our player to use the seven skin. Other available premade skins include six, five, beelden, vapor, roundster, bekle, stormtrooper, and glow. A live example showing each of these, as well as a deeper explanation of custom colors, can be found on our JW Player skin configuration page.
jw_skin_active The color of active skin elements. This should be entered in either hex or x11 color format.
jw_skin_inactive The color of inactive skin elements. Like the above active config, this should be entered in either hex or x11 color format.
jw_skin_background The color of a skin's background portion. Like the above active config, this should be entered in either hex or x11 color format.
jw_skin_url If using an external CSS file to style your player, this can be specified here. Note that with this configuration you will still need to specify the name of your skin and this may negatively impact the speed which your JW Player loads

Modified Configuration Options

1.x 2.x Description of Changes
jw_autoStart jw_autostart Start changed to lower case
jw_posterURL jw_image Renamed

Removed Configuration Options

XML Attribute
jw_controlsFullscreen
jw_controlsQuality
jw_controlsTimePlayed
jw_controlsTotalDuration
jw_controlsSeekEnabled
jw_replayButtonEnabled
jw_posterDrawable

Fullscreen Handler

It is possible to override the default fullscreen behavior. To do this simply implement the FullscreenHandler interface or extend the DefaultFullscreenHandler class and override any or all of these methods:

Method Description
onFullscreenRequested() Called when the player should enter fullscreen.
onFullscreenExitRequested() Called when the player should exit fullscreen.
onResume() Called when the activity containing the JWPlayerView is resumed. You could use this to register Orientation listeners.
onPause() Called when the activity containing the JWPlayerView is paused. You could use this to unregister Orientation listeners.
onDestroy() Called when the activity containing the JWPlayerView is destroyed. You could use this to release resources that the FullscreenHandler holds on to.
onAllowRotationChanged(boolean allowRotation) Called when the "allow rotation" property of the JWPlayerView has changed, use this to determine whether your FullscreenHandler implementation should listen for device orientation changes.
updateLayoutParams(ViewGroup.LayoutParams layoutParms) Called when the layout parameters of the JWPlayerView have been updated. You could use these to restore the player when exiting fullscreen.
setUseFullscreenLayoutFlags(boolean flags) Called when JWPlayerView#setUseFullscreenLayoutFlags is called, use this to determine whether you should use the SYSTEM_UI_FLAG_FULLSCREEN and SYSTEM_UI_FLAG_HIDE_NAVIGATION flags in calls to setSystemUiVisibility.

We also offer an alternative FullscreenHandler implementation MaximizingFullscreenHandler, if the DefaultFullscreenHandler does not fit your use-case you may want to try the MaximizingFullscreenHandler before writing your own implementation.

For more information see the Javadocs.

Examples

These examples assume that you have a reference to a JWPlayerView called player.

Loading a Single Stream

1.x 2.x Description of Changes
player.load(new SingleSource("http://url-pointing-to/file.m3u8")); player.load(new PlaylistItem("http://url-pointing-to/file.m3u8")); Class names changed for SingleSource vs. PlaylistItem

Loading a Playlist

1.x 2.x Description of Changes
List<JWMediaSource> pl = new ArrayList<>();
pl.add(new SingleSource("http://url-pointing-to/first_stream.m3u8"));
pl.add(new SingleSource("http://url-pointing-to/second_stream.m3u8"));

player.load(pl);

Playlist playlist = p.getPlayList();
List<PlaylistItem> playlist = new ArrayList<>();
playlist.add(new PlaylistItem("http://url-pointing-to/first_stream.m3u8"));
playlist.add(new PlaylistItem("http://url-pointing-to/second_stream.m3u8"));

player.load(playlist);
Playlist class was removed in favor of a simple List

Loading a Stream with an Advertising Schedule

Loading a stream with an advertising schedule containing one preroll and one midroll at 50%.

1.x 2.x
SingleSource item = new SingleSource("http://url-to/media.m3u8");

List<AdBreak> adSchedule = new ArrayList<>();
adSchedule.add(new AdBreak(AdBreak.PRE_ROLL, "http://url-to/preroll.xml"));
adSchedule.add(new AdBreak(AdBreak.MID_ROLL, "50%", "http://url-to/midroll.xml"));

Advertising advertising = new Advertising();
advertising.setListOfBreaks(adSchedule);
item.setAdvertising(advertising);

player.load(item);
PlaylistItem plItem = new PlaylistItem("http://url-to/media.m3u8");

List<AdBreak> adSchedule = new ArrayList<>();
adSchedule.add(new AdBreak("pre", new Ad(AdSource.VAST, "http://url-to/preroll.xml")));
adSchedule.add(new AdBreak("50%", new Ad(AdSource.VAST, "http://url-to/midroll.xml")));
plItem.setAdSchedule(adSchedule);

player.load(plItem);

Loading a Playlist with an Advertising Schedule for the Entire Playlist

Loading a playlist with an advertising schedule for the entire playlist where the schedule contains one midroll at 10% and one at 30 seconds.

1.x 2.x
List<AdBreak> adSchedule = new ArrayList<>();
adSchedule.add(new AdBreak(AdBreak.MID_ROLL, "10%", "http://url-to/midroll1.xml"));
adSchedule.add(new AdBreak(AdBreak.MID_ROLL, "30", "http://url-to/midroll2.xml"));
Advertising advertising = new Advertising();
advertising.setListOfBreaks(adSchedule);

SingleSource item1 = new SingleSource("http://url-to/media.m3u8");
item1.setAdvertising(advertising);
SingleSource item2 = new SingleSource("http://url-to/second-media.m3u8");
item2.setAdvertising(advertising);

List<JWMediaSource> playlist = new ArrayList<>();
playlist.add(item1);
playlist.add(item2);

player.load(playlist);
List<PlaylistItem> playlist = new ArrayList<>();
playlist.add(new PlaylistItem("http://url-to/media.m3u8"));
playlist.add(new PlaylistItem("http://url-to/second-media.m3u8"));

List<AdBreak> adSchedule = new ArrayList<>();
adSchedule.add(new AdBreak("10%", new Ad(AdSource.VAST, "http://url-to/midroll1.xml")));
adSchedule.add(new AdBreak("30", new Ad(AdSource.VAST, "http://url-to/midroll2.xml")));
Advertising advertising = new Advertising(AdSource.VAST, adSchedule);

player.load(playlist, advertising);