JavaScript Guide

• How To Add Your Code
• Functions
• Events
  • Player API
  • Video tracking
• Video and player properties
• Cuepoints
• Usage samples

How to add your code

If you are adding some custom function to your theme or building a plugin to customize FV Player behaviour for your site, use wp_enqueue_script() (WordPress.org documentation). If you are doing this in your theme, you can use something like this:

wp_enqueue_script('your-script', get_stylesheet_directory_uri().'/your-script.js', array('flowplayer'), '0.1', true);

If you are building a plugin, then use:

wp_enqueue_script('your-script', plugins_url('/your-script.js', __FILE__), array('flowplayer'), '0.1', true);

Make sure you check the WordPress.org documentation to use wp_enqueue_script() in the right place.

Then in that file you can use JavaScript like this to hook into the ready event of any player:

if( typeof(flowplayer) != "undefined" ) { 
  flowplayer( function(api,root) {
    api.bind('ready', function() {
      alert( 'Video just started!' );
    });
  });
}

Same example like above, but this time affecting only the first player on any page:

document.addEventListener( 'fv_player_loaded', function() {
  var api = flowplayer(0);
  api.bind('ready', function() {
    alert( 'Video just started!' );
  });
}

You can also put the code into the footer.php file of your template after wp_footer(), only this time you will have to put into in a HTML script tag. You should also double check that it works with your Minify plugin if you are using it.

Another option is to modify the .js file provided by your theme, but you can only do this if it’s your own child theme or if you are not going to let WordPress update it.

Important API methods

These can be run on the api object:

• disable(flag) – set flag to true to disable, false to re-enable the player
• fullscreen() – toggle fullscreen
• get_video_link() – get current Video Link along with its playback position, if FV Player’s Video Links are enabled
• load() – play the video
• load(video) – play a specific video, the parameter should be an array like this:

  [{ mpegurl: 'http://mydomain.com/my/other/video.m3u8'}, {webm: 'http://mydomain.com/my/other/video.webm'}, { src: 'http://mydomain.com/my/other/video.mp4', type: 'video/mp4' }, { src: 'http://mydomain.com/my/other/video.ogv', type: 'video/ogg' }]

• next() and prev() – next and previous playlist item
• pause() – pause the video
• play(index) – play a video in playlist
• resume() – resume playback after pause
• seek(time) – seek to time
• speed(speed) – playback speed, set 2 to 2x rate
• stop() – stops the playback and returns to the start of video
• unload() – unload the player
• volume(level) – set player volume, accepts decimal number from 0 to 1

FV Player Pro only:

• ab_loop(flag, start, end) – use to enable/disable AB loop. start and end are optional loop start/end points in seconds.

Usage like in above examples:
api.disable(false);

Player API events

• beforeseek – when the seeking process starts. The 3rd argument is the target seek time.
• cuepoint – when a cuepoint is reached. The 3rd argument is an object with cue time and index.
• error – when an error occurs. The 3rd argument is the object with description of the error.
• finish – when playback has finished.
• fullscreen and fullscreen-exit – when going into/out of fullscreen.
• load – first player event, before the video starts playing
• mute and volume – triggers on mute or volume change
• pause and stop – triggers on pause/stop action
• progress – occurs every 250 ms as the video is playing, third argument is the current video position in seconds
• ready – once the video is loaded and it starts to play, the third argument is the video object
• resume – when video starts playing or when it resumes after being paused
• seek – seeking was completed.
• unload – when player goes back into the splash state.

FV Player Pro only:

• chapter – when advancing to a new chapter. The third argument is the chapter index (starts from 0) and the fourth argument contains the chapter data.

Here is a sample on how to pause a video if it goes to 10th second using the progress event:

if( typeof(flowplayer) != "undefined" ) { 
  flowplayer( function(api,root) {
    var paused = false;
    api.bind('progress', function(e,api,time) {
      if( !paused && time > 10 ) {
        api.pause();
        paused = true;
      }   
    });
  });
}

Tracking API Events

FV Player does trigger the following events as the video plays:

• fv_track_start
• fv_track_first quartile
• fv_track_second quartile
• fv_track_third quartile
• fv_track_complete

These events are only triggered if they come in right order – if you play only the start of the video and then you seek to the end you won’t see the fv_track_complete event running. So it really tells you if the user has seen the whole video.

You can use JavaScript like this to listen on these events and add your own tracking service:

jQuery('.flowplayer').on('fv_track_start fv_track_first_quartile fv_track_second_quartile fv_track_third_quartile fv_track_complete', function(e,api,video_name) {
  console.log('tracking',e.type,video_name);
} );

Video and Player Properties

The Flowplayer object has a lot of properties that can be easily used in your theme to create advanced integrations:

• Video duration api.video.duration
• Video current position api.video.time
• Video playback speed api.currentSpeed (where supported)
• Video loop enabled? api.video.loop
  • you can set this to true while the video plays to make it loop: api.video.loop = true
• Did the player finish playing the video? api.finished
• Is the video loading? api.loading
• Is the video paused? api.paused
• Is the video playing? api.playing
• Is the player ready? That means not loading the video and not showing the video splash screen api.ready
• Is the player showing the video splash screen? api.splash
• Playlist index of a video api.video.index (starts from 0, not present if not a playlist)
• Playlist length api.conf.playlist.length (starts from 0, not present if not a playlist)

Here’s how to obtain the api object:

var api = jQuery('.flowplayer.is-ready').data('flowplayer');
if( api) {
  console.log( 'video duration', api.video.duration );
}

Notice that the selector uses .is-ready to get the player which is actually playing. Even simpler way is to just get the first instance of player on page:

var api = flowplayer(0);

Please note that in many cases it’s better to use events, mainly when hooking actions on video events. The video properties are only available once the video start playing, you can hook into that like this:

if( typeof(flowplayer) != "undefined" ) { 
  // register a global callback function - meaning it will run for each player on the page
  flowplayer( function(api,root) {
    // what to do on the ready event
    api.bind('ready', function( e, api, video ) {
      alert( 'Video duration is '+video.duration );
    });
  });
}

Cuepoints

The cuepoints are used internally to show subtitles and currently FV Player provides on way of setting these with the shortcodes or database. Here’s how you can set the cuepoints for the first FV Player instance on your page:

flowplayer(0).bind('ready', function(e,api) {
  // placing 2 cue points at 5 and 10 seconds, the third one has an extra "custom" property attached to it
  api.setCuepoints( [5, 10, { time: 15, custom: 'data' }] ); 

  // adding another cuepoint
  api.addCuepoint(20);

  // removing the cuepoint which we just added
  api.removeCuepoint(20);
});

Notice that the cuepoints are added after the video has started playling (ready event) – loading the FV Player actually overwrites the cuepoints set with the above functions. You can use JavaScript like this to listen to these cuepoint events:

flowplayer(0).bind('cuepoint', function(e,api,cuepoint) {
  console.log('cuepoint',cuepoint);
});

Usage samples

Always put your scripts into wp_footer hook or include them in footer.php below wp_footer() call.

1. Player initialization via JavaScript

FV Player only loads the scripts if there was a [fvplayer] shortcode used anywhere in the loop, in the widgets or in PHP code.

If the FV Player is not there and you intend to use the JavaScript API make sure you enable Settings -> FV Player -> Compatibility/Integrations -> “Load FV Flowplayer JS everywhere” to make sure the FV Player library is loaded on your page.

A much better option is to put this code to the page template where you need FV Player:

do_action( 'fv_player_force_load_assets');

Make sure the element has dimensions set or set them via JavaScript. Make sure there is no existing video tag in the element, as FV Player will use that instead:

jQuery('#your-element').flowplayer({
  playlist: [
    {
      "sources": [
        { src: "http://example.com/videos/file.mp4", type: "video/mp4" }
      ]
    }
  ]
});

If you want to replace the video with some other one, you can either remove the element and insert a new one with new player, or use the load API call to replace the playing video:

jQuery('#your-element').data('flowplayer').load( [ { src: "https://video-cdn-public.foliovision.com/Swan-Lake-Reloaded-sd.mp4", type: "video/mp4" } ] );

Here’s the code if you also need subtitles:

jQuery('.flowplayer').data('flowplayer').load( [
  {
    subtitles: [
      { srclang: 'en', label: 'English', src: 'https://cdn.foliovision.com/images/2015/05/count_en.vtt' },
      { srclang: 'sk', label: 'Slovak', src: 'https://cdn.foliovision.com/images/2015/05/count_sk.vtt' },
    ],
    src: "https://video-cdn-public.foliovision.com/Swan-Lake-Reloaded-sd.mp4",
    type: "video/mp4"
  }
] );

With FV Player Pro you can set the chapters VTT too:

jQuery('.flowplayer').data('flowplayer').load( [
  {
    chapters: "https://cdn.foliovision.com/images/2017/02/chapters-v2.vtt",
    src: "https://video-cdn-public.foliovision.com/Swan-Lake-Reloaded-sd.mp4",
    type: "video/mp4"
  }
] );

2. How to access and existing player

Call flowplayer() with your element selector and then execute the desired method on it. Like this:

var api = flowplayer('#your-player-wrapping-element .flowplayer');
if( api ) {
  api.load();
}

Note that we did not use the FV Player element ID as that on changes between pageloads.

So it you want to pause any FV Player video playing on the website, just call:

var api = flowplayer('.is-playing');
if( api ) {
  api.pause();
}

You can also get the running video time that way

var api = flowplayer('.is-playing');
if( api ) {
  console.log( api.video.time );
}

3. How to track users watching video until the end with Ajax

Here’s a sample code for FV Player which detects if the user really watched the video to the end (seeking to the end won’t suffice) and send the post ID using Ajax: https://gist.github.com/foliovision/2c266598333ecbd1f151