@micdrop/gradium 1.1.1 → 1.2.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
@@ -12,7 +12,7 @@ npm install @micdrop/gradium
12
12
 
13
13
  ## Gradium TTS (Text-to-Speech)
14
14
 
15
- ### Usage
15
+ ### Usage with MicdropServer
16
16
 
17
17
  ```typescript
18
18
  import { GradiumTTS } from '@micdrop/gradium'
@@ -20,7 +20,7 @@ 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
25
  outputFormat: 'pcm_16000', // Optional: audio format
26
26
  region: 'eu', // Optional: 'eu' or 'us'
@@ -39,11 +39,38 @@ new MicdropServer(socket, {
39
39
  })
40
40
  ```
41
41
 
42
+ ### Usage without MicdropServer
43
+
44
+ ```typescript
45
+ import { GradiumTTS } from '@micdrop/gradium'
46
+ import { Readable } from 'stream'
47
+
48
+ const tts = new GradiumTTS({
49
+ apiKey: process.env.GRADIUM_API_KEY || '',
50
+ voiceId: 'Bla6SbVMczYnOhfK',
51
+ })
52
+
53
+ // Audio is raw PCM, 16 bits, 16 kHz, mono
54
+ tts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))
55
+ tts.on('Failed', (texts) => console.error('Failed:', texts))
56
+
57
+ tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))
58
+ ```
59
+
60
+ ### Events
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[]` | Gradium refused the request, or every reconnection attempt failed, with the text that stayed unspoken. The next utterance connects again. |
66
+
67
+ See the [TTS interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-tts) for the full contract.
68
+
42
69
  ## Gradium STT (Speech-to-Text)
43
70
 
44
71
  Real-time transcription (ASR).
45
72
 
46
- ### Usage
73
+ ### Usage with MicdropServer
47
74
 
48
75
  ```typescript
49
76
  import { GradiumSTT } from '@micdrop/gradium'
@@ -64,6 +91,33 @@ new MicdropServer(socket, {
64
91
  })
65
92
  ```
66
93
 
94
+ ### Usage without MicdropServer
95
+
96
+ ```typescript
97
+ import { GradiumSTT } from '@micdrop/gradium'
98
+ import { createReadStream } from 'fs'
99
+
100
+ const stt = new GradiumSTT({
101
+ apiKey: process.env.GRADIUM_API_KEY || '',
102
+ language: 'en',
103
+ })
104
+
105
+ stt.on('Transcript', (text) => console.log('Transcript:', text))
106
+ stt.on('Failed', (chunks) => console.error('Failed:', chunks.length, 'chunks'))
107
+
108
+ // Audio is raw PCM, 16 bits, 16 kHz, mono
109
+ stt.transcribe(createReadStream('speech.pcm'))
110
+ ```
111
+
112
+ ### Events
113
+
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
+
119
+ See the [STT interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-stt) for the full contract.
120
+
67
121
  ## Documentation
68
122
 
69
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).
package/dist/index.d.mts CHANGED
@@ -24,6 +24,7 @@ declare const DEFAULT_MODEL_NAME = "default";
24
24
  declare const DEFAULT_OUTPUT_FORMAT: GradiumOutputFormat;
25
25
  declare const DEFAULT_INPUT_FORMAT: GradiumInputFormat;
26
26
  declare const DEFAULT_REGION: GradiumRegion;
27
+ declare const DEFAULT_LANGUAGE = "any";
27
28
  interface GradiumASRJsonConfig {
28
29
  language?: string;
29
30
  target_language?: string;
@@ -105,6 +106,7 @@ type GradiumResponse = GradiumReadyResponse | GradiumAudioResponse | GradiumEosR
105
106
  interface GradiumReadyResponse {
106
107
  type: 'ready';
107
108
  request_id?: string;
109
+ delay_in_frames?: number;
108
110
  }
109
111
  interface GradiumAudioResponse {
110
112
  type: 'audio';
@@ -123,52 +125,58 @@ interface GradiumErrorResponse {
123
125
 
124
126
  declare class GradiumSTT extends STT {
125
127
  private options;
126
- private socket?;
127
- private initPromise;
128
- private reconnectTimeout?;
129
- private transcriptionTimeout?;
130
- private audioChunksPending;
131
- private transcript;
128
+ private socket;
129
+ private utterances;
132
130
  private flushId;
133
- private retryCount;
134
- private destroyed;
131
+ private delayInFrames;
135
132
  constructor(options: GradiumSTTOptions);
136
133
  transcribe(audioStream: Readable): void;
137
134
  destroy(): void;
138
- private connect;
139
- private getEndpoint;
140
- private initWS;
141
135
  private buildJsonConfig;
142
- private sendSetup;
136
+ /** Sends the setup, and waits for the server to accept it */
137
+ private handshake;
143
138
  private sendAudioChunk;
144
- private sendFlush;
139
+ /**
140
+ * Silence as long as the transcription lags behind, to follow the speech.
141
+ *
142
+ * The model writes each word a few frames after hearing it, and a flush only
143
+ * processes the audio already sent. With nothing after the last word, the
144
+ * server confirms the flush before writing that word, which then opens the
145
+ * next transcript.
146
+ */
147
+ private trailingSilence;
148
+ /** Sends the trailing silence, already the last audio chunk, and the flush */
149
+ private sendEnd;
145
150
  private emitTranscript;
146
- private handleMessage;
147
- private reconnect;
151
+ private onOpen;
152
+ private onMessage;
153
+ private onFailed;
148
154
  }
149
155
 
150
156
  declare class GradiumTTS extends TTS {
151
157
  private readonly options;
152
- private socket?;
153
- private initPromise;
158
+ private socket;
154
159
  private counter;
155
160
  private generation;
156
- private isProcessing;
157
- private reconnectTimeout?;
158
- private textSent;
159
- private textBuffer;
160
- private retryCount;
161
+ private request?;
161
162
  constructor(options: GradiumTTSOptions);
162
- private connect;
163
163
  speak(textStream: Readable): void;
164
+ /**
165
+ * Stops the current utterance. Gradium can only stop a synthesis by closing
166
+ * its connection, so a new one opens right away.
167
+ */
164
168
  cancel(): void;
165
169
  destroy(): void;
166
- private getEndpoint;
167
- private initWS;
170
+ /** Forgets the current request, and closes the connection that carries it */
171
+ private stopRequest;
168
172
  private sendSetup;
169
173
  private sendTranscript;
174
+ /** Sends the last partial word, then the end of the text */
175
+ private sendEnd;
176
+ private onOpen;
177
+ private onMessage;
170
178
  private processAudioMessage;
171
- private reconnect;
179
+ private onFailed;
172
180
  }
173
181
 
174
- export { DEFAULT_INPUT_FORMAT, 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 };
182
+ 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 };
package/dist/index.d.ts CHANGED
@@ -24,6 +24,7 @@ declare const DEFAULT_MODEL_NAME = "default";
24
24
  declare const DEFAULT_OUTPUT_FORMAT: GradiumOutputFormat;
25
25
  declare const DEFAULT_INPUT_FORMAT: GradiumInputFormat;
26
26
  declare const DEFAULT_REGION: GradiumRegion;
27
+ declare const DEFAULT_LANGUAGE = "any";
27
28
  interface GradiumASRJsonConfig {
28
29
  language?: string;
29
30
  target_language?: string;
@@ -105,6 +106,7 @@ type GradiumResponse = GradiumReadyResponse | GradiumAudioResponse | GradiumEosR
105
106
  interface GradiumReadyResponse {
106
107
  type: 'ready';
107
108
  request_id?: string;
109
+ delay_in_frames?: number;
108
110
  }
109
111
  interface GradiumAudioResponse {
110
112
  type: 'audio';
@@ -123,52 +125,58 @@ interface GradiumErrorResponse {
123
125
 
124
126
  declare class GradiumSTT extends STT {
125
127
  private options;
126
- private socket?;
127
- private initPromise;
128
- private reconnectTimeout?;
129
- private transcriptionTimeout?;
130
- private audioChunksPending;
131
- private transcript;
128
+ private socket;
129
+ private utterances;
132
130
  private flushId;
133
- private retryCount;
134
- private destroyed;
131
+ private delayInFrames;
135
132
  constructor(options: GradiumSTTOptions);
136
133
  transcribe(audioStream: Readable): void;
137
134
  destroy(): void;
138
- private connect;
139
- private getEndpoint;
140
- private initWS;
141
135
  private buildJsonConfig;
142
- private sendSetup;
136
+ /** Sends the setup, and waits for the server to accept it */
137
+ private handshake;
143
138
  private sendAudioChunk;
144
- private sendFlush;
139
+ /**
140
+ * Silence as long as the transcription lags behind, to follow the speech.
141
+ *
142
+ * The model writes each word a few frames after hearing it, and a flush only
143
+ * processes the audio already sent. With nothing after the last word, the
144
+ * server confirms the flush before writing that word, which then opens the
145
+ * next transcript.
146
+ */
147
+ private trailingSilence;
148
+ /** Sends the trailing silence, already the last audio chunk, and the flush */
149
+ private sendEnd;
145
150
  private emitTranscript;
146
- private handleMessage;
147
- private reconnect;
151
+ private onOpen;
152
+ private onMessage;
153
+ private onFailed;
148
154
  }
149
155
 
150
156
  declare class GradiumTTS extends TTS {
151
157
  private readonly options;
152
- private socket?;
153
- private initPromise;
158
+ private socket;
154
159
  private counter;
155
160
  private generation;
156
- private isProcessing;
157
- private reconnectTimeout?;
158
- private textSent;
159
- private textBuffer;
160
- private retryCount;
161
+ private request?;
161
162
  constructor(options: GradiumTTSOptions);
162
- private connect;
163
163
  speak(textStream: Readable): void;
164
+ /**
165
+ * Stops the current utterance. Gradium can only stop a synthesis by closing
166
+ * its connection, so a new one opens right away.
167
+ */
164
168
  cancel(): void;
165
169
  destroy(): void;
166
- private getEndpoint;
167
- private initWS;
170
+ /** Forgets the current request, and closes the connection that carries it */
171
+ private stopRequest;
168
172
  private sendSetup;
169
173
  private sendTranscript;
174
+ /** Sends the last partial word, then the end of the text */
175
+ private sendEnd;
176
+ private onOpen;
177
+ private onMessage;
170
178
  private processAudioMessage;
171
- private reconnect;
179
+ private onFailed;
172
180
  }
173
181
 
174
- export { DEFAULT_INPUT_FORMAT, 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 };
182
+ 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 };