DEVX-6803: Adding Captions API (#267)

* Adding Captions API functionality to the library

CHANGES.md

@@ -1,3 +1,7 @@
+# 4.8.0
+
+* Add support for Captions API [#267](https://github.com/opentok/OpenTok-Ruby-SDK/pull/267)
+
 # 4.7.1
 
 * Updates docs comments for `Broadcasts` and `Sip` [#266](https://github.com/opentok/OpenTok-Ruby-SDK/pull/266)

lib/opentok/captions.rb

@@ -0,0 +1,61 @@
+module OpenTok
+  #  A class for working with OpenTok captions.
+  class Captions
+    # @private
+    def initialize(client)
+      @client = client
+    end
+
+    # Starts live captions for the specified OpenTok session.
+    # See the {https://tokbox.com/developer/guides/live-captions/ OpenTok Live Captions developer guide}.
+    #
+    # @example
+    #    opts = { "language_code" => "en-GB",
+    #             "max_duration" => 5000,
+    #             "partial_captions" => false,
+    #             "status_callback_url" => status_callback_url
+    #           }
+    #    response = opentok.captions.start(session_id, token, opts)
+    #
+    # @param [String] session_id The session ID corresponding to the session for which captions will start.
+    # @param [String] token The token for the session ID with which the SIP user will use to connect.
+    # @param [Hash] options A hash defining options for the captions. For example:
+    # @option options [String] :language_code The BCP-47 code for a spoken language used on this call.
+    #   The default value is "en-US". The following language codes are supported:
+    #     - "en-AU" (English, Australia)
+    #     - "en-GB" (Englsh, UK)
+    #     - "es-US" (English, US)
+    #     - "zh-CN” (Chinese, Simplified)
+    #     - "fr-FR" (French)
+    #     - "fr-CA" (French, Canadian)
+    #     - "de-DE" (German)
+    #     - "hi-IN" (Hindi, Indian)
+    #     - "it-IT" (Italian)
+    #     - "ja-JP" (Japanese)
+    #     - "ko-KR" (Korean)
+    #     - "pt-BR" (Portuguese, Brazilian)
+    #     - "th-TH" (Thai)
+    # @option options [Integer] :max_duration The maximum duration for the audio captioning, in seconds.
+    #   The default value is 14,400 seconds (4 hours), the maximum duration allowed.
+    # @option options [Boolean] :partial_captions Whether to enable this to faster captioning at the cost of some
+    #   degree of inaccuracies. The default value is `true`.
+    # @option options [String] :status_callback_url A publicly reachable URL controlled by the customer and capable
+    #   of generating the content to be rendered without user intervention. The minimum length of the URL is 15
+    #   characters and the maximum length is 2048 characters.
+    #   For more information, see {https://tokbox.com/developer/guides/live-captions/#live-caption-status-updates Live Caption status updates}.
+    def start(session_id, token, options = {})
+      @client.start_live_captions(session_id, token, options)
+    end
+
+    # Starts live captions for the specified OpenTok session.
+    # See the {https://tokbox.com/developer/guides/live-captions/ OpenTok Live Captions developer guide}.
+    #
+    # @example
+    #    response = opentok.captions.stop(captions_id)
+    #
+    # @param [String] captions_id The ID for the captions to be stopped (returned from the `start` request).
+    def stop(captions_id)
+      @client.stop_live_captions(captions_id)
+    end
+  end
+end

lib/opentok/exceptions.rb

@@ -18,4 +18,6 @@ class OpenTokBroadcastError < OpenTokError; end
   class OpenTokWebSocketError < OpenTokError; end
   # Defines errors raised when you perform Experience Composer render operations.
   class OpenTokRenderError < OpenTokError; end
+  # Defines errors raised when you perform Captions operations.
+  class OpenTokCaptionsError < OpenTokError; end
 end

lib/opentok/opentok.rb

@@ -12,6 +12,7 @@
 require "opentok/signals"
 require "opentok/broadcasts"
 require "opentok/renders"
+require "opentok/captions"
 
 module OpenTok
   # Contains methods for creating OpenTok sessions and generating tokens. It also includes
@@ -214,6 +215,16 @@ def broadcasts
       @broadcasts ||= Broadcasts.new client
     end
 
+    # A Captions object, which lets you start and stop live captions for an OpenTok session.
+    def captions
+      @captions ||= Captions.new client
+    end
+
+    # A Connections object, which lets you disconnect clients from an OpenTok session.
+    def connections
+      @connections ||= Connections.new client
+    end
+
     # A Renders object, which lets you work with OpenTok Experience Composer renders.
     def renders
       @renders ||= Renders.new client
@@ -234,11 +245,6 @@ def signals
       @signals ||= Signals.new client
     end
 
-    # A Connections object, which lets you disconnect clients from an OpenTok session.
-    def connections
-      @connections ||= Connections.new client
-    end
-
     # A WebSocket object, which lets you connect OpenTok streams to a WebSocket URI.
     def websocket
       @websocket ||= WebSocket.new client

lib/opentok/version.rb

@@ -1,4 +1,4 @@
 module OpenTok
   # @private
-  VERSION = '4.7.1'
+  VERSION = '4.8.0'
 end

spec/opentok/captions_spec.rb

@@ -0,0 +1,44 @@
+require "opentok/opentok"
+require "opentok/captions"
+require "opentok/version"
+require "spec_helper"
+
+describe OpenTok::Captions do
+  before(:each) do
+    now = Time.parse("2017-04-18 20:17:40 +1000")
+    allow(Time).to receive(:now) { now }
+  end
+
+  let(:api_key) { "123456" }
+  let(:api_secret) { "1234567890abcdef1234567890abcdef1234567890" }
+  let(:session_id) { "SESSIONID" }
+  let(:captions_id) { "CAPTIONSID" }
+  let(:expiring_token) { "TOKENID" }
+  let(:status_callback_url) { "https://example.com/captions/status" }
+  let(:opentok) { OpenTok::OpenTok.new api_key, api_secret }
+  let(:captions) { opentok.captions }
+  subject { captions }
+
+  it "receives a valid response when starting captions", :vcr => { :erb => { :version => OpenTok::VERSION + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"} } do
+    response = captions.start(session_id, expiring_token)
+    expect(response).not_to be_nil
+    expect(response.code).to eq(202)
+  end
+
+  it "receives a valid response when starting captions with options", :vcr => { :erb => { :version => OpenTok::VERSION + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"} } do
+    opts = { "language_code" => "en-GB",
+             "max_duration" => 5000,
+             "partial_captions" => false,
+             "status_callback_url" => status_callback_url
+           }
+
+    response = captions.start(session_id, expiring_token, opts)
+    expect(response).not_to be_nil
+    expect(response.code).to eq(202)
+  end
+
+  it "receives a valid response when stopping captions", :vcr => { :erb => { :version => OpenTok::VERSION + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"} } do
+    response = captions.stop(captions_id)
+    expect(response.code).to eq(202)
+  end
+end