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

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

Revision 1339, 22.1 KB checked in by pablo, 3 years ago (diff)

Fixes an issue with playlist event callbacks in the new API
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 Player's own JavaScript embedder (**jwplayer.js**).
11
12We recommend using the included JW Player Embedder.  It can detect if a browser supports Flash, it ensures that the player's :ref:`javascriptapi` works and it avoids browser compatibility issues.  Also, as of version 5.3, the JW Player Embedder allows you to use the player's HTML5 feautures. 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 from the download to 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 Player Embedder and HTML5 player, upload **jwplayer.js**. 
18
19Your :ref:`media files <mediaformats>` and :ref:`playlists <playlistformats>` can be hosted at any domain. Do note that :ref:`crossdomain` apply when loading these files from a different domain. In short, playing media files works, but loading playlists across domains will not work by default. Resolve this issue by hosting a :ref:`crossdomain.xml file <crossdomain>`.
20
21.. note::
22
23We 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.
24
25
26SWFObject
27---------
28
29There'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>`_.
30
31Before 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/>`_:
32
33.. code-block:: html
34
35   <script type="text/javascript"
36     src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js">
37   </script>
38
39With the library set up, you can start embedding players. Here's an example:
40
41.. code-block:: html
42
43   <p id="container1">Please install the Flash Plugin</p>
44
45   <script type="text/javascript">
46     var flashvars = { file:'/data/bbb.mp4',autostart:'true' };
47     var params = { allowfullscreen:'true', allowscriptaccess:'always' };
48     var attributes = { id:'player1', name:'player1' };
49
50     swfobject.embedSWF('player.swf','container1','480','270','9.0.115','false',
51       flashvars, params, attributes);
52   </script>
53
54It'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:
55
56* 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.
57* 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.
58* 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.
59* 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`.
60* The *instantiation* is where all things come together and the actual player embedding takes place. These are all parameters of the SWFObject call:
61
62   * The URL of the *player.swf*, relative to the page URL.
63   * The ID of the container you want to embed the player into.
64   * The width of the player, in pixels. Note the JW Player automatically stretches itself to fit.
65   * The height of the player, in pixels. Note the JW Player automatically stretches itself to fit.
66   * 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>`.
67   * 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.
68   * Next, the *flashvars*, *params* and *attributes* are passed, in that order.
69
70
71It 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**.
72
73
74Embed tag
75---------
76
77In 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 a SWF player:
78
79* A single *<embed>* tag (for IE + other browsers).
80* An *<object>* tag with nested *<embed>* tag (the first one for IE, the second for other browsers).
81* An *<object>* tag with nested *<object>* tag (the first one for IE, the second for other browsers).
82
83We recommend using the single *<embed>* tag. This works in all current-day browsers (including IE6) and provides the shortest codes. Here is an example embed code that does exactly the same as the SWFObject example above:
84
85.. code-block:: html
86
87   <embed
88     flashvars="file=/data/bbb.mp4&autostart=true"
89     allowfullscreen="true"
90     allowscripaccess="always"
91     id="player1"
92     name="player1"
93     src="player.swf"
94     width="480"
95     height="270"
96   />
97
98As you can see, most of the data of the SWFObject embed is also in here:
99
100* The **container** is now the embed tag itself. The *fallback* text cannot be used anymore.
101* The **flashvars** are merged into a single string, and loaded as an attribute. You should always concatenate the flashvars using so-called querystring parameter encoding: *flashvar1=value1&flashvar2=value2&...*.
102* The **params** each are individual attributes of the embed tag.
103* The **attributes** also are individual attributes of the embed tag.
104* The **instantiation** options (source, width, height) are attributes of the embed tag.
105
106.. note::
107
108   As you can see, the Flash version reference is not in the embed tag: this is one of the drawbacks of this method: it's not possible to sniff for Flash and selectively hide it, e.g. if the flash version is not sufficient or if the device (iPad ...) doesn't support Flash.
109   
110JW Embedder
111-----------
112
113New 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:
114
115* Seamless failover between the Flash and HTML5 players.
116* Automatic integration with the :ref:`JavaScript API <javascriptapi>`.
117
118Getting started
119+++++++++++++++
120
121Embedding the JW Player in your website is a simple, 3-step process:
122
1231. 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.
1242. Include the *jwplayer.js* somewhere in the head of your website:
125   
126    .. code-block:: html
127       
128        <script type="text/javascript" src="/jwplayer/jwplayer.js"></script>
129   
1303. Call the player setup somewhere in the body of your website. Here's a basic example:
131
132    .. code-block:: html
133   
134        <div id="container">Loading the player ...</div>
135   
136        <script type="text/javascript">
137            jwplayer("container").setup({
138                flashplayer: "/jwplayer/player.swf",
139                file: "/uploads/video.mp4",
140                height: 270,
141                width: 480
142            });
143        </script>
144
145When 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.
146
147The *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.
148
149Here's another setup example, this time using a *<video>* tag instead of a generic div:
150
151.. code-block:: html
152
153    <video
154        file="/uploads/video.mp4"
155        height="270"
156        id="container"
157        poster="/uploads/image.jpg"
158        width="480">
159    </video>
160
161    <script type="text/javascript">
162        jwplayer("container").setup({
163            flashplayer: "/jwplayer/player.swf"
164        });
165    </script>
166
167In 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.
168
169.. _quickembed:
170
171Quick Embed
172___________
173
174If 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:
175
176    .. code-block:: html
177       
178        <script type="text/javascript" src="/jwplayer/jwplayer.js"></script>
179        <video class="jwplayer" src="/uploads/video.mp4" poster="/uploads/image.jpg"></video>
180
181That's it!  As long as you have everything in the right place, the <video> tag will be replaced on your page by the JW Player.
182
183
184Setup Syntax
185++++++++++++
186
187Let's take a closer look at the syntax of the *setup()* call. It has the following structure:
188
189.. code-block:: html
190   
191    jwplayer(container).setup({options});
192
193In 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.
194
195The *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:
196
197.. code-block:: html
198
199    <div id="container">Loading the player ...</video>
200
201    <script type="text/javascript">
202        jwplayer("container").setup({
203            autostart: true,
204            controlbar: "none",
205            file: "/uploads/video.mp4",
206            duration: 57,
207            flashplayer: "/jwplayer/player.swf",
208            volume: 80,
209            width: 720
210        });
211    </script>
212
213Though 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:
214
215* **playlist**: allows inline setup of a full playlist, including metadata.
216* **levels**: allows inline setup of multiple quality levels of a video, for bitrate switching purposes.
217* **plugins**: allows inline setup of `JW Player plugins <http://www.longtailvideo.com/addons/plugins/>`_, including their configuration options.
218* **events**: allows inline setup of javascripts for player events, e.g. when you want to do something when the player starts.
219* **players**: allows inline setup of a custom player fallback, e.g. HTML5 first, fallback to Flash.
220
221The sections below explain them in detail.
222
223.. _embed_skinning:
224
225Skins
226+++++
227
228The 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>`_.
229
230To embed a JW Player 5 skin, simply place the ZIP file on your web server and add the *skin* property to your embed code:
231
232.. code-block:: html
233
234    <div id="container">Loading the player ...</div>
235
236    <script type="text/javascript">
237        jwplayer("container").setup({
238            flashplayer: "/jwplayer/player.swf",
239            file: "/uploads/video.mp4",
240            height: 270,
241            width: 480,
242            skin: "/skins/modieus/modieus.zip"
243        });
244    </script>
245
246.. note::
247
248If 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:
249
250.. code-block:: text
251
252 /skins/modieus/modieus.zip
253 /skins/modieus/modieus.xml
254 /skins/modieus/controlbar/
255 /skins/modieus/playlist/
256 etc.
257
258.. _embed_playlist:
259
260Playlist
261++++++++
262
263Previously, 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.
264
265Here 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**.
266
267
268.. code-block:: html
269
270    <div id="container">Loading the player...</div>
271
272    <script type="text/javascript">
273        jwplayer("container").setup({
274            flashplayer: "/jwplayer/player.swf",
275            playlist: [
276                { duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" },
277                { duration: 124, file: "/uploads/bbb.mp4", image: "/uploads/bbb.jpg" },
278                { duration: 542, file: "/uploads/ed.mp4", image: "/uploads/ed.jpg" }
279            ],
280            "playlist.position": "right",
281            "playlist.size": 360,
282            height: 270,
283            width: 720
284        });
285    </script>
286
287.. note::
288
289    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).
290
291A playlist can contain 1 to many videos. For each entry, the  following properties are supported:
292
293* **file**: this one is required (unless you have *levels*, see below). Without a video to play, the playlist item is skipped.
294* **image**: location of the poster image. Is displayed before the video starts, after it finishes, and as part of the graphical playlist.
295* **duration**: duration of the video, in seconds. The player uses this to display the duration in the controlbar, and in the graphical playlist.
296* **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.
297* **title**: title of the video, is displayed in the graphical playlist.
298* **description**: description of the video, is displayed in the graphical playlist.
299* **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.
300* **provider**: specific media playback API (e.g. *http*, *rtmp* or *youtube*) to use for playback of this playlist entry.
301* **levels**: a nested object block, with multiple quality levels of the video. See the *levels* section for more info.
302
303
304
305Levels
306++++++
307
308The **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.
309
310Here'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:
311
312.. code-block:: html
313
314    <div id="container">Loading the player...</div>
315
316    <script type="text/javascript">
317        jwplayer("container").setup({
318            flashplayer: "/jwplayer/player.swf",
319                height: 270,
320                width: 480,
321                image: "/uploads/video.jpg",
322                levels: [
323                    { bitrate: 300, file: "assets/bbb_300k.mp4", width: 320 },
324                    { bitrate: 600, file: "assets/bbb_600k.mp4", width: 480 },
325                    { bitrate: 900, file: "assets/bbb_900k.mp4", width: 720 }
326                ],
327                provider: "rtmp",
328                streamer: "rtmp://mycdn.com/application/"
329        });
330    </script>
331
332
333Here is another example setup, this time using HTTP bitrate switching. The HTTP switching is enabled by setting the *provider* option to *http*:
334
335.. code-block:: html
336
337    <div id="container">Loading the player...</div>
338
339    <script type="text/javascript">
340        jwplayer("container").setup({
341            flashplayer: "/jwplayer/player.swf",
342            height: 270,
343            width: 480,
344            image: "/uploads/video.jpg",
345            levels: [
346                { bitrate: 300, file: "http://mycdn.com/assets/bbb_300k.mp4", width: 320 },
347                { bitrate: 600, file: "http://mycdn.com/assets/bbb_600k.mp4", width: 480 },
348                { bitrate: 900, file: "http://mycdn.com/assets/bbb_900k.mp4", width: 720 }
349            ],
350            provider: "http",
351            "http.startparam":"starttime"
352        });
353    </script>
354
355
356
357Plugins
358+++++++
359
360Plugins 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.
361
362Here 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>`_:
363
364
365.. code-block:: html
366
367    <div id="container">Loading the player...</div>
368
369    <script type="text/javascript">
370        jwplayer("container").setup({
371            flashplayer: "/jwplayer/player.swf",
372            file: "/uploads/video.mp4",
373            height: 270,
374            plugins: {
375                hd: { file: "/uploads/video_high.mp4", fullscreen: true },
376                gapro: { accountid: "UKsi93X940-24" }
377            },
378            image: "/uploads/video.jpg",
379            width: 480
380        });
381        </script>
382
383Here 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:
384
385.. code-block:: html
386
387    <div id="container">Loading the player...</div>
388
389    <script type="text/javascript">
390        jwplayer("container").setup({
391            flashplayer: "/jwplayer/player.swf",
392            playlist: [
393                { file: "/uploads/bbb.mp4", "sharing.link": "http://bigbuckbunny.org" },
394                { file: "/uploads/ed.mp4", "sharing.link": "http://orange.blender.org" }
395            ],
396            plugins: {
397                sharing: { link: true }
398            },
399            height: 270,
400            width: 720
401        });
402    </script>
403
404
405
406.. _embed_events:
407
408Events
409++++++
410
411The **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:
412
413.. code-block:: html
414   
415    <div id="container">Loading the player ...</div>
416   
417    <script type="text/javascript">
418        jwplayer("container").setup({
419            flashplayer: "/jwplayer/player.swf",
420            file: "/uploads/video.mp4",
421            height: 270,
422            width: 480,
423            events: {
424                onComplete: function() { alert("the video is finished!"); }
425            }
426        });
427    </script>
428
429Here 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:
430
431.. code-block:: html
432   
433    <div id="container">Loading the player ...</div>
434   
435    <script type="text/javascript">
436        jwplayer("container").setup({
437            flashplayer: "/jwplayer/player.swf",
438            file: "/uploads/video.mp4",
439            height: 270,
440            width: 480,
441            events: {
442                onReady: function() { this.play(); },
443                onVolume: function(event) { alert("the new volume is "+event.volume); }
444            }
445        });
446    </script>
447
448See the :ref:`API reference <api>` for a full overview of all events and their properties.
449
450.. _embed_players:
451
452Players
453+++++++
454
455The **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:
456
4571. The **Flash** plugin.
4582. The **HTML5** <video> tag.
459
460Using the **players** block, it is possible to specify that the Embedder try the HTML5 player first:
461
462.. code-block:: html
463   
464    <div id="container">Loading the player ...</div>
465   
466    <script type="text/javascript">
467        jwplayer("container").setup({
468            file: "/uploads/video.mp4",
469            height: 270,
470            width: 480,
471            players: [
472                { type: "html5" },
473                { type: "flash", src: "/jwplayer/player.swf" }
474            ]
475        });
476    </script>
477
478
479Player Removal
480++++++++++++++
481
482In addition to setting up a player, the JW Player embed script contains a function to unload a player. It's very simple:
483
484.. code-block:: html
485
486    jwplayer("container").remove();
487
488This 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.