SDK .NET da Video API da Vonage

O SDK do OpenTok para .NET oferece métodos para:

Instalação

NuGet (recomendado):

Usando o Console do Gerenciador de Pacotes:

PM> Install-Package OpenTok

Manualmente:

Baixe a versão mais recente do Página de Lançamentos. Descompacte o arquivo e coloque o OpenTok.dll, os conjuntos dependentes e os arquivos de apoio no seu próprio projeto.

Uso

Inicializando

Importe o OpenTokSDK namespace em todos os arquivos que utilizarão objetos OpenTok. Em seguida, inicialize um OpenTokSDK.OpenTok objeto usando sua própria chave de API e seu próprio segredo de API.

using OpenTokSDK;

// ...

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

Substituir o valor do user-agent da solicitação

Você pode optar por adicionar um valor personalizado ao valor do user-agent enviado em cada solicitação.

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

Se o valor personalizado tiver sido definido, o user-agent seguirá o seguinte formato: Opentok-DotNet-SDK/{version}/{customValue}.

Criação de sessões

Para criar uma sessão do OpenTok, chame a função OpenTok da instância CreateSession(string location, MediaMode mediaMode, ArchiveMode archiveMode) ou CreateSessionAsync(string location, MediaMode mediaMode, ArchiveMode archiveMode) método. Cada um dos parâmetros é opcional e pode ser omitido caso não seja necessário. São eles:

  • string location : Um endereço IPv4 usado como indicação de localização. (padrão: "")

  • MediaMode mediaMode : Especifica se a sessão utilizará o OpenTok Media Router (MediaMode.ROUTED) ou tentará transmitir fluxos diretamente entre os clientes (MediaMode.RELAYED, o padrão)

  • ArchiveMode archiveMode : Especifica se a sessão será arquivada automaticamente (ArchiveMode.ALWAYS) ou não (ArchiveMode.MANUAL, o padrão)

O valor de retorno é um OpenTokSDK.Session objeto. Seu Id Essa propriedade é útil para obter um identificador que possa ser salvo em um armazenamento persistente (como um banco de dados).

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

Geração de tokens

Depois que uma sessão for criada, você poderá começar a gerar tokens para os clientes usarem ao se conectarem a ela. Você pode gerar um token chamando uma OpenTokSDK.OpenTok da instância GenerateToken(string sessionId, Role role, double expireTime, string data) método, ou chamando um OpenTokSDK.Session da instância GenerateToken(Role role, double expireTime, string data) método após criá-lo. No primeiro método, o sessionId é obrigatório, e os demais parâmetros são opcionais. No segundo método, todos os parâmetros são opcionais.


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

Trabalhando com arquivos

Você pode iniciar a gravação de uma sessão do OpenTok usando um OpenTokSDK.OpenTok da instância StartArchive(sessionId, name, hasVideo, hasAudio, outputMode, resolution) método. Isso retornará um OpenTokSDK.Archive instância. O parâmetro name é opcional e serve para atribuir um nome ao Arquivo. Observe que só é possível iniciar um Arquivo em uma Sessão que tenha clientes conectados.

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

ou

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

então

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

Você pode adicionar um nome ao arquivo (para fins de identificação) definindo o name parâmetro do o OpenTok.StartArchive() método.

Você também pode desativar a gravação de áudio ou vídeo configurando o hasAudio ou hasVideo parâmetro do o OpenTok.StartArchive() método false.

Você também pode definir a resolução da gravação para alta definição configurando o resolution parâmetro do OpenTok.StartArchive() método. Os valores aceitos são “640x480” (SD paisagem, o padrão), “1280x720” (HD paisagem), “1920x1080” (FHD na orientação paisagem), “480x640” (SD na orientação retrato), “720x1280” (HD na orientação retrato) ou “1080x1920” (FHD na orientação retrato). Observe que não é possível especificar o resolution quando você define o outputMode parâmetro para OutputMode.INDIVIDUAL.

Por padrão, todos os fluxos são gravados em um único arquivo (composto). É possível gravar os diferentes fluxos da sessão em arquivos individuais (em vez de um único arquivo composto) configurando o outputMode parâmetro do OpenTok.StartArchive() método OutputMode.INDIVIDUAL.

Você pode interromper a gravação de um arquivo já iniciado usando um OpenTokSDK.OpenTok da instância StopArchive(String archiveId) método ou utilizando o OpenTokSDK.Archive da instância Stop() método.

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

ou

var archive = OpenTok.StopArchiveAsync(archiveId);

Para obter um OpenTokSDK.Archive instância (e todas as informações a respeito dela) a partir de um ID de arquivo, use o OpenTokSDK.OpenTok da instância GetArchive(archiveId) método.

var archive = OpenTok.GetArchive(archiveId);

ou

var archive = OpenTok.GetArchiveAsync(archiveId);

Para excluir um arquivo, você pode chamar uma OpenTokSDK.OpenTok da instância DeleteArchive(archiveId) método ou chamar o OpenTokSDK.Archive da instância 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();

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

Você também pode obter uma lista de todos os arquivos que criou (até 1.000) com sua chave de API. Isso é feito por meio de um OpenTokSDK.OpenTok da instância ListArchives(int offset, int count) método. Opcionalmente, você pode paginar os arquivos recebidos usando os parâmetros offset e count. Isso retornará um 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);

Observe que você também pode criar uma sessão arquivada automaticamente, passando ArchiveMode.ALWAYS como o archiveMode parâmetro ao chamar o OpenTok.CreateSession() método (consulte “Criação de sessões”, acima).

Trabalhando com fluxos

É possível obter informações sobre um fluxo chamando a função GetStream(sessionId, streamId) método do 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

É possível obter informações sobre todos os fluxos de uma sessão chamando a função ListStreams(sessionId) método do OpenTok classe.

StreamList streamList = OpenTok.ListStreams(sessionId);

streamList.Count; // total count

Desconexão forçada

Seu servidor de aplicativos pode desconectar um cliente de uma sessão do OpenTok chamando a função ForceDisconnect(sessionId, connectionId) método do OpenTok classe.

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

Enviando sinais

Depois que uma sessão for criada, você poderá enviar sinais para todos os participantes da sessão ou para uma conexão específica. Para enviar um sinal, basta chamar a função Signal(sessionId, signalProperties, connectionId) método do OpenTok classe.

O sessionId O parâmetro é o ID da sessão.

O signalProperties o parâmetro é uma instância do SignalProperties classe na qual você pode definir o data parâmetro e o type parâmetro.

  • data (string) — A string de dados do sinal. É possível enviar no máximo 8 kB.
  • type (string) -- (Opcional) A string que define o tipo do sinal. É possível enviar no máximo 128 caracteres, sendo permitidos apenas os seguintes: A-Z, a-z, Numbers (0-9), '-', '_' e '~'.

O connectionId O parâmetro é uma string opcional usada para especificar o ID de conexão de um cliente conectado à sessão. Se você especificar esse valor, o sinal será enviado ao cliente especificado. Caso contrário, o sinal será enviado a todos os clientes conectados à sessão.

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

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

Trabalhando com transmissões ao vivo

Você pode iniciar uma transmissão ao vivo de uma sessão do OpenTok usando um OpenTokSDK.OpenTok da instância StartBroadcast(sessionId, hls, rtmpList, resolution, maxDuration, layout) método. Isso retorna um OpenTokSDK.Broadcast instância.

Consulte também a documentação sobre o Opentok.StopBroadcast() e OpenTok.GetBroadcast() métodos.

SIP

É possível conectar uma plataforma SIP a uma sessão do OpenTok usando o Opentok.Dial(sessionId, token, sipUri, options) ou Opentok.DialAsync(sessionId, token, sipUri, options) método.

É possível enviar dígitos DTMF para todos os participantes de uma sessão ativa do OpenTok ou para um cliente específico conectado a essa sessão, utilizando o Opentok.PlayDTMF(sessionId, digits, connectionId) ou Opentok.PlayDTMFAsync(sessionId, digits, connectionId) método.

Forçar os clientes em uma sessão a se desconectarem ou silenciarem o áudio publicado

É possível forçar um cliente específico a se desconectar de uma sessão do OpenTok usando o Opentok.ForceDisconnect(sessionId, connectionId) método.

Você pode forçar o emissor de um stream específico a interromper a transmissão de áudio usando o Opentok.ForceMuteStream(sessionId, stream) ou Opentok.ForceMuteStreamAsync(sessionId, stream)método.

É possível forçar o emissor de todos os fluxos em uma sessão (exceto uma lista opcional de fluxos) a interromper a transmissão de áudio usando o Opentok.ForceMuteAll(sessionId, excludedStreamIds) ou Opentok.ForceMuteAllAsync(sessionId, excludedStreamIds) método. Em seguida, você pode desativar o estado de mudo da sessão chamando o Opentok.DisableForceMute(sessionId) ou Opentok.DisableForceMuteAsync(sessionId) método.

Experiência com o Composer

Você pode iniciar um Experiência com o Composer renderizar usando o 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 interromper um renderizador, chame a função Opentok.StopRenderAsync() método.

Para listar os renderizadores, chame a função Opentok.ListRendersAsync() método.

Trabalhando com o Audio Connector

Você pode iniciar um Fluxo do conector de áudio chamando o 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);

Alteração do tempo limite para solicitações HTTP

Se você quiser ajustar os tempos de espera das solicitações HTTP enviadas pelo Client SDK, pode fazê-lo chamando o método OpenTok.SetDefaultRequestTimeout(int timeout) — observe que o tempo de espera é expresso em milissegundos

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

Requisitos

Você precisa de uma chave de API e de um segredo de API do OpenTok, que podem ser obtidos ao fazer login na sua Account da Video API da Vonage.

O SDK do OpenTok para .NET requer o .NET Framework 4.5.2 ou uma versão posterior.

NOTA: Ao usar a versão 4.5.2, o TLS 1.2 não está habilitado por padrão. Você deve usar algo semelhante ao seguinte para forçar o ambiente de execução a usar, no mínimo, o TLS 1.2

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Como alternativa, se sua aplicação depender de uma versão diferente do TLS para outras APIs, você pode adicionar o TLS à lista de métodos suportados usando a operação OR bit a bit:

ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;

Notas de lançamento

Veja o Comunicados página para mais detalhes sobre cada lançamento.

Alterações importantes desde a versão 2.2.0

Alterações na versão 3.0.0:

Esta versão requer o .NET Framework 4.5.2 ou uma versão posterior.

Alterações na versão 2.2.1:

A configuração padrão para o CreateSession() O método consiste em criar uma sessão com o modo de mídia definido como “relayed”. Nas versões anteriores do SDK, a configuração padrão era utilizar o OpenTok Media Router (modo de mídia definido como “routed”). Em uma sessão retransmitida, os clientes tentarão enviar fluxos diretamente entre si (ponto a ponto); se os clientes não conseguirem se conectar devido a restrições de firewall, a sessão utiliza o servidor TURN do OpenTok para retransmitir os fluxos de áudio e vídeo.

Alterações na versão 2.2.0:

Esta versão do SDK inclui suporte para trabalhar com arquivos do OpenTok.

Esta versão do SDK inclui várias melhorias no design da API. Entre elas, estão várias alterações na API:

  • Nova classe OpenTok — O nome da classe principal mudou de OpenTokSDK para OpenTok. Na versão anterior, o construtor era OpenTokSDK(). Na versão 2.2, é OpenTok(int apiKey, int apiSecret).

  • CreateSession — Na versão anterior, havia dois métodos para criar uma sessão: OpenTokSDK.CreateSession(String location) e OpenTokSDK.CreateSession(String location, Dictionary<string, object> options). Esses métodos retornavam uma string (o ID da sessão).

    Na versão 2.2, a classe OpenTok inclui um método que recebe dois parâmetros (ambos opcionais): CreateSession(string location = "", MediaMode mediaMode = MediaMode.ROUTED). O mediaMode O parâmetro substitui o p2p.preference configuração na versão anterior. O método retorna um objeto Session.

  • GenerateToken — Na versão anterior, havia dois métodos: OpenTokSDK.GenerateToken(string sessionId) e OpenTokSDK.GenerateToken(string sessionId, Dictionary<string, object> options) Na versão 2.2, isso é substituído pelo seguinte método: OpenTokSDK.OpenTok.GenerateToken(string sessionId, Role role = Role.PUBLISHER, double expireTime = 0, string data = null). Todos os parâmetros, exceto o sessionId parâmetro, são opcionais.

    Além disso, a classe Session inclui um método para gerar tokens: OpenTokSDK.Session.GenerateToken(Role role = Role.PUBLISHER, double expireTime = 0, string data = null).