Soniox

Soniox

LangChain에서 Soniox 오디오 전사 로더를 시작하는 방법을 안내할게요.

출처: 문서

본문

설정

패키지를 설치하세요:

npm install @soniox/langchain

자격 증명

Soniox 콘솔에서 Soniox API 키를 받아 환경 변수로 설정하세요:

export SONIOX_API_KEY=your_api_key

사용법

기본 전사

SonioxAudioTranscriptLoader로 오디오 파일을 전사하고 LLM으로 요약을 생성하는 예제예요.

import { SonioxAudioTranscriptLoader } from "@soniox/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";

const audioFileUrl = "https://soniox.com/media/examples/coffee_shop.mp3";
const loader = new SonioxAudioTranscriptLoader(
  {
    audio: audioFileUrl,
  },
  {
    language_hints: ["en"],
    // Any other transcription parameters you find here
    // https://soniox.com/docs/stt/api-reference/transcriptions/create_transcription
  }
);

console.log(`Transcribing ${audioFileUrl}...`);
const docs = await loader.load();

const transcriptText = docs[0].pageContent;
console.log(`Transcript: ${transcriptText}`);

// Create a chain to summarize the transcript
const prompt = ChatPromptTemplate.fromTemplate(
  "Write a concise summary of the following speech:\n\n{transcript}"
);

const chain = prompt
  .pipe(new ChatOpenAI({ model: "gpt-5-mini" }))
  .pipe(new StringOutputParser());

const summary = await chain.invoke({ transcript: transcriptText });
console.log(summary);

바이너리 데이터에서 오디오를 전사할 수도 있어요:

// Fetch the file
const response = await fetch("https://github.com/soniox/soniox_examples/raw/refs/heads/master/speech_to_text/assets/coffee_shop.mp3");
const audioBuffer = await response.bytes(); // Uint8Array

const loader = new SonioxAudioTranscriptLoader({
    audio: audioBuffer,
})

const docs = await loader.load();
console.log(docs[0].pageContent); // Transcribed text

번역

감지된 모든 언어에서 대상 언어로 번역:

const loader = new SonioxAudioTranscriptLoader(
  {
    audio: audioFileUrl,
  },
  {
    translation: {
      type: "one_way",
      target_language: "fr",
    },
    language_hints: ["en"],
  }
);

const docs = await loader.load();

let originalText = "";
let translatedText = "";

for (const token of docs[0].metadata.tokens) {
  if (token.translation_status === "translation") {
    translatedText += token.text;
  } else {
    originalText += token.text;
  }
}

console.log(originalText);
console.log(translatedText);

two_way 번역 유형을 사용해 두 언어 간 동시 전사·번역도 할 수 있어요. Soniox 번역에 대해 자세히 알아보세요.

언어 힌트

Soniox는 60개 이상의 언어로 된 음성을 자동으로 감지하고 전사해요. 오디오에 나타날 가능성이 있는 언어를 알고 있다면 language_hints를 제공해 인식을 해당 언어 쪽으로 편향시켜 정확도를 개선할 수 있어요.

언어 힌트는 인식을 제한하지 않으며, 지정된 언어 쪽으로 모델을 편향시킬 뿐이고, 다른 언어가 존재하면 여전히 감지될 수 있어요.

const loader = new SonioxAudioTranscriptLoader(
  {
    audio: audioFileUrl,
  },
  {
    language_hints: ["en", "es"],
  }
);

const docs = await loader.load();

자세한 내용은 Soniox 언어 힌트 문서를 참고하세요.

화자 분리 (Speaker diarization)

화자 식별을 활성화해 서로 다른 화자를 구분하세요:

const loader = new SonioxAudioTranscriptLoader(
  {
    audio: audioFileUrl,
  },
  {
    enable_speaker_diarization: true,
  }
);

const docs = await loader.load();

// Access speaker information in the metadata
let currentSpeaker = null;
let output = "";
for (const token of docs[0].metadata.tokens) {
  if (currentSpeaker !== token.speaker) {
    currentSpeaker = token.speaker;
    output += `\nSpeaker ${currentSpeaker}: ${token.text.trimStart()}`;
  } else {
    output += token.text;
  }
}
console.log(output);

// Analyze the conversation
const prompt = ChatPromptTemplate.fromTemplate(
  `Analyze the following conversation between speakers.
Identify the intent of each speaker.

Conversation:
{conversation}`
);

const chain = prompt
  .pipe(new ChatOpenAI({ model: "gpt-5-mini" }))
  .pipe(new StringOutputParser());

const analysis = await chain.invoke({ conversation: output });
console.log(analysis);

언어 식별

자동 언어 감지 및 식별을 활성화하세요:

const loader = new SonioxAudioTranscriptLoader(
  {
    audio: audioFileUrl,
  },
  {
    enable_language_identification: true,
  }
);

정확도 향상을 위한 컨텍스트

전사 정확도를 개선하기 위해 도메인별 컨텍스트를 제공하세요:

const loader = new SonioxAudioTranscriptLoader(
  {
    audio: audioBuffer,
  },
  {
    context: {
      general: [
        { key: "industry", value: "healthcare" },
        { key: "meeting_type", value: "consultation" }
      ],
      terms: ["hypertension", "cardiology", "metformin"],
      translation_terms: [
        { source: "blood pressure", target: "presión arterial" },
        { source: "medication", target: "medicamento" }
      ]
    }
  }
);

자세한 내용은 Soniox 컨텍스트 문서를 참고하세요.

API 레퍼런스

생성자 매개변수

SonioxLoaderParams (필수)

매개변수 타입 필수 설명
audio Uint8Array | string 예 버퍼 또는 URL로 된 오디오 파일
audioFormat SonioxAudioFormat 아니요 오디오 파일 형식
apiKey string 아니요 Soniox API 키 (SONIOX_API_KEY 환경 변수 기본)
apiBaseUrl string 아니요 API 기본 URL (https://api.soniox.com/v1 기본)
pollingIntervalMs number 아니요 폴링 간격(ms) (최소: 1000, 기본: 1000)
pollingTimeoutMs number 아니요 폴링 타임아웃(ms) (기본: 180000)

SonioxLoaderOptions (선택)

매개변수 타입 설명
model SonioxTranscriptionModelId 사용할 모델 (기본: "stt-async-v4")
translation object 번역 구성
language_hints string[] 전사를 위한 언어 힌트
language_hints_strict boolean 엄격한 언어 힌트 적용
enable_speaker_diarization boolean 화자 식별 활성화
enable_language_identification boolean 언어 감지 활성화
context object 정확도 향상을 위한 컨텍스트

지원되는 옵션의 전체 목록은 문서를 참고하세요.

지원되는 오디오 형식

  • aac - Advanced Audio Coding
  • aiff - Audio Interchange File Format
  • amr - Adaptive Multi-Rate
  • asf - Advanced Systems Format
  • flac - Free Lossless Audio Codec
  • mp3 - MPEG Audio Layer III
  • ogg - Ogg Vorbis
  • wav - Waveform Audio File Format
  • webm - WebM Audio

반환 값

load() 메서드는 단일 Document 객체를 포함하는 배열을 반환해요:

type Document {
  pageContent: string, // The transcribed text
  metadata: SonioxTranscriptResponse // Full transcript with metadata
}

메타데이터에는 전사된 텍스트, 화자 정보(분리 활성화 시), 언어 정보(식별 활성화 시), 번역 데이터(번역 활성화 시), 타이밍 정보가 포함돼요.

type SonioxTranscriptResponse = {
  id: string;
  text?: string | null;
  tokens?: SonioxTranscriptToken[] | null;
}

토큰 타입:

type SonioxTranscriptToken = {
  text: string;
  start_ms?: number | null;
  end_ms?: number | null;
  confidence?: number | null;
  speaker?: number | string | null;
  language?: string | null;
  translation_status?: string | null;
};

SonioxTranscriptResponse 타입에 대해 더 자세히 알아보려면 Soniox REST API 레퍼런스를 참고하세요.

관련 자료

[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/document_loaders/web_loaders/soniox.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).

더 알아보기