SDK Ruby Server

Le SDK Ruby de Vonage vous permet d'interagir avec l'API Video de Vonage en fournissant des méthodes pour :

Installation

Bundler (recommandé) :

Bundler aide à gérer les dépendances pour les projets Ruby. Plus d'informations ici : http://bundler.io

Ajoutez la gem à l'arborescence de votre projet Gemfile:

gem "vonage"

Permet à bundler d'installer la gem dans votre projet.

$ bundle install

RubyGems :

Vous pouvez également installer la Gem directement sur votre système via la ligne de commande en utilisant le CLI RubyGems gem install commande.

$ gem install vonage

Utilisation

Initialisation

Chargez la gemme au début de tout fichier où elle sera utilisée. Initialiser ensuite un fichier Vonage::Client à l'aide de la clé privée et de l'identifiant d'application associés à votre application Vonage Video.

require "vonage"

client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: File.read(ENV['VONAGE_PRIVATE_KEY_PATH'])
)

Remarque : l'exemple ci-dessus suppose que les valeurs de votre ID d'application Vonage et le chemin d'accès à votre clé privée sont sauvegardés en tant que variables d'environnement dans un fichier ENV avec les clés VONAGE_APPLICATION_ID et VONAGE_PRIVATE_KEY_PATH respectivement.

Options d'initialisation

Le client Vonage permet d'outrepasser certaines options de configuration par défaut lorsque des besoins particuliers se font sentir, comme la nécessité de pointer vers un centre de données différent.

require "vonage"

client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: File.read(ENV['VONAGE_PRIVATE_KEY_PATH']),
  video_host: 'country-specific-video.api.vonage.com'
)

Cet exemple utilise le video_host: pour remplacer l'URL de base par défaut de l'API Video. Cette option est utile pour sélectionner un centre de données spécifique ou pointer vers un serveur fictif de l'API à des fins de test.

Création de sessions

Vers créer une session vidéo Vonage avec le SDK Ruby, utilisez l'option Video#create_session méthode. La méthode accepte quelques paramètres optionnels :

  • :media_mode: si la session utilise ou non l'option Routeur vidéo multimédia de Vonagequi est nécessaire pour certaines fonctions de Vonage Video (comme l'archivage). Les options valables sont 'routed' (pour utiliser le routeur multimédia, c'est la valeur par défaut) ou 'relayed' (pour le streaming peer-to-peer)
  • :archive_mode: La session est automatiquement archivée ou non. Les options valables sont 'always' (pour l'archivage automatique) ou 'manual' (pour l'archivage contrôlé manuellement, c'est la valeur par défaut)
  • :location: Un indice d'emplacement pour le serveur vidéo de Vonage.

Vous trouverez ci-dessous quelques exemples de création de sessions avec différents paramètres :

  • Créer une session en utilisant les paramètres par défaut (media_mode La valeur par défaut est 'routed'qui utilisera le routeur média de Vonage, et archive_mode La valeur par défaut est 'manual'qui n'est pas créer automatiquement une archive) :

    session = client.video.create_session

  • Création d'une session qui tentera de transmettre des flux directement entre les clients (notez que archive_mode DOIT ÊTRE 'manual'qui est la valeur par défaut, pour media_mode être 'relayed') :

    session = client.video.create_session(media_mode: 'relayed')

  • Création d'une session avec un indice de localisation :

    session = client.video.create_session(location: '12.34.56.78')

  • Création d'une session avec archivage automatique (utiliser IMPERATIVEMENT l'option 'routed' mode média, qui est le mode par défaut) :

    session = client.video.create_session(archive_mode: 'always')

Vous pouvez utiliser le session_id de la méthode d'accès au Vonage::Response pour obtenir l'identifiant de la session créée. Cet identifiant peut être assigné à une variable pour une utilisation ultérieure, par exemple lors de la création d'une session. générer des jetons:

session_id = session.session_id

Générer des jetons

Une fois la session créée, vous pouvez commencer générer des jetons que les clients doivent utiliser pour se connecter à la session.

Vous pouvez générer un jeton en appelant la fonction Video#generate_client_token méthode. La méthode attend un mot-clé obligatoire en guise d'argument :session_idqui est l'ID de la session pour laquelle vous souhaitez créer le jeton (voir Création de sessions ci-dessus). En outre, la méthode accepte quelques paramètres facultatifs de type mot-clé :

  • :scope: le champ d'application du jeton. Cette valeur ne peut être définie que comme 'session.connect'qui est la valeur par défaut.
  • :role: le rôle du client. Les options valables sont 'publisher' (qui est la valeur par défaut), 'subscriber', 'moderator'et 'publisher-only'. Voir rôles
  • :dataune chaîne de caractères contenant des métadonnées décrivant le client, par exemple un nom ou un identifiant d'utilisateur. Voir Données de connexion
  • :expire_timeun délai d'expiration de 30 jours maximum pour le jeton (après quoi il ne peut plus être utilisé pour se connecter à la session), sous la forme d'un nombre entier. Secondes d'époque. La valeur par défaut est de 24 heures.
  • :initial_layout_class_list:

Voici quelques exemples de génération de jetons :

  • Générer un jeton avec les paramètres par défaut :

    token = client.video.generate_client_token(session_id: session_id)

  • Générer un jeton avec quelques options spécifiques

    token = client.video.generate_client_token(
  session_id: session_id,
  role: 'moderator',
  expire_time: Time.now.to_i+(7 * 24 * 60 * 60), # in one week
  data: 'name=Johnny',
  initial_layout_class_list: ['focus', 'inactive']
)

Travailler avec des flux

Le SDK Ruby fournit des méthodes pour obtenir des informations sur un flux vidéo Vonage spécifique connecté à une session ou pour obtenir des informations sur tous les flux de cette session (voir Création de sessions).

Pour obtenir des informations sur tous les flux d'une session, utilisez la commande Streams#list méthode :

streams = client.video.streams.list(session_id: session_id)

Vous pouvez ensuite appeler diverses méthodes d'accès à l'objet retourné Vonage::Streams::ListResponse pour obtenir des informations sur la liste des flux :

streams.count # => integer with the number of streams in the list
streams.items # => array of streams connected to the session

Les items contient les flux individuels connectés à la session sous la forme de Vonage::Entity sur lesquels vous pouvez appeler des méthodes d'accès. Par exemple, pour obtenir l'ID du premier flux de la liste des flux, vous pouvez procéder comme suit :

stream_id = streams.items.first.id # => "af61926e-77dd-43ae-aa83-0b7e2835b3a0"

Les Vonage::Streams::ListResponse La classe comprend EnumerableVous pouvez donc appeler n'importe quel Enumerable sur un Vonage::Streams::ListResponse objet. Par exemple, pour obtenir un tableau des identifiants de tous les flux connectés à la session, vous pouvez procéder comme suit :

stream_ids_array = streams.map { |stream| stream.id }

Pour obtenir des informations sur un flux spécifique dans une session, utilisez la fonction Streams#info méthode :

stream = client.video.streams.info(session_id: session_id, stream_id: stream_id)

Vous pouvez ensuite appeler diverses méthodes d'accès à l'objet retourné Vonage::Response pour obtenir des informations sur le flux :

stream.id # string with the stream ID
stream.video_type # string with the video type
stream.name # string with the name
stream.layout_class_list # array with the layout class list

Travailler avec les archives

L'API Video de Vonage vous permet de archiver, sauvegarder et retrouver les sessions.

Vous ne pouvez archiver que les sessions qui utilisent le routeur vidéo de Vonage (sessions avec l'option mode média fixé à routed).

Démarrage d'un enregistrement d'archive

Lorsque vous créer une session, vous pouvez régler la archive_mode à 'always' pour créer automatiquement un enregistrement d'archive d'une session. Si vous définissez l'option archive_mode à 'manual' vous pouvez à la place lancer un enregistrement d'archive de la session en utilisant l'option Archives#start méthode.

La méthode requiert un argument de type mot-clé, :session_idpour la session à archiver, et prend également des arguments optionnels de type mot-clé qui vous permettent de définir la valeur de l'option :has_audio, :has_videoet :name options. Notez que vous ne pouvez lancer une archive que sur une session où des clients sont déjà connectés.

Voici quelques exemples de création d'archives :

  • Créer une archive

    archive = client.video.archives.start(session_id: session_id)

  • Créer une archive nommée

    archive = client.video.archives.start(session_id: session_id, name: 'Important Presentation')

  • Créer une archive audio uniquement

    archive = client.video.archives.start(session_id: session_id, has_video: false)

Vous pouvez utiliser le id de la méthode d'accès au Vonage::Response pour obtenir l'identifiant de l'archive créée. Vous pouvez ensuite utiliser cet identifiant pour d'autres interactions avec l'archive, telles que l'arrêt de l'enregistrement de l'archive ou la récupération d'informations sur l'archive.

archive_id = archive.id

Réglage de la output_mode à l'option 'individual' permet d'enregistrer chaque flux de l'archive dans son propre fichier :

archive = client.video.archives.start(session_id: session_id, output_mode: 'individual')

Réglage de la output_mode à l'option 'composed' (par défaut) permet d'enregistrer tous les flux de l'archive dans un seul fichier (composé).

Pour les archives composées, vous pouvez définir l'option resolution de l'archive, "640x480" (SD paysage, par défaut), "1280x720" (HD paysage), "1920x1080" (FHD paysage), "480x640" (SD portrait), "720x1280" (HD portrait), ou "1080x1920" (FHD portrait).

archive = client.video.archives.start(session_id: session_id, output_mode: 'composed', resolution: '1280x720')

Pour personnaliser la présentation initiale des archives composées, vous pouvez utiliser la fonction layout option. Il s'agit d'un hachage contenant deux clés : :type et :stylesheet.

Valeurs valables pour :type sont "bestFit" (meilleur ajustement), "custom" (personnalisé), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image) et "verticalPresentation" (présentation verticale).

Si vous spécifiez un type de mise en page "personnalisé", définissez le paramètre :stylesheet à une chaîne de styles CSS. (Pour les autres types de mise en page, ne pas définir la clé :stylesheet clé.)

archive = client.video.archives.start(
  session_id: session_id
  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%;}'
  }
}

Si vous ne spécifiez pas de type de mise en page initiale, l'archive utilise le type de mise en page 'bestFit' type de mise en page. Pour plus d'informations, voir Personnalisation de la présentation vidéo pour les archives composées.

Notez que vous pouvez également créer une session automatiquement archivée, en passant le paramètre 'always' comme valeur la :archive_mode passé dans le mot-clé Video#create_session (voir Création de sessions ci-dessus).

Arrêt d'un enregistrement d'archive

Vous pouvez arrêter l'enregistrement d'une archive commencée à l'aide de la touche Archives#stop et en passant par la méthode :archive_id de l'archive à arrêter.

client.video.archives.stop(archive_id: archive_id)

Obtenir des informations sur les archives

Vous pouvez obtenir des informations sur un enregistrement d'archive spécifique à l'aide de la fonction Archives#info et en passant par la méthode :archive_id de l'archive.

archive_info = client.video.archives.info(archive_id: archive_id)

Vous pouvez également obtenir une liste de toutes les archives que vous avez créées (jusqu'à 1000). Cette opération s'effectue à l'aide de la fonction Archives#list méthode. La méthode peut prendre en compte des éléments optionnels :offset et :count pour vous aider à paginer dans les résultats. Cette méthode renvoie une instance de la classe Video::Archives::ListResponse classe.

archive_list = client.video.archives.list

Suppression d'une archive

Pour supprimer une archive, vous pouvez appeler le Archives#delete et en passant par la méthode archive_id de l'archive à supprimer.

client.video.archives.delete(archive_id: archive_id)

Définition de la mise en page d'une archive

Vous pouvez définir la mise en page d'une archive à l'aide de la fonction Archives#change_layout méthode :

client.video.archives.change_layout(
  archive_id: archive_id,
  type: 'verticalPresentation'
)

La méthode prend un archive_id ainsi que trois arguments facultatifs (type, stylesheetet screenshare_type) :

  • Les type est le type de présentation de l'archive. Les valeurs valides sont "bestFit" (meilleur ajustement), "custom" (personnalisé), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image) et "verticalPresentation" (présentation verticale).

  • Si vous spécifiez un type de mise en page "personnalisé", définissez le paramètre stylesheet (pour les autres types de mise en page, ne pas définir la propriété de la feuille de style). (Pour les autres types de mise en page, ne pas définir la propriété de feuille de style).

  • Les screenshare_type indique le type de mise en page à utiliser lorsqu'il y a un flux de partage d'écran dans la session. Notez que pour utiliser cette propriété, vous devez définir la propriété type à "bestFit" et laisser la propriété stylesheet n'est pas définie. Pour plus d'informations, voir Types de mise en page pour le partage d'écran.

Vous pouvez définir la classe de mise en page initiale pour les flux d'un client en définissant la propriété layout lorsque vous créez le jeton pour le client, en utilisant l'option Video#generate_client_token méthode.

La définition de la mise en page des archives composées est facultative. Par défaut, les archives composées utilisent la mise en page "best fit". Voir Personnalisation de la présentation vidéo pour les archives composées pour plus de détails.

Travailler avec des diffusions

L'API Video de Vonage vous permet de sessions de diffusion.

Vous ne pouvez diffuser que les sessions qui utilisent le routeur vidéo de Vonage (sessions avec l'option mode média fixé à routed).

Lancement d'une diffusion

Vous pouvez lancer une diffusion de la session à l'aide de la fonction Broadcasts#start méthode. La méthode requiert un argument de type mot-clé, :session_idpour que la session soit diffusée, et prend également des arguments optionnels de type mot-clé qui vous permettent de spécifier les paramètres de la diffusion :

  • layout: utilisé pour personnaliser la mise en page de la diffusion. Il s'agit d'un hachage contenant trois clés :
    • :type (obligatoire). Les valeurs valides sont "bestFit" (meilleur ajustement), "custom" (sur mesure), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image) et "verticalPresentation" (présentation verticale).
    • :stylesheet(obligatoire si :type est fixé à 'custom'). Si vous spécifiez un type de mise en page "personnalisé", définissez le paramètre :stylesheet à une chaîne de styles CSS. (Pour les autres types de mise en page, ne pas définir la clé :stylesheet clé.)
    • :screenshareType: utilisée pour définir la propriété screenshareType sur le type de mise en page à utiliser lorsqu'il y a un flux de partage d'écran dans la session. Les valeurs valides sont "bestFit" (meilleur ajustement), "custom" (sur mesure), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image) et "verticalPresentation" (présentation verticale).
  • max_duration: Durée maximale de la diffusion, en secondes. La valeur par défaut est de 4 heures.
  • outputs: Un hachage qui définit les types de flux de diffusion que vous souhaitez lancer (à la fois HLS et RTMP). Le hachage a deux clés possibles, :hls et/ou rtmp:
    • :hls: il s'agit d'un hachage avec deux clés possibles (toutes deux des valeurs booléennes), :dvr (pour activer ou non la fonctionnalité DVR), et :lowLatency (activation ou non du mode faible latence pour le flux HLS)
    • :rtmp: un tableau comprenant jusqu'à cinq hachages, chacun contenant des informations sur les flux de diffusion RTMP. Chaque hachage peut spécifier un :id pour le flux, un :serverUrl pour le serveur RTMP, et un :streamName.
  • :resolution: une chaîne de caractères spécifiant la résolution de la diffusion. Les options valables sont 640x480, 1280x720, 1920x1080, 480x640, 720x1280, 1080x1920
  • :stream_mode: soit auto (par défaut), ou manual
  • :multi_broadcast_tag: si plusieurs diffusions sont prises en charge pour la même session, définir une chaîne unique pour chaque diffusion simultanée.
  • :max_bitrate: Le débit binaire maximum pour le flux

Vous trouverez ci-dessous quelques exemples de création d'émissions :

  • Créer une diffusion HLS

    broadcast = client.video.archives.start(
  session_id: session_id,
  outputs: {
    hls: {
      dvr: true,
      lowLatency: true
    }
  }
)

  • Créer une diffusion RTMP

    broadcast = client.video.archives.start(
  session_id: session_id,
  outputs: {
    rtmp: [
      {
        id: 'foo',
        serverURL: "rtmps://myfooserver/myfooapp",
        streamName: "myfoostream"
      }
    ]
  }
)

Vous pouvez utiliser le id de la méthode d'accès au Vonage::Response pour obtenir l'identifiant de la diffusion créée. Vous pouvez ensuite utiliser cet identifiant pour d'autres interactions avec la diffusion, telles que l'arrêt de la diffusion ou la récupération d'informations sur la diffusion.

broadcast_id = broadcast.id

Arrêt d'une diffusion

Vous pouvez arrêter une diffusion à l'aide de la touche Broadcasts#stop et en passant par la méthode :broadcast_id de l'émission à arrêter.

client.video.broadcasts.stop(broadcast_id: broadcast_id)

Obtenir des informations sur la radiodiffusion

Vous pouvez obtenir des informations sur une diffusion spécifique à l'aide de la fonction Broadcast#info et en passant par la méthode :broadcast_id de l'émission.

broadcast_info = client.video.broadcasts.info(broadcast_id: broadcast_id)

Vous pouvez également obtenir une liste de toutes les diffusions que vous avez créées. Cela se fait à l'aide de la fonction Broadcasts#list méthode. La méthode peut prendre en compte des éléments optionnels :offset et :count pour vous aider à paginer dans les résultats. Cette méthode renvoie une instance de la classe Video::Broadcasts::ListResponse classe.

broadcast_list = client.video.broadcasts.list

Signalisation

Vous pouvez envoyer un signal à un participant spécifique d'une session vidéo Vonage active ou à tous les participants.

Pour envoyer un message à un participant spécifique, utilisez la fonction Signals#send_to_one méthode.

client.video.signals.send_to_one(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  connection_id: '909b9024-901d-11ed-a1eb-0242ac120002',
  type: 'chat',
  data: 'Hello'
)

Pour envoyer un message à tous les participants, utilisez la fonction Signals#send_to_all méthode.

client.video.signals.send_to_all(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  type: 'chat',
  data: 'Hello'
)

Les deux méthodes nécessitent session_id, typeet data les arguments du mot-clé. L'argument send_to_one nécessite en outre un connection_id mot-clé qui identifie le participant spécifique auquel le signal doit être envoyé.

La longueur maximale du type est de 128 octets et ne doit contenir que des lettres (A-Z et a-z), des chiffres (0-9), des "-", des "_" et des "~".

Les data ne doit pas dépasser la taille maximale (8 kB).

Pour plus d'informations sur la signalisation, voir le document Signalisation vidéo Vonage guide de programmation.

La modération

Vous pouvez sessions modérées de plusieurs manières.

Vous pouvez forcer un client à se déconnecter d'une session en utilisant la commande Moderation#force_disconnect en passant par la méthode session_id de la session vidéo active de Vonage et de la connection_id du client à déconnecter.

client.video.moderation.force_disconnect(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  connection_id: '909b9024-901d-11ed-a1eb-0242ac120002'
)

Vous pouvez mettre en sourdine un flux spécifique dans une session vidéo Vonage active, ou mettre en sourdine plusieurs flux dans cette session.

Pour couper le son d'un flux spécifique, utilisez la fonction Moderation#mute_single_stream en passant par la méthode session_id de la session vidéo active de Vonage et de la stream_id du flux à mettre en sourdine.

client.video.moderation.mute_single_stream(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  stream_id: '684d899a-901f-11ed-a1eb-0242ac120002'
)

Pour mettre en sourdine plusieurs flux dans une session, utilisez la fonction Moderation#mute_multiple_streams méthode.

client.video.moderation.mute_multiple_streams(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  active: true,
  excluded_stream_ids: [
    '2c2a905c-9029-11ed-a1eb-0242ac120002',
    '2c2a92f0-9029-11ed-a1eb-0242ac120002',
    '2c2a97c8-9029-11ed-a1eb-0242ac120002'
  ]
)

En plus de la session_id, le mute_multiple_streams définit deux arguments supplémentaires sous forme de mots-clés :

  • Les active est requis et doit être défini comme suit true ou false. Réglage de la true active l'état muet de la session, ce qui signifie que tous les flux actuels et futurs publiés dans la session (à l'exception des flux dans la section excluded_stream_ids ) sont mis en sourdine. Lorsque vous appelez cette méthode avec l'option active est définie comme étant la propriété falseles flux futurs publiés dans la session ne sont pas mis en sourdine (mais les flux mis en sourdine existants restent mis en sourdine).

  • Les excluded_stream_ids Le mot-clé est facultatif et prend la forme d'un tableau d'identifiants de flux à exclure de la mise en sourdine.

Travailler avec SIP

Vous pouvez lancer un Appel SIP en utilisant le SIP#dial méthode. La méthode comporte trois arguments obligatoires de type mot-clé :

  • :session_id: l'identifiant de la session à composer.
  • :tokenun jeton client pour la session (voir Générer des jetons de client)
  • :sip_uri: l'URI SIP à utiliser comme destination de l'appel SIP initié depuis Vonage Video vers votre plateforme SIP.

Vous trouverez ci-dessous un exemple d'utilisation de la fonction SIP#dial méthode :

client.video.sip.dial(
  session_id: session_id,
  token: token,
  sip_uri: "sip:+15128675309@acme.pstn.example.com;transport=tls"
)

Pour plus d'informations sur l'interconnexion SIP, voir le document Interconnexion vidéo SIP de Vonage guide du développeur.

Exigences

Vous aurez besoin d'un identifiant d'application et d'une clé privée pour une application Vonage compatible avec la vidéo. Vous pouvez créer une application Vonage par l'intermédiaire de la page d'accueil de Vonage. Tableau de bord Vonage.

Le SDK Ruby de Vonage Video supporte Ruby 2.7.0 ou plus.

Notes de mise à jour

Notez que la fonctionnalité vidéo se trouve dans la section SDK Ruby de Vonage de la version 7.19.0.

Voir le Communiqués pour plus de détails.