Create a playlist

Create and add playlists to your iOS app.


The JWPlayerItem class enables you to add content to your player and define the unique characteristics of that content:

  • Title
  • Description
  • Poster Image

There are multiple ways to load and play content in your player. As best practice approaches, we recommend the following:

  • Use JWPlayerConfigurationBuilder() to create single-item or multiple-item playlists with media hosted in your JW Player account.
  • Use JWPlayerItemBuilder() to create single-item or multiple-item playlists with self-hosted media.
  • Use JWPlayerConfigurationBuilder() to associate a playlist to a player and to initiate media playback.
  • All JWPlayerItem must have either a video source or a file set. If neither or both are set, the JWPlayerItemBuilder will throw an exception.

While you can use other approaches to create, associate, and play playlists, JWPlayerItemBuilder() and JWPlayerConfigurationBuilder() enable you to add functionality, such as, customization and advertising.


The following sections explain how to create a playlist with one or more items and to add multiple sources to a playlist item.



Creating a playlist

Use the following step to add items to a playlist to a player:

  1. Use JWPlayerItemBuilder() to create one or more JWPlayerItem objects. All items require that a file be specified. This is the URL to the media file the JWPlayerItem will play.

    To increase user engagement, we strongly recommend defining the title, description, and posterImage for the JWPlayerItem.

  2. Use JWPlayerConfigurationBuilder() to add the JWPlayerItem objects to an array and set the player configuration.
  3. Hand your configuration to the JWPlayer object.
let item1 = try JWPlayerItemBuilder()
                   .file(URL(string:<#item1 url#>))
                   .title("Item 1")
                   .description("This is the first item")
                   .posterImage(<#image url#>)
                   .build()
let item2 = try JWPlayerItemBuilder()
                   .file(URL(string:<#item2 url#>))
                   .title("Item 2")
                   .description("This is the second item")
                   .posterImage(<#image url#>)
                   .build()
let config = try JWPlayerConfigurationBuilder()
                   .playlist([item1, item2])
                   .build()
player.configurePlayer(with: config)
NSError *error = nil;
JWPlayerItem *item1 = [[[[[[JWPlayerItemBuilder new] 
                            file:[NSURL URLWithString:<#item1 url#>]]
                            title:@"Item 1"]
                            description:@"This is the first item"]
                            posterImage:<#image url>]
                            buildAndReturnError:&error];
JWPlayerItem *item2 = [[[[[[JWPlayerItemBuilder new] 
                            file:[NSURL URLWithString:<#item2 url#>]] 
                            title:@"Item 2"]
                            description:@”This is the second item”]
                            posterImage:<#image url>]
                            buildAndReturnError:&error];
JWPlayerConfigurationBuilder *config = [[[JWPlayerConfigurationBuilder new] 
                                             playlist:@[item1, item2] 
                                             buildAndReturnError:&error];
[player configurePlayerWith:config];


Add multiple sources to a playlist item

You can associate multiple sources to a JWPlayerItem. This is useful when you want to offer your viewers an option between a high definition or standard definition variation of your content.

Use the following steps to add multiple sources to a JWPlayerItem:

  1. Use JWVideoSourceBuilder() to create several JWVideoSource objects for a JWPlayerItem.
  2. Use JWPlayerItemBuilder() to create a JWPlayerItem object that passes the JWVideoSource objects as a videoSources array.
  3. Use JWPlayerConfigurationBuilder() to set the JWPlayerItem in the player configuration.
  4. Hand the player configuration to the JWPlayer object.
let source1 = try JWVideoSourceBuilder()
                     .file(<#source url#>)
                     .label("High Quality")
                     .build()
let source2 = try JWVideoSourceBuilder()
                     .file(<#source url#>)
                     .label("Low Quality")
                     .build()
let item = try JWPlayerItemBuilder()
                     .videoSources([source1, source2])
                     .build()
let config = try JWPlayerConfigurationBuilder()
                     .playlist([item])
                     .build()
player.configurePlayer(with: config)
NSError *error = nil;
JWSource *source1 = [[[[JWVideoSource new]
                           file:[NSURL URLWithString:<#source url#>]]
                           label:@"High Quality"]
                           buildAndReturnError:&error];
JWSource *source2 = [[[[JWVideoSource new]
                           file:[NSURL URLWithString:<#source url#>]]
                           label:@"Low Quality"]
                           buildAndReturnError:&error];
JWPlayerItem *item = [[[JWPlayerItemBuilder new] 
                           videoSources:@[source1, source2]] 
                           buildAndReturnError:&error];

JWPlayerConfigurationBuilder *config = [[[JWPlayerConfigurationBuilder new] 
                                             playlist:@[item1, item2] 
                                             buildAndReturnError:&error];
[player configurePlayerWith:config];


Frequently Used Methods and Callbacks

The following list contains frequently used methods and callbacks. To view all available methods and callbacks, review the SDK reference for JWPlayerStateDelegate. If you are using JWPlayerViewController, you only need to override these methods from the view controller.

Method or CallbackDescription
func jwplayer(_ player: JWPlayer, didLoadPlaylist playlist: [JWPlayerItem])This event is triggered when the player has loaded a playlist, and contains a list of the processed player items in the player.
func jwplayerPlaylistHasCompleted(_ player: JWPlayer)This event is triggered when the player has completed playing all items in the playlist.
func jwplayer(_ player: JWPlayer, isAttemptingToPlay playlistItem: JWPlayerItem, reason: JWPlayReason)This event is triggered when the player item is about to play.
func jwplayer(_ player: JWPlayer, didLoadPlaylistItem item: JWPlayerItem, at index: UInt)This event is triggered when the player item has been loaded.


Did this page help you?