Vonage Video API Ruby SDK

Das OpenTok Ruby SDK bietet Methoden für:

Erzeugen von Sitzungen und Token für OpenTok Applications
Arbeiten mit OpenTok Archiv
Arbeiten mit OpenTok Live-Streaming-Übertragungen
Arbeiten mit OpenTok SIP-Zusammenschaltung
Senden von Signalen an Clients, die mit einer Sitzung verbunden sind
Trennen von Kunden von Sitzungen
Erzwingen, dass Clients in einer Sitzung die Verbindung unterbrechen oder das veröffentlichte Audio stummschalten
Arbeiten mit OpenTok Erfahrene Komponisten
Arbeiten mit OpenTok Audio-Anschluss

Einrichtung

Bundler (empfohlen):

Bundler hilft bei der Verwaltung von Abhängigkeiten für Ruby-Projekte. Mehr Informationen finden Sie hier: http://bundler.io

Füge dieses Juwel zu deiner Gemfile:

gem "opentok", "~> 4.0.0"

Lassen Sie den Bundler die Änderung installieren.

$ bundle install

RubyGems:

$ gem install opentok

Verwendung

Initialisierung

Lade das Gem am Anfang einer beliebigen Datei, in der es verwendet werden soll. Initialisiere anschließend ein OpenTok::OpenTok Objekt mit Ihrem OpenTok-API-Schlüssel und Ihrem API-Geheimnis.

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret

Initialisierungsoptionen

Benutzerdefiniertes Timeout

Bei der Initialisierung eines neuen Objekts können Sie einen benutzerdefinierten Timeout-Wert für HTTP-Anfragen festlegen. OpenTok::OpenTok Objekt:

require "opentok"

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

Der Wert für :timeout_length ist eine Ganzzahl, die die Anzahl der Sekunden angibt, die auf den Abschluss einer HTTP-Anfrage gewartet werden soll. Der Standardwert ist auf 2 Sekunden festgelegt.

UA-Nachtrag

Sie können außerdem eine benutzerdefinierte Zeichenfolge an das User-Agent Header-Wert für HTTP-Anfragen bei der Initialisierung eines neuen OpenTok::OpenTok Objekt:

require "opentok"

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

Das Obige würde Folgendes erzeugen: User-Agent Eine Überschrift, die in etwa so aussieht:

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

Sitzungen erstellen

Um eine OpenTok-Sitzung zu erstellen, verwenden Sie die OpenTok#create_session(properties) Methode. Die Website properties Der Parameter ist ein optionales Hash, mit dem Folgendes festgelegt wird:

Ob die Sitzung die OpenTok Media Router, was für einige OpenTok-Funktionen (wie beispielsweise die Archivierung) erforderlich ist
Ein Hinweis auf den Standort des OpenTok-Servers.
Ob die Sitzung automatisch archiviert wird.

Die session_id Methode des zurückgegebenen OpenTok::Session Diese Instanz ist nützlich, um eine Session-ID abzurufen, die in einem persistenten Speicher (z. B. einer Datenbank) gespeichert werden kann.

# 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

Token generieren

Sobald eine Sitzung erstellt ist, können Sie mit der Generierung von Token beginnen, die die Clients bei der Verbindung mit der Sitzung verwenden können. Sie können ein Token entweder durch Aufruf der Funktion opentok.generate_token(session_id, options) Methode, oder durch Aufruf der Session#generate_token(options) Methode auf der Instanz nach deren Erstellung. Die options Der Parameter ist ein optionaler Hash, mit dem die Rolle, die Gültigkeitsdauer und die Verbindungsdaten des Tokens festgelegt werden. Zur Steuerung des Layouts in Archiven und Übertragungen kann zudem die anfängliche Liste der Layoutklassen für Streams festgelegt werden, die über Verbindungen unter Verwendung dieses Tokens veröffentlicht werden.

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

Arbeiten mit Strömen

Verwenden Sie diese Methode, um Informationen zu einem OpenTok-Stream oder zu allen Streams einer Sitzung abzurufen. Sie können diese Methode beispielsweise aufrufen, um Informationen zu den Layout-Klassen abzurufen, die von einem OpenTok-Stream verwendet werden.

Um Informationen zu einem bestimmten Stream in einer Sitzung abzurufen, rufen Sie folgenden Befehl auf: opentok.streams.find(session_id, stream_id). Das Rückgabeobjekt ist ein Stream Objekt, und Sie können auf verschiedene Stream-Eigenschaften zugreifen, wie im folgenden Beispiel gezeigt (unter Verwendung von RSpec-Notationen):

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"

Um Informationen zu allen Streams einer Sitzung abzurufen, rufen Sie folgenden Befehl auf: opentok.streams.all(session_id). Der Rückgabewert ist ein StreamList Objekt:

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"

Arbeiten mit Archiven

Sie können nur Sitzungen archivieren, die den OpenTok Media Router verwenden (Sitzungen, bei denen der Medienmodus auf „routed“ eingestellt ist).

Sie können die Aufzeichnung einer OpenTok-Sitzung über die opentok.archives.create(session_id, options) Methode. Diese gibt ein OpenTok::Archive Beispiel. Der Parameter options ist ein optionaler Hash, der zum Festlegen des has_audio, has_videound name Optionen. Beachten Sie, dass Sie ein Archiv nur in einer Sitzung starten können, mit der Clients verbunden sind.

# 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

Einstellung der :output_mode Option zu :individual Durch diese Einstellung wird jeder Stream im Archiv in einer eigenen Datei aufgezeichnet:

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

Die :output_mode => :composed Bei dieser Einstellung (Standard) werden alle Streams im Archiv in einer einzigen (zusammengesetzten) Datei aufgezeichnet.

Bei zusammengesetzten Archiven können Sie die Auflösung des Archivs festlegen, entweder „640x480“ (SD im Querformat, Standardeinstellung), „1280x720“ (HD im Querformat), „1920x1080“ (FHD im Querformat), „480x640“ (SD im Hochformat), „720x1280“ (HD im Hochformat) oder „1080x1920“ (FHD im Hochformat). Die resolution Der Parameter ist optional und könnte in den Optionen des Hash (zweites Argument) der opentok.archives.create() Methode.

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

archive = opentok.archives.create session_id, opts

Um das anfängliche Layout der zusammengestellten Archive anzupassen, können Sie die :layout Option. Setzen Sie diese Option auf ein Hash-Objekt, das zwei Schlüssel enthält: :type und :stylesheet. Gültige Werte für :type sind „bestFit“ (beste Anpassung), „custom“ (benutzerdefiniert), „horizontalPresentation“ (horizontale Darstellung), „pip“ (Bild-in-Bild) und „verticalPresentation“ (vertikale Darstellung). Wenn Sie den Layouttyp „custom“ angeben, setzen Sie die :stylesheet Schlüssel für das Stylesheet (CSS). (Bei anderen Layouttypen darf der :stylesheet Schlüssel).

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

Wenn Sie keinen anfänglichen Layouttyp angeben, verwendet das Archiv den am besten geeigneten Layouttyp. Weitere Informationen finden Sie unter Anpassen des Videolayouts für zusammengesetzte Archive.

Sie können die Aufzeichnung eines gestarteten Archivs mit der Taste opentok.archives.stop_by_id(archive_id) Methode. Sie können dies auch mithilfe der Archive#stop() Methode.

# 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

Um eine OpenTok::Archive Instanz (und alle Informationen darüber) aus einer archive_id, verwende das opentok.archives.find(archive_id) Methode.

archive = opentok.archives.find archive_id

Um ein Archiv zu löschen, können Sie die Funktion opentok.archives.delete_by_id(archive_id) Methode oder die delete Methode eines OpenTok::Archive Instanz.

# 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

Sie können auch eine Liste aller Archive abrufen, die Sie mit Ihrem API-Schlüssel erstellt haben (bis zu 1000). Dies geschieht mit der Funktion opentok.archives.all(options) Methode. Der Parameter options ist ein optionales Hash, das zur Angabe eines :offset und :count damit Sie die Ergebnisse paginieren können. Dadurch wird eine Instanz der OpenTok::ArchiveList Klasse.

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

Beachten Sie, dass Sie auch eine automatisch archivierte Sitzung erstellen können, indem Sie in :always als die :archive_mode Eigenschaft der options an die OpenTok#create_session() Methode (siehe „Sitzungen erstellen“ weiter oben).

Sie können die Layout aus einem Archiv:

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

Der Hash opts enthält zwei Einträge:

Die type ist der Layouttyp für das Archiv. Gültige Werte sind „bestFit“ (beste Anpassung) „custom“ (benutzerdefiniert), „horizontalPresentation“ (horizontale Darstellung), „pip“ (Bild-in-Bild) und „verticalPresentation“ (vertikale Darstellung).
Wenn Sie einen "benutzerdefinierten" Layouttyp angeben, setzen Sie die stylesheet Eigenschaft. (Bei anderen Layouttypen darf die Stylesheet-Eigenschaft nicht festgelegt werden.)

Siehe Anpassen des Videolayouts für zusammengestellte Archive Weitere Informationen finden Sie hier.

Sie können die anfängliche Layout-Klasse für die Streams eines Clients festlegen, indem Sie die Layout-Option beim Erstellen des Tokens für den Client mithilfe der opentok.generate_token Methode. Außerdem kannst du die Layout-Klassen eines Streams wie folgt ändern:

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)

Weitere Informationen zum Festlegen von Stream-Layout-Klassen finden Sie in der Ändern der Layout-Klassen für zusammengesetzte Archive bei einem OpenTok- Stream.

Bitte beachten Sie, dass die streams.layout Diese Methode gilt ausschließlich für Archiv- und Live-Streams.

Weitere Informationen zur Archivierung finden Sie unter OpenTok-Archivierung Leitfaden für Entwickler.

Signalisierung

Sie können ein Signal senden, indem Sie die opentok.signals.send(session_id, connection_id, opts) Methode. Wenn connection_id ist „nil“ oder eine leere Zeichenkette, wird das Signal an alle gültigen Verbindungen in der Sitzung gesendet.

Ein Beispiel für opts Das Feld kann wie folgt aussehen:

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

Die maximale Länge der type Die Zeichenkette ist 128 Byte lang und darf nur Buchstaben (A–Z und a–z), Numbers (0–9), „-“, „_“ und „~“ enthalten.

Die data String darf die maximale Größe (8 kB) nicht überschreiten.

Die connection_id und opts Diese Parameter sind standardmäßig gemeinsam optional. Daher können Sie auch folgendes verwenden: opentok.signals.send(session_id)

Weitere Informationen zur Signalübertragung finden Sie unter OpenTok-Signalisierung Programmieranleitung.

Rundfunk und Fernsehen

Sie können Ihre Streams an HLS- oder RTMP-Server übertragen.

Um die Übertragung einer Sitzung erfolgreich zu starten, muss mindestens ein Publishing-Client mit der Sitzung verbunden sein.

Die Live-Streaming-Übertragung kann pro Sitzung auf einen HLS-Endpunkt und bis zu fünf RTMP-Server gleichzeitig ausgerichtet sein.

Sie können Live-Streaming nur für Sitzungen starten, die den OpenTok Media Router verwenden (wobei der Medienmodus auf „routed“ eingestellt ist). Bei Sitzungen, bei denen der Medienmodus auf „relayed“ eingestellt ist, können Sie kein Live-Streaming nutzen.

So erstellen Sie eine reine HLS-Übertragung:

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)

Das zurückgegebene Broadcast-Objekt enthält Informationen zur Übertragung, wie z. B. id, sessionId, projectId, createdAt, updatedAt, resolution, status sowie ein Hash von broadcastUrls. Die broadcastUrls bestehen aus einer HLS-URL und einem Array von RTMP-Objekten. Die RTMP-Objekte ähneln den rtmp Wert in opts im obigen Beispiel.

Weitere Informationen zum Thema „Broadcast“ finden Sie unter OpenTok-Leitfaden für Übertragungen Programmieranleitung.

Um Informationen zu einem Broadcast-Stream abzurufen

my_broadcast = opentok.broadcasts.find broadcast_id

Das zurückgegebene „Broadcast“-Objekt verfügt über Eigenschaften, die die Übertragung beschreiben, wie z. B. „id“, „sessionId“, „projectId“, „createdAt“, „updatedAt“, „resolution“, „status“ und ein Hash von „broadcastUrls“. Die „broadcastUrls“ bestehen aus einer HLS-URL und einem Array von RTMP-Objekten. Die RTMP-Objekte ähneln dem rtmp Wert in opts im obigen Beispiel.

So beenden Sie eine Übertragung:

 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"

Um das Layout einer Sendung dynamisch zu ändern

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

Der obige Hash enthält zwei Einträge.

Die type ist der Layouttyp für das Archiv. Gültige Werte sind „bestFit“ (optimale Anpassung), „custom“ (benutzerdefiniert), „horizontalPresentation“ (horizontale Darstellung), „pip“ (Bild-in-Bild) und „verticalPresentation“ (vertikale Darstellung).
Wenn Sie einen "benutzerdefinierten" Layouttyp angeben, setzen Sie die stylesheet Eigenschaft. (Bei anderen Layout-Typen sollte die Stylesheet-Eigenschaft nicht festgelegt werden.)

Siehe Anpassen des Videolayouts für zusammengesetzte Archive Weitere Informationen finden Sie hier.

Sie können das Layout eines einzelnen Streams auch dynamisch ändern. Weitere Informationen finden Sie unter Arbeiten mit Streams.

Erzwungene Trennung

Sie können einen Client dazu zwingen, die Verbindung zu einer Sitzung zu trennen, indem Sie die opentok.connections.forceDisconnect(session_id, connection_id) Methode.

Erzwingen, dass Clients in einer Sitzung das veröffentlichte Audio stummschalten

Sie können den Herausgeber eines bestimmten Streams zwingen, die Veröffentlichung von Audio zu beenden, indem Sie die opentok.streams.force_mute(session_id, stream_id) Methode.

Sie können den Herausgeber aller Streams in einer Sitzung (mit Ausnahme einer optionalen Liste von Streams) zwingen die Veröffentlichung von Audio zu beenden, indem Sie die opentok.streams.force_mute_all(session_id, opts) Methode. Anschließend können Sie den Stummschaltungsstatus der Sitzung aufheben, indem Sie die opentok.streams.disable_force_mute(session_id) Methode.

Weitere Informationen finden Sie unter Stummschalten des Tons von Streams in einer Sitzung.

Einleiten eines SIP-Anrufs

Sie können einen SIP-Anruf über die opentok.sip.dial(session_id, token, sip_uri, opts) Methode. Hierfür ist eine SIP-URL erforderlich. Häufig müssen Sie Optionen zur Authentifizierung beim SIP-Anbieter sowie zur Festlegung eines verschlüsselten Verbindungsaufbaus übergeben.

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)

Weitere Informationen zu SIP Interconnect finden Sie im OpenTok SIP-Anbindung Leitfaden für Entwickler.

Die Zusammenarbeit mit erfahrenen Komponisten

Sie können ein Erlebnis-Komponist durch Aufruf der opentok.renders.start(session_id, options) Methode.

Sie können den Experience Composer anhalten, indem Sie die Funktion opentok.renders.stop(render_id, options) Methode.

Informationen zu Experience Composers erhalten Sie telefonisch unter der Nummer opentok.renders.find(render_id) und opentok.renders.list(options) Methoden.

Arbeiten mit Audio Connector

Sie können ein Audio-Anschluss WebSocket durch Aufruf der opentok.websocket.connect() Methode.

Anforderungen

Sie benötigen einen OpenTok-API-Schlüssel und ein API-Geheimnis, die Sie erhalten, indem Sie sich bei Ihrem Vonage Video API-Konto.

Für das OpenTok Ruby SDK ist Ruby 2.1.0 oder höher erforderlich.

Anmerkungen zur Veröffentlichung

Siehe die Veröffentlichungen Seite mit weiteren Informationen zu den einzelnen Veröffentlichungen.

Wichtige Änderungen seit Version 2.2.0

Änderungen in Version 4.0.0:

Das SDK bietet nun Unterstützung für Ruby v2.7 und erfordert Ruby v2.1.0 oder höher. Für Ruby v2.0.0 verwenden Sie bitte weiterhin das OpenTok Ruby SDK v3.0.0. Für Ruby v1.9.3 verwenden Sie bitte weiterhin das OpenTok Ruby SDK v2.5.0.

Änderungen in Version 3.0.0:

Das SDK erfordert nun Ruby v2.0.0 oder höher. Für Ruby v1.9.3 verwenden Sie bitte weiterhin das OpenTok Ruby SDK v2.5.0.

Änderungen in Version 2.2.2:

Die Standardeinstellung für die create_session() Die Vorgehensweise besteht darin, eine Sitzung zu erstellen, bei der der Medienmodus auf „relayed“ eingestellt ist. In früheren Versionen des SDK war die Standardeinstellung die Verwendung des OpenTok Media Routers (Medienmodus auf „routed“ eingestellt). In einer „relayed“-Sitzung versuchen die Clients, Streams direkt untereinander zu übertragen (Peer-to-Peer); können die Clients aufgrund von Firewall-Einschränkungen keine Verbindung herstellen, nutzt die Sitzung den OpenTok-TURN-Server zur Weiterleitung der Audio- und Videostreams.

Änderungen in Version 2.2.0:

Diese Version des SDK bietet Unterstützung für die Arbeit mit OpenTok-Archiven.

Beachten Sie außerdem, dass die options Parameter des OpenTok.create_session() Die Methode hat eine media_mode Eigenschaft anstelle einer p2p Eigentum.