source: branches/jw6/doc/embedding.html @ 2187

Revision 2187, 8.2 KB checked in by pablo, 13 months ago (diff)

Doc tweaks
Line 
1<!doctype html>
2<html>
3<head>
4<title>Embedding the Player</title>
5<style>
6    body { padding: 50px 100px; width: 700px; font: 13px/20px Arial; background: #FFF; }
7    a, h1, h2 { color: #369; }
8    h1 { font-size: 32px; }
9    h2 { margin-top: 50px; }
10    h3 { margin-top: 25px; }
11    img { display: block; box-shadow: 0 0 5px #999; margin: 0 10px; }
12    pre { font-size: 12px; background: #E5F3C8; padding:5px 10px; border: 1px solid #D3EAA4; }
13    dt { margin-left: 20px; font-weight: bold; } 
14    dd { color: #333; font-style: italic; }
15</style>
16</head><body>
17
18<h1>Embedding the Player</h1>
19
20<p>This guide explains how to embed JW Player into your site, load the media file(s) you want to play and tweak the player's layout and playback behavior.</p>
21
22
23
24<h2>Player Setup</h2>
25
26<p>Since JW Player is CDN hosted, there is no need to install and upload the player to your site. Therefore, embedding the JW Player is a simple, 3-step process. Open your web page in an HTML editor and:</p>
27
28<ol>
29<li>Insert the JW Player script from our CDN into the head of your page:
30<pre>&lt;script type="text/javascript" src="http://jwpcdn.com/player.js" &gt;&lt;/script&gt;</pre>
31</li>
32<li>Insert a &lt;div&gt; element with a unique <em>id</em> at the location you want the player to appear:
33<pre>&lt;div id="container"&gt;Loading the player ...&lt;/div&gt;</pre>
34</li>
35<li>Insert a script that invokes the JW Player <em>setup()</em> call on your &lt;div&gt;:</li>
36<pre>&lt;script type="text/javascript"&gt;
37    jwplayer("container").setup({
38        file: "/uploads/example.mp4",
39        height: 360,
40        image: "/uploads/example.jpg",
41        width: 640
42    });
43&lt;/script&gt;</pre></li>
44</ol>
45
46<p>The last code block is where the heavy lifting happens. The script in it tells the JW Player library to setup a player instance over the DOM element with ID <em>container</em>. Inside the setup call, the script provides a list of options for configuring the player. In this setup, only the <em>file</em>, <em>height</em>, <em>image</em> and <em>width</em> options are set, but many more are available. They are listed below.</p>
47
48
49
50<h2>Configuration Options</h2>
51
52<p>There are three options for configuring which media file(s) to load in the player:</p>
53
54<dl>
55<dt>file (undefined)</dt>
56<dd>URL to a single audio/video file, HLS/RTMP manifest or YouTube video to play. See the <a href="support.html">Supported Media</a> guide for an overview. Use the <strong>playlist</strong> option for more advanced file setups.</dd>
57<dt>image (undefined)</dt>
58<dd>URL to a JPG/PNG poster image to display before playback is started (and during playback for audio). If not set, the image of the first item in the <strong>playlist</strong> is used.</dd>
59<dt>playlist (undefined)</dt>
60<dd>Array with links to multiple files to load. Enables all sophisticated media playback options, like multiple formats, multiple quality levels or multiple items. See <a href="playlists.html">Working with Playlists</a> for more info.</dd>
61</dl>
62
63<p>Overall, the <strong>file</strong> option can be used only for basic setups, like playing a single MP4 video or MP3 song. Use the <strong>playlist</strong> option for everything else, like an MP4+WebM source, SD+HD quality or a list with multiple items. See <a href="playlists.html">Working with Playlists</a> for more info.</p>
64
65
66<h3>Layout</h3>
67
68<p>These are the options for configuring the layout of the player:</p>
69
70<dl>
71<dt>controls (true)</dt>
72<dd>Whether to display the video controls at the bottom of the screen. Can be <strong>false</strong> or <strong>true</strong>.</dd>
73<dt>height (360)</dt>
74<dd>Height of the player in pixels. We recommend setting this to at least <strong>180</strong>, so all UI elements will fit. However, it can be set to a small size (e.g. <strong>40</strong>) for audio-only playback.</dd>
75<dt>icons (true)</dt>
76<dd>Whether to display the Play and Buffer icons in the center of the screen. Can be <strong>false</strong> or <strong>true</strong>.</dd>
77<dt>skin (undefined)</dt>
78<dd>Which skin to use for styling the player. Can be the identifier of a CDN hosted skin or the URL to a self-hosted skin. See the Player Skinning guide for more info.</dd>
79<dt>stretching (uniform)</dt>
80<dd>How to resize the poster and video to fit the display. Can be <strong>none</strong> (keep original dimensions), <strong>exactfit</strong> (stretch disproportionally), <strong>uniform</strong> (stretch proportionally;  black borders) or <strong>fill</strong> (stretch proportionally; parts cut off).</dd>
81<dt>width (640)</dt>
82<dd>Width of the player in pixels. We recommend setting this to at least <strong>320</strong>. On smaller players, certain UI elements may not fit.</dd>
83</dl>
84
85
86<h3>Behavior</h3>
87
88<p>And these are the options for configuring the setup and playback behavior:</p>
89
90<dl>
91<dt>autostart (false)</dt>
92<dd>Automatically start playing the video on page load. Can be <strong>true</strong> or <strong>false</strong>. Autostart does not work on mobile devices like iOS or Android.</dd>
93<dt>fallback (true)</dt>
94<dd>Whether to render a nice download link for the video if HTML5 and/or Flash are not supported. Can be <strong>true</strong> (a download link is rendered) or <strong>false</strong> (the original HTML is not touched).</dd>
95<dt>mute (false)</dt>
96<dd>Whether to have the sound muted on startup or not. Can be <strong>false</strong> (sound) or <strong>true</strong> (no sound).</dd>
97<dt>primary (html5)</dt>
98<dd>Which rendering mode to try first for rendering the player. Can be <strong>html5</strong> or <strong>flash</strong>.</dd>
99<dt>repeat (list)</dt>
100<dd>What to do when an item finished playback. Can be <strong>list</strong> (play the full playlist once), <strong>none</strong> (stop playback after every item), <strong>always</strong> (repeat the playlist forever) or <strong>single</strong> (repeat the active item forever).</dd>
101<dt>shuffle (false)</dt>
102<dd>Whether to play items from the playlist in random order (if there's more than 1). Can be <strong>true</strong> or <strong>false</strong></dd>
103</dl>
104
105
106<h2>Advanced Options Blocks</h2>
107
108<p>In addition to above configuration options, a list of configuration blocks is available to enable the more advanced functionalities of JW Player. For example, the <em>sidebar</em> block can be used to display the playlist in a sidebar next to the video display:</p>
109
110<pre>&lt;script type="text/javascript"&gt;
111    jwplayer("container").setup({
112        playlist: "http://example.com/playlist.rss",
113        height: 360,
114        sidebar: {
115            position: 'right',
116            size: 320
117        },
118        width: 960
119    });
120&lt;/script&gt;</pre>
121
122<p>As you can see, the <em>sidebar</em> is an object that itself contains a set of configuration options. In this case, the sidebar is setup to the right of the display and set 320 pixels wide. See the <a href="playlists.html">Working with Playlists</a> guide for more info on setting up the sidebar.</p>
123
124
125<p>In addition to the <em>sidebar</em>, the following advanced option blocks are available:</p>
126
127<dl>
128<dt>rtmp</dt>
129<dd>Config block for streaming video with the <a href="#">Adobe RTMP protocol</a>.</dd>
130<dt>captions</dt>
131<dd>Config block for displaying <a href="#">closed captions or subtitles</a>.</dd>
132<dt>logo</dt>
133<dd>Config block for displaying an <a href="#">on-screen watermark</a> (<em>licensed players only</em>).</dd>
134<dt>gapro</dt>
135<dd>Config block for pinging events to <a href="#">Google Analytics</a>.</dd>
136<dt>related</dt>
137<dd>Config block for displaying an overlay with <a href="#">Related Videos</a>.</dd>
138<dt>sharing</dt>
139<dd>Config block for displaying an overlay with <a href="#">Social Sharing links</a>.</dd>
140<dt>ova</dt>
141<dd>Config block for loading ads using the <a href="#">VAST/VPaid standards</a>  (<em>licensed players only</em>).</dd>
142<dt>googima</dt>
143<dd>Config block for loading ads using the <a href="#">Google IMA component</a>  (<em>licensed players only</em>).</dd>
144</dl>
145
146
147
148<h2>Player Removal</h2>
149
150<p>In addition to setting up a player, the JW Player embed script contains a function to unload a player. It's very simple:</p>
151
152<pre>jwplayer("container").remove();</pre>
153
154<p>This formal <em>remove()</em> 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.</p>
155
156
157
158</body>
159</html>
Note: See TracBrowser for help on using the repository browser.