DivX Web Developer Guide

The DivX Plus Web Player plug-in gives any webmaster a simple and hassle-free mechanism for offering DivX (DivX/AVI) and DivX Plus HD (MKV/H.264) videos for immediate download and playback on their website by simply hosting the video file and editing some HTML tags.


The DivX Plus Web Player plug-in works by being downloaded and installed on each of your visitor’s computer when they browse a page that contains an embedded a DivX video, and is distributed for free by DivX - saving you the trouble of hosting the plug-in yourself or having to pay for the bandwidth of its download.

All you need to have to get started on your end is a DivX Plus (.mkv) or DivX (.divx or .avi) file and some HTML code, or if you're looking for more customization, you can interact with the DivX Plus Web Player using JavaScript.Click through the topics below, or download the PDF version.

AttachmentSize
DivX Web Player Embedding Guide.pdf861.76 KB

Simple Example

For this simple example, we’ll assume that you have a DivX video file named movie.divx and that you are creating an HTML page named movie.html to host it. We will also assume that those two files will be uploaded to your web server in the same destination folder. Finally we will assume that the video resolution of the movie.divx file is 320x240 pixels.

All you need to add inside the <body> tag of your movie.html file is the following block of code:

<object classid="clsid:67DABFBF-D0AB-41fa-9C46-CC0F21721616"
    width="320" height="260"
    codebase="http://go.divx.com/plugin/DivXBrowserPlugin.cab">
    <param name="src" value="movie.divx"/>
    
    <embed
        type="video/divx"
        src="movie.divx"
        width="320" height="260"
        pluginspage="http://go.divx.com/plugin/download/">
    </embed>
</object>

The explanation of the different tags and parameters of this block of code is as follows:

  • The first, outer <object/> tag is used by Internet Explorer to display the plug-in. It has a set of required direct parameters and also uses inner <param> tags to specify optional parameters.
  • The second, inner <embed/> tag is used by all other supported browsers (such as Mozilla Firefox) and does not need any sub tags. The <embed> tag needs to be inside the <object> tag for this code to work in all browsers at once.

Both of these tags must be present, even though this way some parameters are repeated, in order for the plug-in to appear and function in all supported browsers.

Here is a detailed list and explanation of the required parameters of each tag:

Object tag parameters:

  • classid: The classid parameter is required to identify the plug-in that is needed when using Internet Explorer and its value must be set to exactly "clsid:67DABFBF-D0AB-41fa-9C46-CC0F21721616".
  • width and height: The width and height parameters are required. They determine how much space is allocated on the HTML page for the plug-in control. By default, the DivX Browser Plug-In displays a bar of playback controls that is 20 pixels high at the bottom of the video area. Therefore, in our example, we must allocate an area of 320x260 pixels to host our 320x240 pixels video. As a summary: With the default skin mode settings, the width parameter should always equal the width of the video file while the height parameter should equal the height of the video plus an additional 20 pixels so that the original aspect ratio of your video is maintained.
  • codebase: The codebase parameter is required and must be set to exactly "http://go.divx.com/plugin/DivXBrowserPlugin.cab". This tag is used by Internet Explorer to do an automatic dowthe client computer when it is missing.

Object sub-tag parameter: <param name="src" … >

  • The <param> tag with a name of src is used by Internet Explorer to locate the video that the plug-in control needs to download and play. Here its value is set to movie.divx.

Embed tag parameters:

  • type: The type parameter is used to identify the plug-in that is required when using mozilla-based browsers and should be set to exactly "video/divx".
  • src: The src parameter is used to locate the video file that the plugin should download and play. In our case it is set to movie.divx again.
  • width and height: The width and height parameters are used the same way here as in the <object> tag and therefore set to the same values.
  • pluginspage: The pluginspage parameter is used by mozilla-based browsers to locate a web page where the plug-in can be downloaded when it is not currently installed on the client machine. It is required for proper functioning and must be set to exactly "http://go.divx.com/plugin/download/".

This is all you need to add to your HTML to obtain a web page that downloads and plays DivX video.

Web Server Configuration

Supported web servers

  • Apache 2.2+
  • Microsoft IIS 6.0+

Supported HTTP protocols

  • HTTP 1.0 and 1.1 are supported
  • HTTP 1.1 with byte range requests is required for DivX Plus (.mkv) playback or advanced seeking

Note:
HTTPS and HTTP authentication (i.e. http://user:password@www.yourvideosite.com) are not supported.

Web server MIME type configuration

Proper MIME type configuration is essential for client-side plug-in discovery to function in Firefox

File Extension MIME Type
.divx video/divx
.avi video/divx
.mkv video/divx

Apache MIME type configuration instructions:

Create or add the text below to your Apache server’s root .htaccess file:

AddType video/divx .divx
AddType video/divx .avi
AddType video/divx .mkv

More information on Apache MIME types and .htaccess files can be found here:
http://httpd.apache.org/docs/2.2/mod/mod_mime.html#addtype
http://www.htaccess-guide.com/index.php?a=11
http://www.google.com/search?hl=en&q=htaccess%20addtype

Microsoft IIS MIME type configuration instructions:

Instructions for adding MIME types for Microsoft IIS

Supported Browsers

DivX Plus Web Player supports the following web browsers:

Windows 7/Vista/XP:

  • Internet Explorer (6.0 or higher)
  • Firefox (3.5 or higher)
  • Google Chrome (1.0 or higher)

Mac OS X 10.5, 10.6, 10.7 and 10.8:

  • Safari (4.0 or higher)
  • Firefox (3.5 or higher)
  • Google Chrome (1.0 or higher)

Supported Formats

DivX Web Player supports the standard DivX format (.divx and .avi), the H.264-based DivX Plus (.mkv) video format, and the MP4 (.mp4 .m4v and .mov) format. We recommend publishing in DivX Plus as our H.264 codec will allow you to deliver better quality video at a lower bitrate than standard DivX.

DivX Plus Format Support

Container:

  • .mkv

Video:

  • Codec: H.264 / AVC & ASP
  • Maximum Resolution: 1920x1080

Audio:

  • Codec: AAC & MP3 (AC3 & DTS with AC3 Filter/Perian installed)
  • Channels: 2 or 5.1
  • Suggested bitrate: 32kbits per channel

Subtitles:

  • Formats: SRT, SSA

DivX Format Support

Container:

  • .divx
  • .avi

Video:

  • Codec: DivX (MPEG-4 ASP)
  • Maximum Resolution: 1920x1080

Audio:

  • Codec: MP3
  • Channels: 2
  • Suggested bitrate: 128kbps

Subtitles:

  • Formats: DivX XSub, SRT, SSA

MP4 Format Support

Container:

  • .mp4 .m4v .mov

Video:

  • Codec: H.264 / AVC & ASP
  • Maximum Resolution: 1920x1080

Audio:

  • Codec: AAC & MP3 (AC3 & DTS with AC3 Filter/Perian installed)
  • Channels: 2 or 5.1
  • Suggested bitrate: 32kbits per channel

JavaScript Interaction

The plug-in can be scripted and controlled via JavaScript in all the supported browsers. JavaScript allows you to register callbacks to receive events occurring inside the plug-in as well as to call functions on the plug-in object to perform operations. In order to be able to do so, a couple of parameters must be added to the simple tags shown in the previous section.

Scripting Considerations

In order to access and script the plug-in object from JavaScript code in your HTML page the <object> and <embed> tags must have an additional id parameter giving them unique names for JavaScript to access the objects.

As per the w3c standard,each tag, for example:

<object id="ie_plugin" … >
    <embed id="np_plugin" … ></embed>
</object>

In this case we have named the object tag ie_plugin and the embed tag np_plugin.

The final step required to be able to script the plug-in is to add some code that will determine which plugin object name to use, depending on the browser that is currently using the plug-in. This is done by parsing the “user agent” string that identifies the browser.

In our case, the following code snippet needs to be added at the top of the JavaScript block before trying to call any function on the plugin object:

<script language="Javascript">   
    var plugin;   
    if(navigator.userAgent.indexOf('MSIE')   != -1)   
    {   
        plugin = document.getElementById('ie_plugin');   
    }   
        else   
    {   
        plugin = document.getElementById('np_plugin');   
    }   
</script>

This block of code assigns the correct document object into the variable plugin by detecting whether the current browser is Internet Explorer or Safari, or something else.

After this block of code, the plugin variable can be safely used to call any function of the DivX Browser Plug-In JavaScript API (see below).

Event Callbacks

It is possible to define local JavaScript functions to be used by the plug-in as callbacks when something of importance occurs. The name of these functions must be passed as embedding parameters using both the <param> sub-tags and the <embed> tag so that the plug-in knows to call them when an event occurs in all supported browsers.

The following callback parameters are defined:

statusCallback

This parameter can be used to pass the name of a local JavaScript function that will be called when an event occurs: The function must have the following signature:

function myStatusCallback (event)

In this case “myStatusCallback” is a placeholder for your function name. The event parameter will be a number. The following values are possible:

  • INIT_DONE = 0
  • OPEN_DONE = 1
  • VIDEO_END = 2
  • SHUT_DONE = 3
  • EMBEDDED_START = 4
  • EMBEDDED_END = 5
  • WINDOWED_START = 6
  • WINDOWED_END = 7
  • FULLSCREEN_START = 8
  • FULLSCREEN_END = 9
  • STATUS_PLAYING = 10
  • STATUS_PAUSED = 11
  • STATUS_FF = 12
  • STATUS_RW = 13
  • STATUS_STOPPED = 14
  • BUFFERING_START = 15
  • BUFFERING_STOP = 16
  • DOWNLOAD_START = 17
  • DOWNLOAD_FAILED = 18
  • DOWNLOAD_DONE = 19

timeCallback

This parameter can be used to pass the name of a local JavaScript function that will be called during playback to inform of the current playback time. The function must have the following signature:

function myTimeCallback (time)

In this case “myTimeCallback” is a placeholder for your function name. The time parameter will be a long integer value giving the current playback time in seconds. This function will be called every second.

bufferCallback

This parameter can be used to pass the name of a local JavaScript function that will be called during buffering to inform of the current buffer status. The function must have the following signature:

function myBufferCallback (current, total)

In this case “myBufferCallback” is a placeholder for your function name. The current and total parameters will be long integers containing the current and total amount of data (in bytes) of this buffering stage.

downloadCallback

This parameter can be used to pass the name of a local JavaScript function that will be called during download to inform of the current status. The function must have the following signature:

function myDownloadCallback (current, total)

In this case “myDownloadCallback” is a placeholder for your function name. The current and total parameters will be long integers containing the current and total amount of data (in bytes) of the downloaded video.

JavaScript API

The DivX Plus Web Player supports the following direct JavaScript calls:

Version:

The following function allows querying the plugin version on the end user machine. The return value will be in the form “X.X.X” where X are single digit numbers.

string GetVersion();

Setup:

Those functions can be used to alternatively set all the embedding parameters and take the same parameter values as the corresponding embedding parameters. They take effect immediately (if applicable) or during the next call to the Open() function.

void SetMode(string mode);
void SetAllowContextMenu(boolean allow);
void SetAutoPlay(boolean play);
void SetVolume(unsigned long volume);
void SetPreviewImage(string imageURL);

Media Management:

This function allows opening a new local video file or relative/full URL.

void Open(string URL);

Playback:

void Play();
void Pause();
void Stop();
void Mute();
void UnMute();
void Seek(string method, unsigned long percent); // seeks into the video, method can be “DOWN”, “UP”, or “DRAG” to simulate mouse interaction. Call “DOWN” and “UP” in sequence to perform a full seek.

Windowing:

Windowing

void ShowPreferences(); // shows the preferences panel
void ShowContextMenu(); // shows the contextual menu
void GoEmbedded(); // go back into browser-embedded mode
void GoWindowed(); // go into windowed playback mode
void GoFullscreen(); // go into fullscreen playback mode

Media Information:

These calls can only return valid data once the “OPEN_DONE” callback event has been sent by the plug-in. Otherwise the return values are undefined.

unsigned long GetTotalTime(); // in seconds
unsigned long GetVideoWidth(); // in pixels
unsigned long GetVideoHeight(); // in pixels
unsigned long GetNumberOfAudioTracks();
unsigned long GetNumberOfSubtitleTracks();
long GetCurrentAudioTrack(); // returns the index of the currently playing audio track (or -1 if no audio track is selected)<
long GetCurrentSubtitleTrack(); // returns the index of the currently playing subtitle track (or -1 if no subtitle track is selected)
string GetAudioTrackName(unsigned long trackIndex); // returns a readable track name for audio track “trackIndex” (which must be between 0 and trackCount-1)
string GetSubtitleTrackName(unsigned long trackIndex); // returns a readable track name for subtitle track “trackIndex” (which must be between 0 and trackCount-1)
string GetAudioTrackLanguage(unsigned long trackIndex); // returns the twochar ISO 859 language code of audio track “trackIndex” (which must be between 0 and trackCount-1)
string GetSubtitleTrackLanguage(unsigned long trackIndex); // returns the twochar ISO 859 language code of subtitle track “trackIndex” (which must be between 0 and trackCount-1)

Media Management:

These calls can be successful once the “OPEN_DONE” callback event has been sent by the plug-in for the current video.

void SetCurrentAudioTrack(long index); // sets the currently playing audio track to the audio track at index “index” (pass -1 if you want no audio track to be selected)
void SetCurrentSubtitleTrack(long index); // sets the currently playing subtitle track to the subtitle track at index “index” (pass -1 if you want no subtitle track to be selected)

Preventing Downloads

If you want to prevent DivX Plus Web Player from saving the downloaded video file onto the end user’s hard drive, you can simply name your video file so that its filename on your web server ends with “_ns” (for “no save”) just before the .divx extension and update your HTML code to reference this filename.

Examples: myvideo_ns.divx or trailer_ns.divx.

In this case DivX Plus Web Player will still download the file contents for playback but will not allow the end user to save the full file on disk.

Embedding Parameters

Each of the following embedding parameters allow you to customize the appearance and behavior of the DivX Plus Web Player plug-In. Each of them must be specified twice for them to take effect in all supported browsers, once in the <object> tag as a <param> sub-tag, and once in the <embed> tag directly.

Parameters

allowContextMenu

The allowContextMenu parameter is used to specify whether the plugin should display a contextual (right-click) menu when the user presses the right mouse button or the menu buttons on the skin.

You may wish to disable the contextual menu to provide your own controls on the page.

Usage:

  • In the object tag: <param name="allowContextMenu" value="[value]"> 
  • In the embed tag: allowContextMenu="[value]"

Possible values:

  • "true" or "false", true being the default.

autoPlay

The autoPlay parameter is used to specify whether the plugin should start downloading and buffering immediately or if it should wait for a JavaScript call or for the user to click on the Play button so start doing so.

Usage:

  • In the object tag: <param name="autoPlay" value="[value]"> 
  • In the embed tag: autoPlay="[value]"

Possible values:

  • "true" or "false", true being the default.

bannerEnabled

UPDATE – 4/7/2010This parameter is under maintenance and may not function desirably. We recommended removing this parameter from your embed code until further notice.

The bannerEnabled parameter is used to specify whether the plugin should display the DivX advertisement banner at the end of playback.

Usage:

  • In the object tag: <param name="bannerEnabled" value="[value]"> 
  • In the embed tag: bannerEnabled="[value]"

Possible values:

  • "true" or "false", true being the default.

bufferingMode

The bufferingMode parameter is used to specify how the plug-in should buffer downloaded data before attempting to start playback.

Usage:

  • In the object tag: <param name="bufferingMode" value="[value]"> 
  • In the embed tag: bufferingMode="[value]"

Possible values:

  • null: In this mode, the plug-in does only very minimal buffering and starts playing as soon as data is available. It will not guarantee a very good user experience unless you know that their connection is very fast.
  • auto: This is the default value. In this mode, the plug-in analyses the download speed and tries to buffer just enough so that uninterrupted progressive playback can happen at the end of the buffer period.
  • full: In this mode, the plugin will always buffer the full video file before starting playback.

loop

The loop parameter is used to specify whether the plugin should play the video in a loop or stop video playback when the end of the file is reached.

Usage:

  • In the object tag: <param name="loop" value="[value]">
  • In the embed tag: loop="[value]"

Possible values:

  • "true" or "false", false being the default.

minVersion

The minVersion parameter is used to specify a minimum version number of the DivX Browser Plug-In that is required to play the embedded video.

This parameter can be used to force an upgrade of the client computer when your web page explicitly relies on a specific version of the DivX Browser Plug-In to playback the video. If the end user refuses to upgrade, the video will not download or play.

Usage:

  • In the object tag: <param name="minVersion" value="[value]"> 
  • In the embed tag: minVersion="[value]"

Possible values:

  • A 3-digit, dot-separated, text string specifying the minimum version number required, such as "1.0.3" or "2.0.0".

mode

The mode parameter is used to specify which skin mode the plugin should use to display playback controls. Several modes are provided from showing no controls at all to showing a full-featured playback panel.

Usage:

  • In the object tag: <param name="mode" value="[value]">
  • In the embed tag: mode="[value]"

Possible values:

  • null: In this mode, the plug-in shows absolutely no controls. The usual width and height parameters should then be set to the exact width and height of the video file. 
  • mini: This is the default. In this mode, the plugin shows a more elaborate controls bar that is 30 pixel high at the bottom of the video area. The usual width and height parameters should then be set to the exact width of the video and the height of the video plus 30 pixels.

movieTitle

The movieTitle parameter is useful if your videos don’t have user friendly file names such as “112356.divx” or “gr8t_vidz_1324.avi” as it allows to give a title to your video that is used by the DivX Web Player when showing UI elements and when users wants to save the video file to their Hard Disk.

If you set movieTitle to “My Great Video” then your video file will be saved on each user’s computers as “My Great Video.divx”.

Usage:

  • In the object tag:  <param name="movieTitle" value="[value]"> 
  • In the embed tag:  movieTitle="[value]"

Possible values:

  • Any text that is a valid cross-platform filename such as "My Video" or “My Great Movie”.

previewImage

The previewImage parameter is used to specify the location of an image file in PNG, JPEG or GIF format to use as a preview image. The preview image is displayed in place of the DivX “X” logo when autoPlay is set to false. This allows to setup a piece of  video so that it does not auto start but shows a preview image of what the video is about.

Users can then start the download and playback of the video by clicking anywhere on the preview image. See the previewMessage and previewMessageSize parameters for more options.

Note that you need to set the autoPlay parameter to false for this parameter to be taken into account.

Usage:

  • In the object tag:  <param name="previewImage" value="[value]"> 
  • In the embed tag:  previewImage="[value]"

Possible values:

  • A relative path, such as "myPreviewImage.gif" or "../../images/myImage.jpg". 
  • An absolute path, i.e. "http://mywebsite.com/myImage.png".

previewMessage

The previewMessage parameter allows to display a text message on top of the preview image  to let users know how to start the video. The message can be any text such as “Click to play video”.

Note that you need to also set the previewImage parameter for this parameter to be taken into account.

Usage:

  • In the object tag:  <param name="previewMessage" value="[value]"> 
  • In the embed tag:  previewMessage="[value]"

Possible values:

  • Any text message such as "Click here to play this video".

previewMessageFontSize

The previewMessageFontSize parameter allows to customize the size of the font used to display the preview message over the preview image.

Note that you need to also set the previewImage and previewMessage parameters for this parameter to be taken into account.

Usage:

  • In the object tag:  <param name="previewMessageFontSize" value="[value]"> 
  • In the embed tag:  previewMessageFontSize="[value]"

Possible values:

  • Any integer  value meaningful as a font size message such as "8" or “32”.

src

The src parameter is used to specify which video file the plug-in should attempt to download and play. This file should have an “.avi”, “.divx” or “.mkv” extension.

If this parameter is omitted, the plugin will not attempt to download and play a file on startup but will be ready for JavaScript calls to instruct it to do so at a later time (see the JavaScript API Reference for details).

Usage:

  • In the object tag: <param name="src" value="[value]">
  • In the embed tag: src="[value]"

Possible values:

  • A relative path, i.e. "movie.divx" or "../../videos/ myvideo.divx". 
  • An absolute path, i.e. "http://mywebsite.com/myvideo.divx".