cacaoweb Javascript API for websites

You can use cacaoweb Javascript API to integrate and interact cacaoweb content in your websites, like videos, files or music. For example, you can serve your users videos from file hosting services without time limit or videos from cacaoweb in HD quality, using our simple javascript interface.

Requirements
Getting started
API functions reference
Examples
HTML embed code without the JS API

API description

Requirements

As cacaoweb javascript API relies on javascript, javascript needs to be enabled in the browser.

You need to include our javascript API in your HTML page. To download our API, click here (cacaoweb-2.18.js). You need to include this file in your webpage at the end of the <body> with the following html code:

<script src="cacaoweb-2.18.js"></script>

All the examples below are defined in HTML5 syntax, please adapt the syntax if you need to support older browsers.

Getting started

Playing a video

Here is all that’s needed to play a video link in a webpage.

<html>
<body>

	<div id="mymovie" cacaolink="http://127.0.0.1:4001/?f=25614a53c9bcd3c537bb28a11174785f"></div>

	<script src="cacaoweb-2.18.js"></script>
	<script>		
		cacaoplayer("mymovie").play(); // plays the block with id "mymovie"
	</script>
</body>
</html>

Explanation:

The <div> part (the “cacaoweb block”) is where the video will be played. As you can see it is just a empty div block with 2 properties:

id : to give a name to this cacaoweb block so you can reference it later in your javascript code
(optional) cacaolink : tell which link should be played by default (it can be replaced by something else in subsequent API calls)

At the end of the body, we added a script tag to include the cacaoweb API (cacaoweb-2.16.js), then we call an API function (play) on the previous cacaoweb block. This will play a video.

cacaoplayer(“mymovie”) selects or create a player object that will be inside the div block.

cacaoplayer(“mymovie”).play() plays the video.

API functions reference

Integrating with cacaoweb

The javascript “Cacaoweb” global object exposes a few functions to help you integrate cacaoweb content easily. For example, a common requirement is to be able to detect whether cacaoweb is running on the user’s computer or not. If it’s not, we can prompt the user with a download button or image, for example we can replace the player by a “missing plugin” image, inviting the user to download and launch cacaoweb.

/** 
 * to find out whether cacaoweb is running on the host machine 
 * your callback_function will be like:
 *   function mycallback(cacaowebstatus) {
 *     ...
 *   }
 * the parameter "cacaowebstatus" will be set by the cacaoweb API to one out of 3 possible values:
 *   - "On" (cacaoweb is running on the user's computer)
 *   - "Off" (cacaoweb is not running on the user's computer)
 *   - "Unknown" (we don't know if cacaoweb is running yet - 
         it can take up to 2 sec to know whether cacaoweb is running or not)
 **/
Cacaoweb.subscribeStatusChange(callback_function);

/** downloads cacaoweb (to use if the user doesn't have cacaoweb installed, 
    you can check the status in your callback from Cacaoweb.subscribeStatusChange(yourcallbackfunction) */
Cacaoweb.download();

Global API parameters

These parameters will apply globally to all the videos, but can be changed separately for each video. We also provide the default values of these parameters below.

Cacaoweb.videowidth = 640; /** width of the player */
Cacaoweb.videoheight = 360; /** height of the player */
Cacaoweb.autoplay = true; /** whether the video plays without the user pressing the play button */
/** the image showing up in place of the player when cacaoweb is not installed on the host computer */
Cacaoweb.missingpluginimage = 'http://www.cacaoweb.org/images/plugin.png'; 
/** the path to the player, you can change this if you want to have your own player */
Cacaoweb.playerurl = 'http://127.0.0.1:4001/player.swf';

These properties can be changed at any time after the cacaoweb javascript API is loaded.

Playing videos

This is the most important part. But before we introduce the API, let’s have a look at the format of the link that you need to feed cacaoweb with. Depending on where the video is hosted, a different link format will apply, as explained below.

Links format

cacaoweb can plays videos from cyberlockers like putlocker while removing the time limits, to do this you need to translate the links to the cacaoweb format using the following conversion table:

provider	link	cacaoweb format
Putlocker	`http://putlocker.com/file/PTHE7UWL`	`http://127.0.0.1:4001/putlocker/putlocker.caml?videoid=PTHE7UWL`
cacaoweb		`http://127.0.0.1:4001/?f=25614a53c9bcd3c537bb28a11174785f`

API functions to control the flash player

There are just a few fonctions to control the player, as shown below:

cacaoplayer("yourmovie"); // references the player object in div "yourmovie"
cacaoplayer("yourmovie").play(); // plays the link given be property "cacaolink"
cacaoplayer("yourmovie").play("http://127.0.0.1:4001/?f=25614a53c9bcd3c537bb28a11174785f"); // play this link
cacaoplayer("yourmovie").pause(); // pause playback
cacaoplayer("yourmovie").mute(); // mute the sound volume
cacaoplayer("yourmovie").showmessage("welcome"); // shows a message in the player
cacaoplayer("yourmovie").seek(180); // seeks playback
var currentposition = cacaoplayer("yourmovie").position(); // get current playback position

Before you play a link, you can change the player parameters for this link, like with the following:

// setup player options
cacaoplayer("yourmovie").setup({ autoplay : true, width : 640, height : 360 });

When you call the setup fonction, each parameter is optional. We don’t describe the meaning of these parameters as their name is already self-explanatory

Add subtitles to videos

You can add any subtitles to a video. For example, if your subtitles file is located at address http://127.0.0.1:4001/?f=39bf73af7297076afd6f67c0b74879c7 and the subtitle is desynchronized with the video of 1.8s, you can use:

// setup the subtitles:
cacaoplayer("yourmovie").subtitles({ subtitlesurl : 
      "http://127.0.0.1:4001/?f=39bf73af7297076afd6f67c0b74879c7", subtitleslanguage : 'it', 
      subtitlesoffset : 1.8 });
// simplified syntax if the offset is 0s and you don't plan to add other languages:
cacaoplayer("yourmovie").subtitles({ 
             subtitlesurl : "http://127.0.0.1:4001/?f=39bf73af7297076afd6f67c0b74879c7" });

Here we added 3 parameters:

subtitlesurl: specify the url of the subtitle (usually in .srt format)
subtitleslanguage (optional): the language code of the subtitle
subtitlesoffset (optional): the synchronisation offset between the audio track and the subtitles in seconds. If they are synchronised, there is no need to provide this parameter.

Examples

Tell if cacaoweb is running on the host machine:

<html>
<body>

	<script src="cacaoweb-2.15.js"></script>
	<script>		
		Cacaoweb.subscribeStatusChange(function(status){ 
			if (status == 'Off') {
				alert('cacaoweb is not installed');
			} else if (status == 'On') {
				alert('cacaoweb is installed');
			} else if (status == 'Unknown') {
				alert('cacaoweb status is unknown');
			}
		});
	</script>
</body>
</html>

Add subtitles to a video and play it:

<html>
<body>

	<div id="mymovie" cacaolink="http://127.0.0.1:4001/?f=25614a53c9bcd3c537bb28a11174785f"></div>

	<script src="cacaoweb-2.15.js"></script>
	<script>		
		cacaoplayer("mymovie").subtitles({ subtitlesurl : 
		    "http://127.0.0.1:4001/?f=39bf73af7297076afd6f67c0b74879c7" });
		cacaoplayer("mymovie").play();

		// Note: the call to .subtitles() can be made at any time, 
		// before or after the call to .play()
	</script>
</body>
</html>

Play Different Content in a Playlist:

The javascript API functions can be called within HTML code like the following:

<html>
<body>

	<div id="mymovie" ></div>

	<script src="cacaoweb-2.15.js"></script>

	<ul>
	<li><a href="#" 
	onclick="cacaoplayer("mymovie").play('http://127.0.0.1:4001/?f=25614a53c9bcd3c537bb28a11174785f')">
		Some movie
	</a></li>
	<li><a href="#" 
	onclick="cacaoplayer("mymovie").play('http://127.0.0.1:4001/?f=5c007d83103df2a6229249a6df666f67')">
		Other movie
	</a></li>
	<li><a href="#" 
	onclick="cacaoplayer("mymovie").play('http://127.0.0.1:4001/?f=25614a53c9bcd3c537bb28a11174785f')">
		Another one
	</a></li>
	</ul>

</body>
</html>

Bypassing the API – inserting Flash embed code directly

You don’t need to use our javascript API to power your website with cacaoweb. If you want to do things your way, here is how it would go:

Flash embed code for cacaoweb links

<object width="640" height="360">
	<param name="allowFullScreen" value="true" />
	<param name="flashvars" value="file=http://127.0.0.1:4001/?f=5c007d83103df2a6229249a6df666f67" />
	<param name="movie" value="http://127.0.0.1:4001/player.swf" />
	<param name="AllowScriptAccess" value="always">
	<param name="wmode" value="direct">
	<embed src="http://127.0.0.1:4001/player.swf" 
          flashvars="http://127.0.0.1:4001/?f=5c007d83103df2a6229249a6df666f67" 
          width="640" height="360" allowFullScreen="true" AllowScriptAccess="always" 
          wmode="direct" type="application/x-shockwave-flash" />
</object>

The cacaoweb link is in “flashvars”. Simply insert the embed code in your webpage with the relevant cacaoweb link and you’re ready.

You also may want to check if cacaoweb is installed on the user’s computer, and prompt him with a download button for cacaoweb if it’s not. You can check in Ajax whether cacaoweb is installed simply by requesting a page like http://127.0.0.1:4001/isrunning, if cacaoweb is installed then the success method will be called back immediately.

Flash embed code with subtitles

You can add subtitles to your videos directly by change the “flashvars” item like in the following embed code:

<object width="640" height="360">
	<param name="allowFullScreen" value="true" />
	<param name="flashvars" value="file=http://127.0.0.1:4001/?f=5c007d83103df2a6229249a6df666f67&subtitlesurl=
	http://127.0.0.1:4001/hash_of_your_subtitles_file&subtitleslanguage=it&subtitlesoffset=1.5" />
	<param name="movie" value="http://127.0.0.1:4001/player.swf" />
	<param name="AllowScriptAccess" value="always">
	<param name="wmode" value="direct">
	<embed src="http://127.0.0.1:4001/player.swf" 
          flashvars="file=http://127.0.0.1:4001/?f=5c007d83103df2a6229249a6df666f67&subtitlesurl=
		  http://127.0.0.1:4001/hash_of_your_subtitles_file&subtitleslanguage=it&subtitlesoffset=1.5" 
          width="640" height="360" allowFullScreen="true" AllowScriptAccess="always" 
          wmode="direct" type="application/x-shockwave-flash" />
</object>

The parameters used – subtitlesurl, subtitleslanguage, subtitlesoffset – are the same as in the API defined earlier.

Documentation