L'API JavaScript du lecteur metaScore permet de contrôler et d'interagir avec un lecteur metaScore intégré via une iframe.
Premiers pas
Pour pouvoir contrôler un lecteur, il doit être intégré dans une page HTML avec le paramètre "api", et le script d'API doit être chargé dans cette même page HTML.
Un identifiant doit également être défini sur l'iframe du lecteur, qui sera utilisé par l'API pour identifier le lecteur à contrôler.
Exemple
<script type="text/javascript" src="https://metascore.philharmoniedeparis.fr/libraries/metaScore/metaScore.API.js"></script>
<iframe id="mon-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>
Contrôle automatique à l'aide de liens HTML
Une fois l'API chargée, elle analysera automatiquement la page HTML à la recherche de liens dont l'attribut "rel" est égale à "metascore", et dont la valeur de l'attribut "data-guide" correspond à un identifiant d'un iframe de lecteur intégré.
Après qu'un lien est été analysé par l'API, cliquer dessus déclenchera automatiquement l'action associée sur le lecteur correspondant.
Vous trouverez ci-dessous le format général des liens analysés automatiquement :
<a href="#{action(s)}" rel="metascore" data-guide="{identifiant de l'iframe}">{
texte du lien}</a>
Exemple
<a href="#play=0,2000,scenario-0" rel="metascore" data-guide="mon-guide">play an excerpt</a>
Actions disponibles
Les actions suivantes peuvent être affectées aux liens :
Action | Arguments | Description |
---|---|---|
play | Lance la lecture | |
play | inTime, outTime, scenario | Lance la lecture d'un extrait de inTime à outTime avec le scénario scenario |
pause | Suspend la lecture | |
stop | Arrête la lecture | |
seek | time | Règle le temps de lecture actuel à time en secondes |
page | block, page | Tourne le bloc block à la page spécifiée par page |
scenario | name | Change le scénario actif pour celui spécifié par name |
showBlock | name | Affiche le bloc spécifié par name |
hideBlock | name | Cache le bloc spécifié par name |
toggleblock | name | Bascule la visibilité du bloc spécifié par name |
enterFullscreen | Entre en mode plein écran | |
exitFullscreen | Quitte le mode plein écran | |
toggleFullscreen | Bascule le mode plein écran |
Il est possible de combiner plusieurs actions en un seul lien en les séparant par un "&".
Exemples:
<a href="#play" rel="metascore" data-guide="mon-guide">lance la lecture</a>
<a href="#play=20,50,scenario-2" rel="metascore" data-guide="mon-guide">lance la lecture d'un extrait de 20 secondes à 50 secondes avec le scénario scenario-2</a>
<a href="#pause" rel="metascore" data-guide="mon-guide">suspendre la lecture</a>
<a href="#seek=5" rel="metascore" data-guide="mon-guide">règle le temps de lecture actuel à 5 secondes</a>
<a href="#page=permanentText,3" rel="metascore" data-guide="mon-guide">tourne le bloc "permanentText" à la page 3</a>
<a href="#scenario=scenario-2" rel="metascore" data-guide="mon-guide">change le scénario actif à scenario-2</a>
<a href="#showBlock=permanentText" rel="metascore" data-guide="mon-guide">affiche le bloc "permanentText"</a>
<a href="#hideBlock=permanentText" rel="metascore" data-guide="mon-guide">cache le bloc "permanentText"</a>
<a href="#toggleBlock=permanentText" rel="metascore" data-guide="mon-guide">bascule la visibilité du bloc "permanentText"</a>
<a href="#page=permanentText,3&scenario=scenario-2&seek=5" rel="metascore" data-guide="mon-guide">tourne le bloc "permanentText" à la page 3 ET change le scénario actif à scenario-2 ET règle le temps de lecture actuel à 5 secondes</a>
Contrôle manuel à l'aide de JavaScript
L'API permet également de contrôler et d'interagir avec un lecteur à l'aide de JavaScript.
Cela se fait en instanciant un objet metaScore.API avec un élément iframe du lecteur et un callback.
Les méthodes suivantes sont disponibles sur l'argument retourné par le callback :
Méthode | Arguments | Description |
---|---|---|
on | type, callback | Écoute les événements du lecteur du type correspondant et invoque la fonction de callback lorsqu'un tel événement est reçu. Le type peut être l'un des suivants :
|
play | Lance la lecture | |
play | inTime, outTime, scenario | Lance la lecture d'un extrait de inTime à outTime avec le scénario scenario |
pause | Interrompt la lecture | |
seek | time | Règle le temps de lecture actuel à time en secondes |
page | block, page | Tourne le bloc à la page spécifiée |
scenario | name | Change le scénario actif pour celui spécifié par name |
showBlock | name | Affiche le bloc spécifié par name |
hideBlock | name | Cache le bloc spécifié par name |
toggleBlock | name | Basculer la visibilité du bloc spécifié par name |
playing | callback | Récupère l'état actuel de lecture |
time | callback | Récupère le temps actuel du lecteur en secondes |
Il est recommandé d'attendre que le document HTML soit entièrement chargé avant d'instancier un objet metaScore.API.
Example
<script type="text/javascript"> document.addEventListener("DOMContentLoaded", function(){ var iframe = document.getElementById("mon-guide"); new metaScore.API(iframe, function(api){ // Écouter l'événement ready. player.on("ready", function(){ // Écoutez les événements de type timeupdate. api.on("timeupdate", function(time){ // Faites quelque chose avec le temps actuel. }); // Écouter les événements de type
scenariochange. api.on("
scenariochange", function(name){ // Faites quelque chose avec le nom du scénario actuel. }); // Lance la lecture. api.play(); // Lance la lecture d'un extrait de 2 secondes à 5 secondes avec le scénario scenario-2. api.play(2, 5, "scenario-2"); // Interrompt la lecture api.pause(); // Règle le temps de lecture actuel à 5 secondes. api.seek(5); // Tourne le bloc "permanentText" à la page 3. api.page("permanentText", 3); // Règle le scénario à "scenario-2". api.scenario("scenario-2"); // Affiche le bloc"permanentText". api.showBlock("permanentText"); // Cache le bloc "permanentText". api.hideBlock("permanentText"); // Basculer la visibilité du bloc "permanentText". api.toggleBlock("permanentText"); // Vérifier si la lecture est en cours. api.playing(function(playing){ if(playing){ ... } else{ ... } }); // Récupérer le temps actuel du lecteur. api.time(function(time){ ... }); }); }); }, false); </script>