JW Player WordPress Plugin Reference

The JW Player WordPress Plugin enables you to configure and embed audio and video content through your WordPress website. This is the official JW Player plugin, developed by the JW Player team itself.

This guide explains all functionality available in the plugin. For those eager to get started, there's a separate Getting Started guide, which explains the installation and basic embed process.

Overview

The JW Player WordPress Plugin is compatible with WordPress 3.0 and up. It adds the following capabilities to WordPress:

• A thumbnail property and Embed JW Player button for audio/video files in the Media Manager.
• An option to add External Media (including RTMP streams & YouTube videos) to the Media Manager.
• The ability to group multiple audio/video files in Playlists and embed these playlists with JW Player.
• Management of multiple Player Templates, each with their own layout and playback settings.
• The ability to override Player Template settings through options in the Short Codes.

Finally, some Plugin Settings are available, including those to set your JW Player edition/key and configure the short code behaviour on overview pages.

Media Manager

The JW Player Plugin for WordPress extends the existing media management capabilities of WordPress. This allows you to embed the player into your post through the Add Media interface:

To insert a JW Player, simply click on the Add Media button while editing your post. This will cause the WordPress media manager popup to appear. Now, go to the Media Library section to select an audio/video file (or upload a new one). The metadata of this item appear to the right:

In addition to the default WordPress meta data, the JW Player Plugin for WordPress provides several fields related to the configuration of the JW Player. These include the following:

Thumbnail

This allows you to specify a poster image for the audio/video file from your Media Library. GIF, JPG and PNG images are supported. Alternatively, you can configure an image from outside WordPress by clicking the Thumbnail URL link.

JW Player

This allows you to embed the selected audio/video file into your post with JW Player. You can choose to select a specific Player Template or stick with the default one.

Clicking the button Embed JW Player button will insert its Short Code into your post and close the Media Manager.

External Media

The JW Player plugin adds two new screens to the Media Manager. The first, Add External URL, allows you to add an external media URL to the Media Library. Here's what the screen looks like:

As the help text says, several types of external media can be inserted. Here's the entire list:

• MP4, FLV or WebM videos (e.g. http://example.com/video.mp4). MP4 videos are preferred, since they play across desktop browsers and mobile devices. See Media Format Support for more info.
• MP3, AAC or Ogg audio files (e.g. http://example.com/song.mp3). MP3/AAC are preferred, since they play across desktop browsers and mobile devices. See Media Format Support for more info.
• YouTube videos, loaded simply by providing the YouTube play page (e.g. http://youtu.be/eRsGyueVLvQ). YouTube videos play on desktops and on iOS/Android. See Media Format Support for more info.
• RTMP streams, loaded by providing the full RTMP stream URL (e.g. rtmp://example.com/vod/mp4:video.mp4). Note that RTMP streams only play on the desktop, in Flash. See Using RTMP Streaming for more info.
• Apple HLS streams (e.g. http://example.com/stream.m3u8). Apple HLS is an HTTP streaming format that works on both desktops and iOS (unlike RTMP). See Using Apple HLS Streaming for more info. Note that HLS streams are only supported if you inserted a JW Player Premium or Ads edition license into the Plugin License Settings.

After inserting external URLs, they can then be managed and embedded just like videos you uploaded to the Media Library. You can also group external URLs together with uploaded media into playlists.

Playlists

The second screen added to the media manager is the one to Embed a Playlist. It allows you to embed a playlist you created with JW Player:

To build a playlist, navigate to the Playlists page located in the Media section of the WordPress dashboard. There, you will see two table headers. The table on the right displays all audio/video files in your Media Library. The table on the left, initially empty, lists which videos are in your playlist:

To begin creating a playlist, enter the name of the playlist in the New Playlist field and click the Create Playlist button. Next, simply drag items from the right to the left column. To remove an item simply drag it back to the media column on the right. Once you are satisfied click the Save button to save the playlist. If you wish to remove a playlist, simply click the Delete button.

Template Settings

Note JW Player has the ability to display the playlist in a sidebar next to the video screen (here's an example). You can enable this through the listbar options in your Player Templates. The specific options are:

listbar position

Whether the playlist sidebar should be displayed to the right or bottom of the video screen. The default is none.

listbar size

The width (position=right) or height (position=bottom) of the playlist sidebar in pixels. The default is 180 pixels.

Note the listbar steals pixels from the video screen. If, for example, the player is 560 pixels high and a bottom listbar has a size of 200 pixels, that leaves 360 pixels for the video screen.

Player Templates

The JW Player WordPress plugin is very flexible in its management of the JW Player. You can begin embedding JW Players immediately after installing the plugin. However, you will be using the default JW Player template, which may not fit with the theme of your site. Therefore, there's the ability to design your own JW Player templates, under JW Player » Templates:

In this section, there's the ability to create new player templates or to edit, copy and delete existing ones. Clicking an Edit button will display the player template options.

Player Template Options

The available player options depend upon which edition of JW Player you licensed:

• All player editions contain the basic layout and playback options, as well as the playlist sidebar options.
• The Pro edition adds support for adding a custom watermark.
• The Premium edition adds the selection of premium skins plus Google Analytics & Social Sharing options.
• The Ads edition adds the ability to insert a VAST/VPAID or Google IMA pre-roll ad.

See the Plugin Settings for directions on how to set your player edition and license key.

Short Codes

The actual embedding of a JW Player into an article body is controlled by the shortcode system. The shortcode system is quite flexible and allows for varying levels of complexity in your embedding. The basic syntax for the shortcode system is as follows:

[jwplayer param1="value1" param2="value2" ...]

When clicking an Embed JW Player button in the WordPress interface, a basic shortcode is always inserted. Here are a few examples:

[jwplayer mediaid="22" player="3"]
[jwplayer playlistid="1" player="3"]
[jwplayer mediaid="22"]

The first above shortcode embeds item 22 from your media library, using JW Player template number 3. The second shortcode embeds not a single media, but playlist number 1. The third shortcode contains no player, so the default Player Template is used.

Custom Options

In addition to these basic parameters, you can specify one or more JW Player Configuration Option to tweak your embeds. This gives you the flexibility to setup specific players without creating a new Player Template. Here are a few examples:

[jwplayer mediaid="22" player="3" width="320" height="180"]
[jwplayer playlistid="1" player="3" autostart="true"]
[jwplayer mediaid="22" primary="html5"]

In the first shortcode, the dimensions of the player are set to 320x180, overriding those set in player number 3. In the second shortcode, the player is set to automatically start playback on page load. In the third shortcode, the player is set to prefer the HTML5 rendering mode over Flash.

Plugin Settings

The JW Player WordPress Plugin provides settings for inserting your license edition/key, for customising the shortcode behaviour on overview pages and for some other features.

License Settings

If you own a commercial JW Player license, you must set your Player Edition and License Key in the JW Player » Settings screen:

Setting these options will un-lock the edition's additional Player Template options, as well as hide the JW Player logo from the player video screen. Note a license key is not required for the Free edition, but inserting one will enable the video analytics in your JW Player account.

Shortcode Settings

Unfortunately, the JW Player plugin does not use the official WordPress Shortcode API due to incompatibility with options that contain a ".". Therefore, there's unexpected behaviour on overview pages (home, categories, search, tags) in combination with certain WordPress themes. This can be overridden by these shortcode settings:

In practice, you should set these options to Use excerpt if you see chunks of JavaScript instead of JW Players on your overviews. If you don't want players to show up at all in overviews, you should set Strip shortcode.

Other Settings

The last section of the settings contains three items:

Player Version

This informs you which version of JW Player is currently active with the WordPress plugin. New versions of JW Player will automatically get pushed along with new versions of the WordPress plugin. There's no need for any manual upgrades.

Anonymous Tracking

This informs us which JW Player plugin features you are using for your site (templates, external media, playlists, shortcodes, etc). It allows us to prioritize development and bug fixing. Un-check the box if you don't want to share this info.

Purge Settings

Checking this option will delete all JW Player plugin data (templates, playlists) the next time you de-activate the plugin. Use this if you intend to stop using the JW Player plugin altogether.