@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/reference/voice/composite-voice.mdx

@@ -0,0 +1,140 @@
+---
+title: "Reference: CompositeVoice | Voice Providers | Mastra Docs"
+description: "Documentation for the CompositeVoice class, which enables combining multiple voice providers for flexible text-to-speech and speech-to-text operations."
+---
+
+# CompositeVoice
+
+The CompositeVoice class allows you to combine different voice providers for text-to-speech and speech-to-text operations. This is particularly useful when you want to use the best provider for each operation - for example, using OpenAI for speech-to-text and PlayAI for text-to-speech.
+
+CompositeVoice is used internally by the Agent class to provide flexible voice capabilities.
+
+## Usage Example
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { PlayAIVoice } from "@mastra/voice-playai";
+
+// Create voice providers
+const openai = new OpenAIVoice();
+const playai = new PlayAIVoice();
+
+// Use OpenAI for listening (speech-to-text) and PlayAI for speaking (text-to-speech)
+const voice = new CompositeVoice({
+  input: openai,
+  output: playai
+});
+
+// Convert speech to text using OpenAI
+const text = await voice.listen(audioStream);
+
+// Convert text to speech using PlayAI
+const audio = await voice.speak("Hello, world!");
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "config",
+      type: "object",
+      description: "Configuration object for the composite voice service",
+      isOptional: false,
+    },
+    {
+      name: "config.input",
+      type: "MastraVoice",
+      description: "Voice provider to use for speech-to-text operations",
+      isOptional: true,
+    },
+    {
+      name: "config.output",
+      type: "MastraVoice",
+      description: "Voice provider to use for text-to-speech operations",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Methods
+
+### speak()
+
+Converts text to speech using the configured speaking provider.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "string | NodeJS.ReadableStream",
+      description: "Text to convert to speech",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Provider-specific options passed to the speaking provider",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Notes:
+- If no speaking provider is configured, this method will throw an error
+- Options are passed through to the configured speaking provider
+- Returns a stream of audio data
+
+### listen()
+
+Converts speech to text using the configured listening provider.
+
+<PropertiesTable
+  content={[
+    {
+      name: "audioStream",
+      type: "NodeJS.ReadableStream",
+      description: "Audio stream to convert to text",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Provider-specific options passed to the listening provider",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Notes:
+- If no listening provider is configured, this method will throw an error
+- Options are passed through to the configured listening provider
+- Returns either a string or a stream of transcribed text, depending on the provider
+
+### getSpeakers()
+
+Returns a list of available voices from the speaking provider, where each node contains:
+
+<PropertiesTable
+  content={[
+    {
+      name: "voiceId",
+      type: "string",
+      description: "Unique identifier for the voice",
+      isOptional: false,
+    },
+    {
+      name: "key",
+      type: "value",
+      description: "Additional voice properties that vary by provider (e.g., name, language)",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Notes:
+- Returns voices from the speaking provider only
+- If no speaking provider is configured, returns an empty array
+- Each voice object will have at least a voiceId property
+- Additional voice properties depend on the speaking provider

package/.docs/raw/reference/voice/deepgram.mdx

@@ -0,0 +1,164 @@
+---
+title: "Reference: Deepgram Voice | Voice Providers | Mastra Docs"
+description: "Documentation for the Deepgram voice implementation, providing text-to-speech and speech-to-text capabilities with multiple voice models and languages."
+---
+
+# Deepgram
+
+The Deepgram voice implementation in Mastra provides text-to-speech (TTS) and speech-to-text (STT) capabilities using Deepgram's API. It supports multiple voice models and languages, with configurable options for both speech synthesis and transcription.
+
+## Usage Example
+
+```typescript
+import { DeepgramVoice } from "@mastra/voice-deepgram";
+
+// Initialize with default configuration (uses DEEPGRAM_API_KEY environment variable)
+const voice = new DeepgramVoice();
+
+// Initialize with custom configuration
+const voice = new DeepgramVoice({
+  speechModel: {
+    name: 'aura',
+    apiKey: 'your-api-key',
+  },
+  listeningModel: {
+    name: 'nova-2',
+    apiKey: 'your-api-key',
+  },
+  speaker: 'asteria-en',
+});
+
+// Text-to-Speech
+const audioStream = await voice.speak("Hello, world!");
+
+// Speech-to-Text
+const transcript = await voice.listen(audioStream);
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "speechModel",
+      type: "DeepgramVoiceConfig",
+      description: "Configuration for text-to-speech functionality.",
+      isOptional: true,
+      defaultValue: "{ name: 'aura' }"
+    },
+    {
+      name: "listeningModel",
+      type: "DeepgramVoiceConfig",
+      description: "Configuration for speech-to-text functionality.",
+      isOptional: true,
+      defaultValue: "{ name: 'nova' }"
+    },
+    {
+      name: "speaker",
+      type: "DeepgramVoiceId",
+      description: "Default voice to use for text-to-speech",
+      isOptional: true,
+      defaultValue: "'asteria-en'",
+    },
+  ]}
+/>
+
+### DeepgramVoiceConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "DeepgramModel",
+      description: "The Deepgram model to use",
+      isOptional: true,
+    },
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Deepgram API key. Falls back to DEEPGRAM_API_KEY environment variable",
+      isOptional: true,
+    },
+    {
+      name: "properties",
+      type: "Record<string, any>",
+      description: "Additional properties to pass to the Deepgram API",
+      isOptional: true,
+    },
+    {
+      name: "language",
+      type: "string",
+      description: "Language code for the model",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Methods
+
+### speak()
+
+Converts text to speech using the configured speech model and voice.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "string | NodeJS.ReadableStream",
+      description: "Text to convert to speech. If a stream is provided, it will be converted to text first.",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Additional options for speech synthesis",
+      isOptional: true,
+    },
+    {
+      name: "options.speaker",
+      type: "string",
+      description: "Override the default speaker for this request",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### listen()
+
+Converts speech to text using the configured listening model.
+
+<PropertiesTable
+  content={[
+    {
+      name: "audioStream",
+      type: "NodeJS.ReadableStream",
+      description: "Audio stream to transcribe",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Additional options to pass to the Deepgram API",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Returns: `Promise<string>`
+
+### getSpeakers()
+
+Returns a list of available voice options.
+
+<PropertiesTable
+  content={[
+    {
+      name: "voiceId",
+      type: "string",
+      description: "Unique identifier for the voice",
+      isOptional: false,
+    }
+  ]}
+/>

package/.docs/raw/reference/voice/elevenlabs.mdx

@@ -0,0 +1,216 @@
+---
+title: "Reference: ElevenLabs Voice | Voice Providers | Mastra Docs"
+description: "Documentation for the ElevenLabs voice implementation, offering high-quality text-to-speech capabilities with multiple voice models and natural-sounding synthesis."
+---
+
+# ElevenLabs
+
+The ElevenLabs voice implementation in Mastra provides high-quality text-to-speech (TTS) and speech-to-text (STT) capabilities using the ElevenLabs API.
+
+## Usage Example
+
+```typescript
+import { ElevenLabsVoice } from "@mastra/voice-elevenlabs";
+
+// Initialize with default configuration (uses ELEVENLABS_API_KEY environment variable)
+const voice = new ElevenLabsVoice();
+
+// Initialize with custom configuration
+const voice = new ElevenLabsVoice({
+  speechModel: {
+    name: 'eleven_multilingual_v2',
+    apiKey: 'your-api-key',
+  },
+  speaker: 'custom-speaker-id',
+});
+
+// Text-to-Speech
+const audioStream = await voice.speak("Hello, world!");
+
+// Get available speakers
+const speakers = await voice.getSpeakers();
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "speechModel",
+      type: "ElevenLabsVoiceConfig",
+      description: "Configuration for text-to-speech functionality.",
+      isOptional: true,
+      defaultValue: "{ name: 'eleven_multilingual_v2' }"
+    },
+    {
+      name: "speaker",
+      type: "string",
+      description: "ID of the speaker to use for text-to-speech",
+      isOptional: true,
+      defaultValue: "'9BWtsMINqrJLrRacOk9x' (Aria voice)",
+    },
+  ]}
+/>
+
+### ElevenLabsVoiceConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "ElevenLabsModel",
+      description: "The ElevenLabs model to use",
+      isOptional: true,
+      defaultValue: "'eleven_multilingual_v2'",
+    },
+    {
+      name: "apiKey",
+      type: "string",
+      description: "ElevenLabs API key. Falls back to ELEVENLABS_API_KEY environment variable",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Methods
+
+### speak()
+
+Converts text to speech using the configured speech model and voice.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "string | NodeJS.ReadableStream",
+      description: "Text to convert to speech. If a stream is provided, it will be converted to text first.",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Additional options for speech synthesis",
+      isOptional: true,
+    },
+    {
+      name: "options.speaker",
+      type: "string",
+      description: "Override the default speaker ID for this request",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### getSpeakers()
+
+Returns an array of available voice options, where each node contains:
+
+<PropertiesTable
+  content={[
+    {
+      name: "voiceId",
+      type: "string",
+      description: "Unique identifier for the voice",
+      isOptional: false,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Display name of the voice",
+      isOptional: false,
+    },
+    {
+      name: "language",
+      type: "string",
+      description: "Language code for the voice",
+      isOptional: false,
+    },
+    {
+      name: "gender",
+      type: "string",
+      description: "Gender of the voice",
+      isOptional: false,
+    }
+  ]}
+/>
+
+### listen()
+
+Converts audio input to text using ElevenLabs Speech-to-Text API.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "NodeJS.ReadableStream",
+      description: "A readable stream containing the audio data to transcribe",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Configuration options for the transcription",
+      isOptional: true,
+    },
+  ]}
+/>
+
+The options object supports the following properties:
+
+<PropertiesTable
+  content={[
+    {
+      name: "language_code",
+      type: "string",
+      description: "ISO language code (e.g., 'en', 'fr', 'es')",
+      isOptional: true,
+    },
+    {
+      name: "tag_audio_events",
+      type: "boolean",
+      description: "Whether to tag audio events like [MUSIC], [LAUGHTER], etc.",
+      isOptional: true,
+    },
+    {
+      name: "num_speakers",
+      type: "number",
+      description: "Number of speakers to detect in the audio",
+      isOptional: true,
+    },
+    {
+      name: "filetype",
+      type: "string",
+      description: "Audio file format (e.g., 'mp3', 'wav', 'ogg')",
+      isOptional: true,
+    },
+    {
+      name: "timeoutInSeconds",
+      type: "number",
+      description: "Request timeout in seconds",
+      isOptional: true,
+    },
+    {
+      name: "maxRetries",
+      type: "number",
+      description: "Maximum number of retry attempts",
+      isOptional: true,
+    },
+    {
+      name: "abortSignal",
+      type: "AbortSignal",
+      description: "Signal to abort the request",
+      isOptional: true,
+    }
+  ]}
+/>
+
+Returns: `Promise<string>` - A Promise that resolves to the transcribed text
+
+## Important Notes
+
+1. An ElevenLabs API key is required. Set it via the `ELEVENLABS_API_KEY` environment variable or pass it in the constructor.
+2. The default speaker is set to Aria (ID: '9BWtsMINqrJLrRacOk9x').
+3. Speech-to-text functionality is not supported by ElevenLabs.
+4. Available speakers can be retrieved using the `getSpeakers()` method, which returns detailed information about each voice including language and gender.

package/.docs/raw/reference/voice/google.mdx

@@ -0,0 +1,198 @@
+---
+title: "Reference: Google Voice | Voice Providers | Mastra Docs"
+description: "Documentation for the Google Voice implementation, providing text-to-speech and speech-to-text capabilities."
+---
+
+# Google
+
+The Google Voice implementation in Mastra provides both text-to-speech (TTS) and speech-to-text (STT) capabilities using Google Cloud services. It supports multiple voices, languages, and advanced audio configuration options.
+
+## Usage Example
+
+```typescript
+import { GoogleVoice } from "@mastra/voice-google";
+
+// Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
+const voice = new GoogleVoice();
+
+// Initialize with custom configuration
+const voice = new GoogleVoice({
+  speechModel: {
+    apiKey: 'your-speech-api-key',
+  },
+  listeningModel: {
+    apiKey: 'your-listening-api-key',
+  },
+  speaker: 'en-US-Casual-K',
+});
+
+// Text-to-Speech
+const audioStream = await voice.speak("Hello, world!", {
+  languageCode: 'en-US',
+  audioConfig: {
+    audioEncoding: 'LINEAR16',
+  },
+});
+
+// Speech-to-Text
+const transcript = await voice.listen(audioStream, {
+  config: {
+    encoding: 'LINEAR16',
+    languageCode: 'en-US',
+  },
+});
+
+// Get available voices for a specific language
+const voices = await voice.getSpeakers({ languageCode: 'en-US' });
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "speechModel",
+      type: "GoogleModelConfig",
+      description: "Configuration for text-to-speech functionality",
+      isOptional: true,
+      defaultValue: "{ apiKey: process.env.GOOGLE_API_KEY }",
+    },
+    {
+      name: "listeningModel",
+      type: "GoogleModelConfig",
+      description: "Configuration for speech-to-text functionality",
+      isOptional: true,
+      defaultValue: "{ apiKey: process.env.GOOGLE_API_KEY }",
+    },
+    {
+      name: "speaker",
+      type: "string",
+      description: "Default voice ID to use for text-to-speech",
+      isOptional: true,
+      defaultValue: "'en-US-Casual-K'",
+    },
+  ]}
+/>
+
+### GoogleModelConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Google Cloud API key. Falls back to GOOGLE_API_KEY environment variable",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Methods
+
+### speak()
+
+Converts text to speech using Google Cloud Text-to-Speech service.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "string | NodeJS.ReadableStream",
+      description: "Text to convert to speech. If a stream is provided, it will be converted to text first.",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Speech synthesis options",
+      isOptional: true,
+    },
+    {
+      name: "options.speaker",
+      type: "string",
+      description: "Voice ID to use for this request",
+      isOptional: true,
+    },
+    {
+      name: "options.languageCode",
+      type: "string",
+      description: "Language code for the voice (e.g., 'en-US'). Defaults to the language code from the speaker ID or 'en-US'",
+      isOptional: true,
+    },
+    {
+      name: "options.audioConfig",
+      type: "ISynthesizeSpeechRequest['audioConfig']",
+      description: "Audio configuration options from Google Cloud Text-to-Speech API",
+      isOptional: true,
+      defaultValue: "{ audioEncoding: 'LINEAR16' }",
+    },
+  ]}
+/>
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### listen()
+
+Converts speech to text using Google Cloud Speech-to-Text service.
+
+<PropertiesTable
+  content={[
+    {
+      name: "audioStream",
+      type: "NodeJS.ReadableStream",
+      description: "Audio stream to transcribe",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Recognition options",
+      isOptional: true,
+    },
+    {
+      name: "options.stream",
+      type: "boolean",
+      description: "Whether to use streaming recognition",
+      isOptional: true,
+    },
+    {
+      name: "options.config",
+      type: "IRecognitionConfig",
+      description: "Recognition configuration from Google Cloud Speech-to-Text API",
+      isOptional: true,
+      defaultValue: "{ encoding: 'LINEAR16', languageCode: 'en-US' }",
+    },
+  ]}
+/>
+
+Returns: `Promise<string>`
+
+### getSpeakers()
+
+Returns an array of available voice options, where each node contains:
+
+<PropertiesTable
+  content={[
+    {
+      name: "voiceId",
+      type: "string",
+      description: "Unique identifier for the voice",
+      isOptional: false,
+    },
+    {
+      name: "languageCodes",
+      type: "string[]",
+      description: "List of language codes supported by this voice",
+      isOptional: false,
+    }
+  ]}
+/>
+
+## Important Notes
+
+1. A Google Cloud API key is required. Set it via the `GOOGLE_API_KEY` environment variable or pass it in the constructor.
+2. The default voice is set to 'en-US-Casual-K'.
+3. Both text-to-speech and speech-to-text services use LINEAR16 as the default audio encoding.
+4. The `speak()` method supports advanced audio configuration through the Google Cloud Text-to-Speech API.
+5. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
+6. Available voices can be filtered by language code using the `getSpeakers()` method.