SDK do Node para a Video API da Vonage

O SDK do OpenTok Node oferece métodos para:

Instalação usando o npm (recomendado):

O npm ajuda a gerenciar dependências para projetos Node. Saiba mais aqui: http://npmjs.org.

Execute este comando para instalar o pacote e adicioná-lo ao seu package.json:

$ npm install opentok --save

Uso

Inicializando

Importe o módulo para obter uma função construtora para um objeto OpenTok e, em seguida, chame-a com new para instanciar um objeto OpenTok com sua própria chave de API e seu próprio segredo de API.

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

Aumentando os tempos limite

Atualmente, a biblioteca possui um tempo limite de 20 segundos para solicitações. Se você estiver em uma rede lenta e precisar aumentar o tempo limite, é possível definir esse valor (em milissegundos) ao instanciar o objeto OpenTok.

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

Criação de sessões

Para criar uma sessão do OpenTok, use o OpenTok.createSession(properties, callback) método. O properties O parâmetro é um objeto opcional usado para especificar se a sessão utiliza o OpenTok Media Router, para definir uma sugestão de localização e para determinar se a sessão será automaticamente arquivada ou não. A função de retorno de chamada tem a assinatura function(error, session). O session O valor retornado na função de retorno de chamada é uma instância de Session. Os objetos Session possuem um sessionId propriedade que vale a pena ser salva em um armazenamento persistente (como um banco de dados).

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

Geração de tokens

Depois que uma sessão for criada, você poderá começar a gerar tokens para que os clientes os utilizem ao se conectarem a ela. É possível gerar um token chamando a função OpenTok.generateToken(sessionId, options) método. Outra maneira é chamar o generateToken(options) método de um objeto Session. O options O parâmetro é um objeto opcional usado para definir a função, o tempo de validade e os dados de conexão do token. Para o controle de layout em arquivos e transmissões, também é possível definir a lista inicial de classes de layout das transmissões publicadas a partir de conexões que utilizam esse token.

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

Trabalho com arquivos

Você pode iniciar a gravação de uma sessão do OpenTok usando o OpenTok.startArchive(sessionId, options, callback) método. O options O parâmetro é um objeto opcional usado para definir o nome do arquivo. A função de retorno de chamada tem a assinatura function(err, archive). O archive retornado na função de retorno é uma instância de Archive. Observe que só é possível iniciar um arquivamento em uma sessão com clientes conectados.

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

Você também pode desativar a gravação de áudio ou vídeo configurando o hasAudio ou hasVideo propriedade de o options parâmetro para 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);
  }
});

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 opção de 'individual' quando você chamar o OpenTok.startArchive() método:

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

Você pode interromper a gravação de um arquivo já iniciado usando o OpenTok.stopArchive(archiveId, callback) método. Você também pode fazer isso usando o Archive.stop(callback) método an Archive instância. A função de retorno tem uma assinatura function(err, archive). O archive o que é retornado na função de retorno de chamada é uma instância de 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);
});

Para obter um Archive instância (e todas as informações a respeito dela) de um archiveId, use o OpenTok.getArchive(archiveId, callback) método. A função de retorno de chamada tem uma assinatura de função function(err, archive). Você pode verificar as propriedades do arquivo para obter mais detalhes.

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

  console.log(archive);
});

Para excluir um arquivo, você pode chamar a função OpenTok.deleteArchive(archiveId, callback) método ou o delete(callback) método de um Archive instância. A função de retorno de chamada tem uma assinatura 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);
});

Você também pode obter uma lista de todos os arquivos que criou (até 1.000) com sua chave de API. Isso é feito usando o OpenTok.listArchives(options, callback) método. O parâmetro options é um objeto opcional usado para especificar um offset e count para ajudá-lo a paginar os resultados. A função de retorno de chamada tem a seguinte assinatura function(err, archives, totalCount). O archives o que é retornado pela função de retorno de chamada é um array de Archive instâncias. O totalCount O valor retornado pela função de retorno de chamada é o número total de arquivos que sua chave de API gerou.

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

Observe que você também pode criar uma sessão arquivada automaticamente, passando 'always' como o archiveMode opção ao chamar o OpenTok.createSession() método (consulte “Criação de sessões”, acima).

Para arquivos compostos, é possível alterar o layout dinamicamente, usando o OpenTok.setArchiveLayout(archiveId, type, stylesheet, screenshareType, callback) método:

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

É possível definir a classe de layout inicial para os fluxos de um cliente configurando o layout opção ao criar o token para o cliente, usando o OpenTok.generateToken() método. E você pode alterar as classes de layout dos fluxos em uma sessão chamando o OpenTok.setStreamClassLists(sessionId, classListArray, callback) método.

A configuração do layout dos arquivos compostos é opcional. Por padrão, os arquivos compostos utilizam o layout “best fit” (consulte Personalização do layout do vídeo para arquivos compostos).

Para obter mais informações sobre arquivamento, consulte o Guia do desenvolvedor sobre arquivamento do OpenTok.

Trabalhando com transmissões ao vivo

Importante: Apenas sessões do OpenTok encaminhadas oferecem suporte a transmissões ao vivo.

Para iniciar um transmissão ao vivo transmissão de uma sessão do OpenTok, chame o OpenTok.startBroadcast() método. Passe três parâmetros: o ID da sessão, as opções para a transmissão e uma função de retorno de chamada:

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

Consulte a referência da API para obter detalhes sobre o options parâmetro.

Se a operação for bem-sucedida, um objeto `Broadcast` é passado para a função de retorno de chamada como segundo parâmetro. O objeto `Broadcast` possui propriedades que definem a transmissão, incluindo um broadcastUrls propriedade, que contém URLs para os fluxos de transmissão. Consulte a referência da API para obter mais detalhes.

Ligue para o OpenTok.stopBroadcast() método para interromper uma transmissão ao vivo: passe o ID da transmissão (o id propriedade do objeto Broadcast) como primeiro parâmetro. O segundo parâmetro é a função de retorno de chamada:

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

Você também pode ligar para o stop() método do objeto Broadcast para interromper uma transmissão.

Ligue para o Opentok.getBroadcast() método, passando um ID de transmissão, para obter um objeto Broadcast.

Você também pode obter uma lista de todas as transmissões que criou (até 1.000) com sua chave de API. Isso é feito usando o OpenTok.listBroadcasts(options, callback) método. O parâmetro options é um objeto opcional usado para especificar um offset, count, e sessionId para ajudá-lo a paginar os resultados. A função de retorno de chamada tem a seguinte assinatura function(err, broadcasts, totalCount). O broadcasts o que é retornado pela função de retorno de chamada é um array de Broadcast instâncias. O totalCount O valor retornado pela função de retorno de chamada é o número total de transmissões que sua chave de API gerou.

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

Para alterar o layout da transmissão, chame a função OpenTok.setBroadcastLayout() método, passando o ID da transmissão e o layout tipo.

É possível definir a classe de layout inicial para os fluxos de um cliente configurando o layout opção ao criar o token para o cliente, usando o OpenTok.generateToken() método. E você pode alterar as classes de layout dos fluxos em uma sessão chamando o OpenTok.setStreamClassLists(sessionId, classListArray, callback) método.

A configuração do layout de uma transmissão ao vivo é opcional. Por padrão, as transmissões ao vivo utilizam o layout “melhor ajuste”.

Envio de sinais

Você pode enviar um sinal a todos os participantes de uma sessão do OpenTok chamando a função OpenTok.signal(sessionId, connectionId, payload, callback) método e configuração do connectionId parâmetro para null:

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

Ou envie um sinal para um participante específico da sessão chamando o OpenTok.signal(sessionId, connectionId, payload, callback) método e definindo todos os parâmetros, incluindo 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);
  }
);

Este é o equivalente, no lado do servidor, ao método signal() nos SDKs do cliente OpenTok. Consulte Guia do desenvolvedor de sinalização do OpenTok.

Desconectando participantes

Você pode desconectar participantes de uma sessão do OpenTok usando o OpenTok.forceDisconnect(sessionId, connectionId, callback) método.

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

Este é o equivalente do lado do servidor ao método forceDisconnect() no OpenTok.js: Guia de moderação do OpenTok.js.

Forçar os clientes em uma sessão a silenciar o áudio publicado

Você pode forçar o emissor de um stream específico a interromper a transmissão de áudio usando o Opentok.forceMuteStream(sessionId)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() método. Em seguida, você pode desativar o estado de mudo da sessão chamando o Opentok.disableForceMute() método.

Trabalhando com interconexão SIP

É possível adicionar um fluxo somente de áudio proveniente de um gateway SIP externo de terceiros utilizando o recurso de interconexão SIP. Para isso, é necessário um URI SIP, o ID da sessão à qual você deseja adicionar o fluxo somente de áudio e um token para se conectar a esse ID de sessão.

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

Para obter mais informações, consulte o Guia do desenvolvedor do OpenTok SIP Interconnect.

Obtendo informações sobre a transmissão

É possível obter informações sobre um stream ativo em uma sessão do OpenTok:

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

Passe um ID de sessão, um ID de stream e uma função de retorno de chamada para o OpenTok.getStream() método. A função de retorno de chamada é chamada quando a operação é concluída. Ela recebe dois parâmetros: error (no caso de um erro) ou stream. Após a conclusão bem-sucedida, o stream objeto é definido, contendo as propriedades do fluxo.

Para obter informações sobre todos fluxos ativos em uma sessão, chame a função OpenTok.listStreams() método, passando um ID de sessão e uma função de retorno de chamada. Em caso de sucesso, a função de retorno de chamada é invocada com um array de objetos Stream passado como segundo parâmetro:

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

Trabalhando com o Audio Connector

Você pode iniciar um Conector de áudio WebSocket chamando o OpenTok.websocketConnect() método.

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 Node requer o Node.js 6 ou superior. Ele pode funcionar em versões mais antigas, mas essas versões não são mais testadas.

Notas de lançamento

Veja o Página de lançamentos para obter mais detalhes sobre cada lançamento.

Alterações importantes desde a versão 2.2.0

Alterações na versão 2.2.3:

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.

O createSession() O método passou a aceitar um parâmetro: um options objeto que possui location e mediaMode propriedades. O mediaMode a propriedade substitui o properties.p2p.preference parâmetro na versão anterior do SDK.

O generateToken() foi alterada para aceitar dois parâmetros: o ID da sessão e um options objeto que possui role, expireTime e data propriedades.