음성 인식 (STT)

음성 입력은 init()의 auto_send 옵션에 따라 두 가지 방식으로 동작합니다. 먼저 어떤 입력 방식을 사용할지 선택하세요.

입력 방식 선택

방식	InitOption	호출 흐름	사용자 발화 종료 처리
수동 전송 (기본)	auto_send: false	startListening() → 사용자 발화 → endListening()	앱이 endListening()으로 전송을 확정
자동 전송	auto_send: true	startListening()만 호출	서버가 사용자 발화 종료를 감지하고 자동으로 응답 요청

수동 전송 — auto_send: false (기본값)

startListening()으로 듣기를 시작하고, 사용자의 발화가 끝나면 앱이 endListening()을 호출해 전송을 확정합니다. 마이크 버튼을 누르고 있는 동안의 음성만 입력으로 처리하는 Push-to-Talk형 UI에 적합합니다.

// 듣기 시작 — 음성 인식 구간 시작
SDK.startListening();

// 사용자 발화가 끝나면 호출 — 전송이 확정되고 아바타가 응답
SDK.endListening();

자동 전송 — auto_send: true

음성 입력을 기본 인터페이스로 사용하는 아바타에 적합합니다. startListening()만 호출하면 되고, 사용자 발화의 종료 감지와 응답 요청은 서버가 자동으로 처리하므로 endListening()을 호출할 필요가 없습니다. 연결 완료 시 자동으로 듣기를 시작하려면 다음과 같이 작성합니다.

SDK.onStatus((status) => {
  if (status === 'CONNECTED_FINISH') {
    SDK.startListening(); // 이후 사용자 발화의 종료 감지와 응답 요청은 서버가 자동 처리
  }
});

SDK.init({
  sdk_key: 'YOUR_SDK_KEY',
  avatar_id: 'YOUR_AVATAR_ID',
  auto_send: true,
}).catch((e) => console.error(e.message));

startListening()

음성 인식 구간을 시작합니다. 마이크 자체는 enable_microphone: true(기본값)면 연결 시점부터 켜져 있습니다. startListening()은 이 구간의 음성을 입력으로 처리하도록 서버에 알리는 동작이며, 이전에 endListening()·cancelListening()으로 비활성화된 마이크 트랙이 있으면 다시 활성화합니다. 자동 전송(auto_send: true) 모드에서는 이 호출 하나로 음성 대화가 시작됩니다.

SDK.startListening();

endListening()

수동 전송(auto_send: false) 모드에서 음성 인식 구간을 종료하고 마이크 트랙을 비활성화하며, 전송을 확정합니다. 인식 결과는 STT_RESULT 시그널로 전달되며, stt_only=false인 경우 해당 결과를 바탕으로 아바타가 응답합니다. 자동 전송(auto_send: true) 모드에서는 호출할 필요가 없습니다.

SDK.endListening();

cancelListening()

음성 인식을 취소하고 마이크를 비활성화합니다. 인식된 텍스트를 폐기하고 아바타가 응답하지 않습니다. 수동·자동 전송 양쪽 모드 모두에서 호출할 수 있습니다.

SDK.cancelListening();

stt_only 옵션

stt_only: true로 초기화하면 아바타가 응답하지 않고 STT 인식 결과(STT_RESULT 시그널)만 전달됩니다. 기본값은 false이며, 이 경우 STT 결과 전달 후 아바타 응답이 이어집니다. auto_send와 독립적인 옵션이므로 두 입력 방식 모두와 조합할 수 있습니다.

한편 enable_microphone: false로 초기화하면 마이크 권한을 요청하지 않으므로 음성 입력 자체를 사용할 수 없습니다.

STT 관련 시그널

STT 세션과 발화 구간은 별개입니다

startListening() / endListening()은 음성 인식 구간(듣기 구간)을 제어합니다. 마이크 자체는 enable_microphone: true면 연결 시점부터 켜져 있으며, endListening()·cancelListening() 호출 시 마이크 트랙이 비활성화되고 startListening() 호출 시 다시 활성화됩니다. USER_SPEECH_STARTED / USER_SPEECH_STOPPED는 서버가 감지한 발화 구간이며, 마이크가 켜져 있는 동안에는 듣기 구간 밖(예: 연결 직후 startListening() 호출 전)에서도 수신될 수 있습니다. USER_SPEECH_STOPPED을 수신해도 듣기 구간은 종료되지 않습니다. 수동 전송 모드에서는 endListening()을 호출해야 종료되며, 자동 전송 모드에서는 서버가 사용자 발화의 종료를 감지해 응답을 요청합니다.

SDK.onSignal((data) => {
  switch (data.signal) {
    case 'USER_SPEECH_STARTED':
      // 사용자가 말하기 시작 (마이크는 이미 켜져 있음)
      console.log('사용자 발화 시작');
      break;
    case 'USER_SPEECH_STOPPED':
      // 사용자가 말을 멈춤 (마이크는 여전히 켜져 있음)
      console.log('사용자 발화 종료');
      break;
    case 'STT_RESULT':
      console.log('인식 결과:', data.payload.text);
      break;
  }
});

전체 STT 흐름

수동 전송 (auto_send: false)

stt_only=false 기준입니다. 마이크는 연결 시점부터 켜져 있으므로 USER_SPEECH_* 시그널은 startListening() 호출 전에도 수신될 수 있습니다. 아래는 대표적인 흐름입니다.

자동 전송 (auto_send: true)

endListening() 호출 없이 서버가 사용자 발화의 종료를 감지해 응답까지 이어집니다. stt_only=false 기준입니다.