REVAI-3854: Usage examples (#62)

* REVAI-3854: Usage examples

README.md

@@ -68,6 +68,28 @@ try {
 }
 RevAiJob revAiJob = apiClient.submitJobLocalFile(fileInputStream, String fileName, RevAiJobOptions options);
 ```
+You can request transcript summary.
+```
+String urlLinkToFile = "https://www.rev.ai/FTC_Sample_1.mp3";
+
+RevAiJobOptions revAiJobOptions = new RevAiJobOptions();
+revAiJobOptions.setSourceConfig(urlLinkToFile, null);
+revAiJobOptions.setLanguage("en");
+revAiJobOptions.setSummarizationOptions(new SummarizationOptions().setModel(NlpModel.STANDARD));
+```
+You can request transcript translation into up to five languages.
+```
+String urlLinkToFile = "https://www.rev.ai/FTC_Sample_1.mp3";
+
+RevAiJobOptions revAiJobOptions = new RevAiJobOptions();
+revAiJobOptions.setSourceConfig(urlLinkToFile, null);
+revAiJobOptions.setLanguage("en");
+revAiJobOptions.setTranslationOptions(new TranslationOptions(Arrays.asList(
+            new TranslationLanguageOptions("es")
+                    .setModel(NlpModel.PREMIUM),
+            new TranslationLanguageOptions("de"))
+    ));
+```
 
 You can also submit a job to be handled by a human transcriber using our [Human Transcription](https://docs.rev.ai/api/asynchronous/transcribers/#human-transcription) option.
 ```
@@ -160,6 +182,9 @@ String transcriptText = apiClient.getTranscriptText(revAiJob.getJobId());
 
 // or as an object
 RevAiTranscript revAiTranscript = apiClient.getTranscriptObject(revAiJob.getJobId());
+
+// or if you requested transcript translation(s)
+RevAiTranscript revAiTranscript = apiClient.getTranslatedTranscriptObject(revAiJob.getJobId(), "es");
 ```
 
 The text output is a string containing just the text of your transcript. The object form of
@@ -180,8 +205,23 @@ InputStream inputStream = apiClient.getCaptions(revAiJob.getJobId(), RevAiCaptio
 // with speaker channels
 int channelId = 1;
 InputStream inputStream = apiClient.getCaptions(revAiJob.getJobId(), RevAiCaptionType.VTT, channelId);
+
+// or if you requested transcript translation(s)
+InputStream inputStream = apiClient.getTranslatedCaptions(revAiJob.getJobId(), "es", RevAiCaptionType.VTT, channelId);
+```
+
+### Getting transcript summary
+
+If you requested transcript summary, you can retrieve it as plain text or structured object:
+
 ```
+// as text
+apiClient.getTranscriptSummaryText(job.id);
 
+// as object
+apiClient.getTranscriptSummaryObject(job.id);
+
+```
 ## Streaming Audio
 
 In order to stream audio, you will need to setup a streaming client and the content type

examples/AsyncSummarizeMediaUrl.java

@@ -0,0 +1,113 @@
+package ai.rev;
+
+import ai.rev.speechtotext.ApiClient;
+import ai.rev.speechtotext.models.NlpModel;
+import ai.rev.speechtotext.models.asynchronous.*;
+import ai.rev.speechtotext.models.vocabulary.CustomVocabulary;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+
+public class AsyncSummarizeMediaUrl {
+
+  public static void main(String[] args) {
+    // Assign your access token to a String
+    String accessToken = "<YOUR_ACCESS_TOKEN>";
+
+    // Initialize the ApiClient with your access token
+    ApiClient apiClient = new ApiClient(accessToken);
+
+    // Set up source configuration parameters
+    String mediaUrl = "https://www.rev.ai/FTC_Sample_1.mp3";
+
+    // Initialize the RevAiJobOptions object and assign
+    RevAiJobOptions revAiJobOptions = new RevAiJobOptions();
+    revAiJobOptions.setSourceConfig(mediaUrl, null);
+    revAiJobOptions.setDeleteAfterSeconds(2592000); // 30 days in seconds
+    revAiJobOptions.setLanguage("en");
+    revAiJobOptions.setSummarizationOptions(new SummarizationOptions().setModel(NlpModel.STANDARD));
+
+    RevAiJob submittedJob;
+
+    try {
+      // Submit job with transcription options
+      submittedJob = apiClient.submitJobUrl(revAiJobOptions);
+    } catch (IOException e) {
+      throw new RuntimeException("Failed to submit url [" + mediaUrl + "] " + e.getMessage());
+    }
+    String jobId = submittedJob.getJobId();
+    System.out.println("Job Id: " + jobId);
+    System.out.println("Job Status: " + submittedJob.getJobStatus());
+    System.out.println("Created On: " + submittedJob.getCreatedOn());
+
+    // Waits 5 seconds between each status check to see if job is complete
+    boolean isJobComplete = false;
+    while (!isJobComplete) {
+      RevAiJob retrievedJob;
+      try {
+        retrievedJob = apiClient.getJobDetails(jobId);
+      } catch (IOException e) {
+        throw new RuntimeException("Failed to retrieve job [" + jobId + "] " + e.getMessage());
+      }
+
+      RevAiJobStatus retrievedJobStatus = retrievedJob.getJobStatus();
+      if (retrievedJobStatus == RevAiJobStatus.TRANSCRIBED
+          || retrievedJobStatus == RevAiJobStatus.FAILED) {
+        isJobComplete = true;
+      } else {
+        try {
+          Thread.sleep(5000);
+        } catch (InterruptedException e) {
+          e.printStackTrace();
+        }
+      }
+    }
+
+    // Waits 5 seconds between each status check to see if summarization job is complete
+    isJobComplete = false;
+    while (!isJobComplete) {
+      RevAiJob retrievedJob;
+      try {
+        retrievedJob = apiClient.getJobDetails(jobId);
+      } catch (IOException e) {
+        throw new RuntimeException("Failed to retrieve job [" + jobId + "] " + e.getMessage());
+      }
+
+      SummarizationJobStatus summarizationJobStatus = retrievedJob.getSummarization().getJobStatus();
+      if (summarizationJobStatus == SummarizationJobStatus.COMPLETED
+              || summarizationJobStatus == SummarizationJobStatus.FAILED) {
+        isJobComplete = true;
+      } else {
+        try {
+          Thread.sleep(5000);
+        } catch (InterruptedException e) {
+          e.printStackTrace();
+        }
+      }
+    }
+
+    // Get the transcript and caption outputs
+    Summary objectSummary;
+    String textSummary;
+
+    try {
+      objectSummary = apiClient.getTranscriptSummaryObject(jobId);
+      textSummary = apiClient.getTranscriptSummaryText(jobId);
+
+      System.out.println("Summary:" + textSummary);
+    } catch (IOException e) {
+      e.printStackTrace();
+    }
+
+
+    /*
+     * The job can now be deleted. Deleting the job will remove ALL information
+     * about the job from the Rev AI servers. Subsequent requests to Rev AI that
+     * use the deleted jobs Id will return 404's.
+     */
+    // apiClient.deleteJob(jobId);
+  }
+}

examples/AsyncTranslateMediaUrl.java

@@ -0,0 +1,121 @@
+package ai.rev;
+
+import ai.rev.speechtotext.ApiClient;
+import ai.rev.speechtotext.models.NlpModel;
+import ai.rev.speechtotext.models.asynchronous.*;
+import ai.rev.speechtotext.models.vocabulary.CustomVocabulary;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+
+public class AsyncTranslateMediaUrl {
+
+  public static void main(String[] args) {
+    // Assign your access token to a String
+    String accessToken = "<YOUR_ACCESS_TOKEN>";
+
+    // Initialize the ApiClient with your access token
+    ApiClient apiClient = new ApiClient(accessToken);
+
+    // Set up source configuration parameters
+    String mediaUrl = "https://www.rev.ai/FTC_Sample_1.mp3";
+
+    // Initialize the RevAiJobOptions object and assign
+    RevAiJobOptions revAiJobOptions = new RevAiJobOptions();
+    revAiJobOptions.setSourceConfig(mediaUrl, null);
+    revAiJobOptions.setDeleteAfterSeconds(2592000); // 30 days in seconds
+    revAiJobOptions.setLanguage("en");
+    revAiJobOptions.setTranslationOptions(new TranslationOptions(Arrays.asList(
+            new TranslationLanguageOptions("es")
+                    .setModel(NlpModel.PREMIUM),
+            new TranslationLanguageOptions("de"))
+    ));
+
+    RevAiJob submittedJob;
+
+    try {
+      // Submit job with transcription options
+      submittedJob = apiClient.submitJobUrl(revAiJobOptions);
+    } catch (IOException e) {
+      throw new RuntimeException("Failed to submit url [" + mediaUrl + "] " + e.getMessage());
+    }
+    String jobId = submittedJob.getJobId();
+    System.out.println("Job Id: " + jobId);
+    System.out.println("Job Status: " + submittedJob.getJobStatus());
+    System.out.println("Created On: " + submittedJob.getCreatedOn());
+
+    // Waits 5 seconds between each status check to see if job is complete
+    boolean isJobComplete = false;
+    while (!isJobComplete) {
+      RevAiJob retrievedJob;
+      try {
+        retrievedJob = apiClient.getJobDetails(jobId);
+      } catch (IOException e) {
+        throw new RuntimeException("Failed to retrieve job [" + jobId + "] " + e.getMessage());
+      }
+
+      RevAiJobStatus retrievedJobStatus = retrievedJob.getJobStatus();
+      if (retrievedJobStatus == RevAiJobStatus.TRANSCRIBED
+          || retrievedJobStatus == RevAiJobStatus.FAILED) {
+        isJobComplete = true;
+      } else {
+        try {
+          Thread.sleep(5000);
+        } catch (InterruptedException e) {
+          e.printStackTrace();
+        }
+      }
+    }
+
+    // Waits 5 seconds between each status check to see if summarization job is complete
+    isJobComplete = false;
+    while (!isJobComplete) {
+      RevAiJob retrievedJob;
+      try {
+        retrievedJob = apiClient.getJobDetails(jobId);
+      } catch (IOException e) {
+        throw new RuntimeException("Failed to retrieve job [" + jobId + "] " + e.getMessage());
+      }
+
+      TranslationJobStatus translationJobStatus = retrievedJob.getTranslation().getTargetLanguages().get(0).getJobStatus();
+      if (translationJobStatus == TranslationJobStatus.COMPLETED
+              || translationJobStatus == TranslationJobStatus.FAILED) {
+        isJobComplete = true;
+      } else {
+        try {
+          Thread.sleep(5000);
+        } catch (InterruptedException e) {
+          e.printStackTrace();
+        }
+      }
+    }
+
+    // Get the transcript and caption outputs
+    RevAiTranscript objectTranscript;
+    String textTranscript;
+    InputStream srtCaptions;
+    InputStream vttCaptions;
+
+    try {
+      objectTranscript = apiClient.getTranslatedTranscriptObject(jobId, "es");
+      textTranscript = apiClient.getTranslatedTranscriptText(jobId, "es");
+      srtCaptions = apiClient.getTranslatedCaptions(jobId, "es", RevAiCaptionType.SRT, null);
+      vttCaptions = apiClient.getTranslatedCaptions(jobId, "es", RevAiCaptionType.VTT, null);
+
+      System.out.println("Translation:" + textTranscript);
+    } catch (IOException e) {
+      e.printStackTrace();
+    }
+
+
+    /*
+     * The job can now be deleted. Deleting the job will remove ALL information
+     * about the job from the Rev AI servers. Subsequent requests to Rev AI that
+     * use the deleted jobs Id will return 404's.
+     */
+    // apiClient.deleteJob(jobId);
+  }
+}

pom.xml

@@ -5,7 +5,7 @@
     <!-- groupId, artifactId, these namespaces should not be changed -->
     <groupId>ai.rev</groupId>
     <artifactId>revai-java-sdk</artifactId>
-    <version>2.3.2</version>
+    <version>2.4.0</version>
     <name>Rev AI SDK for Java</name>
     <description>Java SDK for Rev AI API</description>
     <url>https://docs.rev.ai/</url>