Warning: HTML preview using PygmentsRenderer failed (TypeError: function() takes at least 2 arguments (0 given))

source: trunk/fl5/doc/publishers/embedding.rst @ 1397

Revision 1397, 22.7 KB checked in by pablo, 3 years ago (diff)

Updated release notes, player version
Line 
1.. _embedding:
2
3Embedding the player
4====================
5
6Like every other Flash object, the JW Player has to be embedded into the HTML of a webpage using specific embed codes. Overall, there are three methods for embedding the JW Player:
7
8* Using a generic JavaScript embedder (like `SWFObject <http://code.google.com/p/swfobject/>`_).
9* Using a HTML tag (like *<object>* or *<embed>*).
10* Using the JW Embedder, the JW Player's own JavaScript embedder (**jwplayer.js**).
11
12For embedding the JW Player for Flash, we recommend using SWFObject, since it works in all browsers and many examples exist on the web to get you up and running quickly.  If you want the new HTML5 features of the JW Player, or if you want to leverage the new and improved :ref:`JavaScript API <javascriptapi>`, you'll want to use the JW Embedder.  Detailed instructions can be found below.
13
14Upload
15------
16
17First, a primer on uploading. This may sound obvious, but for the JW Player to work on your website, you must upload the *player.swf* file onto your webserver.  If you want to play YouTube videos, you must also upload the **yt.swf** file - this is the bridge between the player and YouTube.  Finally, to use the JW Embedder and HTML5 player, upload **jwplayer.js**. 
18
19.. note::
20
21        We recommend putting everything in a folder called "jwplayer" at the root of your site.  This enables the :ref:`quickembed` method of setting up the player.  The file structure should look like this:
22       
23.. code-block:: text
24
25        [Web Root]/jwplayer/player.swf 
26        [Web Root]/jwplayer/jwplayer.js
27        [Web Root]/jwplayer/yt.swf
28
29
30SWFObject
31---------
32
33There's a wide array of good, open source libraries available for embedding Flash.  **SWFObject** is the most widely used one. It has `excellent documentation <http://code.google.com/p/swfobject/wiki/documentation>`_.
34
35Before embedding any players on the page, make sure to include the *swfobject.js* script in the *<head>* of your HTML. You can download the script and host it yourself, or leverage the copy `provided by Google <http://code.google.com/apis/ajaxlibs/documentation/>`_:
36
37.. code-block:: html
38
39   <script type="text/javascript"
40     src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js">
41   </script>
42
43With the library set up, you can start embedding players. Here's an example:
44
45.. code-block:: html
46
47   <p id="container1">Please install the Flash Plugin</p>
48
49   <script type="text/javascript">
50     var flashvars = { file:'/data/bbb.mp4',autostart:'true' };
51     var params = { allowfullscreen:'true', allowscriptaccess:'always' };
52     var attributes = { id:'player1', name:'player1' };
53
54     swfobject.embedSWF('player.swf','container1','480','270','9.0.115','false',
55       flashvars, params, attributes);
56   </script>
57
58It's a fairly sizeable chunk of code that contains the embed *container*, *flashvars*, *params*, *attributes* and *instantiation*. Let's walk through them one by one:
59
60* The *container* is the HTML element where the player will be placed into. It should be a block-level element, like a <p> or <div>. If a user has a sufficient version of Flash, the text inside the container is removed and replaced by the videoplayer. Otherwise, the contents of the container will remain visible.
61* The *flashvars* object lists your player :ref:`options`. One option that should always be there is *file*, which points to the file to play. You can insert as many options as you want.
62* The *params* object includes the `Flash plugin parameters <http://kb2.adobe.com/cps/127/tn_12701.html>`_. The two parameters in the example (our recommendation) enable both the *fullscreen* and *JavaScript* functionality of Flash.
63* The *attributes* object include the HTML attributes of the player. We recommend always (and only) setting an *id* and *name*, to the same value. This will be the *id* of the player instance if you use its :ref:`javascriptapi`.
64* The *instantiation* is where all things come together and the actual player embedding takes place. These are all parameters of the SWFObject call:
65
66   * The URL of the *player.swf*, relative to the page URL.
67   * The ID of the container you want to embed the player into.
68   * The width of the player, in pixels. Note the JW Player automatically stretches itself to fit.
69   * The height of the player, in pixels. Note the JW Player automatically stretches itself to fit.
70   * The required version of Flash. We highly recommend setting *9.0.115*. This is the first version that supports :ref:`MP4 <mediaformats>` and is currently installed at >95% of all computers. The only feature for which you might restricted to *10.0.0* is :ref:`RTMP dynamic streaming <rtmpstreaming>`.
71   * The location of a Flash auto-upgrade script. We recommend to **not** use it. People that do not have Flash 9.0.115 either do not want or are not able (no admin rights) to upgrade.
72   * Next, the *flashvars*, *params* and *attributes* are passed, in that order.
73
74
75It is no problem to embed multiple players on a page. However, make sure to give each player instance a different container **id** and a different attributess **id** and **name**.
76
77
78Embedding Without JavaScript
79----------------------------
80
81In cases where a JavaScript embed method is not possible (e.g. if your CMS does not allow including JavaScripts), the player can be embedded using plain HTML. There are various combinations of tags for embedding Flash on a webpage:
82
83* A single *<embed>* tag (for IE + other browsers).
84* An *<object>* tag with nested *<embed>* tag (the first one for IE, the second for other browsers).
85* An *<object>* tag with nested *<object>* tag (the first one for IE, the second for other browsers).
86
87We recommend using the *<object>* tag with a nested *<embed>* tag. This works in the widest array of browsers, including older browsers such as Netscape. Here is an example embed code that does exactly the same as the SWFObject example above:
88
89.. code-block:: html
90
91        <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" width="480" height="270" id="player1" name="player1">
92           <param name="movie" value="/jwplayer/player.swf">
93           <param name="allowfullscreen" value="true">
94           <param name="allowscriptaccess" value="always">
95           <param name="flashvars" value="file=/data/bbb.mp4&autostart=true">
96           <embed id="player1"
97                  name="player1"
98                  src="/jwplayer/player.swf"
99                  width="480"
100                  height="270"
101                  allowscriptaccess="always"
102                  allowfullscreen="true"
103                  flashvars="file=/data/bbb.mp4&autostart=true"
104           />
105        </object>
106
107As you can see, most of the data of the SWFObject embed is also in here:
108
109* The **container** is now the id of both the object embed tags. The *fallback* text cannot be used anymore.
110* The **flashvars** are merged into a single string, and loaded as an attribute in each of the tags. You should always concatenate the flashvars using so-called querystring parameter encoding: *flashvar1=value1&flashvar2=value2&...*.
111* The **params** and **attributes** from SWFObject are individual attributes of the embed tag, and *param* tags inside of the object tag.
112* The **instantiation** options (source, width, height) are attributes of the embed and object tags.
113
114.. note::
115
116   The Flash version reference is not in these tags: this is one of the drawbacks of this method: it's not possible to detect Flash and selectively hide it, e.g. if the flash version is not sufficient or if the device (iPad ...) doesn't support Flash.
117   
118For an interesting overview on the different embedding methods, `this article <http://www.alistapart.com/articles/flashembedcagematch/>`_ compares several methods, and provides a historical overview of the subject. 
119
120
121JW Embedder
122-----------
123
124New in version 5.3, the JW Player features its own embedding method.  While the previous embed methods can still be used, the built-in embed method has a couple of useful features:
125
126* Seamless failover between the Flash and HTML5 players.
127* Automatic integration with the :ref:`JavaScript API <javascriptapi>`.
128
129Getting started
130+++++++++++++++
131
132Embedding the JW Player in your website is a simple, 3-step process:
133
1341. Upload the *jwplayer.js*, *player.swf* and *yt.swf* files from the download ZIP to your server. All other files in the download (documentation, source code, etc) are optional.
1352. Include the *jwplayer.js* somewhere in the head of your webpage:
136   
137    .. code-block:: html
138       
139        <script type="text/javascript" src="/jwplayer/jwplayer.js"></script>
140   
1413. Call the player setup somewhere in the body of your website. Here's a basic example:
142
143    .. code-block:: html
144   
145        <div id="container">Loading the player ...</div>
146   
147        <script type="text/javascript">
148            jwplayer("container").setup({
149                flashplayer: "/jwplayer/player.swf",
150                file: "/uploads/video.mp4",
151                height: 270,
152                width: 480
153            });
154        </script>
155
156When the page is loading, the JW Player is automatically instantiated on top of the *<div>*. By default, the player is rendered in Flash. If Flash is not supported (e.g. on an iPad), the player is rendered in HTML5.
157
158The *flashplayer* option (to tell the JavaScript where the SWF resides) is just one of many `configuration options <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12536/configuration-options>`_ available for configuring the JW Player.
159
160Here's another setup example, this time using a *<video>* tag instead of a generic div:
161
162.. code-block:: html
163
164    <video
165        src="/uploads/video.mp4"
166        height="270"
167        id="container"
168        poster="/uploads/image.jpg"
169        width="480">
170    </video>
171
172    <script type="text/javascript">
173        jwplayer("container").setup({
174            flashplayer: "/jwplayer/player.swf"
175        });
176    </script>
177
178In this case, the JW Player is actually inspecting <video> tag and loading its attributes as configuration options. It's a useful shortcut for setting up a basic player.
179
180.. _quickembed:
181
182Quick Embed
183___________
184
185If you've uploaded your *player.swf* and *jwplayer.js* files to a folder called "jwplayer" in the root of your website, you can embed the player by using two simple lines of HTML:
186
187    .. code-block:: html
188       
189        <script type="text/javascript" src="/jwplayer/jwplayer.js"></script>
190        <video class="jwplayer" src="/uploads/video.mp4" poster="/uploads/image.jpg"></video>
191
192That's it!  As long as you have everything in the right place, all <video> tags on your page whose class is **jwplayer** will be replaced on your page by the JW Player.
193
194
195Setup Syntax
196++++++++++++
197
198Let's take a closer look at the syntax of the *setup()* call. It has the following structure:
199
200.. code-block:: html
201   
202    jwplayer(container).setup({options});
203
204In this block, the *container* is the DOM element(*<video>* or *<div>*, *<p>*, etc.) you want to load the JW Player into. If the element is a *<video>* tag, the attributes of that tag (e.g. the *width* and *src*) are loaded into the player.
205
206The *options* are the list of configuration options for the player. The `configuration options guide <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12536/configuration-options>`_ contains the full overview. Here's an example with a bunch of options:
207
208.. code-block:: html
209
210    <div id="container">Loading the player ...</video>
211
212    <script type="text/javascript">
213        jwplayer("container").setup({
214            autostart: true,
215            controlbar: "none",
216            file: "/uploads/video.mp4",
217            duration: 57,
218            flashplayer: "/jwplayer/player.swf",
219            volume: 80,
220            width: 720
221        });
222    </script>
223
224Though generally a flat list, there are a couple of options that can be inserted as structured blocks inside the setup method. Each of these blocks allow for quick but powerful setups:
225
226* **playlist**: allows inline setup of a full playlist, including metadata.
227* **levels**: allows inline setup of multiple quality levels of a video, for bitrate switching purposes.
228* **plugins**: allows inline setup of `JW Player plugins <http://www.longtailvideo.com/addons/plugins/>`_, including their configuration options.
229* **events**: allows inline setup of JavaScripts for player events, e.g. when you want to do something when the player starts.
230* **players**: allows inline setup of a custom player fallback, e.g. HTML5 first, fallback to Flash.
231
232The sections below explain them in detail.
233
234.. _embed_skinning:
235
236Skins
237+++++
238
239The JW Player has a wide variety of skins that can be used to modify the look and feel of the player.  They can be downloaded from our `AddOns Library <http://www.longtailvideo.com/addons/skins>`_.
240
241To embed a JW Player 5 skin, simply place the ZIP file on your web server and add the *skin* property to your embed code:
242
243.. code-block:: html
244
245    <div id="container">Loading the player ...</div>
246
247    <script type="text/javascript">
248        jwplayer("container").setup({
249            flashplayer: "/jwplayer/player.swf",
250            file: "/uploads/video.mp4",
251            height: 270,
252            width: 480,
253            skin: "/skins/modieus/modieus.zip"
254        });
255    </script>
256
257.. note::
258
259        If you're configuring the Embedder to run primarily in HTML5 mode using the :ref:`embed_players` block, you'll need to take the additional step of unzipping the skin ZIP and uploading its contents to your web server in the same location as the ZIP file itself.  Your skin's folder structure would look something like this:
260
261.. code-block:: text
262
263 /skins/modieus/modieus.zip
264 /skins/modieus/modieus.xml
265 /skins/modieus/controlbar/
266 /skins/modieus/playlist/
267 etc.
268
269.. _embed_playlist:
270
271Playlist
272++++++++
273
274Previously, loading a playlist in the JW Player was only available by using an `XML playlist format <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12537/xml-playlist-support>`_ like RSS or ATOM. With the JW Player embed method though, it is possible to load a full playlist into the player using the **playlist** object block.
275
276Here is an example. In it, a playlist of three items is loaded into the player. Each item contains a **duration** hint, the **file** location and the location of a poster **image**.
277
278
279.. code-block:: html
280
281    <div id="container">Loading the player...</div>
282
283    <script type="text/javascript">
284        jwplayer("container").setup({
285            flashplayer: "/jwplayer/player.swf",
286            playlist: [
287                { duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" },
288                { duration: 124, file: "/uploads/bbb.mp4", image: "/uploads/bbb.jpg" },
289                { duration: 542, file: "/uploads/ed.mp4", image: "/uploads/ed.jpg" }
290            ],
291            "playlist.position": "right",
292            "playlist.size": 360,
293            height: 270,
294            width: 720
295        });
296    </script>
297
298.. note::
299
300    The *playlist.position* and *playlist.size* options control the visible playlist inside the Flash player. To date, the HTML5 player doesn't support a visible playlist yet (though it can manage a playlist of videos).
301
302A playlist can contain 1 to many videos. For each entry, the  following properties are supported:
303
304* **file**: this one is required (unless you have *levels*, see below). Without a video to play, the playlist item is skipped.
305* **image**: location of the poster image. Is displayed before the video starts, after it finishes, and as part of the graphical playlist.
306* **duration**: duration of the video, in seconds. The player uses this to display the duration in the controlbar, and in the graphical playlist.
307* **start**: starting point inside the video. When a user plays this entry, the video won't start at the beginning, but at the offset you present here.
308* **title**: title of the video, is displayed in the graphical playlist.
309* **description**: description of the video, is displayed in the graphical playlist.
310* **streamer**: streaming application to use for the video. This is only used for `RTMP <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12535/video-delivery-rtmp-streaming>`_ or `HTTP <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12534/video-delivery-http-pseudo-streaming>`_ streaming.
311* **provider**: specific media playback API (e.g. *http*, *rtmp* or *youtube*) to use for playback of this playlist entry.
312* **levels**: a nested object block, with multiple quality levels of the video. See the *levels* section for more info.
313
314
315
316Levels
317++++++
318
319The **levels** object block allows you to load multiple quality levels of a video into the player. The multiple levels are used by the Flash player (HTML5 not yet) for `RTMP <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12535/video-delivery-rtmp-streaming>`_ or `HTTP <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12534/video-delivery-http-pseudo-streaming>`_ bitrate switching. Bitrate switching is a mechanism where the player automatically shows the best possible video quality to each viewer.
320
321Here's an example setup, using RTMP bitrate switching (also called *dynamic streaming*). Note the additional *streamer* option, which tells the player the location of the RTMP server:
322
323.. code-block:: html
324
325    <div id="container">Loading the player...</div>
326
327    <script type="text/javascript">
328        jwplayer("container").setup({
329            flashplayer: "/jwplayer/player.swf",
330                height: 270,
331                width: 480,
332                image: "/uploads/video.jpg",
333                levels: [
334                    { bitrate: 300, file: "assets/bbb_300k.mp4", width: 320 },
335                    { bitrate: 600, file: "assets/bbb_600k.mp4", width: 480 },
336                    { bitrate: 900, file: "assets/bbb_900k.mp4", width: 720 }
337                ],
338                provider: "rtmp",
339                streamer: "rtmp://mycdn.com/application/"
340        });
341    </script>
342
343
344Here is another example setup, this time using HTTP bitrate switching. The HTTP switching is enabled by setting the *provider* option to *http*:
345
346.. code-block:: html
347
348    <div id="container">Loading the player...</div>
349
350    <script type="text/javascript">
351        jwplayer("container").setup({
352            flashplayer: "/jwplayer/player.swf",
353            height: 270,
354            width: 480,
355            image: "/uploads/video.jpg",
356            levels: [
357                { bitrate: 300, file: "http://mycdn.com/assets/bbb_300k.mp4", width: 320 },
358                { bitrate: 600, file: "http://mycdn.com/assets/bbb_600k.mp4", width: 480 },
359                { bitrate: 900, file: "http://mycdn.com/assets/bbb_900k.mp4", width: 720 }
360            ],
361            provider: "http",
362            "http.startparam":"starttime"
363        });
364    </script>
365
366
367
368Plugins
369+++++++
370
371Plugins can be used to stack functionality on top of the JW Player. A wide array of plugins is available `in our library <http://www.longtailvideo.com/addons/plugins/>`_, for example for viral sharing, analytics or advertisements.
372
373Here is an example setup using both the `HD plugin <http://www.longtailvideo.com/addons/plugins/65/HD>`_ and the `Google Analytics Pro plugin <http://www.longtailvideo.com/addons/plugins/107/Google-Analytics-Pro>`_:
374
375
376.. code-block:: html
377
378    <div id="container">Loading the player...</div>
379
380    <script type="text/javascript">
381        jwplayer("container").setup({
382            flashplayer: "/jwplayer/player.swf",
383            file: "/uploads/video.mp4",
384            height: 270,
385            plugins: {
386                hd: { file: "/uploads/video_high.mp4", fullscreen: true },
387                gapro: { accountid: "UKsi93X940-24" }
388            },
389            image: "/uploads/video.jpg",
390            width: 480
391        });
392        </script>
393
394Here is another example, using the `sharing plugin <http://www.longtailvideo.com/addons/plugins/110/Sharing>`_. In this example, plugin parameters are also included in the playlist block:
395
396.. code-block:: html
397
398    <div id="container">Loading the player...</div>
399
400    <script type="text/javascript">
401        jwplayer("container").setup({
402            flashplayer: "/jwplayer/player.swf",
403            playlist: [
404                { file: "/uploads/bbb.mp4", "sharing.link": "http://bigbuckbunny.org" },
405                { file: "/uploads/ed.mp4", "sharing.link": "http://orange.blender.org" }
406            ],
407            plugins: {
408                sharing: { link: true }
409            },
410            height: 270,
411            width: 720
412        });
413    </script>
414
415
416
417.. _embed_events:
418
419Events
420++++++
421
422The **events** block allows you to respond on player events in JavaScript. It's a short, powerful way to add player - pager interactivity. Here is a swift example:
423
424.. code-block:: html
425   
426    <div id="container">Loading the player ...</div>
427   
428    <script type="text/javascript">
429        jwplayer("container").setup({
430            flashplayer: "/jwplayer/player.swf",
431            file: "/uploads/video.mp4",
432            height: 270,
433            width: 480,
434            events: {
435                onComplete: function() { alert("the video is finished!"); }
436            }
437        });
438    </script>
439
440Here is another example, with two event handlers. Note the *onReady()* handler autostarts the player using the *this* statement and the *onVolume()* handler is processing an event property:
441
442.. code-block:: html
443   
444    <div id="container">Loading the player ...</div>
445   
446    <script type="text/javascript">
447        jwplayer("container").setup({
448            flashplayer: "/jwplayer/player.swf",
449            file: "/uploads/video.mp4",
450            height: 270,
451            width: 480,
452            events: {
453                onReady: function() { this.play(); },
454                onVolume: function(event) { alert("the new volume is "+event.volume); }
455            }
456        });
457    </script>
458
459See the :ref:`API reference <javascriptapi>` for a full overview of all events and their properties.
460
461.. _embed_players:
462
463Players
464+++++++
465
466The **players** option block can be used to customize the order in which the JW Player uses the different browser technologies for rendering the player. By default, the JW Player uses this order:
467
4681. The **Flash** plugin.
4692. The **HTML5** <video> tag.
470
471Using the **players** block, it is possible to specify that the Embedder try the HTML5 player first:
472
473.. code-block:: html
474   
475    <div id="container">Loading the player ...</div>
476   
477    <script type="text/javascript">
478        jwplayer("container").setup({
479            file: "/uploads/video.mp4",
480            height: 270,
481            width: 480,
482            players: [
483                { type: "html5" },
484                { type: "flash", src: "/jwplayer/player.swf" }
485            ]
486        });
487    </script>
488
489
490Player Removal
491++++++++++++++
492
493In addition to setting up a player, the JW Player embed script contains a function to unload a player. It's very simple:
494
495.. code-block:: html
496
497    jwplayer("container").remove();
498
499This formal **remove()** function will make sure the player stops its streams, the DOM is re-set to its original state and all event listeners are cleaned up.
Note: See TracBrowser for help on using the repository browser.