SDK du nœud de l'API Video de Vonage

Le SDK OpenTok Node propose des méthodes permettant de :

Installation à l'aide de npm (recommandé) :

npm permet de gérer les dépendances des projets Node. Pour en savoir plus, rendez-vous ici : http://npmjs.org.

Exécutez cette commande pour installer le paquetage et l'ajouter à votre fichier package.json:

$ npm install opentok --save

Utilisation

Initialisation

Importez le module pour obtenir une fonction de constructeur d'un objet OpenTok, puis appelez-la avec new pour instancier un objet OpenTok avec votre propre clé API et votre secret API.

const OpenTok = require("opentok");
const opentok = new OpenTok(apiKey, apiSecret);

Augmentation des délais d'expiration

La bibliothèque utilise actuellement un délai d'expiration de 20 secondes pour les requêtes. Si vous êtes connecté à un réseau lent et que vous devez augmenter ce délai, vous pouvez le spécifier (en millisecondes) lors de l'instanciation de l'objet OpenTok.

const OpenTok = require("opentok");
const opentok = new OpenTok(apiKey, apiSecret, { timeout: 30000});

Création de sessions

Pour créer une session OpenTok, utilisez la commande OpenTok.createSession(properties, callback) méthode. La méthode properties Le paramètre est un objet facultatif permettant de préciser si la session utilise le Media Router d’OpenTok, de définir une indication de localisation et de déterminer si la session sera automatiquement archivée ou non. La fonction de rappel a la signature suivante : function(error, session). Les session La valeur renvoyée dans la fonction de rappel est une instance de Session. Les objets Session disposent d'un sessionId qui est qu'il est utile d'enregistrer dans une mémoire persistante (telle qu'une base de données).

// Create a session that will attempt to transmit streams directly between
// clients. If clients cannot connect, the session uses the OpenTok TURN server:
opentok.createSession(function (err, session) {
  if (err) return console.log(err);

  // save the sessionId
  db.save("session", session.sessionId, done);
});

// The session will the OpenTok Media Router:
opentok.createSession({ mediaMode: "routed" }, function (err, session) {
  if (err) return console.log(err);

  // save the sessionId
  db.save("session", session.sessionId, done);
});

// A Session with a location hint
opentok.createSession({ location: "12.34.56.78" }, function (err, session) {
  if (err) return console.log(err);

  // save the sessionId
  db.save("session", session.sessionId, done);
});

// A Session with an automatic archiving
opentok.createSession({ mediaMode: "routed", archiveMode: "always" }, function (
  err,
  session
) {
  if (err) return console.log(err);

  // save the sessionId
  db.save("session", session.sessionId, done);
});

Générer des jetons

Une fois qu'une session est créée, vous pouvez commencer à générer des jetons que les clients utiliseront pour se connecter à la session. Vous pouvez générer un jeton en appelant la fonction OpenTok.generateToken(sessionId, options) méthode. Une autre façon consiste à appeler la generateToken(options) méthode d'un objet Session. La options Le paramètre est un objet facultatif permettant de définir le rôle, la durée de validité et les données de connexion du jeton. Pour le contrôle de la mise en page dans les archives et les diffusions, il est également possible de définir la liste initiale des classes de mise en page des flux publiés à partir des connexions utilisant ce jeton.

// Generate a Token from just a sessionId (fetched from a database)
token = opentok.generateToken(sessionId);

// Generate a Token from a session object (returned from createSession)
token = session.generateToken();

// Set some options in a Token
token = session.generateToken({
  role: "moderator",
  expireTime: new Date().getTime() / 1000 + 7 * 24 * 60 * 60, // in one week
  data: "name=Johnny",
  initialLayoutClassList: ["focus"],
});

Travailler avec les archives

Vous pouvez lancer l'enregistrement d'une session OpenTok à l'aide de la commande OpenTok.startArchive(sessionId, options, callback) méthode. La méthode options Le paramètre est un objet facultatif permettant de définir le nom de l'archive. La fonction de rappel a la signature suivante : function(err, archive). Les archive La valeur renvoyée dans la fonction de rappel est une instance de Archive. Notez que vous ne pouvez lancer une archive que sur une session comportant des clients connectés.

opentok.startArchive(sessionId, { name: "Important Presentation" }, function (
  err,
  archive
) {
  if (err) {
    return console.log(err);
  } else {
    // The id property is useful to save off into a database
    console.log("new archive:" + archive.id);
  }
});

Vous pouvez également désactiver l'enregistrement audio ou vidéo en réglant le paramètre hasAudio ou hasVideo propriété de la options au paramètre false:

var archiveOptions = {
  name: "Important Presentation",
  hasVideo: false, // Record audio only
};
opentok.startArchive(sessionId, archiveOptions, function (err, archive) {
  if (err) {
    return console.log(err);
  } else {
    // The id property is useful to save to a database
    console.log("new archive:" + archive.id);
  }
});

Par défaut, tous les flux sont enregistrés dans un seul fichier (composé). Vous pouvez enregistrer les différents de la session sur des fichiers individuels (au lieu d'un seul fichier composé) en définissant le paramètre outputMode à l'option 'individual' lorsque vous appelez le OpenTok.startArchive() méthode :

var archiveOptions = {
  name: "Important Presentation",
  outputMode: "individual",
};
opentok.startArchive(sessionId, archiveOptions, function (err, archive) {
  if (err) {
    return console.log(err);
  } else {
    // The id property is useful to save off into a database
    console.log("new archive:" + archive.id);
  }
});

Vous pouvez arrêter l'enregistrement d'une archive commencée à l'aide de la touche OpenTok.stopArchive(archiveId, callback) méthode. Vous pouvez également le faire à l'aide de la Archive.stop(callback) méthode a Archive par exemple. La fonction de rappel a la signature suivante : function(err, archive). Les archive La valeur renvoyée dans la fonction de rappel est une instance de Archive.

opentok.stopArchive(archiveId, function (err, archive) {
  if (err) return console.log(err);

  console.log("Stopped archive:" + archive.id);
});

archive.stop(function (err, archive) {
  if (err) return console.log(err);
});

Pour obtenir un Archive (et toutes les informations la concernant) à partir d'une instance de archiveId, utiliser le OpenTok.getArchive(archiveId, callback) méthode. La fonction de rappel a la signature suivante : function(err, archive). Vous pouvez consulter les propriétés de l'archive pour obtenir plus de détails.

opentok.getArchive(archiveId, function (err, archive) {
  if (err) return console.log(err);

  console.log(archive);
});

Pour supprimer une archive, vous pouvez appeler le OpenTok.deleteArchive(archiveId, callback) méthode ou la delete(callback) méthode d'un Archive par exemple. La fonction de rappel a la signature suivante : function(err).

// Delete an Archive from an archiveId (fetched from database)
opentok.deleteArchive(archiveId, function (err) {
  if (err) console.log(err);
});

// Delete an Archive from an Archive instance, returned from the OpenTok.startArchive(),
// OpenTok.getArchive(), or OpenTok.listArchives() methods
archive.delete(function (err) {
  if (err) console.log(err);
});

Vous pouvez également obtenir une liste de toutes les archives que vous avez créées (jusqu'à 1000) avec votre clé API. Cette opération s'effectue à l'aide de la à l'aide de la fonction OpenTok.listArchives(options, callback) méthode. Le paramètre options est un est un objet optionnel utilisé pour spécifier un offset et count pour vous aider à paginer dans les résultats. Le callback a une signature function(err, archives, totalCount). Les archives renvoyée par le rappel est un tableau de Archive instances. Les totalCount La valeur renvoyée par la fonction de rappel correspond au nombre total d'archives générées par votre clé API.

opentok.listArchives({ offset: 100, count: 50 }, function (
  error,
  archives,
  totalCount
) {
  if (error) return console.log("error:", error);

  console.log(totalCount + " archives");
  for (var i = 0; i < archives.length; i++) {
    console.log(archives[i].id);
  }
});

Notez que vous pouvez également créer une session automatiquement archivée, en passant le paramètre 'always' en tant que archiveMode lorsque vous appelez l'option OpenTok.createSession() méthode (voir « Création de sessions », ci-dessus).

Pour les archives composées, vous pouvez modifier la mise en page de manière dynamique, en utilisant la fonction OpenTok.setArchiveLayout(archiveId, type, stylesheet, screenshareType, callback) méthode :

opentok.setArchiveLayout(archiveId, type, null, null, function (err) {
  if (err) return console.log("error:", error);
});

Vous pouvez définir la classe de mise en page initiale pour les flux d'un client en définissant la propriété layout lorsque lorsque vous créez le jeton pour le client, à l'aide de l'option OpenTok.generateToken() méthode. Et vous pouvez modifier les classes de présentation pour les flux d'une session en appelant la méthode OpenTok.setStreamClassLists(sessionId, classListArray, callback) méthode.

La définition de la mise en page des archives composées est facultative. Par défaut, les archives composées utilisent la mise en page "best fit" (voir Personnalisation de la mise en page vidéo pour les composées).

Pour plus d'informations sur l'archivage, consultez le Guide du développeur sur l'archivage OpenTok.

Travailler avec des émissions en direct

Important : Seulement sessions OpenTok acheminées prendre en charge les diffusions en direct.

Pour démarrer un diffusion en direct diffusion télévisée d'une session OpenTok, appelez la OpenTok.startBroadcast() méthode. Transmettez-lui trois paramètres : l'identifiant de session correspondant à la session, les options de diffusion et une fonction de rappel :

var broadcastOptions = {
  outputs: {
    hls: {},
    rtmp: [
      {
        id: "foo",
        serverUrl: "rtmp://myfooserver/myfooapp",
        streamName: "myfoostream",
      },
      {
        id: "bar",
        serverUrl: "rtmp://mybarserver/mybarapp",
        streamName: "mybarstream",
      },
    ],
  },
  maxDuration: 5400,
  resolution: "640x480",
  layout: {
    type: "verticalPresentation",
  },
};
opentok.startBroadcast(sessionId, broadcastOptions, function (
  error,
  broadcast
) {
  if (error) {
    return console.log(error);
  }
  return console.log("Broadcast started: ", broadcast.id);
});

Voir la référence de l'API pour plus de détails sur la fonction options paramètre.

En cas de succès, un objet Broadcast est transmis à la fonction de rappel en tant que deuxième paramètre. L'objet Broadcast possède des propriétés qui définissent la diffusion, y compris un paramètre broadcastUrls qui contient les URL des flux de diffusion. Voir la référence de l'API pour plus de détails.

Appeler le OpenTok.stopBroadcast() pour arrêter une diffusion en continu en direct, passez l'identifiant de la diffusion (l'ID de la diffusion). (l'identifiant de la diffusion). id de l'objet Broadcast) comme premier paramètre. Le second est la fonction de rappel :

opentok.stopBroadcast(broadcastId, function (error, broadcast) {
  if (error) {
    return console.log(error);
  }
  return console.log("Broadcast stopped: ", broadcast.id);
});

Vous pouvez également appeler le stop() de l'objet Broadcast pour arrêter une diffusion.

Appeler le Opentok.getBroadcast() en indiquant l'ID de la diffusion, pour obtenir un objet de diffusion.

Vous pouvez également obtenir une liste de toutes les diffusions que vous avez créées (jusqu'à 1000) avec votre clé API. Cette opération s'effectue à l'aide de la à l'aide de la fonction OpenTok.listBroadcasts(options, callback) méthode. Le paramètre options est un est un objet optionnel utilisé pour spécifier un offset, countet sessionId pour vous aider à paginer dans les résultats. Le callback a une signature function(err, broadcasts, totalCount). Les broadcasts renvoyée par le rappel est un tableau de Broadcast instances. Les totalCount La valeur renvoyée par la fonction de rappel correspond au nombre total de diffusions générées par votre clé API.

opentok.listBroadcasts({ offset: 100, count: 50 }, function (
  error,
  broadcasts,
  totalCount
) {
  if (error) return console.log("error:", error);

  console.log(totalCount + " broadcasts");
  for (var i = 0; i < broadcasts.length; i++) {
    console.log(broadcasts[i].id);
  }
});

Pour modifier l'agencement de la diffusion, appelez l'option OpenTok.setBroadcastLayout() méthode, en transmettant l'ID de diffusion et le modèle type.

Vous pouvez définir la classe de mise en page initiale pour les flux d'un client en définissant la propriété layout lorsque lorsque vous créez le jeton pour le client, à l'aide de l'option OpenTok.generateToken() méthode. Et vous pouvez modifier les classes de présentation pour les flux d'une session en appelant la méthode OpenTok.setStreamClassLists(sessionId, classListArray, callback) méthode.

La configuration de la mise en page d'une diffusion en direct est facultative. Par défaut, les diffusions en direct utilisent la mise en page « best fit ».

Envoi de signaux

Vous pouvez envoyer un signal à tous les participants d'une session OpenTok en appelant la fonction OpenTok.signal(sessionId, connectionId, payload, callback) et de définir la connectionId au paramètre null:

var sessionId =
  "2_MX2xMDB-flR1ZSBOb3YgMTkgMTE6MDk6NTggUFNUIDIwMTN-MC2zNzQxNzIxNX2";
opentok.signal(sessionId, null, { type: "chat", data: "Hello!" }, function (
  error
) {
  if (error) return console.log("error:", error);
});

Vous pouvez également envoyer un signal à un participant spécifique de la session en appelant la fonction OpenTok.signal(sessionId, connectionId, payload, callback) et de définir tous les paramètres, y compris connectionId:

var sessionId =
  "2_MX2xMDB-flR1ZSBOb3YgMTkgMTE6MDk6NTggUFNUIDIwMTN-MC2zNzQxNzIxNX2";
var connectionId = "02e80876-02ab-47cd-8084-6ddc8887afbc";
opentok.signal(
  sessionId,
  connectionId,
  { type: "chat", data: "Hello!" },
  function (error) {
    if (error) return console.log("error:", error);
  }
);

Il s'agit de l'équivalent côté serveur de la méthode signal() des SDK clients OpenTok. Voir Guide du développeur sur la signalisation OpenTok.

Déconnexion des participants

Vous pouvez déconnecter des participants d'une session OpenTok à l'aide de la commande OpenTok.forceDisconnect(sessionId, connectionId, callback) méthode.

opentok.forceDisconnect(sessionId, connectionId, function (error) {
  if (error) return console.log("error:", error);
});

Il s'agit de l'équivalent côté serveur de la méthode `forceDisconnect()` dans OpenTok.js : Guide de modération d'OpenTok.js.

Forcer les clients d'une session à couper le son publié

Vous pouvez forcer l'éditeur d'un flux spécifique à cesser de publier de l'audio à l'aide de la commande Opentok.forceMuteStream(sessionId)méthode.

Vous pouvez forcer l'éditeur de tous les flux d'une session (à l'exception d'une liste optionnelle de flux) à cesser de publier de l'audio à l'aide de la commande Opentok.forceMuteAll() et de la méthode de la sourdine. Vous pouvez ensuite désactiver la mise en sourdine de la session en appelant la méthode Opentok.disableForceMute() méthode.

Travailler avec SIP Interconnect

Vous pouvez ajouter un flux audio uniquement provenant d'une passerelle SIP tierce externe à l'aide de la fonctionnalité « SIP Interconnect ». Pour cela, vous devez disposer d'un URI SIP, de l'identifiant de session auquel vous souhaitez ajouter le flux audio uniquement, ainsi que d'un jeton permettant de se connecter à cet identifiant de session.

var options = {
  from: "15551115555",
  secure: true,
};
opentok.dial(sessionId, token, sipUri, options, function (error, sipCall) {
  if (error) return console.log("error: ", error);

  console.log(
    "SIP audio stream Id: " +
      sipCall.streamId +
      " added to session ID: " +
      sipCall.sessionId
  );
});

Pour plus d'informations, voir le Guide du développeur OpenTok SIP Interconnect.

Obtenir des informations sur les flux

Vous pouvez obtenir des informations sur un flux actif au cours d'une session OpenTok :

var sessionId =
  "2_MX6xMDB-fjE1MzE3NjQ0MTM2NzZ-cHVTcUIra3JUa0kxUlhsVU55cTBYL0Y1flB";
var streamId = "2a84cd30-3a33-917f-9150-49e454e01572";
opentok.getStream(sessionId, streamId, function (error, streamInfo) {
  if (error) {
    console.log(error.message);
  } else {
    console.log(stream.id); // '2a84cd30-3a33-917f-9150-49e454e01572'
    console.log(stream.videoType); // 'camera'
    console.log(stream.name); // 'Bob'
    console.log(stream.layoutClassList); // ['main']
  }
});

Transmettez un identifiant de session, un identifiant de flux et une fonction de rappel à la OpenTok.getStream() méthode. La fonction de rappel est appelée une fois l'opération terminée. Elle prend deux paramètres : error (en cas d'erreur) ou stream. Une fois l'opération terminée avec succès, le stream objet est défini, contenant les propriétés du flux.

Pour obtenir des informations sur tous flux actifs au cours d'une session, appeler la fonction OpenTok.listStreams() méthode, en lui transmettant un identifiant de session et une fonction de rappel. En cas de réussite, la fonction de rappel est appelée avec un tableau d'objets Stream transmis en tant que deuxième paramètre :

opentok.listStreams(sessionId, function(error, streams) {
  if (error) {
    console.log(error.message);
  } else {
    streams.map(function(stream) {
      console.log(stream.id); // '2a84cd30-3a33-917f-9150-49e454e01572'
      console.log(stream.videoType); // 'camera'
      console.log(stream.name); // 'Bob'
      console.log(stream.layoutClassList); // ['main']
    }));
  }
});

Utilisation d'Audio Connector

Vous pouvez lancer un Connecteur audio WebSocket en appelant la fonction OpenTok.websocketConnect() méthode.

Exigences

Vous avez besoin d'une clé API OpenTok et d'un secret API, que vous pouvez obtenir en vous connectant à votre Compte Video API de Vonage.

Le SDK OpenTok pour Node.js nécessite Node.js 6 ou une version ultérieure. Il peut fonctionner sur des versions antérieures, mais celles-ci ne font plus l'objet de tests.

Notes de mise à jour

Voir le Page des communiqués de presse pour plus de détails sur chaque version.

Modifications importantes depuis la version 2.2.0

Modifications apportées à la version 2.2.3 :

Le paramètre par défaut pour le createSession() La méthode consiste à créer une session avec le mode multimédia défini sur « relayed ». Dans les versions précédentes du SDK, le paramètre par défaut consistait à utiliser le routeur multimédia OpenTok (mode multimédia défini sur « routed »). Dans une session en mode « relayed », les clients tentent d’échanger des flux directement entre eux (peer-to-peer) ; si les clients ne parviennent pas à se connecter en raison de restrictions de pare-feu, la session utilise le serveur TURN d’OpenTok pour relayer les flux audio et vidéo.

Nouveautés de la version 2.2.0 :

Cette version du SDK permet de travailler avec les archives OpenTok.

Les createSession() La méthode a été modifiée pour accepter un seul paramètre : un options objet qui possède location et mediaMode propriétés. Le mediaMode remplace la propriété properties.p2p.preference paramètre dans la version précédente du SDK.

Les generateToken() a été modifiée pour accepter deux paramètres : l'identifiant de session et un options objet qui possède role, expireTime et data propriétés.