Video API Vonage – Kit de développement logiciel (SDK) .NET

Le SDK OpenTok .NET propose des méthodes permettant de :

Installation

NuGet (recommandé) :

L'utilisation de la Console du gestionnaire de paquets:

PM> Install-Package OpenTok

Manuellement :

Téléchargez la dernière version depuis le Page des communiqués de presse. Décompressez le fichier et placez le OpenTok.dll, les assemblages dépendants et les fichiers associés dans votre propre projet.

Utilisation

Initialisation

Importer le OpenTokSDK espace de noms dans tous les fichiers qui utiliseront des objets OpenTok. Ensuite, initialisez un OpenTokSDK.OpenTok objet en utilisant votre propre clé API et votre secret API.

using OpenTokSDK;

// ...

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

Remplacer la valeur « user-agent » de la requête

Vous pouvez choisir d'ajouter une valeur personnalisée à la valeur « user-agent » transmise à chaque requête.

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

Si la valeur personnalisée a été définie, l'agent utilisateur respectera le format suivant : Opentok-DotNet-SDK/{version}/{customValue}.

Création de sessions

Pour créer une session OpenTok, appelez la méthode OpenTok de l'instance CreateSession(string location, MediaMode mediaMode, ArchiveMode archiveMode) ou CreateSessionAsync(string location, MediaMode mediaMode, ArchiveMode archiveMode) méthode. Chacun de ces paramètres est facultatif et peut être omis s'il n'est pas nécessaire. Il s'agit des paramètres suivants :

  • string location : Une adresse IPv4 servant d'indication de localisation. (par défaut : « »)

  • MediaMode mediaMode : Indique si la session utilisera le routeur multimédia OpenTok (MediaMode.ROUTED) ou tentera de transmettre les flux directement entre les clients (MediaMode.RELAYED, valeur par défaut)

  • ArchiveMode archiveMode : Spécifie si la session sera automatiquement archivée (ArchiveMode.ALWAYS) ou non (ArchiveMode.MANUAL, par défaut). (ArchiveMode.ALWAYS) ou non (ArchiveMode.MANUAL, par défaut)

La valeur de retour est un OpenTokSDK.Session objet. Son Id Cette propriété est utile pour obtenir un identifiant pouvant être enregistré dans un stockage persistant (tel qu'une base de données).

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

Générer des jetons

Une fois la session créée, vous pouvez commencer à générer des jetons que les clients utiliseront pour s'y connecter. Vous pouvez générer un jeton soit en appelant une OpenTokSDK.OpenTok de l'instance GenerateToken(string sessionId, Role role, double expireTime, string data) méthode, ou en appelant une OpenTokSDK.Session de l'instance GenerateToken(Role role, double expireTime, string data) méthode après l'avoir créée. Dans la première méthode, la sessionId est obligatoire, les autres paramètres étant facultatifs. Dans la deuxième méthode, tous les paramètres sont facultatifs.


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

Travailler avec les archives

Vous pouvez lancer l'enregistrement d'une session OpenTok à l'aide d'un OpenTokSDK.OpenTok de l'instance StartArchive(sessionId, name, hasVideo, hasAudio, outputMode, resolution) méthode. Cela renverra un OpenTokSDK.Archive par exemple. Le paramètre name est facultatif et sert à attribuer un nom à l' archive. Notez que vous ne pouvez lancer une archive que sur une session à laquelle des clients sont connectés.

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

ou

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

puis

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

Vous pouvez attribuer un nom à l'archive (à des fins d'identification) en définissant le name paramètre de la OpenTok.StartArchive() méthode.

Vous pouvez également désactiver l'enregistrement audio ou vidéo en réglant le paramètre hasAudio ou hasVideo paramètre de la OpenTok.StartArchive() méthode false.

Vous pouvez également régler la résolution de l'enregistrement en haute définition en configurant le resolution du paramètre OpenTok.StartArchive() méthode. Les valeurs acceptées sont « 640x480 » (SD en mode paysage, valeur par défaut), « 1280x720 » (HD en mode paysage), « 1920x1080 » (FHD en mode paysage), « 480x640 » (SD en mode portrait), « 720x1280 » (HD en mode portrait) ou « 1080x1920 » (FHD en mode portrait). Veuillez noter que vous ne pouvez pas spécifier la resolution lorsque vous réglez le outputMode au paramètre OutputMode.INDIVIDUAL.

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 du paramètre OpenTok.StartArchive() méthode OutputMode.INDIVIDUAL.

Vous pouvez interrompre l'enregistrement d'une archive déjà lancée à l'aide d'un OpenTokSDK.OpenTok de l'instance StopArchive(String archiveId) méthode ou en utilisant le OpenTokSDK.Archive de l'instance Stop() méthode.

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

ou

var archive = OpenTok.StopArchiveAsync(archiveId);

Pour obtenir un OpenTokSDK.Archive (et toutes les informations la concernant) à partir d'un ID d'archive, utilisez la commande OpenTokSDK.OpenTok de l'instance GetArchive(archiveId) méthode.

var archive = OpenTok.GetArchive(archiveId);

ou

var archive = OpenTok.GetArchiveAsync(archiveId);

Pour supprimer une archive, vous pouvez appeler une OpenTokSDK.OpenTok de l'instance DeleteArchive(archiveId) méthode ou appeler la OpenTokSDK.Archive de l'instance Delete() méthode.

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

ou

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

Vous pouvez également obtenir la liste de toutes les archives que vous avez créées (jusqu'à 1 000) à l'aide de votre clé API. Pour cela, il suffit d'utiliser une OpenTokSDK.OpenTok de l'instance ListArchives(int offset, int count) méthode. Vous pouvez, si vous le souhaitez, pager les archives que vous recevez à l'aide des paramètres « offset » et « count ». Cela renverra un OpenTokSDK.ArchiveList objet.

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

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

Travailler avec des flux

Vous pouvez obtenir des informations sur un flux en appelant la fonction GetStream(sessionId, streamId) de la méthode OpenTok classe.

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

Vous pouvez obtenir des informations sur tous les flux d'une session en appelant la fonction ListStreams(sessionId) de la méthode OpenTok classe.

StreamList streamList = OpenTok.ListStreams(sessionId);

streamList.Count; // total count

Forcer la déconnexion

Votre serveur d'applications peut déconnecter un client d'une session OpenTok en appelant la méthode ForceDisconnect(sessionId, connectionId) de la méthode OpenTok classe.

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

Envoi de signaux

Une fois qu'une session est créée, vous pouvez envoyer des signaux à tous les participants à la session ou à une connexion spécifique. Vous pouvez envoyer un signal en appelant la fonction Signal(sessionId, signalProperties, connectionId) de la méthode OpenTok classe.

Les sessionId est l'identifiant de la session.

Les signalProperties Le paramètre est une instance de la classe SignalProperties classe dans laquelle vous pouvez définir le data paramètre et le type paramètre.

  • data (chaîne de caractères) -- La chaîne de caractères contenant les données du signal. Vous pouvez envoyer jusqu'à 8 ko.
  • type (chaîne de caractères) -- (Facultatif) La chaîne de caractères indiquant le type du signal. Vous pouvez envoyer jusqu'à 128 caractères ; seuls les caractères suivants sont autorisés : A-Z, a-z, les Numbers (0-9), « - », « _ » et « ~ ».

Les connectionId Le paramètre est une chaîne de caractères facultative permettant de spécifier l'identifiant de connexion d'un client connecté à la session. Si vous indiquez cette valeur, le signal est envoyé au client spécifié. Dans le cas contraire, le signal est envoyé à tous les clients connectés à la session.

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

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

Travailler avec des émissions en direct

Vous pouvez lancer une diffusion en direct d'une session OpenTok à l'aide d'un OpenTokSDK.OpenTok de l'instance StartBroadcast(sessionId, hls, rtmpList, resolution, maxDuration, layout) méthode. Celle-ci renvoie un OpenTokSDK.Broadcast instance.

Voir également la documentation relative à l'option Opentok.StopBroadcast() et OpenTok.GetBroadcast() des méthodes.

SIP

Vous pouvez connecter une plateforme SIP à une session OpenTok à l'aide de la Opentok.Dial(sessionId, token, sipUri, options) ou Opentok.DialAsync(sessionId, token, sipUri, options) méthode.

Vous pouvez envoyer des chiffres DTMF à tous les participants d'une session OpenTok active, ou à un client spécifique connecté à cette session, à l'aide de la commande Opentok.PlayDTMF(sessionId, digits, connectionId) ou Opentok.PlayDTMFAsync(sessionId, digits, connectionId) méthode.

Forcer les clients d'une session à se déconnecter ou à mettre en sourdine l'audio publié

Vous pouvez forcer un client spécifique à se déconnecter d'une session OpenTok à l'aide de la commande Opentok.ForceDisconnect(sessionId, connectionId) méthode.

Vous pouvez forcer l'éditeur d'un flux spécifique à cesser de publier de l'audio à l'aide de la commande Opentok.ForceMuteStream(sessionId, stream) ou Opentok.ForceMuteStreamAsync(sessionId, stream)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(sessionId, excludedStreamIds) ou Opentok.ForceMuteAllAsync(sessionId, excludedStreamIds) 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(sessionId) ou Opentok.DisableForceMuteAsync(sessionId) méthode.

Compositeur d'expérience

Vous pouvez lancer un Compositeur d'expérience afficher à l'aide de la Opentok.StartRenderAsync() méthode :

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

Pour arrêter un moteur de rendu, appelez la fonction Opentok.StopRenderAsync() méthode.

Pour afficher la liste des moteurs de rendu, appelez la fonction Opentok.ListRendersAsync() méthode.

Utilisation d'Audio Connector

Vous pouvez lancer un Flux « Audio Connector » en appelant le OpenTok.StartAudioConnectorAsync(AudioConnectorStartRequest request)méthode :

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

Modification du délai d'expiration des requêtes HTTP

Si vous souhaitez modifier les délais d'expiration des requêtes HTTP envoyées par le Client SDK, vous pouvez le faire en appelant la méthode OpenTok.SetDefaultRequestTimeout(int timeout) — notez que le délai d'expiration est exprimé en millisecondes.

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

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 .NET nécessite .NET Framework 4.5.2 ou une version ultérieure.

REMARQUE : sous la version 4.5.2, TLS 1.2 n'est pas activé par défaut. Vous devez utiliser une commande similaire à celle ci-dessous pour forcer le moteur d'exécution à utiliser au moins TLS 1.2.

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Sinon, si votre application dépend d'une autre version de TLS pour d'autres API, vous pouvez également ajouter TLS à la liste des méthodes prises en charge à l'aide d'un OU binaire :

ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;

Notes de mise à jour

Voir le Communiqués page pour plus de détails sur chaque sortie.

Modifications importantes depuis la version 2.2.0

Nouveautés de la version 3.0.0 :

Cette version nécessite .NET Framework 4.5.2 ou une version ultérieure.

Modifications apportées à la version 2.2.1 :

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.

Cette version du SDK comporte plusieurs améliorations au niveau de la conception de l'API. Parmi celles-ci figurent plusieurs modifications apportées à l'API :

  • Nouvelle classe OpenTok — Le nom de la classe principale est passé de « OpenTokSDK » à « OpenTok ». Dans la version précédente, le constructeur était OpenTokSDK(). Dans la version 2.2, c'est OpenTok(int apiKey, int apiSecret).

  • CreateSession -- Dans la version précédente, il existait deux méthodes pour créer une session : OpenTokSDK.CreateSession(String location) et OpenTokSDK.CreateSession(String location, Dictionary<string, object> options). Ces méthodes renvoyaient une chaîne de caractères (l'identifiant de session).

    Dans la version 2.2, la classe OpenTok comprend une méthode qui prend deux paramètres (tous deux facultatifs) : CreateSession(string location = "", MediaMode mediaMode = MediaMode.ROUTED). Les mediaMode Le paramètre remplace le p2p.preference paramètre de la version précédente. La méthode renvoie un objet Session.

  • GenerateToken -- Dans la version précédente, il existait deux méthodes : OpenTokSDK.GenerateToken(string sessionId) et OpenTokSDK.GenerateToken(string sessionId, Dictionary<string, object> options) Dans la version 2.2, celle-ci est remplacée par la méthode suivante : OpenTokSDK.OpenTok.GenerateToken(string sessionId, Role role = Role.PUBLISHER, double expireTime = 0, string data = null). Tous les paramètres, à l'exception du sessionId paramètre, sont facultatifs.

    Par ailleurs, la classe `Session` comprend une méthode permettant de générer des jetons : OpenTokSDK.Session.GenerateToken(Role role = Role.PUBLISHER, double expireTime = 0, string data = null).