SDK de Ruby para la Video API de Vonage

El SDK de OpenTok para Ruby ofrece métodos para:

Instalación

Bundler (recomendado):

Bundler ayuda a gestionar las dependencias de los proyectos en Ruby. Encontrarás más información aquí: http://bundler.io

Añade esta joya a tu Gemfile:

gem "opentok", "~> 4.0.0"

Permite que Bundler instale el cambio.

$ bundle install

RubyGems:

$ gem install opentok

Uso

Inicialización de

Carga la gema al principio de cualquier archivo en el que se vaya a utilizar. A continuación, inicializa un OpenTok::OpenTok objeto con tu clave API y tu secreto API de OpenTok.

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret

Opciones de inicialización

Tiempo de espera personalizado

Puedes especificar un valor de tiempo de espera personalizado para las solicitudes HTTP al inicializar un nuevo OpenTok::OpenTok objeto:

require "opentok"

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

El valor de :timeout_length es un número entero que representa el número de segundos que hay que esperar a que se complete una solicitud HTTP. El valor por defecto es de 2 segundos.

Anexo de la UA

También puedes añadir una cadena personalizada al User-Agent valor del encabezado para las solicitudes HTTP al inicializar un nuevo OpenTok::OpenTok objeto:

require "opentok"

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

Lo anterior generaría un User-Agent un encabezado más o menos así:

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

Creación de sesiones

Para crear una sesión de OpenTok, utiliza el OpenTok#create_session(properties) método. En properties El parámetro es un Hash opcional que se utiliza para especificar lo siguiente:

  • Independientemente de si la sesión utiliza el OpenTok Media Enrutador, lo cual es necesario para algunas funciones de OpenTok (como el archivado)

  • Una indicación de la ubicación del servidor de OpenTok.

  • Si la sesión se archiva automáticamente.

El session_id método del valor devuelto OpenTok::Session Esta instancia resulta útil para obtener un «sessionId» 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.
# 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

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 la función opentok.generate_token(session_id, options) método, o llamando a la Session#generate_token(options) método en la instancia tras crearla. El options El parámetro es un hash opcional que se utiliza para configurar el rol, el tiempo de caducidad y los datos de conexión del token. Para controlar el diseño en archivos y retransmisiones, también se puede configurar la lista inicial de clases de diseño de las transmisiones publicadas desde conexiones que utilicen este 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']
});

Trabajar con flujos

Utiliza este método para obtener información sobre una transmisión de OpenTok o sobre todas las transmisiones de una sesión. Por ejemplo, puedes llamar a este método para obtener información sobre las clases de diseño utilizadas por una transmisión de OpenTok.

Para obtener información sobre un flujo concreto de una sesión, llama a opentok.streams.find(session_id, stream_id). El objeto devuelto es un Stream objeto, y puedes acceder a diversas propiedades del flujo tal y como se muestra en el siguiente ejemplo (utilizando la notación de 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 obtener información sobre todas las transmisiones de una sesión, llama a opentok.streams.all(session_id). El valor de retorno es un 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"

Trabajar con archivos

Solo puedes archivar las sesiones que utilicen el OpenTok Media Router (sesiones cuyo modo multimedia esté configurado como «enrutado»).

Puedes iniciar la grabación de una sesión de OpenTok utilizando el opentok.archives.create(session_id, options) método. Esto devolverá un OpenTok::Archive instancia. El parámetro options es un Hash opcional que se utiliza para establecer el has_audio, has_videoy name opciones. Ten en cuenta que solo puedes iniciar un archivo en una sesión que tenga 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

Ajuste del :output_mode opción de :individual Esta configuración hace que cada flujo del archivo se grabe en su propio archivo individual:

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

El :output_mode => :composed Esta configuración (la predeterminada) hace que todas las transmisiones del archivo se graben en un único archivo (compuesto).

En el caso de los archivos compuestos, puedes establecer la resolución del archivo, ya sea «640x480» (SD horizontal, la opción predeterminada), «1280x720» (HD horizontal), «1920x1080» (FHD horizontal), «480x640» (SD vertical), «720x1280» (HD vertical) o «1080x1920» (FHD vertical). El resolution El parámetro es opcional y se puede incluir en el hash de opciones (segundo argumento) de la función opentok.archives.create() método.

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

archive = opentok.archives.create session_id, opts

Para personalizar la disposición inicial de los archivos compuestos, puede utilizar la función :layout opción. Establece este valor como un hash que contenga dos claves: :type y :stylesheet. Valores válidos para :type son «bestFit» (ajuste óptimo), «custom» (personalizado), «horizontalPresentation» (presentación horizontal), «pip» (imagen en imagen) y «verticalPresentation» (presentación vertical). Si se especifica un tipo de diseño «custom», se debe establecer el :stylesheet clave de la hoja de estilo (CSS). (Para otros tipos de diseño, no establezcas la :stylesheet llave).

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

Si no se especifica un tipo de estructura inicial, el archivo utiliza el tipo de estructura que mejor se adapte. Para obtener más información, consulte Personalización del diseño de vídeo para composiciones archivos.

Puede detener la grabación de un Archivo iniciado utilizando la tecla opentok.archives.stop_by_id(archive_id) método. También puedes hacerlo utilizando el 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 obtener un OpenTok::Archive (y toda la información sobre ella) de una instancia de archive_id, utiliza el opentok.archives.find(archive_id) método.

archive = opentok.archives.find archive_id

Para eliminar un archivo, puedes llamar a la función opentok.archives.delete_by_id(archive_id) método o el delete método de un OpenTok::Archive instancia.

# 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

También puede obtener una lista de todos los Archivos que ha creado (hasta 1000) con su Clave API. Para ello utilizando la función opentok.archives.all(options) método. El parámetro options es un hash opcional que se utiliza para especificar un :offset y :count para ayudarte a navegar por los resultados. Esto devolverá una instancia de la OpenTok::ArchiveList clase.

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

Tenga en cuenta que también puede crear una sesión archivada automáticamente, pasando en :always como el :archive_mode propiedad del options parámetro pasado a la OpenTok#create_session() método (véase «Creación de sesiones», más arriba).

Puede ajustar el diseño de un archivo:

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

El hash opts tiene dos entradas:

  • El type es el tipo de diseño del archivo. Los valores válidos son «bestFit» (ajuste óptimo) «custom» (personalizado), «horizontalPresentation» (presentación horizontal), «pip» (imagen en imagen) y «verticalPresentation» (presentación vertical).

  • Si especifica un tipo de diseño "personalizado", defina la opción stylesheet propiedad. (Para otros tipos de diseño, no establezcas la propiedad de la hoja de estilos.)

Véase Personalización del diseño de vídeo para los archivos compuestos Para más información.

Puedes establecer la clase de diseño inicial para las transmisiones de un cliente configurando la opción de diseño al crear el token para el cliente, utilizando la opentok.generate_token método. Además, también puedes modificar las clases de diseño de un flujo de la siguiente manera:

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 obtener más información sobre cómo configurar las clases de diseño de flujos, consulta el Modificación de las clases de diseño del archivo compuesto para una transmisión de OpenTok ».

Ten en cuenta que el streams.layout Este método solo se aplica a las transmisiones de archivo y de emisión.

Para obtener más información sobre el archivado, consulta el Archivado de OpenTok guía del desarrollador.

Señalización

Puedes enviar una señal utilizando el opentok.signals.send(session_id, connection_id, opts) método. Si connection_id es nulo o una cadena vacía, la señal se envía a todas las conexiones válidas de la sesión.

Un ejemplo de opts El campo puede ser el siguiente:

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

La longitud máxima del type La cadena tiene 128 bytes y solo debe contener letras (A-Z y a-z), Numbers (0-9), «-», «_» y «~».

El data no debe superar el tamaño máximo (8 kB).

El connection_id y opts Los parámetros son opcionales de forma conjunta por defecto. Por lo tanto, también puedes utilizar opentok.signals.send(session_id)

Para obtener más información sobre la señalización, consulta el Señalización de OpenTok guía de programación.

Radiodifusión

Puedes transmitir tus contenidos en directo a servidores HLS o RTMP.

Para iniciar correctamente la retransmisión de una sesión, debe haber al menos un cliente de publicación conectado a la sesión.

La retransmisión en directo puede dirigirse a un punto final HLS y a un máximo de cinco servidores RTMP simultáneamente durante una sesión.

Solo puedes iniciar la retransmisión en directo en sesiones que utilicen OpenTok Media Router (con el modo multimedia configurado en «routed»). No puedes utilizar la retransmisión en directo en sesiones cuyo modo multimedia esté configurado en «relayed».

Para crear una emisión solo en 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)

El objeto Broadcast devuelto contiene información sobre la emisión, como id, sessionId, projectId, createdAt, updatedAt, resolution, status y un hash de broadcastUrls. Las broadcastUrls consisten en una URL HLS y una matriz de objetos RTMP. Los objetos RTMP se asemejan a los rtmp valor en opts en el ejemplo anterior.

Para obtener más información sobre la difusión, consulta el Guía de retransmisiones de OpenTok guía de programación.

Para obtener información sobre una transmisión en directo

my_broadcast = opentok.broadcasts.find broadcast_id

El objeto «Broadcast» devuelto tiene propiedades que describen la emisión, como «id», «sessionId», «projectId», «createdAt», «updatedAt», «resolution», «status» y un objeto «Hash» de «broadcastUrls». Las «broadcastUrls» constan de una URL HLS y una matriz de objetos RTMP. Los objetos RTMP se asemejan a los rtmp valor en opts en el ejemplo anterior.

Para detener una emisión:

 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 cambiar dinámicamente la disposición de una emisión

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

El hash anterior tiene dos entradas.

  • El type es el tipo de diseño del archivo. Los valores válidos son «bestFit» (ajuste óptimo), «custom» (personalizado), «horizontalPresentation» (presentación horizontal), «pip» (imagen en imagen) y «verticalPresentation» (presentación vertical).

  • Si especifica un tipo de diseño "personalizado", defina la opción stylesheet propiedad. (Para otros tipos de diseño, no establezcas la propiedad de la hoja de estilos.)

Consulte Personalización del diseño de vídeo para composiciones archivos Para más información.

También puedes modificar dinámicamente el diseño de un flujo concreto. Consulta Trabajar con Streams.

Desconexión forzada

Puedes obligar a un cliente a desconectarse de una sesión utilizando el opentok.connections.forceDisconnect(session_id, connection_id) método.

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

Puede forzar al editor de un flujo específico a dejar de publicar audio utilizando la opción opentok.streams.force_mute(session_id, stream_id) 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.streams.force_mute_all(session_id, opts) método. A continuación, puedes desactivar el estado de silencio de la sesión llamando al opentok.streams.disable_force_mute(session_id) método.

Para obtener más información, consulta Silenciar el audio de los flujos de una sesión.

Iniciar una llamada SIP

Puedes iniciar una llamada SIP utilizando el opentok.sip.dial(session_id, token, sip_uri, opts) método. Para ello se necesita una URL SIP. A menudo tendrás que indicar opciones para la autenticación ante el proveedor SIP y especificar el establecimiento de una sesión cifrada.

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 obtener más información sobre la interconexión SIP, consulta el Interconexión SIP de OpenTok guía del desarrollador.

Trabajar con compositores experimentados

Puedes iniciar un Experiencia con Composer llamando al opentok.renders.start(session_id, options) método.

Puedes detener un Experience Composer llamando a la función opentok.renders.stop(render_id, options) método.

Puedes obtener información sobre Experience Composers llamando al opentok.renders.find(render_id) y opentok.renders.list(options) métodos.

Cómo trabajar con Audio Connector

Puedes iniciar un Conector de audio WebSocket mediante la llamada a la función opentok.websocket.connect() método.

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 Ruby requiere Ruby 2.1.0 o una versión posterior.

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

Cambios en la versión 4.0.0:

El SDK ahora es compatible con Ruby v2.7 y requiere Ruby v2.1.0 o superior. Para Ruby v2.0.0, sigue utilizando el SDK de OpenTok para Ruby v3.0.0. Para Ruby v1.9.3, sigue utilizando el SDK de OpenTok para Ruby v2.5.0.

Novedades de la versión 3.0.0:

El SDK ahora requiere Ruby v2.0.0 o superior. Para Ruby v1.9.3, sigue utilizando el SDK de OpenTok para Ruby v2.5.0.

Cambios en la versión 2.2.2:

La configuración predeterminada para el create_session() 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.

Ten en cuenta también que el options del OpenTok.create_session() El método tiene un media_mode propiedad en lugar de un p2p propiedad.