Zinc Javascript API

Quick Start

Zinc provides a JavaScript API to help you integrate with a user's remote control. You can do a lot of neat things with it - but to get you started, here's a really quick and simple example of how to integrate with the "Play" button on a remote:

<script type="application/x-javascript" src="chrome://zvlib/content/zvpage.js"></script>
<script>
    //Make sure the Zinc library is available
    if (typeof ZvLib == 'undefined')
    {
      //If ZvLib is undefined, it means the user does not have Zinc installed.
      //You could simply ignore this, and have pages work with Zinc automatically if they have it installed.
      //Or you could provide a warning to users telling them they need Zinc.  Up to you!
      alert('Attention user!  You need Zinc installed to use this page!');
    }
    else
    {
      //Add support for the remote control "Play" button        
      ZvLib.Events.addEventListener('ZvRemotePlay', function(e)
      {
          //Do whatever you need to do to control your web page.  Example below:
          var my_player = document.getElementById('MY_PLAYER_ID');
          my_player.play();         
          //This indicates that your web page handled the event and the default handling can be ignored.
          e.stopPropagation();
      }, false);
    }
</script>

The Zinc Libraries

To get started with using the Zinc API, all you need to do is include the Zinc JavaScript source, using this piece of code:

<script type="application/x-javascript" src="chrome://zvlib/content/zvpage.js"></script>

This will get the Zinc libraries loaded. If a user does not have Zinc installed, you can check this easily:

<script type="application/x-javascript" src="chrome://zvlib/content/zvpage.js"></script>
<script>
  if (typeof ZvLib == 'undefined') alert('Attention user!  You need Zinc installed to use this page!');
</script>

You could also simply ignore any Zinc-specific handling if Zinc is not installed, which will allow your player to integrate seamlessly with Zinc-enabled browsers, with no ill effects for everyone else. Since this javascript is specific to Zinc (and by extension, Firefox), it will not work in Internet Explorer or another browser.

Responding to Zinc Events

The Zinc javascript API enables your web page to respond to Zinc events. Since Zinc runs in privileged javascript code and web pages run in unprivileged javascript code, a special event library is necessary to communicate. Zinc uses DOM events to send events securely from privileged chrome code to unprivileged javascript code.

Here is an example of how to listen to a Zinc event:

ZvLib.Events.addEventListener('ZvRemotePlay', YOUR_FUNCTION_HERE(event), false);

You can respond to events any way you wish. For example, you can respond to remote control buttons like Play or Pause, or automatically start Full Screen mode when a user arrives at your page via Zinc.

Note, for keyboard-equivilant events, such as "Up", "Down", "Left", "Right", and "Enter", use the normal JavaScript methods of listening for "keydown", "keyup", or "keypress" events.

Supported javascript events

  • Standard Media Player Buttons
    • ZvRemotePlay - "Play" button (found on standard ZvRemote)
    • ZvRemotePause - "Pause" button (found on standard ZvRemote)
    • ZvRemotePlayPause - Combined "Play" and "Pause" button (found on ZvKeyboard and most Windows Media Center remotes)
    • ZvRemoteRecord - "Record" button
    • ZvRemoteFastForward - "Fast Forward" button. Conventionally, moves forward within or accelerates currently playing media.
    • ZvRemoteRewind - "Rewind" button. Conventionally, moves backward within, decelerates, or reverses currently playing media.
    • ZvRemoteNext - "Next" button. Conventionally, moves to next available track.
    • ZvRemotePrevious - "Previous" button. Conventionally, moves to previous available track.
    • ZvRemoteStop - "Stop" button. Conventionally, stops playback, and may reset position to beginning of media if desired.
  • Other Buttons
    • ZvRemoteFullscreen - "Full Screen" button. Player should go to or exit full screen. (Note for Flash and Silverlight, if the player is already full screen, this will automatically exit full screen mode and you will not receive this event.)
    • ZvRemoteInfo - "Info" button
    • ZvRemoteChannelUp - "Channel Up" button
    • ZvRemoteChannelDown - "Channel Down" button
  • Non-buttons
    • ZvAutoFullscreen - When the user arrives at a page directly from the Zinc user interface, this event is sent repeatedly until either (a) a timeout has expired (b) the web page loses focus or (c) the web page catches the event and calls "event.preventDefault();". This gives the opportunity for a web page to respond to the event after it is fully loaded, and the power to ignore the event before it is fully loaded.

Zinc API Functions

The Zinc javascript API also has several functions that allow you to interact with Zinc or the browser The following functions are supported:

  • ZvLib.DeclareRemoteSupport(arg_buttons) - Declares that your site has Zinc remote control support. This is reflected in the UI as a pop-up window showing which buttons are supported. Examples: ZvLib.DeclareRemoteSupport('PLAY,PAUSE,STOP,REWIND,FF,PREV,NEXT,FULLSCREEN'); or ZvLib.DeclareRemoteSupport('PLAY,PAUSE');
  • ZvLib.DimLights(arg_dim) - Causes the browser to change how it looks for a more pleasant full-screen viewing experience by making the full-screen "toggle" bar smaller and a solid, near-black color instead of its usual large bright gray appearance. Pass true or false to enable or disable the feature.
  • ZvLib.BackToZinc() - Returns to the last Zinc page in the browser's history. This is very useful if your web page uses iframe-based navigation.
  • ZvLib.ContentHasFinished() - Declare that the video has completed playing, and Zinc should take over the user experience again.

A Complete Example

This example code demonstrates basic usage of all parts Zinc API.

<script type="application/x-javascript" src="chrome://zvlib/content/zvpage.js"></script>
<script>
    //Make sure the Zinc library is available
    if (typeof ZvLib == 'undefined')
    {
      //If ZvLib is undefined, it means the user does not have Zinc installed.
      //You could simply ignore this, and have pages work with Zinc automatically if they have it installed.
      //Or you could provide a warning to users telling them they need Zinc.  Up to you!
      alert('Attention user!  You need Zinc installed to use this page!');
    }
    else
    {
      //Get a reference to my player
      var my_player = document.getElementById('MY_PLAYER_ID');
      //Add support for basic remote control buttons
      ZvLib.Events.addEventListener('ZvRemotePlay', function(e) { my_player.play();  e.stopPropagation(); }, false);
      ZvLib.Events.addEventListener('ZvRemotePause', function(e) { my_player.pause();  e.stopPropagation(); }, false);
      ZvLib.Events.addEventListener('ZvRemotePlayPause', function(e) { my_player.play_toggle();  e.stopPropagation(); }, false);
      ZvLib.Events.addEventListener('ZvRemoteRewind', function(e) { my_player.rewind();  e.stopPropagation(); }, false);
      ZvLib.Events.addEventListener('ZvRemoteFastForward', function(e) { my_player.fastforward();  e.stopPropagation(); }, false);
      //Declare remote support
      ZvLib.DeclareRemoteSupport('PLAY','PAUSE','REWIND','FASTFORWARD');      
      //Set up a function that my media player will call as soon as the content ends
      window.MY_MEDIA_PLAYER_MOVIE_ENDED = function() { ZvLib.ContentHasFinished(); }
      //Dim the lights immediately
      ZvLib.DimLights(true);
    }
</script>

Developers

Log in

New to Zinc?

Register