SDK del servidor Ruby

El SDK Ruby de Vonage te permite interactuar con la Video API de Vonage mediante métodos para:

Instalación

Bundler (recomendado):

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

Añada la gema a la carpeta Gemfile:

Permite a bundler instalar la gema en tu proyecto.

$ bundle install

RubyGems:

También puedes instalar la gema directamente en tu sistema a través de la línea de comandos utilizando la CLI de RubyGems gem install comando.

$ gem install vonage

Utilización

Inicialización de

Cargue la gema en la parte superior de cualquier archivo en el que se vaya a utilizar. A continuación, inicialice un Vonage::Client usando la clave privada y el ID de aplicación asociados con tu aplicación de Vonage Video.

Nota: en el ejemplo anterior se supone que tienes los valores de tu ID de aplicación de Vonage y la ruta a tu clave privada guardados como variables de entorno en un archivo ENV con las claves VONAGE_APPLICATION_ID y VONAGE_PRIVATE_KEY_PATH respectivamente.

Opciones de inicialización

El cliente de Vonage permite algunas anulaciones de las opciones de configuración predeterminadas cuando surgen necesidades especiales, como la necesidad de apuntar a un centro de datos diferente.

Este ejemplo utiliza el video_host: para anular la URL base predeterminada de la Video API. Esto es útil cuando se necesita seleccionar un centro de datos específico o apuntar a un servidor simulado de la API con fines de prueba.

Creación de sesiones

A crear una sesión de video de Vonage con el SDK de Ruby, utilice la función Video#create_session método. El método acepta algunos parámetros de palabras clave opcionales:

  • :media_mode: si la sesión utiliza o no el Router multimedia de vídeo de Vonageque es necesario para algunas funciones de Vonage Video (como el archivado). Las opciones válidas son 'routed' (para utilizar el enrutador de medios, este es el valor predeterminado) o 'relayed' (para streaming peer-to-peer)
  • :archive_mode: Si la sesión se archiva automáticamente o no. Las opciones válidas son 'always' (para archivado automático) o 'manual' (para el archivado controlado manualmente, éste es el valor por defecto)
  • :location: Una pista de ubicación para el servidor de Vonage Video.

A continuación se muestran algunos ejemplos de creación de sesiones con diferentes configuraciones:

  • Crear una sesión utilizando la configuración por defecto (media_mode por defecto 'routed'que utilizará el router de medios de Vonage, y archive_mode por defecto 'manual'que no crear automáticamente un archivo):

  • Creación de una sesión que intentará transmitir flujos directamente entre clientes (tenga en cuenta que archive_mode DEBE SER 'manual'por defecto, para media_mode ser 'relayed'):

  • Crear una sesión con una pista de ubicación:

  • Creación de una sesión con archivado automático (DEBE utilizar la opción 'routed' modo multimedia, que es el predeterminado):

Puede utilizar la función session_id del método devuelto Vonage::Response para obtener el ID de sesión de la sesión creada. Esto se puede asignar a una variable o utilizar más tarde, como cuando generar fichas:

Generación de fichas

Una vez creada una Sesión, puede empezar Generación de tokens para que los clientes lo utilicen al conectarse a la sesión.

Puede generar un token llamando a la función Video#generate_client_token método. El método espera un argumento de palabra clave obligatorio :session_idque es el ID de la sesión para la que desea crear el token (véase Creación de sesiones más arriba). Además, el método acepta algunos parámetros de palabras clave opcionales:

  • :scope: el ámbito del token. Sólo se puede establecer en 'session.connect'por defecto.
  • :role: el papel del cliente. Las opciones válidas son 'publisher' (por defecto), 'subscriber', 'moderator'y 'publisher-only'. Véase papeles
  • :data: una cadena que contiene metadatos que describen al cliente, por ejemplo, un identificador de usuario o un nombre. Véase Datos de conexión
  • :expire_timeun tiempo de caducidad de hasta 30 días para el token (después del cual no se puede utilizar para conectarse a la sesión), como número entero Segundos de época. Por defecto son 24 horas.
  • :initial_layout_class_list:

A continuación figuran algunos ejemplos de generación de fichas:

  • Generar un token con la configuración predeterminada:

  • Generar un token con algunas opciones específicas

Trabajar con flujos

El Ruby SDK proporciona métodos para obtener información sobre una transmisión específica de Vonage Video conectada a una sesión o para obtener información sobre todas las transmisiones de esa sesión (consulte Creación de sesiones).

Para obtener información sobre todos los flujos de una sesión, utilice la función Streams#list método:

A continuación, puede llamar a varios métodos de acceso en la devuelta Vonage::Streams::ListResponse para obtener información sobre la lista de flujos:

En items contiene flujos individuales conectados a la sesión en forma de Vonage::Entity sobre los que puede llamar a métodos de acceso. Por ejemplo, para obtener el ID del primer flujo de la lista de flujos, puede hacer lo siguiente:

En Vonage::Streams::ListResponse La clase incluye Enumerablepara que pueda llamar a cualquier Enumerable en un Vonage::Streams::ListResponse objeto. Por ejemplo, para obtener una matriz de los ID de todos los flujos conectados a la sesión, puede hacer lo siguiente:

Para obtener información de un flujo específico en una sesión, utilice la función Streams#info método:

A continuación, puede llamar a varios métodos de acceso en la devuelta Vonage::Response para obtener información sobre el flujo:

Trabajar con archivos

La Video API de Vonage te permite archivar, guardar y recuperar sesiones.

Sólo puedes archivar sesiones que utilicen el router de medios de vídeo de Vonage (sesiones con el modo multimedia ajustado a routed).

Iniciar una grabación de archivo

Cuando crear una sesiónpuede ajustar el archive_mode a 'always' para crear automáticamente una grabación de archivo de una sesión. Si configura la opción archive_mode a 'manual' puede iniciar una grabación de archivo de la sesión utilizando el botón Archives#start método.

El método requiere un argumento de palabra clave, :session_idpara la sesión que se va a archivar, y también toma algunos argumentos de palabras clave opcionales que le permiten establecer el parámetro :has_audio, :has_videoy :name opciones. Tenga en cuenta que sólo puede iniciar un Archivo en una Sesión que ya tenga clientes conectados.

A continuación se ofrecen algunos ejemplos de creación de archivos:

  • Crear un archivo

  • Crear un archivo con nombre

  • Crear un archivo sólo de audio

Puede utilizar la función id del método devuelto Vonage::Response para obtener el Id. de archivo del archivo creado. A continuación, puede utilizar este ID para otras interacciones con el archivo, como detener la grabación del archivo o recuperar información sobre el archivo.

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

Ajuste del output_mode opción de 'composed' (por defecto) hace que todos los flujos del archivo se graben en un único archivo (compuesto).

Para los archivos compuestos, puede establecer el resolution del archivo, "640x480" (SD horizontal, por defecto), "1280x720" (HD horizontal), "1920x1080" (FHD horizontal), "480x640" (SD vertical), "720x1280" (HD vertical) o "1080x1920" (FHD vertical).

Para personalizar la disposición inicial de los archivos compuestos, puede utilizar la función layout opción. Establece un hash que contenga dos claves: :type y :stylesheet.

Valores válidos para :type son "bestFit" (mejor ajuste), "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 a una cadena de estilos CSS. (Para otros tipos de diseño, no establezca el parámetro :stylesheet llave).

Si no se especifica un tipo de diseño inicial, el archivo utiliza el formato 'bestFit' tipo de diseño. Para más información, consulte Personalización del diseño de vídeo para archivos compuestos.

Tenga en cuenta que también puede crear una sesión archivada automáticamente, pasando en 'always' como valor el :archive_mode que se pasa al argumento Video#create_session (véase Creación de sesiones arriba).

Detener una grabación de archivo

Puede detener la grabación de un Archivo iniciado utilizando la tecla Archives#stop y pasando el método :archive_id del archivo a detener.

Información sobre los archivos

Puede recuperar información sobre una grabación de archivo específica utilizando la función Archives#info y pasando el método :archive_id del archivo.

También puede obtener una lista de todos los Archivos que ha creado (hasta 1000). Para ello, utilice la función Archives#list método. El método puede tomar :offset y :count para ayudarle a paginar los resultados. Devolverá una instancia de Video::Archives::ListResponse clase.

Borrar un archivo

Para eliminar un Archivo, puede llamar a la función Archives#delete y pasando el método archive_id del archivo a eliminar.

Definir el diseño de un archivo

Puede definir el diseño de un archivo mediante la opción Archives#change_layout método:

El método requiere archive_id así como tres argumentos opcionales (type, stylesheety screenshare_type):

  • En type es el tipo de presentación para el archivo. Los valores válidos son "bestFit" (mejor ajuste) "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 presentación, no establezca la propiedad stylesheet).

  • En screenshare_type indica el tipo de presentación a utilizar cuando hay un flujo de pantalla compartida en la sesión. Tenga en cuenta que para utilizar esta propiedad, debe establecer la propiedad type a "bestFit" y dejar la propiedad stylesheet no está activada. Para más información, véase Tipos de diseño para pantalla compartida.

Puede establecer la clase de diseño inicial para los flujos de un cliente estableciendo la clase layout al crear el token para el cliente, utilizando la opción Video#generate_client_token método.

El diseño de los archivos compuestos es opcional. Por defecto, los archivos compuestos utilizan el diseño "más adecuado". Véase Personalización del diseño de vídeo para archivos compuestos para más detalles.

Trabajar con emisiones

La Video API de Vonage te permite sesiones de difusión.

Sólo puedes transmitir sesiones que utilicen el router de medios de vídeo de Vonage (sesiones con el modo multimedia ajustado a routed).

Iniciar una emisión

Puede iniciar una retransmisión de la sesión utilizando el botón Broadcasts#start método. El método requiere un argumento de palabra clave, :session_idpara la sesión que se va a retransmitir, y también toma algunos argumentos de palabra clave opcionales que le permiten especificar la configuración de la retransmisión:

  • layout: se utiliza para personalizar el diseño de la emisión. Establecer esto a un hash que contiene tres claves:
    • :type (obligatorio). Los valores válidos son "bestFit" (mejor ajuste), "custom" (costumbre), "horizontalPresentation" (presentación horizontal), "pip" (imagen en imagen) y "verticalPresentation" (presentación vertical).
    • :stylesheet: (obligatorio si :type se establece en 'custom'). Si especifica un tipo de diseño "personalizado", defina el parámetro :stylesheet a una cadena de estilos CSS. (Para otros tipos de diseño, no establezca el parámetro :stylesheet llave).
    • :screenshareType: se utiliza para establecer la propiedad screenshareType al tipo de presentación que se utilizará cuando haya un flujo de pantalla compartida en la sesión. Los valores válidos son "bestFit" (mejor ajuste), "custom" (costumbre), "horizontalPresentation" (presentación horizontal), "pip" (imagen en imagen) y "verticalPresentation" (presentación vertical).
  • max_duration: La duración máxima de la emisión, en segundos. El valor predeterminado es 4 horas.
  • outputs: Un hash que define los tipos de flujos de emisión que desea iniciar (tanto HLS como RTMP). El hash tiene dos claves posibles, :hls y/o rtmp:
    • :hls: se trata de un hash con dos posibles claves (ambas valores booleanos), :dvr (si desea activar la función DVR), y :lowLatency (si se activa el modo de baja latencia para el flujo HLS)
    • :rtmpuna matriz de hasta cinco hashes, cada uno de los cuales contiene información sobre flujos de difusión RTMP. Cada hash puede especificar un :id para el flujo, una :serverUrl para el servidor RTMP, y un :streamName.
  • :resolution: una cadena que especifica la resolución de la emisión. Las opciones válidas son 640x480, 1280x720, 1920x1080, 480x640, 720x1280, 1080x1920
  • :stream_mode: o auto (por defecto), o manual
  • :multi_broadcast_tagsi admite varias emisiones para la misma sesión, defina una cadena única para cada emisión simultánea.
  • :max_bitrate: El bitrate máximo para el flujo

A continuación se ofrecen algunos ejemplos de creación de emisiones:

  • Crear una emisión HLS

  • Crear una difusión RTMP

Puede utilizar la función id del método devuelto Vonage::Response para obtener el ID de la emisión creada. A continuación, puede utilizar este ID para otras interacciones con la emisión, como detenerla o recuperar información sobre ella.

Detener una emisión

Puede detener una emisión utilizando la tecla Broadcasts#stop y pasando el método :broadcast_id de la Emisión a detener.

Información sobre radiodifusión

Puede obtener información sobre una emisión concreta utilizando la función Broadcast#info y pasando el método :broadcast_id de la emisión.

También puede obtener una lista de todas las difusiones que ha creado. Para ello, utilice la función Broadcasts#list método. El método puede tomar :offset y :count para ayudarle a paginar los resultados. Devolverá una instancia de Video::Broadcasts::ListResponse clase.

Señalización

Puedes enviar una señal a un participante específico de una sesión activa de Vonage Video o a todos los participantes.

Para enviar a un participante concreto, utilice la opción Signals#send_to_one método.

Para enviar a todos los participantes, utilice Signals#send_to_all método.

Ambos métodos requieren session_id, typey data argumentos de la palabra clave. La dirección send_to_one requiere además un método connection_id argumento de palabra clave que identifica al participante específico al que debe enviarse la señal.

La longitud máxima del type es de 128 bytes y sólo debe contener letras (A-Z y a-z), números (0-9), '-', '_' y '~'.

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

Para más información sobre la señalización, consulte el Señalización de vídeo de Vonage guía de programación.

Moderación

Puede sesiones moderadas de varias maneras.

Puede hacer que un cliente se vea obligado a desconectarse de una sesión utilizando la función Moderation#force_disconnect pasando el método session_id de la sesión de vídeo de Vonage activa y el connection_id del cliente a desconectar.

Puedes silenciar una transmisión específica en una sesión activa de Vonage Video o silenciar múltiples transmisiones en esa sesión.

Para silenciar un flujo específico, utilice la tecla Moderation#mute_single_stream pasando el método session_id de la sesión de vídeo de Vonage activa y el stream_id del flujo a silenciar.

Para silenciar varios flujos en una sesión, utilice la función Moderation#mute_multiple_streams método.

Así como el session_idEl mute_multiple_streams define dos argumentos clave adicionales:

  • En active es obligatorio y debe tener el valor true o false. Ajuste a true activa el estado mudo de la sesión, significa que todos los flujos actuales y futuros publicados en la sesión (a excepción de los flujos en el estado excluded_stream_ids array) se silencian. Cuando se llama a este método con el parámetro active con el valor falseSi la sesión está silenciada, los flujos futuros publicados en la sesión no se silencian (pero los flujos silenciados existentes permanecen silenciados).

  • En excluded_stream_ids es opcional y toma una matriz de ids de flujos que deben ser excluidos de ser silenciados.

Trabajar con SIP

Puede iniciar un Llamada SIP utilizando el SIP#dial método. El método tiene tres argumentos de palabra clave requeridos:

  • :session_id: el ID de la sesión a la que se va a marcar.
  • :tokenun token de cliente para la sesión (véase Generación de tokens de cliente)
  • :sip_uri: el URI SIP que se utilizará como destino de la llamada SIP iniciada desde Vonage Video a tu plataforma SIP.

A continuación se muestra un ejemplo de uso de SIP#dial método:

Para obtener más información sobre SIP Interconnect, consulte la página Interconexión SIP de vídeo de Vonage guía del desarrollador.

Requisitos

Necesitarás un ID de aplicación y una clave privada para una aplicación de Vonage habilitada para video. Puedes crear una aplicación de Vonage a través de la sección Panel de Vonage.

Vonage Video Ruby SDK es compatible con Ruby 2.7.0 o superior.

Notas de publicación

Tenga en cuenta que la funcionalidad de vídeo se encuentra en SDK Ruby de Vonage de la versión 7.19.0.

Véase el Comunicados para más detalles.