Skip to content

Commit

Permalink
Merge pull request #177 from opentok/dev
Browse files Browse the repository at this point in the history 
Add force disconnect, signaling, resolution support, archive layouts, broadcasting, and stream info APIs
  • Loading branch information
Manik Sachdeva authored Oct 9, 2018
2 parents 7774d3f + a3aac34 commit dfa22dc
Show file tree
Hide file tree
Showing 36 changed files with 2,215 additions and 35 deletions.
263 changes: 249 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,14 @@
[![Build Status](https://travis-ci.org/opentok/OpenTok-Ruby-SDK.png)](https://travis-ci.org/opentok/OpenTok-Ruby-SDK)

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

Expand All @@ -17,7 +21,7 @@ Bundler helps manage dependencies for Ruby projects. Find more info here: <http:
Add this gem to your `Gemfile`:

```ruby
gem "opentok", "~> 3.0.3"
gem "opentok", "~> 3.1.0"
```

Allow bundler to install the change.
Expand Down Expand Up @@ -47,11 +51,19 @@ opentok = OpenTok::OpenTok.new api_key, api_secret

## 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.
Expand Down Expand Up @@ -96,8 +108,37 @@ 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 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
Expand Down Expand Up @@ -127,6 +168,19 @@ 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
```

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.

Expand Down Expand Up @@ -175,14 +229,194 @@ 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.

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.

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.
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,
Expand All @@ -193,7 +427,7 @@ response = opentok.sip.dial(session_id, token, "sip:[email protected]
```

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
Expand All @@ -210,7 +444,8 @@ Reference documentation is available at <http://www.tokbox.com//opentok/librarie

# 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.

Expand Down
Loading

0 comments on commit dfa22dc

Please sign in to comment.