@micdrop/gradium 1.1.2 → 1.3.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
@@ -1,6 +1,6 @@
1
1
  # @micdrop/gradium
2
2
 
3
- [Micdrop website](https://micdrop.dev) | [Documentation](https://micdrop.dev/docs/ai-integration/provided-integrations/gradium)
3
+ [Micdrop website](https://micdrop.dev) | [Documentation](https://micdrop.dev/docs/providers)
4
4
 
5
5
  Gradium STT and TTS implementation for [@micdrop/server](https://micdrop.dev/docs/server).
6
6
 
@@ -20,9 +20,9 @@ import { MicdropServer } from '@micdrop/server'
20
20
 
21
21
  const tts = new GradiumTTS({
22
22
  apiKey: process.env.GRADIUM_API_KEY || '',
23
- voiceId: 'YTpq7expH9539ERJ', // Gradium voice ID
23
+ voiceId: 'Bla6SbVMczYnOhfK', // Gradium voice ID
24
24
  modelName: 'default', // Optional: model name
25
- outputFormat: 'pcm_16000', // Optional: audio format
25
+ sampleRate: 24000, // Optional: 8000, 16000, 24000 or 48000 (default)
26
26
  region: 'eu', // Optional: 'eu' or 'us'
27
27
  jsonConfig: {
28
28
  // Optional: advanced voice settings
@@ -47,10 +47,10 @@ import { Readable } from 'stream'
47
47
 
48
48
  const tts = new GradiumTTS({
49
49
  apiKey: process.env.GRADIUM_API_KEY || '',
50
- voiceId: 'YTpq7expH9539ERJ',
50
+ voiceId: 'Bla6SbVMczYnOhfK',
51
51
  })
52
52
 
53
- // Audio is raw PCM, 16 bits, 16 kHz, mono
53
+ // Audio is raw PCM, 16 bits, mono, at tts.sampleRate
54
54
  tts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))
55
55
  tts.on('Failed', (texts) => console.error('Failed:', texts))
56
56
 
@@ -59,12 +59,12 @@ tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))
59
59
 
60
60
  ### Events
61
61
 
62
- | Event | Payload | Description |
63
- | -------- | ---------- | ------------------------------------------------------------------------ |
64
- | `Audio` | `Buffer` | A chunk of audio, PCM 16 bits, 16 kHz, mono, ready to be played. |
65
- | `Failed` | `string[]` | Synthesis gave up after its retries, with the text that stayed unspoken. |
62
+ | Event | Payload | Description |
63
+ | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
64
+ | `Audio` | `Buffer` | A chunk of audio, PCM 16 bits, mono, at `tts.sampleRate` (the `sampleRate` option, 48 kHz by default), ready to be played. |
65
+ | `Failed` | `string[]` | Gradium refused the request, or every reconnection attempt failed, with the text that stayed unspoken. The next utterance connects again. |
66
66
 
67
- See the [TTS interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-tts) for the full contract.
67
+ See the [TTS interface](https://micdrop.dev/docs/text-to-speech/custom) for the full contract.
68
68
 
69
69
  ## Gradium STT (Speech-to-Text)
70
70
 
@@ -111,16 +111,16 @@ stt.transcribe(createReadStream('speech.pcm'))
111
111
 
112
112
  ### Events
113
113
 
114
- | Event | Payload | Description |
115
- | ------------ | ---------- | ------------------------------------------------------------------------------ |
116
- | `Transcript` | `string` | Transcription of one utterance. The text is empty when nothing was recognized. |
117
- | `Failed` | `Buffer[]` | Transcription gave up after its retries, with the audio chunks left pending. |
114
+ | Event | Payload | Description |
115
+ | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
116
+ | `Transcript` | `string` | Transcription of one utterance, emitted once per utterance even when the next one starts before it returns. The text is empty when nothing was recognized. |
117
+ | `Failed` | `Buffer[]` | Every reconnection attempt failed, with the audio of the utterances still waiting for their transcript. The next utterance connects again. |
118
118
 
119
- See the [STT interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-stt) for the full contract.
119
+ See the [STT interface](https://micdrop.dev/docs/speech-to-text/custom) for the full contract.
120
120
 
121
121
  ## Documentation
122
122
 
123
- Read full [documentation of the Gradium integration for Micdrop](https://micdrop.dev/docs/ai-integration/provided-integrations/gradium) on the [website](https://micdrop.dev).
123
+ Read full [documentation of the Gradium integration for Micdrop](https://micdrop.dev/docs/providers) on the [website](https://micdrop.dev).
124
124
 
125
125
  ## License
126
126
 
package/dist/index.d.mts CHANGED
@@ -1,13 +1,24 @@
1
- import { STT, TTS } from '@micdrop/server';
1
+ import { STT, TTS, MicdropVoice } from '@micdrop/server';
2
2
  import { Readable } from 'stream';
3
3
 
4
4
  type GradiumOutputFormat = 'pcm' | 'wav' | 'opus' | 'ulaw_8000' | 'alaw_8000' | 'pcm_8000' | 'pcm_16000' | 'pcm_24000';
5
5
  type GradiumInputFormat = 'pcm' | 'pcm_8000' | 'pcm_16000' | 'pcm_24000' | 'pcm_48000' | 'wav' | 'opus' | 'ulaw_8000' | 'alaw_8000';
6
6
  type GradiumRegion = 'eu' | 'us';
7
+ /** Rates Gradium streams raw PCM at */
8
+ type GradiumSampleRate = 8000 | 16000 | 24000 | 48000;
7
9
  interface GradiumTTSOptions {
8
10
  apiKey: string;
9
11
  voiceId: string;
10
12
  modelName?: string;
13
+ /**
14
+ * Rate of the audio, in Hz, 48000 by default, the highest one offered. It
15
+ * goes to the client as is, so the voice is never resampled on the server.
16
+ */
17
+ sampleRate?: GradiumSampleRate;
18
+ /**
19
+ * @deprecated Use `sampleRate`. The client only plays raw PCM, so only `pcm`
20
+ * and the `pcm_*` formats work.
21
+ */
11
22
  outputFormat?: GradiumOutputFormat;
12
23
  region?: GradiumRegion;
13
24
  jsonConfig?: GradiumJsonConfig;
@@ -21,10 +32,16 @@ interface GradiumJsonConfig {
21
32
  cfg_coef?: number;
22
33
  }
23
34
  declare const DEFAULT_MODEL_NAME = "default";
35
+ declare const DEFAULT_SAMPLE_RATE: GradiumSampleRate;
36
+ /** @deprecated Use `DEFAULT_SAMPLE_RATE` */
24
37
  declare const DEFAULT_OUTPUT_FORMAT: GradiumOutputFormat;
25
38
  declare const DEFAULT_INPUT_FORMAT: GradiumInputFormat;
26
39
  declare const DEFAULT_REGION: GradiumRegion;
27
40
  declare const DEFAULT_LANGUAGE = "any";
41
+ /** The `output_format` asked of Gradium */
42
+ declare function getOutputFormat(options: GradiumTTSOptions): GradiumOutputFormat;
43
+ /** Rate of the audio Gradium sends, read from its `output_format` */
44
+ declare function getSampleRate(options: GradiumTTSOptions): number;
28
45
  interface GradiumASRJsonConfig {
29
46
  language?: string;
30
47
  target_language?: string;
@@ -125,65 +142,74 @@ interface GradiumErrorResponse {
125
142
 
126
143
  declare class GradiumSTT extends STT {
127
144
  private options;
128
- private socket?;
129
- private initPromise;
130
- private reconnectTimeout?;
131
- private connectionTimeout?;
132
- private transcriptionTimeout?;
133
- private audioChunksPending;
134
- private transcript;
145
+ private socket;
146
+ private utterances;
135
147
  private flushId;
136
148
  private delayInFrames;
137
- private retryCount;
138
- private destroyed;
139
149
  constructor(options: GradiumSTTOptions);
140
150
  transcribe(audioStream: Readable): void;
141
151
  destroy(): void;
142
- private connect;
143
- private getEndpoint;
144
- private initWS;
145
152
  private buildJsonConfig;
146
- private sendSetup;
153
+ /** Sends the setup, and waits for the server to accept it */
154
+ private handshake;
147
155
  private sendAudioChunk;
148
156
  /**
149
- * Follows the speech with as much silence as the transcription lags behind.
157
+ * Silence as long as the transcription lags behind, to follow the speech.
150
158
  *
151
159
  * The model writes each word a few frames after hearing it, and a flush only
152
160
  * processes the audio already sent. With nothing after the last word, the
153
161
  * server confirms the flush before writing that word, which then opens the
154
162
  * next transcript.
155
163
  */
156
- private sendTrailingSilence;
157
- private sendFlush;
164
+ private trailingSilence;
165
+ /** Sends the trailing silence, already the last audio chunk, and the flush */
166
+ private sendEnd;
158
167
  private emitTranscript;
159
- private handleMessage;
160
- private reconnect;
168
+ private onOpen;
169
+ private onMessage;
170
+ private onFailed;
161
171
  }
162
172
 
163
173
  declare class GradiumTTS extends TTS {
164
174
  private readonly options;
165
- private socket?;
166
- private initPromise;
175
+ /**
176
+ * Lists the voices the account can speak with: its own, then the Gradium
177
+ * catalog, over a thousand voices.
178
+ *
179
+ * `language`, such as `fr` or `fr-FR`, keeps the voices that speak it.
180
+ *
181
+ * The list is fetched once and shared by every call of the process for a
182
+ * day. `refresh` fetches it again, for a voice added a moment ago.
183
+ */
184
+ static listVoices(options: {
185
+ apiKey: string;
186
+ region?: GradiumRegion;
187
+ language?: string;
188
+ refresh?: boolean;
189
+ }): Promise<MicdropVoice[]>;
190
+ private socket;
167
191
  private counter;
168
192
  private generation;
169
- private isProcessing;
170
- private reconnectTimeout?;
171
- private connectionTimeout?;
172
- private textSent;
173
- private textBuffer;
174
- private retryCount;
175
- private destroyed;
193
+ private request?;
194
+ get sampleRate(): number;
176
195
  constructor(options: GradiumTTSOptions);
177
- private connect;
178
196
  speak(textStream: Readable): void;
197
+ /**
198
+ * Stops the current utterance. Gradium can only stop a synthesis by closing
199
+ * its connection, so a new one opens right away.
200
+ */
179
201
  cancel(): void;
180
202
  destroy(): void;
181
- private getEndpoint;
182
- private initWS;
203
+ /** Forgets the current request, and closes the connection that carries it */
204
+ private stopRequest;
183
205
  private sendSetup;
184
206
  private sendTranscript;
207
+ /** Sends the last partial word, then the end of the text */
208
+ private sendEnd;
209
+ private onOpen;
210
+ private onMessage;
185
211
  private processAudioMessage;
186
- private reconnect;
212
+ private onFailed;
187
213
  }
188
214
 
189
- export { DEFAULT_INPUT_FORMAT, DEFAULT_LANGUAGE, DEFAULT_MODEL_NAME, DEFAULT_OUTPUT_FORMAT, DEFAULT_REGION, type GradiumASRJsonConfig, type GradiumASRResponse, type GradiumASRSetupMessage, type GradiumAudioMessage, type GradiumAudioResponse, type GradiumEndTextResponse, type GradiumEosMessage, type GradiumEosResponse, type GradiumErrorResponse, type GradiumFlushMessage, type GradiumFlushedResponse, type GradiumInputFormat, type GradiumJsonConfig, type GradiumOutputFormat, type GradiumReadyResponse, type GradiumRegion, type GradiumResponse, GradiumSTT, type GradiumSTTOptions, type GradiumSetupMessage, type GradiumStepResponse, GradiumTTS, type GradiumTTSOptions, type GradiumTextMessage, type GradiumTextResponse };
215
+ export { DEFAULT_INPUT_FORMAT, DEFAULT_LANGUAGE, DEFAULT_MODEL_NAME, DEFAULT_OUTPUT_FORMAT, DEFAULT_REGION, DEFAULT_SAMPLE_RATE, type GradiumASRJsonConfig, type GradiumASRResponse, type GradiumASRSetupMessage, type GradiumAudioMessage, type GradiumAudioResponse, type GradiumEndTextResponse, type GradiumEosMessage, type GradiumEosResponse, type GradiumErrorResponse, type GradiumFlushMessage, type GradiumFlushedResponse, type GradiumInputFormat, type GradiumJsonConfig, type GradiumOutputFormat, type GradiumReadyResponse, type GradiumRegion, type GradiumResponse, GradiumSTT, type GradiumSTTOptions, type GradiumSampleRate, type GradiumSetupMessage, type GradiumStepResponse, GradiumTTS, type GradiumTTSOptions, type GradiumTextMessage, type GradiumTextResponse, getOutputFormat, getSampleRate };
package/dist/index.d.ts CHANGED
@@ -1,13 +1,24 @@
1
- import { STT, TTS } from '@micdrop/server';
1
+ import { STT, TTS, MicdropVoice } from '@micdrop/server';
2
2
  import { Readable } from 'stream';
3
3
 
4
4
  type GradiumOutputFormat = 'pcm' | 'wav' | 'opus' | 'ulaw_8000' | 'alaw_8000' | 'pcm_8000' | 'pcm_16000' | 'pcm_24000';
5
5
  type GradiumInputFormat = 'pcm' | 'pcm_8000' | 'pcm_16000' | 'pcm_24000' | 'pcm_48000' | 'wav' | 'opus' | 'ulaw_8000' | 'alaw_8000';
6
6
  type GradiumRegion = 'eu' | 'us';
7
+ /** Rates Gradium streams raw PCM at */
8
+ type GradiumSampleRate = 8000 | 16000 | 24000 | 48000;
7
9
  interface GradiumTTSOptions {
8
10
  apiKey: string;
9
11
  voiceId: string;
10
12
  modelName?: string;
13
+ /**
14
+ * Rate of the audio, in Hz, 48000 by default, the highest one offered. It
15
+ * goes to the client as is, so the voice is never resampled on the server.
16
+ */
17
+ sampleRate?: GradiumSampleRate;
18
+ /**
19
+ * @deprecated Use `sampleRate`. The client only plays raw PCM, so only `pcm`
20
+ * and the `pcm_*` formats work.
21
+ */
11
22
  outputFormat?: GradiumOutputFormat;
12
23
  region?: GradiumRegion;
13
24
  jsonConfig?: GradiumJsonConfig;
@@ -21,10 +32,16 @@ interface GradiumJsonConfig {
21
32
  cfg_coef?: number;
22
33
  }
23
34
  declare const DEFAULT_MODEL_NAME = "default";
35
+ declare const DEFAULT_SAMPLE_RATE: GradiumSampleRate;
36
+ /** @deprecated Use `DEFAULT_SAMPLE_RATE` */
24
37
  declare const DEFAULT_OUTPUT_FORMAT: GradiumOutputFormat;
25
38
  declare const DEFAULT_INPUT_FORMAT: GradiumInputFormat;
26
39
  declare const DEFAULT_REGION: GradiumRegion;
27
40
  declare const DEFAULT_LANGUAGE = "any";
41
+ /** The `output_format` asked of Gradium */
42
+ declare function getOutputFormat(options: GradiumTTSOptions): GradiumOutputFormat;
43
+ /** Rate of the audio Gradium sends, read from its `output_format` */
44
+ declare function getSampleRate(options: GradiumTTSOptions): number;
28
45
  interface GradiumASRJsonConfig {
29
46
  language?: string;
30
47
  target_language?: string;
@@ -125,65 +142,74 @@ interface GradiumErrorResponse {
125
142
 
126
143
  declare class GradiumSTT extends STT {
127
144
  private options;
128
- private socket?;
129
- private initPromise;
130
- private reconnectTimeout?;
131
- private connectionTimeout?;
132
- private transcriptionTimeout?;
133
- private audioChunksPending;
134
- private transcript;
145
+ private socket;
146
+ private utterances;
135
147
  private flushId;
136
148
  private delayInFrames;
137
- private retryCount;
138
- private destroyed;
139
149
  constructor(options: GradiumSTTOptions);
140
150
  transcribe(audioStream: Readable): void;
141
151
  destroy(): void;
142
- private connect;
143
- private getEndpoint;
144
- private initWS;
145
152
  private buildJsonConfig;
146
- private sendSetup;
153
+ /** Sends the setup, and waits for the server to accept it */
154
+ private handshake;
147
155
  private sendAudioChunk;
148
156
  /**
149
- * Follows the speech with as much silence as the transcription lags behind.
157
+ * Silence as long as the transcription lags behind, to follow the speech.
150
158
  *
151
159
  * The model writes each word a few frames after hearing it, and a flush only
152
160
  * processes the audio already sent. With nothing after the last word, the
153
161
  * server confirms the flush before writing that word, which then opens the
154
162
  * next transcript.
155
163
  */
156
- private sendTrailingSilence;
157
- private sendFlush;
164
+ private trailingSilence;
165
+ /** Sends the trailing silence, already the last audio chunk, and the flush */
166
+ private sendEnd;
158
167
  private emitTranscript;
159
- private handleMessage;
160
- private reconnect;
168
+ private onOpen;
169
+ private onMessage;
170
+ private onFailed;
161
171
  }
162
172
 
163
173
  declare class GradiumTTS extends TTS {
164
174
  private readonly options;
165
- private socket?;
166
- private initPromise;
175
+ /**
176
+ * Lists the voices the account can speak with: its own, then the Gradium
177
+ * catalog, over a thousand voices.
178
+ *
179
+ * `language`, such as `fr` or `fr-FR`, keeps the voices that speak it.
180
+ *
181
+ * The list is fetched once and shared by every call of the process for a
182
+ * day. `refresh` fetches it again, for a voice added a moment ago.
183
+ */
184
+ static listVoices(options: {
185
+ apiKey: string;
186
+ region?: GradiumRegion;
187
+ language?: string;
188
+ refresh?: boolean;
189
+ }): Promise<MicdropVoice[]>;
190
+ private socket;
167
191
  private counter;
168
192
  private generation;
169
- private isProcessing;
170
- private reconnectTimeout?;
171
- private connectionTimeout?;
172
- private textSent;
173
- private textBuffer;
174
- private retryCount;
175
- private destroyed;
193
+ private request?;
194
+ get sampleRate(): number;
176
195
  constructor(options: GradiumTTSOptions);
177
- private connect;
178
196
  speak(textStream: Readable): void;
197
+ /**
198
+ * Stops the current utterance. Gradium can only stop a synthesis by closing
199
+ * its connection, so a new one opens right away.
200
+ */
179
201
  cancel(): void;
180
202
  destroy(): void;
181
- private getEndpoint;
182
- private initWS;
203
+ /** Forgets the current request, and closes the connection that carries it */
204
+ private stopRequest;
183
205
  private sendSetup;
184
206
  private sendTranscript;
207
+ /** Sends the last partial word, then the end of the text */
208
+ private sendEnd;
209
+ private onOpen;
210
+ private onMessage;
185
211
  private processAudioMessage;
186
- private reconnect;
212
+ private onFailed;
187
213
  }
188
214
 
189
- export { DEFAULT_INPUT_FORMAT, DEFAULT_LANGUAGE, DEFAULT_MODEL_NAME, DEFAULT_OUTPUT_FORMAT, DEFAULT_REGION, type GradiumASRJsonConfig, type GradiumASRResponse, type GradiumASRSetupMessage, type GradiumAudioMessage, type GradiumAudioResponse, type GradiumEndTextResponse, type GradiumEosMessage, type GradiumEosResponse, type GradiumErrorResponse, type GradiumFlushMessage, type GradiumFlushedResponse, type GradiumInputFormat, type GradiumJsonConfig, type GradiumOutputFormat, type GradiumReadyResponse, type GradiumRegion, type GradiumResponse, GradiumSTT, type GradiumSTTOptions, type GradiumSetupMessage, type GradiumStepResponse, GradiumTTS, type GradiumTTSOptions, type GradiumTextMessage, type GradiumTextResponse };
215
+ export { DEFAULT_INPUT_FORMAT, DEFAULT_LANGUAGE, DEFAULT_MODEL_NAME, DEFAULT_OUTPUT_FORMAT, DEFAULT_REGION, DEFAULT_SAMPLE_RATE, type GradiumASRJsonConfig, type GradiumASRResponse, type GradiumASRSetupMessage, type GradiumAudioMessage, type GradiumAudioResponse, type GradiumEndTextResponse, type GradiumEosMessage, type GradiumEosResponse, type GradiumErrorResponse, type GradiumFlushMessage, type GradiumFlushedResponse, type GradiumInputFormat, type GradiumJsonConfig, type GradiumOutputFormat, type GradiumReadyResponse, type GradiumRegion, type GradiumResponse, GradiumSTT, type GradiumSTTOptions, type GradiumSampleRate, type GradiumSetupMessage, type GradiumStepResponse, GradiumTTS, type GradiumTTSOptions, type GradiumTextMessage, type GradiumTextResponse, getOutputFormat, getSampleRate };