JavaScript 음성 인식 튜토리얼: 음성 UX 구축 

Web Speech API와 같은 브라우저 네이티브 음성 텍스트 변환(STT) API 덕분에 이제 웹사이트와 브라우저 기반 앱에 음성 인식을 더 쉽게 도입할 수 있습니다. 개발자는 로컬 자동 음성 인식 서버를 구축하지 않고도 API 호출을 통해 마이크 입력을 스트리밍하고, 오디오 데이터를 분석하며, 트랜스크립트를 처리할 수 있습니다. 

Web Speech API는 JavaScript에서 음성 명령을 구현할 때 널리 사용되는 음성 인식 API입니다. 웹 브라우저에서 실시간 트랜스크립션을 실행할 수 있는 메서드, 인수, 속성을 제공합니다. 하지만 복잡한 웹 클라이언트에서는 Web Speech API의 기능이 제한적이라고 느낄 수 있습니다.

이 가이드에서는 Web Speech API로 간단한 JavaScript 음성 인식 웹 앱을 설정하는 방법과 그 한계, 그리고 더 강력한 실시간 트랜스크립션 클라이언트를 구축하기 위한 대안을 살펴봅니다. 

요약

• Web Speech API는 마이크 오디오를 처리하기 위해 백엔드 클라우드 서비스로 전송하는 브라우저 네이티브 음성 텍스트 변환 API입니다.
• 개발자는 SpeechRecognition API 클래스를 사용해 JavaScript 음성 명령 애플리케이션을 구축합니다. 
• 음성 인식 앱을 구축할 때는 오디오 녹음이 진행 중임을 표시하여 사용자 개인정보를 고려해야 합니다. 
• Web Speech API에는 트랜스크립션의 일관성 부족, 브라우저 의존성, 의도 이해 기능 부재 등 여러 한계가 있습니다. 
• ElevenLabs는 클라이언트 및 서버 측 스트리밍을 모두 지원하는 정확도 높은 프로덕션급 음성 텍스트 변환 API를 제공합니다. 

Web Speech API 작동 방식

Web Speech API는 로컬 서버 없이도 웹 개발자에게 브라우저 네이티브 음성 인식 기능을 제공합니다. 기본적으로 Web Speech API는 웹 브라우저의 오디오 스트림을 백엔드 클라우드 서비스로 보내 처리, 분석하고 트랜스크립트로 변환합니다. 트랜스크립션 실행을 브라우저의 백엔드 엔진에 의존하므로 브라우저마다 결과가 달라질 수 있습니다.

일반적으로 Web Speech API는 오디오 스트림을 트랜스크립션하려면 활성화된 인터넷 연결이 필요하며, 특히 Chrome과 Safari용으로 구축하는 경우 그렇습니다. 하지만 이제 일부 브라우저는 오프라인 트랜스크립션을 지원합니다. 오프라인 트랜스크립션에서는 브라우저가 음성 텍스트 변환 엔진 역할을 하며, 음소를 식별해 자연스러운 텍스트로 변환합니다. 

어떤 브라우저를 사용하든 API의 기본 원리는 동일합니다.

• API 요청을 수행하는 데 API 키는 필요하지 않습니다. 
• Web Speech API는 연속 발화와 단일 발화를 지원합니다. 
• 중간 트랜스크립트와 최종 트랜스크립트를 모두 반환합니다. 

하지만 브라우저마다 STT 엔진을 다르게 구현할 수 있으므로 정확도와 지연 시간은 달라질 수 있습니다.

Web Speech API를 사용하려면 JavaScript 코드에서 SpeechRecognition 인터페이스를 초기화합니다. 그런 다음 코드를 작성하면서 메서드, 속성, 이벤트 핸들러에 접근합니다. 다음은 음성 검색 웹 클라이언트를 구축할 때 사용할 항목입니다.

• SpeechRecognition.continuous: 음성 엔진이 true로 설정되면 연속 스트림을 처리하도록 합니다. 
• SpeechRecognition.lang: 오디오의 언어를 설정합니다. 
• SpeechRecognition.interimResults: 엔진에 중간 트랜스크립트를 반환하도록 지시합니다. 
• SpeechRecognition.start(): 음성 인식 프로세스를 시작합니다.
• SpeechRecognition.onresult: 트랜스크립션이 완료되면 API가 트리거하는 이벤트 핸들러를 받습니다. 

Web Speech API는 트랜스크립션을 문자열 배열로 반환합니다. STT 엔진이 중간 또는 최종 트랜스크립트를 반환하면 results 배열에서 찾을 수 있습니다. 하나 이상의 문자열을 반환할 수 있으므로 모든 트랜스크립션 텍스트를 가져오려면 결과 문자열을 순회해야 합니다. 

참고: 중간 트랜스크립션을 활성화했다면 isFinal 속성을 확인해 텍스트가 최종 트랜스크립트인지 판단합니다. 

JavaScript 음성 인식 예제 구축 

이 예제에서는 JavaScript SpeechRecognition 인터페이스를 사용해 실시간 트랜스크립션 웹 앱을 구축합니다. 아래 스크린샷은 완성된 페이지를 보여 줍니다.

예제 페이지에서 듣기 시작 버튼을 누르면 녹음이 시작됩니다. 사용자가 말하면 브라우저는 오디오를 STT 엔진으로 전송하고 트랜스크립션을 기다린 뒤 중간 텍스트와 최종 텍스트를 모두 표시합니다.

이 예제에는 사용자가 지정한 특정 용어를 포착하는 음성 명령 기능도 포함되어 있습니다. 자체 코드에서 트랜스크립트를 미리 정해 둔 구문 목록과 비교하며, 이는 음성 텍스트 변환 API의 키워드 프롬프팅과는 다릅니다. 

아래 코드 조각은 이 예제의 핵심 부분을 보여 줍니다.

SpeechRecognition API 설정 및 마이크 액세스 요청 

코드에서 사용하려면 먼저 SpeechRecognition 클래스를 인스턴스화해야 합니다. 이전 버전의 Chrome 또는 Safari를 사용한다면 webkitSpeechRecognition을 참조합니다.

const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;

그런 다음 SpeechRecognition 인스턴스를 만들고 스트리밍 모드, 중간 트랜스크립션 지원, 음성 언어를 구성합니다. 

recognition = new SpeechRecognition();
recognition.continuous = true;
recognition.interimResults = true;
recognition.lang = language.value;

이후 .start() 메서드를 호출해 트랜스크립션을 시작할 수 있습니다. 

recognition.start();

음성 인식 프로세스를 처음 시작하면 브라우저가 사용자에게 권한을 요청합니다. 트랜스크립션을 시작하려면 사용자가 허용을 클릭해야 합니다. 그렇지 않으면 API가 SpeechRecognitionErrorEvent 핸들러에서 "not-allowed” 값을 반환합니다. 

실시간 트랜스크립트 및 최종 결과 표시 

이 예제에서는 사용자가 마이크에 말하는 동안 트랜스크립트를 표시합니다. 이를 위해 onresult 이벤트에 함수를 추가합니다. 

recognition.onresult = (event) => {
  let interim = "";

  for (let index = event.resultIndex; index < event.results.length; index += 1) {
    const result = event.results[index][0].transcript;
    if (event.results[index].isFinal) text += `${result.trim()} `;
    else interim += result;
  }

  capturePhrases();
  render(interim);
};

중간 트랜스크립트는 확정된 결과가 아닙니다. 따라서 표시되는 텍스트가 실제로 말한 단어와 정확히 일치하지 않을 수 있습니다. STT 엔진은 이후 단어에서 더 많은 문맥을 받으면 트랜스크립트를 수정하고 문자열로 반환합니다. 

중간 텍스트가 최종 트랜스크립트와 구분되도록 다른 색상으로 스타일을 지정할 수도 있습니다. 다음 CSS가 이를 수행합니다:

#transcript .final { color: var(--ink); }
#transcript .interim { color: var(--accent); }

JavaScript에서 음성 명령 추가 

사용자가 감지할 구문을 세미콜론으로 구분하여 입력할 수 있는 텍스트 상자를 추가합니다. (또는 구문을 JSON 파일에 저장하고 코드로 불러올 수도 있습니다.)

그런 다음 최종 트랜스크립트를 구문 목록과 비교하는 함수를 만듭니다. 텍스트를 일치시킬 때는 두 목록을 모두 소문자로 변환해 정규화합니다. 사용자가 단어를 대문자로 입력할 수 있으며, 같은 단어라도 불일치가 발생할 수 있기 때문입니다. 예를 들어 “Hello World”와 “hello world”는 한쪽에 대문자가 있더라도 일치해야 합니다. 

function capturePhrases() {
  const lowerText = text.toLocaleLowerCase();
  getTargetPhrases().forEach((phrase) => {
    if (lowerText.includes(phrase.toLocaleLowerCase()) && !capturedPhrases.includes(phrase)) {
      capturedPhrases.push(phrase);
      const item = document.createElement("li");
      item.textContent = phrase;
      capturedText.append(item);
    }
  });
  capturedResult.classList.toggle("visible", capturedPhrases.length > 0);
}

코드가 트랜스크립트를 받을 때마다 구문 목록을 순회합니다. 일치하는 항목이 있으면 애플리케이션을 실행하거나, 이 경우처럼 일치한 구문을 별도 패널에 표시하는 등의 작업을 트리거합니다. 

브라우저 지원, 권한 및 인식 오류 처리 

Web Speech API는 JavaScript에서 음성 텍스트 변환 인식을 쉽게 실행할 수 있게 해 주지만, 항상 문제없이 작동하는 것은 아닙니다. 사용자는 SpeechRecognition API에 대한 백엔드 지원이 제한적이거나 전혀 없는 브라우저를 사용할 수 있습니다. 경우에 따라 네트워크 문제로 트랜스크립션에 실패할 수 있습니다.

따라서 코드에서 이러한 상황을 처리하고 그에 맞게 사용자에게 알려야 합니다. 

예를 들어 SpeechRecognition API가 정상 작동하는 것으로 검증된 Chrome 또는 Edge를 사용하도록 사용자에게 안내합니다.

if (!SpeechRecognition) {
  toggleButton.disabled = true;
  notice.textContent = "Speech recognition is not supported. Try Chrome or Edge.";
  notice.classList.add("visible");
} else {

한편 오류를 처리하려면 오류 처리 함수를 onerror 이벤트 핸들러에 연결하고 각 오류 코드를 처리합니다. 

예: 

recognition.onerror = (event) => {
  const messages = {
    "not-allowed": "Microphone access was blocked. Allow it in browser settings and try again.",
    "no-speech": "No speech was detected. Try speaking closer to the microphone.",
    network: "The speech recognition service could not connect. Check your internet connection.",
    aborted: "Speech recognition was stopped."
  };
  notice.textContent = messages[event.error] || `Recognition error: ${event.error}.`;
  if (event.error !== "aborted") notice.classList.add("visible");
  listening = false;
  toggleButton.textContent = "Start listening";
  statusText.textContent = "Error";
  status.classList.remove("listening");
};

JavaScript 음성 인식을 접근 가능하고 개인정보를 고려한 방식으로 만들기 

Web Speech API를 통합할 때는 개인정보 보호를 염두에 두어야 합니다. 웹 클라이언트가 녹음을 시작하기 전에 항상 시각적 또는 음성 표시를 제공합니다. 예를 들어 JavaScript 음성 인식 코드가 마이크 신호를 음성 텍스트 변환 엔진으로 활발히 전송하는 동안, 시각적 신호로 듣기 아이콘을 표시합니다. 

개발자가 주의를 기울여야 할 또 다른 영역은 데이터 개인정보 보호입니다. SpeechRecognition API로 트랜스크립션하면 API는 기본적으로 온라인에서 트랜스크립션을 수행합니다. 브라우저가 오프라인 음성 텍스트 변환을 지원하더라도 API는 먼저 온라인 트랜스크립션을 시도합니다. 

데이터 레지던시, 거버넌스, 규정 준수가 엄격하게 규제되는 트랜스크립션 서비스를 구축할 때 이러한 기술 사양은 매우 중요합니다. 

프로덕션 환경에서 브라우저 음성 인식만으로 부족한 경우 

Web Speech API를 사용해 브라우저 기반 음성 앱용 자동 음성 인식을 구축하는 단계를 살펴봤습니다. 이 API는 JavaScript 개발자가 음성 텍스트 변환 기능을 쉽게 이용할 수 있게 합니다. 하지만 여러 한계로 인해 특히 상용 웹 제품에서 활용 사례가 제한됩니다. 

• 브라우저 의존성: 트랜스크립션은 사용자의 브라우저에 크게 의존합니다. 개발자는 사용되는 특정 음성 모델을 제어할 수 없으므로 트랜스크립션 성능이 일관되지 않습니다. 
• 제한된 언어 지원: API는 40개 이상의 언어를 지원하지만 정확한 수는 브라우저마다 다를 수 있습니다.
• 화자 분리: 누가 말하는지 감지하거나 트랜스크립트에 개별 화자를 반영할 수 없습니다. 
• 사용자 지정 어휘: SpeechRecognition API는 사용자 지정 어휘를 안정적으로 지원하지 않습니다. 예를 들어 “ElevenLabs”를 정확하게 트랜스크립션하지 못합니다. (공식 SpeechRecognition API는 SpeechGrammarList를 사용한 사용자 지정 어휘 인터페이스를 제공하지만, 최신 브라우저는 이를 무시하는 경우가 많습니다.)

• 정확도: 화자가 소음이 많은 환경에 있거나 억양이 강하거나 마이크에서 멀리 떨어져 있으면 트랜스크립션 정확도가 떨어집니다. 
• 서버 측 스트리밍: Web Speech API는 서버 스트리밍 또는 수동 오디오 파일 업로드를 지원하지 않으므로 마이크에서만 스트리밍할 수 있습니다. 

이러한 한계로 음성 인식 제품의 상용화가 어렵다면 ElevenLabs Scribe v2 Realtime 사용을 권장합니다. 

ElevenLabs Scribe v2 Realtime은 높은 정확도의 150ms 미만 지연 시간의 실시간 트랜스크립션을 제공하는 음성 인식 모델입니다. 90개 이상의 언어, 브라우저에 구애받지 않는 일관성, 사용자 지정 어휘를 지원합니다. ElevenLabs Scribe v2 Realtime을 사용하면 웹 앱 아키텍처에 맞춰 클라이언트 또는 서버 측 스트리밍을 실행할 수 있습니다. 

ElevenLabs Scribe v2 Realtime을 활용한 JavaScript 음성 인식 튜토리얼  

ElevenLabs로 JavaScript 음성 명령을 구축하는 방식도 비슷합니다. 다만 API 요청을 인증하려면 ElevenLabs API 키를 만들어야 합니다. 아래에서 마이크로부터 스트리밍하는 웹 클라이언트를 만드는 빠른 단계를 확인해 보세요. 

1. ElevenLabs SDK 설치

npm install @elevenlabs/client @elevenlabs/elevenlabs-js

2. API 키를 노출하지 않고 전달할 수 있도록 일회용 토큰 생성

// Node.js server
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

app.get("/scribe-token", yourAuthMiddleware, async (req, res) => {
  const token = await elevenlabs.tokens.singleUse.create("realtime_scribe");

  res.json(token);
});

3. 원하는 매개변수로 Scribe v2 Realtime 모델 구성 및 연결

// Client side
import { Scribe, RealtimeEvents } from "@elevenlabs/client";

// Ensure you have authentication headers set up
const response = await fetch("/scribe-token", yourAuthHeaders);
const { token } = await response.json();

const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  includeTimestamps: true,
  microphone: {
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});
// Client side
import { Scribe, RealtimeEvents } from "@elevenlabs/client";

// Ensure you have authentication headers set up
const response = await fetch("/scribe-token", yourAuthHeaders);
const { token } = await response.json();

const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  includeTimestamps: true,
  microphone: {
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});

4. 트랜스크립트 처리 및 예외 처리를 위한 이벤트 핸들러 생성

// Set up event handlers

// Session started
connection.on(RealtimeEvents.SESSION_STARTED, () => {
  console.log("Session started");
});

// Partial transcripts (interim results), use this in your UI to show the live transcript
connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => {
  console.log("Partial:", data.text);
});

// Committed transcripts
connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
  console.log("Committed:", data.text);
});

// Committed transcripts with word-level timestamps. Only received when includeTimestamps is set to true.
connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS, (data) => {
  console.log("Committed:", data.text);
  console.log("Timestamps:", data.words);
});

// Errors - will catch all errors, both server and websocket specific errors
connection.on(RealtimeEvents.ERROR, (error) => {
  console.error("Error:", error);
});

// Connection opened
connection.on(RealtimeEvents.OPEN, () => {
  console.log("Connection opened");
});

// Connection closed
connection.on(RealtimeEvents.CLOSE, () => {
  console.log("Connection closed");
});

// When you are done, close the connection
connection.close();

Scribe v2 Realtime에 관한 자세한 안내는 공식 문서에서 확인하세요. 

프로덕션 음성 텍스트 변환을 위한 ElevenAPI 시작하기 

ElevenAPI는 웹 클라이언트 및 서버 개발을 위한 프로덕션급 음성 텍스트 변환 모델을 제공합니다. 개발자는 실시간 음성 인식뿐 아니라 ElevenAPI 음성 텍스트 변환 모델을 사용해 화자 분리, 단어 수준 타임스탬프, 비동기 처리를 지원하는 일괄 트랜스크립션을 구현할 수 있습니다. 

음성 텍스트 변환 엔진을 계속 폴링하는 대신 ElevenLabs 대시보드에서 웹훅을 만들고 콜백 URL을 제공할 수 있습니다. 그러면 API가 완료된 트랜스크립트를 해당 URL로 전달합니다. 

자동 음성 인식을 활용한 웹 클라이언트나 서버 앱을 구축하려는 경우, ElevenAPI는 코드에 쉽게 통합할 수 있는 오디오 모델을 제공합니다. 

ElevenLabs API 키를 받고 API 문서 살펴보기를 통해 개발을 시작하세요. 

자주 묻는 질문