API Javascript | metaScore

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}">{

}</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
responsive	adaptSize, allowUpscaling	Définit si l'application peut adapter sa taille à son conteneur
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 : ready : déclenché lorsque le lecteur est prêt timeupdate : déclenché à chaque fois que le temps actuel de lecture change scenariochange: déclenché lorsqu'un changement de scénario est effectué
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
responsive	adaptSize, allowUpscaling	Définit si l'application peut adapter sa taille à son conteneur
enterFullscreen		Entre en mode plein écran
exitFullscreen		Quitte le mode plein écran
toggleFullscreen		Bascule le mode plein écran
playing	callback	Récupère l'état actuel de lecture
time	callback	Récupère le temps actuel du lecteur en secondes
getVariable	name, callback	Récupère la valeur d'une variable de comportement spécifié par name
setVariable	name, value	Définit la valeur d'une variable de comportement spécifié par name

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){
          // Do something with the current scenario.
        });
        // 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>