Vonage Video API Node SDK

• SDK-Übersicht
• API-Referenz
• Herunterladen
• Beispiele
• GitHub

Das OpenTok Node SDK bietet Methoden für:

• Erzeugen von Sitzungen und Token für OpenTok Applications
• Arbeiten mit OpenTok Archiv
• Arbeiten mit OpenTok Live-Streaming-Übertragungen
• Arbeiten mit OpenTok SIP-Zusammenschaltung
• Senden von Signalen an Clients, die mit einer Sitzung verbunden sind
• Trennen von Kunden von Sitzungen
• Erzwingen, dass Clients in einer Sitzung die Verbindung unterbrechen oder das veröffentlichte Audio stummschalten
• Arbeiten mit Audio-Anschluss

Installation mit npm (empfohlen):

npm hilft bei der Verwaltung von Abhängigkeiten für Node-Projekte. Weitere Informationen finden Sie hier: http://npmjs.org.

Führen Sie diesen Befehl aus, um das Paket zu installieren und es zu Ihrem package.json:

$ npm install opentok --save

Verwendung

Initialisierung

Importieren Sie das Modul, um eine Konstruktorfunktion für ein OpenTok-Objekt zu erhalten, und rufen Sie diese anschließend mit new um ein OpenTok-Objekt mit Ihrem eigenen API-Schlüssel und API-Geheimnis zu instanziieren.

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

Timeouts erhöhen

Die Bibliothek verwendet derzeit ein Timeout von 20 Sekunden für Anfragen. Wenn Sie sich in einem langsamen Netzwerk befinden und das Timeout verlängern müssen, können Sie den Wert (in Millisekunden) bei der Instanziierung des OpenTok-Objekts übergeben.

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

Sitzungen erstellen

Um eine OpenTok-Sitzung zu erstellen, verwenden Sie die OpenTok.createSession(properties, callback) Methode. Die Website properties Der Parameter ist ein optionales Objekt, mit dem festgelegt wird, ob die Sitzung den OpenTok Media Router verwendet, ein Standorthinweis angegeben wird und ob die Sitzung automatisch archiviert wird oder nicht. Der Callback hat die folgende Signatur: function(error, session). Die session Die im Callback zurückgegebene Instanz ist eine Instanz von „Session“. „Session“-Objekte verfügen über eine sessionId Eigenschaft, die es die in einem dauerhaften Speicher (z. B. einer Datenbank) gespeichert werden sollen.

// 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);
});

Token generieren

Sobald eine Sitzung erstellt ist, können Sie damit beginnen, Token zu erzeugen, die die Clients bei der Verbindung mit der Sitzung verwenden können. Sie können ein Token erzeugen, indem Sie die Funktion OpenTok.generateToken(sessionId, options) Methode. Eine weitere Möglichkeit besteht darin, die generateToken(options) Methode eines Session-Objekts. Die options „parameter“ ist ein optionales Objekt, mit dem die Rolle, die Gültigkeitsdauer und die Verbindungsdaten des Tokens festgelegt werden können. Zur Steuerung des Layouts in Archiven und Sendungen kann zudem die anfängliche Liste der Layoutklassen für Streams festgelegt werden, die über Verbindungen unter Verwendung dieses Tokens veröffentlicht werden.

// 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"],
});

Arbeit mit Archiven

Sie können die Aufzeichnung einer OpenTok-Sitzung über die OpenTok.startArchive(sessionId, options, callback) Methode. Die Website options „parameter“ ist ein optionales Objekt, mit dem der Name des Archivs festgelegt wird. Der Callback hat folgende Signatur: function(err, archive). Die archive Das, was im Callback zurückgegeben wird, ist eine Instanz von Archive. Beachten Sie, dass Sie ein Archiv nur in einer Sitzung mit verbundenen Clients starten können.

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);
  }
});

Sie können die Audio- oder Videoaufzeichnung auch deaktivieren, indem Sie die Option hasAudio oder hasVideo Eigenschaft der der options Parameter zu 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);
  }
});

Standardmäßig werden alle Streams in einer einzigen (zusammengesetzten) Datei aufgezeichnet. Sie können die verschiedenen Streams in der Sitzung in einzelnen Dateien (statt in einer einzigen zusammengesetzten Datei) aufzeichnen, indem Sie den Parameter outputMode Option zu 'individual' wenn Sie die OpenTok.startArchive() Methode:

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);
  }
});

Sie können die Aufzeichnung eines gestarteten Archivs mit der Taste OpenTok.stopArchive(archiveId, callback) Methode. Sie können dies auch mithilfe der Archive.stop(callback) Methode a Archive Beispiel. Der Callback hat folgende Signatur function(err, archive). Die archive Der im Callback zurückgegebene Wert ist eine Instanz von 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);
});

Um eine Archive Instanz (und alle Informationen darüber) aus einer archiveIdverwenden Sie die OpenTok.getArchive(archiveId, callback) Methode. Der Callback hat folgende Funktionssignatur function(err, archive). Weitere Informationen finden Sie in den Eigenschaften des Archivs.

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

  console.log(archive);
});

Um ein Archiv zu löschen, können Sie die Funktion OpenTok.deleteArchive(archiveId, callback) Methode oder die delete(callback) Methode eines Archive Beispiel. Der Callback hat folgende Signatur 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);
});

Sie können auch eine Liste aller Archive abrufen, die Sie mit Ihrem API-Schlüssel erstellt haben (bis zu 1000). Dies geschieht mit der Funktion OpenTok.listArchives(options, callback) Methode. Der Parameter options ist ein optionales Objekt, das zur Angabe einer offset und count um Ihnen das Paginieren durch die Ergebnisse zu erleichtern. Der Callback hat eine Signatur function(err, archives, totalCount). Die archives zurückgegeben von der Rückruf ist ein Array von Archive Instanzen. Die totalCount Der vom Callback zurückgegebene Wert ist die Gesamtzahl der Archive, die Ihr API-Schlüssel generiert hat.

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);
  }
});

Beachten Sie, dass Sie auch eine automatisch archivierte Sitzung erstellen können, indem Sie in 'always' als die archiveMode wenn Sie die Option OpenTok.createSession() Methode (siehe „Erstellen von Sitzungen“ weiter oben).

Für zusammengesetzte Archive können Sie das Layout dynamisch ändern, indem Sie die OpenTok.setArchiveLayout(archiveId, type, stylesheet, screenshareType, callback) Methode:

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

Sie können die anfängliche Layoutklasse für die Streams eines Clients festlegen, indem Sie die layout Option, wenn Sie das Token für den Client erstellen, indem Sie die OpenTok.generateToken() Methode. Und Sie können die Layoutklassen für Streams in einer Sitzung ändern, indem Sie die OpenTok.setStreamClassLists(sessionId, classListArray, callback) Methode.

Die Festlegung des Layouts von zusammengestellten Archiven ist optional. Standardmäßig verwenden zusammengestellte Archive das "best fit" Layout (siehe Anpassen des Videolayouts für zusammengesetzte Archive).

Weitere Informationen zur Archivierung finden Sie unter OpenTok-Entwicklerhandbuch zur Archivierung.

Arbeiten mit Live-Streaming-Übertragungen

Das ist wichtig: Nur weitergeleitete OpenTok-Sitzungen Live-Streaming-Übertragungen unterstützen.

Zum Starten einer Live-Streaming Übertragung einer OpenTok-Sitzung, rufen Sie die OpenTok.startBroadcast() Methode. Übergeben Sie drei Parameter: die Sitzungs-ID für die Sitzung, Optionen für die Übertragung und eine Callback-Funktion:

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);
});

Siehe die API-Referenz für Details über die options Parameter.

Bei Erfolg wird ein Broadcast-Objekt als zweiter Parameter an die Callback-Funktion übergeben. Das Broadcast-Objekt hat Eigenschaften, die den Broadcast definieren, einschließlich einer broadcastUrls Eigenschaft, die URLs für die Broadcast-Streams enthält. Siehe die API-Referenz für Details.

Rufen Sie die OpenTok.stopBroadcast() Methode, um eine Live-Streaming-Übertragung zu stoppen, geben Sie die Broadcast-ID (die id Eigenschaft des Broadcast-Objekts) als ersten Parameter. Der zweite Parameter ist die Rückruffunktion:

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

Sie können auch die stop() Methode des Broadcast-Objekts, um einen Broadcast zu stoppen.

Rufen Sie die Opentok.getBroadcast() Methode und geben Sie eine Broadcast-ID ein, um ein Broadcast-Objekt zu erhalten.

Sie können auch eine Liste aller Sendungen abrufen, die Sie mit Ihrem API-Schlüssel erstellt haben (bis zu 1000). Dies geschieht erfolgt über die OpenTok.listBroadcasts(options, callback) Methode. Der Parameter options ist ein optionales Objekt, das zur Angabe einer offset, countund sessionId um Ihnen das Paginieren durch die Ergebnisse zu erleichtern. Der Callback hat eine Signatur function(err, broadcasts, totalCount). Die broadcasts zurückgegeben von der Rückruf ist ein Array von Broadcast Instanzen. Die totalCount Der vom Callback zurückgegebene Wert ist die Gesamtzahl der Broadcasts, die Ihr API-Schlüssel generiert hat.

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);
  }
});

Um das Broadcast-Layout zu ändern, rufen Sie die Funktion OpenTok.setBroadcastLayout() Methode, Übergabe der Broadcast-ID und des Layout Typ.

Sie können die anfängliche Layoutklasse für die Streams eines Clients festlegen, indem Sie die layout Option, wenn Sie das Token für den Client erstellen, indem Sie die OpenTok.generateToken() Methode. Und Sie können die Layoutklassen für Streams in einer Sitzung ändern, indem Sie die OpenTok.setStreamClassLists(sessionId, classListArray, callback) Methode.

Die Festlegung des Layouts einer Live-Streaming-Übertragung ist optional. Standardmäßig verwenden Live-Streaming-Übertragungen das Layout „Best Fit“.

Senden von Signalen

Sie können ein Signal an alle Teilnehmer einer OpenTok-Sitzung senden, indem Sie die OpenTok.signal(sessionId, connectionId, payload, callback) Methode und Einstellung die connectionId Parameter zu null:

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

Oder senden Sie ein Signal an einen bestimmten Teilnehmer der Sitzung, indem Sie die Funktion OpenTok.signal(sessionId, connectionId, payload, callback) Methode und Einstellung aller Parameter, einschließlich 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);
  }
);

Dies ist das serverseitige Äquivalent zur Methode „signal()“ in den OpenTok-Client-SDKs. Siehe OpenTok-Entwicklerhandbuch zur Signalisierung.

Trennen von Teilnehmern

Sie können Teilnehmer aus einer OpenTok-Sitzung trennen, indem Sie die OpenTok.forceDisconnect(sessionId, connectionId, callback) Methode.

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

Dies ist das serverseitige Äquivalent zur Methode `forceDisconnect()` in OpenTok.js: OpenTok.js-Leitfaden zur Moderation.

Erzwingen, dass Clients in einer Sitzung das veröffentlichte Audio stummschalten

Sie können den Herausgeber eines bestimmten Streams zwingen, die Veröffentlichung von Audio zu beenden, indem Sie die Opentok.forceMuteStream(sessionId)Methode.

Sie können den Herausgeber aller Streams in einer Sitzung (mit Ausnahme einer optionalen Liste von Streams) zwingen die Veröffentlichung von Audio zu beenden, indem Sie die Opentok.forceMuteAll() Methode. Sie können dann den Stummschaltungsstatus der Sitzung deaktivieren, indem Sie die Methode Opentok.disableForceMute() Methode.

Arbeiten mit SIP Interconnect

Mithilfe der Funktion „SIP Interconnect“ können Sie einen reinen Audio-Stream von einem externen SIP-Gateway eines Drittanbieters hinzufügen. Dazu benötigen Sie eine SIP-URI, die Sitzungs-ID, zu der Sie den reinen Audio-Stream hinzufügen möchten, sowie ein Token, um eine Verbindung zu dieser Sitzungs-ID herzustellen.

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
  );
});

Weitere Informationen finden Sie in der OpenTok SIP Interconnect – Entwicklerhandbuch.

Stream-Informationen abrufen

Sie können Informationen zu einem aktiven Stream in einer OpenTok-Sitzung abrufen:

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']
  }
});

Übergeben Sie eine Sitzungs-ID, eine Stream-ID und eine Callback-Funktion an die OpenTok.getStream() Methode. Die Callback-Funktion wird aufgerufen, sobald der Vorgang abgeschlossen ist. Sie nimmt zwei Parameter entgegen: error (im Falle eines Fehlers) oder stream. Nach erfolgreichem Abschluss wird die stream Objekt wird gesetzt, das die Eigenschaften des Streams enthält.

Um Informationen zu erhalten über alle aktive Streams in einer Sitzung, rufen Sie die OpenTok.listStreams() Methode, wobei eine Sitzungs-ID und eine Callback-Funktion übergeben werden. Bei Erfolg wird die Callback-Funktion aufgerufen, wobei ein Array von Stream-Objekten als zweiter Parameter übergeben wird:

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']
    }));
  }
});

Arbeiten mit Audio Connector

Sie können ein Audio-Anschluss WebSocket durch Aufruf der OpenTok.websocketConnect() Methode.

Anforderungen

Sie benötigen einen OpenTok-API-Schlüssel und ein API-Geheimnis, die Sie erhalten, indem Sie sich bei Ihrem Vonage Video API-Konto.

Das OpenTok Node SDK erfordert Node.js 6 oder höher. Es funktioniert möglicherweise auch mit älteren Versionen, diese werden jedoch nicht mehr getestet.

Anmerkungen zur Veröffentlichung

Siehe die Seite „Veröffentlichungen“ für weitere Informationen zu den einzelnen Veröffentlichungen.

Wichtige Änderungen seit Version 2.2.0

Änderungen in Version 2.2.3:

Die Standardeinstellung für die createSession() Die Vorgehensweise besteht darin, eine Sitzung zu erstellen, bei der der Medienmodus auf „relayed“ eingestellt ist. In früheren Versionen des SDK war die Standardeinstellung die Verwendung des OpenTok Media Routers (Medienmodus auf „routed“ eingestellt). In einer „relayed“-Sitzung versuchen die Clients, Streams direkt untereinander zu übertragen (Peer-to-Peer); können die Clients aufgrund von Firewall-Einschränkungen keine Verbindung herstellen, nutzt die Sitzung den OpenTok-TURN-Server zur Weiterleitung der Audio- und Videostreams.

Änderungen in Version 2.2.0:

Diese Version des SDK bietet Unterstützung für die Arbeit mit OpenTok-Archiven.

Die createSession() Die Methode wurde so geändert, dass sie nun einen Parameter entgegennimmt: einen options Objekt, das location und mediaMode Eigenschaften. Die mediaMode ersetzt die Eigenschaft properties.p2p.preference Parameter in der vorherigen Version des SDK.

Die generateToken() wird nun mit zwei Parametern aufgerufen: der Sitzungs-ID und einem options Objekt, das role, expireTime und data Eigenschaften.