Context Navigation

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

source: trunk/fl5/doc/publishers/javascriptapi.rst @ 1344

Visit:

Revision 1344, 16.0 KB checked in by pablo, 3 years ago (diff)
Updates to the documentation

Rev	Line
[1069]	1	.. _javascriptapi:
	2
[1342]	3	Player API
	4	==========
[1069]	5
[1342]	6	The 5.3 player introduces a new, shorthand javascript API for interacting with your website. This API abstracts any differences between Flash and HTML5; any code you write will work with both technologies.
[1079]	7
[1342]	8	For versions 5.2 and below, the player used the 4.x JavaScript API. A reference for that API can be found on the `player support site <http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v4/12209/javascript-api-reference>`_.
[1079]	9
	10
[1342]	11	Getting started
	12	---------------
[1079]	13
[1344]	14	First, you'll need to upload the API library (jwplayer.js) to your web server. We recommend putting it, along with player.swf, in a folder called jwplayer in the root of your site. Once it's on your web server, add this bit of code to your HTML pages, in the <head> of your page:
[1079]	15
[1104]	16	.. code-block:: html
[1344]	17
	18	<head>
	19	<script type="text/javascript" src="/jwplayer/jwplayer.js"></script>
	20	</head>
	21
	22	To get a sense of the possibilities of what you can do with the API, here's a quick example that showcases how to control the player from the page:
	23
	24	.. code-block:: html
[1342]	25
	26	<div id="container">Loading the player ...</div>
	27
	28	<script type="text/javascript">
	29	jwplayer("container").setup({
[1344]	30	flashplayer: "/jwplayer/player.swf",
[1342]	31	file: "/uploads/video.mp4",
	32	height: 270,
	33	width: 480
	34	});
	35	</script>
	36
	37	<ul>
	38	<li onclick="jwplayer().play()">Start the player</li>
	39	<li onclick="alert(jwplayer().getPosition())">Get current position</li>
	40	</ul>
[1104]	41
[1342]	42	Of course it's also possible to have the player manipulate the page. Here's a second example, using the :ref:`event block <embed_events>` of the JW Player embedder:
[1104]	43
[1079]	44	.. code-block:: html
[1342]	45
	46	<div id="container">Loading the player ...</div>
	47
	48	<script type="text/javascript">
	49	jwplayer("container").setup({
[1344]	50	flashplayer: "/jwplayer/player.swf",
[1342]	51	file: "/uploads/video.mp4",
	52	height: 270,
	53	width: 480,
	54	events: {
	55	onComplete: function() {
	56	document.getElementById("status").innerHTML("That's all folks!");
	57	}
	58	}
	59	});
	60	</script>
	61
	62	<p id="status"></p>
[1079]	63
[1342]	64	The following sections give a detailed description of the JW Player API, describing how to:
[1079]	65
[1342]	66	* Select a player.
	67	* Get variables from a player.
	68	* Call functions on a player.
	69	* Listen to events from a player.
[1079]	70
[1344]	71	Embedding with SWFObject
	72	++++++++++++++++++++++++
[1079]	73
[1344]	74	If you embed the player using SWFObject, rather than the built-in setup() function, you can still use the JavaScript API, although you'll need to wait for Flash to be loaded on the page before interacting with the API. SWFObject 2.2 includes a callback function (in this example, named flashLoaded) which is executed when SWFObject has finished embedding Flash into the page. Make sure you wait until this function is called before making any calls to the API.
	75
	76	Here's a simple example of using the `SWFObject callback <http://code.google.com/p/swfobject/wiki/api>`_:
	77
	78	.. code-block:: javascript
	79
	80	var flashvars = { file:"/videos/video.mp4" };
	81	var params = { allowfullscreen:"true", allowscriptaccess:"always" };
	82	var attributes = { id:"player", name:"player" };
	83
	84	swfobject.embedSWF("/jwplayer/player.swf", "container", 320, 240, "9.0.115", "false",
	85	flashvars, params, attributes, flashLoaded);
	86
	87	function flashLoaded(e) {
	88	// e.ref is a reference to the Flash object. We'll pass it to jwplayer() so the API knows where the player is.
	89
	90	// Add event listeners
	91	jwplayer(e.ref).onReady(function() { alert("Player is ready"); });
	92	jwplayer(e.ref).onPlay(function() { alert("Player is playing"); });
	93
	94	// Interact with the player
	95	jwplayer(e.ref).play();
	96	}
	97
	98	Embedding with an <object> or <embed> tag
	99	+++++++++++++++++++++++++++++++++++++++++
	100
	101	If you embed the player directly using an <object> or <embed> tag, simply pass your tag's id to the API when referencing the player:
	102
	103	.. code-block:: html
	104
	105	<embed
	106	id="player"
	107	name="player"
	108	src="/jwplayer/player.swf"
	109	width="320"
	110	height="240"
	111	allowscriptaccess="always"
	112	allowfullscreen="true"
	113	flashvars="file=/videos/video.mp4"
	114	/>
	115
	116	<script type="text/javascript">
	117	jwplayer("player").onReady(function() { alert("Player is ready"); });
	118	jwplayer("player").onPlay(function() { alert("Player is playing"); });
	119	jwplayer("player").play();
	120	</script>
	121
[1342]	122	Selecting
	123	---------
[1079]	124
[1342]	125	The first thing you need to do when attempting to interact with a JW Player, is to get a reference to it. The easiest way, probably sufficient for 95% of all use cases is this:
[1079]	126
[1342]	127	.. code-block:: javascript
[1079]	128
[1342]	129	// Start the player on this page
	130	jwplayer().play();
[1079]	131
	132
[1342]	133	Only when you have multiple players on a page, you need to be more specific on which player you want to interact with. In that case, there are three ways to select a player:
[1079]	134
[1344]	135	* With the id of the element you :ref:`instantiated <embedding>` the player over:
[1342]	136
	137	.. code-block:: javascript
	138
	139	jwplayer("container").play();
[1079]	140
[1342]	141	* With the actual DOM element itself:
	142
	143	.. code-block:: javascript
	144
	145	var element = document.getElementById("container");
	146	jwplayer(element).play();
[1079]	147
[1342]	148	* With the index in the list of players on the page (in order of loading):
	149
	150	.. code-block:: javascript
	151
	152	jwplayer(2).play();
	153
	154	.. note::
	155
	156	The selector jwplayer(0) is actually the same as jwplayer().
[1079]	157
	158
	159
[1342]	160	Variables
	161	---------
[1079]	162
[1342]	163	Here is a list of all the variables that can be retrieved from the player:
[1079]	164
[1342]	165	.. describe:: getBuffer()
[1079]	166
[1342]	167	Returns the current PlaylistItem's filled buffer, as a percentage (0 to 100) of the total video's length.
	168
	169	.. describe:: getFullscreen()
[1079]	170
[1342]	171	Returns the player's current fullscreen state, as a boolean (true when fullscreen).
[1079]	172
[1342]	173	.. describe:: getMetadata()
[1079]	174
[1342]	175	Returns the current PlaylistItem's metadata, as a javascript object. This object contains arbitrary key:value parameters, depending upon the type of player, media file and streaming provider that is used. Common metadata keys are width, duration or videoframerate.
[1079]	176
[1342]	177	.. describe:: getMute()
[1079]	178
[1342]	179	Returns the player's current audio muting state, as a boolean (true when there's no sound).
[1079]	180
[1342]	181	.. describe:: getPlaylist()
[1079]	182
[1342]	183	Returns the player's entire playlist, as an array of PlaylistItem objects. Here's an example playlist, with three items:
	184
	185	.. code-block:: javascript
	186
	187	[
	188	{ duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" },
	189	{ title: "cool video", file: "/uploads/bbb.mp4" },
	190	{ duration: 542, file: "/uploads/ed.mp4", start: 129 }
	191	]
[1079]	192
[1342]	193	.. describe:: getPlaylistItem(index):
[1079]	194
[1342]	195	Returns the playlist item at the specified index. If the index is not specified, the currently playing playlistItem is returned. The item that is returned is an object with key:value properties (e.g. file, duration and title). Example:
	196
	197	.. code-block:: javascript
	198
	199	{ duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" }
[1079]	200
[1342]	201	.. describe:: getWidth()
[1079]	202
[1342]	203	Returns the player's current width, in pixels.
[1079]	204
[1342]	205	.. describe:: getHeight()
[1079]	206
[1342]	207	Returns the player's current height, in pixels.
[1079]	208
[1342]	209	.. describe:: getState()
[1079]	210
[1342]	211	Returns the player's current playback state. It can have the following values:
	212
	213	* BUFFERING: user pressed play, but sufficient data has to be loaded first (no movement).
	214	* PLAYING: the video is playing (movement).
	215	* PAUSED: user paused the video (no movement).
	216	* IDLE: either the user stopped the video or the video has ended (no movement).
[1079]	217
[1342]	218	.. describe:: getPosition()
[1079]	219
[1342]	220	Returns the current playback position in seconds, as a number.
[1079]	221
[1342]	222	.. describe:: getDuration()
[1079]	223
[1342]	224	Returns the currently playing PlaylistItem's duration in seconds, as a number.
[1079]	225
[1342]	226	.. describe:: getVolume()
[1079]	227
[1342]	228	Returns the current playback volume percentage, as a number (0 to 100).
[1079]	229
	230
	231
[1342]	232	Functions
	233	---------
[1120]	234
[1342]	235	Here is a list of all functions that can be called on the player:
[1120]	236
[1342]	237	.. describe:: setFullscreen(state)
[1120]	238
[1342]	239	Change the player's fullscreen mode. Parameters:
	240
	241	* state:Boolean (undefined): If state is undefined, perform a fullscreen toggle. Otherwise, set the player's fullscreen mode to fullscreen if true, and return to normal screen mode if false.
[1120]	242
[1342]	243	.. describe:: setMute(state)
[1079]	244
[1342]	245	Change the player's mute state (no sound). Parameters:
[1079]	246
[1342]	247	* state:Boolean (undefined): If state is undefined, perform a muting toggle. Otherwise, mute the player if true, and unmute if false.
[1079]	248
[1342]	249	.. describe:: load(playlist)
[1079]	250
[1342]	251	Loads a new playlist into the player. The playlist parameter is required and can take a number of forms:
	252
	253	* Array: If an array of PlaylistItem objects is passed, load an entire playlist into the player. Example:
	254
	255	.. code-block:: javascript
	256
	257	[
	258	{ duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" },
	259	{ title: "cool video", file: "/uploads/bbb.mp4" },
	260	{ duration: 542, file: "/uploads/ed.mp4", start: 129 }
	261	]
[1079]	262
[1342]	263	* Object: If a PlaylistItem is passed, load it as a single item into the player. Example:
	264
	265	.. code-block:: javascript
	266
	267	{ duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" },
	268
	269	* String: Can be an XML playlist, or the link to a single media item (e.g. an MP4 video).
[1079]	270
[1342]	271	.. describe:: playlistItem(index)
[1079]	272
[1342]	273	Jumps to the playlist item at the specified index. Parameters:
	274
	275	* index:Number: zero-based index into the playlist array (i.e. playlistItem(0) jumps to the first item in the playlist).
[1079]	276
[1342]	277	.. describe:: playlistNext()
[1079]	278
[1342]	279	Jumps to the next playlist item. If the current playlist item is the last one, the player jumps to the first.
[1079]	280
[1342]	281	.. describe:: playlistPrev()
[1079]	282
[1342]	283	Jumps to the previous playlist item. If the current playlist item is the first one, the player jumps to the last.
[1079]	284
[1342]	285	.. describe:: resize(width, height)
[1079]	286
[1342]	287	Resizes the player to the specified dimensions. Parameters:
	288
	289	* width:Number: the new overall width of the player.
	290	* height:Number: the new overall height of the player.
	291
	292	.. note::
	293
	294	If a controlbar or playlist is displayed next to the video, the actual video is of course smaller than the overall player.
[1079]	295
[1342]	296	.. describe:: play(state)
[1079]	297
[1342]	298	Toggles playback of the player. Parameters:
	299
	300	* state:Boolean (undefined): if set true the player will start playing. If set false the player will pause. If not set, the player will toggle playback.
[1079]	301
	302
[1342]	303	.. describe:: pause(state)
[1079]	304
[1342]	305	Toggles playback of the player. Parameters:
	306
	307	* state:Boolean (undefined): if set true the player will pause playback. If set false the player will play. If not set, the player will toggle playback.
	308
	309	.. describe:: stop()
[1079]	310
[1342]	311	Stops the player and unloads the currently playing media file from memory.
[1079]	312
[1342]	313	.. describe:: seek(position)
[1079]	314
[1342]	315	Jump to the specified position within the currently playing item. Parameters:
[1079]	316
[1342]	317	* position:Number: Requested position in seconds.
[1079]	318
[1342]	319	.. describe:: setVolume(volume)
[1079]	320
[1342]	321	Sets the player's audio volume. Parameters:
	322
	323	* volume:Number: The new volume percentage; 0 and 100.
[1079]	324
	325
	326
[1342]	327	Events
	328	------
[1079]	329
[1342]	330	Here is a list of all events the player supports. In javascript, you can listen to events by assigning a function to it. Your function should take one argument (the event that is fired). Here is a code example, with some javascript that listens to changes in the volume:
[1079]	331
[1342]	332	.. code-block:: javascript
	333
	334	jwplayer("container").onVolume(
	335	function(event) {
	336	alert("the new volume is: "+event.volume);
	337	}
	338	);
[1079]	339
[1344]	340	Note that our :ref:`official embed method <embedding>` contains a shortcut for assigning event listeners, directly in the embed code:
[1079]	341
[1342]	342	.. code-block:: html
	343
	344	<div id="container">Loading the player ...</div>
	345
	346	<script type="text/javascript">
	347	jwplayer("container").setup({
[1344]	348	flashplayer: "/jwplayer/player.swf",
[1342]	349	file: "/uploads/video.mp4",
	350	height: 270,
	351	width: 480,
	352	events: {
	353	onVolume: function(event) {
	354	alert("the new volume is: "+event.volume);
	355	}
	356	}
	357	});
	358	</script>
[1079]	359
	360
[1342]	361	And here's the full event list:
[1120]	362
[1342]	363	.. describe:: onBufferChange(callback)
[1120]	364
[1342]	365	Fired when the currently playing item loads additional data into its buffer. Event attributes:
[1079]	366
[1342]	367	* percent: Number: Percentage (between 0 and 100); number of seconds buffered / duration in seconds.
[1079]	368
[1342]	369	.. describe:: onBufferFull(callback)
[1079]	370
[1342]	371	Fired when the player's buffer has exceeded the player's bufferlength property (default: 1 second). No attributes.
[1079]	372
[1342]	373	.. describe:: onError(callback)
[1079]	374
[1342]	375	Fired when an error has occurred in the player. Event attributes:
[1079]	376
[1342]	377	* message: String: The reason for the error.
[1079]	378
[1342]	379	.. describe:: onFullscreen(callback)
[1079]	380
[1342]	381	Fired when the player's fullscreen mode changes. Event attributes:
	382
	383	* fullscreen: boolean. New fullscreen state.
[1079]	384
[1342]	385	.. describe:: onMetadata(callback)
[1079]	386
[1342]	387	Fired when new metadata has been discovered in the player. Event attributes:
[1079]	388
[1342]	389	data: Object: dictionary object containing the new metadata.
[1079]	390
[1342]	391	.. describe:: onMute(callback)
[1079]	392
[1342]	393	Fired when the player has gone into or out of the mute state. Event attributes:
[1079]	394
[1342]	395	* mute: Boolean: New mute state.
[1079]	396
[1342]	397	.. describe:: onPlaylist(callback)
[1079]	398
[1342]	399	Fired when a new playlist has been loaded into the player. Event attributes:
	400
	401	* playlist: Array: The new playlist; an array of PlaylistItem objects.
[1079]	402
[1342]	403	.. describe:: onPlaylistItem(callback)
[1079]	404
[1342]	405	Fired when the player is playing a new media item. Event attributes:
[1079]	406
[1342]	407	* index Number: Zero-based index into the playlist array (e.g. 0 is the first item).
[1079]	408
[1342]	409	.. describe:: onReady(callback)
[1079]	410
[1342]	411	Fired when the player has initialized and is ready for playback. No attributes.
[1079]	412
[1342]	413	.. describe:: onResize(callback)
[1079]	414
[1342]	415	Fired when the player's dimensions have changed (the player is resizing or switching fullscreen). Event attributes:
[1079]	416
[1342]	417	* width: Number: The new width of the player.
	418	* height: Number: The new height of the player.
[1079]	419
[1342]	420	.. describe:: onPlay(callback)
[1120]	421
[1342]	422	Fired when the player enters the PLAYING state. Event attributes:
[1120]	423
[1342]	424	* oldstate: String: the state the player moved from. Can be PAUSED or BUFFERING.
[1079]	425
[1342]	426	.. describe:: onPause(callback)
[1079]	427
[1342]	428	Fired when the player enters the PAUSED state. Event attributes:
[1079]	429
[1342]	430	* oldstate: String: the state the player moved from. Can be PLAYING or BUFFERING.
[1079]	431
[1342]	432	.. describe:: onBuffer(callback)
[1079]	433
[1342]	434	Fired when the player enters the BUFFERING state. Event attributes:
[1079]	435
[1342]	436	* oldstate: String: the state the player moved from. Can be PLAYING, PAUSED or IDLE.
[1079]	437
[1342]	438	.. describe:: onIdle(callback)
[1079]	439
[1342]	440	Fired when the player enters the IDLE state. Event attributes:
[1079]	441
[1342]	442	* oldstate: String: the state the player moved from. Can be PLAYING, PAUSED or BUFFERING.
[1079]	443
[1342]	444	.. describe:: onComplete(callback)
[1079]	445
[1342]	446	Fired when the player has finished playing the current media. No event attributes.
[1079]	447
[1342]	448	.. describe:: onPosition(callback)
[1079]	449
[1342]	450	When the player is playing, fired as the playback position gets updated. This happens with a resolution of 0.1 second, so there's a lot of events! Event attributes:
[1079]	451
[1342]	452	* duration: Number: Duration of the current item in seconds.
	453	* offset: Number: When playing streaming media, this value contains the last unbuffered seek offset.
	454	* position: Number: Playback position in seconds.
[1079]	455
[1342]	456	.. describe:: onVolume(callback)
[1079]	457
[1342]	458	Fired when the player's volume changes. Event attributes:
[1079]	459
[1342]	460	* volume: Number: The new volume percentage (0 to 100).
[1079]	461
	462
	463
[1342]	464	Chaining
	465	--------
[1079]	466
[1342]	467	Note that every API call to a JW Player in turn returns the player instance. This makes it possible to chain API calls (like with `jQuery <http://jquery.net>`_):
[1079]	468
[1342]	469	.. code-block:: javascript
[1079]	470
[1342]	471	jwplayer().setVolume(50).onComplete(function(){ alert("done!"); }).play();
[1079]	472
	473

Note: See TracBrowser for help on using the repository browser.

Download in other formats: