@kubohiroya/turbowarp-openai-realtime-api 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md ADDED
@@ -0,0 +1,353 @@
1
+ # TurboWarp-OpenAI-Realtime-API
2
+
3
+ [English](README.md) | [日本語](README.ja.md)
4
+
5
+ OpenAI Realtime APIと音声やテキストで会話し、ブロックで書いた関数をモデルから呼び出せるようにするTurboWarp機能拡張です。OpenAIのAPIキーはlocalhostの中継に置いたままで、ブラウザには短時間だけ有効な一時キーしか渡しません。
6
+
7
+ **利用ガイド:** [English](https://kubohiroya.github.io/turbowarp-openai-realtime-api/)
8
+
9
+ ## できること
10
+
11
+ - TurboWarpのプロジェクトをWebRTCでOpenAI Realtime APIにつなぐ(マイクあり/なし)
12
+ - テキストを送り、アシスタントの応答テキストまたは音声の書き起こしを受け取る
13
+ - `define function ... export as tool` のスクリプトをモデルが呼べるツールにし、スクリプトの `return` の値をモデルに返す
14
+ - OpenAIのAPIキーは、localhostで動く[`@kubohiroya/capability-proxy`](https://github.com/kubohiroya/capability-proxy)に置いたままにする。拡張はワンタイムコードで中継とペアリングし、接続のたびに一時キーを受け取る
15
+
16
+ ## 動作条件と安全上の注意
17
+
18
+ - カスタム機能拡張を使えるTurboWarp DesktopまたはTurboWarp Web
19
+ - `openai` providerを設定して`127.0.0.1`で起動した[`@kubohiroya/capability-proxy`](https://github.com/kubohiroya/capability-proxy)
20
+ - WebRTCとマイクが使えるブラウザ。応答の音声はページから再生される
21
+
22
+ > [!IMPORTANT]
23
+ > この機能拡張は、マイク、WebRTC、localhostの中継、関数スクリプトを起動するためのVMランタイムを使うため、サンドボックスなしで実行する必要があります。
24
+ > 信頼できる配布元の機能拡張だけを読み込んでください。
25
+
26
+ - 中継のendpointは `http://127.0.0.1:8787` のようなループバックのoriginに限ります。中継のtokenがこのマシンの外に出ないよう、それ以外のhostは拒否します。
27
+ - 中継のtokenと一時キーは実行時のメモリだけに保持し、ブロックや `.sb3` には保存しません。
28
+ - ツールとして公開した関数は、モデルが選んだ引数で呼ばれます。引数はすべて信頼できない入力として扱ってください。
29
+
30
+ ## インストール
31
+
32
+ 1. [`dist/turbowarp-openai-realtime-api.js`](dist/turbowarp-openai-realtime-api.js?raw=1)をダウンロードします。
33
+ 2. TurboWarpで**機能拡張**を開きます。
34
+ 3. **カスタム機能拡張**からfileを読み込みます。
35
+ 4. **サンドボックスなしで実行する**を有効にします。
36
+
37
+ npm packageとして使う場合は、検証済みのversionをexact pinします。
38
+
39
+ ```bash
40
+ pnpm add --save-exact @kubohiroya/turbowarp-openai-realtime-api@0.1.0
41
+ ```
42
+
43
+ ## クイックスタート
44
+
45
+ 1. `openai` providerを設定した`capability-proxy`を起動し、表示された8桁のペアリングコードを控えます(設定方法は同READMEを参照)。
46
+ 2. この機能拡張をサンドボックスなしで読み込みます。
47
+ 3. 次のブロックを実行し、マイクに話しかけるか、`send text`を使います。
48
+
49
+ ```text
50
+ configure local relay [http://127.0.0.1:8787]
51
+ pair local relay with one-time code [12345678]
52
+ set instructions to [You are a friendly assistant. Answer briefly.]
53
+ connect to Realtime with microphone [on]
54
+ send text [Hello!]
55
+
56
+ when assistant finishes responding
57
+ say (last assistant response)
58
+
59
+ define function [get_score] description [Returns the player's score.] args schema [{"type":"object","properties":{}}] export as [tool]
60
+ return (join [{"score":] (join (score) [}]))
61
+ ```
62
+
63
+ ## ブロックリファレンス
64
+
65
+ ブロックリファレンスは[`src/block-definitions.json`](src/block-definitions.json)から生成しています。生成された部分は手で編集しないでください。ブロックの表示文言はTurboWarp上の英語表記のままです。
66
+
67
+ <!-- BEGIN GENERATED BLOCKS -->
68
+
69
+ ### `configure local relay [ENDPOINT]`
70
+
71
+ localhostで動くcapability-proxy中継のループバックoriginを設定します。以前のペアリングは消去されます。
72
+
73
+ | 項目 | 値 |
74
+ |---|---|
75
+ | 種類 | コマンド |
76
+ | Opcode | `configureRelay` |
77
+ | `ENDPOINT` | 文字列, 既定値: `http://127.0.0.1:8787` |
78
+
79
+ ### `pair local relay with one-time code [CODE]`
80
+
81
+ 中継が表示した8桁のコードを、メモリだけに保持するセッションtokenと交換します。
82
+
83
+ | 項目 | 値 |
84
+ |---|---|
85
+ | 種類 | コマンド |
86
+ | Opcode | `pairRelay` |
87
+ | `CODE` | 文字列, 既定値: `00000000` |
88
+
89
+ ### `local relay paired?`
90
+
91
+ 有効期限内の中継セッションtokenをメモリに保持しているかを返します。
92
+
93
+ | 項目 | 値 |
94
+ |---|---|
95
+ | 種類 | 真偽値ブロック |
96
+ | Opcode | `isRelayPaired` |
97
+
98
+ ### `set instructions to [TEXT]`
99
+
100
+ 次の接続で使うシステムへの指示(instructions)を設定します。
101
+
102
+ | 項目 | 値 |
103
+ |---|---|
104
+ | 種類 | コマンド |
105
+ | Opcode | `setInstructions` |
106
+ | `TEXT` | 文字列, 既定値: `You are a friendly assistant. Answer briefly.` |
107
+
108
+ ### `set voice to [VOICE]`
109
+
110
+ 次の接続で使う応答の声を設定します。
111
+
112
+ | 項目 | 値 |
113
+ |---|---|
114
+ | 種類 | コマンド |
115
+ | Opcode | `setVoice` |
116
+ | `VOICE` | 文字列, 既定値: `marin`, 選択肢: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `marin`, `sage`, `shimmer`, `verse` |
117
+
118
+ ### `set output to [MODE]`
119
+
120
+ 次の接続で、音声で応答するかテキストだけで応答するかを選びます。
121
+
122
+ | 項目 | 値 |
123
+ |---|---|
124
+ | 種類 | コマンド |
125
+ | Opcode | `setOutputMode` |
126
+ | `MODE` | 文字列, 既定値: `audio`, 選択肢: `audio`, `text` |
127
+
128
+ ### `set model to [MODEL]`
129
+
130
+ 次の接続で使うRealtimeのモデルを選びます。中継の運用者が許可したモデルだけが使えます。空にすると中継の既定のモデルを使います。
131
+
132
+ | 項目 | 値 |
133
+ |---|---|
134
+ | 種類 | コマンド |
135
+ | Opcode | `setModel` |
136
+ | `MODEL` | 文字列, 既定値: `gpt-realtime-2.1-mini`, 選択肢: `gpt-realtime-2.1-mini`, `gpt-realtime-2.1` |
137
+
138
+ ### `set session time limit to [SECONDS] seconds`
139
+
140
+ 次の接続から、指定した秒数が経つと自動で切断します。0にすると制限しません。
141
+
142
+ | 項目 | 値 |
143
+ |---|---|
144
+ | 種類 | コマンド |
145
+ | Opcode | `setSessionTimeLimit` |
146
+ | `SECONDS` | 数値, 既定値: `600` |
147
+
148
+ ### `connect to Realtime with microphone [MICROPHONE]`
149
+
150
+ 中継を通じて一時キーを発行し、WebRTCのセッションを開きます。ツールとして公開した関数はモデルから呼べるようになります。
151
+
152
+ | 項目 | 値 |
153
+ |---|---|
154
+ | 種類 | コマンド |
155
+ | Opcode | `connect` |
156
+ | `MICROPHONE` | 文字列, 既定値: `on`, 選択肢: `on`, `off` |
157
+
158
+ ### `disconnect from Realtime`
159
+
160
+ WebRTCのセッションを閉じてマイクを止め、実行中の関数呼び出しを失敗させます。
161
+
162
+ | 項目 | 値 |
163
+ |---|---|
164
+ | 種類 | コマンド |
165
+ | Opcode | `disconnect` |
166
+
167
+ ### `connected to Realtime?`
168
+
169
+ Realtimeのセッションが開いているかを返します。
170
+
171
+ | 項目 | 値 |
172
+ |---|---|
173
+ | 種類 | 真偽値ブロック |
174
+ | Opcode | `isConnected` |
175
+
176
+ ### `Realtime connection state`
177
+
178
+ disconnected、connecting、connected、failedのいずれかを返します。
179
+
180
+ | 項目 | 値 |
181
+ |---|---|
182
+ | 種類 | 値ブロック |
183
+ | Opcode | `connectionState` |
184
+
185
+ ### `Realtime model`
186
+
187
+ 現在または直前の接続で中継が使ったモデルを返します。
188
+
189
+ | 項目 | 値 |
190
+ |---|---|
191
+ | 種類 | 値ブロック |
192
+ | Opcode | `currentModel` |
193
+
194
+ ### `session elapsed seconds`
195
+
196
+ 現在のセッションが接続してからの秒数を返します。切断中は0を返します。
197
+
198
+ | 項目 | 値 |
199
+ |---|---|
200
+ | 種類 | 値ブロック |
201
+ | Opcode | `sessionElapsed` |
202
+
203
+ ### `when session time limit is reached`
204
+
205
+ セッションの時間上限によって切断されたときに起動します。
206
+
207
+ | 項目 | 値 |
208
+ |---|---|
209
+ | 種類 | ハット |
210
+ | Opcode | `whenSessionTimeLimitReached` |
211
+
212
+ ### `send text [TEXT]`
213
+
214
+ 利用者のテキストメッセージを会話に追加し、応答を要求します。
215
+
216
+ | 項目 | 値 |
217
+ |---|---|
218
+ | 種類 | コマンド |
219
+ | Opcode | `sendText` |
220
+ | `TEXT` | 文字列, 既定値: `Hello!` |
221
+
222
+ ### `when assistant finishes responding`
223
+
224
+ アシスタントのテキストまたは音声の書き起こしを含む応答が完了したときに起動します。
225
+
226
+ | 項目 | 値 |
227
+ |---|---|
228
+ | 種類 | ハット |
229
+ | Opcode | `whenResponseDone` |
230
+
231
+ ### `last assistant response`
232
+
233
+ 直近に完了したアシスタントの応答のテキスト、または音声の書き起こしを返します。
234
+
235
+ | 項目 | 値 |
236
+ |---|---|
237
+ | 種類 | 値ブロック |
238
+ | Opcode | `lastResponseText` |
239
+
240
+ ### `define function [NAME] description [DESCRIPTION] args schema [SCHEMA] export as [EXPORT]`
241
+
242
+ 関数を定義します。export asをtoolにすると、モデルから呼べるツールになります。NAME、DESCRIPTION、SCHEMAには文字列を直接書く必要があります。
243
+
244
+ | 項目 | 値 |
245
+ |---|---|
246
+ | 種類 | ハット |
247
+ | Opcode | `defineFunction` |
248
+ | `NAME` | 文字列, 既定値: `get_score` |
249
+ | `DESCRIPTION` | 文字列, 既定値: `Returns the player's current score.` |
250
+ | `SCHEMA` | 文字列, 既定値: `{"type":"object","properties":{}}` |
251
+ | `EXPORT` | 文字列, 既定値: `tool`, 選択肢: `tool`, `none` |
252
+
253
+ ### `function argument [PATH]`
254
+
255
+ 関数の中で、cityやitems.0.nameのようなドット区切りのパスにある引数を返します。
256
+
257
+ | 項目 | 値 |
258
+ |---|---|
259
+ | 種類 | 値ブロック |
260
+ | Opcode | `functionArgument` |
261
+ | `PATH` | 文字列, 既定値: `city` |
262
+
263
+ ### `function arguments JSON`
264
+
265
+ 関数の中で、すべての引数をJSONテキストとして返します。
266
+
267
+ | 項目 | 値 |
268
+ |---|---|
269
+ | 種類 | 値ブロック |
270
+ | Opcode | `functionArgumentsJson` |
271
+
272
+ ### `return [VALUE]`
273
+
274
+ 関数の中で値を返し、スクリプトを終了します。JSONテキストはJSONとして、それ以外のテキストは文字列として返します。
275
+
276
+ | 項目 | 値 |
277
+ |---|---|
278
+ | 種類 | コマンド |
279
+ | Opcode | `returnValue` |
280
+ | `VALUE` | 文字列, 既定値: `{"score":10}` |
281
+
282
+ ### `Realtime usage [FIELD]`
283
+
284
+ 最後にリセットしてからの使用量の合計を返します。costUSDは公開価格からの概算で、正確な請求額はOpenAIの管理画面で確認してください。
285
+
286
+ | 項目 | 値 |
287
+ |---|---|
288
+ | 種類 | 値ブロック |
289
+ | Opcode | `usageValue` |
290
+ | `FIELD` | 文字列, 既定値: `costUSD`, 選択肢: `costUSD`, `responses`, `inputTokens`, `outputTokens`, `cachedInputTokens`, `textInputTokens`, `audioInputTokens`, `textOutputTokens`, `audioOutputTokens` |
291
+
292
+ ### `reset Realtime usage`
293
+
294
+ 使用量の合計を0に戻します。
295
+
296
+ | 項目 | 値 |
297
+ |---|---|
298
+ | 種類 | コマンド |
299
+ | Opcode | `resetUsage` |
300
+
301
+ ### `last Realtime error`
302
+
303
+ 直近の中継、接続、APIのエラーを返します。エラーがなければ空文字列を返します。
304
+
305
+ | 項目 | 値 |
306
+ |---|---|
307
+ | 種類 | 値ブロック |
308
+ | Opcode | `lastError` |
309
+
310
+ <!-- END GENERATED BLOCKS -->
311
+
312
+ ## 重要な動作
313
+
314
+ | 状況 | 動作 |
315
+ |---|---|
316
+ | 中継のendpointがループバックのoriginでない | `last Realtime error`にエラーを記録し、以前のendpointを維持する |
317
+ | ペアリング前、または中継のセッションが期限切れの状態で接続する | `connect`はエラーを記録し、OpenAIには接続しない |
318
+ | `define function`のハットが不正(NAME/DESCRIPTION/SCHEMAが文字列の直書きでない、JSON Schemaが不正、名前の重複、descriptionのないツール) | `connect`は問題をすべて記録し、接続しない |
319
+ | 接続中に設定を変えた | instructions、voice、出力、ツールは次の接続から反映される |
320
+ | モデルが関数を呼んだ | すべての`define function`ハットが起動され、NAMEが一致したものだけが実行を続ける。`return`の値をJSONとして返し、新しい応答を要求する |
321
+ | 関数のスクリプトが`return`なしで終わった | 結果は`null`になる |
322
+ | 関数が30秒以内に終わらない | モデルには`{"error": "Function ... timed out."}`を返す |
323
+ | 同じ関数を続けて呼ばれた | 1つずつ順番に実行する。異なる関数は並行して実行する |
324
+ | ツールとして公開していない関数をモデルが呼んだ | 呼び出しを拒否し、モデルにエラーを返す |
325
+ | プロジェクトの停止 | 実行中・待機中の関数呼び出しは失敗する。Realtimeのセッションは`disconnect`まで維持する |
326
+ | 切断、または接続が切れた | マイクを解放し、音声を止め、実行中の関数呼び出しは失敗する |
327
+ | `set model to` | モデルは次の接続で送られる。中継は`allowedModels`に載っているモデルだけを受け付ける。空にすると中継の既定のモデルを使う。実際に使われたモデルは`Realtime model`でわかる |
328
+ | `set session time limit to` | 次の接続から、指定した秒数が経つとセッションを切断し、`when session time limit is reached`を起動する。0にすると制限しない |
329
+ | `Realtime usage [FIELD]` | 最後にリセットしてからのすべての`response.done`(関数呼び出しの往復も含む)の合計。`costUSD`は公開価格からの概算(`src/usage.ts`)で、正確な請求額はOpenAIの管理画面で確認する |
330
+
331
+ ## Composition API
332
+
333
+ Composition APIをimportしても、単独のTurboWarp機能拡張は登録されません。音声会話の拡張などの下流の拡張が、自分のブロックとハットを持ち、処理をこのAPIに渡します。関数は[`@kubohiroya/turbowarp-named-functions`](https://github.com/kubohiroya/turbowarp-named-functions)を使います。下流の拡張も同じ関数を使う場合は、`functions`に共有のインスタンスを渡します。使い方は[英語版README](README.md#composition-api)を参照してください。
334
+
335
+ ## 開発
336
+
337
+ Node.js 22.18.0以上と、`packageManager`で指定したpnpmを使います。
338
+
339
+ ```bash
340
+ corepack enable
341
+ pnpm install --frozen-lockfile
342
+ pnpm check
343
+ ```
344
+
345
+ 本物のTurboWarp VMをブラウザなしで動かす結合テストも実行する場合は、`SCRATCH_VM_PATH`にTurboWarpの`scratch-vm`の場所を指定します。
346
+
347
+ ```bash
348
+ SCRATCH_VM_PATH=/path/to/TurboWarp/scratch-vm pnpm test
349
+ ```
350
+
351
+ ## ライセンス
352
+
353
+ [Mozilla Public License 2.0](LICENSE) (SPDX: `MPL-2.0`).