Timesheet Scheduler

This document presents the SMIL Timesheet scheduler that was developed as part of the LimSee3 project. It consists of one JavaScript library written by Elodie Nouguier. It is suitable for interpreting SMIL Timesheets embedded in an XHTML document.

The code of the scheduler

Currently, the scheduler has reached version 1.0.

We release the code under the terms of the CeCILL-B license. Roughly speaking, this license makes it free to download, use and modify as long as you leave our credits in the code header.

When using the scheduler (even without any modification), please download it first and use your local copy. Do not link your XHTML documents to the scheduler code on this page - our web server is not performant enough.

How to use the scheduler

You have an XHTML document with an embedded SMIL Timesheet and you want to use the scheduler to "play" the document. To this end, you need to

  1. Include the scheduler code in the document header:
    <head>
      ...
      <script type="text/javascript" src="scheduler.js"></script>
      ...
    </head>
  2. Start the execution at the end of the document body:
    <body>
      ...
      <script type="text/javascript">
        setTimeout("Scheduler()", 1000)
      </script>
    </body>

    (This code will start the main scheduler procedure one second after the document loads. We found this delay necessary for long documents with embedded audio and/or video tracks).

The scheduler needs some minimal context in order to work properly:

In this section, we treat the case of "clickable links" in (X)HTML:

<a href="foo">...</a>

Simple case

Links that point outside the current document need no special treatment, since the usual semantics ("replace the current document by the link target") is exactly what is wanted. However, the case of local links (href="#bar") is different, because the usual semantics may not be sufficient, as time should be taken into account, too.

For instance, in a slideshow, clicking on the "Next" link should replace the current slide by the next one and it should advance the global presentation time to the beginning of the next slide.

This is why some interaction is needed with the scheduler, in order to make it aware of user clicks. This is the role of two scheduler functions, addPossibleArea and proceedAreas. In the simplest case of use, you should replace every link of the form

<a href="#bar">...</a>

by

<a href="#bar" onclick="addPossibleArea('#bar'); proceedAreas(); return false">...</a>

The onclick part takes care of the click in case JavaScript is enabled and the scheduler is running; otherwise the usual treatment is ensured by interpretation of the href.

For the sake of generality, you can replace every clickable link as indicated above (not only the local links). The scheduler will simply delegate non local links to the browser without further notice.

General case

Why is the onclick attribute value so complex? Why do we use two different functions? The reason is not linked to SMIL Timesheets but rather to LimSee3. In fact, in LimSee3 we use the notion of <area> elements taken from SMIL. The problem is that

So in order to mimick the SMIL semantics, we introduced the addPossibleArea and proceedAreas functions. Actually, addPossibleArea is called as many times as there are areas defined inside the element and, when the list is done, proceedAreas is called, which dynamically selects zero or one of the possible areas (depending on their timing) and activates it.

Let us see it on an example. Suppose we want to render in XHTML+Timesheets an equivalent of this SMIL code:

<smil:img src="foo">
  <smil:area href="href1" begin="b1" end="e1" dur="d1" />
  <smil:area href="href2" dur="d2" />
  <smil:area href="href3" begin="b3" />
</smil:img>

Our translation would be

<a href="javascript: addPossibleArea('href1','b1','e1','d1');
                     addPossibleArea('href2',null,null,'d2');
                     addPossibleArea('href3','b3');
                     proceedAreas();">
  <img src="foo" />
</a>

Public API

External code can interact with the scheduler through the following JavaScript functions:

Name and parameters Description
function Scheduler()

Main function of the scheduler. Called only once, at the beginning. It parses the timesheet, initializes the internal representations and starts the document presentation.

function Play()

As their names suggest, these three functions switch the current state of the scheduler. For instance when playing, it can be paused by the Pause function (presentation time will not advance) or stopped by Stop (presentation time will not advance and it will be reinitialized to zero).

A detailed state diagram is on figure†1 below.

function Pause()
function Stop()
abstract function showTime(time)

showTime is a call-back function: it is not implemented in the scheduler, but if it is otherwise present in the global XHTML document, it is periodically called with the current presentation time (in milliseconds) as parameter.

abstract function alertVLCProblem(present, goodversion) alertVLCProblem is an other call-back function: it is not implemented in the scheduler (so that document authors are free to implement it). This function is called when there is a problem with the VLC plug-in. The two parameters are booleans: present indicates whether the VLC plug-in is present in the browser and goodversion indicates whether the plug-in version is sufficient.
function addPossibleArea(href,begin,end,dur,id) and function proceedAreas() Functions for treating user clicks. See section Special case of clickable links above.

Play-pause-stop state diagram

Fig. 1 - Play/pause/stop state diagram (t is time and t' is its first derivative)

Known limitations

The version 1.0 of the scheduler does not implement the whole Timesheet specification. Following parts are missing: