Playlists and recommendations

You can expose your viewers to other videos in your collection by creating video playlists and using video recommendations.

Creating a playlist

Use the video player's playlist method to create a set of videos to play in your video player. You can define a list of public IDs to include, and optionally set transformations for each source. Alternatively, you can generate a playlist based on all videos in your Cloudinary account with a specified tag.

After you have defined a playlist, you can use playlist methods to control the list. For example, you can jump to the next or previous video, jump to a specific video in the playlist by index, determine whether to auto-advance to the next video when the previous one ends, retrieve the total number of videos in the list, and more.

Create a fixed source playlist

The following example creates a playlist with the videos IDs: book, ocean, and dog. The book video plays with a transformation that overrides the default player settings. The next video in the list automatically begins 10 seconds after the previous, and then repeats the playlist from the beginning after the last video ends.

  { publicId: 'oceans', 
    transformation: { width: 500, crop: 'pad' } },
], autoAdvance: 10, repeat: true)

See playlist.html in the sample CodePen to see a sample video player with a play list, including Next and Previous buttons.

For details on all available playlist methods, see Playlist operations in the Video Player API Reference.

Create a playlist for a specified tag

The playlistByTag method performs a call to the client-side resource list operation and returns a promise object that when fulfilled, returns the player with the playlist.

To enable this functionality, make sure that the Resource list option is not restricted in your account settings: In the Cloudinary console, go to Settings > Security > Restricted image types, and make sure the Resource list option is not selected.

The playlistByTag method receives the tag to use and a set of options. In addition to setting the autoAdvance, repeat, and presentUpcoming parameters, you can also optionally provide a sorter (receives the name of a function that determines the sort order of the retrieved set of videos) and a sourceParams object (enables you to set transformations that will be applied to all the retrieved videos in the playlist).

When creating a playlistByTag with the presentUpcoming parameter or when autoShowRecommendations is true, the titles, subtitles, and descriptions are automatically taken from the title entry of the resource's context data if it exists. Otherwise the public ID is used instead. You can add a video title (as well as a subtitle and description) to the resource context using the Upload or Context methods of the Upload API or via the Media Library.

The following example generates (the promise of) a playlist from all videos with the tag, demo. It will deliver all retrieved sources with a 10 degree angle rotation transformation. The playlist is set to play each video in succession with no delay and then reloop to the beginning of the playlist, and the upcoming video thumbnail will display 5 seconds before the end of each video. When the promise is fulfilled, the console log displays a message:

{ sourceParams: { angle: 10 }, autoAdvance: 0, repeat: true, presentUpcoming: 5 })
            console.log("Playlist loaded")

See playlistByTag.html in the sample CodePen to see a playlist generated by tags, including a sorter function.

You can also use the sourcesByTag method to retrieve the sources for a specified tag without actually creating the playlist. This method has the same syntax and supports the same options as the playlistByTag.

The example below retrieves (the promise of) the sources data from all videos with the tag, "demo". When the promise is fulfilled, it passes the sources to the playlist method.

  .then(function(sources) { 

For details on all available playlist methods, see Playlist operations in the Video Player API Reference.

Present the upcoming video

When using playlists, you can optionally display a 'Next up' thumbnail with the title of the upcoming video, a few seconds before the current one ends, using the presentUpcoming parameter.

Set presentUpcoming to true, to display the upcoming video at the default time of 10 seconds before the end of the video. Alternatively, specify how many seconds before the end of the video the thumbnail should display.

For example:

player.playlist([source1, source2], { autoAdvance: true, repeat: true, presentUpcoming: 8 });

present upcoming thumbnail in playlist


  • If your playlist is set to repeat, then the upcoming video thumbnail shows the first video when the last video nears the end. Otherwise, no upcoming video is displayed at the end of the list.
  • If you have not set a title for a particular source in your playlist, either in the context of the resource itself or in the <video> tag source definitions, then the source's public ID is displayed instead of the title. For details, see title values.

Showing video recommendations

You can set your video player to show up to four video recommendations in a recommendations overlay pane when a video finishes playing. This can be for an individual video, or at the end of each video in a playlist as long auto-advance is disabled (autoAdvance: false). The recommendations pane displays one primary recommendation including large thumbnail, title, subtitle, and description (if they are defined for the relevant source), followed by up to three secondary recommendations, with a smaller thumbnail and the video title or public ID.

Video recommendations pane with titles and descriptions

To include recommendations at the end of a video, you need to:

  1. Pass autoShowRecommendations: true when creating the player, or trigger player.autoShowRecommendations(true) at a later time.
  2. Add a recommendations parameter to each video source for which you want to show recommendations after it. The parameter value is an array of video source objects (or a function or Promise that resolves into an array of video source objects).

For best results, make sure that each source you define as a recommendation has a title, sub-title, and description defined, either in the source definition or in the context of the resource itself.

For example:

// Setting video sources:
var source1 = { publicId: 'movie1', info: { title: 'My main movie', 
   subtitle: 'Something to know about the main movie' } }
var source2 = { publicId: 'movie2', info: { title: 'The next best video', 
   subtitle: 'A great subtitle', 
   description: 'An interesting description of this video....' } }
var source3 = { publicId: 'movie3', info: { title: 'Another interesting video1', 
   subtitle: 'Subtitle for video1' } }
var source4 = { publicId: 'movie4', info: { title: 'Another interesting video2', 
   subtitle: 'Subtitle for video2' } }
var source5 = { publicId: 'movie5', info: { title: 'Another interesting video3', 
   subtitle: 'Subtitle for video3' } }

// Specifying the recommendations for source1 as a fixed array of sources:
source1.recommendations = [source2, source3, source4, source5]

// Initializing the player with recommendations turned on
var player = cld.videoPlayer('example-player', { autoShowRecommendations: true });

Notes for using recommendations with playlists

  • If you create a playlist with auto-advance disabled (autoAdvance: false) and autoShowRecommendations: true, then by default, the next videos in the playlist are automatically displayed as the recommendations. In this case, if a viewer selects one of the recommendations, they remain within the context of the playlist.
  • If you explicitly specify recommendations for the sources in your playlist, those are displayed in the recommendations pane. In this case, if a viewer selects one of the recommendations, they exit the playlist.