API | Programmer’s Guide

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

• Using custom code to build a player
• Fine tuning player settings
• WordPress Filters
• 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 id="716"]');

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

Fine tuning player settings

FV Player does not offer the most granular settings. We believe in intelligent defaults and presets. If you need to tweak the settings then we can always suggest the code to achieve your needs, if we can understand these needs.

Handle WordPress audio/video

This is one of the Integrations/Compatibility settings.

Use this code in your PHP template to prevent FV Player from changing the YouTube links and embed codes to FV Player:

remove_filter( 'the_content', 'fv_player_handle_youtube_links' );
remove_filter( 'embed_oembed_html', 'fv_player_handle_youtube_links' );

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_splash – allows you adjust the first video splash screen.

fv_flowplayer_playlist_splash – allows you adjust the playlist videos splash screens.

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,
    )),
  ),
  /**
   * Start/end time in seconds, if using FV Player Pro
   * Custom Start/End Time
   */ 
  'fv_start' => 10,
  'fv_end' => 30
)

fv_player_drm_stream_loader_output – HLS m3u8 files server via FV Player Pro Stream Loader.

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. Other array keys are not supported.

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'] );

  // You can get the current user data using the standard WordPress function call
  $user_data = wp_get_current_user();
  if ( ! empty( $user_data->ID ) ) {
    /* more of your code here */
  }

  return $data;
}

fv_player_sharing_html – player sharing buttons HTML.

fv_player_stats_view_exclude_posts_query_args – use to return a WP_Query arguments array which will then cause these posts to not show in FV Player -> Stats screen graphs.

// I don't want page ID 84144 to ever show in our video playback stats
add_filter(
  'fv_player_stats_view_exclude_posts_query_args',
  function( $args ) {
    return array( 
      'page_id' => 84144
    );
  }
);

Let us know if you are missing any filters!

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.

If you are not a programmer, please head over to How to change FV Player Translations and Labels.

The following code changes the “Item 1.” text found in the player controlbar for playlists:

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

function tweak_fv_player_playlist_item_controlbar( $translation, $text, $domain ) {
  if( $domain == 'fv-wordpress-flowplayer' ) {
    if( $text == 'Item %d.' ) {
      $translation = 'Video %d.';
    }
  }
  return $translation;
}

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;
}