### Starting the server

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Command-line interface to start the Echogarden WebSocket server with various options.

```APIDOC
## Starting the server

```bash
echogarden serve [options]
```

### Options (all optional):
* `port`: Port number. Defaults to `45054`
* `secure`: Start a secure server? Defaults to `false`
* `certPath`: Path to a certificate file, required when `secure = true`
* `keyPath`: Path to a private key file, required when `secure = true`
* `deflate`: Use per-message deflate. Defaults to `true`
* `maxPayload`: Maximum raw message payload size (in bytes). Defaults to `1000 * 1000000` (1GB)
* `useWorkerThread`: Run worker in a separate thread. Defaults to `true` (recommended leaving as is)
```

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

### Starting the server programmatically

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Programmatically starting the Echogarden WebSocket server using the `startServer` method.

```APIDOC
## Starting the server programmatically

You can use the `startServer` method to start a new server.
```ts
async function startServer(serverOptions: ServerOptions, onStarted: (options: ServerOptions) => void)
```

Example:
```ts
import { startServer } from 'echogarden'

await startServer({ port: 1234 }, () => {
	console.log("Server is started!")
})
```

The method would return when the server is closed.

**TODO**: accept a signal to stop the server.
```

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

### Install Echogarden CLI

Source: https://github.com/echogarden-project/echogarden/blob/main/README.md

Installs the Echogarden command-line utility globally using npm. Ensure Node.js v18 or later is installed.

```bash
npm install -g echogarden@latest
```

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

### Start Echogarden Server

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Starts the Echogarden server on a specified port. Useful for microservice architecture.

```bash
echogarden serve --port=45054
```

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

### Start Echogarden Server

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Use the `echogarden serve` command to start the WebSocket server. Various options are available to configure port, security, payload size, and worker threads.

```bash
echogarden serve [options]
```

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

### Echogarden CLI: Text-to-Speech Examples

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Command-line interface examples for text-to-speech operations, including speaking text, files, and URLs with various engine and language options.

```bash
# Text-to-speech
echogarden speak "Hello World!" --engine=kokoro --language=en
echogarden speak-file story.txt output.mp3 output.srt --engine=vits --speed=1.1
echogarden speak-url https://example.com/article --engine=espeak
echogarden speak-wikipedia "Albert Einstein" --language=en output.mp3
```

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

### Echogarden CLI: Speech-to-Text Examples

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Command-line interface examples for speech-to-text transcription, showing basic transcription and outputting to multiple file formats with a specified engine.

```bash
# Speech-to-text
echogarden transcribe speech.mp3
echogarden transcribe speech.mp3 result.txt result.srt result.json --engine=whisper
```

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

### Synthesis Request Example

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

An example of a `SynthesisRequest` message sent to the server.

```APIDOC
For example, this message requests synthesis:
```ts
{
	messageType: 'SynthesisRequest',
	requestId: 'cb7e0f3ec835a213b005c4424c8d5775',

	input: 'Hello World!',

	options: {
		engine: 'espeak',
		language: 'en-GB'
	}
}
```
```

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

### Start Server Programmatically

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Use the `startServer` function from the `echogarden` package to programmatically start the WebSocket server. The server will run until it is closed.

```typescript
import { startServer } from 'echogarden'

await startServer({ port: 1234 }, () => {
	console.log("Server is started!")
})
```

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

### Synthesis Response Example

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

An example of a `SynthesisResponse` message received from the server.

```APIDOC
Example response, for the above synthesis request:

```ts
{
	messageType: 'SynthesisResponse',
	requestId: 'cb7e0f3ec835a213b005c4424c8d5775',

	audio: {
		sampleRate: 22050,
		channels: [ ... ] // An array of `Float32Array` channel data
	}

	// ... other result object properties
}
```
```

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

### Install Echogarden CLI and Module

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Install Echogarden globally for CLI usage or as a project dependency for programmatic integration.

```bash
# Global CLI installation
npm install -g echogarden@latest

# As a project dependency
npm install echogarden
```

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

### Echogarden Configuration File

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Example configuration file for Echogarden, specifying global settings, CLI behavior, and engine-specific parameters.

```conf
# echogarden.config (auto-loaded from current directory)
[global]
packageBaseURL = https://hf-mirror.com/echogarden/echogarden-packages/resolve/main/
logLevel = info

[cli]
play = true
overwrite = true

[speak]
engine = kokoro
voice = af_heart
speed = 1.0
subtitles.mode = sentence
subtitles.maxLineWidth = 42

[transcribe]
engine = whisper
whisper.model = base.en
whisper.temperature = 0.1
```

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

### Using the client class

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Example of using the Echogarden client class in Node.js to interact with the WebSocket server.

```APIDOC
## Using the client class

For Node.js clients, a simple client class allows to wrap communications with the server in a more convenient interface, without needing to know the details of the protocol.

Currently, the client is embedded in the main codebase. This means you have to import the `echogarden` package to use it:

```ts
import { WebSocket } from 'ws'
import { Client } from 'echogarden'

const ws = new WebSocket('ws://localhost:45054')

ws.on("open", async () => {
	const client = new Client(ws)

	const { audio } = await client.synthesize("Hello World", { engine: 'espeak' })
})
```
```

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

### Initialize WebSocket Client

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Import and use the `Client` class from the `echogarden` package to interact with the WebSocket server. This example demonstrates connecting to the server and synthesizing audio.

```typescript
import { WebSocket } from 'ws'
import { Client } from 'echogarden'

const ws = new WebSocket('ws://localhost:45054')

ws.on("open", async () => {
	const client = new Client(ws)

	const { audio } = await client.synthesize("Hello World", { engine: 'espeak' })
})
```

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

### Install echogarden Node.js Package

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/API.md

Install the echogarden package as a dependency in your Node.js project using npm.

```bash
npm install echogarden
```

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

### Start Echogarden WebSocket Server and Client

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Launches a WebSocket server for remote API access and demonstrates a client connecting to synthesize speech. The server uses MessagePack for binary requests.

```typescript
import { startServer, Client } from 'echogarden'
import { WebSocket } from 'ws'

// --- Server side ---
await startServer(
  { port: 45054, secure: false, deflate: true, useWorkerThread: true },
  () => console.log('Server listening on port 45054')
)

// --- Client side (separate process or file) ---
const ws = new WebSocket('ws://localhost:45054')

ws.on('open', async () => {
  const client = new Client(ws)

  // Synthesize via WebSocket client
  const { audio } = await client.synthesize(
    'Hello from the WebSocket client!',
    { engine: 'espeak', language: 'en-GB' }
  )
  console.log('Received audio, sample rate:', (audio as any).sampleRate)

  ws.close()
})

// Protocol: send a raw MessagePack binary message directly
// {
//   messageType: 'SynthesisRequest',
//   requestId: 'cb7e0f3ec835a213b005c4424c8d5775',
//   input: 'Hello World!',
//   options: { engine: 'espeak', language: 'en-GB' }
// }
// Cancel with: { messageType: 'CancellationRequest', requestId: '...' }
```

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

### Package ID Format

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Technical.md

This format is used for identifying downloaded and installed components within the Echogarden package system.

```plaintext
[engine name]-[package id]-[date as yyyymmdd]
```

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

### Synthesis Request Message

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Example of a `SynthesisRequest` message. It includes the input text and options for the synthesis engine and language.

```typescript
{
	messageType: 'SynthesisRequest',
	requestId: 'cb7e0f3ec835a213b005c4424c8d5775',

	input: 'Hello World!',

	options: {
		engine: 'espeak',
		language: 'en-GB'
	}
}
```

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

### Synthesize Text with Sentence Callback

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/API.md

Synthesize text to audio and receive callbacks for each synthesized sentence. This example demonstrates the basic usage of the `synthesize` function with a specified engine.

```typescript
const { audio } = await Echogarden.synthesize("Hello World!", { engine: 'espeak' })

```

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

### Check for Echogarden Updates

Source: https://github.com/echogarden-project/echogarden/blob/main/README.md

Checks for newer versions of Echogarden using npm-check-updates. Install npm-check-updates globally first, then run the check.

```bash
npm install -g npm-check-updates
ncu -g echogarden
```

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

### align(input, transcript, options)

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Matches a spoken audio recording to a provided transcript and returns precise word-level timing. Three alignment engines are available: `dtw` (default, synthesis-based), `dtw-ra` (recognition-assisted), and `whisper` (guided decoding).

```APIDOC
## align(input, transcript, options)

### Description
Matches a spoken audio recording to a provided transcript and returns precise word-level timing. Three alignment engines are available: `dtw` (default, synthesis-based), `dtw-ra` (recognition-assisted), and `whisper` (guided decoding).

### Method Signature
`align(input: string | Buffer | RawAudio, transcript: string, options?: AlignOptions): Promise<AlignResult>`

### Parameters
* `input` (string | Buffer | RawAudio) - Path to an audio file, encoded audio buffer, or `RawAudio` object.
* `transcript` (string) - The known transcript to align the audio against.
* `options` (AlignOptions, optional) - Configuration options for the alignment process.
  * `engine` (string) - The alignment engine to use (e.g., 'dtw', 'dtw-ra', 'whisper'). Defaults to 'dtw'.
  * `language` (string, optional) - The language of the audio and transcript (e.g., 'en'). Auto-detected if omitted.
  * `dtw` (object, optional) - Options specific to the DTW alignment engine.
    * `granularity` (Array<string>) - Controls the granularity of alignment (e.g., ['xx-low', 'medium']).
    * `windowDuration` (Array<string | number>) - Defines the Sakoe-Chiba window duration (e.g., ['15%', 30]).
  * `whisper` (object, optional) - Options specific to the Whisper-guided alignment.
    * `model` (string) - The Whisper model to use (e.g., 'small.en').
    * `timestampAccuracy` (string) - Desired accuracy for timestamps ('high', 'medium', 'low').

### Returns
* `Promise<AlignResult>` - A promise that resolves to an object containing:
  * `timeline` (Array<TimelineEntry>) - A general timeline of the audio.
  * `wordTimeline` (Array<WordTimelineEntry>) - An array of objects, each representing a word with its precise start and end times.
  * `language` (string) - The detected language of the audio.

### Example
```ts
import * as Echogarden from 'echogarden'
import { readFileSync } from 'fs'

const transcript = readFileSync('transcript.txt', 'utf8')

const { timeline, wordTimeline, language } = await Echogarden.align(
  'speech.mp3',
  transcript,
  {
    engine: 'dtw',
    language: 'en',
    dtw: {
      granularity: ['xx-low', 'medium'],   // multi-pass for better accuracy
      windowDuration: ['15%', 30]           // Sakoe-Chiba window: 15% or 30s
    }
  }
)

wordTimeline.forEach(word =>
  console.log(`${word.text}: ${word.startTime.toFixed(3)}s → ${word.endTime.toFixed(3)}s`)
)
```
```

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

### Synthesis Response Message

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Server.md

Example of a `SynthesisResponse` message. It contains the audio data, including sample rate and channel information, in response to a synthesis request.

```typescript
{
	messageType: 'SynthesisResponse',
	requestId: 'cb7e0f3ec835a213b005c4424c8d5775',

	audio: {
		sampleRate: 22050,
		channels: [ ... ] // An array of `Float32Array` channel data
	}

	// ... other result object properties
}
```

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

### `startServer(serverOptions, onStarted)`

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Launches a WebSocket server for Echogarden, enabling remote or inter-process use of core API operations via MessagePack-encoded binary requests.

```APIDOC
## WebSocket Server

### `startServer(serverOptions, onStarted)`

### Description
Launches an Echogarden WebSocket server that accepts MessagePack-encoded binary requests, enabling remote or inter-process use of all core API operations.

### Method Signature
`startServer(serverOptions: ServerOptions, onStarted?: () => void): Promise<void>`

### Parameters
*   **serverOptions** (ServerOptions) - Options for configuring the WebSocket server.
    *   **port** (number) - The port to listen on.
    *   **secure** (boolean) - Whether to use secure WebSocket (WSS).
    *   **deflate** (boolean) - Whether to enable message deflation.
    *   **useWorkerThread** (boolean) - Whether to use worker threads for processing.
*   **onStarted** (function, optional) - A callback function to execute once the server has started.

### Request Example (Server Side)
```ts
import { startServer } from 'echogarden'

await startServer(
  { port: 45054, secure: false, deflate: true, useWorkerThread: true },
  () => console.log('Server listening on port 45054')
)
```

### Request Example (Client Side)
```ts
import { Client } from 'echogarden'
import { WebSocket } from 'ws'

const ws = new WebSocket('ws://localhost:45054')

ws.on('open', async () => {
  const client = new Client(ws)

  // Synthesize via WebSocket client
  const { audio } = await client.synthesize(
    'Hello from the WebSocket client!',
    { engine: 'espeak', language: 'en-GB' }
  )
  console.log('Received audio, sample rate:', (audio as any).sampleRate)

  ws.close()
})
```

### Protocol
Messages are sent as MessagePack binary data. Example request structure:
```json
{
  "messageType": "SynthesisRequest",
  "requestId": "cb7e0f3ec835a213b005c4424c8d5775",
  "input": "Hello World!",
  "options": { "engine": "espeak", "language": "en-GB" }
}
```
Cancellation requests use `messageType: 'CancellationRequest'` with the corresponding `requestId`.
```

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

### Load Configuration from Flattened JSON File

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Use a JSON configuration file with flattened property names for a more concise representation of settings.

```json
{
	"transcribe": {
		"engine": "whisper",
		"whisper.model": "tiny"
	}
}
```

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

### Echogarden CLI Commands

Source: https://github.com/echogarden-project/echogarden/blob/main/README.md

A sample of common commands for the Echogarden command-line interface. These commands cover speaking text, speaking from files, transcribing audio, translating speech, aligning speech with text, and isolating speech.

```bash
echogarden speak "Hello World!"
```

```bash
echogarden speak-file story.txt --engine=kokoro
```

```bash
echogarden transcribe speech.mp3
```

```bash
echogarden translate-speech speech.webm subtitles.srt
```

```bash
echogarden align speech.opus transcript.txt
```

```bash
echogarden isolate speech.wav
```

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

### Run Echogarden CLI Locally

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Development.md

Execute the Echogarden command-line interface directly from your local project code using `npx`. This is useful for testing CLI commands with your latest changes.

```bash
npx echogarden speak "Hello World!"
```

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

### Load Configuration from INI File

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Store CLI and command-specific options in an `echogarden.config` file for automatic loading. This simplifies complex configurations by centralizing settings.

```conf
[global]

# Custom remote packages base URL:
packageBaseURL = https://hf-mirror.com/echogarden/echogarden-packages/resolve/main/

# Log level:
logLevel = info

[cli]

# Should play audio in the terminal:
play = true

# Overwrite existing files:
overwrite = true

[speak]

# Engine for synthesis:
engine = vits

# Voice for synthesis (case-insensitive, can be a search pattern):
voice = amy

# Custom lexicon paths:
customLexiconPaths = ["lexicon1.json", "lexicon2.json"]

[transcribe]

# Engine for recognition:
engine = whisper

# Whisper options:
whisper.model = tiny
whisper.temperature = 0.15

```

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

### List Available Engines for a Command

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Display a list of supported engines for a specific Echogarden command, such as 'speak'.

```bash
echogarden list-engines speak
```

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

### Update Echogarden CLI

Source: https://github.com/echogarden-project/echogarden/blob/main/README.md

Updates the globally installed Echogarden package to the latest version using npm. This command may not always update to the very latest major version.

```bash
npm update -g echogarden
```

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

### Load Configuration from JSON File

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Utilize a JSON file for configuration, offering an alternative structured format. This can be named `echogarden.config.json`.

```json
{
	"speak": {
		"engine": "vits",
		"voice": "amy",
		"customLexiconPaths": ["lexicon1.json", "lexicon2.json"]
	},

	"transcribe": {
		"engine": "whisper",
		"whisper": {
			"model": "tiny"
		}
	}
}
```

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

### alignTranslation(input, translatedTranscript, options)

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Aligns a spoken recording in any language with a pre-existing English translation of its content. Uses the Whisper model in guided decoding mode to produce word-level timestamps for the translated text.

```APIDOC
## alignTranslation(input, translatedTranscript, options)

### Description
Aligns a spoken recording in any language with a pre-existing English translation of its content. Uses the Whisper model in guided decoding mode to produce word-level timestamps for the translated text.

### Method Signature
`alignTranslation(input: string | Buffer | RawAudio, translatedTranscript: string, options?: AlignTranslationOptions): Promise<AlignTranslationResult>`

### Parameters
* `input` (string | Buffer | RawAudio) - Path to an audio file, encoded audio buffer, or `RawAudio` object.
* `translatedTranscript` (string) - The pre-existing English translation of the audio content.
* `options` (AlignTranslationOptions, optional) - Configuration options for alignment.
  * `engine` (string) - The alignment engine to use. Currently only 'whisper' is supported.
  * `sourceLanguage` (string, optional) - The source language of the audio (e.g., 'nl'). Auto-detected if omitted.
  * `targetLanguage` (string) - The target language of the `translatedTranscript` (must be 'en' for this function).
  * `whisper` (object, optional) - Options specific to the Whisper engine.
    * `model` (string) - The Whisper model to use (e.g., 'base').

### Returns
* `Promise<AlignTranslationResult>` - A promise that resolves to an object containing:
  * `timeline` (Array<TimelineEntry>) - A general timeline of the audio.
  * `wordTimeline` (Array<WordTimelineEntry>) - An array of objects, each representing a word from the translated transcript with its start and end times in the audio.
  * `sourceLanguage` (string) - The detected source language of the audio.

### Example
```ts
import * as Echogarden from 'echogarden'

const { timeline, wordTimeline, sourceLanguage } = await Echogarden.alignTranslation(
  'dutch-speech.mp3',
  'This is the English translation of the Dutch recording.',
  {
    engine: 'whisper',
    sourceLanguage: 'nl',
    targetLanguage: 'en',
    whisper: { model: 'base' }
  }
)

console.log('Source language detected:', sourceLanguage)
wordTimeline.forEach(w =>
  console.log(`[${w.startTime.toFixed(2)}s] ${w.text}`)
)
```
```

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

### Split Output to Multiple Files with Templates

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Use segment placeholders in output file paths to automatically split content into multiple files. The placeholder is replaced by the segment index and initial text.

```bash
echogarden speak text.txt parts/[segment].opus
```

```bash
echogarden align speech.mp3 transcript.txt parts/[segment].m4a parts/[segment].srt
```

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

### `setGlobalOption(key, value)` / `getGlobalOption(key)`

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Configures global API behavior by setting or retrieving settings such as log verbosity, custom FFmpeg/SoX paths, and download base URLs.

```APIDOC
## Global Options

### `setGlobalOption(key, value)` / `getGlobalOption(key)`

### Description
Sets or retrieves global settings such as log verbosity, custom FFmpeg/SoX paths, and the package download base URL. These settings apply to all subsequent API calls.

### Method Signatures
*   `setGlobalOption(key: string, value: any): void`
*   `getGlobalOption(key: string): any`

### Parameters
*   **key** (string) - The name of the global option to set or get.
*   **value** (any) - The value to set for the option (for `setGlobalOption`).

### Available Options (Examples)
*   `logLevel`: Controls log output verbosity (e.g., 'silent', 'error', 'info').
*   `packageBaseURL`: Custom base URL for downloading packages.
*   `ffmpegPath`: Path to a custom FFmpeg binary.

### Request Example
```ts
import * as Echogarden from 'echogarden'

// Suppress all log output
Echogarden.setGlobalOption('logLevel', 'silent')

// Use a mirror for model downloads
Echogarden.setGlobalOption(
  'packageBaseURL',
  'https://hf-mirror.com/echogarden/echogarden-packages/resolve/main/'
)

// Point to a custom FFmpeg binary
Echogarden.setGlobalOption('ffmpegPath', '/usr/local/bin/ffmpeg')

// Read back a value
const logLevel = Echogarden.getGlobalOption('logLevel')
console.log('Current log level:', logLevel) // 'silent'
```

### Response
`setGlobalOption` returns void. `getGlobalOption` returns the current value of the specified option.
```

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

### Speak Content from URL

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Synthesize spoken audio from the main article content extracted from a given URL.

```bash
echogarden speak-url https://example.com/hola
```

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

### Configure VS Code for Step-Debugging

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Development.md

Set up `launch.json` in VS Code to launch the Echogarden CLI in debug mode. This allows you to set breakpoints and inspect the code execution.

```json
{
	"version": "0.2.0",
	"configurations": [
		{
			"type": "node",
			"request": "launch",
			"name": "Launch Program",
			"skipFiles": [
				"<node_internals>/**"
			],
			"program": "${workspaceFolder}/dist/cli/CLIStarter.js",
			"outputCapture": "std",
			"console": "integratedTerminal",
			"runtimeArgs": ["--experimental-wasi-unstable-preview1", "--no-warnings", "--trace-uncaught"],

			"args": ["speak", "Hello World!", "--debug"]
		}
	]
}
```

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

### Enable Audio Playback in Terminal

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Override the default behavior to enable audio playback directly in the terminal when an output file is specified. Use `--play` to activate this feature.

```bash
echogarden speak-file text.txt result.mp3 --play
```

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

### List Available TTS Voices for an Engine

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Retrieve and display the available Text-to-Speech voices for a specified engine, like 'google-cloud'.

```bash
echogarden list-voices google-cloud
```

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

### Speak Text from File

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Synthesize spoken audio from text content within a file (e.g., .txt, .html, .srt). Supports specifying output files for audio and subtitles, language, and synthesis engine.

```bash
echogarden speak-file text.txt result.mp3 --language=en
```

```bash
echogarden speak-file text.txt result.mp3 --language=en --engine=pico
```

```bash
echogarden speak-file text.txt result.mp3 result.wav result.srt --engine=kokoro --speed=1.1
```

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

### Configure Global Echogarden Options

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Sets or retrieves global settings that affect all subsequent API calls. Useful for controlling log verbosity, specifying custom binary paths, or changing download sources.

```typescript
import * as Echogarden from 'echogarden'

// Suppress all log output
Echogarden.setGlobalOption('logLevel', 'silent')

// Use a mirror for model downloads (e.g., if huggingface.co is blocked)
Echogarden.setGlobalOption(
  'packageBaseURL',
  'https://hf-mirror.com/echogarden/echogarden-packages/resolve/main/'
)

// Point to a custom FFmpeg binary
Echogarden.setGlobalOption('ffmpegPath', '/usr/local/bin/ffmpeg')

// Read back a value
const logLevel = Echogarden.getGlobalOption('logLevel')
console.log('Current log level:', logLevel) // 'silent'
```

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

### recognize(input, options)

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Applies speech recognition to an audio file path, encoded audio buffer, or RawAudio object. Returns a transcript, word-level timeline, detected language, and optionally isolated/background audio if source separation is applied.

```APIDOC
## recognize(input, options)

### Description
Applies speech recognition to an audio file path, encoded audio buffer, or `RawAudio` object. Returns a transcript, word-level timeline, detected language, and optionally isolated/background audio if source separation is applied.

### Method Signature
`recognize(input: string | Buffer | RawAudio, options?: RecognizeOptions): Promise<RecognizeResult>`

### Parameters
* `input` (string | Buffer | RawAudio) - Path to an audio file, encoded audio buffer, or `RawAudio` object.
* `options` (RecognizeOptions, optional) - Configuration options for speech recognition.
  * `engine` (string) - The speech recognition engine to use (e.g., 'whisper', 'openai-cloud').
  * `language` (string, optional) - The language of the audio (e.g., 'en'). Auto-detected if omitted.
  * `whisper` (object, optional) - Options specific to the Whisper engine.
    * `model` (string) - The Whisper model to use (e.g., 'base.en').
    * `temperature` (number) - Controls randomness in the output. Lower values make the model more deterministic.
  * `openaiCloud` (object, optional) - Options specific to the OpenAI Cloud engine.
    * `apiKey` (string) - Your OpenAI API key.
    * `model` (string) - The OpenAI model to use (e.g., 'whisper-1').
  * `isolate` (boolean, optional) - Whether to attempt source separation before recognition.

### Returns
* `Promise<RecognizeResult>` - A promise that resolves to an object containing:
  * `transcript` (string) - The recognized text transcript.
  * `wordTimeline` (Array<WordTimelineEntry>) - An array of objects, each representing a word with its start and end times.
  * `language` (string) - The detected language of the audio.
  * `isolatedAudio` (Buffer, optional) - The isolated speech audio if `isolate` was true.
  * `backgroundAudio` (Buffer, optional) - The background noise audio if `isolate` was true.

### Example
```ts
import * as Echogarden from 'echogarden'

const { transcript, wordTimeline, language } = await Echogarden.recognize(
  'speech.mp3',
  {
    engine: 'whisper',
    language: 'en',
    whisper: {
      model: 'base.en',
      temperature: 0.1
    }
  }
)

console.log('Transcript:', transcript)
console.log('Language:', language)
wordTimeline.forEach(entry =>
  console.log(`[${entry.startTime.toFixed(2)}s - ${entry.endTime.toFixed(2)}s] ${entry.text}`)
)
```
```

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

### Save Spoken Audio to File

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Synthesize spoken audio from text and save it to a specified audio file, optionally with language specification.

```bash
echogarden speak "Hello world!" result.mp3 --language=en
```

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

### General Alignment Options

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Options.md

Configure the core aspects of the alignment process, including the engine, language, and pre-processing steps.

```APIDOC
## General Alignment Options

### Description
Configure the core aspects of the alignment process, including the engine, language, and pre-processing steps.

### Parameters
#### General
- **engine** (string) - Optional - Alignment algorithm to use. Can be `dtw`, `dtw-ra`, or `whisper`. Defaults to `dtw`.
- **language** (string) - Optional - Language code for the audio and transcript (e.g., `en`, `fr`, `en-US`, `pt-BR`). Auto-detected from transcript if not set.
- **crop** (boolean) - Optional - Crop to active parts using voice activity detection before starting. Defaults to `true`.
- **isolate** (boolean) - Optional - Apply source separation to isolate voice before starting alignment. Defaults to `false`.
- **customLexiconPaths** (array of strings) - Optional - An array of custom lexicon file paths.
- **subtitles** (object) - Optional - Prefix to provide options for subtitles.
- **vad** (object) - Optional - Prefix to provide options for voice activity detection when `crop` is set to `true`.
- **sourceSeparation** (object) - Optional - Prefix to provide options for source separation when `isolate` is set to `true`.
```

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

### synthesize(input, options, onSegment?, onSentence?)

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Converts text into spoken audio. It supports streaming via optional callbacks and returns audio data along with a word-level timeline.

```APIDOC
## synthesize(input, options, onSegment?, onSentence?)

### Description
Converts a string (or array of strings) to audio. Returns a promise resolving to an object containing the raw or encoded audio, a word-level timeline, and the detected/used language. Optional async callbacks (`onSegment`, `onSentence`) allow streaming-style processing as each unit is produced.

### Method
`synthesize`

### Parameters
- **input** (string | string[]) - Required - The text to synthesize.
- **options** (object) - Required - Configuration options for synthesis.
  - **engine** (string) - Required - The TTS engine to use (e.g., 'kokoro', 'vits').
  - **language** (string) - Required - The language for synthesis (e.g., 'en-US').
  - **voice** (string) - Optional - The specific voice to use.
  - **speed** (number) - Optional - The speech speed multiplier (default: 1.0).
  - **outputAudioFormat** (object) - Optional - Specifies the desired audio output format.
    - **codec** (string) - Required if outputAudioFormat is specified - The audio codec (e.g., 'mp3').
- **onSegment** (function) - Optional - Callback function for segment-level synthesis events.
- **onSentence** (function) - Optional - Callback function for sentence-level synthesis events.

### Request Example
```ts
import * as Echogarden from 'echogarden'
import { writeFileSync } from 'fs'

// Basic synthesis with Kokoro (offline neural TTS)
const { audio, timeline, language } = await Echogarden.synthesize(
  "The quick brown fox jumps over the lazy dog.",
  {
    engine: 'kokoro',
    language: 'en-US',
    voice: 'af_heart',
    speed: 1.0,
    outputAudioFormat: { codec: 'mp3' }
  }
)

// audio is a Uint8Array (encoded) when codec is specified
writeFileSync('output.mp3', audio as Uint8Array)
console.log('Detected language:', language)     // e.g. "en"
console.log('First word start:', timeline[0]?.startTime) // e.g. 0.05

// Streaming via onSegment callback
async function onSegment(data: Echogarden.SynthesisSegmentEventData) {
  console.log(`Segment ${data.index + 1}/${data.total}: "${data.transcript}"`);
  // data.audio contains the RawAudio for this segment
}

const { audio: rawAudio } = await Echogarden.synthesize(
  ["First paragraph.", "Second paragraph."],
  { engine: 'vits', language: 'en' },
  onSegment
)
// rawAudio is a RawAudio: { sampleRate: number, channels: Float32Array[] }
```

### Response
#### Success Response
- **audio** (Uint8Array | RawAudio) - The synthesized audio data.
- **timeline** (Array<object>) - A word-level timeline with start and end times.
- **language** (string) - The detected or used language code.

#### Response Example
```json
{
  "audio": "<Uint8Array or RawAudio object>",
  "timeline": [
    {"word": "The", "startTime": 0.05, "endTime": 0.15},
    {"word": "quick", "startTime": 0.15, "endTime": 0.30}
  ],
  "language": "en"
}
```
```

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

### List Engines and Voices

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Lists available speech synthesis engines or voices for a specific language. Useful for selecting speech parameters.

```bash
echogarden list-engines speak
```

```bash
echogarden list-voices google-cloud --language=en
```

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

### Synthesize Speech with Kokoro Engine

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Perform basic text-to-speech synthesis using the offline Kokoro engine. Specify output format and retrieve audio data and word-level timeline.

```typescript
import * as Echogarden from 'echogarden'
import { writeFileSync } from 'fs'

// Basic synthesis with Kokoro (offline neural TTS)
const { audio, timeline, language } = await Echogarden.synthesize(
  "The quick brown fox jumps over the lazy dog.",
  {
    engine: 'kokoro',
    language: 'en-US',
    voice: 'af_heart',
    speed: 1.0,
    outputAudioFormat: { codec: 'mp3' }
  }
)

// audio is a Uint8Array (encoded) when codec is specified
writeFileSync('output.mp3', audio as Uint8Array)
console.log('Detected language:', language)     // e.g. "en"
console.log('First word start:', timeline[0]?.startTime) // e.g. 0.05
```

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

### Two-Stage Alignment (Separate Stages)

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Performs alignment in two separate stages: first aligning audio to native transcript, then aligning the resulting timeline to a translated transcript. Useful for reusing intermediate alignment results.

```bash
echogarden align dutch-speech.mp3 dutch-transcript.txt dutch-timeline.json
```

```bash
echogarden align-timeline-translation dutch-timeline.json russian-transcript.txt --audio=dutch-speech.mp3
```

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

### `timelineToSubtitles(timeline, options)`

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Converts a timeline object into formatted subtitle content (SRT/VTT) with intelligent sentence boundary detection and configurable line width.

```APIDOC
## `timelineToSubtitles(timeline, options)`

### Description
Converts any timeline (from synthesis, recognition, or alignment) into formatted subtitle file content, with intelligent sentence/phrase boundary detection and configurable line width.

### Method Signature
`timelineToSubtitles(timeline: TimelineEntry[], options?: SubtitleOptions): string`

### Parameters
*   **timeline** (TimelineEntry[]) - An array of timeline entries.
*   **options** (SubtitleOptions, optional) - Configuration options for subtitle generation.
    *   **format** (string) - The desired subtitle format ('srt' or 'vtt').
    *   **mode** (string) - The mode for cue creation ('sentence' or 'phrase').
    *   **maxLineCount** (number, optional) - Maximum number of lines per subtitle cue.
    *   **maxLineWidth** (number, optional) - Maximum line width in characters.
    *   **separatePhrases** (boolean, optional) - Whether to separate phrases within cues.
    *   **maxAddedDuration** (number, optional) - Maximum padding duration for cues in seconds.

### Request Example
```ts
import * as Echogarden from 'echogarden'
import { writeFileSync } from 'fs'

// Get a timeline from recognition
const { timeline } = await Echogarden.recognize('speech.mp3', { engine: 'whisper' })

const srtContent = Echogarden.timelineToSubtitles(timeline, {
  format: 'srt',
  mode: 'sentence',
  maxLineCount: 2,
  maxLineWidth: 42,
  separatePhrases: true,
  maxAddedDuration: 3.0
})

writeFileSync('output.srt', srtContent)
console.log('SRT preview:\n', srtContent.slice(0, 300))
```

### Response
Returns a string containing the formatted subtitle content.
```

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

### Import Echogarden Module

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Import the Echogarden module into your TypeScript project for programmatic access.

```typescript
// Module import
import * as Echogarden from 'echogarden'
```

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

### Two-Stage Alignment (Combined Stages)

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Aligns an audio file with its native transcript and then with a translated transcript. Outputs synchronized results to the terminal or to JSON/SRT files.

```bash
echogarden align-transcript-and-translation dutch-speech.mp3 dutch-transcript.txt russian-translation.txt
```

```bash
echogarden align-transcript-and-translation dutch-speech.mp3 dutch-transcript.txt russian-translation.txt out.json out.srt
```

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

### DTW Engine Options

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/Options.md

Configure specific parameters for the Dynamic Time Warping (DTW) alignment engine.

```APIDOC
## DTW Engine Options

### Description
Configure specific parameters for the Dynamic Time Warping (DTW) alignment engine.

### Parameters
#### DTW
- **dtw.granularity** (string or array of strings) - Optional - Adjusts the MFCC frame width and hop size. Can be set to `xx-low`, `x-low`, `low`, `medium`, `high`, `x-high`. For multi-pass processing, multiple granularities can be provided (e.g., `['xx-low','medium']`). Auto-selected by default.
- **dtw.windowDuration** (string or number or array) - Optional - Sets the maximum duration of the Sakoe-Chiba window. Can be specified in seconds (e.g., `240`) or as an integer percentage (e.g., `15%`). Recommended to be at least 10%-20% of total audio duration. For multi-pass processing, multiple durations can be provided (e.g., `['15%', 20]`). Auto-selected by default.
```

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

### Overwrite Existing Output Files

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Configure the CLI to overwrite existing output files instead of creating new ones with appended numbers. Use the `--overwrite` option for this behavior.

```bash
echogarden --overwrite ...
```

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

### setGlobalOption

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/API.md

Sets a global option for the Echogarden API. Refer to the options reference for available global options.

```APIDOC
## setGlobalOption(key, value)

### Description
Sets a global option.

See the [options reference](Options.md) for more details about the available global options.

### Parameters
* `key`: The option key to set.
* `value`: The value for the option.
```

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

### Align Transcript and Translation with Echogarden

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Use this function for a two-stage alignment pipeline that first aligns audio with its native transcript, then aligns the resulting timeline with a translation using semantic text embeddings. Supports approximately 100 languages.

```typescript
import * as Echogarden from 'echogarden'

const result = await Echogarden.alignTranscriptAndTranslation(
  'dutch-speech.mp3',
  'Dit is de Nederlandse tekst.',       // native transcript
  'Esta es la traducción al español.',  // translated transcript
  {
    sourceLanguage: 'nl',
    targetLanguage: 'es'
  }
)

console.log('Native timeline words:', result.wordTimeline.length)
console.log('Translated timeline words:', result.translatedWordTimeline.length)
result.translatedWordTimeline.forEach(w =>
  console.log(`[${w.startTime.toFixed(2)}s] ${w.text}`)
)
```

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

### `isolate(input, options)`

Source: https://context7.com/echogarden-project/echogarden/llms.txt

Separates voice from music or background audio using the MDX-NET deep learning model. It returns the original, isolated voice, and background audio streams.

```APIDOC
## `isolate(input, options)`

### Description
Uses the MDX-NET deep learning model to isolate a vocal stem from a mixed audio signal. Returns the original, isolated, and background (residual) audio streams.

### Method Signature
`isolate(input: string, options?: object): Promise<{ inputRawAudio: RawAudio, isolatedRawAudio: RawAudio, backgroundRawAudio: RawAudio }>`

### Parameters
*   **input** (string) - Path to the input audio file.
*   **options** (object, optional) - Configuration options for the isolation process.
    *   **engine** (string) - The engine to use, e.g., 'mdx-net'.
    *   **mdxNet** (object, optional) - Options specific to the MDX-NET engine.
        *   **model** (string) - The name of the model to use (e.g., 'Kim_Vocal_2').
        *   **provider** (string) - The processing provider (e.g., 'cpu').

### Request Example
```ts
import * as Echogarden from 'echogarden'

const { inputRawAudio, isolatedRawAudio, backgroundRawAudio } =
  await Echogarden.isolate(
    'song-with-vocals.mp3',
    {
      engine: 'mdx-net',
      mdxNet: {
        model: 'Kim_Vocal_2',
        provider: 'cpu'
      }
    }
  )

console.log('Input channels:', inputRawAudio.channels.length)
console.log('Isolated (voice) channels:', isolatedRawAudio.channels.length)
console.log('Background (music) channels:', backgroundRawAudio.channels.length)
```

### Response
Returns an object containing three audio streams: `inputRawAudio`, `isolatedRawAudio`, and `backgroundRawAudio`.
```

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

### Speak Wikipedia Article

Source: https://github.com/echogarden-project/echogarden/blob/main/docs/CLI.md

Synthesize spoken audio for a Wikipedia article, specifying the article title and optionally the language edition.

```bash
echogarden speak-wikipedia "Psychologie" --language=fr
```