Video API Vonage – SDK Ruby

Le SDK Ruby d'OpenTok propose des méthodes permettant de :

Installation

Bundler (recommandé) :

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

Ajoutez ce petit bijou à votre Gemfile:

gem "opentok", "~> 4.0.0"

Autorisez Bundler à installer la modification.

$ bundle install

RubyGems :

$ gem install opentok

Utilisation

Initialisation

Chargez le gem en début de n'importe quel fichier dans lequel il sera utilisé. Ensuite, initialisez un OpenTok::OpenTok objet avec votre clé API OpenTok et votre secret API.

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret

Options d'initialisation

Délai d'expiration personnalisé

Vous pouvez définir une valeur de délai d'expiration personnalisée pour les requêtes HTTP lors de l'initialisation d'un nouveau OpenTok::OpenTok objet :

require "opentok"

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

La valeur de :timeout_length Il s'agit d'un nombre entier représentant le nombre de secondes à attendre avant qu'une requête HTTP ne soit terminée. La valeur par défaut est de 2 secondes.

Annexe UA

Vous pouvez également ajouter une chaîne personnalisée à la User-Agent valeur d'en-tête pour les requêtes HTTP lors de l'initialisation d'un nouveau OpenTok::OpenTok objet :

require "opentok"

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

Le code ci-dessus générerait un User-Agent un en-tête du genre :

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

Création de sessions

Pour créer une session OpenTok, utilisez la commande OpenTok#create_session(properties) méthode. La méthode properties Le paramètre est un Hash facultatif permettant de spécifier les éléments suivants :

  • Que la session utilise le OpenTok Media Routeur, ce qui est nécessaire pour certaines fonctionnalités d'OpenTok (telles que l'archivage)

  • Une indication de l'emplacement du serveur OpenTok.

  • Si la session est automatiquement archivée.

Les session_id méthode de la valeur renvoyée OpenTok::Session Cette instance est utile pour obtenir un identifiant de session (sessionId) qui peut être enregistré dans un magasin persistant (tel qu'une base de données).

# 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

Générer des jetons

Une fois qu'une session est créée, vous pouvez commencer à générer des jetons que les clients utiliseront pour se connecter à la session. Vous pouvez générer un jeton soit en appelant la fonction opentok.generate_token(session_id, options) méthode, ou en appelant la Session#generate_token(options) méthode sur l'instance après sa création. La options Le paramètre est un hash facultatif permettant de définir le rôle, la durée de validité et les données de connexion du jeton. Pour le contrôle de la mise en page dans les archives et les diffusions, il est également possible de définir la liste initiale des classes de mise en page des flux publiés à partir des connexions utilisant ce jeton.

## 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']
});

Travailler avec des flux

Utilisez cette méthode pour obtenir des informations sur un flux OpenTok ou sur tous les flux d'une session. Par exemple, vous pouvez appeler cette méthode pour obtenir des informations sur les classes de mise en page utilisées par un flux OpenTok.

Pour obtenir des informations sur un flux spécifique au sein d'une session, appelez opentok.streams.find(session_id, stream_id). L'objet renvoyé est un Stream objet, et vous pouvez accéder à diverses propriétés du flux, comme le montre l'exemple suivant (en utilisant la notation 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"

Pour obtenir des informations sur tous les flux d'une session, appelez opentok.streams.all(session_id). La valeur de retour est un StreamList objet :

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"

Travailler avec les archives

Vous ne pouvez archiver que les sessions qui utilisent OpenTok Media Router (les sessions dont le mode multimédia est défini sur « routed »).

Vous pouvez lancer l'enregistrement d'une session OpenTok à l'aide de la commande opentok.archives.create(session_id, options) méthode. Cela renverra un OpenTok::Archive par exemple. Le paramètre options est un Hash facultatif utilisé pour définir le has_audio, has_videoet name options. Notez que vous ne pouvez lancer une archive que sur une session à laquelle des clients sont connectés.

# 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

Réglage de la :output_mode à l'option :individual Ce paramètre fait en sorte que chaque flux de l'archive soit enregistré dans son propre fichier :

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

Les :output_mode => :composed Ce paramètre (par défaut) fait en sorte que tous les flux de l'archive soient enregistrés dans un seul fichier (composé).

Pour les archives composées, vous pouvez définir la résolution de l'archive : soit « 640x480 » (SD paysage, valeur par défaut), « 1280x720 » (HD paysage), « 1920x1080 » (FHD paysage), « 480x640 » (SD portrait), « 720x1280 » (HD portrait) ou « 1080x1920 » (FHD portrait). Le resolution Ce paramètre est facultatif et peut être inclus dans le hachage des options (deuxième argument) de la fonction opentok.archives.create() méthode.

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

archive = opentok.archives.create session_id, opts

Pour personnaliser la présentation initiale des archives composées, vous pouvez utiliser la fonction :layout option. Définissez cette option sur un hachage contenant deux clés : :type et :stylesheet. Valeurs valides pour :type sont « bestFit » (ajustement optimal), « 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 « custom », définissez le :stylesheet clé de la feuille de style (CSS). (Pour les autres types de mise en page, ne définissez pas la :stylesheet clé.)

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 vous ne spécifiez pas de type de structure initiale, l'archive utilise le type de structure le plus adapté. Pour plus d'informations, consultez Personnalisation de la mise en page vidéo pour les composées.

Vous pouvez arrêter l'enregistrement d'une archive commencée à l'aide de la touche opentok.archives.stop_by_id(archive_id) méthode. Vous pouvez également le faire à l'aide de la Archive#stop() méthode.

# 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

Pour obtenir un OpenTok::Archive (et toutes les informations la concernant) à partir d'une instance de archive_id, utilisez le opentok.archives.find(archive_id) méthode.

archive = opentok.archives.find archive_id

Pour supprimer une archive, vous pouvez appeler le opentok.archives.delete_by_id(archive_id) méthode ou la delete méthode d'un OpenTok::Archive instance.

# 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

Vous pouvez également obtenir une liste de toutes les archives que vous avez créées (jusqu'à 1000) avec votre clé API. Cette opération s'effectue à l'aide de la à l'aide de la fonction opentok.archives.all(options) méthode. Le paramètre options est un hash facultatif utilisé pour spécifier un :offset et :count pour vous aider à parcourir les résultats par pages. Cela renverra une instance de la 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

Notez que vous pouvez également créer une session automatiquement archivée, en passant le paramètre :always en tant que :archive_mode de la propriété options paramètre transmis à la OpenTok#create_session() méthode (voir « Création de sessions », ci-dessus).

Vous pouvez régler la mise en page d'une archive :

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

Le hachage opts comporte deux entrées :

  • Les type Il s'agit du type de mise en page 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 propriété. (Pour les autres types de mise en page, ne définissez pas cette propriété de feuille de style.)

Voir Personnalisation de la présentation vidéo pour les archives composées pour plus d'informations.

Vous pouvez définir la classe de mise en page initiale pour les flux d'un client en configurant l'option de mise en page lors de la création du jeton pour ce client, à l'aide de la opentok.generate_token méthode. Vous pouvez également modifier les classes de mise en page d'un flux comme suit :

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)

Pour plus d'informations sur la configuration des classes de mise en page des flux, consultez la Modification des classes de mise en page des archives composées pour un flux OpenTok ».

N'oubliez pas que le streams.layout Cette méthode s'applique uniquement aux flux d'archivage et de diffusion.

Pour plus d'informations sur l'archivage, consultez le Archivage OpenTok guide du développeur.

Signalisation

Vous pouvez envoyer un signal à l'aide du opentok.signals.send(session_id, connection_id, opts) méthode. Si connection_id est nul ou une chaîne vide, le signal est alors envoyé à toutes les connexions valides de la session.

Un exemple de opts Le champ peut se présenter comme suit :

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

La longueur maximale du type La chaîne comporte 128 octets et ne doit contenir que des lettres (A-Z et a-z), des Numbers (0-9), les caractères « - », « _ » et « ~ ».

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

Les connection_id et opts Ces paramètres sont tous facultatifs par défaut. Vous pouvez donc également utiliser opentok.signals.send(session_id)

Pour plus d'informations sur la signalisation, consultez le Signalisation OpenTok guide de programmation.

Radiodiffusion

Vous pouvez diffuser vos flux vers des serveurs HLS ou RTMP.

Pour pouvoir lancer correctement la diffusion d'une session, au moins un client de publication doit être connecté à cette session.

La diffusion en direct peut cibler un point de terminaison HLS et jusqu'à cinq serveurs RTMP simultanément pour une même session.

Vous ne pouvez lancer la diffusion en direct que pour les sessions utilisant OpenTok Media Router (avec le mode multimédia défini sur « routed »). Vous ne pouvez pas utiliser la diffusion en direct avec les sessions dont le mode multimédia est défini sur « relayed ».

Pour créer une diffusion exclusivement au format 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)

L'objet Broadcast renvoyé contient des informations sur la diffusion, telles que id, sessionId, projectId, createdAt, updatedAt, resolution, status, ainsi qu'un hachage de broadcastUrls. Les broadcastUrls se composent d'une URL HLS et d'un tableau d'objets RTMP. Les objets RTMP ressemblent à la rtmp valeur dans opts dans l'exemple ci-dessus.

Pour plus d'informations sur la diffusion, consultez le Guide de diffusion OpenTok guide de programmation.

Pour obtenir des informations sur un flux de diffusion

my_broadcast = opentok.broadcasts.find broadcast_id

L'objet Broadcast renvoyé comporte des propriétés décrivant la diffusion, telles que id, sessionId, projectId, createdAt, updatedAt, resolution, status, ainsi qu'un objet Hash contenant les broadcastUrls. Les broadcastUrls sont constituées d'une URL HLS et d'un tableau d'objets RTMP. Les objets RTMP ressemblent à la rtmp valeur dans opts dans l'exemple ci-dessus.

Pour interrompre une diffusion :

 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"

Pour modifier dynamiquement la mise en page d'une émission

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

Le hachage ci-dessus comporte deux entrées.

  • Les type Il s'agit du type de mise en page 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 propriété. (Pour les autres types de mise en page, ne définissez pas cette propriété de feuille de style.)

Se référer à Personnalisation de la mise en page vidéo pour les composées pour plus d'informations.

Vous pouvez également modifier dynamiquement la mise en page d'un flux individuel. Reportez-vous à Utilisation des flux.

Déconnexion forcée

Vous pouvez forcer un client à se déconnecter d'une session en utilisant la commande opentok.connections.forceDisconnect(session_id, connection_id) méthode.

Forcer les clients d'une session à couper le son publié

Vous pouvez forcer l'éditeur d'un flux spécifique à cesser de publier de l'audio à l'aide de la commande opentok.streams.force_mute(session_id, stream_id) méthode.

Vous pouvez forcer l'éditeur de tous les flux d'une session (à l'exception d'une liste optionnelle de flux) à cesser de publier de l'audio à l'aide de la commande opentok.streams.force_mute_all(session_id, opts) méthode. Vous pouvez ensuite désactiver le mode « muet » de la session en appelant la méthode opentok.streams.disable_force_mute(session_id) méthode.

Pour plus d'informations, consultez Désactiver l'audio des flux dans une session.

Lancer un appel SIP

Vous pouvez lancer un appel SIP à l'aide de la opentok.sip.dial(session_id, token, sip_uri, opts) méthode. Cela nécessite une URL SIP. Vous devrez souvent transmettre des options permettant de vous authentifier auprès du fournisseur SIP et de spécifier l'établissement d'une session chiffrée.

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)

Pour plus d'informations sur l'interconnexion SIP, consultez le Interconnexion SIP OpenTok guide du développeur.

Travailler avec des compositeurs expérimentés

Vous pouvez lancer un Compositeur d'expérience en appelant le opentok.renders.start(session_id, options) méthode.

Vous pouvez arrêter un Experience Composer en appelant la fonction opentok.renders.stop(render_id, options) méthode.

Pour obtenir des informations sur Experience Composers, vous pouvez appeler le opentok.renders.find(render_id) et opentok.renders.list(options) des méthodes.

Utilisation d'Audio Connector

Vous pouvez lancer un Connecteur audio WebSocket en appelant la fonction opentok.websocket.connect() méthode.

Exigences

Vous avez besoin d'une clé API OpenTok et d'un secret API, que vous pouvez obtenir en vous connectant à votre Compte Video API de Vonage.

Le SDK OpenTok pour Ruby nécessite Ruby 2.1.0 ou une version ultérieure.

Notes de mise à jour

Voir le Communiqués page pour plus de détails sur chaque sortie.

Modifications importantes depuis la version 2.2.0

Nouveautés de la version 4.0.0 :

Le SDK prend désormais en charge Ruby v2.7 et nécessite désormais Ruby v2.1.0 ou une version ultérieure. Pour Ruby v2.0.0, veuillez continuer à utiliser le SDK OpenTok pour Ruby v3.0.0. Pour Ruby v1.9.3, veuillez continuer à utiliser le SDK OpenTok pour Ruby v2.5.0.

Nouveautés de la version 3.0.0 :

Le SDK nécessite désormais Ruby v2.0.0 ou une version ultérieure. Pour Ruby v1.9.3, veuillez continuer à utiliser le SDK OpenTok pour Ruby v2.5.0.

Modifications apportées à la version 2.2.2 :

Le paramètre par défaut pour le create_session() La méthode consiste à créer une session avec le mode multimédia défini sur « relayed ». Dans les versions précédentes du SDK, le paramètre par défaut consistait à utiliser le routeur multimédia OpenTok (mode multimédia défini sur « routed »). Dans une session en mode « relayed », les clients tentent d’échanger des flux directement entre eux (peer-to-peer) ; si les clients ne parviennent pas à se connecter en raison de restrictions de pare-feu, la session utilise le serveur TURN d’OpenTok pour relayer les flux audio et vidéo.

Nouveautés de la version 2.2.0 :

Cette version du SDK permet de travailler avec les archives OpenTok.

Notez également que le options du paramètre OpenTok.create_session() La méthode dispose d'un media_mode propriété au lieu d'un p2p propriété.