> ## 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.

# 単語タイムスタンプ

> すべての単語の開始時刻と終了時刻を取得する

単語タイムスタンプは、各単語が話されたタイミングを示します。これにより、話されている単語のハイライト表示、字幕の位置合わせ、音声の秘匿処理、エージェントの応答速度の測定などが行えます。

`ink-preview` では、すべてのトランスクリプトに単語タイムスタンプが含まれます。有効にするための設定は必要ありません。

## 単語タイムスタンプを返すモデル

| モデル | 単語タイムスタンプ |
| - | - |
| `ink-preview` | Realtime STT (Auto) と Realtime STT (Manual) で常に返される |
| `ink-whisper` | Realtime STT (Manual) では常に返される。Batch STT では、`timestamp_granularities` を `["word"]` に設定した場合のみ |
| `ink-2` | まだ利用できない |

## 各単語の形式

`words` リストの各エントリには 3 つのフィールドがあります。

| フィールド | 型 | 説明 |
| - | - | - |
| `word` | string | トランスクリプトに表示される単語。単語に付いている句読点を含む |
| `start` | number | 単語の開始時刻（秒） |
| `end` | number | 単語の終了時刻（秒） |

時刻は、各ターンの開始からではなく、接続で最初に送信した音声から計測されます。値は 10 ms 単位に丸められます。

## Realtime STT (Auto)

`turn.update`、`turn.eager_end`、`turn.end` には、`transcript` と同様に `words` が含まれます。`turn.update` にはその時点までの単語が、`turn.eager_end` と `turn.end` にはターン内のすべての単語が含まれます。新しいターンごとに新しいリストが始まります。

単語は、モデルがその単語全体を聞き終えた時点で追加され、その後エントリが変わることはありません。そのため、話者がまだ話している間は、`words` がトランスクリプトよりわずかに遅れることがあります。次の例では、`someone` はトランスクリプトに含まれていますが、まだ `words` には含まれていません。

```json theme={null}
{ "type": "turn.update", "transcript": "When you call someone", "words": [
    { "word": "When", "start": 1.11, "end": 1.29 },
    { "word": "you", "start": 1.29, "end": 1.41 },
    { "word": "call", "start": 1.41, "end": 1.68 } ] }
```

ターンに最初の完全な単語が揃うまで `words` は省略されるため、`words` がない場合は空のリストとして扱ってください。

## Realtime STT (Manual)

[Realtime STT (Manual)](https://docs.cartesia.ai/ja-jp/api-reference/stt/websocket.md) では、`text` に新しいテキストのみが含まれるのと同様に、各 `transcript` イベントには前回のイベント以降に完了した単語のみが含まれます。リストを保持し、各イベントの単語を追加していってください。`flush_done` または `done` が届いた時点で、確定した音声のすべての単語が揃います。

タイムスタンプはテキストよりわずかに遅れることがあります。この例では、`away` は最初のイベントのテキストに含まれていますが、そのエントリは 2 番目のイベントで届きます。`satellite` は 2 番目のイベントのテキストに含まれ、そのエントリはさらに後に届きます。

```json theme={null}
{ "type": "transcript", "is_final": true, "text": " miles away", "words": [
    { "word": "miles", "start": 3.15, "end": 3.48 } ] }
{ "type": "transcript", "is_final": true, "text": ", you are using a satellite", "words": [
    { "word": "away,", "start": 3.51, "end": 3.93 },
    { "word": "you", "start": 4.29, "end": 4.44 },
    { "word": "are", "start": 4.44, "end": 4.50 },
    { "word": "using", "start": 4.53, "end": 4.83 },
    { "word": "a", "start": 4.86, "end": 4.92 } ] }
```

遅れて届く単語は、`text` が空のイベントで届くこともあります。その単語は保持し、トランスクリプトには何も追加しないでください。

## 単語の分割方法

スペースで区切って書く言語では、各エントリは 1 つの単語です。句読点は `away,` や `please.` のように直前の単語に付きますが、開き引用符や開き括弧は `"Hello` や `(see` のように直後の単語に付きます。

中国語、日本語、タイ語など、スペースで区切らずに書く言語では、モデルが分割位置を決めるため、エントリは単語の一部、1 つの単語全体、または複数の単語になることがあります。中国語や日本語のテキスト内の英単語と数字は、それぞれ独立したエントリとして返されます。

いずれの場合も、すべての単語が届いた時点で、エントリはトランスクリプト全体を正しい順序でカバーします。

## タイムスタンプの精度

モデルは各タイムスタンプを計測するのではなく予測するため、近い値ではあるものの、常に正確とは限らないことを想定してください。

* スペルアウトされたメールアドレスや長い数字など、長い単語では、話者がその単語を話し始めた時点より `start` が遅くなることがあります。
* エントリの長さがゼロ（`start` と `end` が等しい）になることがあります。これはスペースで区切って書く言語ではまれですが、単語が分割されて返されることがある中国語（標準語）、広東語、日本語、タイ語ではよく見られます。そのテキストもトランスクリプトに含まれます。

## 次に進む

> [card] [ターン検出](https://docs.cartesia.ai/ja-jp/use-the-api/stt/turns.md)
>
> `words` がターンのライフサイクルにどう組み込まれるか

> [card] [言語](https://docs.cartesia.ai/ja-jp/use-the-api/stt/languages.md)
>
> 検出された言語は同じイベントで届く

> [card] [API リファレンス](https://docs.cartesia.ai/ja-jp/api-reference/stt/turns/websocket.md)
>
> すべてのイベントとフィールド


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.