opentok 3.0.3 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 679a364a592829ee29acad18146e680f82d2a3de
-  data.tar.gz: 1d822425e30d6aa05e41768348fd9863b85677a4
+SHA256:
+  metadata.gz: 55309730e5aa9927756e9003fb5745c497e3956e5fab4810a280cfcab77614fa
+  data.tar.gz: ed3f6dcf6577b28f762503c7d271a485d03cdf27862a358a809951d09f9747b1
 SHA512:
-  metadata.gz: 0e0fdf3a74c811f22c535c1829eb9109ce7f8e2c45ab711796ee97a5891658aa2ab3d5625f9ddf953ddcbb27241ddb339261fec7d5321145ed012469cc896a1f
-  data.tar.gz: '0741182e612a82221688abda4226a5138e1051a47ad5d0f8a3e59005461935a2af711ba338721d37d2a42954e4113f43733ec2cbfca0c0a0ee77d83222701319'
+  metadata.gz: cfecdaf4cd7eeef31be4e6fb9e2b146007c1c9305051483400d4764508066dc62f45cd74a31a4c604b50cfb79aac48310821e7bd88956513a83bdaf07a107f89
+  data.tar.gz: ab5b745259d82e5c79b8ad25c794e0dafe66eb3d5205909a4659bafcfa696a5160949c12841de5b87b444635e8d70517158ee73627976a33c9188d90eae37c4f

data/.github/workflows/metrics.yml

@@ -0,0 +1,17 @@
+name: Aggregit
+
+on:
+  schedule:
+    - cron: "0 0 * * *"
+
+jobs:
+  recordMetrics:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: michaeljolley/aggregit@v1
+      with:
+        githubToken: ${{ secrets.GITHUB_TOKEN }}
+        project_id: ${{ secrets.project_id }}
+        private_key: ${{ secrets.private_key }}
+        client_email: ${{ secrets.client_email }}
+        firebaseDbUrl: ${{ secrets.firebaseDbUrl }}

data/.travis.yml

@@ -5,11 +5,13 @@ language: ruby
 cache: bundler
 before_install: gem update bundler
 rvm:
-- 2.0
 - 2.1
 - 2.2
 - 2.3
 - 2.4
+- 2.5
+- 2.6
+- 2.7
 notifications:
   slack:
     secure: agVll2R9PTPvJMcUgbvOh9eGt60zGDc8kPUwEsiQr828rCgXh/ZxD5irYDyKQg3ZsS8+f3MjFCwzU7uQALkia2pDrie9d8g8m1dt4Q5U7Qm6QecshvE0U9JwbB5Ngxaftbqyf0XEFrE7CKs7RI1BzFRpe8m+fdZgfwccX8Gb7pc=

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+devrel@vonage.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

data/README.md

@@ -1,12 +1,18 @@
 # OpenTok Ruby SDK
 
-[![Build Status](https://travis-ci.org/opentok/OpenTok-Ruby-SDK.png)](https://travis-ci.org/opentok/OpenTok-Ruby-SDK)
+[![Build Status](https://travis-ci.org/opentok/OpenTok-Ruby-SDK.png)](https://travis-ci.org/opentok/OpenTok-Ruby-SDK) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
+
+<img src="https://assets.tokbox.com/img/vonage/Vonage_VideoAPI_black.svg" height="48px" alt="Tokbox is now known as Vonage" />
 
 The OpenTok Ruby SDK lets you generate
-[sessions](http://www.tokbox.com/opentok/tutorials/create-session/) and
-[tokens](http://www.tokbox.com/opentok/tutorials/create-token/) for
-[OpenTok](http://www.tokbox.com/) applications, and
-[archive](https://tokbox.com/opentok/tutorials/archiving) OpenTok sessions.
+[sessions](https://tokbox.com/developer/guides/create-session/) and
+[tokens](https://tokbox.com/developer/guides/create-token/) for
+[OpenTok](http://www.tokbox.com/) applications. It also includes methods for
+working with OpenTok [archives](https://tokbox.com/developer/guides/archiving),
+working with OpenTok [live streaming
+broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/),
+working with OpenTok [SIP interconnect](https://tokbox.com/developer/guides/sip),
+and [disconnecting clients from sessions](https://tokbox.com/developer/guides/moderation/rest/).
 
 # Installation
 
@@ -17,7 +23,7 @@ Bundler helps manage dependencies for Ruby projects. Find more info here:
 Add this gem to your `Gemfile`:
 
 ```ruby
-gem "opentok", "~> 3.0.3"
+gem "opentok", "~> 4.0.0"
 ```
 
 Allow bundler to install the change.
@@ -45,13 +51,35 @@ require "opentok"
 opentok = OpenTok::OpenTok.new api_key, api_secret
 ```
 
+### Initialization Options
+
+You can specify a custom timeout value for HTTP requests when initializing a new `OpenTok::OpenTok`
+object:
+
+```ruby
+require "opentok"
+
+opentok = OpenTok::OpenTok.new api_key, api_secret, :timeout_length => 10
+```
+
+The value for `:timeout_length` is an integer representing the number of seconds to wait for an HTTP
+request to complete. The default is set to 2 seconds.
+
 ## Creating Sessions
 
-To create an OpenTok Session, use the `OpenTok#create_session(properties)` method. The
-`properties` parameter is an optional Hash used to specify whether you are creating a session that
-uses the OpenTok Media Server and specifying a location hint. The `session_id` method of the
-returned `OpenTok::Session` instance is useful to get a sessionId that can be saved to a persistent
-store (e.g. database).
+To create an OpenTok Session, use the `OpenTok#create_session(properties)` method.
+The `properties` parameter is an optional Hash used to specify the following:
+
+- Whether the session uses the [OpenTok Media
+  Router](https://tokbox.com/developer/guides/create-session/#media-mode),
+  which is required for some OpenTok features (such as archiving)
+
+- A location hint for the OpenTok server.
+
+- Whether the session is automatically archived.
+
+The `session_id` method of the returned `OpenTok::Session` instance is useful to
+get a sessionId that can be saved to a persistent store (such as a database).
 
 ```ruby
 # Create a session that will attempt to transmit streams directly between clients.
@@ -96,10 +124,38 @@ token = session.generate_token({
 });
 ```
 
+## Working with Streams
+
+Use this method to get information for an OpenTok stream or for all streams in a session.
+For example, you can call this method to get information about layout classes used by an
+OpenTok stream.
+
+To get information of a specific stream in a session, call
+`opentok.streams.find(session_id, stream_id)`. The return object is a `Stream` object and
+you can access various stream properties as shown in the following example (using RSpec notations):
+
+```ruby
+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"
+```
+
+To get information on all streams in a session, call `opentok.streams.all(session_id)`.
+The return value is a `StreamList` object:
+
+```ruby
+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"
+```
+
 ## Working with Archives
 
-You can start the recording of an OpenTok Session using the `opentok.archives.create(session_id,
-options)` method. This will return an `OpenTok::Archive` instance. The parameter `options` is an
+You can only archive sessions that use the OpenTok Media Router
+(sessions with the media mode set to routed).
+
+You can start the recording of an OpenTok Session using the `opentok.archives.create(session_id, options)` method. This will return an `OpenTok::Archive` instance. The parameter `options` is an
 optional Hash used to set the `has_audio`, `has_video`, and `name` options. Note that you can
 only start an Archive on a Session that has clients connected.
 
@@ -127,6 +183,43 @@ archive = opentok.archives.create session_id :output_mode => :individual
 The `:output_mode => :composed` setting (the default) causes all streams in the archive to be
 recorded to a single (composed) file.
 
+For composed archives you can set the resolution of the archive, either "640x480" (SD, the default)
+or "1280x720" (HD). The `resolution` parameter is optional and could be included in the options
+hash (second argument) of the `opentok.archives.create()` method.
+
+```ruby
+opts = {
+    :output_mode => :composed,
+    :resolution => "1280x720"
+}
+
+archive = opentok.archives.create session_id, opts
+```
+
+To customize the initial layout of composed archives, you can use the `:layout` option.
+Set this to a hash containing two keys: `:type` and `:stylesheet`. Valid values for
+`:type` are "bestFit" (best fit), "custom" (custom), "horizontalPresentation"
+(horizontal presentation), "pip" (picture-in-picture), and "verticalPresentation"
+(vertical presentation)). If you specify a "custom" layout type, set the `:stylesheet`
+key to the stylesheet (CSS). (For other layout types, do not set the `:stylesheet` key.)
+
+```ruby
+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
+```
+
+If you do not specify an initial layout type, the archive uses the best fit
+layout type. For more information, see [Customizing the video layout for composed
+archives](https://tokbox.com/developer/guides/archiving/layout-control.html).
+
 You can stop the recording of a started Archive using the `opentok.archives.stop_by_id(archive_id)`
 method. You can also do this using the `Archive#stop()` method.
 
@@ -175,14 +268,197 @@ Note that you can also create an automatically archived session, by passing in `
 as the `:archive_mode` property of the `options` parameter passed into the
 `OpenTok#create_session()` method (see "Creating Sessions," above).
 
+You can set the [layout](https://tokbox.com/developer/rest/#change_composed_archive_layout) of an archive:
+
+```ruby
+opts = { :type => "verticalPresentation" }
+opentok.archives.layout(archive_id, opts)
+```
+
+The hash `opts` has two entries:
+
+- The `type` is the layout type for the archive. Valid values are "bestFit" (best fit)
+  "custom" (custom), "horizontalPresentation" (horizontal presentation),
+  "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)).
+
+- If you specify a "custom" layout type, set the `stylesheet` property.
+  (For other layout types, do not set the stylesheet property.)
+
+See [Customizing the video layout for composed archives](https://tokbox.com/developer/guides/archiving/layout-control.html)
+for more details.
+
+You can set the initial layout class for a client's streams by setting the layout option when you
+create the token for the client, using the `opentok.generate_token` method. And you can also change
+the layout classes of a stream as follows:
+
+```ruby
+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)
+```
+
+For more information on setting stream layout classes, see the
+[Changing the composed archive layout classes for an OpenTok
+stream](https://tokbox.com/developer/rest/#change-stream-layout-classes-composed).
+
+Please keep in mind that the `streams.layout` method applies to archive and broadcast streams only.
+
 For more information on archiving, see the
 [OpenTok archiving](https://tokbox.com/opentok/tutorials/archiving/) programming guide.
 
+## Signaling
 
-## Initiating a SIP call
+You can send a signal using the `opentok.signals.send(session_id, connection_id, opts)` method.  
+If `connection_id` is nil or an empty string, then the signal is send to all valid connections in
+the session.
 
-You can initiate a SIP call using the `opentok.sip.dial(session_id, token, sip_uri, opts)` method.  This requires a SIP url. You will often need to pass options for authenticating to the SIP provider and specifying encrypted session establishment.
+An example of `opts` field can be as follows:
 
+```ruby
+opts = { :type => "chat",
+         :data => "Hello"
+}
+```
+
+The maximum length of the `type` string is 128 bytes, and it must contain only letters
+(A-Z and a-z), numbers (0-9), '-', '\_', and '~'.
+
+The `data` string must not exceed the maximum size (8 kB).
+
+The `connection_id` and `opts` parameter are jointly optional by default. Hence you can also
+use `opentok.signals.send(session_id)`
+
+For more information on signaling, see the
+[OpenTok Signaling](https://tokbox.com/developer/guides/signaling/js/) programming guide.
+
+## Broadcasting
+
+You can broadcast your streams to a HLS or RTMP servers.
+
+To successfully start broadcasting a session, at least one publishing client must be connected to
+the session.
+
+You can only have one active live streaming broadcast at a time for a session (however, having more
+than one would not be useful).
+
+The live streaming broadcast can target one HLS endpoint and up to five RTMP servers simultaneously
+for a session.
+
+You can only start live streaming for sessions that use the OpenTok Media Router (with the
+media mode set to routed). You cannot use live streaming with sessions that have the media mode set
+to relayed.
+
+To create a HLS only broadcast:
+
+```ruby
+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)
+```
+
+The returned Broadcast object has information about the broadcast, like id, sessionId , projectId,
+createdAt, updatedAt, resolution, status, and a Hash of broadcastUrls. The broadcastUrls
+consists of an HLS URL and an array of RTMP objects. The RTMP objects resembles the `rtmp` value
+in `opts` in the example above.
+
+For more information on broadcast, see the
+[OpenTok Broadcast guide](https://tokbox.com/developer/rest/#start_broadcast) programming guide.
+
+To get information about a broadcast stream
+
+```ruby
+my_broadcast = opentok.broadcasts.find broadcast_id
+```
+
+The Broadcast object returned has properties describing the broadcast, like id, sessionId,
+projectId, createdAt, updatedAt, resolution, status, and a Hash of broadcastUrls. The broadcastUrls
+consists of an HLS URL and an array of RTMP objects. The RTMP objects resembles the `rtmp` value
+in `opts` in the example above.
+
+To stop a broadcast:
+
+```ruby
+ 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"
+```
+
+To change the layout of a broadcast dynamically
+
+```ruby
+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
+```
+
+The hash above has two entries.
+
+- The `type` is the layout type for the archive. Valid values are "bestFit" (best fit),
+  "custom" (custom), "horizontalPresentation" (horizontal presentation),
+  "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation).
+
+- If you specify a "custom" layout type, set the `stylesheet` property. (For other layout types,
+  do not set the stylesheet property.)
+
+Refer to [Customizing the video layout for composed
+archives](https://tokbox.com/developer/guides/archiving/layout-control.html)
+for more details.
+
+You can also change the layout of an individual stream dynamically. Refer to
+[working with Streams](#working-with-streams).
+
+## Force disconnect
+
+You can cause a client to be forced to disconnect from a session by using the
+`opentok.connections.forceDisconnect(session_id, connection_id)` method.
+
+## Initiating a SIP call
+
+You can initiate a SIP call using the `opentok.sip.dial(session_id, token, sip_uri, opts)` method.
+This requires a SIP URL. You will often need to pass options for authenticating to the SIP provider
+and specifying encrypted session establishment.
 
 ```ruby
 opts = { "auth" => { "username" => sip_username,
@@ -193,16 +469,16 @@ response = opentok.sip.dial(session_id, token, "sip:+15128675309@acme.pstn.examp
 ```
 
 For more information on SIP Interconnect, see the
-[OpenTok SIP Interconnect](https://tokbox.com/developer/guides/sip/) programming guide.
-
+[OpenTok SIP Interconnect](https://tokbox.com/developer/guides/sip/) developer guide.
 
 # Samples
 
-There are two sample applications included in this repository. To get going as fast as possible, clone the whole
-repository and follow the Walkthroughs:
+There are three sample applications included in this repository. To get going as fast as possible, clone the whole
+repository and read the README in each of the sample directories:
 
-*  [HelloWorld](sample/HelloWorld/README.md)
-*  [Archiving](sample/Archiving/README.md)
+- [HelloWorld](sample/HelloWorld/README.md)
+- [Archiving](sample/Archiving/README.md)
+- [Broadcast](sample/Broadcast/README.md)
 
 # Documentation
 
@@ -210,9 +486,10 @@ Reference documentation is available at
 
 # Requirements
 
-You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
+You need an OpenTok API key and API secret, which you can obtain by logging into your
+[TokBox account](https://tokbox.com/account).
 
-The OpenTok Ruby SDK requires Ruby 1.9.3 or greater.
+The OpenTok Ruby SDK requires Ruby 2.1.0 or greater.
 
 # Release Notes
 
@@ -221,6 +498,12 @@ about each release.
 
 ## Important changes since v2.2.0
 
+**Changes in v4.0.0:**
+
+The SDK adds support for Ruby v2.7 and now requires Ruby v2.1.0 or higher.
+For Ruby v2.0.0 please continue to use the OpenTok Ruby SDK v3.0.0.
+For Ruby v1.9.3 please continue to use the OpenTok Ruby SDK v2.5.0.
+
 **Changes in v3.0.0:**
 
 The SDK now now requires Ruby v2.0.0 or higher. For Ruby v1.9.3 please continue to use the
@@ -245,15 +528,16 @@ See the reference documentation
 <http://www.tokbox.com/opentok/libraries/server/ruby/reference/index.html> and in the
 docs directory of the SDK.
 
-
 # Development and Contributing
 
 Interested in contributing? We :heart: pull requests! See the [Development](DEVELOPING.md) and
 [Contribution](CONTRIBUTING.md) guidelines.
 
-# Support
+## Getting Help
 
-See <https://support.tokbox.com> for all our support options.
+We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either:
 
-Find a bug? File it on the [Issues](https://github.com/opentok/opentok-ruby-sdk/issues) page. Hint:
-test cases are really helpful!
+- Open an issue on this repository
+- See <https://support.tokbox.com/> for support options
+- Tweet at us! We're [@VonageDev on Twitter](https://twitter.com/VonageDev)
+- Or [join the Vonage Developer Community Slack](https://developer.nexmo.com/community/slack)