@andresaya/edge-tts 1.2.7 → 1.3.1

package/README.md

@@ -6,13 +6,16 @@
 
 - **Text-to-Speech**: Convert text into natural-sounding speech using Microsoft Edge's TTS capabilities.
 - **Multiple Voices**: Access a variety of voices to suit your project's needs.
+- **Voice Filtering**: Filter voices by language and gender for better selection.
+- **Audio Information**: Get detailed information about generated audio (size, duration, format).
 - **Audio Export Options**: Export synthesized audio in different formats (raw, base64, or directly to a file).
+- **Streaming Support**: Stream audio data in real-time for better performance.
 - **Command-Line Interface**: Use a simple CLI for easy access to functionality.
 - **Easy Integration**: Modular structure allows for easy inclusion in existing projects.
 
 ## Installation
 
-You can install Edge TTS via npm. Run the following command in your terminal:
+You can install Edge TTS via npm or bun:
 
 ```bash
 bun add @andresaya/edge-tts
@@ -21,63 +24,288 @@ bun add @andresaya/edge-tts
 npm install @andresaya/edge-tts
 ```
 
-
 ## Usage
-Command-Line Interface
 
-You can install Edge TTS via npm. bun  Run the following command in your terminal:
+### Command-Line Interface
+
+Install globally to use the CLI:
 
 ```bash
 npm install -g @andresaya/edge-tts
 ```
 
-To synthesize speech from text, use the following command:
+To synthesize speech from text:
 ```bash
 edge-tts synthesize -t "Hello, world!" -o hello_world_audio
 ```
 
-To list available voices, run:
-
+To list available voices:
 ```bash
 edge-tts voice-list
 ```
 
-Integration into Your Project
-To use Edge TTS in your Bun project, you can import it like this:
+### Integration into Your Project
 
 ```js
 import { EdgeTTS } from '@andresaya/edge-tts';
 
 // Initialize the EdgeTTS service
 const tts = new EdgeTTS();
+```
+
+## API Reference
 
-// Get voices
-const voices = await tts.getVoices();  
-console.log(voices);  // Display available voices
+### Voice Management
+
+#### Get All Voices
+```js
+const voices = await tts.getVoices();
+console.log(`Found ${voices.length} voices`);
+```
+
+#### Filter Voices by Language
+```js
+// Get all English voices
+const englishVoices = await tts.getVoicesByLanguage('en');
+
+// Get specific locale voices
+const usEnglishVoices = await tts.getVoicesByLanguage('en-US');
+```
+
+#### Filter Voices by Gender
+```js
+// Get all female voices
+const femaleVoices = await tts.getVoicesByGender('Female');
+
+// Get all male voices
+const maleVoices = await tts.getVoicesByGender('Male');
+```
+
+### Text Synthesis
+
+#### Basic Synthesis
+```js
+// Simple synthesis with default voice
+await tts.synthesize("Hello, world!");
 
-// Synthesize text with options for voice, rate, volume, and pitch
+// Synthesis with specific voice
+await tts.synthesize("Hello, world!", 'en-US-AriaNeural');
+```
+
+#### Advanced Synthesis with Options
+```js
 await tts.synthesize("Hello, world!", 'en-US-AriaNeural', {
-    rate: '0%',       // Speech rate (range: -100% to 100%)
-    volume: '0%',     // Speech volume (range: -100% to 100%)
-    pitch: '0Hz'      // Voice pitch (range: -100Hz to 100Hz)
+    rate: '50%',      // Speech rate: -100% to +200% (or number)
+    volume: '90%',    // Speech volume: -100% to +100% (or number)
+    pitch: '+20Hz'    // Voice pitch: -100Hz to +100Hz (or number)
 });
+```
 
-// Export synthesized audio in different formats
-tts.toBase64();   // Get audio as base64
-await tts.toFile("output_audio");       // Save audio to file
-await tts.toRaw();         // Get raw audio buffer
+#### Streaming Synthesis
+```js
+// Stream audio data in real-time
+for await (const chunk of tts.synthesizeStream("Long text to stream...", 'en-US-AriaNeural')) {
+    // Process each audio chunk as it arrives
+    console.log(`Received chunk: ${chunk.length} bytes`);
+}
 ```
 
-## Export Options
-After synthesizing speech, you can export the audio in various formats:
+### Audio Information
 
-- `toBase64`: Returns the audio as a Base64 string.
-- `toFile`: Saves the audio to a specified file (e.g., "output.wav").
-- `toRaw`: Returns the raw audio stream.
+#### Get Audio Details
+```js
+await tts.synthesize("Hello, world!");
 
-## PHP Version
-If you want to use Edge TTS with PHP, you can check out the PHP version of this package, [Edge TTS PHP](https://github.com/andresayac/edge-tts-php)
+const audioInfo = tts.getAudioInfo();
+console.log(`Size: ${audioInfo.size} bytes`);
+console.log(`Format: ${audioInfo.format}`);
+console.log(`Duration: ${audioInfo.estimatedDuration} seconds`);
+```
+
+#### Get Duration Only
+```js
+const duration = tts.getDuration();
+console.log(`Audio duration: ${duration} seconds`);
+```
+
+### Export Options
+
+#### Export as Base64
+```js
+await tts.synthesize("Hello, world!");
+const base64Audio = tts.toBase64();
+console.log(`Base64 length: ${base64Audio.length}`);
+```
+
+#### Export as Raw Buffer
+```js
+const rawAudio = tts.toRaw(); // Alias for toBase64()
+const buffer = tts.toBuffer(); // Get as Buffer object
+```
 
+#### Export to File
+```js
+const filePath = await tts.toFile("output_audio");
+console.log(`Audio saved to: ${filePath}`);
+// Creates: output_audio.mp3
+```
+
+## Examples
+
+### Complete Example with Voice Selection
+```js
+import { EdgeTTS } from '@andresaya/edge-tts';
+
+async function textToSpeechExample() {
+    const tts = new EdgeTTS();
+    
+    // Get available English voices
+    const englishVoices = await tts.getVoicesByLanguage('en-US');
+    console.log(`Available English voices: ${englishVoices.length}`);
+    
+    // Use the first available voice
+    const voice = englishVoices[0];
+    console.log(`Using voice: ${voice.FriendlyName}`);
+    
+    // Synthesize with custom options
+    await tts.synthesize(
+        "This is a test of the Edge TTS system with custom voice parameters.",
+        voice.ShortName,
+        {
+            pitch: '+10Hz',
+            rate: '-10%',
+            volume: '90%'
+        }
+    );
+    
+    // Get audio information
+    const info = tts.getAudioInfo();
+    console.log(`Generated audio: ${info.size} bytes, ${info.estimatedDuration.toFixed(2)}s`);
+    
+    // Save to file
+    const outputPath = await tts.toFile('./output/speech');
+    console.log(`Audio saved to: ${outputPath}`);
+}
+
+textToSpeechExample().catch(console.error);
+```
+
+### Streaming Example
+```js
+import { EdgeTTS } from '@andresaya/edge-tts';
+import { createWriteStream } from 'fs';
+
+async function streamingExample() {
+    const tts = new EdgeTTS();
+    const writeStream = createWriteStream('streaming_output.mp3');
+    
+    const longText = "This is a very long text that will be streamed...";
+    
+    for await (const chunk of tts.synthesizeStream(longText, 'en-US-AriaNeural')) {
+        writeStream.write(chunk);
+        console.log(`Streamed ${chunk.length} bytes`);
+    }
+    
+    writeStream.end();
+    console.log('Streaming completed!');
+}
+
+streamingExample().catch(console.error);
+```
+
+### Voice Exploration Example
+```js
+import { EdgeTTS } from '@andresaya/edge-tts';
+
+async function exploreVoices() {
+    const tts = new EdgeTTS();
+    
+    // Get all voices
+    const allVoices = await tts.getVoices();
+    console.log(`Total voices available: ${allVoices.length}`);
+    
+    // Group by language
+    const languages = [...new Set(allVoices.map(v => v.Locale.split('-')[0]))];
+    console.log(`Languages available: ${languages.join(', ')}`);
+    
+    // Get Spanish voices
+    const spanishVoices = await tts.getVoicesByLanguage('es');
+    console.log(`Spanish voices: ${spanishVoices.length}`);
+    
+    // Get female voices
+    const femaleVoices = await tts.getVoicesByGender('Female');
+    console.log(`Female voices: ${femaleVoices.length}`);
+    
+    // Test different voices
+    const testText = "Hola, este es un ejemplo de síntesis de voz.";
+    
+    for (const voice of spanishVoices.slice(0, 3)) {
+        console.log(`Testing voice: ${voice.FriendlyName}`);
+        
+        await tts.synthesize(testText, voice.ShortName);
+        const filePath = await tts.toFile(`./voices/${voice.ShortName}`);
+        
+        console.log(`Saved: ${filePath}`);
+    }
+}
+
+exploreVoices().catch(console.error);
+```
+
+## Voice Options
+
+### Synthesis Parameters
+
+| Parameter | Type | Range | Description |
+|-----------|------|-------|-------------|
+| `pitch` | `string \| number` | `-100Hz` to `+100Hz` | Voice pitch adjustment |
+| `rate` | `string \| number` | `-100%` to `+200%` | Speech rate adjustment |
+| `volume` | `string \| number` | `-100%` to `+100%` | Volume adjustment |
+
+### Parameter Examples
+```js
+// Using numbers (recommended)
+{ pitch: 20, rate: -10, volume: 90 }
+
+// Using strings
+{ pitch: '+20Hz', rate: '-10%', volume: '90%' }
+
+// Mixed usage
+{ pitch: 15, rate: '25%', volume: 85 }
+```
+
+## Error Handling
+
+```js
+import { EdgeTTS } from '@andresaya/edge-tts';
+
+async function handleErrors() {
+    const tts = new EdgeTTS();
+    
+    try {
+        await tts.synthesize("Test text", 'invalid-voice-name');
+    } catch (error) {
+        console.error('Synthesis failed:', error.message);
+    }
+    
+    try {
+        // This will throw an error - no audio data
+        const duration = tts.getDuration();
+    } catch (error) {
+        console.error('No audio data available:', error.message);
+    }
+    
+    try {
+        // Invalid volume range
+        await tts.synthesize("Test", 'en-US-AriaNeural', { volume: -150 });
+    } catch (error) {
+        console.error('Invalid parameter:', error.message);
+    }
+}
+```
+
+## PHP Version
+If you want to use Edge TTS with PHP, you can check out the PHP version of this package: [Edge TTS PHP](https://github.com/andresayac/edge-tts-php)
 
 ## License
 This project is licensed under the GNU General Public License v3 (GPLv3).
@@ -88,4 +316,4 @@ We would like to extend our gratitude to the developers and contributors of the
 
 * https://github.com/rany2/edge-tts/tree/master/examples
 * https://github.com/rany2/edge-tts/blob/master/src/edge_tts/util.py
-* https://github.com/hasscc/hass-edge-tts/blob/main/custom_components/edge_tts/tts.py
+* https://github.com/hasscc/hass-edge-tts/blob/main/custom_components/edge_tts/tts.py

package/dist/cli/edge-tts.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/edge-tts.js

@@ -6,7 +6,7 @@ const VoiceListCommand_1 = require("../commands/VoiceListCommand");
 const commander_1 = require("commander");
 const program = new commander_1.Command();
 program
-    .version('1.2.6')
+    .version('1.3.0')
     .addCommand(SynthesizeCommand_1.SynthesizeCommand)
     .addCommand(VoiceListCommand_1.VoiceListCommand);
 try {

package/dist/commands/SynthesizeCommand.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const SynthesizeCommand: Command;

package/dist/commands/VoiceListCommand.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const VoiceListCommand: Command;

package/dist/config/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const Constants: {
+    TRUSTED_CLIENT_TOKEN: string;
+    WSS_URL: string;
+    VOICES_URL: string;
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { EdgeTTS, type Voice, type SynthesisOptions } from './services/EdgeTTS';

package/dist/services/EdgeTTS.d.ts

@@ -0,0 +1,40 @@
+import { Buffer } from 'buffer';
+export interface Voice {
+    Name: string;
+    ShortName: string;
+    Gender: string;
+    Locale: string;
+    FriendlyName: string;
+}
+export interface SynthesisOptions {
+    pitch?: string | number;
+    rate?: string | number;
+    volume?: string | number;
+}
+export declare class EdgeTTS {
+    private audio_stream;
+    private audio_format;
+    private ws;
+    getVoices(): Promise<Voice[]>;
+    getVoicesByLanguage(locale: string): Promise<Voice[]>;
+    getVoicesByGender(gender: 'Male' | 'Female'): Promise<Voice[]>;
+    private generateUUID;
+    private validatePitch;
+    private validateRate;
+    private validateVolume;
+    synthesize(text: string, voice?: string, options?: SynthesisOptions): Promise<void>;
+    private getSSML;
+    private buildTTSConfigMessage;
+    synthesizeStream(text: string, voice?: string, options?: SynthesisOptions): AsyncGenerator<Uint8Array, void, unknown>;
+    private processAudioData;
+    getDuration(): number;
+    getAudioInfo(): {
+        size: number;
+        format: string;
+        estimatedDuration: number;
+    };
+    toFile(outputPath: string, format?: string): Promise<string>;
+    toRaw(): string;
+    toBase64(): string;
+    toBuffer(): Buffer;
+}

package/dist/services/EdgeTTS.js

@@ -37,6 +37,14 @@ class EdgeTTS {
             return voice;
         });
     }
+    async getVoicesByLanguage(locale) {
+        const voices = await this.getVoices();
+        return voices.filter(voice => voice.Locale.startsWith(locale));
+    }
+    async getVoicesByGender(gender) {
+        const voices = await this.getVoices();
+        return voices.filter(voice => voice.Gender === gender);
+    }
     generateUUID() {
         return 'xxxxxxxx-xxxx-xxxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
             const r = Math.random() * 16 | 0;
@@ -130,6 +138,77 @@ class EdgeTTS {
         return `X-Timestamp:${new Date().toISOString()}Z\r\nContent-Type:application/json; charset=utf-8\r\nPath:speech.config\r\n\r\n` +
             `{"context":{"synthesis":{"audio":{"metadataoptions":{"sentenceBoundaryEnabled":false,"wordBoundaryEnabled":true},"outputFormat":"audio-24khz-48kbitrate-mono-mp3"}}}}`;
     }
+    async *synthesizeStream(text, voice = 'en-US-AnaNeural', options = {}) {
+        this.audio_stream = [];
+        const req_id = this.generateUUID();
+        this.ws = new ws_1.default(`${constants_1.Constants.WSS_URL}?trustedclienttoken=${constants_1.Constants.TRUSTED_CLIENT_TOKEN}&ConnectionId=${req_id}`);
+        const SSML_text = this.getSSML(text, voice, options);
+        const queue = [];
+        let done = false;
+        let error = null;
+        let notify = null;
+        const push = (chunk) => {
+            queue.push(chunk);
+            if (notify) {
+                notify();
+                notify = null;
+            }
+        };
+        const timeout = setTimeout(() => {
+            if (this.ws && this.ws.readyState === ws_1.default.OPEN) {
+                this.ws.close();
+            }
+        }, 30000);
+        this.ws.on('open', () => {
+            const message = this.buildTTSConfigMessage();
+            this.ws.send(message);
+            const speechMessage = `X-RequestId:${req_id}\r\nContent-Type:application/ssml+xml\r\nX-Timestamp:${new Date().toISOString()}Z\r\nPath:ssml\r\n\r\n${SSML_text}`;
+            this.ws.send(speechMessage);
+        });
+        this.ws.on('message', (data) => {
+            const buffer = ensureBuffer(data);
+            const needle = buffer_1.Buffer.from('Path:audio\r\n');
+            const audioStartIndex = buffer.indexOf(new Uint8Array(needle));
+            if (audioStartIndex !== -1) {
+                const audioChunk = buffer.subarray(audioStartIndex + needle.length);
+                const chunk = new Uint8Array(audioChunk);
+                this.audio_stream.push(chunk);
+                push(chunk);
+            }
+            if (buffer.toString().includes('Path:turn.end')) {
+                this.ws?.close();
+            }
+        });
+        this.ws.on('error', (err) => {
+            error = err;
+            done = true;
+            if (notify) {
+                notify();
+                notify = null;
+            }
+        });
+        this.ws.on('close', () => {
+            clearTimeout(timeout);
+            done = true;
+            if (notify) {
+                notify();
+                notify = null;
+            }
+        });
+        while (!done || queue.length > 0) {
+            if (queue.length === 0) {
+                await new Promise(resolve => (notify = resolve));
+                continue;
+            }
+            const chunk = queue.shift();
+            if (chunk) {
+                yield chunk;
+            }
+        }
+        if (error) {
+            throw error;
+        }
+    }
     processAudioData(data) {
         const buffer = ensureBuffer(data);
         const needle = buffer_1.Buffer.from("Path:audio\r\n");
@@ -142,9 +221,28 @@ class EdgeTTS {
             this.ws?.close();
         }
     }
-    async toFile(outputPath) {
+    getDuration() {
+        if (this.audio_stream.length === 0) {
+            throw new Error("No audio data available");
+        }
+        // Estimate duration based on the size of the audio stream
+        const bufferSize = this.toBuffer().length;
+        const estimatedDuration = bufferSize / (24000 * 3); // 24000 Hz sample rate, 3 bytes per sample (16-bit stereo)
+        return estimatedDuration;
+    }
+    getAudioInfo() {
+        const buffer = this.toBuffer();
+        return {
+            size: buffer.length,
+            format: this.audio_format,
+            estimatedDuration: this.getDuration()
+        };
+    }
+    async toFile(outputPath, format = this.audio_format) {
+        if (!format || typeof format !== 'string')
+            format = this.audio_format;
         const audioBuffer = this.toBuffer();
-        const finalPath = `${outputPath}.${this.audio_format}`;
+        const finalPath = `${outputPath}.${format}`;
         await (0, promises_1.writeFile)(finalPath, new Uint8Array(audioBuffer));
         return finalPath;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresaya/edge-tts",
-  "version": "1.2.7",
+  "version": "1.3.1",
   "description": "Edge TTS is a package that allows access to the online text-to-speech service used by Microsoft Edge without the need for Microsoft Edge, Windows, or an API key.",
   "main": "dist/index.js",
   "keywords": [