API Javascript

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