Order Now AdSolution Sign Up | Login » Bits on the Run Sign Up | Login »

Configuration Options

Purpose

This guide is a list of all configuration options (flashvars) the JW Player for Flash v5 supports.

Introduction

Configuration options are entered into the embed code and define how the player looks and functions.

Contents

Encoding

First, a note on encoding. If you are embedding the Flash player using SWFObject or <object> / <embed< code, you must URL encode the three characters ? = & inside flashvars, because of the way these options are loaded into Flash (as a querystring). The urlencoded values for these symbols are listed here:

  • ? → %3F
  • = → %3D
  • & → %26

If, for example, your file flashvar is at the location getplaylist.php?id=123&provider=flv, you must encode the option to:

getplaylist.php%3Fid%3D123%26provider%3Dflv

Note, if you are using the JW Embedder, URL encoding these options is not necessary.

Playlist Properties

To load a playlist, only a single flashvar is required:

playlistfile ( undefined )
Location of an XML playlist to load into the player.

Note - If you're using the JW Embedder, you can also pass in several types of structured data that represents the playlist. See the JW Embedder Reference Guide for more information.

The following flashvars can be set instead of playlistfile. They are used to create a playlist with a single item. They set various properties of the media item to load (e.g. the source file or preview image or title). Those properties are:

duration ( 0 )
Duration of the file in seconds. Set this to present the duration in the controlbar before the video starts. It can also be set to a shorter value than the actual file duration. The player will restrict playback to only that section.
file ( undefined )
Location of the file or playlist to play, e.g. http://www.mywebsite.com/myvideo.mp4.
image ( undefined )
Location of a preview (poster) image; shown in display before the video starts.
mediaid ( undefined )
Unique string (e.g. 9Ks83JsK) used to identify this media file. Is used by certain plugins, e.g. for the targeting of advertisements. The player itself doesn’t use this ID anywhere.
provider ( undefined )

Set this flashvar to tell the player in which format (regular/streaming) the player is. By default, the provider is detected by the player based upon the file extension. If there is no suiteable extension, it can be manually set. The following provider strings are supported:

  • video: progressively downloaded FLV / MP4 video, but also AAC audio. See Media Support.
  • sound: progressively downloaded MP3 files. See Media Support.
  • image: JPG/GIF/PNG images. See Media Support.
  • youtube: videos from YouTube. See Media Support.
  • http (Flash only): FLV/MP4 videos using HTTP pseudo-streaming. See HTTP Pseudostreaming.
  • rtmp (Flash only): FLV/MP4/MP3 files or live streams using RTMP streaming. See RTMP Streaming.

Note - In addition to these built-in providers, it is possible to load custom providers into the JW Player, e.g. for specific CDN support. Custom providers are packed in a separate SWF file, much like a plugin.

A number of custom providers is available from our AddOns repository. Third party developers interested in building a custom provider should check our our developer site, which includes documentation and a MediaProvider SDK.

start ( 0 )
Position in seconds where playback should start. This option works for HTTP Pseudostreaming, RTMP Streaming and the MP3 and YouTube files. It does not work for regular videos.
streamer ( undefined )
Location of an RTMP or HTTP server instance to use for streaming. Can be an RTMP application or external PHP/ASP file. See RTMP Streaming and HTTP Pseudostreaming.

 

Note - Technically, any playlist item property is also available as an option. In practice though, the properties author, date, description, link, tags and title are not used anywhere if a single media file is loaded.

Layout

These flashvars control the look and layout of the player.

controlbar.position ( over* )
Position of the controlbar. Can be set to bottom, top, over and none.
* Note - The default value for this setting varies depending on whether or not the JW Embedder is used to embed the player. If the Embedder is used, the controlbar's position will be set to over If the player is embedded as a Flash-only component (i.e., using SWFObject to embed player.swf), the default position will be bottom.
controlbar.idlehide ( false )
If controlbar.position is set to over, this option determines whether the controlbar stays hidden when the player is paused or stopped.
display.showmute ( false )
Shows a mute icon in the player's display window while the player is playing. Disabled by default.
dock ( true )
set this to false to show plugin buttons in controlbar. By default (true), plugin buttons are shown in the display.
icons ( true )
set this to false to hide the play button and buffering icons in the display.
playlist.position ( none )
Position of the playlist. Can be set to bottom, top, right, left, over or none.

Note - In HTML5 mode on iOS devices, to scroll the playlist, users must use a two-finger swipe gesture. To enable one-finger scrolling, simply include the iScroll 4 JavaScript library in the <head> of your HTML document.

playlist.size ( 180 )
When the playlist is positioned below the display, this option can be used to change its height. When the playlist lives left or right of the display, this option represents its width. In the other cases, this option isn’t needed.
skin ( undefined )

Location of a skin file, containing graphics which change the look of the player. There are two types of skins available:

  • XML/PNG skins: These skins consist of an XML file with settings and a bunch of PNG images. The files are packed up in a ZIP, which improves the time it takes for them to load over the network. Building your own skin is extremely easy and can be done with any basic image and text editor. See XML/PNG Skinning for more info.
  • SWF skins: These skins consist of a single SWF file, built using Adobe Flash. This type of skins has been supported since the 4.0 player. Since SWF skins can only be built using Flash (a $500+ package) and since this skinning model can easily break, SWF skins are considered deprecated in favor of PNG skins.

Our AddOns repository contains a list of available skins.

Behavior

These flashvars control the playback behavior of the player.

autostart ( false )
Set this to true to automatically start the player on load.
bufferlength ( 1 )  Flash only
Number of seconds of the file that has to be loaded before the player starts playback. Set this to a low value to enable instant-start (good for fast connections) and to a high value to get less mid-stream buffering (good for slow connections).
id ( undefined )
Unique identifier of the player in the HTML DOM. You only need to set this option if you want to use the JavaScript API and want to target Linux users.

The ID is needed by JavaScript to get a reference to the player. On Windows and Mac OS X, the player automatically reads the ID from the id and name attributes of the player’s HTML embed code <embedding>. On Linux however, this functionality does not work. Setting the id option in addition to the HTML attributes will fix this problem.

item ( 0 )
Playlist item that should start to play. Use this to start the player with a specific item instead of with the first item.
mute ( false )
Mute the sounds on startup. Is saved in a cookie.
netstreambasepath ( undefined )
The netstreambasepath should be set to a URL from which relative paths will be calculated for video files. Introduced in JW Player 5.4, this configuration parameter directs the video and http media providers to request video files relative to the specified netstreambasepath rather than relative to the player SWF (see below). This will likely cause issues for publishers using the JW Embedder with relative file paths.
Note - This does not affect any other URLs (such as skins, playlists, or plugins), but relative URLs contained within a playlist will be calculated relative to this path.
Note - The netstreambasepath configuration option exists as a workaround for a technical limitation in Flash. All video in Flash must be loaded using Adobe's NetStream class. For historical reason, relative file paths passed into the NetStream are always resolved relative to the SWF making the request.
The JW Player uses the NetStream class to load media for the video and http media providers. With the introduction of the HTML5 player, it became impossible to consistently reference a video file via a relative path, as in Flash mode would load it relative to the player SWF, while in HTML5 mode it would load relative to the current page. The netstreambasepath is a workaround that allow for a consistent referencing by specifing the original path from which relative URLs should be resolved.
playerready ( undefined )
By default, the player calls a playerReady() JavaScript function when it is initialized. This option is used to let the player call a different function after it’s initialized (e.g. registerPlayer()).
plugins ( undefined )
A powerful feature, this is a comma-separated list of plugins to load (e.g. hd,viral). Plugins are separate JavaScript or SWF files that extend the functionality of the player, e.g. with advertising, analytics or viral sharing features. Visit our addons repository to browse the long list of available plugins.
repeat ( none )

What to do when the mediafile has ended. Has several options:

  • none: do nothing (stop playback) whever a file is completed.
  • list: play each file in the playlist once, stop at the end.
  • always: continously play the file (or all files in the playlist).
  • single: continously repeat the current file in the playlist.
shuffle ( false )
Shuffle playback of playlist items. The player will randomly pick the items.
smoothing ( true )  Flash only
This sets the smoothing of videos, so you won’t see blocks when a video is upscaled. Set this to false to disable the feature and get performance improvements with old computers / big files.
stretching ( uniform )

Defines how to resize the poster image and video to fit the display. Can be:

  • none: keep the original dimensions.
  • exactfit: disproportionally stretch the video/image to exactly fit the display.
  • uniform: stretch the image/video while maintaining its aspect ratio. There’ll be black borders.
  • fill: stretch the image/video while maintaining its aspect ratio, completely filling the display.
volume ( 90 )
Startup audio volume of the player. Can be 0 to 100.

Colors

These options are available when either using no skin or when using skins built with the older SWF skinning model (these skins have the extension .swf). These color options will be deprecated once SWF skinning support is dropped in a future release.

backcolor ( ffffff )  Flash only
background color of the controlbar and playlist. This is white by default.
frontcolor ( 000000 )  Flash only
color of all icons and texts in the controlbar and playlist. Is black by default.
lightcolor ( 000000 )  Flash only
Color of an icon or text when you rollover it with the mouse. Is black by default.
screencolor ( 000000 )  Flash only
Background color of the display. Is black by default.

The four color flashvars must be entered using hexadecimal values, as is common for web colors (e.g. FFCC00 for bright yellow).

Config XML

All options can be listed in an XML file and then fed to the player with a single option:

config ( undefined )  Flash only
location of a XML file with flashvars. Useful if you want to keep the actual embed codes short. Here’s an example:

Here is an example of such an XML file:

<config>
  <file>files/bunny.mp4</file>

  <image>files/bunny.jpg</image>
  <repeat>true</repeat>
  <backcolor>333333</backcolor>
  <volume>40</volume>

  <controlbar>over</controlbar>
</config>

Options set in the embed code will overwrite those set in the config XML.

Note - Due to the Crossdomain Security Restrictions restrictions of Flash, you cannot load a config XML from one domain in a player on another domain. This issue can be circumvented by placing a crossdomain.xml file on the server that hosts your XML.