Added Captions API (#245)

* Added Captions API

* Bump version: v4.12.0 → v4.13.0

* Fixed bad character

.bumpversion.cfg

@@ -1,7 +1,7 @@
 [bumpversion]
 commit = True
 tag = False
-current_version = v4.12.0
+current_version = v4.13.0
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<release>[a-z]+)(?P<build>\d+))?
 serialize = 
 	{major}.{minor}.{patch}-{release}{build}

README.md

@@ -34,7 +34,7 @@ When you use Maven as your build tool, you can manage dependencies in the `pom.x
 <dependency>
     <groupId>com.tokbox</groupId>
     <artifactId>opentok-server-sdk</artifactId>
-    <version>4.12.0</version>
+    <version>4.13.0</version>
 </dependency>
 ```
 
@@ -44,7 +44,7 @@ When you use Gradle as your build tool, you can manage dependencies in the `buil
 
 ```groovy
 dependencies {
-  compile group: 'com.tokbox', name: 'opentok-server-sdk', version: '4.12.0'
+  compile group: 'com.tokbox', name: 'opentok-server-sdk', version: '4.13.0'
 }
 ```
 

build.gradle

@@ -11,7 +11,7 @@ plugins {
 
 group = 'com.tokbox'
 archivesBaseName = 'opentok-server-sdk'
-version = '4.12.0'
+version = '4.13.0'
 sourceCompatibility = "1.8"
 targetCompatibility = "1.8"
 

src/main/java/com/opentok/Caption.java

@@ -0,0 +1,45 @@
+/**
+ * OpenTok Java SDK
+ * Copyright (C) 2023 Vonage.
+ * http://www.tokbox.com
+ *
+ * Licensed under The MIT License (MIT). See LICENSE file for more information.
+ */
+package com.opentok;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonValue;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Represents the response from {@link OpenTok#startCaptions(String, String, CaptionProperties)}.
+ */
+@JsonIgnoreProperties(ignoreUnknown=true)
+public class Caption {
+    private String captionsId;
+
+    /**
+     * The unique ID for the audio captioning session.
+     *
+     * @return The captions UUID as a string.
+     */
+    @JsonProperty("captionsId")
+    public String getCaptionsId() {
+        return captionsId;
+    }
+
+    @Override
+    public String toString() {
+        try {
+            return new ObjectMapper().writeValueAsString(this);
+        } catch (JsonProcessingException e) {
+            return "";
+        }
+    }
+}

src/main/java/com/opentok/CaptionProperties.java

@@ -0,0 +1,165 @@
+/**
+ * OpenTok Java SDK
+ * Copyright (C) 2023 Vonage.
+ * http://www.tokbox.com
+ *
+ * Licensed under The MIT License (MIT). See LICENSE file for more information.
+ */
+package com.opentok;
+
+/**
+ * Defines values for the <code>properties</code> parameter of the
+ * {@link OpenTok#startCaptions(String, String, CaptionProperties)} method.
+ *
+ * @see OpenTok#startCaptions(String, String, CaptionProperties)
+ */
+public class CaptionProperties {
+    private final String statusCallbackUrl, languageCode;
+    private final int maxDuration;
+    private final boolean partialCaptions;
+
+    private CaptionProperties(Builder builder) {
+        statusCallbackUrl = builder.statusCallbackUrl;
+        languageCode = builder.languageCode;
+        maxDuration = builder.maxDuration;
+        partialCaptions = builder.partialCaptions;
+    }
+
+    /**
+     * 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>.
+     *
+     * @return The status callback URL as a string, or {@code null} if not set.
+     */
+    public String getStatusCallbackUrl() {
+        return statusCallbackUrl;
+    }
+
+    /**
+     * The BCP-47 code for a spoken language used on this call.
+     *
+     * @return The language code as a string.
+     */
+    public String getLanguageCode() {
+        return languageCode;
+    }
+
+    /**
+     * The maximum duration for the audio captioning, in seconds.
+     *
+     * @return The maximum captioning duration as an integer.
+     */
+    public int getMaxDuration() {
+        return maxDuration;
+    }
+
+    /**
+     * Whether faster captioning is enabled at the cost of some degree of inaccuracies.
+     *
+     * @return {@code true} if the partial captions setting is enabled.
+     */
+    public boolean partialCaptions() {
+        return partialCaptions;
+    }
+
+    /**
+     * Entry point for constructing an instance of this class.
+     *
+     * @return A new Builder.
+     */
+    public static Builder Builder() {
+        return new Builder();
+    }
+
+    /**
+     * Used to create a CaptionProperties object.
+     *
+     * @see CaptionProperties
+     */
+    public static class Builder {
+        private String languageCode = "en-US", statusCallbackUrl;
+        private int maxDuration = 14400;
+        private boolean partialCaptions = true;
+
+        private Builder() {
+        }
+
+        /**
+         * 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).
+         *
+         * @param languageCode The BCP-47 language code as a string.
+         *
+         * @return This Builder with the languageCode property setting.
+         */
+        public Builder languageCode(String languageCode) {
+            if (languageCode == null || languageCode.length() != 5 || languageCode.charAt(2) != '-') {
+                throw new IllegalArgumentException("Invalid language code.");
+            }
+            this.languageCode = languageCode;
+            return this;
+        }
+
+        /**
+         * 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>.
+         *
+         * @param statusCallbackUrl The status callback URL as a string.
+         *
+         * @return This Builder with the statusCallbackUrl property setting.
+         */
+        public Builder statusCallbackUrl(String statusCallbackUrl) {
+            if (statusCallbackUrl == null || statusCallbackUrl.length() < 15 || statusCallbackUrl.length() > 2048) {
+                throw new IllegalArgumentException("Status callback URL must be between 15 and 2048 characters.");
+            }
+            this.statusCallbackUrl = statusCallbackUrl;
+            return this;
+        }
+
+        /**
+         * The maximum duration for the audio captioning, in seconds.
+         * The default value is 14,400 seconds (4 hours), the maximum duration allowed.
+         *
+         * @param maxDuration The maximum captions duration in seconds.
+         *
+         * @return This Builder with the maxDuration property setting.
+         */
+        public Builder maxDuration(int maxDuration) {
+            if ((this.maxDuration = maxDuration) < 0 || maxDuration > 14400) {
+                throw new IllegalArgumentException("Max duration must be positive and less than 14400 seconds.");
+            }
+            return this;
+        }
+
+        /**
+         * Whether to enable this to faster captioning at the cost of some degree of inaccuracies.
+         * The default value is {@code true}.
+         *
+         * @param partialCaptions Whether to enable faster captions.
+         *
+         * @return This Builder with the partialCaptions property setting.
+         */
+        public Builder partialCaptions(boolean partialCaptions) {
+            this.partialCaptions = partialCaptions;
+            return this;
+        }
+
+        /**
+         * Builds the CaptionProperties object.
+         *
+         * @return The CaptionProperties object with this builder's settings.
+         */
+        public CaptionProperties build() {
+            return new CaptionProperties(this);
+        }
+    }
+}

src/main/java/com/opentok/OpenTok.java

@@ -52,7 +52,8 @@ public class OpenTok {
         broadcastReader = new ObjectMapper().readerFor(Broadcast.class),
         renderReader = new ObjectMapper().readerFor(Render.class),
         renderListReader = new ObjectMapper().readerForListOf(Render.class),
-        connectReader = new ObjectMapper().readerFor(AudioConnector.class);
+        connectReader = new ObjectMapper().readerFor(AudioConnector.class),
+        captionReader = new ObjectMapper().readerFor(Caption.class);
 
     static final String defaultApiUrl = "https://api.opentok.com";
 
@@ -978,6 +979,55 @@ public List<Render> listRenders(Integer offset, Integer count) throws OpenTokExc
         }
     }
 
+    /**
+     * Use the Live Captions API to transcribe audio streams and generate real-time captions for your application.
+     * Live Captions is enabled by default for all projects, and it is a usage-based product. The Live Captions
+     * feature is only supported in routed sessions (sessions that use the OpenTok Media Router). You can send up to
+     * 50 audio streams from a single Vonage session at a time to the transcription service for captions.
+     *
+     * @param sessionId The session ID of the OpenTok session. The audio from Publishers publishing into
+     * this session will be used to generate the captions.
+     *
+     * @param token A valid OpenTok token with role set to Moderator.
+     *
+     * @param properties The {@link CaptionProperties} object defining optional properties of the live captioning.
+     *
+     * @return A {@link Caption} response containing the captions ID for this call.
+     *
+     * @throws OpenTokException
+     */
+    public Caption startCaptions(String sessionId, String token, CaptionProperties properties) throws OpenTokException {
+        if (StringUtils.isEmpty(sessionId)) {
+            throw new InvalidArgumentException("Session ID is required.");
+        }
+        if (StringUtils.isEmpty(token)) {
+            throw new InvalidArgumentException("Token is required.");
+        }
+        String captions = client.startCaption(sessionId, token,
+                properties != null ? properties : CaptionProperties.Builder().build()
+        );
+        try {
+            return captionReader.readValue(captions);
+        } catch (JsonProcessingException e) {
+            throw new RequestException("Exception mapping json: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Use this method to stop live captions for a session.
+     *
+     * @param captionsId The unique ID for the audio captioning session,
+     * as obtained from {@linkplain Caption#getCaptionsId()}.
+     *
+     * @throws OpenTokException
+     */
+    public void stopCaptions(String captionsId) throws OpenTokException {
+        if (StringUtils.isEmpty(captionsId)) {
+            throw new InvalidArgumentException("Captions id is required.");
+        }
+        client.stopCaption(captionsId);
+    }
+
     /**
      * Used to create an OpenTok object with advanced settings. You can set
      * the request timeout for API calls and a proxy to use for API calls.

src/main/java/com/opentok/constants/Version.java

@@ -8,5 +8,5 @@
 package com.opentok.constants;
 
 public class Version {
-    public static final String VERSION = "4.12.0";
+    public static final String VERSION = "4.13.0";
 }