SDK em Ruby da Video API da Vonage

O SDK do OpenTok para Ruby oferece métodos para:

Instalação

Bundler (recomendado):

O Bundler ajuda a gerenciar dependências em projetos Ruby. Saiba mais aqui: http://bundler.io

Adicione esta joia à sua Gemfile:

gem "opentok", "~> 4.0.0"

Permita que o Bundler instale a alteração.

$ bundle install

RubyGems:

$ gem install opentok

Uso

Inicializando

Carregue a gem no início de qualquer arquivo em que ela será utilizada. Em seguida, inicialize um OpenTok::OpenTok objeto com sua chave de API e seu segredo de API do OpenTok.

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret

Opções de inicialização

Tempo limite personalizado

É possível definir um valor personalizado de tempo limite para solicitações HTTP ao inicializar um novo OpenTok::OpenTok objeto:

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret, :timeout_length => 10

O valor para :timeout_length é um número inteiro que representa o número de segundos que se deve aguardar até que uma solicitação HTTP seja concluída. O valor padrão é de 2 segundos.

Anexo da UA

Você também pode acrescentar uma sequência personalizada ao User-Agent valor do cabeçalho para solicitações HTTP ao inicializar um novo OpenTok::OpenTok objeto:

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret, :ua_addendum => 'FOO'

O código acima geraria um User-Agent cabeçalho mais ou menos assim:

User-Agent: OpenTok-Ruby-SDK/4.6.0-Ruby-Version-3.1.2-p20 FOO

Criação de sessões

Para criar uma sessão do OpenTok, use o OpenTok#create_session(properties) método. O properties O parâmetro é um Hash opcional usado para especificar o seguinte:

  • Independentemente de a sessão utilizar o OpenTok Media Roteador, o que é necessário para alguns recursos do OpenTok (como o arquivamento)

  • Uma sugestão de localização para o servidor OpenTok.

  • Se a sessão é arquivada automaticamente.

O session_id método do valor retornado OpenTok::Session Essa instância é útil para obter um sessionId 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.
# If clients cannot connect, the session uses the OpenTok TURN server:
session = opentok.create_session

# A session that will use the OpenTok Media Server:
session = opentok.create_session :media_mode => :routed

# A session with a location hint:
session = opentok.create_session :location => '12.34.56.78'

# A session with automatic archiving (must use the routed media mode):
session = opentok.create_session :archive_mode => :always, :media_mode => :routed

# A session with end-to-end encryption (must use the routed media mode):
session = opentok.create_session :e2ee => true, :media_mode => :routed

# Store this sessionId in the database for later use:
session_id = session.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 a função opentok.generate_token(session_id, options) método, ou chamando o Session#generate_token(options) método na instância após criá-la. O options O parâmetro é um Hash opcional usado para definir a função, o tempo de validade e os dados de conexão do token. Para 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 session_id (fetched from a database)
token = opentok.generate_token session_id

# Generate a Token by calling the method on the Session (returned from createSession)
token = session.generate_token

# Set some options in a token
token = session.generate_token({
    :role        => :moderator,
    :expire_time => Time.now.to_i+(7 * 24 * 60 * 60), # in one week
    :data        => 'name=Johnny',
    :initial_layout_class_list => ['focus', 'inactive']
});

Trabalhando com fluxos

Use este método para obter informações sobre um stream do OpenTok ou sobre todos os streams de uma sessão. Por exemplo, você pode chamar este método para obter informações sobre as classes de layout utilizadas por um stream do OpenTok.

Para obter informações sobre um fluxo específico em uma sessão, chame opentok.streams.find(session_id, stream_id). O objeto de retorno é um Stream objeto, e é possível acessar várias propriedades do fluxo, conforme mostrado no exemplo a seguir (usando a notação do RSpec):

expect(stream).to be_an_instance_of OpenTok::Stream
expect(stream.videoType).to eq 'camera'
expect(stream.layoutClassList.count).to eq 1
expect(stream.layoutClassList.first).to eq "full"

Para obter informações sobre todos os fluxos de uma sessão, chame opentok.streams.all(session_id). O valor de retorno é um StreamList objeto:

expect(all_streams).to be_an_instance_of OpenTok::StreamList
expect(all_streams.total).to eq 2
expect(all_streams[0].layoutClassList[1]).to eq "focus"

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 o opentok.archives.create(session_id, options) método. Isso retornará um OpenTok::Archive instância. O parâmetro options é um Hash opcional usado para definir o has_audio, has_video, e name opções. Observe que você só pode iniciar um Arquivo em uma Sessão que tenha clientes conectados.

# Create an Archive
archive = opentok.archives.create session_id

# Create a named Archive
archive = opentok.archives.create session_id :name => "Important Presentation"

# Create an audio-only Archive
archive = opentok.archives.create session_id :has_video => false

# Store this archive_id in the database for later use
archive_id = archive.id

Configurando o :output_mode opção de :individual Essa configuração faz com que cada fluxo no arquivo seja gravado em seu próprio arquivo individual:

archive = opentok.archives.create session_id :output_mode => :individual

O :output_mode => :composed Essa configuração (padrão) faz com que todos os fluxos do arquivo sejam gravados em um único arquivo (composto).

Para arquivos compostos, é possível definir a resolução do arquivo como “640x480” (SD paisagem, padrão), “1280x720” (HD paisagem), “1920x1080” (FHD paisagem), “480x640” (SD retrato), “720x1280” (HD retrato) ou “1080x1920” (FHD retrato). O resolution O parâmetro é opcional e pode ser incluído no hash de opções (segundo argumento) do opentok.archives.create() método.

opts = {
    :output_mode => :composed,
    :resolution => "1280x720"
}

archive = opentok.archives.create session_id, opts

Para personalizar o layout inicial dos arquivos compostos, você pode usar o :layout opção. Defina-a como um hash contendo duas chaves: :type e :stylesheet. Valores válidos para :type são “bestFit” (melhor ajuste), “custom” (personalizado), “horizontalPresentation” (apresentação horizontal), “pip” (imagem em imagem) e “verticalPresentation” (apresentação vertical). Se você especificar um tipo de layout “custom”, defina o :stylesheet chave da folha de estilo (CSS). (Para outros tipos de layout, não defina o :stylesheet (chave.)

opts = {
    :output_mode => :composed,
    :resolution => "1280x720",
    :layout => {
      :type => "custom",
      :stylesheet => "stream:last-child{display: block;margin: 0;top: 0;left: 0;width: 1px;height: 1px;}stream:first-child{display: block;margin: 0;top: 0;left: 0;width: 100%;height: 100%;}"
    }
}

archive = opentok.archives.create session_id, opts

Se você não especificar um tipo de layout inicial, o arquivo utilizará o tipo de layout mais adequado. Para obter mais informações, consulte Personalização do layout do vídeo para arquivos compostos.

Você pode interromper a gravação de um arquivo já iniciado usando o opentok.archives.stop_by_id(archive_id) método. Você também pode fazer isso usando o Archive#stop() método.

# Stop an Archive from an archive_id (fetched from database)
opentok.archives.stop_by_id archive_id

# Stop an Archive from an instance (returned from opentok.archives.create)
archive.stop

Para obter um OpenTok::Archive instância (e todas as informações a respeito dela) de um archive_id, use o opentok.archives.find(archive_id) método.

archive = opentok.archives.find archive_id

Para excluir um arquivo, você pode chamar a função opentok.archives.delete_by_id(archive_id) método ou o delete método de um OpenTok::Archive instância.

# Delete an Archive from an archive_id (fetched from database)
opentok.archives.delete_by_id archive_id

# Delete an Archive from an Archive instance (returned from archives.create, archives.find)
archive.delete

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.archives.all(options) método. O parâmetro options é um Hash opcional usado para especificar um :offset e :count para ajudá-lo a paginar os resultados. Isso retornará uma instância do OpenTok::ArchiveList classe.

archive_list = opentok.archives.all

# Get an specific Archive from the list
archive_list[i]

# Get the total number of Archives for this API Key
$total = archive_list.total

Observe que você também pode criar uma sessão arquivada automaticamente, passando :always como o :archive_mode propriedade do options parâmetro passado para o OpenTok#create_session() método (consulte “Criação de sessões”, acima).

Você pode definir o layout de um arquivo:

opts = { :type => "verticalPresentation" }
opentok.archives.layout(archive_id, opts)

O hash opts tem duas entradas:

  • O type é o tipo de layout do arquivo. Os valores válidos são “bestFit” (melhor ajuste) “custom” (personalizado), “horizontalPresentation” (apresentação horizontal), “pip” (imagem em imagem) e “verticalPresentation” (apresentação vertical).

  • Se você especificar um tipo de layout “personalizado”, defina o stylesheet propriedade. (Para outros tipos de layout, não defina a propriedade da folha de estilo.)

Veja Personalização do layout do vídeo para arquivos compostos para mais detalhes.

É possível definir a classe de layout inicial para os fluxos de um cliente configurando a opção de layout ao criar o token para o cliente, utilizando o opentok.generate_token método. E você também pode alterar as classes de layout de um stream da seguinte maneira:

streams_list = {
    :items => [
        {
            :id => "8b732909-0a06-46a2-8ea8-074e64d43422",
            :layoutClassList => ["full"]
        },
        {
            :id => "8b732909-0a06-46a2-8ea8-074e64d43423",
            :layoutClassList => ["full", "focus"]
        }
    ]
}
response = opentok.streams.layout(session_id, streams_list)

Para obter mais informações sobre como definir classes de layout de fluxo, consulte o Alteração das classes de layout do arquivo composto para um stream do OpenTok stream.

Lembre-se de que o streams.layout O método se aplica apenas a fluxos de arquivo e de transmissão.

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

Sinalização

Você pode enviar um sinal usando o opentok.signals.send(session_id, connection_id, opts) método. Se connection_id for nulo ou uma string vazia, o sinal é enviado a todas as conexões válidas na sessão.

Um exemplo de opts O campo pode ser o seguinte:

opts = { :type => "chat",
         :data => "Hello"
}

O comprimento máximo do type A sequência de caracteres tem 128 bytes e deve conter apenas letras (A-Z e a-z), Numbers (0-9), '-', '_' e '~'.

O data A string não deve exceder o tamanho máximo (8 kB).

O connection_id e opts Os parâmetros são opcionais em conjunto por padrão. Portanto, você também pode usar opentok.signals.send(session_id)

Para obter mais informações sobre sinalização, consulte o Sinalização do OpenTok guia de programação.

Radiodifusão

Você pode transmitir suas transmissões para servidores HLS ou RTMP.

Para iniciar com sucesso a transmissão de uma sessão, pelo menos um cliente de publicação deve estar conectado à sessão.

A transmissão ao vivo pode ser direcionada a um ponto de extremidade HLS e a até cinco servidores RTMP simultaneamente por 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 em sessões cujo modo de mídia esteja definido como “relayed”.

Para criar uma transmissão apenas em HLS:

opts = {
  :outputs => {
      :hls => {}
  }
}
broadcast = opentok.broadcasts.create(session_id, opts)

# HLS + RTMP
opts = {
   :outputs => {
       :hls => {},
       :rtmp => [
           {
               :id => "myOpentokStream",
               :serverUrl => "rtmp://x.rtmp.youtube.com/live123",
               :streamName => "66c9-jwuh-pquf-9x00"
           }
       ]
   }
}
broadcast = opentok.broadcasts.create(session_id, opts)

O objeto Broadcast retornado contém informações sobre a transmissão, como id, sessionId, projectId, createdAt, updatedAt, resolution, status e um Hash de broadcastUrls. Os broadcastUrls consistem em uma URL HLS e uma matriz de objetos RTMP. Os objetos RTMP se assemelham ao rtmp valor em opts no exemplo acima.

Para obter mais informações sobre transmissão, consulte o Guia de transmissão do OpenTok guia de programação.

Para obter informações sobre um fluxo de transmissão

my_broadcast = opentok.broadcasts.find broadcast_id

O objeto Broadcast retornado possui propriedades que descrevem a transmissão, como id, sessionId, projectId, createdAt, updatedAt, resolution, status e um Hash de broadcastUrls. Os broadcastUrls consistem em uma URL HLS e uma matriz de objetos RTMP. Os objetos RTMP se assemelham ao rtmp valor em opts no exemplo acima.

Para interromper uma transmissão:

 my_broadcast = opentok.broadcasts.stop broadcast_id

 # stop at a broadcast object level too
 #
 my_broadcast = opentok.broadcasts.find broadcast_id
 ret_broadcast =  my_broadcast.stop

 # Both the above returned objects has the "broadcastUrls" property as a nil value and the status
 # property value is "stopped"

Para alterar o layout de uma transmissão dinamicamente

opentok.broadcasts.layout(started_broadcast_id, {
        :type => "verticalPresentation"
    })

  # On an object level
   my_broadcast = opentok.broadcasts.find broadcast_id
   my_broadcast.layout(
             :type => 'pip',
             )

   # the returned value is true if successful

O hash acima contém duas entradas.

  • O type é o tipo de layout do arquivo. Os valores válidos são “bestFit” (melhor ajuste), “custom” (personalizado), “horizontalPresentation” (apresentação horizontal), “pip” (imagem em imagem) e “verticalPresentation” (apresentação vertical).

  • Se você especificar um tipo de layout “personalizado”, defina o stylesheet propriedade. (Para outros tipos de layout, não defina a propriedade da folha de estilo.)

Consulte Personalização do layout do vídeo para arquivos compostos para mais detalhes.

Você também pode alterar o layout de um stream específico dinamicamente. Consulte trabalhando com Streams.

Desconexão forçada

É possível forçar um cliente a se desconectar de uma sessão usando o opentok.connections.forceDisconnect(session_id, connection_id) método.

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.streams.force_mute(session_id, stream_id) 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.streams.force_mute_all(session_id, opts) método. Em seguida, você pode desativar o estado de mudo da sessão chamando o opentok.streams.disable_force_mute(session_id) método.

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

Iniciando uma chamada SIP

Você pode iniciar uma chamada SIP usando o opentok.sip.dial(session_id, token, sip_uri, opts) método. Isso requer uma URL SIP. Muitas vezes, será necessário passar opções para autenticação junto ao provedor SIP e especificar o estabelecimento de uma sessão criptografada.

opts = { "auth" => { "username" => sip_username,
                     "password" => sip_password },
         "secure" => "true"
}
response = opentok.sip.dial(session_id, token, "sip:+15128675309@acme.pstn.example.com;transport=tls", opts)

Para obter mais informações sobre a interconexão SIP, consulte o Interconexão SIP da OpenTok guia do desenvolvedor.

Trabalhando com compositores experientes

Você pode iniciar um Experiência com o Composer chamando o opentok.renders.start(session_id, options) método.

É possível interromper um Experience Composer chamando a função opentok.renders.stop(render_id, options) método.

Você pode obter informações sobre a Experience Composers ligando para o opentok.renders.find(render_id) e opentok.renders.list(options) métodos.

Trabalhando com o Audio Connector

Você pode iniciar um Conector de áudio WebSocket chamando o opentok.websocket.connect() 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 Ruby requer o Ruby 2.1.0 ou uma versão posterior.

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 4.0.0:

O SDK agora oferece suporte ao Ruby v2.7 e requer o Ruby v2.1.0 ou superior. Para o Ruby v2.0.0, continue usando o OpenTok Ruby SDK v3.0.0. Para o Ruby v1.9.3, continue usando o OpenTok Ruby SDK v2.5.0.

Alterações na versão 3.0.0:

O SDK agora requer o Ruby v2.0.0 ou superior. Para o Ruby v1.9.3, continue usando o OpenTok Ruby SDK v2.5.0.

Alterações na versão 2.2.2:

A configuração padrão para o create_session() 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.

Observe também que o options parâmetro do OpenTok.create_session() O método tem um media_mode propriedade em vez de um p2p propriedade.