WebSocket API リファレンス

機械可読な版は asyncapi.yaml（AsyncAPI 3.1）と schemas/（JSON Schema 2020-12）にあります。

共通の決まり

• クライアントと文字おこしくんは、制御メッセージを、WebSocket のテキストフレーム 1 個に UTF-8 の JSON オブジェクトを 1 個ずつ入れて送る。type がメッセージの種類を表す。
• クライアントは、認証のトークンを最初の hello メッセージで送る。 トークンを URL・ヘッダー・サブプロトコルには載せない。トークンはセッション単位の短期のもので、API キーではない。
• 受け手は未知のフィールドを無視する（前方互換）。送り手は任意フィールドを省くか null にする。受け手は未知の type のメッセージを不正なメッセージとして扱う。
• 文字おこしくんは、文字列の長さを、Unicode のコードポイントの数で数える。クライアントと文字おこしくんは、1 メッセージを 64 KiB までにし、permessage-deflate を使わない。
• 文字おこしくんは、エラーを {"type":"error","error":{"code","message","fatal"}} の形で送る。fatal: true なら、文字おこしくんはこの後に接続を閉じる。文字おこしくんは WebSocket の close code を規定しない。クライアントは、切れた理由を、直前に受け取った error.code で判断する。
• 文字おこしくんは、非 fatal な error を送った後に接続を切ることがある。たとえば、hello のタイムアウトの後と、受信が文字おこしくんからの送信に追いつかないクライアントへの rate_limited の後に、文字おこしくんは接続を切る。クライアントは、この切断を予期しない切断として扱い、短いバックオフで再接続する。

クライアントがいつ再接続し、いつ再接続せずに終えるかは、再接続とエラーの扱いにあります。

Subscribe（/v1/subscribe）

接続の流れ: hello → welcome（スナップショット）→ 差分のイベント → session_ended。受け手は utteranceId ごとに revision が最大の発話だけを採用します（改訂モデル）。

クライアント → サーバー

hello

クライアントは、接続の直後に hello を 1 回だけ送る。

スキーマ: schemas/subscribe-client-message.json#/$defs/Hello

例: 接続直後の名乗り

{"type":"hello","protocolVersion":1,"token":"eyJ2IjoxLCJzaWQiOiJzZXNfMDEiLCJzY29wZSI6InRyYW5zY3JpcHQ6cmVhZCJ9.c2lnbmF0dXJl"}

ping

ブラウザは WebSocket の ping フレームを扱えないので、クライアントは、生存確認とプロキシのアイドル切断の防止のために ping を送る。文字おこしくんは pong を返す。

スキーマ: schemas/subscribe-client-message.json#/$defs/Ping

例: 生存確認（15 秒ごとなど）

{"type":"ping"}

サーバー → クライアント

welcome

文字おこしくんは、接続した時点の状態のスナップショットを welcome で送る。受け手は状態を丸ごと置き換える（再接続のときも）。recent は、直近の発話の最新の改訂を startedAt の昇順に並べたものである（認識途中を含む）。

スキーマ: schemas/subscribe-server-message.json#/$defs/Welcome

例: 接続時点のスナップショット

{"type":"welcome","protocolVersion":1,"sessionId":"ses_01J8Z6Q3M4","speakers":[{"speaker":{"speakerId":"alice","displayName":"たろう","avatarUrl":"https://cdn.example.com/avatars/alice.png"},"inferred":false},{"speaker":{"speakerId":"room-mic#1","displayName":"話者 1"},"inferred":true}],"tracks":[{"trackId":"alice-mic","mode":"single","speakerId":"alice"},{"trackId":"room-mic","mode":"mixed"}],"speakingTrackIds":["alice-mic"],"recent":[{"utteranceId":"utt_01","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"refined","revision":5,"text":"こんにちは、今日はよろしくお願いします。","startedAt":1790000000000}]}

speaker_upserted

文字おこしくんは、話者の追加・更新を知らせる。inferred は、話者分離が推定した話者かどうかを表す。

スキーマ: schemas/subscribe-server-message.json#/$defs/SpeakerUpserted

例: 話者の追加・更新

{"type":"speaker_upserted","speaker":{"speakerId":"bob","displayName":"はなこ"},"inferred":false}

speaker_removed

文字おこしくんは、話者の削除を知らせる。受け手はその話者の過去の発話を消さない。

スキーマ: schemas/subscribe-server-message.json#/$defs/SpeakerRemoved

例: 話者の削除

{"type":"speaker_removed","speakerId":"bob"}

track_opened

文字おこしくんは、トラックが開いたことを知らせる。

スキーマ: schemas/subscribe-server-message.json#/$defs/TrackOpened

例: トラックが開いた

{"type":"track_opened","track":{"trackId":"bob-mic","mode":"single","speakerId":"bob"}}

track_closed

文字おこしくんは、トラックが閉じたことを知らせる。受け手はそのトラックの発話を消さない。

スキーマ: schemas/subscribe-server-message.json#/$defs/TrackClosed

例: トラックが閉じた

{"type":"track_closed","trackId":"bob-mic"}

speech_started

文字おこしくんは、トラックが発声中になったことを知らせる（「話している」の表示に使う）。

スキーマ: schemas/subscribe-server-message.json#/$defs/SpeechStarted

例: 発声中になった

{"type":"speech_started","trackId":"alice-mic"}

speech_ended

文字おこしくんは、トラックの発声が終わったことを知らせる。

スキーマ: schemas/subscribe-server-message.json#/$defs/SpeechEnded

例: 発声が終わった

{"type":"speech_ended","trackId":"alice-mic"}

utterance

文字おこしくんは、発話の改訂を 1 件ずつ送る。受け手は utteranceId ごとに revision が最大のものだけを採用し、同じか小さい revision は捨てる（追記しない。置き換える）。

スキーマ: schemas/subscribe-server-message.json#/$defs/Utterance

例: 認識途中（partial）。同じ utteranceId の後の改訂で置き換わる

{"type":"utterance","utterance":{"utteranceId":"utt_02","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"partial","revision":1,"text":"それでは始め","startedAt":1790000004000}}

例: 確定（final）

{"type":"utterance","utterance":{"utteranceId":"utt_02","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"final","revision":3,"text":"それでは始めましょう","startedAt":1790000004000}}

例: 整形済み（refined）。final の後に非同期で届く

{"type":"utterance","utterance":{"utteranceId":"utt_02","trackId":"alice-mic","speaker":{"kind":"declared","speakerId":"alice"},"stage":"refined","revision":4,"text":"それでは始めましょう。","startedAt":1790000004000}}

例: 話者分離による推定の話者（mixed トラック）

{"type":"utterance","utterance":{"utteranceId":"utt_03","trackId":"room-mic","speaker":{"kind":"inferred","speakerId":"room-mic#1"},"stage":"final","revision":2,"text":"よろしくお願いします","startedAt":1790000006500}}

例: 話者不明（トラック単位で表示する）

{"type":"utterance","utterance":{"utteranceId":"utt_04","trackId":"room-mic","speaker":{"kind":"unattributed"},"stage":"partial","revision":0,"text":"えっと","startedAt":1790000009120}}

session_ended

文字おこしくんは、文字起こしが終了したことを知らせる。この後、文字おこしくんはイベントを送らない。クライアントは再接続しない。

スキーマ: schemas/subscribe-server-message.json#/$defs/SessionEnded

例: 文字起こしの終了

{"type":"session_ended"}

error

文字おこしくんは、エラーを error で知らせる。error.fatal が true なら、文字おこしくんはこの後に接続を切る。

スキーマ: schemas/subscribe-server-message.json#/$defs/Error

例: 終了済み・存在しないセッション（fatal。再接続しない）

{"type":"error","error":{"code":"session_ended","message":"session not found","fatal":true}}

例: クライアントの受信が、文字おこしくんからの送信に追いつかない（文字おこしくんは非 fatal の error を送った後に接続を切る。クライアントは短いバックオフで再接続する）

{"type":"error","error":{"code":"rate_limited","message":"the client is too slow to keep up","fatal":false}}

pong

文字おこしくんは、ping に pong で応える。

スキーマ: schemas/subscribe-server-message.json#/$defs/Pong

例: ping への応答

{"type":"pong"}

Ingest（/v1/ingest）

接続の流れ: hello → welcome を待つ → 全話者の speaker_upsert → 開いている全トラックの track_open → state_synced → 音声のバイナリフレームと speech_start / speech_end。詳しい手順は音声を送るにあります。

音声バイナリフレーム

例（channel = 1、sequence = 42、payload = f8 ff fe）:

01 00 01 00 00 00 2a f8 ff fe

• opus のトラックで payload が Discord の無音フレーム（f8 ff fe の 3 バイト）のとき、文字おこしくんは無音フレームをデコーダーに通すだけで、音声認識にも利用量にも入れない。デコーダーは次の音声との継ぎ目に無音フレームを使うので、クライアントは無音フレームを省かずに送る。無音フレームを送らない場合も、クライアントは sequence を飛ばさない（文字おこしくんは、飛ばした番号を欠損として補間する）。文字おこしくんは、無音フレームの直後の欠番を補間しない（補間しても無音になるため）。

クライアント → サーバー

hello

クライアントは、接続の直後に hello を 1 回だけ送る。welcome を受け取るまで、ほかのメッセージを送らない。

スキーマ: schemas/ingest-client-message.json#/$defs/Hello

例: 接続直後の名乗り

{"type":"hello","protocolVersion":1,"token":"eyJ2IjoxLCJzaWQiOiJzZXNfMDEiLCJzY29wZSI6InRyYW5zY3JpcHQ6cmVhZCJ9.c2lnbmF0dXJl","clientName":"my-recorder/1.0"}

speaker_upsert

クライアントは、このメッセージで話者を追加・更新する。single トラックの話者の speaker_upsert は、そのトラックの track_open より前に送る。

スキーマ: schemas/ingest-client-message.json#/$defs/SpeakerUpsert

例: 話者の宣言

{"type":"speaker_upsert","speaker":{"speakerId":"alice","displayName":"たろう","avatarUrl":"https://cdn.example.com/avatars/alice.png"}}

speaker_remove

クライアントは、このメッセージで話者を削除する。その話者の single トラックは、先に track_close しておく。

スキーマ: schemas/ingest-client-message.json#/$defs/SpeakerRemove

例: 話者の削除

{"type":"speaker_remove","speakerId":"alice"}

track_open

クライアントは、このメッセージでトラックを開き、バイナリフレームで使う channel 番号を割り当てる。

スキーマ: schemas/ingest-client-message.json#/$defs/TrackOpen

例: 1 人の話者の Opus（48kHz・2ch）のトラック

{"type":"track_open","trackId":"alice-mic","channel":1,"format":{"codec":"opus","sampleRate":48000,"channels":2},"track":{"mode":"single","speakerId":"alice"}}

例: 複数人の声が入った PCM 16kHz モノラルのトラック（話者分離あり）

{"type":"track_open","trackId":"room-mic","channel":2,"format":{"codec":"pcm_s16le","sampleRate":16000,"channels":1},"track":{"mode":"mixed","diarize":true}}

track_close

クライアントは、このメッセージでトラックを閉じる。

スキーマ: schemas/ingest-client-message.json#/$defs/TrackClose

例: トラックを閉じる

{"type":"track_close","trackId":"room-mic"}

state_synced

クライアントは、接続の直後の状態の送り直し（全話者の speaker_upsert と全トラックの track_open）が終わったことを、このメッセージで知らせる。文字おこしくんは、クライアントが state_synced までに宣言しなかったトラックを閉じる。

スキーマ: schemas/ingest-client-message.json#/$defs/StateSynced

例: 状態の送り直しの完了

{"type":"state_synced"}

speech_start

クライアントは、このメッセージで発話区間の開始の目安を知らせる。capturedAt は、送信側の時計による参考値である。

スキーマ: schemas/ingest-client-message.json#/$defs/SpeechStart

例: 発話の開始

{"type":"speech_start","trackId":"alice-mic","capturedAt":1790000000000}

speech_end

クライアントは、このメッセージで発話区間の終わりの目安を知らせる。文字おこしくんに speech_end が届くと、確定（final）が早く出る。

スキーマ: schemas/ingest-client-message.json#/$defs/SpeechEnd

例: 発話の終わり

{"type":"speech_end","trackId":"alice-mic"}

ping

クライアントは、生存確認のために ping を送る。文字おこしくんは pong を返す。

スキーマ: schemas/ingest-client-message.json#/$defs/Ping

例: 生存確認

{"type":"ping"}

audio_frame

クライアントは、音声をバイナリフレーム（application/octet-stream）で送ります。レイアウトは音声バイナリフレームにあります。

サーバー → クライアント

welcome

文字おこしくんは、hello を受け付けたことを welcome で知らせる。protocolVersion は、この接続で使うバージョンである。

スキーマ: schemas/ingest-server-message.json#/$defs/Welcome

例: hello の受け付け

{"type":"welcome","protocolVersion":1,"sessionId":"ses_01J8Z6Q3M4"}

error

文字おこしくんは、エラーを error で知らせる。trackId は、特定のトラックに関するエラーのときだけ付く。error.fatal が true なら、文字おこしくんはこの後に接続を切る。

スキーマ: schemas/ingest-server-message.json#/$defs/Error

例: 宣言していない話者を参照した（非 fatal。送信内容を直す）

{"type":"error","error":{"code":"unknown_speaker","message":"speaker bob is not declared","fatal":false},"trackId":"bob-mic"}

例: トークンが不正・期限切れ（fatal。再接続しない）

{"type":"error","error":{"code":"unauthorized","message":"the token is invalid, expired, or lacks ingest:write","fatal":true}}

pong

文字おこしくんは、ping に pong で応える。

スキーマ: schemas/ingest-server-message.json#/$defs/Pong

例: ping への応答

{"type":"pong"}

共通の型

次の型は schemas/common.json の $defs にあります。

値の上限

不正なメッセージの例

次の表に、文字おこしくんのサーバーの検証関数（parse*）と JSON Schema のどちらも拒否する、不正なメッセージの代表例を並べます。