fix(client): properly support srt and vtt in audio transcriptions. (#472)

iammohan01 · TomerAberbach · web-flow · commit 1e5bf3d36cb1 · 2025-05-14T19:34:19.000-04:00
* feat(api): adding srt and vtt support for audio transcriptions.

* chore: refactoring

* chore: fix import format

---------

Co-authored-by: Tomer Aberbach &lt;tomer@stainless.com&gt;
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt b/openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt
@@ -142,6 +142,17 @@ class AudioResponseFormat @JsonCreator private constructor(private val value: Js
      */
     @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1
 
+    @JvmSynthetic
+    internal fun isJson(): Boolean =
+        when (this) {
+            JSON -> true
+            TEXT -> false
+            SRT -> false
+            VERBOSE_JSON -> true
+            VTT -> false
+            else -> false
+        }
+
     override fun equals(other: Any?): Boolean {
         if (this === other) {
             return true
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt
@@ -9,10 +9,12 @@ import com.openai.core.handlers.errorHandler
 import com.openai.core.handlers.jsonHandler
 import com.openai.core.handlers.mapJson
 import com.openai.core.handlers.sseHandler
+import com.openai.core.handlers.stringHandler
 import com.openai.core.handlers.withErrorHandler
 import com.openai.core.http.AsyncStreamResponse
 import com.openai.core.http.HttpMethod
 import com.openai.core.http.HttpRequest
+import com.openai.core.http.HttpResponse
 import com.openai.core.http.HttpResponse.Handler
 import com.openai.core.http.HttpResponseFor
 import com.openai.core.http.StreamResponse
@@ -22,10 +24,12 @@ import com.openai.core.http.parseable
 import com.openai.core.http.toAsync
 import com.openai.core.prepareAsync
 import com.openai.models.ErrorObject
+import com.openai.models.audio.transcriptions.Transcription
 import com.openai.models.audio.transcriptions.TranscriptionCreateParams
 import com.openai.models.audio.transcriptions.TranscriptionCreateResponse
 import com.openai.models.audio.transcriptions.TranscriptionStreamEvent
 import java.util.concurrent.CompletableFuture
+import kotlin.jvm.optionals.getOrNull
 
 class TranscriptionServiceAsyncImpl internal constructor(private val clientOptions: ClientOptions) :
     TranscriptionServiceAsync {
@@ -58,9 +62,19 @@ class TranscriptionServiceAsyncImpl internal constructor(private val clientOptio
 
         private val errorHandler: Handler<ErrorObject?> = errorHandler(clientOptions.jsonMapper)
 
-        private val createHandler: Handler<TranscriptionCreateResponse> =
+        private val createJsonHandler: Handler<TranscriptionCreateResponse> =
             jsonHandler<TranscriptionCreateResponse>(clientOptions.jsonMapper)
                 .withErrorHandler(errorHandler)
+        private val createStringHandler: Handler<TranscriptionCreateResponse> =
+            object : Handler<TranscriptionCreateResponse> {
+
+                private val stringHandler = stringHandler().withErrorHandler(errorHandler)
+
+                override fun handle(response: HttpResponse): TranscriptionCreateResponse =
+                    TranscriptionCreateResponse.ofTranscription(
+                        Transcription.builder().text(stringHandler.handle(response)).build()
+                    )
+            }
 
         override fun create(
             params: TranscriptionCreateParams,
@@ -81,9 +95,13 @@ class TranscriptionServiceAsyncImpl internal constructor(private val clientOptio
             return request
                 .thenComposeAsync { clientOptions.httpClient.executeAsync(it, requestOptions) }
                 .thenApply { response ->
+                    val handler =
+                        if (params.responseFormat().getOrNull()?.isJson() != false)
+                            createJsonHandler
+                        else createStringHandler
                     response.parseable {
                         response
-                            .use { createHandler.handle(it) }
+                            .use { handler.handle(it) }
                             .also {
                                 if (requestOptions.responseValidation!!) {
                                     it.validate()
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionServiceImpl.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionServiceImpl.kt
@@ -9,9 +9,11 @@ import com.openai.core.handlers.errorHandler
 import com.openai.core.handlers.jsonHandler
 import com.openai.core.handlers.mapJson
 import com.openai.core.handlers.sseHandler
+import com.openai.core.handlers.stringHandler
 import com.openai.core.handlers.withErrorHandler
 import com.openai.core.http.HttpMethod
 import com.openai.core.http.HttpRequest
+import com.openai.core.http.HttpResponse
 import com.openai.core.http.HttpResponse.Handler
 import com.openai.core.http.HttpResponseFor
 import com.openai.core.http.StreamResponse
@@ -20,9 +22,11 @@ import com.openai.core.http.multipartFormData
 import com.openai.core.http.parseable
 import com.openai.core.prepare
 import com.openai.models.ErrorObject
+import com.openai.models.audio.transcriptions.Transcription
 import com.openai.models.audio.transcriptions.TranscriptionCreateParams
 import com.openai.models.audio.transcriptions.TranscriptionCreateResponse
 import com.openai.models.audio.transcriptions.TranscriptionStreamEvent
+import kotlin.jvm.optionals.getOrNull
 
 class TranscriptionServiceImpl internal constructor(private val clientOptions: ClientOptions) :
     TranscriptionService {
@@ -52,9 +56,19 @@ class TranscriptionServiceImpl internal constructor(private val clientOptions: C
 
         private val errorHandler: Handler<ErrorObject?> = errorHandler(clientOptions.jsonMapper)
 
-        private val createHandler: Handler<TranscriptionCreateResponse> =
+        private val createJsonHandler: Handler<TranscriptionCreateResponse> =
             jsonHandler<TranscriptionCreateResponse>(clientOptions.jsonMapper)
                 .withErrorHandler(errorHandler)
+        private val createStringHandler: Handler<TranscriptionCreateResponse> =
+            object : Handler<TranscriptionCreateResponse> {
+
+                private val stringHandler = stringHandler().withErrorHandler(errorHandler)
+
+                override fun handle(response: HttpResponse): TranscriptionCreateResponse =
+                    TranscriptionCreateResponse.ofTranscription(
+                        Transcription.builder().text(stringHandler.handle(response)).build()
+                    )
+            }
 
         override fun create(
             params: TranscriptionCreateParams,
@@ -70,8 +84,11 @@ class TranscriptionServiceImpl internal constructor(private val clientOptions: C
             val requestOptions = requestOptions.applyDefaults(RequestOptions.from(clientOptions))
             val response = clientOptions.httpClient.execute(request, requestOptions)
             return response.parseable {
+                val handler =
+                    if (params.responseFormat().getOrNull()?.isJson() != false) createJsonHandler
+                    else createStringHandler
                 response
-                    .use { createHandler.handle(it) }
+                    .use { handler.handle(it) }
                     .also {
                         if (requestOptions.responseValidation!!) {
                             it.validate()
diff --git a/openai-java-example/src/main/java/com/openai/example/AudioTranscriptionsVttExample.java b/openai-java-example/src/main/java/com/openai/example/AudioTranscriptionsVttExample.java
@@ -0,0 +1,34 @@
+package com.openai.example;
+
+import com.openai.client.OpenAIClient;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+import com.openai.models.audio.AudioModel;
+import com.openai.models.audio.AudioResponseFormat;
+import com.openai.models.audio.transcriptions.Transcription;
+import com.openai.models.audio.transcriptions.TranscriptionCreateParams;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+public final class AudioTranscriptionsVttExample {
+    private AudioTranscriptionsVttExample() {}
+
+    public static void main(String[] args) throws Exception {
+        // Configures using one of:
+        // - The `OPENAI_API_KEY` environment variable
+        // - The `OPENAI_BASE_URL` and `AZURE_OPENAI_KEY` environment variables
+        OpenAIClient client = OpenAIOkHttpClient.fromEnv();
+
+        ClassLoader classloader = Thread.currentThread().getContextClassLoader();
+        Path path = Paths.get(classloader.getResource("sports.wav").toURI());
+
+        TranscriptionCreateParams createParams = TranscriptionCreateParams.builder()
+                .file(path)
+                .model(AudioModel.WHISPER_1)
+                .responseFormat(AudioResponseFormat.VTT)
+                .build();
+
+        Transcription transcription =
+                client.audio().transcriptions().create(createParams).asTranscription();
+        System.out.println(transcription.text());
+    }
+}
