Programmer’s Guide

Here are some tips on how to tweak FV Player behavior.

• Using custom code to build a player
• WordPress Filters
• JavaScript How To
  • How To Add Your Code
  • Functions
  • Events
    • Player API
    • Video tracking
  • Video and player properties
  • Cuepoints
  • Usage samples
• Determining video length
• Building custom start/end popups
• Customizing labels using translation hooks

Using custom code to build a player

We strongly recommend you avoid this and let us know what would be your preferred way of publishing videos if you don’t like our shortcodes.

You can put in the shortcode into a PHP function:

echo do_shortcode('[fvplayer src="video.mp4"]');

You can call the function directly:

echo flowplayer_content_handle( array( "src" => "video.mp4" ) );

Here’s a quick sample of how to feed in values from postmeta:

if( function_exists('flowplayer_content_handle') && $meta = get_post_meta( get_the_ID(), 'my-field', true ) ) {
  $args = array();
  $args['src'] = $meta;
  if( $splash = get_post_meta( get_the_ID(), 'my-field-for-splash-screen-url', true ) ) {
    $args['splash'] = $splash;
  }
  echo flowplayer_content_handle( $args );
}

Available WordPress filters

You probably already know how WordPress filters work, you can read the Filter Reference on wordpress.org here.

List of available filters:

fv_flowplayer_ad_html – allows you to customize what’s in the ad which shows once the video starts playing. You can use the global $post variable to check what post is being served.

fv_flowplayer_args_pre – all the shortcode arguments before processing. Here’s a code snippet to enable autoplay if ?autoplay is in URL:

add_filter( 'fv_flowplayer_args_pre', 'fv_tweak_fv_flowplayer_args_pre' );

function fv_tweak_fv_flowplayer_args_pre( $args ) {
  if( isset($_GET['autoplay']) ) $args['autoplay'] = 'true';
  return $args;
}

Or another code snippet which will automatically use the post featured image as splash:

add_filter( 'fv_flowplayer_args_pre', 'fv_tweak_fv_flowplayer_args_pre' );

function fv_tweak_fv_flowplayer_args_pre( $args ) {
  global $post;
  if( !empty($post) && empty($args['splash']) ) $args['splash'] = get_the_post_thumbnail_url( $post->ID, 'large' );
  return $args;
}

Make sure you replace the “large” image size with what’s the best fit for the size of your player.

fv_flowplayer_autobuffer_limit – customize how many videos should be autobuffering when the plugin option is enabled. Default is 2.

fv_flowplayer_amazon_expires – allows you to customize the URL expiration time in seconds. First argument is the duration and second is the file URL

fv_flowplayer_amazon_secure_exclude – allows you to exclude URL from the process of adding the access tokens. File URL is the argument, return true to skip the file.

fv_flowplayer_attributes – first parameter is an array of all attributes of the player DIV element, second is the video URL. You can use the global $post variable to check what post is being served. The most important attributes are:

•   class – CSS class of the element
• data-cuepoints – allows you to put in cue points. Use data like [10, 30, 60, 120]
• data-embed – set to “false” to disable embedding of video
• data-engine – set to “flash” to prefer Flash for the video
• data-fullscreen – set to “false” to disable fullscreen option
• data-key – license key
• data-keyboard – set to “false” to disable keyboard shortcuts
• data-logo – path to your player logo. Only works with a valid license key.
• data-rtmp – set the RTMP endpoint URL
• style – the inline style attribute of the player container. Used for video dimensions.

Add a play button to control bar of the players (easily done, as it’s just a CSS class):

add_filter( 'fv_flowplayer_attributes', 'tweak_fv_flowplayer_attributes', 10, 2 );
function tweak_fv_flowplayer_attributes( $attrs ) {
  $attrs['class'] .= ' play-button';
  return $attrs;
}

fv_flowplayer_conf – allows you to tweak the core Flowplayer JavaScript conf variables. The following sample sets the custom speeds for the speed menu (visible is you have the Speed Buttons enabled)

add_filter( 'fv_flowplayer_conf', 'tweak_fv_flowplayer_conf' );
function tweak_fv_flowplayer_conf( $conf) {
  $conf['speed'] = array( 0.9, 0.95, 1, 1.05, 1.1 );
  return $conf;
}

fv_flowplayer_inner_html – allows you to insert any HTML into the player container, right after the video and popup elements

fv_flowplayer_html – allows you to adjust all the basic player HTML, but not the actual controls as these are added by JavaScript

fv_flowplayer_popup_html – allows you to customize what’s in the popup which shows at the end of video. You can use the global $post variable to check what post is being served.

Here’s a code to auto-generate a popup for each player:

// the popup argument in shortcode has to be present, so we add it
add_filter( 'fv_flowplayer_args_pre', 'fv_tweak_fv_flowplayer_args_pre' );

function fv_tweak_fv_flowplayer_args_pre( $args ) {
  if( !$args['popup'] ) $args['popup'] = 'custom';
  return $args;
}

add_filter( 'fv_flowplayer_popup_html', 'fv_tweak_fv_flowplayer_popup_html' );

function fv_tweak_fv_flowplayer_popup_html( $html ) {
  global $fv_fp;
  if( $fv_fp->aCurArgs['popup'] == 'custom' && in_the_loop() ) { // changing the HTML of popup only if it's the custom popup
    $post_categories = wp_get_post_categories( get_the_ID() ); // we can check the post categories for example
    if( $post_categories ) {
      $cat = get_category($post_categories[0]);
      $html = "Check more posts in <a target="_blank" href="".get_category_link($cat)."">".$cat->name."</a>!";
    }    
  }
  return $html;
}

fv_flowplayer_video_src – allows you adjust any video URL.

Here’s a code to append a token to the query string part of video URL:

add_filter( 'fv_flowplayer_video_src', 'tweak_fv_flowplayer_video_src' );

function tweak_fv_flowplayer_video_src( $url ) {
  $url = add_query_arg( 'token', 'SAMPLETOKEN', $url );
  return $url;
}

fv_player_item – modify most of the video properties. Typically the filter receives and array like this:

array (
  'sources' => 
  array (
    0 => 
    array (
      'src' => 'https://foliovision.com/videos/dominika-960-31.mp4',
      'type' => 'video/mp4',
    ),
  ),
  'fv_title' => 'This item has subtitles',
  'splash' => 'https://foliovision.com/video/burning-hula-hoop-girl-dominika.jpg',
  'subtitles' => 
  array (
    0 => 
    stdClass::__set_state(array(
       'srclang' => 'en',
       'label' => 'English',
       'src' => 'https://foliovision.com/images/2015/05/count_en.vtt',
       'default' => true,
    )),
  ),
)

fv_player_pro_drm_text – modify what shows up in the FV Player Pro DRM Text. The argument is an array with keys: id, email, name, IP, date, site.

Here’s a code to remove the email address:

add_filter( 'fv_player_pro_drm_text', 'tweak_fv_player_pro_drm_text' );

function tweak_fv_player_pro_drm_text( $data) {
  unset( $data['email'] );
  return $data;
}

fv_player_sharing_html – player sharing buttons HTML.

Let us know if you are missing any filters!

Using FV Player JavaScript API

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

• disable(flag) – set flag to true to disable, false to re-enable the player
• fullscreen() – toggle fullscreen
• 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() – set player volume

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.
• seek – seeking was completed.
• unload – when player goes back into the splash state.

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

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() {
      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

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 if it has no [fvplayer] shortcode in it.

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" } ] );

2. How to use the above API methods

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

flowplayer('#your-element').play();

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

flowplayer('.is-playing').pause()

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

Determining Video Length

How to get started

First you need to enable Integrations > Scan video length. Enabling this option puts all your posts with [fvplayer...] shortcode into a queue, and then a cron scans the videos in those posts and stores the length of each video.

Saving a post also triggers the check.

• There is a strict time limit when saving a post – 2 seconds. If the video is not properly checked within that time (bad encoding, slow connection from server), then it’s put into a queue for the scheduled cron job. So you might not see the duration of all videos right away.
• The video duration is checked only once per URL. If you change your video substantially, we expect that you also change the file name.
• If you really need to refresh it, you can remove _fv_flowplayer_% meta tag for your post ID in wp_postmeta table. Make sure you backup your database before proceeding, unless you really know SQL. Then disable/re-enable the Integrations > Scan video length option to run the video duration indexing again.

What videos are supported?

The video has to be properly encoded, the moov meta data must be at the beginning of the file. Currently we don’t support this for MPEG-DASH or RTMP streams.

How to show the video durations

Video duration is put up for:

1. Individual videos
2. Playlists

The time duration is hidden in CSS, to not disrupt normal users. You need to use CSS to make it visible:

1. Invididual videos – .fvfp_duration { display: block }
2. Playlists – .fp-playlist-external .dur { display: inline-block }

You can also use the following PHP code to show duration of the first video in a post in your templates:

echo flowplayer::get_duration_post( $post_id )

You can also use this shortcode to show duration of the previous video in the post. So if you have multiple [fvplayer] shortcodes in the post, you can put this shortcode after each and it will show the duration: [fv_time].

Building custom start/end popups

The FV Player playback state classes are very powerful. So you can append your HTML to the player DIV element and then write CSS to show/hide it based on the player status:

• is-finished – after playback has finished
• is-loading – while the video is initially loading
• is-mouseout – while the mouse is outside the player area
• is-mouseover – while the mouse hovers over the player area
• is-ready.is-paused – while the player is paused
• is-playing – while the player is playing
• is-ready – once the loading phase has finished
• is-seeking – while the player is seeking
• is-small – while the player is of less than 600px, but no less than 400px width
• is-splash – while the splash screen is visible and awaits a click
• is-tiny – while the player is of less than 400px width

Practically speaking, here is a sample PHP code to add some HTML into the player:

add_filter( 'fv_flowplayer_inner_html', 'my_fv_player_custom_popup');

function my_fv_player_custom_popup($html) {
  $html .= '<div class="my-custom-popup"><div class="my-custom-popup-content"><h2>Announcement</h2><p>Some important offer which you must not miss!</p></div></div>';
  return $html;
}

And here is the CSS code to make it cover the entire player area with some transparency and make it appear when the video is finished:

.my-custom-popup {
    position: absolute;
    top: 25%;
    width: 100%;
    display: none;
    z-index: 1; /* required to keep the content clickable */ 
}
.is-finished .my-custom-popup {
    display: block;
}
.my-custom-popup-content {
    background: white;
    max-width: 400px;
    margin: 0 auto;
    padding: .5em 1em;
}

Customizing labels using translation hooks

gettext is a useful WordPress filter as it lets you custmize any of the FV Player (or WordPress) text labels without need for a separate language file. So if you only need to change a single label here’s a code sample.

This one changes the placeholder text of the search input found in FV Player Pro Interactive Transcript feature:

add_filter( 'gettext', 'tweak_fv_player_pro_fp_transcript_search', 999, 3 );

function tweak_fv_player_pro_fp_transcript_search( $translation, $text, $domain ) {
  if( $domain == 'fv-player-pro' ) {
    if( $text == 'Search' ) {
      $translation = 'Search the transcript';
    }
  }
  return $translation;
}