Vonage Video API .NET SDK

Das OpenTok .NET SDK bietet Methoden für:

Einrichtung

NuGet (empfohlen):

Die Verwendung des Paketmanager-Konsole:

PM> Install-Package OpenTok

Manuell:

Laden Sie die neueste Version von der Seite „Veröffentlichungen“. Entpacken Sie die Datei und legen Sie die OpenTok.dll, abhängige Baugruppen und zugehörige Dateien in Ihr eigenes Projekt.

Verwendung

Initialisierung

Importieren Sie die OpenTokSDK Namespace in alle Dateien ein, die OpenTok-Objekte verwenden werden. Initialisieren Sie anschließend ein OpenTokSDK.OpenTok Objekt unter Verwendung Ihres eigenen API-Schlüssels und API-Geheimnisses.

using OpenTokSDK;

// ...

int ApiKey = 000000; // YOUR API KEY
string ApiSecret = "YOUR API SECRET";
var OpenTok = new OpenTok(ApiKey, ApiSecret);

Den User-Agent-Wert der Anfrage überschreiben

Sie können festlegen, dass dem bei jeder Anfrage übermittelten User-Agent-Wert ein benutzerdefinierter Wert hinzugefügt wird.

var OpenTok = new OpenTok(ApiKey, ApiSecret);
OpenTok.SetCustomUserAgent(customUserAgent);

Wenn der benutzerdefinierte Wert festgelegt wurde, entspricht der User-Agent dem folgenden Format: Opentok-DotNet-SDK/{version}/{customValue}.

Sitzungen erstellen

Um eine OpenTok-Sitzung zu erstellen, rufen Sie die OpenTok Instanz CreateSession(string location, MediaMode mediaMode, ArchiveMode archiveMode) oder CreateSessionAsync(string location, MediaMode mediaMode, ArchiveMode archiveMode) Methode. Jeder der Parameter ist optional und kann weggelassen werden, wenn er nicht benötigt wird. Es handelt sich um folgende Parameter:

  • string location : Eine IPv4-Adresse, die als Hinweis auf den Standort dient. (Standard: „“)

  • MediaMode mediaMode : Legt fest, ob die Sitzung den OpenTok Media Router verwendet (MediaMode.ROUTED) oder versucht, Streams direkt zwischen den Clients zu übertragen (MediaMode.RELAYED, Standardeinstellung)

  • ArchiveMode archiveMode ArchiveMode.ALWAYS: Gibt an, ob die Sitzung automatisch archiviert wird (ArchiveMode.ALWAYS) oder nicht (ArchiveMode.MANUAL, Voreinstellung)

Der Rückgabewert ist ein OpenTokSDK.Session Objekt. Sein Id Diese Eigenschaft ist nützlich, um eine Kennung zu erhalten, die in einem persistenten Speicher (z. B. einer Datenbank) gespeichert werden kann.

// Create a session that will attempt to transmit streams directly between clients
var session = OpenTok.CreateSession();
// Store this sessionId in the database for later use:
string sessionId = session.Id;

// Create a session that uses the OpenTok Media Router (which is required for archiving)
var session = OpenTok.CreateSession(mediaMode: MediaMode.ROUTED);
// Store this sessionId in the database for later use:
string sessionId = session.Id;

// Create an automatically archived session:
var session = OpenTok.CreateSession(mediaMode: MediaMode.ROUTED, ArchiveMode.ALWAYS);
// Store this sessionId in the database for later use:
string sessionId = session.Id;

Token generieren

Sobald eine Sitzung erstellt wurde, können Sie damit beginnen, Token zu generieren, die Clients bei der Verbindung zu dieser Sitzung verwenden können. Sie können ein Token entweder durch Aufruf einer OpenTokSDK.OpenTok Instanz GenerateToken(string sessionId, Role role, double expireTime, string data) Methode oder durch Aufruf einer OpenTokSDK.Session Instanz GenerateToken(Role role, double expireTime, string data) Methode nach deren Erstellung. In der ersten Methode wird die sessionId ist erforderlich, die übrigen Parameter sind optional. Bei der zweiten Methode sind alle Parameter optional.


// Generate a token from a sessionId (fetched from database)
string token = OpenTok.GenerateToken(sessionId);

// Generate a token by calling the method on the Session (returned from CreateSession)
string token = session.GenerateToken();

// Set some options in a token
double inOneWeek = (DateTime.UtcNow.Add(TimeSpan.FromDays(7)).Subtract(new DateTime(1970, 1, 1))).TotalSeconds;
string token = session.GenerateToken(role: Role.MODERATOR, expireTime: inOneWeek, data: "name=Johnny");

Arbeiten mit Archiven

Sie können die Aufzeichnung einer OpenTok-Sitzung mit einem OpenTokSDK.OpenTok Instanz StartArchive(sessionId, name, hasVideo, hasAudio, outputMode, resolution) Methode. Diese gibt ein OpenTokSDK.Archive Beispiel. Der Parameter name ist optional und dient dazu, dem Archiv einen Namen zuzuweisen. Beachten Sie, dass Sie ein Archiv nur in einer Sitzung starten können, mit der Clients verbunden sind.

// A simple Archive (without a name)
var archive = OpenTok.StartArchive(sessionId);

oder

// A simple Archive (without a name)
var archive = await OpenTok.StartArchiveAsync(sessionId);

dann

// Store this archive ID in the database for later use
Guid archiveId = archive.Id;

Sie können einen Namen für das Archiv (zur Identifizierung) hinzufügen, indem Sie die name Parameter von dem OpenTok.StartArchive() Methode.

Sie können die Audio- oder Videoaufzeichnung auch deaktivieren, indem Sie die Option hasAudio oder hasVideo Parameter von dem OpenTok.StartArchive() Methode false.

Sie können die Auflösung der Aufnahme auch auf High Definition einstellen, indem Sie die resolution Parameter des OpenTok.StartArchive() Methode. Zulässige Werte sind „640x480“ (SD im Querformat, Standard), „1280x720“ (HD im Querformat), „1920x1080“ (FHD im Querformat), „480x640“ (SD im Hochformat), „720x1280“ (HD im Hochformat) oder „1080x1920“ (FHD im Hochformat). Bitte beachten Sie, dass Sie die resolution wenn Sie die outputMode Parameter zu OutputMode.INDIVIDUAL.

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 Parameter des OpenTok.StartArchive() Methode OutputMode.INDIVIDUAL.

Sie können die Aufzeichnung eines bereits gestarteten Archivs mit einem OpenTokSDK.OpenTok Instanz StopArchive(String archiveId) Methode oder mithilfe der OpenTokSDK.Archive Instanz Stop() Methode.

// Stop an Archive from an archive ID (fetched from database)
var archive = OpenTok.StopArchive(archiveId);

oder

var archive = OpenTok.StopArchiveAsync(archiveId);

Um eine OpenTokSDK.Archive Instanz (und alle zugehörigen Informationen) aus einer Archiv-ID zu erhalten, verwenden Sie die OpenTokSDK.OpenTok Instanz GetArchive(archiveId) Methode.

var archive = OpenTok.GetArchive(archiveId);

oder

var archive = OpenTok.GetArchiveAsync(archiveId);

Um ein Archiv zu löschen, können Sie eine OpenTokSDK.OpenTok Instanz DeleteArchive(archiveId) Methode oder die OpenTokSDK.Archive Instanz Delete() Methode.

// Delete an archive from an archive ID (fetched from database)
OpenTok.DeleteArchive(archiveId);

// Delete an archive from an Archive instance (returned from GetArchive)
Archive.Delete();

oder

// Delete an archive from an archive ID (fetched from database)
OpenTok.DeleteArchiveAsync(archiveId);

// Delete an archive from an Archive instance (returned from GetArchive)
Archive.DeleteAsync();

Sie können sich außerdem eine Liste aller von Ihnen mit Ihrem API-Schlüssel erstellten Archive (bis zu 1000) anzeigen lassen. Dies erfolgt mithilfe eines OpenTokSDK.OpenTok Instanz ListArchives(int offset, int count) Methode. Optional können Sie die erhaltenen Archive mithilfe der Parameter „offset“ und „count“ paginieren. Dadurch wird ein OpenTokSDK.ArchiveList Objekt.

// Get a list with the first 50 archives created by the API Key
var archives = OpenTok.ListArchives();
var archives = OpenTok.ListArchivesAsync();

// Get a list of the first 50 archives created by the API Key
var archives = OpenTok.ListArchives(0, 50);
var archives = OpenTok.ListArchivesAsync(0, 50);

// Get a list of the next 50 archives
var archives = OpenTok.ListArchives(50, 50);
var archives = OpenTok.ListArchivesAsync(50, 50);

// Get a list of the first 50 archives created for the given sessionId
var archives = OpenTok.ListArchives(sessionId:sessionId);
var archives = OpenTok.ListArchivesAsync(sessionId:sessionId);

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

Arbeiten mit Strömen

Sie können Informationen über einen Stream erhalten, indem Sie die GetStream(sessionId, streamId) Methode der OpenTok Klasse.

Stream stream = OpenTok.GetStream(sessionId, streamId);

// Stream Properties
stream.Id; // string with the stream ID
stream.VideoType; // string with the video type
stream.Name; // string with the name
stream.LayoutClassList; // list with the layout class list

Sie können Informationen über alle Streams in einer Sitzung erhalten, indem Sie die ListStreams(sessionId) Methode der OpenTok Klasse.

StreamList streamList = OpenTok.ListStreams(sessionId);

streamList.Count; // total count

Trennen der Verbindung erzwingen

Ihr Anwendungsserver kann einen Client von einer OpenTok-Sitzung trennen, indem er die ForceDisconnect(sessionId, connectionId) Methode der OpenTok Klasse.

// Force disconnect a client connection
OpenTok.ForceDisconnect(sessionId, connectionId);

Senden von Signalen

Sobald eine Sitzung erstellt ist, können Sie Signale an alle Teilnehmer der Sitzung oder an eine bestimmte Verbindung senden. Sie können ein Signal senden, indem Sie die Funktion Signal(sessionId, signalProperties, connectionId) Methode der OpenTok Klasse.

Die sessionId ist die Sitzungs-ID der Sitzung.

Die signalProperties Der Parameter ist eine Instanz der SignalProperties Klasse, in der Sie die data Parameter und der type Parameter.

  • data (Zeichenkette) – Die Datenzeichenkette für das Signal. Es können maximal 8 kB gesendet werden.
  • type (Zeichenkette) -- (Optional) Die Typzeichenkette für das Signal. Es können maximal 128 Zeichen gesendet werden, wobei nur die folgenden Zeichen zulässig sind: A–Z, a–z, Numbers (0–9), „-“, „_“ und „~“.

Die connectionId Der Parameter ist eine optionale Zeichenkette, mit der die Verbindungs-ID eines mit der Sitzung verbundenen Clients angegeben wird. Wenn Sie diesen Wert angeben, wird das Signal an den angegebenen Client gesendet. Andernfalls wird das Signal an alle mit der Sitzung verbundenen Clients gesendet.

string sessionId = "SESSIONID";
SignalProperties signalProperties = new SignalProperties("data", "type");
OpenTok.Signal(sessionId, signalProperties);

string connectionId = "CONNECTIONID";
OpenTok.Signal(sessionId, signalProperties, connectionId);

Arbeiten mit Live-Streaming-Übertragungen

Sie können eine Live-Übertragung einer OpenTok-Sitzung starten, indem Sie einen OpenTokSDK.OpenTok Instanz StartBroadcast(sessionId, hls, rtmpList, resolution, maxDuration, layout) Methode. Diese gibt ein OpenTokSDK.Broadcast Instanz.

Siehe auch die Dokumentation für das Opentok.StopBroadcast() und OpenTok.GetBroadcast() Methoden.

SIP

Sie können eine SIP-Plattform über die Opentok.Dial(sessionId, token, sipUri, options) oder Opentok.DialAsync(sessionId, token, sipUri, options) Methode.

Sie können DTMF-Ziffern an alle Teilnehmer einer aktiven OpenTok-Sitzung oder an einen bestimmten Client senden, der mit dieser Sitzung verbunden ist, und zwar mithilfe der Opentok.PlayDTMF(sessionId, digits, connectionId) oder Opentok.PlayDTMFAsync(sessionId, digits, connectionId) Methode.

Erzwingen, dass Clients in einer Sitzung die Verbindung unterbrechen oder das veröffentlichte Audio stummschalten

Sie können einen bestimmten Client dazu zwingen, die Verbindung zu einer OpenTok-Sitzung zu trennen, indem Sie die Opentok.ForceDisconnect(sessionId, connectionId) Methode.

Sie können den Herausgeber eines bestimmten Streams zwingen, die Veröffentlichung von Audio zu beenden, indem Sie die Opentok.ForceMuteStream(sessionId, stream) oder Opentok.ForceMuteStreamAsync(sessionId, stream)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(sessionId, excludedStreamIds) oder Opentok.ForceMuteAllAsync(sessionId, excludedStreamIds) Methode. Sie können dann den Stummschaltungsstatus der Sitzung deaktivieren, indem Sie die Methode Opentok.DisableForceMute(sessionId) oder Opentok.DisableForceMuteAsync(sessionId) Methode.

Erlebnis-Komponist

Sie können ein Erlebnis-Komponist mit Hilfe von Opentok.StartRenderAsync() Methode:

string sessionId = "opentok-session-id";
string token = "token-for-opentok-session";
string url = "https://your-render-url/path/";
StartRenderRequest request = new StartRenderRequest(sessionId, token, url);
OpenTok.StartRenderAsync(request);

Um einen Renderer anzuhalten, rufen Sie die Opentok.StopRenderAsync() Methode.

Um die Renderer aufzulisten, rufen Sie die Funktion Opentok.ListRendersAsync() Methode.

Arbeiten mit Audio Connector

Sie können ein Audio-Connector-Stream durch Aufruf der OpenTok.StartAudioConnectorAsync(AudioConnectorStartRequest request)Methode:

var webSocket = new AudioConnectorStartRequest.WebSocket(
    new Uri("wss://service.com/ws-endpoint"),
    new []{"streamId-1", "streamId-2"},
    new Dictionary<string, string>
    {
        {"X-CustomHeader-Key1", "headerValue1"},
        {"X-CustomHeader-Key2", "headerValue2"},
    });
var startRequest = new AudioConnectorStartRequest(sessionId, token, webSocket);
AudioConnector response = await this.OpenTok.StartAudioConnectorAsync(startRequest);

Ändern des Timeouts für HTTP-Anfragen

Wenn Sie die Timeouts für die vom Client SDK gesendeten HTTP-Anfragen anpassen möchten, können Sie dies durch Aufruf von `OpenTok.SetDefaultRequestTimeout(int timeout)` tun – beachten Sie, dass der Timeout-Wert in Millisekunden angegeben wird.

this.OpenTok = new OpenTok(apiKey, apiSecret);
this.OpenTok.SetDefaultRequestTimeout(2000);

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.

Für das OpenTok .NET SDK ist das .NET Framework 4.5.2 oder höher erforderlich.

HINWEIS: Bei Verwendung unter Version 4.5.2 ist TLS 1.2 standardmäßig nicht aktiviert. Sie sollten einen Befehl wie den folgenden verwenden, um die Laufzeitumgebung zu zwingen, mindestens TLS 1.2 zu verwenden.

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Falls Ihre Anwendung für andere APIs auf eine andere TLS-Version angewiesen ist, können Sie TLS alternativ mithilfe eines bitweisen ODER-Operators zur Liste der unterstützten Methoden hinzufügen:

ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;

Anmerkungen zur Veröffentlichung

Siehe die Veröffentlichungen Seite mit weiteren Informationen zu den einzelnen Veröffentlichungen.

Wichtige Änderungen seit Version 2.2.0

Änderungen in Version 3.0.0:

Für diese Version ist das .NET Framework 4.5.2 oder höher erforderlich.

Änderungen in Version 2.2.1:

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.

Diese Version des SDK enthält eine Reihe von Verbesserungen im API-Design. Dazu gehören eine Reihe von API-Änderungen:

  • Neue OpenTok-Klasse – Der Name der Hauptklasse wurde von „OpenTokSDK“ in „OpenTok“ geändert. In der vorherigen Version lautete der Konstruktor OpenTokSDK(). In Version 2.2 ist es OpenTok(int apiKey, int apiSecret).

  • CreateSession – In der vorherigen Version gab es zwei Methoden zum Erstellen einer Sitzung: OpenTokSDK.CreateSession(String location) und OpenTokSDK.CreateSession(String location, Dictionary<string, object> options). Diese Methoden gaben eine Zeichenkette (die Sitzungs-ID) zurück.

    In Version 2.2 enthält die OpenTok-Klasse eine Methode, die zwei Parameter (beide optional) entgegennimmt: CreateSession(string location = "", MediaMode mediaMode = MediaMode.ROUTED). Die mediaMode Der Parameter ersetzt den p2p.preference Einstellung in der vorherigen Version. Die Methode gibt ein Session-Objekt zurück.

  • GenerateToken – In der vorherigen Version gab es zwei Methoden: OpenTokSDK.GenerateToken(string sessionId) und OpenTokSDK.GenerateToken(string sessionId, Dictionary<string, object> options) In Version 2.2 wird dies durch die folgende Methode ersetzt: OpenTokSDK.OpenTok.GenerateToken(string sessionId, Role role = Role.PUBLISHER, double expireTime = 0, string data = null). Alle Parameter, mit Ausnahme des sessionId Parameter sind optional.

    Außerdem enthält die Klasse „Session“ eine Methode zum Generieren von Tokens: OpenTokSDK.Session.GenerateToken(Role role = Role.PUBLISHER, double expireTime = 0, string data = null).