Javascript API

The metaScore player API enables allows you to control and interact with an iframe embedded metaScore player using JavaScript.

Getting Started

To be able to control a player, it must be embedded in an HTML page with the "api" flag, and the API script must be loaded in that save HTML page.
An id must also be set on the player's iframe, which will be used by the API to identify the player to control.

Example

<script type="text/javascript" src="https://metascore.philharmoniedeparis.fr/sites/default/libraries/metaScore/metaScore.api.js"></script>
<iframe id="my-guide" type="text/html" src="https://metascore.philharmoniedeparis.fr/en/player/ABC?api=1" width="640" height="390" frameborder="0" allowfullscreen="true" allow="autoplay; fullscreen" class="metascore-embed"></iframe>

 

Automatic control using HTML links

Once the API is loaded, it will automatically scan the HTML page for links who's "rel" attribute is set to "metascore", and who's "data-guide" attribute's value corresponds to an id of an embedded player's iframe.
After being parsed by the API, clicking on such links will automatically trigger the associated action on the corresponding player.
Below is the general format of automatically parsed links:

<a href="#{action(s)}" rel="metascore" data-guide="{player's iframe id}">{link text}</a>

Example

<a href="#play=0,2000,scenario-0" rel="metascore" data-guide="my-guide">play an excerpt</a>

Available actions

The following actions can be assigned to links:

action arguments description
play   Plays the player
play inTime, outTime, scenario Plays an excerpt from inTime to outTime on scenario
pause   Pauses the player
seek time Sets the current playback time to time in seconds
page block, page Turns the block specified by block to the specified page
scenario name Switches the scenario to the specified name
showBlock name Shows the block specified by name
hideBlock name Hides the block specified by name
toggleBlock name Toggles the visibility of the block specified by name

Multiple actions can be combines in a single link by separating them with a "&".

Examples:

<a href="#play" rel="metascore" data-guide="my-guide">play</a>
<a href="#play=20,500,scenario-2" rel="metascore" data-guide="my-guide">play excerpt from 20 centiseconds to 500 centiseconds at reading index 2</a>
<a href="#pause" rel="metascore" data-guide="my-guide">pause</a>
<a href="#seek=5" rel="metascore" data-guide="my-guide">seek to 5 seconds</a>
<a href="#page=permanentText,3" rel="metascore" data-guide="my-guide">go to page 3 of the "permanentText" block</a>
<a href="#scenario=scenario-2" rel="metascore" data-guide="my-guide">set the reading index to 2</a>
<a href="#showBlock=permanentText" rel="metascore" data-guide="my-guide">show the "permanentText" block</a>
<a href="#hideBlock=permanentText" rel="metascore" data-guide="my-guide">hide the "permanentText" block</a>
<a href="#toggleBlock=permanentText" rel="metascore" data-guide="my-guide">toggle the "permanentText" block</a>
<a href="#page=permanentText,3&scenario=scenario-2&seek=5" rel="metascore" data-guide="my-guide">go to page 3 of the "permanentText" block AND set the reading index to 2 AND seek to 5 seconds</a>

 

Manual control using JavaScript

The API also allows interacting with and controlling a player using JavaScript.
This is done by instantiating a metaScore.API object with a player's iframe element and a callback.

The following methods are made available on the argument returned by the callback function:

method arguments description
on type, callback Listens to player events of the corresponding type and invokes the callback function when such an event is received.
The type can be one of the following:
  • ready: triggered when the player has finished loading
  • timeupdate: triggered every time the media time changes
  • scenariochange: triggered when the scenario is changed
play   Plays the player
play inTime, outTime, scenario Plays an excerpt from inTime to outTime on scenario
pause   Pauses the player
stop   Stops the player
seek time Sets the current playback time to time in seconds
page block, page Turns the block specified by block to the specified page
scenario name Switches the scenario to the specified name
showBlock name Shows the block specified by name
hideBlock name Hides the block specified by name
toggleBlock name Toggles the visibility of the block specified by name
enterFullscreen   Enters fullscreen mode
exitFullscreen   Exits the fullscreen mode
toggleFullscreen   Toggles the fullscreen mode
playing callback Retrieves the player's playing state
time callback Retrieves the current player's time

It is recommended to wait for the HTML document to fully load before instantiating an metaScore.API object.

Example

<script type="text/javascript">
  document.addEventListener("DOMContentLoaded", function(){

    var iframe = document.getElementById("my-guide");

    new metaScore.API(iframe, function(api){

      // Listen to the ready event
      api.on("ready", function(){

        // Listen to timeupdate events.
        api.on("timeupdate", function(time){
          // Do something with the current time.
        });

        // Listen to rindex events.
        api.on("scenariochange", function(name){
          // Do something with the current scenario.
        });

        // Play.
        api.play();

        // Play excerpt from 2 seconds to 5 seconds on scenario-2.
        api.play(2, 5, "scenario-2");

        // Pause
        api.pause();

        // Seek to 5 seconds.
        api.seek(5);

        // Go to page 3 of the "permanentText" block.
        api.page("permanentText", 3);

        // Set the reading index to 2.
        api.scenario("scenario-2");

        // Show the "permanentText" block.
        api.showBlock("permanentText");

        // Hide the "permanentText" block.
        api.hideBlock("permanentText");

        // Toggle the "permanentText" block.
        api.toggleBlock("permanentText");

        // Check if the player is playing.
        api.playing(function(playing){
          if(playing){
            ...
          }
          else{
            ...
          }
        });

        // Retrieve the current player's time.
        api.time(function(time){
          ...
        });
      });
    });

  }, false);
</script>