> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# トラブルシューティング

> 文字起こしエラー、高レイテンシー、サーバーエラー

## Realtime STT (Auto) のトラブルシューティング

当社の `/stt/turns/websocket` エンドポイントは、ユーザーターンがモデルによって**自動的にファイナライズ**されるため、「Realtime STT (**Auto**)」と呼んでいます。

### Realtime STT (Auto): トランスクリプトエラー

<AccordionGroup>
  <Accordion title="トランスクリプトを正しく結合していますか？">
    `transcript` フィールドは **ターン内で累積的** です。各 `turn.update`、`turn.eager_end`、`turn.end` イベントには、これまでのターンの全文がすでに含まれています。

    最終的なトランスクリプトだけが必要な場合は、完了したターンごとに 1 つずつ、各 `turn.end` から `transcript` プロパティを取得してください。**`transcript` はそのまま連結してください。`strip()` で空白を取り除いたり、正規化したり、独自の区切り文字を追加してはいけません。**

    ```python theme={null}
    import json

    full_audio_transcript = ""
    turns: list[str] = []
    async for message in websocket:
        event = json.loads(message)
        if event["type"] == "turn.end":
            # transcripts across turns should be
            # concatenated without formatting!
            full_audio_transcript += event["transcript"]

            # per-turn transcript
            turns.append(event["transcript"])
    ```

    `turn.update` や `turn.eager_end` イベントのトランスクリプトを連結するのは、テキストの重複の典型的な原因です。各更新は累積的なので、それらを連結するとトランスクリプトの一部が繰り返されます。
    `turn.update` や `turn.eager_end` は、トランスクリプトのチャンクではなく、ターン状態の更新として扱ってください。

    最終トランスクリプトは `turn.end` のみから読み取ってください。
  </Accordion>

  <Accordion title="すべてのイベントをドレインしましたか？">
    セッションの音声をすべて送信し終えたら、`{"type": "close"}` を送信して、バッファリングされている音声をフラッシュし、残りのイベントを発行するようモデルに伝えます。モデルが完了すると、サーバーがソケットをクローズします。

    サーバーは文字起こしの精度を高めるために音声を一定量バッファします。close コマンドを送信しなかったり、メッセージの読み取りを早期に停止したりすると、バッファされた音声は処理されません。最後の 1 秒の音声を気にしないのであれば、これは問題ありません。

    ```python theme={null}
    await websocket.send(json.dumps({"type": "close"}))
    async for message in websocket:
        event = json.loads(message)
        if event["type"] == "turn.end":
            turns.append(event["transcript"])
            # do not stop reading from the websocket!
    print("server closed the connection")
    ```
  </Accordion>

  <Accordion title="サポートされている言語を使用していますか？">
    Ink 2 は現時点で英語のみをサポートしています。他言語の概念は持たず、すべてを英語として文字起こししようとします。
  </Accordion>

  <Accordion title="正しいサンプルレートとエンコーディングを使用していますか？">
    モデルは、接続時に宣言した `encoding` と `sample_rate` を使ってバイト列をデコードします。これらのパラメーターが正しくなくても、Cartesia のサーバーは **エラーを返さない場合があります**。

    パラメーターを検証するには、音声データを保存し、[ffplay](https://ffmpeg.org/ffplay.html) で再生してみてください:

    ```bash theme={null}
    # encoding=pcm_s16le
    # sample_rate=16000
    # 1 channel (the API expects mono)
    ffplay -f s16le -ar 16000 -ac 1 audio.raw

    # general format
    ffplay -f <encoding_without_pcm_prefix> -ar <sample_rate> -ac <num_channels_must_be_one> <file_path>
    ```

    再生がおかしく聞こえる場合 (かなり明らかにわかるはずです)、`encoding` か `sample_rate` がデータと一致していません。音声がきれいに再生されるように修正し、その同じ値を API に送ってください。

    適切なパラメータを見つけるには [STT 入力音声エンコーディング](/build-with-cartesia/capability-guides/stt-input-encodings) を参照してください。
  </Accordion>
</AccordionGroup>

### Realtime STT (Auto): 高レイテンシー

<AccordionGroup>
  <Accordion title="音声の送信を停止しましたか？">
    Cartesia の API は連続した音声ストリームを想定しています。
    音声の送信を停止すると、サーバーはユーザーが無音であると見なすのではなく、追加の音声チャンクが到着するのを待ちます。

    これは通常、ネットワークの遅延に対応するために望ましい挙動ですが、クライアントが音声入力をミュートしている間、無音 (すべてゼロ) を送信し続ける必要があることも意味します。
  </Accordion>

  <Accordion title="適切なエンドポイントを使用していますか？">
    プッシュ・トゥ・トーク型のアプリ (ユーザーがボタンを押している間に話すなど) を構築している場合や、所定のポイント (特定の評価など) でトランスクリプトを「フラッシュ」したい場合は、[リアルタイム STT (Manual)](/api-reference/stt/websocket) への切り替えを検討してください。

    ターン検出は、`turn.end` で運ばれる最終トランスクリプトに 0.5 秒程度の遅延を追加します。
    セットアップが許すなら、manual エンドポイントを使い、ユーザーの発話が終わった時点で `"finalize"` を送信することで、ターン検出によるレイテンシのオーバーヘッドを取り除けます。
  </Accordion>
</AccordionGroup>

### Realtime STT (Auto): サーバーエラー

<Accordion title="音声をチャンク分割していますか？">
  Cartesia のリアルタイム WebSocket エンドポイントは、音声がほぼ発話と同じ速度で到着することを想定しています。
  ソケットに一度に大量の音声をプッシュすると、サーバー側のバッファをオーバーロードする可能性があり、内部サーバーエラーとして現れる場合があります。

  小さなチャンク (各 50〜200 ミリ秒) でストリーミングし、リアルタイムに合わせて、ウォールクロック 1 秒あたり平均 1 秒の音声を送るようにペースを調整してください。[JavaScript の例](https://github.com/cartesia-ai/cartesia-js/blob/v3.2.0/examples/browser_examples.ts#L29-L66) もご覧ください。

  完全なファイルを一度に文字起こししたい場合は、ファイル全体を 1 回のリクエストで受け付ける [Batch STT](/api-reference/stt/transcribe) の利用を検討してください。
</Accordion>

## Realtime STT (Manual) のトラブルシューティング

当社の `/stt/websocket` エンドポイントは、ユーザーターンがクライアントによって**手動でファイナライズ**されるため、「Realtime STT (**Manual**)」と呼んでいます。

### Realtime STT (Manual): トランスクリプトエラー

<AccordionGroup>
  <Accordion title="トランスクリプトを正しく結合していますか？">
    各 `transcript` イベントは、音声全体のトランスクリプトではなく、**最後の確定トランスクリプト以降のデルタ** を運びます。`is_final` が `true` のすべてのイベントの `text` を追記してください:

    ```python theme={null}
    import json

    transcript = ""
    async for message in websocket:
        event = json.loads(message)
        if event["type"] == "transcript" and event["is_final"]:
            # delta, appended exactly as received
            transcript += event["text"]
    ```

    `is_final` が true のすべての `transcript` イベントを必ず含めてください。

    ```json lines theme={null}
    { "type": "transcript", "is_final": false, "text": "Ignore this" }
    { "type": "transcript", "is_final": true, "text": "This is a" }
    { "type": "transcript", "is_final": true, "text": " single sentence." }
    ```

    `text` をトリミングしないでください

    ```json lines theme={null}
    "Trimming may"
    " join words."
    ```

    ```json theme={null}
    "Trimming mayjoin words."
    ```

    `text` を空白を挟んで結合しないでください

    ```json lines theme={null}
    "Insert"
    "ing spaces is not safe"
    ```

    ```json theme={null}
    "Insert ing spaces is not safe"
    ```
  </Accordion>

  <Accordion title="すべてのイベントをドレインしましたか？">
    セッションの音声をすべて送信し終えたら、`"close"` を送信して、バッファリングされている音声をフラッシュし、残りの `transcript` イベントを発行するようモデルに伝えます。すべての音声が処理されると、サーバーは `{ "type": "done" }` を送信し、その後でソケットをクローズします。

    サーバーは文字起こしの精度を高めるために音声を一定量バッファします。close コマンドを送信しなかったり、メッセージの読み取りを早期に停止したりすると、バッファされた音声は処理されません。最後の 1 秒の音声を気にしないのであれば、これは問題ありません。

    ```python theme={null}
    await websocket.send("close")
    async for message in websocket:
        event = json.loads(message)
        if event["type"] == "transcript" and event["is_final"]:
            transcript += event["text"]
        elif event["type"] == "done":
            print("done! expect the server to close the connection soon with code=1000")
            # optional: stop reading messages and close the socket yourself
    print("server closed the connection now")
    ```
  </Accordion>

  <Accordion title="言語を指定しましたか？">
    WebSocket 接続を確立する際に、クエリパラメーターとして `?language=xx` (`xx` を ISO 639-1 言語コードに置き換え) を必ず含めてください。このエンドポイントはまだ言語検出をサポートしていません。

    対応言語については [Models](/build-with-cartesia/stt-models/latest) を参照してください。
  </Accordion>

  <Accordion title="正しいサンプルレートとエンコーディングを使用していますか？">
    モデルは、接続時に宣言した `encoding` と `sample_rate` を使ってバイト列をデコードします。これらのパラメーターが正しくなくても、Cartesia のサーバーは **エラーを返さない場合があります**。

    パラメーターを検証するには、音声データを保存し、[ffplay](https://ffmpeg.org/ffplay.html) で再生してみてください:

    ```bash theme={null}
    # encoding=pcm_s16le
    # sample_rate=16000
    # 1 channel (the API expects mono)
    ffplay -f s16le -ar 16000 -ac 1 audio.raw

    # general format
    ffplay -f <encoding_without_pcm_prefix> -ar <sample_rate> -ac <num_channels_must_be_one> <file_path>
    ```

    再生がおかしく聞こえる場合 (かなり明らかにわかるはずです)、`encoding` か `sample_rate` がデータと一致していません。音声がきれいに再生されるように修正し、その同じ値を API に送ってください。

    適切なパラメータを見つけるには [STT 入力音声エンコーディング](/build-with-cartesia/capability-guides/stt-input-encodings) を参照してください。
  </Accordion>

  <Accordion title="ファイナライズの頻度が高すぎませんか？">
    `finalize` は、ユーザーの発話が終わった後にのみ送信するようにしてください。発話の途中でファイナライズすると、文字起こしエラーが発生します。
  </Accordion>
</AccordionGroup>

### Realtime STT (Manual): 高レイテンシー

<AccordionGroup>
  <Accordion title="finalize コマンドを送信していますか？">
    文字起こしは `finalize` コマンドによってトリガーされます。ユーザーが発話を終えたことを示したとき、または VAD がユーザーの発話終了を検出したときに送信して「ターンをファイナライズ」してください:

    ```python theme={null}
    await websocket.send("finalize")
    ```

    `finalize` を送信しない場合、モデルは無音ベースの自動ファイナライズにフォールバックします。これは設計上、より低速です。ユーザーの発話が終わったことを確認するため、無音が続くのを待つ必要があるからです。

    `finalize` は必要なだけ何度でも送信してください。セッションを恒久的にクローズする `close` と混同しないでください。

    `finalize` は、音声ストリームの妥当なタイミングでのみ送信する必要があります。発話の途中でファイナライズすると、文字起こしエラーが発生します。
  </Accordion>

  <Accordion title="適切なエンドポイントを使用していますか？">
    ユーザーが発話を開始・終了するタイミングが分からない場合は、
    [リアルタイム STT (Auto)](/api-reference/stt/turns/websocket) を試してみてください。
    モデルがターンの境界を検出し、ユーザーの発話が終わったらすぐに最終トランスクリプトを発行します。

    "manual" から "auto" に切り替えると、すぐに最終トランスクリプトのレイテンシが改善されます。
    "manual" エンドポイントは、クライアントが `finalize` を送信することを想定し、ユーザーの発話による最後のトランスクリプトチャンクを保留するためです。

    "auto" エンドポイントは、クライアントから音声以外を送ることを想定していません。最終トランスクリプトの準備ができ次第、`turn.end` イベントで送信します。
  </Accordion>

  <Accordion title="音声の送信を停止しましたか？">
    Cartesia の API は連続した音声ストリームを想定しています。
    音声の送信を停止すると、サーバーはユーザーが無音であると見なすのではなく、追加の音声チャンクが到着するのを待ちます。

    これは通常、ネットワークの遅延に対応するために望ましい挙動ですが、クライアントが音声入力をミュートしている間、無音 (すべてゼロ) を送信し続ける必要があることも意味します。
  </Accordion>
</AccordionGroup>

### Realtime STT (Manual): サーバーエラー

<Accordion title="音声をチャンク分割していますか？">
  Cartesia のリアルタイム WebSocket エンドポイントは、音声がほぼ発話と同じ速度で到着することを想定しています。
  ソケットに一度に大量の音声をプッシュすると、サーバー側のバッファをオーバーロードする可能性があり、内部サーバーエラーとして現れる場合があります。

  小さなチャンク (各 50〜200 ミリ秒) でストリーミングし、リアルタイムに合わせて、ウォールクロック 1 秒あたり平均 1 秒の音声を送るようにペースを調整してください。[JavaScript の例](https://github.com/cartesia-ai/cartesia-js/blob/v3.2.0/examples/browser_examples.ts#L29-L66) もご覧ください。

  完全なファイルを一度に文字起こししたい場合は、ファイル全体を 1 回のリクエストで受け付ける [Batch STT](/api-reference/stt/transcribe) の利用を検討してください。
</Accordion>