Table of contents

Migrating a Flowplayer 7 setup to Native

This guide aims to explain the differences and similarities of the old Flowplayer 7 and our current offering Flowplayer Native. As the native (hence the player name) html5 APIs evolved, we were able to remove lots of custom code and use those APIs instead, resulting in a much smaller player size and far broader compatibility with current devices and browsers.

The guide is meant as a first stop for orientation, we highly recommend reading the whole player developer documentation to exploit the full potential of Flowplayer Native.

This guide is work in progress and we might add bits and pieces while we enhance thje main documentation as well.

Release numbers and channels

Flowplayer Native is continuously developed and updated and there is no more need (though you can still do it) to use a specific version url or to download and install packages. You just reference the stable (or for testing canary) release channel and are set. See the release channel info for details. Plugins are released in the same semver path as the core release, even though internal numbers might differ.

Embedding

Flowplayer Native does not offer a plain <video> tag embed, instead you can use one of two methods:

The manual Javascript setup with jQuery is not supported anymore and there is no need to load the library (of course you could still use it for custom purposes as demoed here.

To protect from unwanted usage, you can domain-lock [tokens](/player/embedding#configure-the-player-with-your and async players.

For details on the async players with platform-hosted or self-hosted content, follow the embedding documentation.

Configuration

The configuration structure syntax is similar to Flowplayer 7 but offers different options which are explained in the player documentation. Plugins have their own config sets which live under the respective plugin namespace in the configuration root. Please refer to the plugin documentation pages for the available options. Please note the inline configuration JSON format.

[to be done: list of deprecated options, new options]

Video sources

Video sources can be configured in the src: object, which replaces the clip: configuration object of FP7. Please see the video source documentation for details.

Flowplayer supports playback of the following video source types:

Flash video is no longer supported, hence rtmp and flvcannot be used either.

(*) mediaid is a special src: option where you can use the Flowplayer platform media ids (for video/audio clips, livestreams and playlists) using the platform integration plugin (optionally with a hosted player configuration id), the video source urls and metadata will be retrieved from our platform and automatically merged into the configuration.

(**) MP4 refers to MPEG-4 part 10 video (h264) in an MP4 container. MPEG-4 part 2 (h263) is not supported in many browsers. WebM (VP8/VP9) is not supported in all browsers. Please check the Caniuse site for a support matrix.

Features moved to plugins

Airplay and Chromecast features are now separate plugins: Airplay and Chromecast.

Cuepoints is now a separate plugin: Cuepoints.

The Playlist feature is now a separate plugin which is initialized in a custom way. To show external controls, you can define a container name of your choice instead of the .fp-playlist class. See the playlist plugin documentation for details.

Keyboard control is now a separate plugin: Keyboard. Please check the Accessibility guide as well.

The Share feature is now a separate plugin: Share .

Subtitles are now handled by separate plugins: Subtitles and HTML Subtitles. The first one uses the native browser subtitle implementation while subtitles-html is stylable.

Audio selection and manual quality selection are now separate plugins, please check the Asel and Qsel docs.

Skinning

The skinning options and modifier classes were completely revamped, check the skinning documentation for the details.

Translations

The player text strings are translatable. Please read the translation guide .

Plugins

Below is a map of old Flowplayer 7 vs. current Flowplayer Native plugins. This covers the plugins which were available for FP7, please note we added several new feature plugins like DRM, Frame Accurate Seeking, Float On Scroll, Gemius Analytics, Comscore Analytics, Message to the ever-growing list.

    • FP7 plugin
    • Native plugin
    • Details
    • Adsense
    • deprecated, replaced by advertising plugin
    • The Google Ads revenue sharing offer and plugin are deprecated. To show ads you'll need a contract with an advertising network (or a reseller), a player subscription with ads feature (Pro/Enterprise), and the advertising plugin.
    • Background
    • deprecated
    • You can use simple CSS to put a video in the background, see this background demo.
    • hlsjs
    • HLS plugin
    • HLS support is integrated into the async cloud player, for manual JS embeds please follow the docs.
    • overlay
    • overlay demo
    • There is currently no plugin but you can use the API to create an overlay.
    • VOD quality selector
    • deprecated
    • We no longer offer MP4/WebM quality selection; please use HLS or DASH and the qsel plugin.
    • VAST
    • deprecated
    • To show ads you'll need a contract with an advertising network (or a reseller),a player subscription with ads feature (Pro/Enterprise) and the advertising plugin.

API

The Flowplayer Native API is very different from the FP7 API as it mainly extends the standard Element, HTMLMediaElement and HTMLVideoElement object APIs with it's own set of properties and methods. Please read the API docs for details; as you can see the official standards are used where possible.

API access

[available soon]

    • FP 7 property
    • FP Native property or
    • html5 medialement property
    • comment
    • conf
    • opts
    • n/a
    • the initial configuration object
    • currentSpeed
    • playbackRate
    • playbackRate
    • the current playback speed level: 1 = normal speed less than 1 = slow motion greater than 1 = fast forward Default: 1
    • disabled
    • setOpts({disabled: true|false})
    • disabled
    • true while the player is disabled Default: false
    • dvr
    • setOpts({dvr: true|false})
    • n/a
    • true while the current video is a live DVR stream Default: false
    • engine
    • n/a
    • n/a
    • Flash engine has been deprecated, so htlm5 is always used
    • error
    • error
    • error
    • true once an error has occured Default: undefined
    • finished
    • ended
    • ended
    • true while the player is stopped at the end of the video Default: false
    • forcedSplash
    • n/a (all video are splash by default where it makes sense using preload=none)
    • n/a
    • whether a splash setup was enforced for this player, true on mobile devices Default: false
    • live
    • player.opt("live")
    • n/a
    • true while the current video is a livestream, also live DVR Default: false
    • loading
    • readyState
    • readyState
    • true while the player is being loaded Default: false
    • muted
    • muted
    • muted
    • true while the player is muted Default: false
    • paused
    • paused
    • paused
    • true while the player is paused Default: false
    • playing
    • !paused
    • !paused
    • true while the player is playing Default: false
    • poster
    • n/a
    • poster
    • true while the player is in [poster state](../setup#poster Default: false
    • ready
    • n/a
    • n/a
    • true once the player API is ready and completely loaded Default: false
    • rtl
    • setOpts({rtl: true|false})
    • rtl
    • true if the player has a right-to-left layout Default: false
    • seeking
    • seeking
    • seeking
    • true while the player is seeking Default: false
    • splash
    • n/a
    • n/a
    • true while the player is in splash state Default: false
    • video
    • n/a
    • n/a
    • the current video object
    • volumeLevel
    • volume
    • volume
    • the current volume level between 0 and 1 Default: 0.8

new FP Native properties:

[available soon]

API Methods

    • FP 7 method
    • FP Native method if applicable, otherwise
    • html5 medialement method
    • comment
    • disable([flag])
    • setOpts({[flag]: false})
    • n/a
    • disable() without argument toggles between disabled and normal API state. disable(true) disables and disable(false) enables the API. While the API is disabled loading, pausing, resuming and seeking is not possible. The progress bar is greyed out (color configurable via CSS).
    • fullscreen()
    • Toggles between native fullscreen mode and initial screen size. When native fullscreen support is not present the player expands to the full size of the browser window. Note: Many browsers allow this method to work only from events which are triggered by user interaction, like "click", and not for example from player events like "ready" which happen at moments undetermined by the user.
    • load([video], [callback])
    • setSrc()
    • Loads the player with the specified video. See the section on the load method.
    • message(text)
    • emit("error", new Error("message"))
    • n/a
    • Normally used to display a fatal error message, message() may come in handy to notify the user with a custom alert as in this demo.
    • mute([flag])
    • muted = [boolean]
    • muted = [boolean]
    • Normally used to display a fatal error message, message() may come in handy to notify the user with a custom alert as in this demo.
    • pause([callback])
    • pause()
    • pause()
    • Pauses playback.
    • play([video], [callback])
    • togglePlay()
    • play()
    • Alias for the load method.
    • quality(quality)
    • Switches playback to HLS quality index given in argument. The index is zero-based for fixed qualities in the configured hlsQualities array, -1 for adaptive. For VOD quality selection see the method of the same name provided by the VOD quality selector plugin.
    • resume()
    • Resumes playback.
    • seek(time, [callback])
    • currentTime = time
    • currentTime = time
    • Seeks to the given position in seconds. For example: 13.5. The callback is executed once after the seek.
    • seek(flag, [callback])
    • n/a
    • n/a
    • seek(true) seeks 10% forward and seek(false) seeks 10% backward. Same as pressing → or ← on the keyboard. The callback is executed once after the seek.
    • seekTo(position, [callback])
    • n/a
    • n/a
    • seek(true) seeks 10% forward and seek(false) seeks 10% backward. Same as pressing → or ← on the keyboard. The callback is executed once after the seek.
    • shutdown()
    • destroy()
    • n/a
    • Destroys the player instance. Call this method before you remove the container element from the page, or before you remove the player from it. This way all Flowplayer event handles are cleaned up as well. Caveat: Like unload() which is called internally by it, this method requires a splash setup for perfect cleanup. Also prefer unload() whenever possible to avoid unnecessary DOM manipulations and prevent race conditions with immediately ensuing actions by wrapping them in the callback of the shutdown event.
    • speed(rate, [callback])
    • playBackRate = rate
    • playBackRate = rate
    • Sets the speed level to the given rate. 1 = normal speed less than 1 = slow motion greater than 1 = fast forward The callback is executed once after the speed has changed.
    • speed(flag, [callback])
    • n/a
    • n/a
    • Changes the speed based on the speed configuration variable. speed(false) switches backward on the speed array. speed(true) switches forward. The callback is executed once after the speed has changed.
    • stop()
    • pause & currentTime=0
    • pause & currentTime=0
    • Pauses playback and seeks to the beginning of the video. In a poster setup the player goes back into poster state.
    • toggle()
    • pause & currentTime=0
    • pause & currentTime=0
    • Pauses playback and seeks to the beginning of the video. In a poster setup the player goes back into poster state.
    • trigger(type, args)
    • emit(eventName, eventData)
    • n/a
    • Triggers a player event. 2 mandatory arguments: 1. the event type 2. an array of arguments with at least one member; the first item must be the API instance, the second must be provided if the event provides a third argument.
    • unload()
    • n/a
    • n/a
    • In a splash setup unloads the player back to the splash state. In non-splash setups the player is not unloaded but goes back to its initial state, the poster or first video frame is shown.
    • volume(level)
    • volume=level
    • volume=level
    • Set the volume level to a decimal value between 0.0 (no volume) and 1.0 (full volume). The volume level is remembered between page loads.

new FP Native methods

[available soon]

API Events

    • FP 7 event
    • FP Native event or
    • html5 medialement event
    • comment
    • beforeresume
    • n/a
    • n/a
    • Before playback is resumed.
    • beforeseek
    • seeking
    • seeking
    • Before seeking starts at the origin position. The 3rd argument gives access to the seek target position. By callingevent.preventDefault() (where event is the callback's 1st argument) the seek can be stopped.
    • buffer
    • n/a
    • n/a
    • When the browser downloads video. The 3rd argument provides the time position up to which the video is buffered, the equivalent of the value of the buffer property of thevideo object at this moment.
    • disable
    • flowplayer.events.CONFIG
    • config
    • When the player toggles between disabled and normal state. In disabled mode the UI elements cannot be used.
    • error
    • flowplayer.events.ERROR
    • error
    • When an error occurred. The 3rd argument provides an object featuring the code and message properties. See theerror table below.
    • finish
    • flowplayer.events.ENDED
    • ended
    • When playback has finished.
    • flashdisabled
    • n/a
    • n/a
    • Flash is no longer supported
    • fullscreen
    • flowplayer.events.FULLSCREEN_ENTER
    • n/a
    • When the player goes to fullscreen mode.
    • fullscreen-exit
    • flowplayer.events.FULLSCREEN_EXIT
    • n/a
    • When player exits fullscreen mode.
    • load
    • flowplayer.events.LOAD
    • load
    • First event in the lifecycle of a clip, before the configured clip or a new video starts playing. Offers an opportunity to alter the video properties. The 3rd argument provides thevideo object featuring basic data like src, but not yet the video metadata from the server (such as duration). Returning false will prevent the video from loading. Note: In nonsplash setups the initial load event is only available via theglobal flowplayer function.
    • mute
    • flowplayer.events.VOLUME_CHANGE
    • volumechange
    • When the player's mute state is toggled.
    • pause
    • flowplayer.events.PAUSE
    • pause
    • When playback is paused.
    • progress
    • flowplayer.events.TIME_UPDATE
    • timeupdate
    • When the playhead moves forward. Happens approximately every 250 milliseconds during playback. The 3rd argument provides the current playback position, i.e. the current value of the time property of the video object.
    • quality
    • flowplayer.events.SET_QUALITY
    • n/a
    • When a hlsQuality is manually selected. The 3rd argument provides index of the selected HLS level. For VOD quality selection see the event of the same name provided by the VOD quality selector plugin.
    • ready
    • flowplayer.events.CAN_PLAY
    • canplay
    • When the video is fully loaded and video metadata (such as duration) becomes available from thevideo object which is provided by the 3rd argument.
    • resume
    • flowplayer.events.PLAYING
    • playing
    • When playback is resumed.
    • seek
    • flowplayer.events.SEEK
    • seek
    • When seeking is completed at the target position. The 3rd argument gives access to the target position.
    • shutdown
    • flowplayer.events.REAP
    • n/a
    • When the player and API instance is destroyed, after the shutdown()method has been invoked. Last event in a player's life cycle.
    • speed
    • ratechange
    • ratechange
    • When the playback speed is changed. The new level is provided by the 3rd argument.
    • stop
    • flowplayer.events.PAUSE
    • pause
    • When playback is stopped by the stop()method.
    • unload
    • n/a
    • n/a
    • When the player goes back to the splash state.
    • volume
    • flowplayer.events.VOLUME_CHANGE
    • volumechange
    • The new level is provided by the 3rd argument.

new FP Native Events, registered under the flowplayer.events UMD:

  1. MOUNT
  2. CONTEXT_MENU
  3. CLICK
  4. DBL_CLICK
  5. KEYUP
  6. KEYDOWN
  7. LOAD
  8. MOUSE_ENTER
  9. MOUSE_LEAVE
  10. MOUSE_UP
  11. MOUSE_DOWN
  12. MOUSE_MOVE
  13. TOUCH_START
  14. TOUCH_MOVE
  15. TOUCH_END
  16. TOUCH_CANCEL
  17. RESIZE
  18. FULLSCREEN_CHANGE
  19. WEBKIT_NEEDKEY
  20. METADATA
  21. DATA
  22. PROGRESS
  23. LOAD_START
  24. WAITING
  25. DURATION_CHANGE
  26. BEFORE_PLAY
  27. BEFORE_PAUSE
  28. STATE
  29. VIEW_ENTER
  30. VIEW_LEAVE
  31. SOURCE
  32. RECOVER
  33. CONFIG
  34. QUALITIES
  35. SET_QUALITY
  36. NON_RECOVERABLE_ERROR
  37. RECOMMENDATIONS_READY
  38. AUDIO_ONLY_SOURCE
  39. LANDSCAPE
  40. PORTRAIT
  41. DVR
  42. LIVE
  43. SEEK_QUEUED
  44. SEEK_CANCEL

API error codes

[available soon]

Code samples

Also check out our showcase demos, developer demos and the advanced demos Github repository.

v3.0 Migration Player API
Results