Feature/captions api

src/OpenTok/OpenTok.php

@@ -1262,6 +1262,66 @@ public function connectAudio(string $sessionId, string $token, array $websocketO
         return $this->client->connectAudio($sessionId, $token, $websocketOptions);
     }
 
+    /**
+     *
+     * Use this method to start real-time Live Captions for an OpenTok Session.
+     *
+     * The maximum allowed duration is 4 hours, after which the audio captioning will stop without any effect on the
+     * ongoing OpenTok Session. An event will be posted to your callback URL if provided when starting the captions.
+     *
+     * Each OpenTok Session supports only one audio captioning session.
+     *
+     * For more information about the Live Captions feature, see the Live Captions developer guide.
+     *
+     * @param string $sessionId The session ID of the OpenTok session. The audio from Publishers publishing into
+     * this session will be used to generate the captions.
+     *
+     * @param string $token A valid OpenTok token with role set to Moderator.
+     *
+     * @param string $languageCode (Optional) 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"
+     * (English, 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).
+     *
+     * @param int $maxDuration (Optional) The maximum duration for the audio captioning, in seconds. The default value
+     * is 14,400 seconds (4 hours), the maximum duration allowed.
+     *
+     * @param bool $partialCaptions (Optional) Whether to enable this to faster captioning at the cost of some
+     * degree of inaccuracies. The default value is true.
+     *
+     * @param string $statusCallbackUrl (Optional) 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 <a href="https://tokbox.com/developer/guides/live-captions/#live-caption-status-updates">Live Caption status updates.</a>
+     */
+    public function startCaptions(
+        string $sessionId,
+        string $token,
+        ?string $languageCode = null,
+        ?int $maxDuration = null,
+        ?bool $partialCaptions = null,
+        ?string $statusCallbackUrl = null
+    ): array
+    {
+        return $this->client->startCaptions(
+            $sessionId,
+            $token,
+            $languageCode,
+            $maxDuration,
+            $partialCaptions,
+            $statusCallbackUrl
+        );
+    }
+
+    /**
+     * Use this method to stop live captions for a session.
+     */
+    public function stopCaptions(string $captionsId)
+    {
+        return $this->client->stopCaptions($captionsId);
+    }
+
     /** @internal */
     private function signString($string, $secret)
     {

src/OpenTok/Util/Client.php

@@ -881,9 +881,75 @@ public function connectAudio(string $sessionId, string $token, array $websocketO
             $this->handleException($e);
             return false;
         }
+
+        return $jsonResponse;
+    }
+
+    public function startCaptions(
+        string $sessionId,
+        string $token,
+        ?string $languageCode,
+        ?int $maxDuration,
+        ?bool $partialCaptions,
+        ?string $statusCallbackUrl
+    )
+    {
+        $request = new Request(
+            'POST',
+            '/v2/project/' . $this->apiKey . '/captions'
+        );
+
+        $body = [
+            'sessionId' => $sessionId,
+            'token' => $token,
+        ];
+
+        if ($languageCode !== null) {
+            $body['languageCode'] = $languageCode;
+        }
+
+        if ($maxDuration !== null) {
+            $body['maxDuration'] = $maxDuration;
+        }
+
+        if ($partialCaptions !== null) {
+            $body['partialCaptions'] = $partialCaptions;
+        }
+
+        if ($statusCallbackUrl !== null) {
+            $body['statusCallbackUrl'] = $statusCallbackUrl;
+        }
+
+        try {
+            $response = $this->client->send($request, [
+                'debug' => $this->isDebug(),
+                'json' => $body
+            ]);
+            $jsonResponse = json_decode($response->getBody(), true);
+        } catch (\Exception $e) {
+            $this->handleException($e);
+        }
+
         return $jsonResponse;
     }
 
+    public function stopCaptions(string $captionsId)
+    {
+        $request = new Request(
+            'POST',
+            '/v2/project/' . $this->apiKey . '/captions/' . $captionsId . '/stop'
+        );
+
+        try {
+            $this->client->send($request, [
+                'debug' => $this->isDebug(),
+            ]);
+            return true;
+        } catch (\Exception $e) {
+            $this->handleException($e);
+        }
+    }
+
     private function handleException($e)
     {
         // TODO: test coverage

tests/OpenTokTest/OpenTokTest.php

@@ -2836,5 +2836,33 @@ public function testDefaultTimeoutErrorsIfLessThanZero(): void
         $this->expectExceptionMessage('Default Timeout must be a number greater than zero');
         new OpenTok('1234', 'abd', ['timeout' => -1]);
     }
+
+    public function testCanStartCaptions(): void
+    {
+        $this->setupOTWithMocks([[
+            'code' => 202,
+            'headers' => [
+                'Content-Type' => 'application/json'
+            ],
+            'path' => '/v2/project/APIKEY/session/SESSIONID/caption-start'
+        ]]);
+
+        $result = $this->opentok->startCaptions('SESSION_ID', 'abc');
+        $this->assertEquals('7c0680fc-6274-4de5-a66f-d0648e8d3ac2', $result['captionsId']);
+    }
+
+    public function testCanStopCaptions(): void
+    {
+        $this->setupOTWithMocks([[
+            'code' => 202,
+            'headers' => [
+                'Content-Type' => 'application/json'
+            ],
+            'path' => '/v2/project/APIKEY/session/SESSIONID/caption-stop'
+        ]]);
+
+        $result = $this->opentok->stopCaptions('7c0680fc-6274-4de5-a66f-d0648e8d3ac2');
+        $this->assertTrue($result);
+    }
 }
 

tests/mock/v2/project/APIKEY/session/SESSIONID/caption-start

@@ -0,0 +1,3 @@
+{
+  "captionsId": "7c0680fc-6274-4de5-a66f-d0648e8d3ac2"
+}