SDK Java da Video API da Vonage

O SDK Java do OpenTok oferece métodos para:

Instalação

Maven Central (recomendado):

O Maven Central O repositório ajuda a gerenciar dependências para projetos baseados na JVM. Ele pode ser utilizado por meio de várias ferramentas de compilação, incluindo o Maven e o Gradle.

Maven

Ao usar o Maven como ferramenta de compilação, você pode gerenciar as dependências no pom.xml arquivo:

<dependency>
    <groupId>com.tokbox</groupId>
    <artifactId>opentok-server-sdk</artifactId>
    <version>4.11.0</version>
</dependency>

Gradle

Ao usar o Gradle como ferramenta de compilação, você pode gerenciar as dependências no build.gradle arquivo:

dependencies {
  compile group: 'com.tokbox', name: 'opentok-server-sdk', version: '4.11.0'
}

Manualmente:

Baixe o arquivo .jar da versão mais recente no Comunicados página. Inclua-a no classpath do seu próprio projeto ao usando o JDK diretamente ou no IDE de sua preferência.

Uso

Inicializando

Importe as classes necessárias em qualquer classe em que elas venham a ser utilizadas. Em seguida, inicialize um com.opentok.OpenTok objeto com sua própria chave de API e segredo de API.

import com.opentok.OpenTok;

// inside a class or method...
int apiKey = 000000; // YOUR API KEY
String apiSecret = "YOUR API SECRET";
OpenTok opentok = new OpenTok(apiKey, apiSecret)

Opções de configuração avançadas

Você pode usar OpenTok.Builder para definir opções avançadas. Essa classe inclui os seguintes métodos:

  • .requestTimeout(int) -- Chame esta função para definir o tempo limite para solicitações HTTP (em segundos). O tempo limite padrão é de 60 segundos.

  • .proxy(Proxy) -- Usando um java.net.Proxy objeto, você pode configurar um servidor proxy que o cliente HTTP utilizará ao chamar a API REST do OpenTok.

Ligue para o OpenTok.Builder() construtor, passando sua chave e seu segredo da API, para instanciar um OpenTok.Builder objeto. Em seguida, chame o requestTimeout() ou proxy() métodos (ou ambos). Em seguida, chame o build() método que retorna um objeto OpenTok.

Por exemplo, o código a seguir instancia um objeto OpenTok, com o tempo limite padrão definido em 10 segundos:

int apiKey = 12345; // YOUR API KEY
String apiSecret = "YOUR API SECRET";
int timeout = 10;

OpenTok opentok = new OpenTok.Builder(apiKey, apiSecret)
  .requestTimeout(timeout)
  .build();

O método close()

Não se esqueça de ligar para o OpenTok.close() método quando terminar, para evitar o vazamento de descritores de arquivo:

opentok.close();

Criação de sessões

Para criar uma sessão do OpenTok, use o OpenTok da instância createSession(SessionProperties properties) método. O properties O parâmetro é opcional e serve para especificar duas coisas:

  • Se a sessão utiliza o OpenTok Media Router
  • Uma sugestão de localização para o servidor OpenTok.
  • Se a sessão é arquivada automaticamente.

Uma instância pode ser inicializada usando o com.opentok.SessionProperties.Builder classe. O sessionId propriedade do valor retornado com.opentok.Session instância, que você pode ler usando o getSessionId() O método é útil para obter um identificador que possa ser salvo em um repositório persistente (como um banco de dados).

import com.opentok.MediaMode;
import com.opentok.ArchiveMode;
import com.opentok.Session;
import com.opentok.SessionProperties;

// A session that attempts to stream media directly between clients:
Session session = opentok.createSession();

// A session that uses the OpenTok Media Router:
Session session = opentok.createSession(new SessionProperties.Builder()
  .mediaMode(MediaMode.ROUTED)
  .build());

// A Session with a location hint:
Session session = opentok.createSession(new SessionProperties.Builder()
  .location("12.34.56.78")
  .build());

// A session that is automatically archived (it must be used for routed media mode)
Session session = opentok.createSession(new SessionProperties.Builder()
  .mediaMode(MediaMode.ROUTED)
  .archiveMode(ArchiveMode.ALWAYS)
  .build());

// Store this sessionId in the database for later use:
String sessionId = session.getSessionId();

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 com.opentok.OpenTok da instância generateToken(String sessionId, TokenOptions options) método, ou chamando um com.opentok.Session da instância generateToken(TokenOptions options) método após criá-lo. O options O parâmetro é opcional e é usado para definir a função, o tempo de validade e os dados de conexão do token. Uma instância pode ser inicializada usando o TokenOptions.Builder classe.

import com.opentok.TokenOptions;
import com.opentok.Role;

// Generate a token from just a sessionId (fetched from a 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
String token = session.generateToken(new TokenOptions.Builder()
  .role(Role.MODERATOR)
  .expireTime((System.currentTimeMillis() / 1000L) + (7 * 24 * 60 * 60)) // in one week
  .data("name=Johnny")
  .build());

Trabalhando com arquivos

É possível arquivar apenas as sessões que utilizam o OpenTok Media Router (sessões com o modo de mídia definido como “routed”).

Você pode iniciar a gravação de uma sessão do OpenTok usando um com.opentok.OpenTok da instância startArchive(String sessionId, String name) método. Isso retornará um com.opentok.Archive instância. O parâmetro name é opcional e serve para atribuir um nome ao Arquivo. Observe que você só pode iniciar um Arquivo em uma Sessão que tenha clientes conectados.

import com.opentok.Archive;

// A simple Archive (without a name)
Archive archive = opentok.startArchive(sessionId, null);

// Store this archiveId in the database for later use
String archiveId = archive.getId();

Você também pode desativar a gravação de áudio ou vídeo chamando a função hasAudio(false) ou hasVideo(false) métodos de um ArchiveProperties construtor e passando o objeto criado para o OpenTok.startArchive(String sessionId, ArchiveProperties properties) método:

import com.opentok.Archive;
import com.opentok.ArchiveProperties;

// Start an audio-only archive
Archive archive = opentok.startArchive(sessionId, new ArchiveProperties.Builder()
  .hasVideo(false)
  .build());

// Store this archiveId in the database for later use
String archiveId = archive.getId();

Definir o modo de saída como Archive.OutputMode.INDIVIDUAL Essa configuração faz com que cada fluxo no arquivo seja gravado em seu próprio arquivo individual:

import com.opentok.Archive;
import com.opentok.ArchiveProperties;

Archive archive = opentok.startArchive(sessionId, new ArchiveProperties.Builder()
  .outputMode(Archive.OutputMode.INDIVIDUAL)
  .build());

// Store this archiveId in the database for later use
String archiveId = archive.getId();

O Archive.OutputMode.COMPOSED essa opção é o valor padrão para outputMode. Ele arquiva todos os fluxos a serem gravados em um único arquivo (composto).

Você só pode especificar o resolution para arquivos compostos que utilizam o ArchiveProperties gerador. Se você definir o resolution propriedade e também definir o outputMode propriedade para Archive.OutputMode.INDIVIDUAL, o método lançará uma InvalidArgumentException.

Os valores aceitos para resolution são:

  • "640x480" (SD, o padrão)
  • "1280x720" (HD)

    Observe que definir qualquer outro valor para o resolution Essa propriedade resultará em uma exceção.

import com.opentok.ArchiveProperties;

ArchiveProperties properties = new ArchiveProperties.Builder().resolution("1280x720").build();

Você pode interromper a gravação de um arquivo já iniciado usando um com.opentok.Archive da instância stopArchive(String archiveId) método.

// Stop an Archive from an archiveId (fetched from database)
Archive archive = opentok.stopArchive(archiveId);

Para obter um com.opentok.Archive instância (e todas as informações a respeito dela) de um archiveId, use um com.opentok.OpenTok da instância getArchive(String archiveId) método.

Archive archive = opentok.getArchive(String archiveId);

Para excluir um arquivo, você pode chamar um com.opentok.OpenTok da instância deleteArchive(String archiveId) método.

// Delete an Archive from an archiveId (fetched from database)
opentok.deleteArchive(archiveId);

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 uma com.opentok.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 List<Archive> tipo. Um InvalidArgumentException será gerada se o deslocamento ou a contagem forem negativos ou se a contagem for maior que 1000.

// Get a list with the first 1000 archives created by the API Key
List<Archive> archives = opentok.listArchives();

// Get a list of the first 50 archives created by the API Key
List<Archive> archives = opentok.listArchives(0, 50);

// Get a list of the next 50 archives
List<Archive> archives = opentok.listArchives(50, 50);

Você também pode obter a lista de arquivos de uma ID de sessão específica e, opcionalmente, usar os parâmetros offset e count, conforme descrito acima.

// Get a list with the first 1000 archives for a specific session
ArchiveList archives = opentok.listArchives(sessionId);

// Get a list of the first 50 archives  for a specific session
ArchiveList archives = sdk.listArchives(sessionId, 0, 50);

// Get a list of the next 50 archives for a specific session
ArchiveList archives = sdk.listArchives(sessionId, 50, 50);

Observe que você também pode criar uma sessão arquivada automaticamente, passando ArchiveMode.ALWAYS para o archiveMode() método do SessionProperties.Builder objeto que você usa para construir o sessionProperties parâmetro passado para o OpenTok.createSession() método (consulte “Criação de sessões”, acima).

Para arquivos compostos, é possível definir dinamicamente o layout do arquivo (enquanto ele está sendo gravado) usando o OpenTok.setArchiveLayout(String archiveId, ArchiveProperties properties) método. Veja Personalização do layout do vídeo para arquivos compostos Para obter mais informações, use o ArchiveProperties gerador da seguinte forma:

ArchiveProperties properties = new ArchiveProperties.Builder()
    .layout(new ArchiveLayout(ArchiveLayout.Type.VERTICAL))
    .build();
opentok.setArchiveLayout(archiveId, properties);

Para layouts personalizados, o construtor tem a seguinte aparência:

ArchiveProperties properties = new ArchiveProperties.Builder()
.layout(new ArchiveLayout(ArchiveLayout.Type.CUSTOM, "stream { position: absolute; }"))
.build();

É 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(String sessionId, TokenOptions options) método. E você também pode alterar as classes de layout de um stream da seguinte maneira:

StreamProperties streamProps = new StreamProperties.Builder()
  .id(streamId)
  .addLayoutClass("full")
  .addLayoutClass("focus")
  .build();
StreamListProperties properties = new StreamListProperties.Builder()
  .addStreamProperties(streamProps)
  .build();
opentok.setStreamLayouts(sessionId, properties);

Se você quiser alterar o layout de vários fluxos, crie um objeto StreamProperties para cada fluxo e adicione-os ao objeto StreamListProperties da seguinte maneira:

StreamListProperties properties = new StreamListProperties.Builder()
  .addStreamProperties(streamProps1)
  .addStreamProperties(streamProps2)
  .build();
opentok.setStreamLayouts(sessionId, properties);

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

Desconectando clientes

Seu servidor de aplicativos pode desconectar um cliente de uma sessão do OpenTok chamando a função forceDisconnect(sessionId, connectionId) método do com.opentok.OpenTok instância.

opentok.forceDisconnect(sessionId, connectionId);

O connectionId O parâmetro é usado para especificar o ID de conexão de um cliente à sessão.

Para obter mais informações sobre a funcionalidade de desconexão forçada e os códigos de exceção, consulte o Documentação da API REST.

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(String sessionId, String streamId)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(String sessionId, MuteAllProperties properties) método. Em seguida, você pode desativar o estado de mudo da sessão chamando o Opentok.disableForceMute(String sessionId) método.

Para obter mais informações, consulte Silenciar o áudio das transmissões em uma sessão.

Sinalização

Você pode enviar sinais para todas as conexões de uma sessão ou para uma conexão específica:

  • public void signal(String sessionId, SignalProperties props) throws OpenTokException , RequestException, InvalidArgumentException

  • public void signal(String sessionId, String connectionId, SignalProperties props) throws OpenTokException , RequestException , InvalidArgumentException

O SignalProperties O construtor ajuda você a definir os dados e o tipo do sinal:

SignalProperties properties = new SignalProperties.Builder()
  .type("test")
  .data("This is a test string")
  .build();

opentok.signal(sessionId, properties);
opentok.signal(sessionId, connectionId, properties);

Certifique-se de que o type a string não excede o comprimento máximo (128 bytes) e a data A string não excede o comprimento máximo (8 kB). O SignalProperties Atualmente, o construtor não verifica essas limitações.

Para obter mais informações sobre códigos de sinalização e de exceção, consulte a documentação do Sinalização do OpenTok Método REST.

Radiodifusão

É possível transmitir fluxos de publicação do OpenTok para um HLS (HTTP Live Streaming) ou para fluxos RTMP. Para iniciar com sucesso a transmissão de uma sessão, pelo menos um cliente deve estar conectado à sessão. A transmissão ao vivo pode ter como destino um ponto de extremidade HLS e até cinco servidores RTMP simultaneamente para uma sessão. Você só pode iniciar a transmissão ao vivo para sessões que utilizem o OpenTok Media Router (com o modo de mídia definido como “routed”); não é possível usar a transmissão ao vivo com sessões que tenham o modo de mídia definido como “relayed”. (Consulte o OpenTok Media Router e modos de mídia modes (guia do desenvolvedor).

Você pode iniciar uma transmissão usando o OpenTok.startBroadcast(sessionId, properties) método, onde o properties campo é um BroadcastProperties objeto. Inicialize um BroadcastProperties objeto da seguinte forma (consulte o Transmissão do Opentok Método REST (para mais detalhes):

BroadcastProperties properties = new BroadcastProperties.Builder()
        .hasHls(true)
        .addRtmpProperties(rtmpProps)
        .addRtmpProperties(rtmpNextProps)
        .maxDuration(1000)
        .resolution("640x480")
        .layout(layout)
        .build();

// The Rtmp properties can be build using RtmpProperties as shown below
RtmpProperties rtmpProps = new RtmpProperties.Builder()
        .id("foo")
        .serverUrl("rtmp://myfooserver/myfooapp")
        .streamName("myfoostream").build();

//The layout object is initialized as follows:
BroadcastLayout layout = new BroadcastLayout(BroadcastLayout.Type.PIP);

Por fim, inicie uma transmissão conforme mostrado a seguir:

Broadcast broadcast = opentok.startBroadcast(sessionId, properties)

O Broadcast O objeto retornado contém as seguintes informações:

String broadcastId;
String sessionId;
int projectId;
long createdAt;
long updatedAt;
String resolution;
String status;
List<Rtmp> rtmpList = new ArrayList<>();  //not more than 5
String hls;    // HLS url

// The Rtmp class mimics the RtmpProperties

Para interromper uma transmissão, use:

Broadcast broadcast = opentok.stopBroadcast(broadcastId);

Para obter mais informações sobre uma transmissão ao vivo, use:

Broadcast broadcast = opentok.getBroadcast(broadcastId);

As informações retornadas estão no Broadcast objeto e consiste em URLs HLS e/ou RTMP, juntamente com o ID da sessão, a resolução, etc.

Você também pode alterar o layout de uma transmissão ao vivo de forma dinâmica, utilizando:

opentok.setBroadcastLayout(broadcastId, properties);

//properties can be
BroadcastProperties properties = new BroadcastProperties.Builder()
          .layout(new BroadcastLayout(BroadcastLayout.Type.VERTICAL))
          .build();

Para alterar dinamicamente a classe de layout de um fluxo específico, use

StreamProperties streamProps = new StreamProperties.Builder()
          .id(streamId)
          .addLayoutClass("full")
          .addLayoutClass("focus")
          .build();
StreamListProperties properties = new StreamListProperties.Builder()
          .addStreamProperties(streamProps)
          .build();
opentok.setStreamLayouts(sessionId, properties);

Trabalhando com fluxos

É possível obter informações sobre um fluxo chamando a função getStream(sessionId, streamId) método do com.opentok.OpenTok instância.

// Get stream info from just a sessionId (fetched from a database)
Stream stream = opentok.getStream(sessionId, streamId);

// Stream Properties
stream.getId(); // string with the stream ID
stream.getVideoType(); // string with the video type
stream.getName(); // 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 com.opentok.OpenTok instância.


// Get list of streams from just a sessionId (fetched from a database)
StreamList streamList = opentok.listStreams(sessionId);

streamList.getTotalCount(); // total count

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, são necessários 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.

Para conectar sua plataforma SIP a uma sessão do OpenTok, chame a função OpenTok.dial(String sessionId, String token, SipProperties properties) método. O áudio da sua extremidade da chamada SIP é adicionado à sessão do OpenTok como um fluxo apenas de áudio. O OpenTok Media Router mixa o áudio de outros fluxos na sessão e envia o áudio mixado para o seu terminal SIP. A chamada é encerrada quando o seu servidor SIP envia uma mensagem BYE (para encerrar a chamada). Você também pode encerrar uma chamada usando o OpenTok.forceDisconnect(sessionId, connectionId) método para desconectar o cliente SIP da sessão (consulte Desconectando clientes).

O gateway SIP da OpenTok encerra automaticamente uma chamada após 5 minutos de inatividade (5 minutos sem recepção de mídia). Além disso, como medida de segurança, o gateway SIP da OpenTok encerra qualquer chamada SIP que dure mais de 6 horas.

O recurso de interconexão SIP exige que você utilize uma sessão do OpenTok que utilize o OpenTok Media Router (uma sessão com o modo de mídia definido como “routed”).

Para conectar uma sessão do OpenTok a um gateway SIP:

SipProperties properties = new SipProperties.Builder()
         .sipUri("sip:user@sip.partner.com;transport=tls")
         .from("from@example.com")
         .headersJsonStartingWithXDash(headerJson)
         .userName("username")
         .password("password")
         .secure(true)
         .build();

 Sip sip = opentok.dial(sessionId, token, properties);

Trabalhando com compositores experientes

Você pode iniciar um Experiência com o Composer chamando o OpenTok.startRender(String sessionId, String token, RenderProperties properties) método:

RenderProperties properties = new RenderProperties.Builder()
         .url("http://example.com/path-to-page/")
         .build();

Render render = opentok.startRender(sessionId, token, properties);

É possível interromper um Experience Composer chamando a função OpenTok.stopRender(String renderId) método.

Você pode obter informações sobre a Experience Composers ligando para o OpenTok.getRender(String renderId), OpenTok.listRenders() ou OpenTok.listRenders(Integer offset, Integer count) métodos.

Trabalhando com o Audio Connector

Você pode iniciar um Fluxo do conector de áudio chamando o OpenTok.connectAudioStream(String sessionId, String token, AudioConnectorProperties properties) método:

AudioConnectorProperties properties = new AudioConnectorProperties.Builder("wss://service.com/ws-endpoint")
        .addStreams("streamId-1", "streamId-2")
        .addHeader("X-CustomHeader-Key", "headerValue")
        .build();

AudioConnector ac = opentok.connectAudioStream(sessionId, token, properties);

Amostras

Há duas Applications de exemplo incluídas no SDK. Para começar o mais rápido possível, clone todo o repositório e siga os tutoriais:

Documentação

A documentação de referência está disponível em &lt;/opentok/sdks/java/reference/index.html&gt;.

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 Java do OpenTok requer o JDK 8 ou superior para compilação. O ambiente de execução requer o Java SE 8 ou superior. Este projeto foi testado tanto na implementação do OpenJDK quanto na da Oracle.

Para o Java 7, utilize o OpenTok Java SDK v3.

Notas de lançamento

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