Setting up

How to install and configure Flowplayer.

Table of contents

Doctype

At the top of your page declare the HTML5 doctype:

<!DOCTYPE html>

This is mandatory. Otherwise HTML5 video will not work in some browsers, notably Internet Explorer 9. Do not add a transitional doctype or other non-html5 stuff.

Prerequisites

Load the required assets and declare the page title — the TITLE tag is mandatory for HTML5 pages — in the HEAD section of your page:

<title>My Flowplayer video</title>

<!-- 1. skin -->
<link rel="stylesheet" href="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/skin/skin.css">

<!-- 2. jquery library - required for video tag based installs -->
<script src="{{ config.flowplayer7.jquery }}"></script>

<!-- 3. flowplayer -->
<script src="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/flowplayer.min.js"></script>
  • These assets are served globally from a content delivery network. Free for you to use.
  • You can place the files on your own servers too, maybe combine them with your existing files for faster initial load. The latest commercial version is always available from your account page.
  • jQuery v1.7.2+ is required for VIDEO tag based installations. Make sure to load only one version of the library when integrating Flowplayer in an existing page.
  • Alternate skins are available.
  • In general it is recommended to load CSS stylesheets before JavaScript assets.
  • If you host the player files yourself, make sure to set CORS headers for the font files. See also the skinning docs.
  • It is not recommended to load the Flowplayer and jQuery Javascripts in the BODY or at the end of the document.

Loading assets in <body> or at the bottom of the page is not recommended and will usually not speed up page rendering.

Installation

For each player you need to prepare a html DIV element as player container inside the BODY of your page.

3 ways to install

  • automatic installation: quick, no fuss, no scripting required, and yet entirely customizable, including complete API access if the need arises
  • manual installation: install on demand, individual customization both in HTML and JSON syntax
  • pure JavaScript installation: complete and consistent control via JavaScript, no dependence on external libraries, advanced configuration and seamless API integration

2 installation categories

<video>
   <source type="application/x-mpegurl" src="//mydomain.com/video.m3u8">
   <source type="video/mp4"             src="//mydomain.com/video.mp4">
</video>
clip: {
    sources: [
        { type: "application/x-mpegurl",
          src:  "//mydomain.com/video.m3u8" },
        { type: "video/mp4",
          src:  "//mydomain.com/video.mp4" }
    ]
}

Video tag based

These installation methods require the jQuery library to be loaded.

Always use SOURCE tags inside the VIDEO tag and specify the video type. Flowplayer will then tweak the VIDEO tag as needed by platform or browser. Or, for the Flash engine, replace it with a Flash OBJECT.

Advantages of video tag based installations:

  • The video is represented in the page source code in a static fashion. For you, as the page creator: what you see is what you mean.
  • For many users the easiest way to get started.

Restrictions of video tag based installations:

  • Fine-tuning the configuration on the clip and source level is not possible or only in a restricted way for playlists.

Automatic installation

Flowplayer will be installed automatically into each container element for which the magic CSS class "flowplayer" is specified:

<div class="flowplayer">
   <video>
      <source type="application/x-mpegurl" src="//mydomain.com/video.m3u8">
      <source type="video/mp4"             src="//mydomain.com/video.mp4">
   </video>
</div>

Advantages of the automatic installation method:

Restriction of the automatic installation method:

  • will and can only be run once at page load.

The automatic method is used in the quick start guide and an example for the automatic method is shipped with each Flowplayer distribution as minimal example setup.

The automatic installation method is ideal to get started with Flowplayer, and for quick no-fuss results.

[View standalone page]({{ config.flowplayer7.standalonedemos }}/basics/minimal/)

Manual installation with jQuery

<div class="player">
   <video>
      <source type="application/x-mpegurl" src="//mydomain.com/video.m3u8">
      <source type="video/mp4"             src="//mydomain.com/video.mp4">
   </video>
</div>

<script>
// run script after document is ready
$(function () {

   // install flowplayer into all elements with CSS class="player"
   $(".player").flowplayer();

});
</script>
  • The player is installed using the flowplayer jQuery plugin.
  • Container elements are targeted with a jQuery selector.

Advantages of the manual method over automatic installation:

Advantage of the manual method over pure JavaScript installation:

  • jQuery allows you to select several container elements as install targets in one flowplayer call. The pure method can target only one element at a time, as it also must configure the individual video clip.
$(".player").flowplayer({
    // configuration common to all players in
    // containers with class="player" goes here
});

The manual installation method makes it easy to fine tune the customization of individual players in a flexible fashion.

[View standalone page]({{ config.flowplayer7.standalonedemos }}/basics/manual)

Pure JavaScript

This installation method uses flowplayer() as pure JavaScript function. It takes a reference to the container element as first argument, and the player configuration as mandatory second argument.

<div id="player"></div>

<script>
// select the above element as player container
var container = document.getElementById("player");

// install flowplayer into selected container
flowplayer(container, {
    clip: {
        sources: [
              { type: "application/x-mpegurl",
                src:  "//mydomain.com/video.m3u8" },
              { type: "video/mp4",
                src:  "//mydomain.com/video.mp4" }
        ]
    }
});
</script>

Because video sources are absent on the page the clip object featuring its mandatory sources property must be specified.

For convenience the container reference in the first argument can also be written in shorthand as a simple string formatted in jQuery selector syntax:

// install into container with id="#player"
// corresponding jquery selector: $("#player")

flowplayer("#player", {
    // mandatory player and clip configuration goes here
});

If the first argument references an array of elements, only the first array member will be targeted. To avoid surprises make sure that you always select a single unique element as installation target.

If the jQuery library is loaded, flowplayer() can also be invoked as jQuery extension like in the VIDEO tag based installation methods with the player configuration including clip in the first argument:

$("#player").flowplayer({
    // mandatory player and clip configuration goes here
});

The jQuery invocation syntax is strongly discouraged for this installation method because it will not give instant access to the Flowplayer JavaScript API and blurs the structure of the code.

Advantages of the pure JavaScript installation in addition to those of the manual installation:

  • It does not depend on an external library — you may still use jQuery of course.
  • Availability of some advanced features with playlists, like subtitles or looping of individual clips.
  • The entire player functionality is controled in one place, in one language.
  • A reference to a specific player's JavaScript API can be created in one step at installation time.
  • The page will load faster because no VIDEO tag is present, especially with multiple splash setups.

Restrictions of the pure JavaScript installation:

  • Only one player can be installed per flowplayer() call.
  • By definition options set via HTML data attributes have no effect.

If you want clearly structured code suited for long-term maintenance and extensibility, choose the JavaScript installation method.

Clip object

The clip object is Flowplayer's concept and understanding of video content.

The clip configuration object is the representation of a HTML5 VIDEO tag, including Flash video, in JavaScript Object Notation.

Each object in a clip's sources array is the representation of a HTML5 SOURCE tag in JavaScript Object Notation.

[View standalone page]({{ config.flowplayer7.standalonedemos }}/basics/pure-js)

Installation summary

    • method
    • container selection
    • characteristic
    • automatic video tag
    • CSS class flowplayer
    • static
    • manual video tag
    • jQuery
    • mixed
    • pure JavaScript empty container
    • JavaScript
    • dynamic

In all setup variants, make sure to set a player ratio to avoid letterboxes or whitespace around the video.

Video

The Flowplayer engines can play a slew of video formats: all videos which can be played by a HTML5 video tag or by Flash.

However, one of the main purposes of using Flowplayer is to achieve cross browser and cross device compatibility, so your videos can be viewed in all browsers and on all mobile devices. To achieve that goal, the videos must meet the these criteria:

  1. They must be correctly encoded for the purpose. See the encoding docs if you want to do this yourself.
  2. Not every format can be played in every browser or on every device. The trick is to find a combination of formats which meets the cross compatibility criterion with the least amount of fuss.

The second point will be covered in this section.

Clip and sources

clip is how we call the sum of everything related to one video content.

sources is how we call the format variants of this video, i.e., technically differing representations of the same one content.

The audience will watch one clip - the content -, but to grant an optimal viewing experience the player should be provided with several sources to choose from:

Video formats

Flowplayer supports playback of the following video formats:

    • format and src type
    • delivery
    • HLS application/x-mpegurl
    • http html5 or Flash
    • WebM video/webm
    • http html5
    • MP4 video/mp4 (html5) video/flash (Flash)
    • http html5 or rtmp Flash
    • OGG video/ogg
    • http html5
    • FLV video/flash
    • http or rtmp Flash
    • DASH application/dash+xml
    • http html5

The src type is the same as the MIME type of the video, expect for the Flowplayer-unique video/flash src type, which forces the Flash engine.

  • OGG is an old format and while is still works has been superseded by WebM and MP4 a long time ago, we do not recommend to use it anymore.
  • Flash (and hence FLV which can only be played in Flash) is quickly being deprecated and will strop working in any major browser soon, so it should be avoided.

Livestreaming

Flowplayer support livestreams through HLS and DASH . rtmp livestreams are supported in the Flash engine but not recommended, as there is no multibitrate support, and Flash support is being outphased by browser manufacturers.

Simply switch the player to live mode by setting the live option for player or clip to true.

Adaptive Bitrate Streaming

Adaptive bitrate streaming means the player will adjust the quality (bitrate and resolution) of the video to the bandwidth available to your browser while it plays the clip. This is possible with both HLS and DASH streams if your stream source has multiple variants. Flowplayer will start with the best possible quality and continously monitor the bandwdith, adaping to any fluctuations by switching to a higher or lower qualiyt where needed.

For HLS, Flowplayer also offers manual selection in the hlsjs and Flash engines (MacOS and iOS native HLS implementations do not allow manual selection).

HLS

HLS is the only cross-device and cross-browser compatible format for livestreams and live DVR. Other solutions do not cover all scenarios:

  • RTMP delivery requires Flash and does not support DVR
  • DASH requires a modern browser with MediaSource support, and for lack of the latter also does not work on iOS

Both of the above are supported by Flowplayer, but you would still need to offer HLS for cross-compatibility.

Flowplayer supports HLS everywhere:

  • v7.2.1+ with the integrated hlsjs-lite engine

  • native playback in browsers which can play HLS

  • with its Flash engine in older browsers

As Flash is on the decline, we recommend to make your streams and server ready for hlsjs. The recommendations apply for hlsjs-lite as well.

hlsjs-lite

Since version 7.2.1 , Flowplayer features an integrated interface to the hls.js client library. Use it by loading the hls.js client library before flowplayer.min.js . For standard usage you cand eploy the light version, if you need multiple audio track support or other advanced features, implement the full library.

Sample:

<!-- head section -->
<!-- skin -->
<link rel="stylesheet" href="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/skin/skin.css">
<!-- hls.js -->
<script src="{{ config.flowplayer7.hls_js_light }}"></script>
<!-- flowplayer -->
<script src="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/flowplayer.min.js"></script>

<!-- body section -->
<div id="player"></div>

<script>
        flowplayer('#player', {
            live: true,  // set if it's a livestream
            ratio: 9/16, // set the aspect ratio of the stream
            clip: {
                sources: [
                    // path to the HLS m3u8
                    { type: "application/x-mpegurl", src: "//yourserver/path/index.m3u8"},
                    // path to an optional MP4 fallback, usually not available for live feeds
                    { type: "video/mp4", src: "//yourserver/path/index.mp4"}
                ]
            }
        });
</script>

hls.js configuration

All configuration is done by the hlsjs option:

    • option
    • description
    • hlsjs boolean
    • Players can be told to disable the plugin by setting this to false. Normally used only for testing Flash HLS.

The hlsjs configuration object makes all hls.js tuning parameters available for Flowplayer.

Additionally hlsjs accepts the following Flowplayer-specific properties:

    • option
    • description
    • bufferWhilePaused boolean
    • If set to true, stops prebuffering of HSL segments in paused state. Use with caution and consider setting the hls.js buffer options instead. Default: false
    • recoverMediaError boolean
    • When true, the hlsjs engine will try to recover from otherwise fatal decoding errors if possible. Default: false
    • recoverNetworkError boolean
    • When true, the hlsjs engine will try to recover from otherwise fatal network errors if possible.Note: Enabling network error recovery changes player behaviour, and only for the hlsjs engine. Default: false
    • safari boolean
    • If set to true the plugin is enabled in Safari. Please read the section on browser support before enabling this option. Default: false

hls.js event listening

The hlsjs-lite engine listens to error events, so you can establish a reconnect script on the player config level like in this sample code:

<script>
window.onload = function () {

  var container = document.getElementById("live"),
      player,
      initialDelay = 10,
      timer,
      // clone default errors for customization
      customErrors = flowplayer.defaults.errors.slice(0),
      customError = "<h2>We are sorry, currently no livestream available.</h2>"
                  + "<p>Retrying in <span>" + initialDelay + "</span> seconds ...</p>",
      // preload error image; case: user disconnects
      errImage = new Image();

  customErrors[2] = customError;
  customErrors[4] = customError;

  player = flowplayer(container, {
    // use custom errors 2 and 4
    errors: customErrors,
    ratio: 9/16,
    splash: true,
    live: true,
    share: false,
    hlsjs: {
        xhrSetup: function (xhr, url) {
          var isPlaylist = url.lastIndexOf(".m3u8") === url.length - 5;

          xhr.addEventListener("error", function () {
            if (isPlaylist) {
              // intentionally throw Network error
              player.trigger("error", [player, {code: 2}]);
            }
          });
          xhr.addEventListener("readystatechange", function (e) {
            var xstatus = e.currentTarget.status;
            if (isPlaylist && xhr.readyState === 4 && xstatus >= 400 && xstatus < 499) {
              // intentionally throw Video file not found error
              player.trigger("error", [player, {code: 4}]);
            }
          });
        }
      },
    clip: {
      flashls: {
        // limit amount of retries to load hls manifests in Flash
        manifestloadmaxretry: 2
      },
      sources: [
        { type: "application/x-mpegurl",
          src:  "//path/to/your.m3u8" }
      ]
    }

  }).on("error", function (e, api, err) {
    var delay = initialDelay;

    clearInterval(timer);

    if (err.code === 2 || err.code === 4) {
      container.className += " is-offline";

      if (flowplayer.support.flashVideo) {
        api.one("flashdisabled", function () {
          container.querySelector(".fp-flash-disabled").style.display = "none";
        });
      }

      timer = setInterval(function () {
        var messageElement = container.querySelector(".fp-ui .fp-message");

        delay -= 1;

        if (delay && messageElement) {
          messageElement.querySelector("span").innerHTML = delay;
          // only for disconnected user:
          messageElement.style.backgroundImage = "url(" + errImage.src + ")";
        } else {
          clearInterval(timer);
          api.error = api.loading = false;
          if (messageElement) {
            container.querySelector(".fp-ui").removeChild(messageElement);
          }
          container.className = container.className.replace(/\bis-(error|offline)\b/g, "");
          api.load();
        }

      }, 1000);
    }

  });

  // preload error image in case of network timeouts
  errImage.src = "//pathto/img/interruption.png";

  /*
   * the following is for demo purposes and simulation only
   * do not use in production!
   */

  var buttons = document.getElementsByTagName("button"),
      i;

  for (i = 0; i < buttons.length; i += 1) {
    buttons[i].onclick = function () {
      var errorstream = !this.id
          ? null
          : this.id === "dummy"
            ? "//edge.flowplayer.org/dummy-live.m3u8"
            : "//edge.flowplayer.org/non-existent.m3u8";

      if (player.error) {
        // clean retry
        player.error = player.loading = false;
        container.className = container.className.replace(/\bis-offline\b/, "");
        container.className = container.className.replace(/\bis-error\b/, "");
      }

      if (errorstream) {
        player.load({
          sources: [
            { type: "application/x-mpegurl", src: errorstream }
          ]
        });
      } else {
        player.load(player.conf.clip);
      }
    };
  }

};
</script>

hls.js JavaScript API

The plugin provides complete access to the hls.js client API via the engine.hls property.

Simple example:

// switch to first hls level
flowplayer(0).engine.hls.nextLevel = 0;

hls.js locations

hls.js light
  • https://cdn.jsdelivr.net/npm/hls.js@0.12.0/dist/hls.light.min.js
  • https://cdn.jsdelivr.net/hls.js/latest/hls.light.min.js (always latest)
  • https://cdnjs.cloudflare.com/ajax/libs/hls.js/0.10.1/hls.light.min.js (not up to date)
hls.js full package
  • https://cdn.jsdelivr.net/npm/hls.js@0.12.0/dist/hls.min.js
  • https://cdn.jsdelivr.net/hls.js/latest/hls.min.js (always latest)

  • https://cdnjs.cloudflare.com/ajax/libs/hls.js/0.10.1/hls.min.js (not up to date)

    Stream compatibility

For stream compatibility check the list of supported m3u8 tags and the as of yet unsupported HLS features.

Chromecast cannot play streams with alternate audio renditions.

Test your streams in the hls.js demo player. In case of playback issues with the hls.js client, we encourage you to use the hls.js bug tracker as first port of call.

Server side

The video streams must be served with a cross domain policy (CORS) allowing GET requests. If the segments are not static files, but are retrieved via byte-range requests HEAD and OPTIONS must be allowed as well.

Sample CORS Configuration for Amazon S3:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>

        <!-- only required for byte-range based retrieval -->
        <AllowedMethod>HEAD</AllowedMethod>

        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>

For other server configurations, please check enable-cors.org .

On a https site, you MUST load the stream with https as well. Modern browsers do not allow mixed content, hence you cannot use a http HLS stream on a https site.

HLS quality selection

Manual HLS quality selection is available out of the box via the HD menu if the stream is delivered from a root playlist pointing to several variants.

Note: Native HLS playback - for example on iOS - does not allow manual HLS level selection. This feature is available with hlsjs and Flash HLS.

By default all HLS levels are shown in the HD menu. Manual selection can be disabled or a specific set of HLS levels specified with the hlsQualities option on the global, player, and clip level.

DASH

Flowplayer supports MPEG-DASH

  • with the dashjs plugin in modern browsers

  • On https site, you MUST load the stream with https as well. Modern browsers do not allow mixed content, hence you cannot use a http HLS stream on a https site.

DRM

HLS offers the best content protection in HTML5 video. Flowplayer supports encrypted HLS also in Flash — check out the demo.

The dashjs plugin also supports many encrypted DASH streams.

Since MP4 is now supported by almost all browsers, e recommend to offer a correctly encoded MP4 for short videos if you don't need quality selection, and HLS as the primary source for longer clips and if you need manual quality selection. Additionally you can provide an MP4 fallback source.

This is also the default offering in our platform

In case you intend to also offer an WebM version (VOD only): to be chosen it should be listed before MP4, because all current browsers now support MP4 playback, and will never get to pick WebM otherwise.

Picking order

The order in which you specify the sources matters. Flowplayer will cycle through the sources and choose the first source it can play.

If a source can be played by more than one engine Flowplayer will try the html5 engine first. The main candidates for this scenario are the HLS and MP4 formats: If the browser cannot play the format and its Flash plugin is enabled, then this source will be played using the flash engine. - Exception for convenience: If HTML5 video is not supported by the browser, HLS is not on offer, but an RTMP stream, the RTMP stream takes precedence over MP4 via HTTP.

You can completely control the picking order by setting the engine source option explicitly.

This is the recommended order to provide the sources by type:

  1. application/x-mpegurl - HLS - Adaptive Bitrate Streaming allows optimal quality according to bandwidth and device compatibility; reduces Content Delivery Network costs as some browsers will keep downloading a video file even while playback is paused
  2. video/webm - WebM - before MP4 because otherwise it won't be chosen.
  3. video/mp4 - also required as Flash fallback if neither HLS nor an RTMP stream is available; for mobile device compatibility refer to our encoding documentation
  4. video/flash - MP4 over RTMP if HLS is not available - allows random seeking if html5 video is not available

Layout

This section covers how the player is presented on the page before playback starts.

Player size

The size of the player is determined by the dimensions of the container element. For example you can hard code them using CSS directives:

.flowplayer {
   width: 600px;
   height: 338px;
}

However, hard coding width and height of the container element foregoes Flowplayer's responsive design: If you do not specify fixed dimensions for the container like above, the player will adapt itself to the dimensions of the parent element according to its ratio setting (see below) - very useful to make the player look good on small mobile screens for example. Therefore it is recommended to either just omit dimension directives, or you can use more flexible CSS rules like max-width and/or max-height:

.flowplayer {
   max-width: 800px;
}

By default Flowplayer uses all the width that is given via CSS or the width of the container's parent element. The height of the player is determined by the aspectRatio or ratio configuration settings which default to "16:9" or 9/16 respectively. Under the premise that letterboxing or empty sidebars on the video screen are to be avoided, this assumes a video of 16/9 aspect ratio. Note that the ratio notation is the inverse ratio of how one usually specifies the aspect ratio of a video: height/width (container) as opposed to width/height (video). html5 video cannot be stretched/squeezed/cropped , so it will always retain the aspect ratio of the video, even if you set a different container ratio.

You can change the ratio in the global player configuration:

flowplayer.conf.aspectRatio = "4:3";

This is the same as:

flowplayer.conf.ratio = 3/4;

Or you can set the ratio in the HTML configuration using the data-aspect-ratio or data-ratio attribute of the container element as follows:

<div class="flowplayer" data-aspect-ratio="4:3">
   <video>...</video>
</div>

This is the same as:

<div class="flowplayer" data-ratio="0.75">
   <video>...</video>
</div>

You may round a floating point value, but you should not go below a precision of 4 decimals.

Here are the player ratio values for some widely used video aspect ratios:

    • aspect ratio
    • fraction ratio
    • float ratio
    • 16:9 landscape
    • 9/16 default
    • 0.5625
    • 4:3 landscape
    • 3/4
    • 0.75
    • 12:5 landscape
    • 5/12
    • 0.4167
    • 9:16 portrait
    • 16/9
    • 1.1778
    • 3:4 portrait
    • 4/3
    • 1.3333

Alternatively you can change the container's ratio via CSS while setting the ratio option to false:

.flowplayer .fp-ratio {
   padding-top 41.67%
}

Now when you resize the browser the video size will adjust accordingly, and the player's width/height ratio is kept.

You may also let the player size dynamically be determined by the video's aspect ratio: Set the adaptiveRatio player option to true.

This comes in handy for quick setups when you do not happen to know the exact dimensions of the video, but still want the player's screen size to match the aspect ratio of the video. By consequence refrain from configuring adaptiveRatio for a splash setup as the video's dimensions - and therefore its aspect ratio are only available once the video is loaded and the player is ready.

Start screen

In a basic setup like the one in our quick start guide the video is loaded and the first frame is shown - unless autoplay is configured.

In most cases however, you want to customize the initial screen as what is often called a splash or poster screen. Flowplayer offers two techniques to implement a start screen which are also named "poster" and "splash".

Common features of "poster" and "splash":

  • The visible result: the player area is filled with an image or coloring, and in the middle sits the play button to advertise a video player and invite the audience to play the video.
  • The implementation method: entirely via CSS, background-image or a background-color or both, as directives for the container element - not mandatory for "splash" because it also changes the initial player behaviour, see below.

Where "poster" and "splash" differ is their behaviour:

  • poster the video is loaded in the background
  • splash the video is loaded on demand, i.e. when the user starts playback with a click

A splash or poster setup is mandatory if the player is hidden at some point in its life cycle. Some browsers forbid hiding the Flash object, and thus errors are encountered when the flash engine is in use. This notably concerns modal window setups.

Poster

The poster setup is recommended when you want to preload the video at startup while giving the player a custom look and feel.

Flowplayer features an extended and flexible concept of the generic poster VIDEO tag attribute: If the poster attribute is given, it will also be used as CSS background image of the container element. Par consequence you can also choose to omit the poster attribute, and instead specify a background image or background color (treated as monochrome "poster") CSS directive to the same effect.

The advantages of this approach:

  1. works consistently in Flash and HTML5
  2. does not break when browser is resized (very hard to do in Flash)
  3. you can take advantage of CSS techniques such as positioning, animations, scaling and many more
  4. you can use CSS sprites and thereby avoid multiple server calls
  5. you get rid of browser issues, for example Internet Explorer 9 loads the first frame of the video on top of the poster image
  6. you can use higher resolution images with Retina and similar devices To sum up, a poster setup requires that
  • a background-image or background-color CSS rule applies to the container element or
  • the poster configuration option is set or
  • the VIDEO tag carries a poster attribute and
  • the splash setup is not enforced.

If both background-image for the container and poster attribute for the VIDEO tag are given, the poster image takes precedence and replaces the background image.

When the above conditions are met, the CSS "is-poster" state class is assigned to the container at startup. For instance this allows you to create a loading animation for the entire player area with a few CSS rules.

[View standalone page]({{ config.flowplayer7.standalonedemos }}/basics/poster)

Splash

Flowplayer has a unique feature called "splash screen" which is similar to the poster setup except that the nested VIDEO or Flash OBJECT tag initially is not present on the page, but is inserted on demand. The player is installed on the fly when the user clicks on the splash screen. This has the following benefits:

  1. You can have an unlimited amount of players on the page and they - or rather their splash screens — all render immediately, even in Flash mode.
  2. There are no hidden Flash objects which interfere with your scripting or CSS layout dynamics.
  3. Only one video can be played at a time. When the user clicks on a splash screen while another player instance is running, the latter is unloaded automatically.

By design the splash setup also disables preloading of the video and therefore autoplay.

To set up splash screens you either add the state class "is-splash" to the CSS class of the container element:

<div class="flowplayer is-splash"
     style="background-color:#777; background-image:url(/path/to/splash.jpg);">
   <video>
      <source type="application/x-mpegurl" src="//mydomain.com/video.m3u8">
      <source type="video/mp4"             src="//mydomain.com/video.mp4">
   </video>
</div>

Or you configure the addition of the "is-splash" state class by setting the splash option to true or to the location of the splash image. For instance this global configuration applies the splash setup to all players on the page:

flowplayer.conf = {
  splash: true
};

The splash image is given in the CSS background-image directive for the container element or by setting the splash option to the location of the image. However, providing an image is not mandatory to set up a Flowplayer splash screen; in fact there is no CSS or image requirement for the splash setup. Usually you want at least a background-color to discern the player from its surroundings.

Here is how it works:

  • Video tag based installations: Upon recognition of the "is-splash" class name or the splash option the VIDEO tag is temporarily removed from the container element on page load.
  • When the splash screen is clicked the VIDEO or an OBJECT tag, depending on the engine picked, is placed inside the player container and the "is-splash" CSS class name is removed.
  • Unloading does the opposite: the VIDEO or OBJECT tag is removed and the "is-splash" class is re-added.
  • The player can be made to go back to splash state by hitting the q key or by calling the unload API method.
  • Adding the "is-closeable" state class displays an unload button.

Splash screens are used heavily in our demo area. They are one of the main reasons why people use Flowplayer.

The cleanest and fastest way to implement a splash setup is to use a pure JavaScript installation, and, if desired, to set the splash image via CSS.

Splash contradicts autoplay and takes precendence if you configure both.

[View standalone page]({{ config.flowplayer7.standalonedemos }}/basics/splash)

Autoplay

You can set videos to autoplay with the autoplay: true (Javascript setup) resp. data-autoplay="true" (videotag setup).

Since autoplay is often not desired by the viewer, browser manufacturers are taking steps to disallow autoplay or restrict the outcome; current Chrome and Safari for example do not allow autoplay with sound. In such a situation Flowplayer will default to muted autoplay, the viewer needs to set the volume by user gesture / using the controlar or devcei volume control.

You can disable muted autoplay by setting mutedAutoplay: false in the configuration.

You cannot use autoplay in a splash setup.

Configuration

The player supports various configuration options. For example:

<script>
$(".myplayer").flowplayer({

   // option 1
   ratio: 3/4,

   // option 2, here: rtmp netConenctionUrl
   rtmp: 'rtmp://some.rtmpserver.com/appath/',

  // option 3, note: no comma fter last option!
  share: false
});
</script>

Configuration happens on 3 levels:

  1. player level: options which affect the player
  2. clip level: options which set or affect the video
  3. source level: options which set or affect source variants of the clip

JavaScript schema:

var conf = {
    // player level
    clip: {
        // clip level
        sources: [
            // source level
            ...
        ]
    }
}

HTML schema:

<div id="playerContainer" data-[option]="value" ...> <!-- player level -->
   <video>                                           <!-- clip level   -->
      <source ...>                                   <!-- source level -->
      ...
   </video>
</div>

The HTML schema is less clear cut and sometimes less flexible at the clip and source level. We recommend to use the JavaScript installation method for complex setups.

The following tables show all options as they are declared in a global localor pureJavaScript configuration in JSON syntax.

The provided configuration can also be just a string, in which case it is interpreted as the swf core option.

Options marked in red are advanced options. Only set them when you know what you are doing and aware of potential side-effects or drawbacks.

Player options

Here is a list of all core configuration options at player level.

For video tag based installations every player option can alternatively be specified in HTML configuration syntax as custom data-attribute of the container element - except for clip which is set via the VIDEO and SOURCE tags and rtmp if specified as Object. Camel cased option names like adaptiveRatio must be written as compound lower cased attributes: data-adaptive-ratio.

Clip specific options, like title must be set on the clip level.

    • option
    • description
    • adaptiveRatio boolean
    • Whether the player's ratio adapts vertically to the video's aspect ratio. Do not apply in conjunction with the aspectRatio or ratio options. Default: false
    • aspectRatio string
    • A string specifying the aspect ratio of the player, width to height. Usually should be set to the value as the video's aspect ratio. Both colon : and slash / separators are allowed.
      Refer to the section on player size for further details.
      See also the ratio option. Default: 16:9
    • autoplay boolean
    • If true, playback will start automatically once the player is loaded.
      Contradicts a splash setup by definition and must not be used with it.
      Has no effect on mobile devices which do not allow automatic playback. Default: false
    • bgcolor string
    • The background color (hex value) of theplayer canvas in Flash mode unless the wmode option is not set to "transparent". If a CSS background-color rule is specified for the container, its calculated full hex value becomes the default, so you usually want to configure this via CSS. Default: '#333333'
    • chromecast boolean since 7.0.3
    • Whether Chromecast device detection and playback is is enabled. Set to false if you do not want the chromecast sender script to be loaded. Default: true
    • clickToUnMute boolean since 7.2.5
    • configure whether player will immediately unmute on tap (useful for custom "activate audio" buttons). Default: true
    • debug boolean
    • Whether to show debug messages in the browser console. Causes errors if window.console is not available. Default: false
    • disabled boolean
    • Whether playback should be forced by disabling the UI. Seeking, pausing etc. is impossible. API still works. Typically used in ads. Default: false
    • dvr boolean
    • Enable dvr for live streams so viewers can seek back in a stream recording. Default: false. Can also be enabled with the is-dvr state css class.
    • errors array
    • An array of error messages. The default list can be found in the API documentation.
    • fullscreen boolean
    • Whether fullscreen is enabled. Defaults to false when the player is viewed in anIFRAME. Must therefore be set to true explicitly to enable players in an IFRAME to go fullscreen. Default: true
    • hlsQualities boolean or array
    • bool: If false, disables manual HLS quality selection. Shorthand for an array comprising all level index numbers.
      Can be set as data-hls-qualities HTML attribute. Default: true
      array: An array of HLS levels to offer for manual HLS quality selection. The levels are specified as index numbers from 0 (lowest) to highest. Level -1 for adaptive bitrate switching must be listed first. Example:
      [-1, 1, 6]
      Can be set as data-hls-qualities HTML attribute.
      Levels may also be specified with a custom selector menu label:
      [{level: -1, label: "ABR"},<br>{level: 1, label: "SD"}, {level: 6, label: "HD"}]
      In this case hlsQualities cannot be set as HTML data attribute.
    • live boolean
    • Whether the player is set up for livestreaming.
      CSS alternative: the is-livestate class.
      See also the corresponding clip option. Default: false
    • mouseoutTimeout integer
    • How long the full controlbar stays visible in fullscreen after a mouse movement (in milliseconds).
      Has no effect in conjunction with the fixed-controls and no-toggle skin modifier classes. Default: 5000
    • muted boolean
    • Whether the player should start in muted state. Default: false
    • mutedAutoplay boolean since 7.2.2
    • Boolean to disable muted autoplay feature in those browsers which do not allow autoplay with sound. Default: true
    • native_fullscreen boolean
    • Whether to use native fullscreen on iOS instead of the full browser window. The screen will be bigger but native video controls will be in use instead of customizable Flowplayer controls.
      Setting this to true is required to enable a player in an IFRAME to go fullscreen on iOS. Default: false
    • poster string or boolean
    • URL or path to poster image. Enables a poster setup.
      Caveat: Setting the poster via this option is slow, because the poster image can only be shown once the player is loaded.
      If a CSS poster setup is detected on boot, theAPI sets this option to true.
    • ratio integer
    • A fraction or decimal number representing the height of the player in proportion to its width. Refer to the section on player size for details.
      See also the aspectRatio option.
      Set this to false if you want to set the ratio via CSS only or set the player dimensions to a fixed size via CSS. Default: 9/16
    • speeds array
    • The available speed levels that are used with SHIFT + arrowkeys or by the speed() APImethod.
      To offer a user interface for playrate changes load the speed menu plugin.
      The values in the given array are the factors by which normal playback speed is multiplied. Configured values will be rounded to 2 decimals.
      Values less than 1.0: slow motion.
      Values greater than 1.0: fast forward.
      Not supported by the Flash engine, older browsers and many mobile devices. Default: [0.25, 0.5,<br>1.0, 1.5, 2.0]
    • seekStep boolean or integer since 7.2.2
    • Configure the arrow key seek interval
      set an integer for the seconds to be used for each seek step. Default: false
    • splash boolean or string
    • bool: As boolean: enables a splash setup. If a splash image is desired, it can be set as CSS background-image for the container element.
      CSS alternative: the is-splash state class. Default: false
      As string: The location of the splash image. Enables a splash setup.
    • storage object 7.2.2
    • To disable the use of localStorage (for volume settings) just set it to empty with flowplayer.conf.storage = {}
    • swf string
    • Flash only. Location of the Flash file. URL or path. Defaults to {{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/flowplayer.swf for the free player.
    • swfHls string or boolean
    • Flash only. Location of the Flash HLS plugin. URL or path. Defaults to {{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/flowplayerhls.swf for the free player. Setting this to false will prevent playback of HLS by the Flash engine altogether.
    • volume integer
    • The initial volume level. Default: 1.0
    • wmode string
    • The wmode value to be used by the Flash engine. Refer to the Adobe Flash documentation for more info.
      Warning: Setting this to "direct" or "window" will cause problems in some browsers, namely Internet Explorer and Firefox on Windows. Default: opaque

Extension and plugin options

The following options are undefined by default, but are supported by player extensions or additionally loaded plugins. Follow the link in the third column for details. The rightmost column indicates whether the option can also be set as data attribute in a HTML configuration. Some of the options accept a nested configuration object as value, in which case only the top-level option is listed here.

Commercial configuration

The commercial version allows you to get rid of the Flowplayer logo and optionally use your own. By default this will be displayed in the bottom/left corner of the player in the shared players. When a user clicks the logo [s]he will be redirected to the originating page or the configured link.

The license key is tied to the domain name shown in the browser's location bar

  • in the case of IFRAMEs when the frame is viewed in its own window, i.e., the IFRAME source domain.

Commercial prerequisites

Make sure to deploy and load the commercial release available at your Flowplayer account, or simply load the commercial API script from {{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/commercial/flowplayer.min.js .

The following assets must be commercial for license validation:

  • the API script: flowplayer.min.js
  • the Flash swf file: flowplayer.swf - if not loaded from our CDN (the default) the swf option or the data-swf container attribute must be set
  • the Flash HLS swf file: flowplayerhls.swf - if not loaded from our CDN (the default) the swfHls option or the data-swf-hls container attribute must be set

Commercial options

Here are the player options for the commercial version. All commercial options belong into the top level.

    • key string
    • A valid license key removes the Flowplayer branding from the player. The value can be a comma separated string of keys to support multiple domains. For example:
      '$688345122773207, $334773811075656'
    • logo string or object
    • string: Location of your logo. URL or path.
      Clicking on the logo will redirect the viewer to the originating page.
      Its appearance can be further customized via CSS.
      Object: this option allows to redirect the viewer to a location of your choice.
      Its appearance can be further customized via CSS.
    • swf
    • Flash only. Location of the Flash file. URL or path. Defaults to
      {{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/commercial/flowplayer.swf
    • swfHls
    • Flash only. Location of the Flash HLS plugin. URL or path. Defaults to
      {{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/commercial/flowplayerhls.swf.
      Setting this to false will prevent playback of HLS by the Flash engine altogether

As with other player options HTML configuration via container data-attributes is only applicable to VIDEO tag based installations. In Javascritp setups you must configure the commercial options in the JS config object on the player level.

Here is a [minimal commercial setup]({{ config.flowplayer7.standalonedemos }}/commercial.html). Take a look at its source code and you can see how the key is provided. You create the key on your account page after purchase by entering the domain name you wish to license into the "Add domain" field.

Logo options

If configured as Object the logo option accepts the following parameters:

    • parameter
    • description
    • href string
    • URL. When clicking on the logo, the viewer will be redirected to this location. Default: originating page.
    • src string
    • Location of your logo. URL or path. Setting this is mandatory.

Example, applies globally to all players on the page:

flowplayer.conf.logo = {
    href: "https://example.com/home.html",
    src:  "//example.com/images/logo.png"
};

Custom context menu

The context menu which shows up on right-click on the player area can be customized in licensed players. Refer to the skinning documentation for how to set it up.

By default no context menu is present in the commercial player.

Clip options

The clip object may not be empty. As any HTML5 player, Flowplayer requires a video to run. Therefore specifying a sources parameter is mandatory for a valid clip configuration.

In a VIDEO tag based installation the sources are already present as SOURCE tags. Options which are not generic VIDEO tag attributes can be set as data-attributes of the VIDEO tag if their value is not an object.

    • option
    • htmlsyntax
    • description
    • hlsQualities boolean
    • ' data-hls-qualities'
    • Overrides the hlsQualities player configuration for this clip, turning manual HLS level selection on or off. default: true
    • loop boolean
    • 'loop`
    • Whether this clip should play again automatically on finish.
      For loop playback of playlists use the loop option at player level provided by the playlist extension. default: false
    • live boolean
    • data-live
    • Whether this clip is a livestream.
      Overrides the liveplayer option. default: false
    • rtmp string or object
    • data-rtmp (string only)
    • string: Flash (RTMP) only. Address of the Flash RTMP server. See also:server side video handling.
      Overrides the rtmp player option.
      object: Flash (RTMP) only. When specified in JavaScript object notation: the rtmp object.
      Overrides the rtmp player option.
      Cannot be set in HTML syntax.
    • sources array
    • none (in video tag)
    • A list of video formats. Refer to source options for parameters and detailed descriptions.
      Setting this property is mandatory.
    • title string
    • data-title
    • Set a title for this clip. Displayed in a top bar when hovering over the player.

Extension and plugin clip options

These options are undefined by default but are supported by the referenced extensions or plugins, especially for use in playlists.

|

Source options

    • option
    • html syntax
    • description
    • engine optional string
    • data-engine
    • The engine the player must use for this source, no other engine will be tested. If the source cannot be played by the specified engine or the engine is not supported by the browser, the next source will be tried.
      Makes picking order completely customizeable.
    • type mandatory string
    • type
    • The video type of this source.
    • src mandatory string
    • src
    • The location of this source. Path or URL.

Source options cannot be set in a VIDEO tag based playlist installation.

Video tag attributes

In VIDEO tag based installations you can apply the following standard html5 VIDEO tag attributes:

    • attribute
    • level
    • description
    • autoplay boolean
    • player
    • If set, playback will start automatically once the player is loaded -
      Flowplayer-hosted video Self-hosted video 
      <div data-player-id="cdcc4202-ef0b-4e03-a43a-d1fcf6d83157">
  <script src="//cdn.flowplayer.com/players/ffdf2c44-aa29-4df8-a270-3a199a1b119e/native/flowplayer.async.js">
    {
      "src": "f576651c-4cc6-4664-84fa-bb3b35ef1aba"
    }
  </script>
</div>
      <div data-player-id="cdcc4202-ef0b-4e03-a43a-d1fcf6d83157">
  <script src="//cdn.flowplayer.com/players/ffdf2c44-aa29-4df8-a270-3a199a1b119e/native/flowplayer.async.js">
    {
      "src": "//edge.flowplayer.org/bauhaus.m3u8"
    }
  </script>
</div>
      ({{ config.flowplayer7.standalonedemos }}/basics/autoplay). Same effect as the player option of the same name.
      Has no effect on mobile devices which do not allow automatic playback.
    • loop boolean
    • clip
    • If set, the video plays again automatically on finish. Corresponds to the JavaScriptclip option of the same name.
      Cannot be used with playlists.

Do not use any other standard VIDEO tag attributes as they might cause conflicting or unpredictable behaviour. We recommend to use the player / clip configuration options instead.

Global JavaScript configuration

Here we provide global settings for all players on the page:

<script src="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/flowplayer.min.js"></script>

<!-- global options -->
<script>
flowplayer.conf = {
   ratio: 5/12,
   splash: true,
   analytics: "UA-27182341-1"
};
</script>

The flowplayer.conf object sets the global configuration for Flowplayer. You should customize its properties right after Flowplayer has been included in the HEAD section of your page (with script src). Another common place to put site-wide Flowplayer defaults is in an external javascript file which contains the website logic and is loaded after the basic assets. This is a practical way to specify global settings such as the Google Analytics ID.

Each player will have these as defaults but they can be overridden for individual players.

You can set individual options as follows:

<script src="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/flowplayer.min.js"></script>

<script>
flowplayer.conf.ratio = 5/12;
</script>

Remember to set these after the flowplayer.conf = {...} setting if you have one because setting the entire conf object will discard any individual property settings. Or use the flowplayer.set function which allows to extend an existing global configuration.

Local JavaScript configuration

The scope of both the pure JavaScript installation and manual installation methods is local. Player specific configuration is passed as argument to the flowplayer() function.

Here is an example how to configure the ratio option for all players which are manually installed into containers of class "player".

// install player manually after DOM is ready
$(function() {
    // install into all elements with class="player"
    $(".player").flowplayer({
        // reverse fraction of video aspect ratio
        // video dimensions: 470px / 250px
        ratio: 25/47,
        rtmp: "rtmp://s3b78u0kbtx79q.cloudfront.net/cfx/st",
        embed: {
            // embed with minimalist skin
            skin: "{{ config.flowplayer7.releases }}/skin/minimalist.css"
        }
    });
});

The configuration is normally passed as in JavaScript Object Notation as argument to the flowplayer() call. If the argument is a simple string it is treated as the location of the flowplayer swf file.

Local configuration overrides global configuration.

[View standalone page]({{ config.flowplayer7.standalonedemos }}/basics/manual)

HTML configuration

Configuration options for specific players can also be set directly in HTML syntax:

<div data-ratio="0.5319"
     class="flowplayer no-volume no-mute functional">
   <video autoplay>
      <source type="video/webm"
              src="//edge.flowplayer.org/black/470x250.webm">
      <source type="video/mp4"
              src="//edge.flowplayer.org/black/470x250.mp4">
      </video>
</div>

The HTML syntax allows to customize specific players even when they are automatically installed.

HTML configuration overrides global configuration and local JavaScript configuration.

[View standalone page]({{ config.flowplayer7.standalonedemos }}/basics/autoplay)

Order of precedence

The above override rules result in this order of precedence regarding the possibilities to configure the player:

  1. HTML configuration
  2. local JavaScript configuration
  3. global JavaScript configuration

Configuration summary

Here is an overwiew of the ways to configure Flowplayer mapped to their respective coding, level, and installation method.

● = mandatory   + = accepted   − = not possible

syntax level automatic manual pure
flowplayer.conf JavaScript global +
− clip		 +
− clip		 +
DIV data-attr HTML player +
− clip		 +
− clip		 −
$(sel).flowplayer({
conf
})		 jQuery player − +
− clip		 −
flowplayer(DIV, {
conf
})		 JavaScript player − − ● clip
VIDEO HTML clip ● SOURCE ● SOURCE −
VIDEO attr HTML mixed + + −
clip JavaScript clip − − ● sources
SOURCE HTML source ● ● −
SOURCE attr HTML source ● type
● src		 ● type
● src		 −
sources[index] JavaScript source − − ● type
● src

sel = jQuery selectorDIV = container element

attr = element attribute conf = JSONObject Notation] option: value mapping index = array index

Keyboard

Flowplayer not only offers a graphical interface. It can also be controled via the keyboard. Here is an overview of the available keyboard shortcuts:

Key Action
space play/pause
q stop (unload in a splash setup)
f fullscreen
shift + left arrow slower (see the speeds option)
shift + right arrow faster (see the speeds option)
down arrow volume down
up arrow volume up
m mute
left arrow seek backward
right arrow seek forward
. seek to previous position
number seek to numbertimes 10 percent of duration

Keyboard shortcuts can be turned off by setting the keyboard configuration option to false.

Iframe

For players shown in an IFRAME fullscreen is disabled by default. It would not work in browsers without native fullscreen support, and some browsers forbid fullscreen from IFRAMEs, notably from a remote orgin, without offering a reliable detection mechanism.

If you are in control of the IFRAME's source and the page where the IFRAME is shown you can allow fullscreen by excplicitly setting the fullscreen configuration option to true on the originating page and specifying the allowfullscreen attribute for the IFRAME:

<iframe src="//example.com/iframe-src.html"
        width="800" height="500"
        allowfullscreen="true"></iframe>

To allow fullscreen playback from within an IFRAME on iOS, additionally the native_fullscreen option must be set to true.

Check out [the iframe demo]({{ config.flowplayer7.demos }}/basics/iframe.html).

Engines

Flowplayer is shipped with two engines: html5 and flash.

Additional engines can be added as plugins for advanced purposes like [DASH playback]({{ config.flowplayer7.demos }}/plugins/dash.html).

html5 engine

The primary engine is the html5 engine, unless you configured a different engine for a specific source explicitly.

HTML5 video

Generic HTML5 video support introduced by major desktop browser versions:

browser ogg mp4 webm hls
Internet Explorer - 9.0 - 13.0 Edge
Firefox 3.5 35.0 4.0 -
Chrome 3.0 3.0 6.0 -
Safari - 3.1 - 6.0
Opera 10.5 15.0 10.6 -

Native HLS playback support in Internet Explorer Edge is very buggy, using the hlsjs plugin is strongly recommended.

Safari on Windows is capable to play HTML5 video if QuickTime is installed.

HTML5 video format support on mobiles:

  • MP4: all devices
  • HLS: iOS and most modern other devices

Check out [this dynamic table]({{ config.flowplayer7.demos }}/videotest/canplay.html) which shows what formats your current browser can play.

Flash engine

The Flash engine is chosen to play a source if

  1. the tested video source cannot be played as HTML5 video by the browser and
  2. the tested video type can be played by the Flash engine and
  3. the engine source option for this source is not set to a value other than "flash" and
  4. the Flash plugin is enabled in the browser

or if

  1. the engine source option for this source is set to "flash" and
  2. the Flash plugin is enabled in the browser

The Flowplayer Flash component requires Flash version 9.0.0. Flash supports playback of the MP4 format since version 9.0.115. Consider it safe to neglect offering a FLV source as fallback for ancient Flash.

The Flash engine supports playback of the following video formats:

Flash HLS

The hlsjs plugin enables HLS playback in modern browsers and devices without requiring Flash. Compared to Flash HLS it features better playback performance and is more resource friendly. - Flash HLS will still be used in legacy browsers.

Flowplayer supports HLS playback with its Flash engine. Adaptive Bit Rate (ABR) switching is available not only in browsers which can play HLS in HTML5 video, but also in all other browsers, noteably most desktop browsers.

For livestreams this means that the same range of clients can be reached with just one source of type application/x-mpegurl as with a combination of HLS for HTML5 video and RTMP for Flash (where RTMP does not offer the benefits of ABR).

Advantages of Flash HLS over RTMP:

  • ABR is available
  • no additonal Flash source required
  • no RTMP server required to offer random seeking via the Flash engine

Flash HLS does not support playlists (#EXT-X-VERSION:4).

Rare scenarios where RTMP delivery for Flash might be preferrable:

  • livestreams where synchronicity with the live event is of crucial importance; livestream delivery often is done over RTMP first, which then has to be transformed to HLS causing a slight delay
  • very fine seeking granularity is of crucial importance to the setup - reason: Flash HLS seeks only to keyframe positions by default and setting flashls seekmode: "ACCURATE" doesn't yield the desired experience. — Even in this scenario RTMP should only be 3rd choice after HLS via the hlsjs plugin and native playback.

Flash video (RTMP)

Flowplayer supports a special video/flash source type to target video specifically for Flash. The type is mostly and best used to offer an RTMP stream as Flash source if a HLS stream is not available:

<!-- flowplayer with RTMP configuration option -->
<div class="flowplayer" data-rtmp="rtmp://myrtmpserver.com">

  <video>
    <!-- consumed by the html5 engine -->
    <source type="video/webm"  src="//mydomain.com/video.webm">
    <source type="video/mp4"   src="//mydomain.com/video.mp4">

    <!-- consumed by the flash engine -->
    <source type="video/flash" src="mp4:path/to/video.mp4">
  </video>

</div>

RTMP delivery in Flash allows seeking to unbuffered positions in the timeline.

  • The rtmp option for the server address - also called 'net connection url' - must be set. Please consult the documentation of your server for its exact value.
  • The src must be the path on the server, not a full URL. For video on demand it is often prefixed with mp4: for MP4 videos. Again the server documentation is your friend. If your site is using https, your stream source needs to be rtmps (not rtmp).

Specifying a video/flash source delivered via HTTP for progressive download is rarely useful:

  • If the video is in MP4 format, the source of type video/mp4 will be be automatically chosen as Flash fallback format if no HLS or RTMP source is available.
  • The FLV format has a lower quality/bitrate ratio compared to MP4 and cannot be played in HTML5 video. Since Flash support will be deprecated by all major browsers soon, usage is strongly discouraged.

Server side

Mime types

Make sure that all the files are available on the server and that the server transmits them with the correct Content-Type. Depending on your server you might have to extend the .htaccess or mime.types files (Apache), use the IIS manager (Internet Information Server) or set the header via Metadata (Amazon S3). Example .htaccess file:

AddType video/mp4             .mp4
AddType video/webm            .webm
AddType video/ogg             .ogv
AddType application/x-mpegurl .m3u8
AddType application/dash+xml .mpd

## hls transport stream segments:
AddType video/mp2t            .ts
## subtitle text tracks:
AddType text/vtt              .vtt

The first 4 mime types above are also the ones most commonly used source types.

For nginx, the MIME type is defined in nginx/conf/mime.types In lighthttps, use the config file

HTTPS

When loading the Flowplayer assets make sure to avoid mixed content if your page is accessed via HTTPS.

The easiest and most flexible way to achieve this is by omitting the protocol:

<!-- omit protocol when loading assets -->
<link rel="stylesheet" src="//example.com/assets/skin/skin.css">
<!-- ... -->
<script src="//example.com/assets/flowplayer.min.js"></script>

The same applies to loading the video sources:

// omit protocol when loading sources
sources: [
    { type: "application/x-mpegurl",
      src:  "//example.com/video.m3u8" },
    { type: "video/mp4",
      src:  "//example.com/video.mp4" }
]

or:

<!-- omit protocol when loading sources -->
<source type="application/x-mpegurl" src="//example.com/video.m3u8">
<source type="video/mp4"             src="//example.com/video.mp4">

This obviously requires that example.com is accessible both via HTTPS and HTTP. Otherwise use the same protocol as the page is served with or a local path — but also read the notes on sharing.

Adobe Flash does not allow to use https urls for the swf files on a httpsite, so make sure you load them with the correct protocol. If your site is using https and you still need the rtmp protocol, your stream source needs to be rtmps (not rtmp) as well.

Cross domain

To make HLS work in Flash Flowplayer's Flash engine must have explicit permission to access the transport streams. The deployment of a cross domain policy file at the root of the domain from which the TS files are served is obligatory. It must allow requests from the location of flowplayerhls.swf (see the swfHls configuration option).

Simple example of a crossdomain.xml file giving full access to requests from anywhere:

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
  <allow-access-from domain="*" />
</cross-domain-policy>

For a very loose policy which also allows retrieving assets via https to a http site it would look like this:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
  <allow-access-from domain="*" secure="false"/>
  <site-control permitted-cross-domain-policies="all"/>
</cross-domain-policy>

Refer to the Adobe Flash documentation for a full specification.

With Flash HLS it is especially important to load the Flowplayer assets (flowplayerhls.swf) and the media via the same protocol.

Redirecting

Avoid redirects in the video source URLs. Some browsers may not be able to handle them in HTML5 video.

Flash HLS does not allow for 302 redirecting of relative paths in the master variant HLS playlist.

Random seeking

Audiences expect to be able to skip back and forth in a video without inconvenience. They expect a "streamed" video. With HTML5 video the server side requirements are now lowered dramatically for offering this feature.

  1. HLS is genuinely made to order for this purpose. As Flowplayer's Flash engine plays HLS out of the box, most scenarios are covered, adaptive bitrate streaming included. It is also the most cost effective format.
  2. Almost all modern HTTP servers support byte-range requests. Thus they fulfill the only requirement to "stream" HTML5 video on demand as it can be viewed in partial downloads.
  3. Flash is only capable of progressive download over HTTP. If you cannot offer a HLS stream, consider serving from an RTMP server for Flash delivery. You do not necessarily have to run your own RTMP server for this purpose. Most content delivery networks (CDNs) offer this alternative and other advantages, see below.
  4. Note on MP4 metadata: make sure the MOOV atom is at the beginning of the file, or some browsers will not start playback before downlaoding the full file.

CDN

In the interest of your audience, and to lower your worries regarding maintenance, reliability, and delivery speed, consider serving your videos from a content delivery network. The videos will be served from edge locations near your viewers, which can result in a noticeable speed gain, resulting in improved playback quality.

Advanced Flash configuration

The options listed in the following sections should only be applied if needed, and with knowledge regarding their effects.

flashls

For finer control of Flash HLS the following options are available as properties of the flashls configuration object on the clip level:

option default description
capleveltostage false Whether levels are limited the stage (screen) dimensions.
false: levels will not be limited. All available levels could be used taking only bandwidth into consideration.
true: level width and height (defined in m3u8 playlist) will be compared with the player width and height. Max level will be set depending on the maxlevelcappingmode option.
debug false If true Flash HLS debug messages are shown in the JavaScript console.
debug2 false If true Flash HLS verbose debug messages are shown in the JavaScript console.
fragmentloadmaxretry 4 Maximum number of fragment load retries after I/O error.
Any I/O error will trigger retries every 1s, 2s, 4s, 8s (exponential, capped at 64s).
-1 means infinite retries.
0 means no retry, a "Video not found" error will be raised instantly.
fragmentloadskipaftermaxretry true Controls behaviour in case fragment load still fails after max retry timeout.
true: fragment will be skipped and next one will be loaded.
false: "Video file not found" error will be raised.
keyloadmaxretry -1 Maximum number of AES encryption key load retries after I/O error.
Any I/O error will trigger retries every 1s, 2s, 4s, 8s (exponential, capped at 64s).
-1 means infinite retries.
0 means no retry, an error will be raised instantly.
live_flushurlcache false If set to true a live playlist will be flushed from URL cache before reloading. Use only for testing!
lowbufferlength 3 Low buffer threshold in seconds. When crossing down this threshold, the player goes into loading state. Playback will still continue.
manifestloadmaxretry -1 Maximum number of manifest (m3u8 playlist) load retries after I/O error.
If any I/O error is encountered during initial manifest load, a "Video not found" error will be raised immediately. After the initial load, any I/O error will trigger retries every 1s, 2s, 4s, 8s (exponential, capped at 64s).
-1 means infinite retries.
0 means no retry, an error will be raised instantly.
maxbackbufferlength 30 Maximum back buffer length in seconds. 0 means infinite back buffering. The back buffer is seekable without redownloading segments.
maxbufferlength 300 Maximum buffer length in seconds. 0 means infinite buffering.
maxlevelcappingmode "downscale" Defines the max level capping mode:
"downscale": max capped level should be the one with the dimensions equal or greater than the screen dimensions.
"upscale": max capped level should be the one with the dimensions equal or lower than the screen dimensions.
minbufferlength -1 Minimum buffer length in seconds that needs to be reached before playback can start after seeking, or restart in case of empty buffer.
By default -1 some heuristics based on past metrics are used to define an accurate value that should prevent buffer stalling.
seekfromlevel -1 -1: automatic seek level selection, keep level before seek.
From 0 to 1: indicates the "normalized" preferred bit rate:
0: lowest (non-audio) bit rate is used.
1: highest bit rate is used.
0.5: nearest to middle bitrate will be selected and used first.
startfrombitrate -1 If greater than 0, specifies the preferred bitrate to start with.
If -1 (default), and startfromlevel is not specified, automatic start level selection will be used.
Otherwise overrides startfromlevel.
startfromlevel -1 -1: automatic start level selection, playback will start from level matching download bandwidth (determined from download of first segment).
-2: playback will start from the first level appearing in the variant manifest (regardless of its bit rate) - similar to native HLS starting behaviour.
From 0 to 1: indicates the "normalized" preferred bit rate:
0: lowest (non-audio) bit rate is used.
1: highest bit rate is used.
0.5: nearest to middle bitrate will be selected and used first.
seekmode "KEYFRAME" "KEYFRAME": seek to last key frame before requested position.
"ACCURATE": seek to exact position. Caveat: might cause jumping of video on resume after seek.
usehardwarevideodecoder true Whether hardware video decoding is enbabled. Only set to false to check for potential hardware decoding issues.

The flashls configuration does not influence the behaviour of native HTML5 video HLS playback.

RTMP options

To fine tune RTMP server settings the rtmp option can be specfied in JavaScript object notation. The rtmp object accepts the following properties:

option default description
bufferTime 3 Specifies how long to buffer messages before starting to display the stream. See Adobe's docs for NetStream.bufferTime for more info.
In a live configuration the default value is 0 as recommended by Adobe; changing the value might cause problems with resuming livestreams.
proxy best Determines which fallback methods are tried if an initial connection attempt to the RTMP server fails. See the Adobe documentation for details.
rtmpt true Try an RTMP connection through HTTP tunneling. The one that connects first will be used in playback. Set this to false if you want to disable RTMPT.
subscribe false Some livestreams require this to be set to true. Check with your stream provider or CDN whether their server sends the FCSubscribe netConnection event.
url Address of the Flash RTMP server.
Mandatory, corresponds to rtmp given as string.

Both forms of the rtmp option can be given at player and clip level.

Migration from Version 6

Manual HLS quality selection is now available out of the box via the builtin HD menu.

Discover the revamped skinning and sharing possibilies.

Migration from Version 5

A lot of effort went into keeping the player compatible with existing setups. If you still encounter problems, please check also the migration notes in the skinning and api doc sections and turn to our forum for support. Installation of a playlist of sources into an empty container element has grown up to become a first class citizen in the form of the API friendly JavaScript installation method in Flowplayer 6 with an extensible clip object. We recommend to embrace the more flexible full syntax which will give you even more control over each clip and its sources.

Flowplayer 6 introduces a simpler source picking order: Every source will be tried in the given order by all engines available. In the usual recommended setups this will not cause any difference in behaviour.

In the same vein, the engine option has moved from the player level to the source level to allow for complete fine-grained control of video source preferences.

Users of advanced RTMP options like bufferTime, rtmpt: The options will currently still work when set at player level directly. We recommend to start upgrading to the new rtmp configuration object which is available both at player and clip level and thereby offers increased flexibility.

Results