OpenAI의 API를 사용한 Java의 실시간 오디오 전사

Openai는 텍스트 모델에 두 가지 새로운 연설을 시작했습니다 gpt-4o-mini-transcribe 그리고 gpt-4o-transcribe 2025 년 3 월.이 모델은 완성 된 오디오 및 진행중인 오디오 모두에 대한 스트리밍 전사를 지원합니다. 오디오 전사는 오디오 입력을 텍스트 출력으로 변환하는 것을 말합니다 (출력 형식은 텍스트 또는 JSON). 이미 완성 된 오디오의 전사는 OpenAI가 제공 한 전사 API를 사용하여 훨씬 간단합니다.

실시간 전사는 음성 보조원, 라이브 캡션, 대화식 음성 응용 프로그램, 전사 및 접근성 도구 충족과 같은 즉각적인 피드백이 필요한 응용 프로그램에 유용합니다. OpenAI는 실시간 전사 API (현재 베타 버전)를 제공하여 오디오 데이터를 스트리밍하고 실시간으로 전사 결과를받을 수 있습니다. WebSocket 또는 WebRTC를 사용하여 실시간 전사 API를 호출해야합니다. 이 기사는 Java Websocket 구현을 사용하여 실시간 API를 호출하는 데 중점을 둡니다.

이 이미지는 flaticon.com의 리소스를 사용하여 설계되었습니다

Websockets는 무엇입니까?

Websockets는 클라이언트와 서버 간의 지속적인 통신에 유용한 양방향 통신 프로토콜입니다. 이는 요청 응답 형식을 따르는 HTTP와 다르며 클라이언트는 서비스로부터 응답을 얻으려면 주문을 주문 제출해야합니다. Websockets는 클라이언트와 서버 간의 2 웨이 커뮤니케이션을 허용하는 단일의 긴 살아있는 TCP 연결을 만듭니다. 실시간 오디오 전사에서 클라이언트는 오디오 청크를 사용할 수있게되면 보냅니다. OpenAI API는 처리시 전사 결과를 반환합니다.

WebSocket 방법

OnOpen():이 메소드는 WebSocket 연결이 설정되면 호출됩니다.
onMessage():이 메소드는 클라이언트가 서버로부터 메시지를받을 때 호출됩니다. 여기에서 오류를 감지하고 전사 응답을 처리하기 위해 핵심 논리를 추가해야합니다.
onClose():이 메소드는 WebSocket 클라이언트가 닫히면 호출됩니다. 클라이언트와 서버가 WebSocket 연결을 닫을 수 있습니다.
onError():이 메소드는 WebSocket에서 오류가 발생하면 호출됩니다. WebSocket은 오류 후 항상 연결을 닫습니다.

구현

Java 프로젝트에서 Java-Websocket 의존성을 귀하의 pom.xml 파일. MVN 저장소에서 최신 안정 버전을 선택하십시오.



    org.java-websocket
    Java-WebSocket
    1.6.0

두 수업 만들기 : SimpleOpenAITranscription 그리고 TranscriptionWebSocketClient. TranscriptionWebSocketClient에는 WebSocket 클라이언트 구현이 포함됩니다. SimpleOpenAITranscription 오디오 스트리밍 및 전사를 조정하는 주요 방법이 포함됩니다. 아래 코드 예제에서는 그들이 속한 클래스를 지정했습니다.

OpenAI의 API에 WebSocket 연결을 설정하십시오

OpenAI API는 인증을 위해 API 키를 사용합니다. API 키를 만들려면 OpenAI 계정에 로그인하고 조직 설정으로 이동하십시오. 연결은 호출하여 설정됩니다 client.connect() 주요 방법에서. WebSocket URL입니다 wss://api.openai.com/v1/realtime?intent=transcription

//TranscriptionWebSocketClient
// Set the request headers
private static class TranscriptionWebSocketClient extends WebSocketClient {
  public TranscriptionWebSocketClient(URI serverUri) {
  super(serverUri, createHeaders());
  }

  private static Map createHeaders() {
    Map headers = new HashMap();
    headers.put("Authorization", "Bearer " + API_KEY);
    headers.put("openai-beta", "realtime=v1");
    return headers;
    }
}

//SimpleOpenAITranscription

TranscriptionWebSocketClient client = new TranscriptionWebSocketClient(new URI(WEBSOCKET_URL));
client.connect();

// Wait until websocket connection is established
while (!client.isOpen()) {
    System.out.println("Websocket is not open.");
    Thread.sleep(100);
}

전사 세션을 설정하십시오

전사 세션을 작성하는 동안 구성 메시지가 필요합니다. 구성의 모델 이름도있을 수 있습니다 gpt-4o-transcribe 또는 gpt-4o-mini-transcribe 응용 프로그램 요구 사항을 기반으로합니다. 그만큼 language (예 : “en”, “fr”, “ko”)는 선택적 필드이지만 지정된 경우 정확도를 향상시킵니다. 그만큼 turn_detection 필드는 음성 활동 감지 (VAD)를 설정하는 데 사용됩니다. VAD가 활성화되면 OpenAI는 오디오의 침묵을 자동으로 감지하고 오디오 메시지를 커밋합니다. 일단 커밋되면 서버는 전사 결과로 응답합니다. 단순성을 위해 VAD를 비활성화했습니다.

// SimpleOpenAITranscription
client.sendInitialConfig();

//TranscriptionWebSocketClient

public void sendInitialConfig() {
  JSONObject config = new JSONObject()
  .put("type", "transcription_session.update")
  .put("session", new JSONObject()
  .put("input_audio_format", "pcm16")
  .put("input_audio_transcription", new JSONObject()
  .put("model", "gpt-4o-transcribe")
  .put("language", "en")) 
  .put("turn_detection", JSONObject.NULL)
  .put("input_audio_noise_reduction", new JSONObject()
  .put("type", "near_field")));
  send(config.toString());
}

청크로 오디오 데이터를 스트리밍합니다

오디오 청크는“input_audio_buffer.append“메시지 유형. VAD가 비활성화되면 전사 결과를 받으려면 메시지를 수동으로 커밋해야합니다.

//SimpleOpenAITranscription
File audioFile = new File(args[0]);
AudioInputStream audioInputStream = AudioSystem.getAudioInputStream(audioFile);

byte[] buffer = new byte[CHUNK_SIZE];
int bytesRead;

while ((bytesRead = audioInputStream.read(buffer)) != -1) {
    client.sendAudioChunk(buffer, bytesRead);
}

client.commitAndClearBuffer();

//TranscriptionWebSocketClient
public void sendAudioChunk(byte[] buffer, int bytesRead) {
    // Create a new byte array with only the read bytes
    byte[] audioData = Arrays.copyOf(buffer, bytesRead);
    String base64Audio = Base64.getEncoder().encodeToString(audioData);
    JSONObject audioMessage = new JSONObject()
        .put("type", "input_audio_buffer.append")
        .put("audio", base64Audio);
    send(audioMessage.toString());
}

public void commitAndClearBuffer() {
    send(new JSONObject().put("type", "input_audio_buffer.commit").toString());
    send(new JSONObject().put("type", "input_audio_buffer.clear").toString());
}

실시간으로 응답을 받고 처리합니다

클라이언트는 서버로부터 메시지를 사용하여 메시지를받습니다 onMessage() WebSocket의 방법. 성적표가 있습니다 conversation.item.input_audio_transcription.completed 메시지 유형. 응용 프로그램은 이러한 이벤트를 듣고 사용자에게 전사 응답을 표시해야합니다.

//TranscriptionWebSocketClient
@Override
public void onMessage(String message) {
    System.out.println("message: " + message);
    JSONObject response = new JSONObject(message);
    if ("conversation.item.input_audio_transcription.completed".equals(response.get("type"))) {
        System.out.println("Transcription: " + response.getString("transcript"));
        this.close();
    }
}

이들은 추적하는 데 도움이되는 다른 응답 유형입니다.

transcription_session.created: 세션이 만들어졌습니다.
transcription_session.updated: 세션은 구성 페이로드를 기반으로 업데이트됩니다.
input_audio_buffer.committed: 오디오는 클라이언트가 커밋했습니다.
conversation.item.input_audio_transcription.delta: 서버에서받은 부분 전사.

응용 프로그램을 개선하기위한 팁

전사 세션을 더 잘 추적하려면 a sessionCreatedLatch 그리고 streamLatch CountdownLatch 유형의 변수. SessionCreatedLatch를 사용하여 오디오 보내기를 기다릴 때까지transcription_session.created”이벤트가 접수됩니다. 사용하십시오 streamLatch 클라이언트가 모든 이벤트를 보냈고 모든 전사를 다시받을 때까지 오디오 스트림을 열어두기 위해.
VAD (Voice Activity Detection) 기능은 스피치 턴의 시작 및 끝을 자동으로 감지합니다. 사용시 server_vad VAD 모드, 조정해야 할 수도 있습니다 silence_duration_ms 오디오의 침묵이 잘못 식별되는 경우.
응용 프로그램에서 API 키를 하드 코딩하지 마십시오. AWS Secrets Manager를 사용하여 비밀을 저장할 수 있습니다.
VAD가 비활성화되면 입력 버퍼 한계를 초과하지 않도록 정기 간격으로 오디오 버퍼를 커밋하고 명확하게하십시오.
이벤트 사이에 약간의 지연이 추가되면 연결이 압도적입니다. OpenAi 응답에는 연결이 압도 될 때 횡설수설 텍스트가 포함되어 있습니다.
오류 중에 리소스를 확보하기 위해 오류 중에 연결을 올바르게 닫습니다. WebSocket은 30 분에 연결됩니다.
OpenAI의 실시간 오디오 전사 기능이 적극적으로 개발되었으므로 업데이트에 대한 공식 공식 문서를 정기적으로 확인하십시오.