@reaatech/media-pipeline-mcp-elevenlabs

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

ElevenLabs provider for the media pipeline framework. Delivers high-quality text-to-speech synthesis with configurable voice selection, speaking speed, voice stability tuning, similarity boost, and style exaggeration. Supports multiple output formats and native audio-byte streaming.

Installation

npm install @reaatech/media-pipeline-mcp-elevenlabs
# or
pnpm add @reaatech/media-pipeline-mcp-elevenlabs

Feature Overview

• High-quality TTS with eleven_monolingual_v1, eleven_multilingual_v2, and eleven_turbo_v2 models
• Named voice selection (Rachel, Josh, Daniel, Charlotte) plus custom voice IDs
• Fine-grained voice tuning: stability (0-1), similarity boost (0-1), style exaggeration (0-1)
• Speaking speed control via SSML prosody tags
• Multiple output formats: MP3, WAV, OGG, FLAC, AAC
• Streaming support for TTS audio bytes (supportsStreaming)
• Character-count-based cost estimation

Quick Start

import { ElevenLabsProvider } from "@reaatech/media-pipeline-mcp-elevenlabs";
 
const provider = new ElevenLabsProvider({ apiKey: process.env.ELEVENLABS_API_KEY! });
 
const audio = await provider.execute({
  operation: "audio.tts",
  params: {
    text: "Welcome to our media pipeline. This audio was generated with ElevenLabs.",
    voice: "Rachel",
    speed: 1.0,
    model: "eleven_turbo_v2",
  },
  config: {},
});
 
// Save or pipe the audio
import { writeFileSync } from "node:fs";
writeFileSync("output.mp3", audio.data);
console.log(`Generated ${audio.metadata.characterCount} chars in ${audio.metadata.duration}s`);

Supported Operations

Configuration Parameters

audio.tts

Voice Tuning (internal defaults)

The provider applies these voice settings automatically on every request:

API Reference

ElevenLabsProvider

class ElevenLabsProvider extends MediaProvider {
  constructor(config: ElevenLabsProviderConfig)
 
  healthCheck(): Promise<ProviderHealth>
  estimateCost(input: ProviderInput): Promise<CostEstimate>
  execute(input: ProviderInput): Promise<ProviderOutput>
}

ElevenLabsProviderConfig

interface ElevenLabsProviderConfig {
  apiKey: string;
  voices?: {
    default?: string;
    [voiceName: string]: string | undefined;
  };
  model?: string;    // Default model ID
  timeout?: number;  // Request timeout in ms
}

Factory Function

import { defineElevenLabsProvider } from "@reaatech/media-pipeline-mcp-elevenlabs";
 
const provider = defineElevenLabsProvider({ apiKey: process.env.ELEVENLABS_API_KEY! });

Voice Resolution Logic

Voice parameters are resolved in this order:

1. If a custom voices map is configured, the name is looked up there first
2. If the value starts with voice_ or is exactly 20 characters, it’s treated as a raw voice ID
3. If the name matches a built-in preset, that voice ID is used
4. Falls back to "Rachel"

Key Methods

Non-Retryable Errors

The provider classifies these errors as non-retryable: authentication failed, invalid API key, permission denied, insufficient credits, voice not found, invalid voice ID.

Cost Estimation

Per-Character Pricing

Example Estimates

Cache Configuration

The provider exposes static cacheConfig with deterministic and non-deterministic parameters.

Deterministic parameters: text, voice_id, voice, model, voice_settings

Non-deterministic parameters: (none)

The normalize() function trims and collapses whitespace in text, and preserves voice settings as-is. All parameters are deterministic, so identical text + voice + model combinations will produce matching cache keys.

Health Check

The health check sends a GET request to https://api.elevenlabs.io/v1/voices using the xi-api-key header. Returns { healthy: true, latency: <ms> } on 2xx response, or { healthy: false, error: "<message>" } on failure.

Related Packages

• @reaatech/media-pipeline-mcp-provider-core — Base provider class
• @reaatech/media-pipeline-mcp-server — MCP server
• @reaatech/media-pipeline-mcp-openai — Alternative TTS provider (TTS-1)

License

MIT