Re: [PR] CAMEL-23390: Add audio transcription support to camel-openai [camel]

["gnodet (via GitHub)" <gi...@apache.org>]

gnodet commented on code in PR #22872:
URL: https://github.com/apache/camel/pull/22872#discussion_r3180467232


##########
test-infra/camel-test-infra-openai-mock/src/main/java/org/apache/camel/test/infra/openai/mock/AudioTranscriptionResponseBuilder.java:
##########
@@ -0,0 +1,38 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.test.infra.openai.mock;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+/**
+ * Builder class for creating OpenAI audio transcription API mock responses.
+ */
+public class AudioTranscriptionResponseBuilder {
+    private final ObjectMapper objectMapper;
+
+    public AudioTranscriptionResponseBuilder(ObjectMapper objectMapper) {
+        this.objectMapper = objectMapper;
+    }
+
+    public String createTranscriptionResponse(AudioTranscriptionExpectation expectation) throws Exception {
+        record TranscriptionResponse(String text) {

Review Comment:
   nit: The project conventions say "Do NOT use Records or Lombok (unless already present in the file)." This is a new file in `test-infra` (not production API), and it's a local record inside a method body, so the risk is very low. Just flagging for awareness — could be replaced with a simple `Map` or inline JSON string if strict compliance is preferred.
   ```suggestion
           String json = String.format("{\"text\":\"%s\"}", expectation.getTranscriptionText());
           return json;
   ```



##########
components/camel-ai/camel-openai/src/main/java/org/apache/camel/component/openai/OpenAIAudioTranscriptionProducer.java:
##########
@@ -0,0 +1,162 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.component.openai;
+
+import java.io.ByteArrayInputStream;
+import java.io.File;
+import java.io.InputStream;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+import com.openai.core.MultipartField;
+import com.openai.models.audio.AudioResponseFormat;
+import com.openai.models.audio.transcriptions.TranscriptionCreateParams;
+import com.openai.models.audio.transcriptions.TranscriptionCreateResponse;
+import com.openai.models.audio.transcriptions.TranscriptionVerbose;
+import org.apache.camel.Exchange;
+import org.apache.camel.Message;
+import org.apache.camel.WrappedFile;
+import org.apache.camel.support.DefaultProducer;
+import org.apache.camel.util.ObjectHelper;
+
+/**
+ * OpenAI producer for audio transcription.
+ */
+public class OpenAIAudioTranscriptionProducer extends DefaultProducer {
+
+    public OpenAIAudioTranscriptionProducer(OpenAIEndpoint endpoint) {
+        super(endpoint);
+    }
+
+    @Override
+    public OpenAIEndpoint getEndpoint() {
+        return (OpenAIEndpoint) super.getEndpoint();
+    }
+
+    @Override
+    public void process(Exchange exchange) throws Exception {
+        OpenAIConfiguration config = getEndpoint().getConfiguration();
+        Message in = exchange.getIn();
+
+        String model = resolveParameter(in, OpenAIConstants.AUDIO_MODEL, config.getAudioModel(), String.class);
+        if (model == null) {
+            throw new IllegalArgumentException(
+                    "Audio model must be specified via audioModel parameter or CamelOpenAIAudioModel header");
+        }
+
+        String language = resolveParameter(in, OpenAIConstants.AUDIO_LANGUAGE, config.getAudioLanguage(), String.class);
+        String responseFormat = resolveParameter(in, OpenAIConstants.AUDIO_RESPONSE_FORMAT,
+                config.getAudioResponseFormat(), String.class);
+        Double temperature = resolveParameter(in, null, config.getAudioTemperature(), Double.class);
+        String prompt = resolveParameter(in, null, config.getAudioPrompt(), String.class);
+        String timestampGranularities = resolveParameter(in, null, config.getAudioTimestampGranularities(), String.class);
+
+        TranscriptionCreateParams.Builder paramsBuilder = TranscriptionCreateParams.builder()
+                .model(model);
+
+        setFileInput(paramsBuilder, in);
+
+        if (ObjectHelper.isNotEmpty(language)) {
+            paramsBuilder.language(language);
+        }
+        if (ObjectHelper.isNotEmpty(prompt)) {
+            paramsBuilder.prompt(prompt);
+        }
+        if (ObjectHelper.isNotEmpty(responseFormat)) {
+            paramsBuilder.responseFormat(AudioResponseFormat.of(responseFormat));
+        }
+        if (temperature != null) {
+            paramsBuilder.temperature(temperature);
+        }
+        if (ObjectHelper.isNotEmpty(timestampGranularities)) {
+            List<TranscriptionCreateParams.TimestampGranularity> granularities = new ArrayList<>();
+            for (String g : timestampGranularities.split(",")) {
+                String trimmed = g.trim();
+                if (!trimmed.isEmpty()) {
+                    granularities.add(TranscriptionCreateParams.TimestampGranularity.of(trimmed));
+                }
+            }
+            if (!granularities.isEmpty()) {
+                paramsBuilder.timestampGranularities(granularities);
+            }
+        }
+
+        TranscriptionCreateParams params = paramsBuilder.build();
+        TranscriptionCreateResponse response = getEndpoint().getClient()
+                .audio().transcriptions().create(params);
+
+        Message out = exchange.getMessage();
+
+        if (response.isVerbose()) {

Review Comment:
   question: This `verbose_json` code path sets `AUDIO_DURATION` and `AUDIO_DETECTED_LANGUAGE` output headers, but the mock's `AudioTranscriptionResponseBuilder` always returns a simple `{"text": "..."}` response — it never produces a verbose response. So this branch is never exercised by any test.
   
   Would be good to add a test with `audioResponseFormat=verbose_json` to validate this path. The mock infrastructure already has `withDuration()` and `withLanguage()` on the builder — they just need a matching verbose response format in `AudioTranscriptionResponseBuilder`.



##########
components/camel-ai/camel-openai/src/main/java/org/apache/camel/component/openai/OpenAIAudioTranscriptionProducer.java:
##########
@@ -0,0 +1,162 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.component.openai;
+
+import java.io.ByteArrayInputStream;
+import java.io.File;
+import java.io.InputStream;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+import com.openai.core.MultipartField;
+import com.openai.models.audio.AudioResponseFormat;
+import com.openai.models.audio.transcriptions.TranscriptionCreateParams;
+import com.openai.models.audio.transcriptions.TranscriptionCreateResponse;
+import com.openai.models.audio.transcriptions.TranscriptionVerbose;
+import org.apache.camel.Exchange;
+import org.apache.camel.Message;
+import org.apache.camel.WrappedFile;
+import org.apache.camel.support.DefaultProducer;
+import org.apache.camel.util.ObjectHelper;
+
+/**
+ * OpenAI producer for audio transcription.
+ */
+public class OpenAIAudioTranscriptionProducer extends DefaultProducer {
+
+    public OpenAIAudioTranscriptionProducer(OpenAIEndpoint endpoint) {
+        super(endpoint);
+    }
+
+    @Override
+    public OpenAIEndpoint getEndpoint() {
+        return (OpenAIEndpoint) super.getEndpoint();
+    }
+
+    @Override
+    public void process(Exchange exchange) throws Exception {
+        OpenAIConfiguration config = getEndpoint().getConfiguration();
+        Message in = exchange.getIn();
+
+        String model = resolveParameter(in, OpenAIConstants.AUDIO_MODEL, config.getAudioModel(), String.class);
+        if (model == null) {
+            throw new IllegalArgumentException(
+                    "Audio model must be specified via audioModel parameter or CamelOpenAIAudioModel header");
+        }
+
+        String language = resolveParameter(in, OpenAIConstants.AUDIO_LANGUAGE, config.getAudioLanguage(), String.class);
+        String responseFormat = resolveParameter(in, OpenAIConstants.AUDIO_RESPONSE_FORMAT,
+                config.getAudioResponseFormat(), String.class);
+        Double temperature = resolveParameter(in, null, config.getAudioTemperature(), Double.class);
+        String prompt = resolveParameter(in, null, config.getAudioPrompt(), String.class);
+        String timestampGranularities = resolveParameter(in, null, config.getAudioTimestampGranularities(), String.class);

Review Comment:
   nit: `audioTemperature`, `audioPrompt`, and `audioTimestampGranularities` are resolved with `headerName = null`, which means they can only be set via endpoint configuration — unlike `audioModel`, `audioLanguage`, and `audioResponseFormat` which support header overrides at runtime.
   
   This asymmetry may be intentional (fewer headers to define), but it's not documented. The doc section "Audio Transcription Parameters" doesn't distinguish which parameters support header overrides. Consider either:
   - Adding header constants for these three as well (for consistency), or
   - Documenting in the adoc that only `audioModel`, `audioLanguage`, and `audioResponseFormat` can be overridden via headers.



##########
components/camel-ai/camel-openai/src/main/java/org/apache/camel/component/openai/OpenAIAudioTranscriptionProducer.java:
##########
@@ -0,0 +1,162 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.component.openai;
+
+import java.io.ByteArrayInputStream;
+import java.io.File;
+import java.io.InputStream;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+import com.openai.core.MultipartField;
+import com.openai.models.audio.AudioResponseFormat;
+import com.openai.models.audio.transcriptions.TranscriptionCreateParams;
+import com.openai.models.audio.transcriptions.TranscriptionCreateResponse;
+import com.openai.models.audio.transcriptions.TranscriptionVerbose;
+import org.apache.camel.Exchange;
+import org.apache.camel.Message;
+import org.apache.camel.WrappedFile;
+import org.apache.camel.support.DefaultProducer;
+import org.apache.camel.util.ObjectHelper;
+
+/**
+ * OpenAI producer for audio transcription.
+ */
+public class OpenAIAudioTranscriptionProducer extends DefaultProducer {
+
+    public OpenAIAudioTranscriptionProducer(OpenAIEndpoint endpoint) {
+        super(endpoint);
+    }
+
+    @Override
+    public OpenAIEndpoint getEndpoint() {
+        return (OpenAIEndpoint) super.getEndpoint();
+    }
+
+    @Override
+    public void process(Exchange exchange) throws Exception {
+        OpenAIConfiguration config = getEndpoint().getConfiguration();
+        Message in = exchange.getIn();
+
+        String model = resolveParameter(in, OpenAIConstants.AUDIO_MODEL, config.getAudioModel(), String.class);
+        if (model == null) {
+            throw new IllegalArgumentException(
+                    "Audio model must be specified via audioModel parameter or CamelOpenAIAudioModel header");
+        }
+
+        String language = resolveParameter(in, OpenAIConstants.AUDIO_LANGUAGE, config.getAudioLanguage(), String.class);
+        String responseFormat = resolveParameter(in, OpenAIConstants.AUDIO_RESPONSE_FORMAT,
+                config.getAudioResponseFormat(), String.class);
+        Double temperature = resolveParameter(in, null, config.getAudioTemperature(), Double.class);
+        String prompt = resolveParameter(in, null, config.getAudioPrompt(), String.class);
+        String timestampGranularities = resolveParameter(in, null, config.getAudioTimestampGranularities(), String.class);
+
+        TranscriptionCreateParams.Builder paramsBuilder = TranscriptionCreateParams.builder()
+                .model(model);
+
+        setFileInput(paramsBuilder, in);
+
+        if (ObjectHelper.isNotEmpty(language)) {
+            paramsBuilder.language(language);
+        }
+        if (ObjectHelper.isNotEmpty(prompt)) {
+            paramsBuilder.prompt(prompt);
+        }
+        if (ObjectHelper.isNotEmpty(responseFormat)) {
+            paramsBuilder.responseFormat(AudioResponseFormat.of(responseFormat));
+        }
+        if (temperature != null) {
+            paramsBuilder.temperature(temperature);
+        }
+        if (ObjectHelper.isNotEmpty(timestampGranularities)) {
+            List<TranscriptionCreateParams.TimestampGranularity> granularities = new ArrayList<>();
+            for (String g : timestampGranularities.split(",")) {
+                String trimmed = g.trim();
+                if (!trimmed.isEmpty()) {
+                    granularities.add(TranscriptionCreateParams.TimestampGranularity.of(trimmed));
+                }
+            }
+            if (!granularities.isEmpty()) {
+                paramsBuilder.timestampGranularities(granularities);
+            }
+        }
+
+        TranscriptionCreateParams params = paramsBuilder.build();
+        TranscriptionCreateResponse response = getEndpoint().getClient()
+                .audio().transcriptions().create(params);
+
+        Message out = exchange.getMessage();
+
+        if (response.isVerbose()) {
+            TranscriptionVerbose verbose = response.asVerbose();
+            out.setBody(verbose.text());
+            out.setHeader(OpenAIConstants.AUDIO_DURATION, verbose.duration());
+            out.setHeader(OpenAIConstants.AUDIO_DETECTED_LANGUAGE, verbose.language());
+        } else if (response.isTranscription()) {
+            out.setBody(response.asTranscription().text());
+        } else {
+            out.setBody(response.toString());
+        }
+
+        if (config.isStoreFullResponse()) {
+            exchange.setProperty(OpenAIConstants.RESPONSE, response);
+        }
+    }
+
+    private void setFileInput(TranscriptionCreateParams.Builder paramsBuilder, Message in) {
+        Object body = in.getBody();
+
+        if (body instanceof WrappedFile<?> wrappedFile) {
+            body = wrappedFile.getFile();
+        }
+
+        if (body instanceof File file) {
+            paramsBuilder.file(file.toPath());
+        } else if (body instanceof Path path) {
+            paramsBuilder.file(path);
+        } else if (body instanceof byte[] bytes) {
+            paramsBuilder.file(multipartWithFilename(new ByteArrayInputStream(bytes)));
+        } else if (body instanceof InputStream inputStream) {
+            paramsBuilder.file(multipartWithFilename(inputStream));
+        } else {
+            InputStream converted = in.getBody(InputStream.class);
+            if (converted == null) {
+                throw new IllegalArgumentException(
+                        "Unsupported body type for audio transcription: "
+                                                   + (body != null ? body.getClass().getName() : "null")
+                                                   + ". Supported: File, Path, InputStream, byte[]");
+            }
+            paramsBuilder.file(multipartWithFilename(converted));
+        }
+    }
+
+    private MultipartField<InputStream> multipartWithFilename(InputStream stream) {
+        return MultipartField.<InputStream> builder()
+                .value(stream)
+                .filename("audio")

Review Comment:
   question: The filename is hardcoded to `"audio"` with no extension. The OpenAI API itself handles this fine (content-type detection), but some OpenAI-compatible local servers may rely on the file extension to determine the audio format.
   
   Consider deriving the filename from the original `File`/`Path` name when available, or allowing it to be set via a header (e.g., `CamelOpenAIAudioFilename`). Not blocking — just a thought for broader compatibility.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org