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:
|
| 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>