音声認識（STT）

音声入力は init() の auto_send オプションによって2つの方式で動作します。まずどの入力方式を使用するか選択してください。

入力方式の選択

方式	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 を前提としています。