@micdrop/elevenlabs 1.1.3 → 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
@@ -2,7 +2,7 @@
2
2
 
3
3
  [Micdrop website](https://micdrop.dev) | [Documentation](https://micdrop.dev/docs/ai-integration/provided-integrations/elevenlabs)
4
4
 
5
- ElevenLabs implementation for [@micdrop/server](https://micdrop.dev/docs/server).
5
+ `@micdrop/elevenlabs` streams ElevenLabs text to speech for [@micdrop/server](https://micdrop.dev/docs/server). It works with Eleven v4 Turbo, Eleven v4, Eleven v3, Flash v2.5, Turbo v2.5 and Multilingual v2, and picks the WebSocket each model needs.
6
6
 
7
7
  ## Installation
8
8
 
@@ -12,7 +12,7 @@ npm install @micdrop/elevenlabs
12
12
 
13
13
  ## ElevenLabs TTS (Text-to-Speech)
14
14
 
15
- ### Usage
15
+ ### Usage with MicdropServer
16
16
 
17
17
  ```typescript
18
18
  import { ElevenLabsTTS } from '@micdrop/elevenlabs'
@@ -21,12 +21,10 @@ import { MicdropServer } from '@micdrop/server'
21
21
  const tts = new ElevenLabsTTS({
22
22
  apiKey: process.env.ELEVENLABS_API_KEY || '',
23
23
  voiceId: '21m00Tcm4TlvDq8ikWAM', // ElevenLabs voice ID
24
- modelId: 'eleven_turbo_v2_5', // Optional: model to use
24
+ modelId: 'eleven_v4_turbo', // Optional: model to use
25
25
  language: 'en', // Optional: language code
26
26
  voiceSettings: {
27
27
  stability: 0.5,
28
- similarity_boost: 0.75,
29
- style: 0.5,
30
28
  },
31
29
  })
32
30
 
@@ -37,6 +35,46 @@ new MicdropServer(socket, {
37
35
  })
38
36
  ```
39
37
 
38
+ ### Usage without MicdropServer
39
+
40
+ ```typescript
41
+ import { ElevenLabsTTS } from '@micdrop/elevenlabs'
42
+ import { Readable } from 'stream'
43
+
44
+ const tts = new ElevenLabsTTS({
45
+ apiKey: process.env.ELEVENLABS_API_KEY || '',
46
+ voiceId: '21m00Tcm4TlvDq8ikWAM',
47
+ })
48
+
49
+ // Audio is raw PCM, 16 bits, 16 kHz, mono
50
+ tts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))
51
+ tts.on('Failed', (texts) => console.error('Failed:', texts))
52
+
53
+ tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))
54
+ ```
55
+
56
+ ### Events
57
+
58
+ | Event | Payload | Description |
59
+ | -------- | ---------- | ------------------------------------------------------------------------ |
60
+ | `Audio` | `Buffer` | A chunk of audio, PCM 16 bits, 16 kHz, mono, ready to be played. |
61
+ | `Failed` | `string[]` | The text left unspoken when `ElevenLabsTTS` gives up after its retries. |
62
+
63
+ See the [TTS interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-tts) for the full contract.
64
+
65
+ ### Models
66
+
67
+ | Model | WebSocket | Audio tags |
68
+ | -------------------------------------------------------------- | ---------------- | ---------- |
69
+ | `eleven_v4_turbo`, `eleven_v4`, `eleven_v3_conversational`, `eleven_v3` | Text to Dialogue | Performed |
70
+ | `eleven_flash_v2_5`, `eleven_multilingual_v2`, `eleven_turbo_v2_5` | Text to Speech | Read out |
71
+
72
+ `eleven_turbo_v2_5` is the default. An LLM can write audio tags such as `[whispers]` or `[laughs]` into its answers. Eleven v3 and v4 perform them, while the other models read them out loud.
73
+
74
+ `voiceSettings` takes the `VoiceSettings` type of the ElevenLabs SDK, with its keys in camel case. Eleven v3 and v4 only read its `stability`.
75
+
76
+ ElevenLabs counts each open connection to the Text to Dialogue WebSocket as one of the [dialogue sessions your plan allows at once](https://elevenlabs.io/docs/overview/models#text-to-dialogue-concurrency), so each call holds one session from start to end.
77
+
40
78
  ## Documentation
41
79
 
42
80
  Read full [documentation of the ElevenLabs integration for Micdrop](https://micdrop.dev/docs/ai-integration/provided-integrations/elevenlabs) on the [website](https://micdrop.dev).
@@ -47,4 +85,4 @@ MIT
47
85
 
48
86
  ## Author
49
87
 
50
- Originally developed for [Raconte.ai](https://www.raconte.ai) and open sourced by [Lonestone](https://www.lonestone.io) ([GitHub](https://github.com/lonestone))
88
+ Originally developed for [Raconte.ai](https://www.raconte.ai), created and open sourced by [Godefroy de Compreignac](https://github.com/Godefroy)
package/dist/index.d.mts CHANGED
@@ -2,10 +2,11 @@ import { TTS } from '@micdrop/server';
2
2
  import { Readable } from 'stream';
3
3
  import { TextToSpeechStreamRequestOutputFormat, VoiceSettings } from '@elevenlabs/elevenlabs-js/api';
4
4
 
5
+ type ElevenLabsModelId = 'eleven_v4_turbo' | 'eleven_v4' | 'eleven_v3_conversational' | 'eleven_v3' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_turbo_v2_5';
5
6
  interface ElevenLabsTTSOptions {
6
7
  apiKey: string;
7
8
  voiceId: string;
8
- modelId?: 'eleven_multilingual_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2_5';
9
+ modelId?: ElevenLabsModelId;
9
10
  language?: string;
10
11
  outputFormat?: TextToSpeechStreamRequestOutputFormat;
11
12
  voiceSettings?: VoiceSettings;
@@ -15,6 +16,8 @@ interface ElevenLabsTTSOptions {
15
16
  }
16
17
  declare const DEFAULT_MODEL_ID = "eleven_turbo_v2_5";
17
18
  declare const DEFAULT_OUTPUT_FORMAT = "pcm_16000";
19
+ /** Eleven v3 and v4 only run on the Text to Dialogue WebSocket */
20
+ declare function isDialogueModel(modelId: string): boolean;
18
21
  type ElevenLabsWebSocketMessage = ElevenLabsWebSocketAudioOutputMessage | ElevenLabsWebSocketFinalOutputMessage | ElevenLabsWebSocketErrorMessage;
19
22
  interface ElevenLabsWebSocketAudioOutputMessage {
20
23
  audio: string;
@@ -35,30 +38,41 @@ interface ElevenLabsWebSocketErrorMessage {
35
38
  error: string;
36
39
  code: number;
37
40
  }
41
+ interface ElevenLabsDialogueClientMessage {
42
+ voices?: string[];
43
+ voice_settings?: {
44
+ stability?: number;
45
+ };
46
+ inputs?: ElevenLabsDialogueInput[];
47
+ flush?: boolean;
48
+ keep_alive?: boolean;
49
+ }
50
+ interface ElevenLabsDialogueInput {
51
+ text: string;
52
+ voice_id: string;
53
+ new_turn?: boolean;
54
+ }
55
+ type ElevenLabsDialogueMessage = {
56
+ audio: string;
57
+ } | {
58
+ is_final_audio_for_turn: boolean;
59
+ } | {
60
+ is_final: boolean;
61
+ } | ElevenLabsWebSocketErrorMessage;
38
62
 
63
+ /**
64
+ * ElevenLabs text to speech, streamed over the WebSocket the model runs on.
65
+ *
66
+ * Eleven v3 and v4 only answer on the Text to Dialogue WebSocket, the other
67
+ * models on the Text to Speech WebSocket. The two speak different protocols,
68
+ * so the model picks the one this class drives.
69
+ */
39
70
  declare class ElevenLabsTTS extends TTS {
40
- private readonly options;
41
- private socket?;
42
- private initPromise;
43
- private isProcessing;
44
- private textEnded;
45
- private textSent;
46
- private textBuffer;
47
- private receivedAudioText;
48
- private keepAliveInterval?;
49
- private reconnectTimeout?;
50
- private retryCount;
51
- private canceled;
71
+ private readonly webSocket;
52
72
  constructor(options: ElevenLabsTTSOptions);
53
73
  speak(textStream: Readable): void;
54
74
  cancel(): void;
55
75
  destroy(): void;
56
- private initWS;
57
- private onMessage;
58
- private processAudioMessage;
59
- private fixIsFinal;
60
- private sendTranscript;
61
- private reconnect;
62
76
  }
63
77
 
64
- export { DEFAULT_MODEL_ID, DEFAULT_OUTPUT_FORMAT, ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketAudioOutputMessage, type ElevenLabsWebSocketAudioOutputMessageAlignment, type ElevenLabsWebSocketErrorMessage, type ElevenLabsWebSocketFinalOutputMessage, type ElevenLabsWebSocketMessage };
78
+ export { DEFAULT_MODEL_ID, DEFAULT_OUTPUT_FORMAT, type ElevenLabsDialogueClientMessage, type ElevenLabsDialogueInput, type ElevenLabsDialogueMessage, type ElevenLabsModelId, ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketAudioOutputMessage, type ElevenLabsWebSocketAudioOutputMessageAlignment, type ElevenLabsWebSocketErrorMessage, type ElevenLabsWebSocketFinalOutputMessage, type ElevenLabsWebSocketMessage, isDialogueModel };
package/dist/index.d.ts CHANGED
@@ -2,10 +2,11 @@ import { TTS } from '@micdrop/server';
2
2
  import { Readable } from 'stream';
3
3
  import { TextToSpeechStreamRequestOutputFormat, VoiceSettings } from '@elevenlabs/elevenlabs-js/api';
4
4
 
5
+ type ElevenLabsModelId = 'eleven_v4_turbo' | 'eleven_v4' | 'eleven_v3_conversational' | 'eleven_v3' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_turbo_v2_5';
5
6
  interface ElevenLabsTTSOptions {
6
7
  apiKey: string;
7
8
  voiceId: string;
8
- modelId?: 'eleven_multilingual_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2_5';
9
+ modelId?: ElevenLabsModelId;
9
10
  language?: string;
10
11
  outputFormat?: TextToSpeechStreamRequestOutputFormat;
11
12
  voiceSettings?: VoiceSettings;
@@ -15,6 +16,8 @@ interface ElevenLabsTTSOptions {
15
16
  }
16
17
  declare const DEFAULT_MODEL_ID = "eleven_turbo_v2_5";
17
18
  declare const DEFAULT_OUTPUT_FORMAT = "pcm_16000";
19
+ /** Eleven v3 and v4 only run on the Text to Dialogue WebSocket */
20
+ declare function isDialogueModel(modelId: string): boolean;
18
21
  type ElevenLabsWebSocketMessage = ElevenLabsWebSocketAudioOutputMessage | ElevenLabsWebSocketFinalOutputMessage | ElevenLabsWebSocketErrorMessage;
19
22
  interface ElevenLabsWebSocketAudioOutputMessage {
20
23
  audio: string;
@@ -35,30 +38,41 @@ interface ElevenLabsWebSocketErrorMessage {
35
38
  error: string;
36
39
  code: number;
37
40
  }
41
+ interface ElevenLabsDialogueClientMessage {
42
+ voices?: string[];
43
+ voice_settings?: {
44
+ stability?: number;
45
+ };
46
+ inputs?: ElevenLabsDialogueInput[];
47
+ flush?: boolean;
48
+ keep_alive?: boolean;
49
+ }
50
+ interface ElevenLabsDialogueInput {
51
+ text: string;
52
+ voice_id: string;
53
+ new_turn?: boolean;
54
+ }
55
+ type ElevenLabsDialogueMessage = {
56
+ audio: string;
57
+ } | {
58
+ is_final_audio_for_turn: boolean;
59
+ } | {
60
+ is_final: boolean;
61
+ } | ElevenLabsWebSocketErrorMessage;
38
62
 
63
+ /**
64
+ * ElevenLabs text to speech, streamed over the WebSocket the model runs on.
65
+ *
66
+ * Eleven v3 and v4 only answer on the Text to Dialogue WebSocket, the other
67
+ * models on the Text to Speech WebSocket. The two speak different protocols,
68
+ * so the model picks the one this class drives.
69
+ */
39
70
  declare class ElevenLabsTTS extends TTS {
40
- private readonly options;
41
- private socket?;
42
- private initPromise;
43
- private isProcessing;
44
- private textEnded;
45
- private textSent;
46
- private textBuffer;
47
- private receivedAudioText;
48
- private keepAliveInterval?;
49
- private reconnectTimeout?;
50
- private retryCount;
51
- private canceled;
71
+ private readonly webSocket;
52
72
  constructor(options: ElevenLabsTTSOptions);
53
73
  speak(textStream: Readable): void;
54
74
  cancel(): void;
55
75
  destroy(): void;
56
- private initWS;
57
- private onMessage;
58
- private processAudioMessage;
59
- private fixIsFinal;
60
- private sendTranscript;
61
- private reconnect;
62
76
  }
63
77
 
64
- export { DEFAULT_MODEL_ID, DEFAULT_OUTPUT_FORMAT, ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketAudioOutputMessage, type ElevenLabsWebSocketAudioOutputMessageAlignment, type ElevenLabsWebSocketErrorMessage, type ElevenLabsWebSocketFinalOutputMessage, type ElevenLabsWebSocketMessage };
78
+ export { DEFAULT_MODEL_ID, DEFAULT_OUTPUT_FORMAT, type ElevenLabsDialogueClientMessage, type ElevenLabsDialogueInput, type ElevenLabsDialogueMessage, type ElevenLabsModelId, ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketAudioOutputMessage, type ElevenLabsWebSocketAudioOutputMessageAlignment, type ElevenLabsWebSocketErrorMessage, type ElevenLabsWebSocketFinalOutputMessage, type ElevenLabsWebSocketMessage, isDialogueModel };