diff --git a/src/OpenTok/OpenTok.php b/src/OpenTok/OpenTok.php index 6a69aed..a33e394 100644 --- a/src/OpenTok/OpenTok.php +++ b/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 Live Caption status updates. + */ + 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) { diff --git a/src/OpenTok/Util/Client.php b/src/OpenTok/Util/Client.php index 9212c52..76606ec 100755 --- a/src/OpenTok/Util/Client.php +++ b/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 diff --git a/tests/OpenTokTest/OpenTokTest.php b/tests/OpenTokTest/OpenTokTest.php index c24d77a..4dbacfe 100644 --- a/tests/OpenTokTest/OpenTokTest.php +++ b/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); + } } diff --git a/tests/mock/v2/project/APIKEY/session/SESSIONID/caption-start b/tests/mock/v2/project/APIKEY/session/SESSIONID/caption-start new file mode 100644 index 0000000..cfca81f --- /dev/null +++ b/tests/mock/v2/project/APIKEY/session/SESSIONID/caption-start @@ -0,0 +1,3 @@ +{ + "captionsId": "7c0680fc-6274-4de5-a66f-d0648e8d3ac2" +} \ No newline at end of file diff --git a/tests/mock/v2/project/APIKEY/session/SESSIONID/caption-stop b/tests/mock/v2/project/APIKEY/session/SESSIONID/caption-stop new file mode 100644 index 0000000..e69de29