@micdrop/openai 1.5.1 → 1.6.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.md CHANGED
@@ -75,6 +75,8 @@ See the [Agent interface](https://micdrop.dev/docs/ai-integration/custom-integra
75
75
 
76
76
  ## OpenAI STT (Speech-to-Text)
77
77
 
78
+ OpenAI [deprecated](https://developers.openai.com/api/docs/deprecations) `gpt-4o-transcribe` (the default), `gpt-4o-mini-transcribe` and `whisper-1`, which shut down on **February 26, 2027**. Their replacements, `gpt-live-transcribe` and `gpt-transcribe`, work with the same options: `language` is sent as the list of expected languages these models take. `gpt-live-transcribe` is recommended for new integrations.
79
+
78
80
  ### Usage with MicdropServer
79
81
 
80
82
  ```typescript
@@ -83,7 +85,7 @@ import { MicdropServer } from '@micdrop/server'
83
85
 
84
86
  const stt = new OpenaiSTT({
85
87
  apiKey: process.env.OPENAI_API_KEY || '',
86
- model: 'gpt-4o-transcribe',
88
+ model: 'gpt-live-transcribe', // Default 'gpt-4o-transcribe', shut down on February 26, 2027
87
89
  language: 'en',
88
90
  })
89
91
 
@@ -123,6 +125,13 @@ See the [STT interface](https://micdrop.dev/docs/ai-integration/custom-integrati
123
125
 
124
126
  ## OpenAI TTS (Text-to-Speech)
125
127
 
128
+ Two ways to synthesize, picked by `model`:
129
+
130
+ - **Speech endpoint** (default): `gpt-4o-mini-tts`, its dated snapshots, `tts-1` and `tts-1-hd`. OpenAI [deprecated](https://developers.openai.com/api/docs/deprecations) all of them, and the endpoint shuts down on **January 6, 2027**. Until then, they work as before.
131
+ - **Realtime API**: `gpt-realtime-2.1-mini`, the replacement OpenAI names, recommended for new integrations. Each sentence is sent as an out-of-band response with instructions to read it word for word. The model is a voice model rather than a reader, so it can reword a sentence now and then (a contraction such as "I'm" for "I am"), and `OpenaiTTS` logs the transcript of any sentence it reads differently.
132
+
133
+ Either way, the incoming text is buffered into sentences and each sentence is synthesized as soon as it is complete, so playback can start without waiting for the whole answer.
134
+
126
135
  ### Usage with MicdropServer
127
136
 
128
137
  ```typescript
@@ -131,13 +140,16 @@ import { MicdropServer } from '@micdrop/server'
131
140
 
132
141
  const tts = new OpenaiTTS({
133
142
  apiKey: process.env.OPENAI_API_KEY || '',
134
- model: 'gpt-4o-mini-tts', // Default model
135
- voice: 'alloy', // Default voice
143
+ // Recommended: the speech endpoint models (default 'gpt-4o-mini-tts')
144
+ // shut down on January 6, 2027
145
+ model: 'gpt-realtime-2.1-mini',
146
+ voice: 'marin', // Default with gpt-realtime-*, 'alloy' otherwise
136
147
 
137
- // Prosody control, only for gpt-4o-mini-tts (optional)
148
+ // Delivery control, not for tts-1 / tts-1-hd (optional)
138
149
  instructions: 'Speak in a calm and friendly tone',
139
150
 
140
- // Speech speed from 0.25 to 4.0, only for tts-1 / tts-1-hd (optional)
151
+ // Speech speed: 0.25 to 1.5 with gpt-realtime-*, 0.25 to 4.0 with
152
+ // tts-1 / tts-1-hd (optional)
141
153
  // speed: 1,
142
154
  })
143
155
 
@@ -175,7 +187,9 @@ tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))
175
187
 
176
188
  See the [TTS interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-tts) for the full contract.
177
189
 
178
- > **Language**: OpenAI's speech API has no language parameter, the voice follows the language of the input text. To influence the spoken language or accent, use `instructions` (e.g. `'Speak in French'`) with the `gpt-4o-mini-tts` model.
190
+ > **Voices**: the Realtime API offers `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin` and `cedar`. `fable`, `nova` and `onyx` only exist on the speech endpoint.
191
+
192
+ > **Language**: neither the speech endpoint nor the Realtime API has a language parameter, the voice follows the language of the input text. To influence the accent, use `instructions` (e.g. `'Speak with a Parisian accent'`) with `gpt-realtime-*` or `gpt-4o-mini-tts`.
179
193
 
180
194
  ## OpenAI Realtime
181
195
 
package/dist/index.d.mts CHANGED
@@ -104,7 +104,9 @@ declare class OpenaiSTT extends STT {
104
104
  private socket?;
105
105
  private initPromise;
106
106
  private reconnectTimeout?;
107
+ private connectionTimeout?;
107
108
  private retryCount;
109
+ private destroyed;
108
110
  private transcriptionTimeout?;
109
111
  private audioChunksPending;
110
112
  private resampler;
@@ -123,22 +125,32 @@ declare class OpenaiSTT extends STT {
123
125
  * OpenAI Text-to-Speech
124
126
  *
125
127
  * @see https://platform.openai.com/docs/guides/text-to-speech
128
+ * @see https://developers.openai.com/api/docs/deprecations
129
+ *
130
+ * Two ways to synthesize, picked by the model:
131
+ * - tts-1, tts-1-hd and gpt-4o-mini-tts go through the speech endpoint, which
132
+ * OpenAI shuts down on January 6, 2027.
133
+ * - gpt-realtime-* models go through the Realtime API, see
134
+ * OpenaiRealtimeSpeech. gpt-realtime-2.1-mini is the replacement OpenAI
135
+ * names for the speech endpoint.
126
136
  *
127
- * The OpenAI speech endpoint takes a complete text input (no streaming text
128
- * in), so the incoming text stream is buffered into sentences and each
129
- * sentence is synthesized as soon as it is complete. Requests are processed
130
- * sequentially, which keeps the emitted audio in order while still starting
131
- * playback as soon as the first sentence is ready.
137
+ * Neither takes a text stream in, so the incoming text is buffered into
138
+ * sentences and each sentence is synthesized as soon as it is complete. The
139
+ * audio is emitted in the order the sentences were written, while playback
140
+ * still starts as soon as the first sentence is ready.
132
141
  */
133
142
  type OpenaiTTSOptions = OpenaiOptions & {
134
143
  model?: string;
135
144
  voice?: string;
136
145
  instructions?: string;
137
146
  speed?: number;
147
+ reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
148
+ connectionTimeout?: number;
138
149
  };
139
150
  declare class OpenaiTTS extends TTS {
140
151
  private readonly options;
141
- private openai;
152
+ private openai?;
153
+ private realtime?;
142
154
  private counter;
143
155
  private generation;
144
156
  private splitter;
@@ -147,15 +159,16 @@ declare class OpenaiTTS extends TTS {
147
159
  private cushion;
148
160
  private cushionBytes;
149
161
  private processing;
150
- private abortControllers;
162
+ private syntheses;
151
163
  constructor(options: OpenaiTTSOptions);
152
164
  speak(textStream: Readable): void;
153
165
  cancel(): void;
166
+ destroy(): void;
154
167
  private enqueue;
155
168
  /**
156
169
  * Starts what can be started, then speaks what is ready.
157
170
  *
158
- * The endpoint takes a few hundred milliseconds before its first byte, and
171
+ * A request takes a few hundred milliseconds before its first byte, and
159
172
  * waiting for that between two sentences leaves a silence in the middle of
160
173
  * her voice. It is loudest at the very start, where a greeting is often one
161
174
  * short sentence: a syllable, a hole, then the rest of the answer. Asking for
@@ -168,12 +181,16 @@ declare class OpenaiTTS extends TTS {
168
181
  private pump;
169
182
  /** Speaks the started requests in the order they were queued. */
170
183
  private drain;
171
- /** Asks for one sentence, without waiting for the answer. */
172
- private request;
184
+ /**
185
+ * Asks the speech endpoint for one sentence, without waiting for the answer.
186
+ *
187
+ * Only for tts-1, tts-1-hd and gpt-4o-mini-tts, until January 6, 2027.
188
+ */
189
+ private requestSpeech;
173
190
  /** Holds the opening of an utterance back, then lets the rest through. */
174
191
  private emitAudio;
175
192
  private flushCushion;
176
- /** Emits one sentence, whose request was started earlier. */
193
+ /** Emits one sentence as its audio arrives, from a request started earlier. */
177
194
  private speakItem;
178
195
  }
179
196
 
package/dist/index.d.ts CHANGED
@@ -104,7 +104,9 @@ declare class OpenaiSTT extends STT {
104
104
  private socket?;
105
105
  private initPromise;
106
106
  private reconnectTimeout?;
107
+ private connectionTimeout?;
107
108
  private retryCount;
109
+ private destroyed;
108
110
  private transcriptionTimeout?;
109
111
  private audioChunksPending;
110
112
  private resampler;
@@ -123,22 +125,32 @@ declare class OpenaiSTT extends STT {
123
125
  * OpenAI Text-to-Speech
124
126
  *
125
127
  * @see https://platform.openai.com/docs/guides/text-to-speech
128
+ * @see https://developers.openai.com/api/docs/deprecations
129
+ *
130
+ * Two ways to synthesize, picked by the model:
131
+ * - tts-1, tts-1-hd and gpt-4o-mini-tts go through the speech endpoint, which
132
+ * OpenAI shuts down on January 6, 2027.
133
+ * - gpt-realtime-* models go through the Realtime API, see
134
+ * OpenaiRealtimeSpeech. gpt-realtime-2.1-mini is the replacement OpenAI
135
+ * names for the speech endpoint.
126
136
  *
127
- * The OpenAI speech endpoint takes a complete text input (no streaming text
128
- * in), so the incoming text stream is buffered into sentences and each
129
- * sentence is synthesized as soon as it is complete. Requests are processed
130
- * sequentially, which keeps the emitted audio in order while still starting
131
- * playback as soon as the first sentence is ready.
137
+ * Neither takes a text stream in, so the incoming text is buffered into
138
+ * sentences and each sentence is synthesized as soon as it is complete. The
139
+ * audio is emitted in the order the sentences were written, while playback
140
+ * still starts as soon as the first sentence is ready.
132
141
  */
133
142
  type OpenaiTTSOptions = OpenaiOptions & {
134
143
  model?: string;
135
144
  voice?: string;
136
145
  instructions?: string;
137
146
  speed?: number;
147
+ reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
148
+ connectionTimeout?: number;
138
149
  };
139
150
  declare class OpenaiTTS extends TTS {
140
151
  private readonly options;
141
- private openai;
152
+ private openai?;
153
+ private realtime?;
142
154
  private counter;
143
155
  private generation;
144
156
  private splitter;
@@ -147,15 +159,16 @@ declare class OpenaiTTS extends TTS {
147
159
  private cushion;
148
160
  private cushionBytes;
149
161
  private processing;
150
- private abortControllers;
162
+ private syntheses;
151
163
  constructor(options: OpenaiTTSOptions);
152
164
  speak(textStream: Readable): void;
153
165
  cancel(): void;
166
+ destroy(): void;
154
167
  private enqueue;
155
168
  /**
156
169
  * Starts what can be started, then speaks what is ready.
157
170
  *
158
- * The endpoint takes a few hundred milliseconds before its first byte, and
171
+ * A request takes a few hundred milliseconds before its first byte, and
159
172
  * waiting for that between two sentences leaves a silence in the middle of
160
173
  * her voice. It is loudest at the very start, where a greeting is often one
161
174
  * short sentence: a syllable, a hole, then the rest of the answer. Asking for
@@ -168,12 +181,16 @@ declare class OpenaiTTS extends TTS {
168
181
  private pump;
169
182
  /** Speaks the started requests in the order they were queued. */
170
183
  private drain;
171
- /** Asks for one sentence, without waiting for the answer. */
172
- private request;
184
+ /**
185
+ * Asks the speech endpoint for one sentence, without waiting for the answer.
186
+ *
187
+ * Only for tts-1, tts-1-hd and gpt-4o-mini-tts, until January 6, 2027.
188
+ */
189
+ private requestSpeech;
173
190
  /** Holds the opening of an utterance back, then lets the rest through. */
174
191
  private emitAudio;
175
192
  private flushCushion;
176
- /** Emits one sentence, whose request was started earlier. */
193
+ /** Emits one sentence as its audio arrives, from a request started earlier. */
177
194
  private speakItem;
178
195
  }
179
196