### Install @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Instructions for installing the @bestcodes/edge-tts package using npm or bun.

```bash
npm install @bestcodes/edge-tts
# or
bun add @bestcodes/edge-tts
```

--------------------------------

### Get All Available Voices

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

This function retrieves a comprehensive list of all voices supported by the Microsoft Edge TTS service. It can optionally accept a proxy URL to fetch voices through a proxy server. The returned voice objects contain detailed properties like name, short name, gender, locale, and status.

```typescript
import { getVoices } from "@bestcodes/edge-tts";

// Get all available voices
const voices = await getVoices();

console.log(`Found ${voices.length} voices`);

// Explore voice properties
voices.slice(0, 3).forEach(voice => {
  console.log({
    name: voice.Name,
    shortName: voice.ShortName,
    gender: voice.Gender,
    locale: voice.Locale,
    status: voice.Status,
    friendlyName: voice.FriendlyName,
  });
});

// Example output:
// {
//   name: "Microsoft Server Speech Text to Speech Voice (en-US, EmmaMultilingualNeural)",
//   shortName: "en-US-EmmaMultilingualNeural",
//   gender: "Female",
//   locale: "en-US",
//   status: "GA",
//   friendlyName: "Emma Multilingual"
// }

// Use with proxy if needed
const voicesViaProxy = await getVoices("http://proxy.example.com:8080");

```

--------------------------------

### Configure Speech Generation Options in TypeScript

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Demonstrates how to configure speech generation options for the `@bestcodes/edge-tts` library in TypeScript. This includes setting text, voice, rate, volume, pitch, boundary types, proxy, and connection timeouts. Error handling for `generateSpeech` is also shown.

```typescript
import { generateSpeech, GenerateSpeechOptions } from "@bestcodes/edge-tts";

const options: GenerateSpeechOptions = {
  // Required
  text: "Your text to convert to speech",

  // Optional voice selection (default: "en-US-EmmaMultilingualNeural")
  voice: "en-US-AriaNeural",

  // Speech rate adjustment (default: "+0%")
  // Positive values speed up, negative values slow down
  rate: "+10%",  // Range: typically -100% to +100%

  // Volume adjustment (default: "+0%")
  volume: "+20%",  // Range: typically -100% to +100%

  // Pitch adjustment (default: "+0Hz")
  pitch: "+5Hz",  // Range: typically -50Hz to +50Hz

  // Boundary type for metadata events (default: "SentenceBoundary")
  boundary: "WordBoundary",  // or "SentenceBoundary"

  // Proxy configuration for network requests
  proxy: "http://proxy.example.com:8080",

  // WebSocket connection timeout in seconds (default: 10)
  connectTimeoutSeconds: 15,

  // Data receive timeout in seconds (default: 60)
  receiveTimeoutSeconds: 120,
};

const audio = await generateSpeech(options);

// Error handling example
try {
  const result = await generateSpeech({
    text: "Test speech with error handling",
    voice: "en-US-GuyNeural",
  });
  console.log("Success:", result.length, "bytes");
} catch (error) {
  if (error.message.includes("No audio received")) {
    console.error("Failed to receive audio from service");
  } else if (error.message.includes("Failed to list voices")) {
    console.error("Could not fetch voice list");
  } else {
    console.error("Error:", error.message);
  }
}
```

--------------------------------

### Generate SRT Subtitles with Experimental_Raw.SubMaker

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Shows how to create SRT subtitle files by feeding boundary events (SentenceBoundary, WordBoundary) from the communicate stream into the SubMaker. Requires the '@bestcodes/edge-tts' library.

```typescript
import { Experimental_Raw } from "@bestcodes/edge-tts";

const communicate = new Experimental_Raw.Communicate(
  "First sentence. Second sentence. Third sentence.",
  "en-US-AriaNeural",
  { boundary: "SentenceBoundary" }
);

const subMaker = new Experimental_Raw.SubMaker();

// Feed boundary events to subtitle maker
for await (const chunk of communicate.stream()) {
  if (chunk.type === "SentenceBoundary" || chunk.type === "WordBoundary") {
    subMaker.feed(chunk);
  }
}

// Generate SRT format subtitles
const srtContent = subMaker.getSrt();
console.log("Generated SRT subtitles:");
console.log(srtContent);

// Example output:
// 1
// 00:00:00,000 --> 00:00:01,250
// First sentence.
//
// 2
// 00:00:01,250 --> 00:00:02,500
// Second sentence.
//
// 3
// 00:00:02,500 --> 00:00:03,750
// Third sentence.

```

--------------------------------

### Generate Speech to Audio Buffer with @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Generates speech from text and returns an audio buffer. Requires the 'generateSpeech' function from the library. No explicit dependencies are listed, but it relies on the online Microsoft Edge TTS service.

```typescript
import { generateSpeech } from "@bestcodes/edge-tts";

const audio = await generateSpeech({
  text: "Hello, world!",
  voice: "en-US-EmmaMultilingualNeural",
});

// Do something with the audio buffer
```

--------------------------------

### generateSpeechWithSubtitlesToFile

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Generates speech audio and SRT subtitles simultaneously, saving both to files. Supports word or sentence boundary timing for precise synchronization.

```APIDOC
## POST /generateSpeechWithSubtitlesToFile

### Description
Generates speech audio and synchronized SRT subtitles from the provided text. The audio is returned as a Buffer, and subtitles are saved to a specified file path. This is ideal for video production workflows.

### Method
POST

### Endpoint
/generateSpeechWithSubtitlesToFile

### Parameters
#### Request Body
- **text** (string) - Required - The text to convert to speech.
- **subtitlePath** (string) - Required - The path where the SRT subtitle file will be saved.
- **voice** (string) - Optional - The voice to use (e.g., "en-US-EmmaMultilingualNeural"). Defaults to a system default.
- **boundary** (string) - Optional - The boundary type for timing information (e.g., "WordBoundary", "SentenceBoundary"). Defaults to "WordBoundary".
- **rate** (string) - Optional - The speaking rate (e.g., "+20%", "-10%"). Defaults to "0%".
- **proxy** (string) - Optional - URL of a proxy server to use for the request.
- **connectTimeoutSeconds** (number) - Optional - Timeout in seconds for establishing a connection.
- **receiveTimeoutSeconds** (number) - Optional - Timeout in seconds for receiving data.

### Request Example
```json
{
  "text": "The quick brown fox jumps over the lazy dog. This sentence demonstrates timing.",
  "subtitlePath": "./output/subtitles.srt",
  "voice": "en-US-EmmaMultilingualNeural",
  "boundary": "WordBoundary"
}
```

### Response
#### Success Response (200)
- **audio** (Buffer) - The generated speech audio data.
- **subtitles** (string) - The generated SRT subtitle content.
```

--------------------------------

### Low-level Audio Streaming with Experimental_Raw.Communicate

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Demonstrates direct access to the streaming communication layer for chunk-by-chunk audio processing and tracking word/sentence boundaries. Requires the '@bestcodes/edge-tts' library.

```typescript
import { Experimental_Raw } from "@bestcodes/edge-tts";

// Create a communicate instance
const communicate = new Experimental_Raw.Communicate(
  "This is a detailed example of low-level streaming.",
  "en-US-EmmaMultilingualNeural",
  {
    rate: "+0%",
    volume: "+0%",
    pitch: "+0Hz",
    boundary: "WordBoundary",
    connectTimeoutSeconds: 10,
    receiveTimeoutSeconds: 60,
  }
);

const audioChunks: Buffer[] = [];
const wordTimings: Array<{ text: string; offset: number; duration: number }> = [];

// Stream and process chunks
for await (const chunk of communicate.stream()) {
  if (chunk.type === "audio") {
    // Process audio data immediately as it arrives
    audioChunks.push(chunk.data!);
    console.log(`Received audio chunk: ${chunk.data!.length} bytes`);
  } else if (chunk.type === "WordBoundary") {
    // Track word-level timing for synchronization
    wordTimings.push({
      text: chunk.text!,
      offset: chunk.offset!,
      duration: chunk.duration!,
    });
    console.log(`Word boundary: "${chunk.text}" at ${chunk.offset! / 10000}ms`);
  } else if (chunk.type === "SentenceBoundary") {
    // Track sentence-level timing
    console.log(`Sentence boundary: "${chunk.text}" at ${chunk.offset! / 10000}ms`);
  }
}

const fullAudio = Buffer.concat(audioChunks);
console.log(`Total audio: ${fullAudio.length} bytes`);
console.log(`Word timings: ${wordTimings.length} words tracked`);

```

--------------------------------

### Advanced Voice Filtering with Experimental_Raw.VoicesManager

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Illustrates how to create and use the VoicesManager for advanced filtering of available TTS voices based on criteria like gender and language. Supports both default and custom (cached) voice lists. Requires the '@bestcodes/edge-tts' library.

```typescript
import { Experimental_Raw } from "@bestcodes/edge-tts";

// Create manager with default voices
const manager = await Experimental_Raw.VoicesManager.create();

// Find voices with multiple criteria
const targetVoices = manager.find({
  Gender: "Female",
  Language: "en",
});

console.log(`Found ${targetVoices.length} English female voices:`);
targetVoices.forEach(voice => {
  console.log(`- ${voice.FriendlyName} (${voice.Locale}) - ${voice.Status}`);
});

// Create manager with custom voice list (e.g., cached voices)
const customVoices = await Experimental_Raw.listVoices();
const cachedManager = await Experimental_Raw.VoicesManager.create(customVoices);

// Use the cached manager for faster lookups
const spanishVoices = cachedManager.find({ Language: "es" });
console.log(`Spanish voices from cache: ${spanishVoices.length}`);

```

--------------------------------

### generateSpeech

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Generate speech audio from text and return it as a Buffer. Supports default and custom voices with various parameters for rate, volume, and pitch.

```APIDOC
## POST /generateSpeech

### Description
Generates speech audio from the provided text and returns it as a Buffer. This function allows for customization of voice, speaking rate, volume, and pitch.

### Method
POST

### Endpoint
/generateSpeech

### Parameters
#### Request Body
- **text** (string) - Required - The text to convert to speech.
- **voice** (string) - Optional - The voice to use (e.g., "en-US-AriaNeural"). Defaults to a system default.
- **rate** (string) - Optional - The speaking rate (e.g., "+20%", "-10%"). Defaults to "0%".
- **volume** (string) - Optional - The speaking volume (e.g., "+10%", "-5%"). Defaults to "0%".
- **pitch** (string) - Optional - The speaking pitch (e.g., "+5Hz", "-2Hz"). Defaults to "0Hz".
- **boundary** (string) - Optional - The boundary type for timing information (e.g., "WordBoundary", "SentenceBoundary").
- **proxy** (string) - Optional - URL of a proxy server to use for the request.
- **connectTimeoutSeconds** (number) - Optional - Timeout in seconds for establishing a connection.
- **receiveTimeoutSeconds** (number) - Optional - Timeout in seconds for receiving data.

### Request Example
```json
{
  "text": "Hello, world! This is a test of the text-to-speech system.",
  "voice": "en-US-AriaNeural",
  "rate": "+20%",
  "volume": "+10%",
  "pitch": "+5Hz"
}
```

### Response
#### Success Response (200)
- **audio** (Buffer) - The generated speech audio data.
```

--------------------------------

### generateSpeechToFile

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Converts text to speech and saves the audio directly to a specified file path. Ideal for generating audio files for later use.

```APIDOC
## POST /generateSpeechToFile

### Description
Converts the provided text into speech audio and saves it directly to a file at the specified output path. This is useful for batch processing or generating audio assets.

### Method
POST

### Endpoint
/generateSpeechToFile

### Parameters
#### Request Body
- **text** (string) - Required - The text to convert to speech.
- **outputPath** (string) - Required - The path where the audio file will be saved.
- **voice** (string) - Optional - The voice to use (e.g., "en-GB-SoniaNeural"). Defaults to a system default.
- **rate** (string) - Optional - The speaking rate (e.g., "+20%", "-10%"). Defaults to "0%".
- **volume** (string) - Optional - The speaking volume (e.g., "+10%", "-5%"). Defaults to "0%".
- **pitch** (string) - Optional - The speaking pitch (e.g., "+5Hz", "-2Hz"). Defaults to "0Hz".
- **proxy** (string) - Optional - URL of a proxy server to use for the request.
- **connectTimeoutSeconds** (number) - Optional - Timeout in seconds for establishing a connection.
- **receiveTimeoutSeconds** (number) - Optional - Timeout in seconds for receiving data.

### Request Example
```json
{
  "text": "This audio will be saved to a file on disk.",
  "outputPath": "./output/speech.mp3",
  "voice": "en-GB-SoniaNeural",
  "rate": "-10%"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the file was saved successfully.
```

--------------------------------

### Low-level Audio Streaming with @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Provides a low-level API for streaming audio and receiving word boundary metadata. Uses the 'Experimental_Raw.Communicate' class for granular control over the TTS stream.

```typescript
import { Experimental_Raw } from "@bestcodes/edge-tts";

const communicate = new Experimental_Raw.Communicate(
  "Hello!",
  "en-US-EmmaMultilingualNeural",
);

for await (const chunk of communicate.stream()) {
  if (chunk.type === "audio") {
    // Process audio data (chunk.data is a Buffer)
  } else if (chunk.type === "WordBoundary") {
    // Word boundary metadata
  }
}
```

--------------------------------

### streamSpeechToFile

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Streams speech audio directly to a file with real-time progress tracking. Useful for large audio generation where real-time feedback is needed.

```APIDOC
## POST /streamSpeechToFile

### Description
Streams speech audio directly to a file with real-time progress tracking.

### Method
POST

### Endpoint
/streamSpeechToFile

### Parameters
#### Request Body
- **text** (string) - Required - The text to convert to speech.
- **outputPath** (string) - Required - The file path where the audio will be saved.
- **voice** (string) - Optional - The voice to use for speech synthesis (e.g., "en-US-AriaNeural").
- **rate** (string) - Optional - The speech rate adjustment (e.g., "+10%").

### Request Example
```json
{
  "text": "This is being written to a file as it's generated.",
  "outputPath": "./output/streamed-speech.mp3",
  "voice": "en-US-AriaNeural",
  "rate": "+10%"
}
```

### Response
**Stream Progress**: The API returns a stream of progress objects.

#### Success Response (Stream Event)
- **bytesWritten** (number) - The total number of bytes written to the file so far.
- **chunkSize** (number) - The size of the current audio chunk processed.

#### Response Example (Progress Update)
```json
{
  "bytesWritten": 10240,
  "chunkSize": 5120
}
```
```

--------------------------------

### Stream Audio Chunks with @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Streams audio data in chunks in real-time as it's generated. This is useful for immediate audio processing without waiting for the full file. It requires the 'streamSpeech' function and accepts text and voice configurations.

```typescript
import { streamSpeech } from "@bestcodes/edge-tts";

for await (const chunk of streamSpeech({
  text: "Hello, world!",
  voice: "en-US-EmmaMultilingualNeural",
})) {
  if (chunk.type === "audio" && chunk.data) {
    // Process audio chunk in real-time
    console.log(`Received ${chunk.data.length} bytes`);
  }
}
```

--------------------------------

### streamSpeechWithSubtitlesToFile

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Streams speech audio along with subtitles, providing real-time updates as chunks of audio and subtitle data become available. Ideal for video generation or real-time captioning.

```APIDOC
## POST /streamSpeechWithSubtitlesToFile

### Description
Streams speech audio with subtitles, receiving real-time updates as chunks arrive. The subtitles can be generated based on word boundaries or other specified criteria.

### Method
POST

### Endpoint
/streamSpeechWithSubtitlesToFile

### Parameters
#### Request Body
- **text** (string) - Required - The text to convert to speech and generate subtitles for.
- **subtitlePath** (string) - Required - The file path where the subtitles will be saved.
- **voice** (string) - Optional - The voice to use for speech synthesis (e.g., "en-US-EmmaMultilingualNeural").
- **boundary** (string) - Optional - The boundary type for subtitle generation (e.g., "WordBoundary").

### Request Example
```json
{
  "text": "This text will have subtitles generated in real-time.",
  "subtitlePath": "./output/streamed-subtitles.srt",
  "voice": "en-US-EmmaMultilingualNeural",
  "boundary": "WordBoundary"
}
```

### Response
**Streamed Chunks**: The API returns a stream of objects, each representing either an audio chunk or subtitle update.

#### Success Response (Stream Event)
- **type** (string) - "audio" or "subtitle".
- **data** (Buffer/string) - The audio data if type is "audio".
- **subtitles** (object) - Subtitle information if type is "subtitle".

#### Response Example (Audio Chunk)
```json
{
  "type": "audio",
  "data": "<audio_data>"
}
```

#### Response Example (Subtitle Update)
```json
{
  "type": "subtitle",
  "subtitles": {
    "startTime": "00:00:01,000",
    "endTime": "00:00:02,500",
    "text": "real-time"
  }
}
```
```

--------------------------------

### Save Generated Speech to File with @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Generates speech from text and saves it directly to an MP3 file. Uses the 'generateSpeechToFile' function and requires a text input and an output file path.

```typescript
import { generateSpeechToFile } from "@bestcodes/edge-tts";

await generateSpeechToFile({
  text: "Hello, world!",
  outputPath: "./output.mp3",
});
```

--------------------------------

### Stream Speech Directly to File with Progress using @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Streams generated speech directly to an output file while providing real-time progress updates on bytes written and chunk sizes. This function is suitable for large outputs where progress monitoring is beneficial.

```typescript
import { streamSpeechToFile } from "@bestcodes/edge-tts";

for await (const progress of streamSpeechToFile({
  text: "Hello, world!",
  outputPath: "./output.mp3",
})) {
  console.log(
    `Written: ${progress.bytesWritten} bytes (chunk: ${progress.chunkSize})`,
  );
}
```

--------------------------------

### Generate Speech with Subtitles to File using @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Generates speech from text and saves both the audio and SRT subtitles to separate files. This function returns both the audio data and subtitle content.

```typescript
import { generateSpeechWithSubtitlesToFile } from "@bestcodes/edge-tts";

const { audio, subtitles } = await generateSpeechWithSubtitlesToFile({
  text: "This text will have subtitles.",
  subtitlePath: "./subtitles.srt",
});
```

--------------------------------

### Stream Speech to File with Progress

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

This function streams generated speech audio directly to a specified file. It provides real-time progress updates on the number of bytes written, allowing for dynamic feedback or UI updates during the streaming process. It requires the 'text', 'outputPath', 'voice', and optionally 'rate' options.

```typescript
import { streamSpeechToFile } from "@bestcodes/edge-tts";

// Stream to file with progress updates
for await (const progress of streamSpeechToFile({
  text: "This is being written to a file as it's generated.",
  outputPath: "./output/streamed-speech.mp3",
  voice: "en-US-AriaNeural",
  rate: "+10%",
})) {
  console.log(
    `Written: ${progress.bytesWritten} bytes total (chunk: ${progress.chunkSize} bytes)`,
  );
  // Can update progress bar, log status, etc.
}

console.log("File writing complete");

```

--------------------------------

### findVoices

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Searches for voices that match specific criteria, such as gender, locale, or language. This allows for targeted voice selection.

```APIDOC
## GET /findVoices

### Description
Searches for voices matching specific criteria like gender, locale, or language.

### Method
GET

### Endpoint
/findVoices

### Parameters
#### Query Parameters
- **criteria** (object) - Required - An object containing the search criteria.
    - **Gender** (string) - Optional - Filter by gender (e.g., "Female", "Male").
    - **Locale** (string) - Optional - Filter by locale (e.g., "en-US", "en-GB").
    - **Language** (string) - Optional - Filter by language code (e.g., "es" for Spanish).
    - **ShortName** (string) - Optional - Filter by the exact short name of the voice.
- **proxyUrl** (string) - Optional - A URL to a proxy server to use for the request.

### Request Example
```
GET /findVoices?criteria.Gender=Female&criteria.Locale=en-US
```

### Request Example (with proxy)
```
GET /findVoices?criteria.ShortName=en-GB-RyanNeural&proxyUrl=http://proxy.example.com:8080
```

### Response
#### Success Response (200)
- **voices** (array) - An array of voice objects matching the criteria. The structure of each voice object is the same as returned by `getVoices()`.

#### Response Example
```json
[
  {
    "Name": "Microsoft Server Speech Text to Speech Voice (en-US, Aria Neural)",
    "ShortName": "en-US-AriaNeural",
    "Gender": "Female",
    "Locale": "en-US",
    "Status": "GA",
    "FriendlyName": "Aria Neural"
  }
]
```
```

--------------------------------

### List Available Edge TTS Voices with @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Retrieves a list of all available voices for Microsoft Edge TTS service or finds specific voices based on criteria like gender or locale. It uses the 'getVoices' and 'findVoices' functions.

```typescript
import { getVoices, findVoices } from "@bestcodes/edge-tts";

// Get all voices
const allVoices = await getVoices();

// Find specific voices
const femaleVoices = await findVoices({ Gender: "Female" });
const englishVoices = await findVoices({ Locale: "en-US" });
```

--------------------------------

### Generate Speech Audio Buffer with Edge TTS

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Generates speech audio from text and returns it as a Buffer. Supports basic usage with default voices and advanced customization of voice, rate, volume, pitch, and proxy settings. Useful for direct audio manipulation or client-side playback.

```typescript
import { generateSpeech } from "@bestcodes/edge-tts";

// Basic usage with default voice
const audio = await generateSpeech({
  text: "Hello, world! This is a test of the text-to-speech system.",
});

// Advanced usage with custom voice and parameters
const customAudio = await generateSpeech({
  text: "Welcome to our application. Please follow the instructions carefully.",
  voice: "en-US-AriaNeural",
  rate: "+20%",        // Speak 20% faster
  volume: "+10%",      // Increase volume by 10%
  pitch: "+5Hz",       // Raise pitch by 5 hertz
  boundary: "WordBoundary",
  proxy: "http://proxy.example.com:8080",
  connectTimeoutSeconds: 15,
  receiveTimeoutSeconds: 120,
});

// Use the audio buffer (e.g., save to file, stream to client, etc.)
console.log(`Generated ${audio.length} bytes of audio data`);
```

--------------------------------

### streamSpeech

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Streams speech audio in real-time as it's generated from text. Provides audio chunks and timing information for word or sentence boundaries.

```APIDOC
## GET /streamSpeech

### Description
Streams speech audio in real-time from the provided text. The function yields chunks of audio data and boundary events (word or sentence) as they are generated, allowing for immediate processing or playback.

### Method
GET

### Endpoint
/streamSpeech

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to convert to speech.
- **voice** (string) - Optional - The voice to use (e.g., "en-US-EmmaMultilingualNeural"). Defaults to a system default.
- **boundary** (string) - Optional - The boundary type for timing information (e.g., "WordBoundary", "SentenceBoundary"). Defaults to "WordBoundary".
- **rate** (string) - Optional - The speaking rate (e.g., "+20%", "-10%"). Defaults to "0%".
- **proxy** (string) - Optional - URL of a proxy server to use for the request.
- **connectTimeoutSeconds** (number) - Optional - Timeout in seconds for establishing a connection.
- **receiveTimeoutSeconds** (number) - Optional - Timeout in seconds for receiving data.

### Request Example
```
GET /streamSpeech?text=Hello%2C%20world%21&voice=en-US-EmmaMultilingualNeural
```

### Response
#### Success Response (200)
- **Yields** - An async iterator that yields objects with the following properties:
  - **type** (string) - "audio" for audio data, or "WordBoundary"/"SentenceBoundary" for timing events.
  - **data** (Buffer) - The audio data chunk (only for type "audio").
  - **text** (string) - The text corresponding to the boundary event.
  - **offset** (number) - The time offset in microseconds from the start of the speech for boundary events.
```

--------------------------------

### Find Voices by Criteria

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

This function allows searching for specific voices based on various criteria such as gender, locale, language, or short name. Multiple criteria can be combined for more precise filtering. It also supports fetching results through a specified proxy server. The function returns an array of voice objects matching the provided filters.

```typescript
import { findVoices } from "@bestcodes/edge-tts";

// Find all female voices
const femaleVoices = await findVoices({ Gender: "Female" });
console.log(`Found ${femaleVoices.length} female voices`);

// Find all US English voices
const usEnglishVoices = await findVoices({ Locale: "en-US" });
console.log(`US English voices: ${usEnglishVoices.map(v => v.ShortName).join(", ")}`);

// Find all Spanish language voices (any locale)
const spanishVoices = await findVoices({ Language: "es" });
console.log(`Spanish voices available in locales: ${[...new Set(spanishVoices.map(v => v.Locale))].join(", ")}`);

// Find a specific voice by ShortName
const specificVoice = await findVoices({ ShortName: "en-GB-RyanNeural" });
if (specificVoice.length > 0) {
  console.log("Found:", specificVoice[0].FriendlyName);
}

// Combine multiple criteria
const britishMaleVoices = await findVoices({
  Gender: "Male",
  Locale: "en-GB",
});
console.log("British male voices:", britishMaleVoices.map(v => v.ShortName));

// Use with proxy
const voicesViaProxy = await findVoices({ Gender: "Female" }, "http://proxy.example.com:8080");

```

--------------------------------

### Stream Speech Audio in Real-time with Edge TTS

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Streams speech audio in real-time from text, allowing processing of audio chunks as they are generated. It also provides event data for word and sentence boundaries with timing information. Ideal for live applications or interactive experiences.

```typescript
import { streamSpeech } from "@bestcodes/edge-tts";

// Stream audio chunks as they're generated
for await (const chunk of streamSpeech({
  text: "Hello, world! This is streamed in real-time.",
  voice: "en-US-EmmaMultilingualNeural",
})) {
  if (chunk.type === "audio" && chunk.data) {
    // Process audio chunk immediately as it arrives
    console.log(`Received ${chunk.data.length} bytes`);
    // Can send to client, play immediately, etc.
  } else if (chunk.type === "WordBoundary") {
    // Track word-level timing
    console.log(`Word: "${chunk.text}" at ${chunk.offset! / 10000}ms`);
  } else if (chunk.type === "SentenceBoundary") {
    // Track sentence-level timing
    console.log(`Sentence: "${chunk.text}" at ${chunk.offset! / 10000}ms`);
  }
}

console.log("Streaming complete");
```

--------------------------------

### Stream Speech with Real-time Subtitles using @bestcodes/edge-tts

Source: https://github.com/the-best-codes/edge-tts/blob/main/README.md

Streams speech and updates a subtitle file in real-time. This function allows processing of audio chunks as they arrive and provides immediate updates to the subtitle file.

```typescript
import { streamSpeechWithSubtitlesToFile } from "@bestcodes/edge-tts";

for await (const chunk of streamSpeechWithSubtitlesToFile({
  text: "This text will have subtitles.",
  subtitlePath: "./subtitles.srt",
})) {
  if (chunk.type === "audio" && chunk.data) {
    // Process audio chunk
  } else if (chunk.subtitles) {
    // Subtitles file updated in real-time
    console.log("Subtitles updated:", chunk.subtitles);
  }
}
```

--------------------------------

### Generate Speech and Subtitles with Edge TTS

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Generates speech audio and synchronized SRT subtitles simultaneously, saving subtitles to a specified file. Supports both word-level and sentence-level timing boundaries. This is useful for creating video captions and transcripts.

```typescript
import { generateSpeechWithSubtitlesToFile } from "@bestcodes/edge-tts";

// Generate audio with word-level subtitles
const { audio, subtitles } = await generateSpeechWithSubtitlesToFile({
  text: "The quick brown fox jumps over the lazy dog. This sentence demonstrates timing.",
  subtitlePath: "./output/subtitles.srt",
  voice: "en-US-EmmaMultilingualNeural",
  boundary: "WordBoundary",  // Word-by-word timing
});

console.log(`Audio: ${audio.length} bytes`);
console.log("Subtitles preview:");
console.log(subtitles.substring(0, 200));

// Example with sentence-level boundaries
const { audio: sentenceAudio, subtitles: sentenceSubtitles } = await generateSpeechWithSubtitlesToFile({
  text: "First sentence here. Second sentence here. Third sentence here.",
  subtitlePath: "./output/sentence-subtitles.srt",
  boundary: "SentenceBoundary",  // Sentence-by-sentence timing
  rate: "+0%",
});

// The subtitle file is automatically saved to the specified path
// Format: SRT with millisecond precision timing
```

--------------------------------

### getVoices

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Retrieves a comprehensive list of all available voices supported by the Microsoft Edge TTS service. This is useful for understanding the full range of voice options.

```APIDOC
## GET /getVoices

### Description
Retrieves the complete list of available voices from Microsoft Edge TTS service.

### Method
GET

### Endpoint
/getVoices

### Parameters
#### Query Parameters
- **proxyUrl** (string) - Optional - A URL to a proxy server to use for the request.

### Request Example
```
GET /getVoices
```

### Response
#### Success Response (200)
- **voices** (array) - An array of voice objects.
    - **Name** (string) - The full name of the voice.
    - **ShortName** (string) - A short identifier for the voice (e.g., "en-US-AriaNeural").
    - **Gender** (string) - The gender of the voice (e.g., "Female", "Male").
    - **Locale** (string) - The locale the voice is associated with (e.g., "en-US").
    - **Status** (string) - The status of the voice (e.g., "GA" for General Availability).
    - **FriendlyName** (string) - A human-readable name for the voice.

#### Response Example
```json
[
  {
    "Name": "Microsoft Server Speech Text to Speech Voice (en-US, Aria Neural)",
    "ShortName": "en-US-AriaNeural",
    "Gender": "Female",
    "Locale": "en-US",
    "Status": "GA",
    "FriendlyName": "Aria Neural"
  },
  {
    "Name": "Microsoft Server Speech Text to Speech Voice (en-US, Guy Neural)",
    "ShortName": "en-US-GuyNeural",
    "Gender": "Male",
    "Locale": "en-US",
    "Status": "GA",
    "FriendlyName": "Guy Neural"
  }
]
```
```

--------------------------------

### Stream Speech with Subtitles to File

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

This function streams speech audio along with its corresponding subtitles to separate files. It provides real-time chunks of either audio data or subtitle updates as they are generated. The function requires 'text', 'subtitlePath', 'voice', and 'boundary' options, with 'outputPath' being optional for audio.

```typescript
import { streamSpeechWithSubtitlesToFile } from "@bestcodes/edge-tts";

// Stream audio and subtitles with real-time updates
for await (const chunk of streamSpeechWithSubtitlesToFile({
  text: "This text will have subtitles generated in real-time.",
  subtitlePath: "./output/streamed-subtitles.srt",
  voice: "en-US-EmmaMultilingualNeural",
  boundary: "WordBoundary",
})) {
  if (chunk.type === "audio" && chunk.data) {
    // Process audio chunk
    console.log(`Audio chunk: ${chunk.data.length} bytes`);
  } else if (chunk.subtitles) {
    // Subtitles file updated in real-time
    console.log("Subtitles updated with new boundary");
    // Can notify client, update UI, etc.
  }
}

console.log("Streaming with subtitles complete");

```

--------------------------------

### Save Speech Audio to File with Edge TTS

Source: https://context7.com/the-best-codes/edge-tts/llms.txt

Converts text to speech and saves the generated audio directly to a specified file path. This function is ideal for creating audio files for later use, such as in video projects or offline playback. It allows customization of voice and speech rate.

```typescript
import { generateSpeechToFile } from "@bestcodes/edge-tts";

// Save speech to MP3 file
await generateSpeechToFile({
  text: "This audio will be saved to a file on disk.",
  outputPath: "./output/speech.mp3",
  voice: "en-GB-SoniaNeural",
  rate: "-10%",  // Speak 10% slower for clarity
});

// Generate narration for a video project
await generateSpeechToFile({
  text: "Chapter one: The beginning of the journey. Our hero sets out on an adventure...",
  outputPath: "./narration/chapter1.mp3",
  voice: "en-US-GuyNeural",
  volume: "+15%",
  pitch: "-2Hz",
});

console.log("Audio file saved successfully");
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.