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 (see events below) of any player:
if( typeof(flowplayer) != "undefined" ) { flowplayer( function(api,root) { api.bind('ready', function( e, api, video ) { alert( 'Video ' + video.fv_title + ' 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.
Usage like in above examples:
api.disable(false);
disable(flag)
– set flag to true to disable, false to re-enable the playerfullscreen()
– toggle fullscreenget_video_link()
– get current Video Link along with its playback position, if FV Player’s Video Links are enabledload()
– play the videoload(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()
andprev()
– next and previous playlist itempause()
– pause the videoplay(index)
– play a video in playlistresume()
– resume playback after pauseseek(time)
– seek to timespeed(speed)
– playback speed, set 2 to 2x ratestop()
– stops the playback and returns to the start of videounload()
– unload the playervolume(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
andend
are optional loop start/end points in seconds. Please note that AB Loop has to be activated in settings first.
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
andfullscreen-exit
– when going into/out of fullscreen.load
– first player event, before the video starts playingmute
andvolume
– triggers on mute or volume changepause
andstop
– triggers on pause/stop actionprogress
– occurs every 250 ms as the video is playing, third argument is the current video position in secondsready
– once the video is loaded and it starts to play, the third argument is the video objectresume
– when video starts playing or when it resumes after being pausedseek
– seeking was completed.unload
– when player goes back into the splash state.
FV Player Pro only:
abloop
– when toggling the AB loop bar. The third argument is theactive
flag.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 title
api.video.fv_title
- 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
- you can set this to true while the video plays to make it loop:
- 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 video an FV Player Pro video ad?
typeof api.video.click != "undefined"
- 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 Examples
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
4. How to show the AB loop bar by default
FV Player Pro AB Loop function can be enabled in settings, but it only adds the button and does not show it by default. Activate that setting and use this code to show the AB Loop bar when video starts.
flowplayer( function( api, root ) { api.on( 'ready', function() { api.ab_loop( true, 0, api.video.duration ); } ); } );