@andresaya/edge-tts 1.2.6 → 1.3.0

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

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-import { SynthesizeCommand } from '../commands/SynthesizeCommand';
-import { VoiceListCommand } from '../commands/VoiceListCommand';
-import { Command } from 'commander';
-const program = new Command();
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const SynthesizeCommand_1 = require("../commands/SynthesizeCommand");
+const VoiceListCommand_1 = require("../commands/VoiceListCommand");
+const commander_1 = require("commander");
+const program = new commander_1.Command();
 program
-    .version('1.2.6')
-    .addCommand(SynthesizeCommand)
-    .addCommand(VoiceListCommand);
+    .version('1.2.7')
+    .addCommand(SynthesizeCommand_1.SynthesizeCommand)
+    .addCommand(VoiceListCommand_1.VoiceListCommand);
 try {
     program.parse();
 }

package/dist/commands/SynthesizeCommand.d.ts

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

package/dist/commands/SynthesizeCommand.js

@@ -1,6 +1,9 @@
-import { Command } from 'commander';
-import { EdgeTTS } from '../services/EdgeTTS';
-export const SynthesizeCommand = new Command('synthesize')
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SynthesizeCommand = void 0;
+const commander_1 = require("commander");
+const EdgeTTS_1 = require("../services/EdgeTTS");
+exports.SynthesizeCommand = new commander_1.Command('synthesize')
     .description('Edge TTS: synthesize text to audio')
     .option('-t, --text <text>', 'Text to convert to audio')
     .option('-v, --voice [voice]', 'Voice to use for the audio synthesis', 'en-US-AriaNeural')
@@ -14,7 +17,7 @@ export const SynthesizeCommand = new Command('synthesize')
         console.error('Text is required');
         process.exit(1);
     }
-    const tts = new EdgeTTS();
+    const tts = new EdgeTTS_1.EdgeTTS();
     await tts.synthesize(text, voice, { pitch, rate, volume });
     await tts.toFile(`${output}`);
     console.log(`Audio file generated: ${output}.mp3`);

package/dist/commands/VoiceListCommand.d.ts

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

package/dist/commands/VoiceListCommand.js

@@ -1,9 +1,12 @@
-import { Command } from 'commander';
-import { EdgeTTS } from '../services/EdgeTTS';
-export const VoiceListCommand = new Command('voice-list')
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoiceListCommand = void 0;
+const commander_1 = require("commander");
+const EdgeTTS_1 = require("../services/EdgeTTS");
+exports.VoiceListCommand = new commander_1.Command('voice-list')
     .description('Get the list of available voices')
     .action(async () => {
-    const tts = new EdgeTTS();
+    const tts = new EdgeTTS_1.EdgeTTS();
     const voices = await tts.getVoices();
     console.log('Lista de voces disponibles:');
     voices.forEach((voice) => {

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/config/constants.js

@@ -1,4 +1,7 @@
-export const Constants = {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Constants = void 0;
+exports.Constants = {
     TRUSTED_CLIENT_TOKEN: '6A5AA1D4EAFF4E9FB37E23D68491D6F4',
     WSS_URL: 'wss://speech.platform.bing.com/consumer/speech/synthesize/readaloud/edge/v1',
     VOICES_URL: 'https://speech.platform.bing.com/consumer/speech/synthesize/readaloud/voices/list',

package/dist/index.d.ts

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

package/dist/index.js

@@ -1 +1,5 @@
-export { EdgeTTS } from './services/EdgeTTS';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeTTS = void 0;
+var EdgeTTS_1 = require("./services/EdgeTTS");
+Object.defineProperty(exports, "EdgeTTS", { enumerable: true, get: function () { return EdgeTTS_1.EdgeTTS; } });

package/dist/services/EdgeTTS.d.ts

@@ -0,0 +1,31 @@
+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[]>;
+    private generateUUID;
+    private validatePitch;
+    private validateRate;
+    private validateVolume;
+    synthesize(text: string, voice?: string, options?: SynthesisOptions): Promise<void>;
+    private getSSML;
+    private buildTTSConfigMessage;
+    private processAudioData;
+    toFile(outputPath: string): Promise<string>;
+    toRaw(): string;
+    toBase64(): string;
+    toBuffer(): Buffer;
+}

package/dist/services/EdgeTTS.js

@@ -1,28 +1,34 @@
-import WebSocket, {} from 'ws';
-import { Constants } from '../config/constants';
-import { writeFile } from 'fs/promises';
-import { Buffer } from 'buffer';
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeTTS = void 0;
+const ws_1 = __importDefault(require("ws"));
+const constants_1 = require("../config/constants");
+const promises_1 = require("fs/promises");
+const buffer_1 = require("buffer");
 function ensureBuffer(data) {
-    if (Buffer.isBuffer(data)) {
+    if (buffer_1.Buffer.isBuffer(data)) {
         return data;
     }
     if (data instanceof ArrayBuffer) {
-        return Buffer.from(data);
+        return buffer_1.Buffer.from(data);
     }
     if (Array.isArray(data)) {
-        return Buffer.concat(data);
+        return buffer_1.Buffer.concat(data);
     }
     if (typeof data === 'string') {
-        return Buffer.from(data, 'utf-8');
+        return buffer_1.Buffer.from(data, 'utf-8');
     }
     throw new Error(`Unsupported RawData type: ${typeof data}`);
 }
-export class EdgeTTS {
+class EdgeTTS {
     audio_stream = [];
     audio_format = 'mp3';
     ws;
     async getVoices() {
-        const response = await fetch(`${Constants.VOICES_URL}?trustedclienttoken=${Constants.TRUSTED_CLIENT_TOKEN}`);
+        const response = await fetch(`${constants_1.Constants.VOICES_URL}?trustedclienttoken=${constants_1.Constants.TRUSTED_CLIENT_TOKEN}`);
         const data = await response.json();
         return data.map((voice) => {
             delete voice.VoiceTag;
@@ -81,10 +87,10 @@ export class EdgeTTS {
         return new Promise((resolve, reject) => {
             this.audio_stream = [];
             const req_id = this.generateUUID();
-            this.ws = new WebSocket(`${Constants.WSS_URL}?trustedclienttoken=${Constants.TRUSTED_CLIENT_TOKEN}&ConnectionId=${req_id}`);
+            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 timeout = setTimeout(() => {
-                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                if (this.ws && this.ws.readyState === ws_1.default.OPEN) {
                     this.ws.close();
                 }
                 reject(new Error("Synthesis timeout"));
@@ -100,7 +106,7 @@ export class EdgeTTS {
             });
             this.ws.on('error', (err) => {
                 clearTimeout(timeout);
-                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                if (this.ws && this.ws.readyState === ws_1.default.OPEN) {
                     this.ws.close();
                 }
                 reject(err);
@@ -126,7 +132,7 @@ export class EdgeTTS {
     }
     processAudioData(data) {
         const buffer = ensureBuffer(data);
-        const needle = Buffer.from("Path:audio\r\n");
+        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);
@@ -139,7 +145,7 @@ export class EdgeTTS {
     async toFile(outputPath) {
         const audioBuffer = this.toBuffer();
         const finalPath = `${outputPath}.${this.audio_format}`;
-        await writeFile(finalPath, new Uint8Array(audioBuffer));
+        await (0, promises_1.writeFile)(finalPath, new Uint8Array(audioBuffer));
         return finalPath;
     }
     toRaw() {
@@ -152,6 +158,7 @@ export class EdgeTTS {
         if (this.audio_stream.length === 0) {
             throw new Error("No audio data available. Did you run synthesize() first?");
         }
-        return Buffer.concat(this.audio_stream);
+        return buffer_1.Buffer.concat(this.audio_stream);
     }
 }
+exports.EdgeTTS = EdgeTTS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresaya/edge-tts",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "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": [