JSignage:Playlist

Description

A playlist is a sequence of media files (images, video, animation) displayed one after the other.

To build a playlist, you need to setup a list of file to be displayed and optionally a duration for each item. If no explicit duration is set, then the file is played for its media duration. For images, as they don't have a duration by default, a defaultDur may be specified.

A new playlist is constructed with $.playlist( { ... } ).

Playlist may loop indefinitely or not depending on the configuration.

The playlist is part of the advanced layer type.

Specific attributes

All layers share a common set of attributes to define their screen layout and active time interval. Frame decoration may also be used with this layer.

The playlists accepts the following specific attributes:

data
Array of the elements of the playlists. There are two ways to specify a playlist element:
1. A simple URI string, all parameters being set to default values.
2. A descriptor object with the following fields (only href is mandatory):
  - href URI of the media
  - dur Duration in seconds. The default value is 'media' for videos and animations and defaultDur for images.
  - transition Transition from previous element in the playlist. If no transition is specified, the defaultTransition is used.

Optionals:

defaultDur
Duration for images in the playlist. The default value is 5 seconds.
minimumDur
Minimum duration of any element (videos may be extended to this duration by freezing on the last frame). By default there is no minimum duration.
maximumDur
Maximum duration of any element (videos may be clipped to this duration). By default there is no maximum duration.
defaultTransition
Default transition from the previous element in the playlist. See the Transitions topic for more on transitions.
iterating: function ( iter ) {}
Optional callback to modify some of the playlist parameters before a new iteration starts. See iterating callback for details.

Specific functions

As $.playlist() returns a jSignage layer object, any of the layer common functions can be applied. Additional functions are detailed below.

.pushData()

.pushData( value1, value2, ..., valueN )

This function can be used to push / append additional items to the data array specified at playlist creation. Each argument can be a single element or an array of elements.

If the slide show is currently active, the new items are appended to an internal copy of the current data array, thus lengthening the duration of the slide show. If it has ended or has not yet started, it will be restarted (applying the begin effects if it's the case) and any data previously used is lost.

Examples

Basic playlist of videos

The video are displayed in loop one after the other. The playlist do not have any dimention and is thus displayed in full screen.

$(function(){ 
   $.playlist({
     data: [ 'ad-1.mp4', 'info-1.mp4', 'ad-2.mp4', 'info-2.mp4' ],
     repeatDur: 'indefinite'
   }).addTo( 'svg' );
});

Playlist of videos with shuffle

Every video in the list is played once, in a random order. The shuffle helper is used to randomize the playlist.

$(function(){ 
   $.playlist({
     data: $.shuffle( [ 'ad-1.mp4', 'info-1.mp4', 'ad-2.mp4', 'info-2.mp4' ] )
   }).addTo( 'svg' );
});

Playlist of videos with shuffle and repeat

If we want to change the shuffle at each iteration, we can use the pre-iteration callback.

$(function(){ 
   $.playlist({
     iterating: function() {
       this.data = $.shuffle( [ 'ad-1.mp4', 'info-1.mp4', 'ad-2.mp4', 'info-2.mp4' ] );
     },
     repeatDur: 'indefinite'
   }).addTo( 'svg' );
});

Each time the playlist loops, the iterating callback is executed, causing the order of the media to be shuffled once more.

Basic playlist of images

Each images is displayed for 10 seconds. The transition from one image to another is configured to use a fade. The playlist will be displayed once, and will not loop.

$(function(){ 
   $.playlist({
     data: [ 'mountain.jpg', 'sea.jpg', 'beach.jpg' ],
     defaultDur: 10,
     defaultTransition: $.fade()
   }).addTo( 'svg' );
});

Basic playlist of media

The playlist is composed of a mix of images and video. The duration of the images is set to 2s, whereas the video are displayed for their full duration. The playlist is set to loop indefinitely.

$(function(){ 
   $.playlist({
     data: [ 'images/1.jpg', 'video/1.avi', 'images/2.jpg', 'video/2.avi', 'images/3.jpg', 'video/3.avi' ],
     repeatDur: 'indefinite',
     defaultDur : 2,
   }).addTo( 'svg' );
});

Images, video and all media type can be mixed in the same playlist.

Non fullscreen playlist

Playlist may use only one region of the screen. This is controlled like any other layers using the width, height and position attributes. The example bellow uses a playlist in front of a background image.

$(function(){ 
   $.image( {href:'images/1.jpg'} ).addTo('svg');
   $.playlist({ width: 640, height:480, top: 120, right: 160,
                data: [ 'images/1.jpg', 'video/1.avi', 'video/2.avi', 'video/3.avi' ],
                repeatDur: 'indefinite',
                defaultDur : 2,
                maximumDur : 8,
   }).addTo( 'svg' );
});

Custom media transitions

The playlist transition and the media duration may be modified for each media.

$(function(){
   $.playlist({
     defaultDur: 3,
     defaultTransition: $.wipe({ type: 'iris' }),
     maximumDur: 10,
     repeatCount: 'indefinite',
     data: [
          { href: 'images/1.jpg', transition: $.crossFade() },
          { href: 'images/3.jpg', dur: 5, transition: $.flip({ orientation: 'horizontal' }) },
          'images/3.jpg',
          'video/1.avi',
        ]
  }).addTo( 'svg' );
});

Note:

The first image has a duration of 3s (the default) and overrides the transition, using a cross-fade instead of the default wipe.
The second image has a duration of 5s and overrides the transition
The other media uses the default duration and transition.
The video will be displayed only for 10s, as a maximumDur has been set.

Advanced playlist of images

Combining tools can be used to create advanced playlist.

The list of images available in a given folder is returned by a PHP script, with one line per image. Random transition is used to switch from one image to another.

$.get( 
    'list.php?mediaPath=media',
    function( text, status ) {
      var images = $.trim(text).split( '\r\n' );
      var playlist=[];
      var transitions=[ 'fade', 'push', 'wipe' ];   
      for ( var i=0; i<images.length; i++ ) {
        playlist.push({
          href: images[i],
          transition: $[$.randomChoice(transitions)]()
        });
      }
      $.playlist({
        data: playlist,
        defaultDur: 5
      }).addTo( 'svg' );
    }
);