Ruby Server SDK

The Vonage Ruby SDK lets you interact with the Vonage Video API by providing methods for:

• Creating Sessions
• Generating Client Tokens
• Working with Streams
• Working with Archives
• Working with Broadcasts
• Signaling
• Moderation
• Working with SIP

Installation

Bundler (recommended):

Bundler helps manage dependencies for Ruby projects. Find more info here: http://bundler.io

Add the gem to your project's Gemfile:

Allow bundler to install the gem in your project.

RubyGems:

Alternatively, you can install the Gem directly on your system via the command line using the RubyGems CLI gem install command.

Usage

Initializing

Load the gem at the top of any file where it will be used. Then initialize a Vonage::Client object using the private key and application ID associated with your Vonage Video application.

Note: the above example assumes that you have the values for your Vonage Application ID and the path to your private key saved as environment variables in an ENV hash with the keys VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY_PATH respectively.

Initialization Options

The Vonage client allows for some overrides of default configuration options when special needs arise, such as needing to point to a different datacenter.

This example uses the video_host: keyword argument to over-ride the default base URL for the Video API. This is useful when needing to select a specific datacenter or point to a mock server of the API for testing purposes.

Creating Sessions

To create a Vonage Video Session with the Ruby SDK, use the Video#create_session method. The method accepts some optional keyword parameters:

• :media_mode: whether or not the session uses the Vonage Video Media Router, which is required for some Vonage Video features (such as archiving). The valid options are 'routed' (to use the Media Router, this is the default) or 'relayed' (for peer-to-peer streaming)
• :archive_mode: Whether the session is automatically archived or not. The valid options are 'always' (for automatic archiving) or 'manual' (for manually-controlled archiving, this is the default)
• :location: A location hint for the Vonage Video server.

Below are some examples of creating sessions with different settings:

• Creating a session using the default settings (media_mode defaults to 'routed', which will use the Vonage Media Router, and archive_mode defaults to 'manual', which does not automatically create an archive):

• Creating a session that will attempt to transmit streams directly between clients (note that archive_mode MUST BE 'manual', which is the default, for media_mode to be 'relayed'):

• Creating a session with a location hint:

• Creating a session with automatic archiving (MUST use the 'routed' media mode, which is the default):

You can use the session_id accessor method of the returned Vonage::Response instance to get the session ID of the created session. This can be assigned to a variable or later use, such as when generating tokens:

Generating Tokens

Once a Session is created, you can start generating Tokens for clients to use when connecting to the session.

You can generate a token by calling the Video#generate_client_token method. The method expects one required keyword argument :session_id, which is the ID of the session you wish to create the token for (see Creating Sessions above). Additionally, the method accepts some optional keyword parameters:

• :scope: the scope of the token. This can only be set to 'session.connect', which is the default.
• :role: the role of the client. Valid options are 'publisher' (which is the default), 'subscriber', 'moderator', and 'publisher-only'. See roles
• :data: a string containing metadata describing the client, e.g. a user id or name. See Connection data
• :expire_time: an expiration time of up to 30 days for the token (after which it cannot be used to connect to the session), as integer Epoch seconds. The default is 24 hours.
• :initial_layout_class_list:

Below are some examples of generating tokens:

• Generate a Token with default settings:

• Generate a Token with some specific options

Working with Streams

The Ruby SDK provides methods for getting information about a specific Vonage Video stream connected to a session or for getting information about all streams for that session (see Creating Sessions).

To get information on all streams in a session, use the Streams#list method:

You can then call various accessor methods on the returned Vonage::Streams::ListResponse instance to get information about the stream list:

The items array contains individual streams connected to the session in the form of Vonage::Entity objects on which you can call accessor methods. For example, to get the ID of the first stream in the list of streams you could do the following:

The Vonage::Streams::ListResponse class includes Enumerable, so you can call any Enumerable method on a Vonage::Streams::ListResponse object. For example, to get an array of the IDs of all the streams connected to the session, you could do the following:

To get information of a specific stream in a session, use the Streams#info method:

You can then call various accessor methods on the returned Vonage::Response instance to get information about the stream:

Working with Archives

The Vonage Video API allows you to archive, save and retrieve sessions.

Starting an Archive Recording

When you create a session, you can set the archive_mode to 'always' to automatically create an archive recording of a session. If you set the archive_mode to 'manual' you can instead start an archive recording of the session by using the Archives#start method.

The method requires a keyword argument, :session_id, for the session to be archived, and also takes some optional keyword arguments which let you set the :has_audio, :has_video, and :name options. Note that you can only start an Archive on a Session that already has clients connected.

Below are some examples of creating archives:

• Create an Archive

• Create a named Archive

• Create an audio-only Archive

You can use the id accessor method of the returned Vonage::Response instance to get the Archive Id of the created archive. You can then use this ID for other interactions with the archive, such as stopping the archive recording or retrieving information about the archive.

Setting the output_mode option to 'individual' causes each stream in the archive to be recorded to its own individual file:

Setting the output_mode option to 'composed' (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, "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait).

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 a string of CSS styles. (For other layout types, do not set the :stylesheet key.)

If you do not specify an initial layout type, the archive uses the 'bestFit' layout type. For more information, see Customizing the video layout for composed archives.

Stopping an Archive Recording

You can stop the recording of a started Archive using the Archives#stop method and passing in the :archive_id of the archive to be stopped.

Getting Information about Archives

You can retrieve information about a specific archive recording using the Archives#info method and passing in the :archive_id of the archive.

You can also get a list of all the Archives you've created (up to 1000). This is done using the Archives#list method. The method can take optional :offset and :count keyword arguments to help you paginate through the results. This will return an instance of the Video::Archives::ListResponse class.

Deleting an Archive

To delete an Archive, you can call the Archives#delete method and passing in the archive_id of the archive to be deleted.

Setting the Layout of an Archive

You can set the layout of an archive using the Archives#change_layout method:

The method takes a required archive_id keyword arguments as well as three optional ones (type, stylesheet, and screenshare_type):

• 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.)

• The screenshare_type indicates the layout type to use when there is a screen-sharing stream in the session. Note that to use this property, you must set the type property to "bestFit" and leave the stylesheet property unset. For more information, see Layout types for screen sharing.

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 Video#generate_client_token method.

Setting the layout of composed archives is optional. By default, composed archives use the "best fit" layout. See Customizing the video layout for composed archives for more details.

Working with Broadcasts

The Vonage Video API allows you to broadcast sessions.

Starting a Broadcast

You can start a broadcast of the session by using the Broadcasts#start method. The method requires a keyword argument, :session_id, for the session to be broadcast, and also takes some optional keyword arguments which let you specify settings for the broadcast:

• layout: used to customize the layout of the broadcast. Set this to a hash containing three keys:
  • :type (required). Valid values are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation), "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation).
  • :stylesheet: (required if :type is set to 'custom'). If you specify a "custom" layout type, set the :stylesheet key to a string of CSS styles. (For other layout types, do not set the :stylesheet key.)
  • :screenshareType: used to set the screenshareType property to the layout type to use when there is a screen-sharing stream in the session. Valid values are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation), "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation).
• max_duration: The maximum duration for the broadcast, in seconds. The default is 4 hours.
• outputs: A hash which defines the types of broadcast streams you want to start (both HLS and RTMP). The hash has two possible keys, :hls and/or rtmp:
  • :hls: this is a hash with two possible keys (both boolean values), :dvr (whether to enable DVR functionality), and :lowLatency (whether to enable low-latency mode for the HLS stream)
  • :rtmp: an array of up to five hashes, each containing information about RTMP broadcast streams. Each hash can specify an :id for the stream, a required :serverUrl for the RTMP server, and a required :streamName.
• :resolution: a string specifying the resolution of the broadcast. Valid options are 640x480, 1280x720, 1920x1080, 480x640, 720x1280, 1080x1920
• :stream_mode: either auto (the default), or manual
• :multi_broadcast_tag: if supporting multiple broadcasts for the same session, set this to a unique string for each simultaneous broadcast
• :max_bitrate: The maximum bitrate for the stream

Below are some examples of creating broadcasts:

• Create an HLS Broadcast

• Create an RTMP Broadcast

You can use the id accessor method of the returned Vonage::Response instance to get the Broadcast Id of the created broadcast. You can then use this ID for other interactions with the broadcast, such as stopping the broadcast or retrieving information about the broadcast.

Stopping a Broadcast

You can stop a broadcast using the Broadcasts#stop method and passing in the :broadcast_id of the Broadcast to be stopped.

Getting Information about Broadcast

You can retrieve information about a specific broadcast using the Broadcast#info method and passing in the :broadcast_id of the broadcast.

You can also get a list of all the Broadcasts you've created. This is done using the Broadcasts#list method. The method can take optional :offset and :count keyword arguments to help you paginate through the results. This will return an instance of the Video::Broadcasts::ListResponse class.

Signaling

You can send a signal to either a specific participant of an active Vonage Video session, or to all participants.

To send to a specific participant, use the Signals#send_to_one method.

To send to a all participants, use the Signals#send_to_all method.

Both methods require session_id, type, and data keyword arguments. The send_to_one method additionally requires a connection_id keyword argument which identifies the specific participant to which the signal should be sent.

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

For more information on signaling, see the Vonage Video Signaling programming guide.

Moderation

You can moderate sessions in a number of ways.

You can cause a client to be forced to disconnect from a session by using the Moderation#force_disconnect method, passing in the session_id of the active Vonage video session and the connection_id of the client to be disconnected.

You can mute a specific stream in an active Vonage Video session, or mute multiple streams in that session.

To mute to a specific stream, use the Moderation#mute_single_stream method, passing in the session_id of the active Vonage video session and the stream_id of the stream to be muted.

To mute multiple streams in a session, use the Moderation#mute_multiple_streams method.

As well as the session_id, the mute_multiple_streams method defines two additional keyword arguments:

• The active argument is required, and should be set to either true or false. Setting to true enables the mute state of the session, means that all current and future streams published to the session (with the exception of streams in the excluded_stream_ids array) are muted. When you call this method with the active property set to false, future streams published to the session are not muted (but any existing muted streams remain muted).

• The excluded_stream_ids keyword argument is optional and takes an array of stream ids which are to be excluded from being muted.

Working with SIP

You can initiate a SIP call using the SIP#dial method. The method has three required keyword arguments:

• :session_id: the ID of the session to be dialled into.
• :token: a client token for the session (see Generating Client Tokens)
• :sip_uri: the SIP URI to be used as destination of the SIP call initiated from Vonage Video to your SIP platform.

Below is an example of using the SIP#dial method:

For more information on SIP Interconnect, see the Vonage Video SIP Interconnect developer guide.

Requirements

You will need a Application ID and Private Key for a Video-enabled Vonage Application. You can create a Vonage Application via the Vonage Dashboard.

The Vonage Video Ruby SDK supports Ruby 2.7.0 or greater.

Release Notes

Note that the video functionality is in the Vonage Ruby SDK from version 7.19.0.

See the Releases page for details.