SDK de .NET para la Video API de Vonage

El SDK de OpenTok para .NET ofrece métodos para:

Instalación

NuGet (recomendado):

Utilización de la Consola del gestor de paquetes:

PM> Install-Package OpenTok

De forma manual:

Descarga la última versión desde la Página de comunicados de prensa. Descomprime el archivo y coloca el OpenTok.dll, los ensamblados dependientes y los archivos de apoyo en tu propio proyecto.

Uso

Inicialización de

Importa el OpenTokSDK espacio de nombres en todos los archivos que vayan a utilizar objetos OpenTok. A continuación, inicializa un OpenTokSDK.OpenTok objeto utilizando tu propia clave API y tu secreto API.

using OpenTokSDK;

// ...

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

Sobrescribir el valor de «user-agent» de la solicitud

Puedes optar por añadir un valor personalizado al valor de «user-agent» que se envía con cada solicitud.

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

Si se ha establecido el valor personalizado, el agente de usuario se ajustará al siguiente formato: Opentok-DotNet-SDK/{version}/{customValue}.

Creación de sesiones

Para crear una sesión de OpenTok, llama a la función OpenTok de la instancia CreateSession(string location, MediaMode mediaMode, ArchiveMode archiveMode) o CreateSessionAsync(string location, MediaMode mediaMode, ArchiveMode archiveMode) método. Cada uno de los parámetros es opcional y puede omitirse si no es necesario. Son los siguientes:

  • string location : Una dirección IPv4 que sirve como indicación de ubicación. (por defecto: «»)

  • MediaMode mediaMode : Especifica si la sesión utilizará el OpenTok Media Router (MediaMode.ROUTED) o si intentará transmitir los flujos directamente entre los clientes (MediaMode.RELAYED, el valor por defecto)

  • ArchiveMode archiveMode Especifica si la sesión se archivará automáticamente (ArchiveMode.ALWAYS) o no (ArchiveMode.MANUAL, por defecto). (ArchiveMode.ALWAYS) o no (ArchiveMode.MANUAL, por defecto)

El valor de retorno es un OpenTokSDK.Session objeto. Su Id Esta propiedad resulta útil para obtener un identificador que se pueda guardar en un almacén persistente (como una base de datos).

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

Generación de fichas

Una vez creada una sesión, puedes empezar a generar tokens para que los clientes los utilicen al conectarse a ella. Puedes generar un token llamando a una OpenTokSDK.OpenTok de la instancia GenerateToken(string sessionId, Role role, double expireTime, string data) método, o llamando a un OpenTokSDK.Session de la instancia GenerateToken(Role role, double expireTime, string data) método tras crearlo. En el primer método, el sessionId es obligatorio y el resto de los parámetros son opcionales. En el segundo método, todos los parámetros son opcionales.


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

Trabajar con archivos

Puedes iniciar la grabación de una sesión de OpenTok utilizando un OpenTokSDK.OpenTok de la instancia StartArchive(sessionId, name, hasVideo, hasAudio, outputMode, resolution) método. Esto devolverá un OpenTokSDK.Archive instancia. El parámetro name Es opcional y se utiliza para asignar un nombre al archivo. Ten en cuenta que solo puedes iniciar un archivo en una sesión que tenga clientes conectados.

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

o

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

entonces

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

Puedes añadir un nombre al archivo (que servirá para identificarlo) configurando el name parámetro de el OpenTok.StartArchive() método.

También puedes desactivar la grabación de audio o vídeo configurando la opción hasAudio o hasVideo parámetro de el OpenTok.StartArchive() método false.

También puedes configurar la resolución de la grabación en alta definición seleccionando la opción resolution del OpenTok.StartArchive() método. Los valores admitidos son «640x480» (SD horizontal, el valor predeterminado), «1280x720» (HD horizontal), «1920x1080» (FHD horizontal), «480x640» (SD vertical), «720x1280» (HD vertical) o «1080x1920» (FHD vertical). Ten en cuenta que no puedes especificar el resolution cuando configures el outputMode parámetro a OutputMode.INDIVIDUAL.

De forma predeterminada, todas las secuencias se graban en un único archivo (compuesto). Puedes grabar las diferentes secuencias de la sesión en archivos individuales (en lugar de en un único archivo compuesto) configurando el outputMode del OpenTok.StartArchive() método OutputMode.INDIVIDUAL.

Puedes detener la grabación de un archivo que ya se haya iniciado utilizando un OpenTokSDK.OpenTok de la instancia StopArchive(String archiveId) método o utilizando el OpenTokSDK.Archive de la instancia Stop() método.

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

o

var archive = OpenTok.StopArchiveAsync(archiveId);

Para obtener un OpenTokSDK.Archive (y toda su información) a partir de un ID de archivo, utilice la función OpenTokSDK.OpenTok de la instancia GetArchive(archiveId) método.

var archive = OpenTok.GetArchive(archiveId);

o

var archive = OpenTok.GetArchiveAsync(archiveId);

Para eliminar un archivo, puedes llamar a una OpenTokSDK.OpenTok de la instancia DeleteArchive(archiveId) método o llamar a la OpenTokSDK.Archive de la instancia Delete() método.

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

o

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

También puedes obtener una lista de todos los archivos que hayas creado (hasta 1000) con tu clave API. Para ello, se utiliza un OpenTokSDK.OpenTok de la instancia ListArchives(int offset, int count) método. Si lo deseas, puedes paginación los archivos que recibas utilizando los parámetros «offset» y «count». Esto devolverá un OpenTokSDK.ArchiveList objeto.

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

Tenga en cuenta que también puede crear una sesión archivada automáticamente, pasando en ArchiveMode.ALWAYS como el archiveMode parámetro al llamar a la función OpenTok.CreateSession() método (véase «Creación de sesiones», más arriba).

Trabajar con flujos

Puede obtener información sobre un flujo llamando a la función GetStream(sessionId, streamId) método del OpenTok clase.

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

Puede obtener información sobre todos los flujos de una sesión llamando a la función ListStreams(sessionId) método del OpenTok clase.

StreamList streamList = OpenTok.ListStreams(sessionId);

streamList.Count; // total count

Desconexión forzada

Tu servidor de aplicaciones puede desconectar a un cliente de una sesión de OpenTok llamando a la función ForceDisconnect(sessionId, connectionId) método del OpenTok clase.

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

Envío de señales

Una vez creada una sesión, puedes enviar señales a todos los participantes de la sesión o a una conexión concreta. Para enviar una señal, debes llamar a la función Signal(sessionId, signalProperties, connectionId) método del OpenTok clase.

El sessionId es el ID de la sesión.

El signalProperties El parámetro es una instancia de la SignalProperties clase en la que puedes configurar el data parámetro y el type parámetro.

  • data (cadena de caracteres) -- La cadena de datos de la señal. Se puede enviar un máximo de 8 kB.
  • type (cadena) -- (Opcional) La cadena que indica el tipo de la señal. Se puede enviar un máximo de 128 caracteres, y solo se permiten los siguientes: A-Z, a-z, Numbers (0-9), «-», «_» y «~».

El connectionId El parámetro es una cadena opcional que se utiliza para especificar el ID de conexión de un cliente conectado a la sesión. Si se especifica este valor, la señal se envía al cliente indicado. De lo contrario, la señal se envía a todos los clientes conectados a la sesión.

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

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

Trabajar con retransmisiones en directo

Puedes iniciar una retransmisión en directo de una sesión de OpenTok utilizando un OpenTokSDK.OpenTok de la instancia StartBroadcast(sessionId, hls, rtmpList, resolution, maxDuration, layout) método. Este devuelve un OpenTokSDK.Broadcast instancia.

Consulte también la documentación de Opentok.StopBroadcast() y OpenTok.GetBroadcast() métodos.

SIP

Puedes conectar una plataforma SIP a una sesión de OpenTok utilizando el Opentok.Dial(sessionId, token, sipUri, options) o Opentok.DialAsync(sessionId, token, sipUri, options) método.

Puedes enviar dígitos DTMF a todos los participantes de una sesión activa de OpenTok, o a un cliente concreto conectado a esa sesión, utilizando el Opentok.PlayDTMF(sessionId, digits, connectionId) o Opentok.PlayDTMFAsync(sessionId, digits, connectionId) método.

Forzar a los clientes de una sesión a desconectarse o silenciar el audio publicado

Puedes forzar a un cliente concreto a desconectarse de una sesión de OpenTok utilizando el Opentok.ForceDisconnect(sessionId, connectionId) método.

Puede forzar al editor de un flujo específico a dejar de publicar audio utilizando la opción Opentok.ForceMuteStream(sessionId, stream) o Opentok.ForceMuteStreamAsync(sessionId, stream)método.

Puede forzar al editor de todos los flujos de una sesión (excepto una lista opcional de flujos) para que deje de publicar audio mediante la opción Opentok.ForceMuteAll(sessionId, excludedStreamIds) o Opentok.ForceMuteAllAsync(sessionId, excludedStreamIds) método. A continuación, puedes desactivar el estado de silencio de la sesión llamando al Opentok.DisableForceMute(sessionId) o Opentok.DisableForceMuteAsync(sessionId) método.

Experiencia con Composer

Puedes iniciar un Experiencia con Composer renderizar utilizando el Opentok.StartRenderAsync() método:

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

Para detener un renderizador, llama a la función Opentok.StopRenderAsync() método.

Para mostrar la lista de renderizadores, llama a la función Opentok.ListRendersAsync() método.

Cómo trabajar con Audio Connector

Puedes iniciar un Flujo de «Audio Connector» llamando al OpenTok.StartAudioConnectorAsync(AudioConnectorStartRequest request)método:

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

Modificación del tiempo de espera de las solicitudes HTTP

Si deseas ajustar los tiempos de espera de las solicitudes HTTP enviadas por el Client SDK, puedes hacerlo llamando a OpenTok.SetDefaultRequestTimeout(int timeout); ten en cuenta que el tiempo de espera se expresa en milisegundos.

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

Requisitos

Necesitas una clave API y un secreto API de OpenTok, que puedes obtener iniciando sesión en tu Cuenta API de Video de Vonage.

El SDK de OpenTok para .NET requiere .NET Framework 4.5.2 o una versión posterior.

NOTA: En la versión 4.5.2, TLS 1.2 no está habilitado de forma predeterminada. Debes utilizar algo similar a lo siguiente para forzar que el entorno de ejecución utilice, como mínimo, TLS 1.2

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Por otra parte, si tu aplicación depende de una versión diferente de TLS para otras API, también puedes añadir TLS a la lista de métodos compatibles mediante un OR bit a bit:

ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;

Notas de publicación

Véase el Comunicados página para obtener más información sobre cada lanzamiento.

Cambios importantes desde la versión 2.2.0

Novedades de la versión 3.0.0:

Esta versión requiere .NET Framework 4.5.2 o una versión posterior.

Cambios en la versión 2.2.1:

La configuración predeterminada para el CreateSession() El método consiste en crear una sesión con el modo multimedia configurado en «relayed». En versiones anteriores del SDK, la configuración predeterminada era utilizar el OpenTok Media Router (modo multimedia configurado en «routed»). En una sesión de retransmisión, los clientes intentarán enviar flujos directamente entre ellos (punto a punto); si los clientes no pueden conectarse debido a restricciones del cortafuegos, la sesión utiliza el servidor TURN de OpenTok para retransmitir los flujos de audio y vídeo.

Cambios en la versión 2.2.0:

Esta versión del SDK incluye compatibilidad para trabajar con archivos de OpenTok.

Esta versión del SDK incluye una serie de mejoras en el diseño de la API. Entre ellas se encuentran varios cambios en la API:

  • Nueva clase OpenTok: el nombre de la clase principal ha cambiado de OpenTokSDK a OpenTok. En la versión anterior, el constructor era OpenTokSDK(). En la versión 2.2, es OpenTok(int apiKey, int apiSecret).

  • CreateSession -- En la versión anterior, había dos métodos para crear una sesión: OpenTokSDK.CreateSession(String location) y OpenTokSDK.CreateSession(String location, Dictionary<string, object> options). Estos métodos devolvían una cadena (el ID de sesión).

    En la versión 2.2, la clase OpenTok incluye un método que admite dos parámetros (ambos opcionales): CreateSession(string location = "", MediaMode mediaMode = MediaMode.ROUTED). En mediaMode El parámetro sustituye al p2p.preference configuración de la versión anterior. El método devuelve un objeto Session.

  • GenerateToken -- En la versión anterior, había dos métodos: OpenTokSDK.GenerateToken(string sessionId) y OpenTokSDK.GenerateToken(string sessionId, Dictionary<string, object> options) En la versión 2.2, esto se sustituye por el siguiente método: OpenTokSDK.OpenTok.GenerateToken(string sessionId, Role role = Role.PUBLISHER, double expireTime = 0, string data = null). Todos los parámetros, excepto el sessionId parámetro, son opcionales.

    Además, la clase «Session» incluye un método para generar tokens: OpenTokSDK.Session.GenerateToken(Role role = Role.PUBLISHER, double expireTime = 0, string data = null).