@micdrop/openai 1.5.2 → 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
@@ -125,22 +125,32 @@ declare class OpenaiSTT extends STT {
125
125
  * OpenAI Text-to-Speech
126
126
  *
127
127
  * @see https://platform.openai.com/docs/guides/text-to-speech
128
+ * @see https://developers.openai.com/api/docs/deprecations
128
129
  *
129
- * The OpenAI speech endpoint takes a complete text input (no streaming text
130
- * in), so the incoming text stream is buffered into sentences and each
131
- * sentence is synthesized as soon as it is complete. Requests are processed
132
- * sequentially, which keeps the emitted audio in order while still starting
133
- * playback as soon as the first sentence is ready.
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.
136
+ *
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.
134
141
  */
135
142
  type OpenaiTTSOptions = OpenaiOptions & {
136
143
  model?: string;
137
144
  voice?: string;
138
145
  instructions?: string;
139
146
  speed?: number;
147
+ reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
148
+ connectionTimeout?: number;
140
149
  };
141
150
  declare class OpenaiTTS extends TTS {
142
151
  private readonly options;
143
- private openai;
152
+ private openai?;
153
+ private realtime?;
144
154
  private counter;
145
155
  private generation;
146
156
  private splitter;
@@ -149,15 +159,16 @@ declare class OpenaiTTS extends TTS {
149
159
  private cushion;
150
160
  private cushionBytes;
151
161
  private processing;
152
- private abortControllers;
162
+ private syntheses;
153
163
  constructor(options: OpenaiTTSOptions);
154
164
  speak(textStream: Readable): void;
155
165
  cancel(): void;
166
+ destroy(): void;
156
167
  private enqueue;
157
168
  /**
158
169
  * Starts what can be started, then speaks what is ready.
159
170
  *
160
- * 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
161
172
  * waiting for that between two sentences leaves a silence in the middle of
162
173
  * her voice. It is loudest at the very start, where a greeting is often one
163
174
  * short sentence: a syllable, a hole, then the rest of the answer. Asking for
@@ -170,12 +181,16 @@ declare class OpenaiTTS extends TTS {
170
181
  private pump;
171
182
  /** Speaks the started requests in the order they were queued. */
172
183
  private drain;
173
- /** Asks for one sentence, without waiting for the answer. */
174
- 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;
175
190
  /** Holds the opening of an utterance back, then lets the rest through. */
176
191
  private emitAudio;
177
192
  private flushCushion;
178
- /** Emits one sentence, whose request was started earlier. */
193
+ /** Emits one sentence as its audio arrives, from a request started earlier. */
179
194
  private speakItem;
180
195
  }
181
196
 
package/dist/index.d.ts CHANGED
@@ -125,22 +125,32 @@ declare class OpenaiSTT extends STT {
125
125
  * OpenAI Text-to-Speech
126
126
  *
127
127
  * @see https://platform.openai.com/docs/guides/text-to-speech
128
+ * @see https://developers.openai.com/api/docs/deprecations
128
129
  *
129
- * The OpenAI speech endpoint takes a complete text input (no streaming text
130
- * in), so the incoming text stream is buffered into sentences and each
131
- * sentence is synthesized as soon as it is complete. Requests are processed
132
- * sequentially, which keeps the emitted audio in order while still starting
133
- * playback as soon as the first sentence is ready.
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.
136
+ *
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.
134
141
  */
135
142
  type OpenaiTTSOptions = OpenaiOptions & {
136
143
  model?: string;
137
144
  voice?: string;
138
145
  instructions?: string;
139
146
  speed?: number;
147
+ reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
148
+ connectionTimeout?: number;
140
149
  };
141
150
  declare class OpenaiTTS extends TTS {
142
151
  private readonly options;
143
- private openai;
152
+ private openai?;
153
+ private realtime?;
144
154
  private counter;
145
155
  private generation;
146
156
  private splitter;
@@ -149,15 +159,16 @@ declare class OpenaiTTS extends TTS {
149
159
  private cushion;
150
160
  private cushionBytes;
151
161
  private processing;
152
- private abortControllers;
162
+ private syntheses;
153
163
  constructor(options: OpenaiTTSOptions);
154
164
  speak(textStream: Readable): void;
155
165
  cancel(): void;
166
+ destroy(): void;
156
167
  private enqueue;
157
168
  /**
158
169
  * Starts what can be started, then speaks what is ready.
159
170
  *
160
- * 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
161
172
  * waiting for that between two sentences leaves a silence in the middle of
162
173
  * her voice. It is loudest at the very start, where a greeting is often one
163
174
  * short sentence: a syllable, a hole, then the rest of the answer. Asking for
@@ -170,12 +181,16 @@ declare class OpenaiTTS extends TTS {
170
181
  private pump;
171
182
  /** Speaks the started requests in the order they were queued. */
172
183
  private drain;
173
- /** Asks for one sentence, without waiting for the answer. */
174
- 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;
175
190
  /** Holds the opening of an utterance back, then lets the rest through. */
176
191
  private emitAudio;
177
192
  private flushCushion;
178
- /** Emits one sentence, whose request was started earlier. */
193
+ /** Emits one sentence as its audio arrives, from a request started earlier. */
179
194
  private speakItem;
180
195
  }
181
196