ClickToPlugin HTML5 replacements

Installing killers is easy: simply add their URLs (taken for example from the list of killers below) to the “Plug-in to HTML5 conversion scripts” list in ClickToPlugin’s preferences. Close the preference window and ClickToPlugin will have loaded the new killer(s).

The order of the killers in the list matters, since at most one is applied to any given plug-in object. As a precaution you should add killers before the built-in Flash.js, Silverlight.js, and Generic.js killers, who have lax criteria of applicability.

The killers in the first part of the table are included in ClickToPlugin, but the versions posted here may be more recent.

If you would like to share your own killers, you can do so by contacting me or directly on GitHub.

Killer files are included as scripts in the extension’s global page, using ClickToPlugin’s built-in universal extension. In particular, all killer files share the same scope, so global definitions must be avoided.

Here is a minimal killer file:

addKiller("Useless killer", {
   "canKill": function(data) {return false;},
   "process": function(data, callback) {}
});

The first argument of the addKiller function serves as a unique identifier for the killer, which is the function’s second argument. The mandatory methods canKill and process are described below.

Here is what an actual killer file looks like:

addKiller("GitHub", {
   
   "canKill": function(data) {
      if(data.type !== "application/x-shockwave-flash") return false;
      return data.src.indexOf("http://hoyois.github.io/") !== -1;
   },

   "process": function(data, callback) {
      var flashvars = parseFlashVariables(data.params.flashvars);
      if(!flashvars.mp4Source) return;
   
      callback({
         "playlist": [{
            "poster": decodeURIComponent(flashvars.previewImage),
            "sources": [{
               "url": decodeURIComponent(flashvars.mp4Source),
               "isNative": true
            }]
         }]
      });
   }
   
});

This killer will process all Flash content hosted on this domain and offer a simple HTML5 alternative for those that have the mp4Source Flash variable.

The killers database provides further examples with varying degrees of complexity.

The canKill method

The canKill method has a plug-in data object as argument and must return a boolean. This function should be kept as simple as possible, since it will be executed for every blocked plug-in object. If it returns true, ClickToPlugin stops evaluating the canKill methods of other killers and asynchronously runs the process method of this killer. Otherwise the plug-in data object is passed to the next killer’s canKill method. In particular, the canKill method should not modify its argument if it does not return true.

The process method

The process method has a plug-in data object and a function callback as arguments and does not return anything. To be successful, this method must apply the callback function to a media data object. This needs not happen in the body of the process method itself: for example, if the killer makes an HTTP request, the callback function will be called in the onload handler of the XMLHttpRequest object.

Plug-in data objects

The same object is passed as first argument to the canKill and process methods. It has the following properties:

• src is the source of the blocked resource as absolute URL. For the Flash plug-in, this is an SWF file, for the Silverlight plug-in an XAP file, etc.
• type is a the MIME type of the blocked resource, as determined by Safari.
• location is the address of the blocked plug-in’s document as an absolute URL.
• title is the title of the blocked plug-in’s document.
• baseURL is the base URL of the blocked plug-in’s document.
• params is an object containing the parameters to be passed to the plug-in. For example, Flash objects typically have a flashvars parameter, and Silverlight objects an initparams parameter.

Media data objects

A media data object contains data to be used by ClickToPlugin’s media player. The following minimal media data object will result in an HTML5 video element with src attribute set to videoURL:

{
   "playlist": [{
      "sources": [{
         "url": videoURL
      }]
   }]
}

The only mandatory property of a media data object is playlist, which is an array of media track objects.

Each media track object can have the following properties:

• sources (mandatory) is an array of media source objects;
• poster is a URL to an image file to be used as poster image for the media element;
• title is the title of the track;
• siteInfo is an object that makes the “View on …” command appear in the shortcut menu. It has two mandatory properties:
  • name is the name of the site displayed in the shortcut menu, e.g. "YouTube";
  • url is the absolute URL to open when the “View on …” command is used.

Each media source object can have the following properties:

• url (mandatory) is a URL to a media file that must be playable in Safari;
• format is the text that will appear in the source selector (it should be set if there are more than one source);
• height is a number approximating the native height in pixels of the video;
• isNative is a boolean which should be set to true only if the video file can be played without using third-party QuickTime components;
• isAudio can be set to true for an audio source; this causes the poster to be used as background image throughout playback.

Available functions

The following functions form the interface between killers and ClickToPlugin.

• addKiller(name, killer) adds the object killer to the list of killers.
• hasKiller(name) returns a boolean indicating if the killer named name is loaded.
• getKiller(name) returns the killer object named name.

ClickToPlugin also defines the following useful functions that can be used in killer files.

• parseFlashVariables(flashvars) returns a Flash object’s flashvars as a key–value object.
• parseSLVariables(initparams) returns a Silverlight object’s initparams as a key–value object.
• unescapeHTML(text) replaces HTML entities in text by the characters they represent and returns the result.
• unescapeUnicode(text) replaces any sequence of the form \uxxxx in text by the character with code xxxx and returns the result.
• makeAbsoluteURL(url, base) returns the resolution of the URL url with respect to base.
• extractExt(url) returns the extension of url.
• typeInfo(type) returns null if Safari cannot play the MIME type type, otherwise an object with three properties that can be used to build a media source object: format, isNative, and isAudio.
• extInfo(ext) has the same return values as typeInfo, based on the extension ext.
• The following predefined variables can be used when the data provided by typeInfo or urlInfo is not needed:
  • canPlayFLV;
  • canPlayOgg;
  • canPlayWebM;
  • canPlayWM.
• getMIMEType(resourceURL, handleMIMEType) runs the function handleMIMEType with the MIME type of the resource resourceURL as argument.
• parseXSPlaylist(playlistURL, baseURL, posterURL, startIndex, handleMediaData) runs the function handleMediaData with argument a media data object obtained from the XSPF file playlistURL.