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

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

@@ -0,0 +1,159 @@
+---
+title: "Reference: PlayAI Voice | Voice Providers | Mastra Docs"
+description: "Documentation for the PlayAI voice implementation, providing text-to-speech capabilities."
+---
+
+# PlayAI
+
+The PlayAI voice implementation in Mastra provides text-to-speech capabilities using PlayAI's API.
+
+## Usage Example
+
+```typescript
+import { PlayAIVoice } from "@mastra/voice-playai";
+
+// Initialize with default configuration (uses PLAYAI_API_KEY environment variable and PLAYAI_USER_ID environment variable)
+const voice = new PlayAIVoice();
+
+// Initialize with default configuration
+const voice = new PlayAIVoice({
+  speechModel: {
+    name: 'PlayDialog',
+    apiKey: process.env.PLAYAI_API_KEY,
+    userId: process.env.PLAYAI_USER_ID
+  },
+  speaker: 'Angelo'  // Default voice
+});
+
+// Convert text to speech with a specific voice
+const audioStream = await voice.speak("Hello, world!", {
+  speaker: 's3://voice-cloning-zero-shot/b27bc13e-996f-4841-b584-4d35801aea98/original/manifest.json' // Dexter voice
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "speechModel",
+      type: "PlayAIConfig",
+      description: "Configuration for text-to-speech functionality",
+      isOptional: true,
+      defaultValue: "{ name: 'PlayDialog' }",
+    },
+    {
+      name: "speaker",
+      type: "string",
+      description: "Default voice ID to use for speech synthesis",
+      isOptional: true,
+      defaultValue: "First available voice ID",
+    },
+  ]}
+/>
+
+### PlayAIConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "'PlayDialog' | 'Play3.0-mini'",
+      description: "The PlayAI model to use",
+      isOptional: true,
+      defaultValue: "'PlayDialog'",
+    },
+    {
+      name: "apiKey",
+      type: "string",
+      description: "PlayAI API key. Falls back to PLAYAI_API_KEY environment variable",
+      isOptional: true,
+    },
+    {
+      name: "userId",
+      type: "string",
+      description: "PlayAI user ID. Falls back to PLAYAI_USER_ID 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.speaker",
+      type: "string",
+      description: "Override the default speaker for this request",
+      isOptional: true,
+      defaultValue: "Constructor's speaker value",
+    },
+  ]}
+/>
+
+Returns: `Promise<NodeJS.ReadableStream>`.
+
+### getSpeakers()
+
+Returns an array of available voice options, where each node contains:
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "string",
+      description: "Name of the voice",
+      isOptional: false,
+    },
+    {
+      name: "accent",
+      type: "string",
+      description: "Accent of the voice (e.g., 'US', 'British', 'Australian')",
+      isOptional: false,
+    },
+    {
+      name: "gender",
+      type: "'M' | 'F'",
+      description: "Gender of the voice",
+      isOptional: false,
+    },
+    {
+      name: "age",
+      type: "'Young' | 'Middle' | 'Old'",
+      description: "Age category of the voice",
+      isOptional: false,
+    },
+    {
+      name: "style",
+      type: "'Conversational' | 'Narrative'",
+      description: "Speaking style of the voice",
+      isOptional: false,
+    },
+    {
+      name: "voiceId",
+      type: "string",
+      description: "Unique identifier for the voice",
+      isOptional: false,
+    },
+  ]}
+/>
+### listen()
+
+This method is not supported by PlayAI and will throw an error. PlayAI does not provide speech-to-text functionality.
+
+## Notes
+
+- PlayAI requires both an API key and a user ID for authentication
+- The service offers two models: 'PlayDialog' and 'Play3.0-mini'
+- Each voice has a unique S3 manifest ID that must be used when making API calls

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

@@ -0,0 +1,260 @@
+---
+title: "Reference: Sarvam Voice | Voice Providers | Mastra Docs"
+description: "Documentation for the Sarvam class, providing text-to-speech and speech-to-text capabilities."
+---
+
+# Sarvam
+
+The SarvamVoice class in Mastra provides text-to-speech and speech-to-text capabilities using Sarvam AI models.
+
+## Usage Example
+
+```typescript
+import { SarvamVoice } from "@mastra/voice-sarvam";
+
+// Initialize with default configuration using environment variables
+const voice = new SarvamVoice();
+
+// Or initialize with specific configuration
+const voiceWithConfig = new SarvamVoice({
+   speechModel: {
+    model: "bulbul:v1",
+    apiKey: process.env.SARVAM_API_KEY!,
+    language: "en-IN",
+    properties: {
+      pitch: 0,
+      pace: 1.65,
+      loudness: 1.5,
+      speech_sample_rate: 8000,
+      enable_preprocessing: false,
+      eng_interpolation_wt: 123,
+    },
+  },
+  listeningModel: {
+    model: "saarika:v2",
+    apiKey: process.env.SARVAM_API_KEY!,
+    languageCode: "en-IN",
+     filetype?: 'wav';
+  },
+  speaker: "meera", // Default voice
+});
+
+
+// Convert text to speech
+const audioStream = await voice.speak("Hello, how can I help you?");
+
+
+// Convert speech to text
+const text = await voice.listen(audioStream, {
+  filetype: "wav",
+});
+```
+
+### Sarvam API Docs -
+
+https://docs.sarvam.ai/api-reference-docs/endpoints/text-to-speech
+
+## Configuration
+
+### Constructor Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "speechModel",
+      type: "SarvamVoiceConfig",
+      description: "Configuration for text-to-speech synthesis.",
+      isOptional: true,
+      defaultValue: "{ model: 'bulbul:v1', language: 'en-IN' }",
+    },
+    {
+      name: "speaker",
+      type: "SarvamVoiceId",
+      description:
+        "The speaker to be used for the output audio. If not provided, Meera will be used as default. AvailableOptions - meera, pavithra, maitreyi, arvind, amol, amartya, diya, neel, misha, vian, arjun, maya",
+      isOptional: true,
+      defaultValue: "'meera'",
+    },
+    {
+      name: "listeningModel",
+      type: "SarvamListenOptions",
+      description: "Configuration for speech-to-text recognition.",
+      isOptional: true,
+      defaultValue: "{ model: 'saarika:v2', language_code: 'unknown' }",
+    },
+  ]}
+/>
+
+### SarvamVoiceConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "apiKey",
+      type: "string",
+      description:
+        "Sarvam API key. Falls back to SARVAM_API_KEY environment variable.",
+      isOptional: true,
+    },
+    {
+      name: "model",
+      type: "SarvamTTSModel",
+      description: "Specifies the model to use for text-to-speech conversion.",
+      isOptional: true,
+      defaultValue: "'bulbul:v1'",
+    },
+    {
+      name: "language",
+      type: "SarvamTTSLanguage",
+      description:
+        "Target language for speech synthesis. Available options: hi-IN, bn-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN, en-IN, gu-IN",
+      isOptional: false,
+      defaultValue: "'en-IN'",
+    },
+    {
+      name: "properties",
+      type: "object",
+      description: "Additional voice properties for customization.",
+      isOptional: true,
+    },
+    {
+      name: "properties.pitch",
+      type: "number",
+      description:
+        "Controls the pitch of the audio. Lower values result in a deeper voice, while higher values make it sharper. The suitable range is between -0.75 and 0.75.",
+      isOptional: true,
+    },
+    {
+      name: "properties.pace",
+      type: "number",
+      description:
+        "Controls the speed of the audio. Lower values result in slower speech, while higher values make it faster. The suitable range is between 0.5 and 2.0. Default is 1.0. Required range: 0.3 <= x <= 3",
+      isOptional: true,
+    },
+    {
+      name: "properties.loudness",
+      type: "number",
+      description:
+        "Controls the loudness of the audio. Lower values result in quieter audio, while higher values make it louder. The suitable range is between 0.3 and 3.0. Required range: 0 <= x <= 3",
+      isOptional: true,
+    },
+    {
+      name: "properties.speech_sample_rate",
+      type: "8000 | 16000 | 22050",
+      description: "Audio sample rate in Hz.",
+      isOptional: true,
+    },
+    {
+      name: "properties.enable_preprocessing",
+      type: "boolean",
+      description:
+        "Controls whether normalization of English words and numeric entities (e.g., numbers, dates) is performed. Set to true for better handling of mixed-language text. Default is false.",
+      isOptional: true,
+    },
+    {
+      name: "properties.eng_interpolation_wt",
+      type: "number",
+      description: "Weight for interpolating with English speaker at encoder.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### SarvamListenOptions
+
+<PropertiesTable
+  content={[
+    {
+      name: "apiKey",
+      type: "string",
+      description:
+        "Sarvam API key. Falls back to SARVAM_API_KEY environment variable.",
+      isOptional: true,
+    },
+    {
+      name: "model",
+      type: "SarvamSTTModel",
+      description:
+        "Specifies the model to use for speech-to-text conversion. Note:- Default model is saarika:v2 . Available options: saarika:v1, saarika:v2, saarika:flash ",
+      isOptional: true,
+      defaultValue: "'saarika:v2'",
+    },
+    {
+      name: "languageCode",
+      type: "SarvamSTTLanguage",
+      description:
+        "Specifies the language of the input audio. This parameter is required to ensure accurate transcription. For the saarika:v1 model, this parameter is mandatory. For the saarika:v2 model, it is optional. unknown: Use this when the language is not known; the API will detect it automatically. Note:- that the saarika:v1 model does not support unknown language code. Available options: unknown, hi-IN, bn-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN, en-IN, gu-IN ",
+      isOptional: true,
+      defaultValue: "'unknown'",
+    },
+    {
+      name: "filetype",
+      type: "'mp3' | 'wav'",
+      description: "Audio format of the input stream.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Methods
+
+### speak()
+
+Converts text to speech using Sarvam's text-to-speech models.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "string | NodeJS.ReadableStream",
+      description: "Text or text stream to convert to speech.",
+      isOptional: false,
+    },
+    {
+      name: "options.speaker",
+      type: "SarvamVoiceId",
+      description: "Voice ID to use for speech synthesis.",
+      isOptional: true,
+      defaultValue: "Constructor's speaker value",
+    },
+  ]}
+/>
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### listen()
+
+Transcribes audio using Sarvam's speech recognition models.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "NodeJS.ReadableStream",
+      description: "Audio stream to transcribe.",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "SarvamListenOptions",
+      description: "Configuration options for speech recognition.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Returns: `Promise<string>`
+
+### getSpeakers()
+
+Returns an array of available voice options.
+
+Returns: `Promise<Array<{voiceId: SarvamVoiceId}>>`
+
+## Notes
+
+- API key can be provided via constructor options or the `SARVAM_API_KEY` environment variable
+- If no API key is provided, the constructor will throw an error
+- The service communicates with the Sarvam AI API at `https://api.sarvam.ai`
+- Audio is returned as a stream containing binary audio data
+- Speech recognition supports mp3 and wav audio formats

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

@@ -0,0 +1,145 @@
+---
+title: "Reference: Speechify Voice | Voice Providers | Mastra Docs"
+description: "Documentation for the Speechify voice implementation, providing text-to-speech capabilities."
+---
+
+# Speechify
+
+The Speechify voice implementation in Mastra provides text-to-speech capabilities using Speechify's API.
+
+## Usage Example
+
+```typescript
+import { SpeechifyVoice } from "@mastra/voice-speechify";
+
+// Initialize with default configuration (uses SPEECHIFY_API_KEY environment variable)
+const voice = new SpeechifyVoice();
+
+// Initialize with custom configuration
+const voice = new SpeechifyVoice({
+  speechModel: {
+    name: 'simba-english',
+    apiKey: 'your-api-key'
+  },
+  speaker: 'george'  // Default voice
+});
+
+// Convert text to speech
+const audioStream = await voice.speak("Hello, world!", {
+  speaker: 'henry',  // Override default voice
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "speechModel",
+      type: "SpeechifyConfig",
+      description: "Configuration for text-to-speech functionality",
+      isOptional: true,
+      defaultValue: "{ name: 'simba-english' }",
+    },
+    {
+      name: "speaker",
+      type: "SpeechifyVoiceId",
+      description: "Default voice ID to use for speech synthesis",
+      isOptional: true,
+      defaultValue: "'george'",
+    },
+  ]}
+/>
+
+### SpeechifyConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "VoiceModelName",
+      description: "The Speechify model to use",
+      isOptional: true,
+      defaultValue: "'simba-english'",
+    },
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Speechify API key. Falls back to SPEECHIFY_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.speaker",
+      type: "string",
+      description: "Override the default speaker for this request",
+      isOptional: true,
+      defaultValue: "Constructor's speaker value",
+    },
+    {
+      name: "options.model",
+      type: "VoiceModelName",
+      description: "Override the default model for this request",
+      isOptional: true,
+      defaultValue: "Constructor's model value",
+    },
+  ]}
+/>
+
+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",
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Display name of the voice",
+    },
+    {
+      name: "language",
+      type: "string",
+      description: "Language code for the voice",
+    },
+    {
+      name: "gender",
+      type: "string",
+      description: "Gender of the voice",
+    },
+  ]}
+/>
+
+### listen()
+
+This method is not supported by Speechify and will throw an error. Speechify does not provide speech-to-text functionality.
+
+## Notes
+
+- Speechify requires an API key for authentication
+- The default model is 'simba-english'
+- Speech-to-text functionality is not supported
+- Additional audio stream options can be passed through the speak() method's options parameter

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

@@ -0,0 +1,122 @@
+---
+title: "Reference: voice.answer() | Voice Providers | Mastra Docs"
+description: "Documentation for the answer() method available in real-time voice providers, which triggers the voice provider to generate a response."
+---
+
+# voice.answer()
+
+The `answer()` method is used in real-time voice providers to trigger the AI to generate a response. This method is particularly useful in speech-to-speech conversations where you need to explicitly signal the AI to respond after receiving user input.
+
+## Usage Example
+
+```typescript
+import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+import Speaker from "@mastra/node-speaker";
+
+const speaker = new Speaker({
+  sampleRate: 24100,  // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
+  channels: 1,        // Mono audio output (as opposed to stereo which would be 2)
+  bitDepth: 16,       // Bit depth for audio quality - CD quality standard (16-bit resolution)
+});
+
+// Initialize a real-time voice provider
+const voice = new OpenAIRealtimeVoice({
+  realtimeConfig: {
+    model: "gpt-4o",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+  speaker: "alloy", // Default voice
+});
+// Connect to the real-time service
+await voice.connect();
+// Register event listener for responses
+voice.on("speaker", (stream) => {
+  // Handle audio response
+  stream.pipe(speaker);
+});
+// Send user audio input
+const microphoneStream = getMicrophoneStream();
+await voice.send(microphoneStream);
+// Trigger the AI to respond
+await voice.answer();
+// With custom options (provider-specific)
+await voice.answer({
+  options: {
+    content: "Hello, how can I help you today?",
+    voice: "nova",
+  },
+});
+```
+
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "Record<string, unknown>",
+      description: "Provider-specific options for the response",
+      isOptional: true,
+    }
+  ]}
+/>
+
+## Return Value
+
+Returns a `Promise<void>` that resolves when the response has been triggered.
+
+## Provider-Specific Options
+
+Each real-time voice provider may support different options for the `answer()` method:
+
+### OpenAI Realtime
+
+<PropertiesTable
+  content={[
+    {
+      name: "options.content",
+      type: "string",
+      description: "Text content to use for the response instead of generating one",
+      isOptional: true,
+    },
+    {
+      name: "options.voice",
+      type: "string",
+      description: "Voice ID to use for this specific response",
+      isOptional: true,
+    }
+  ]}
+/>
+
+## Using with CompositeVoice
+
+When using `CompositeVoice`, the `answer()` method delegates to the configured real-time provider:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+const realtimeVoice = new OpenAIRealtimeVoice();
+const voice = new CompositeVoice({
+  realtimeProvider: realtimeVoice,
+});
+// Connect to the real-time service
+await voice.connect();
+// This will use the OpenAIRealtimeVoice provider
+await voice.answer();
+```
+
+## Notes
+
+- This method is only implemented by real-time voice providers that support speech-to-speech capabilities
+- If called on a voice provider that doesn't support this functionality, it will log a warning and resolve immediately
+- The response audio will typically be emitted through the 'speaking' event rather than returned directly
+- For providers that support it, you can use this method to send a specific response instead of having the AI generate one
+- This method is commonly used in conjunction with `send()` to create a conversational flow
+
+## Related Methods
+
+- [voice.connect()](./voice.connect) - Establishes a connection to the real-time service
+- [voice.send()](./voice.send) - Sends audio data to the voice provider
+- [voice.speak()](./voice.speak) - Converts text to speech
+- [voice.listen()](./voice.listen) - Converts speech to text