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

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

@@ -0,0 +1,203 @@
+---
+title: "Reference: voice.speak() | Voice Providers | Mastra Docs"
+description: "Documentation for the speak() method available in all Mastra voice providers, which converts text to speech."
+---
+
+# voice.speak()
+
+The `speak()` method is a core function available in all Mastra voice providers that converts text to speech. It takes text input and returns an audio stream that can be played or saved.
+
+## Usage Example
+
+```typescript
+import { OpenAIVoice } from "@mastra/voice-openai";
+// Initialize a voice provider
+const voice = new OpenAIVoice({
+  speaker: "alloy", // Default voice
+});
+// Basic usage with default settings
+const audioStream = await voice.speak("Hello, world!");
+// Using a different voice for this specific request
+const audioStreamWithDifferentVoice = await voice.speak("Hello again!", {
+  speaker: "nova",
+});
+// Using provider-specific options
+const audioStreamWithOptions = await voice.speak("Hello with options!", {
+  speaker: "echo",
+  speed: 1.2, // OpenAI-specific option
+});
+// Using a text stream as input
+import { Readable } from "stream";
+const textStream = Readable.from(["Hello", " from", " a", " stream!"]);
+const audioStreamFromTextStream = await voice.speak(textStream);
+```
+
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "string | NodeJS.ReadableStream",
+      description: "Text to convert to speech. Can be a string or a readable stream of text.",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Options for speech synthesis",
+      isOptional: true,
+    },
+    {
+      name: "options.speaker",
+      type: "string",
+      description: "Voice ID to use for this specific request. Overrides the default speaker set in the constructor.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Return Value
+
+Returns a `Promise<NodeJS.ReadableStream | void>` where:
+
+- `NodeJS.ReadableStream`: A stream of audio data that can be played or saved
+- `void`: When using a realtime voice provider that emits audio through events instead of returning it directly
+
+## Provider-Specific Options
+
+Each voice provider may support additional options specific to their implementation. Here are some examples:
+
+### OpenAI
+
+<PropertiesTable
+  content={[
+    {
+      name: "options.speed",
+      type: "number",
+      description: "Speech speed multiplier. Values between 0.25 and 4.0 are supported.",
+      isOptional: true,
+      defaultValue: "1.0",
+    }
+  ]}
+/>
+
+### ElevenLabs
+
+<PropertiesTable
+  content={[
+    {
+      name: "options.stability",
+      type: "number",
+      description: "Voice stability. Higher values result in more stable, less expressive speech.",
+      isOptional: true,
+      defaultValue: "0.5",
+    },
+    {
+      name: "options.similarity_boost",
+      type: "number",
+      description: "Voice clarity and similarity to the original voice.",
+      isOptional: true,
+      defaultValue: "0.75",
+    }
+  ]}
+/>
+
+### Google
+
+<PropertiesTable
+  content={[
+    {
+      name: "options.languageCode",
+      type: "string",
+      description: "Language code for the voice (e.g., 'en-US').",
+      isOptional: true,
+    },
+    {
+      name: "options.audioConfig",
+      type: "object",
+      description: "Audio configuration options from Google Cloud Text-to-Speech API.",
+      isOptional: true,
+      defaultValue: "{ audioEncoding: 'LINEAR16' }",
+    }
+  ]}
+/>
+
+### Murf
+
+<PropertiesTable
+  content={[
+    {
+      name: "options.properties.rate",
+      type: "number",
+      description: "Speech rate multiplier.",
+      isOptional: true,
+    },
+    {
+      name: "options.properties.pitch",
+      type: "number",
+      description: "Voice pitch adjustment.",
+      isOptional: true,
+    },
+    {
+      name: "options.properties.format",
+      type: "'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'",
+      description: "Output audio format.",
+      isOptional: true,
+    }
+  ]}
+/>
+
+## Realtime Voice Providers
+
+When using realtime voice providers like `OpenAIRealtimeVoice`, the `speak()` method behaves differently:
+
+- Instead of returning an audio stream, it emits a 'speaking' event with the audio data
+- You need to register an event listener to receive the audio chunks
+
+```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)
+});
+
+const voice = new OpenAIRealtimeVoice();
+await voice.connect();
+// Register event listener for audio chunks
+voice.on("speaker", (stream) => {
+  // Handle audio chunk (e.g., play it or save it)
+  stream.pipe(speaker)
+});
+// This will emit 'speaking' events instead of returning a stream
+await voice.speak("Hello, this is realtime speech!");
+```
+
+
+## Using with CompositeVoice
+
+When using `CompositeVoice`, the `speak()` method delegates to the configured speaking provider:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { PlayAIVoice } from "@mastra/voice-playai";
+const voice = new CompositeVoice({
+  speakProvider: new PlayAIVoice(),
+  listenProvider: new OpenAIVoice(),
+});
+// This will use the PlayAIVoice provider
+const audioStream = await voice.speak("Hello, world!");
+```
+
+## Notes
+
+- The behavior of `speak()` may vary slightly between providers, but all implementations follow the same basic interface.
+- When using a realtime voice provider, the method might not return an audio stream directly but instead emit a 'speaking' event.
+- If a text stream is provided as input, the provider will typically convert it to a string before processing.
+- The audio format of the returned stream depends on the provider. Common formats include MP3, WAV, and OGG.
+- For best performance, consider closing or ending the audio stream when you're done with it.

package/.docs/raw/reference/workflows/after.mdx

@@ -0,0 +1,88 @@
+---
+title: "Reference: .after() | Building Workflows | Mastra Docs"
+description: Documentation for the `after()` method in workflows, enabling branching and merging paths.
+---
+
+# .after()
+
+The `.after()` method defines explicit dependencies between workflow steps, enabling branching and merging paths in your workflow execution.
+
+## Usage
+
+### Basic Branching
+
+```typescript
+workflow
+  .step(stepA)
+    .then(stepB)
+  .after(stepA)  // Create new branch after stepA completes
+    .step(stepC);
+```
+
+### Merging Multiple Branches
+
+```typescript
+workflow
+  .step(stepA)
+    .then(stepB)
+  .step(stepC)
+    .then(stepD)
+  .after([stepB, stepD])  // Create a step that depends on multiple steps
+    .step(stepE);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "steps",
+      type: "Step | Step[]",
+      description: "A single step or array of steps that must complete before continuing",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining"
+    }
+  ]}
+/>
+
+## Examples
+
+### Single Dependency
+
+```typescript
+workflow
+  .step(fetchData)
+  .then(processData)
+  .after(fetchData)  // Branch after fetchData
+  .step(logData);
+```
+
+### Multiple Dependencies (Merging Branches)
+
+```typescript
+workflow
+  .step(fetchUserData)
+  .then(validateUserData)
+  .step(fetchProductData)
+  .then(validateProductData)
+  .after([validateUserData, validateProductData])  // Wait for both validations to complete
+  .step(processOrder);
+```
+
+## Related
+
+- [Branching Paths example](../../../examples/workflows/branching-paths.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Step Reference](./step-class.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx#merging-multiple-branches)

package/.docs/raw/reference/workflows/afterEvent.mdx

@@ -0,0 +1,76 @@
+---
+title: ".afterEvent() Method | Mastra Docs"
+description: "Reference for the afterEvent method in Mastra workflows that creates event-based suspension points."
+---
+
+# afterEvent()
+
+The `afterEvent()` method creates a suspension point in your workflow that waits for a specific event to occur before continuing execution.
+
+## Syntax
+
+```typescript
+workflow.afterEvent(eventName: string): Workflow
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| eventName | string | The name of the event to wait for. Must match an event defined in the workflow's `events` configuration. |
+
+## Return Value
+
+Returns the workflow instance for method chaining.
+
+## Description
+
+The `afterEvent()` method is used to create an automatic suspension point in your workflow that waits for a specific named event. It's essentially a declarative way to define a point where your workflow should pause and wait for an external event to occur.
+
+When you call `afterEvent()`, Mastra:
+
+1. Creates a special step with ID `__eventName_event`
+2. This step automatically suspends the workflow execution
+3. The workflow remains suspended until the specified event is triggered via `resumeWithEvent()`
+4. When the event occurs, execution continues with the step following the `afterEvent()` call
+
+This method is part of Mastra's event-driven workflow capabilities, allowing you to create workflows that coordinate with external systems or user interactions without manually implementing suspension logic.
+
+## Usage Notes
+
+- The event specified in `afterEvent()` must be defined in the workflow's `events` configuration with a schema
+- The special step created has a predictable ID format: `__eventName_event` (e.g., `__approvalReceived_event`)
+- Any step following `afterEvent()` can access the event data via `context.inputData.resumedEvent`
+- Event data is validated against the schema defined for that event when `resumeWithEvent()` is called
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Define workflow with events
+const workflow = new Workflow({
+  name: 'approval-workflow',
+  events: {
+    approval: {
+      schema: z.object({
+        approved: z.boolean(),
+        approverName: z.string(),
+      }),
+    },
+  },
+});
+
+// Build workflow with event suspension point
+workflow
+  .step(submitRequest)
+  .afterEvent('approval')    // Workflow suspends here
+  .step(processApproval)     // This step runs after the event occurs
+  .commit();
+```
+## Related
+
+- [Event-Driven Workflows](./events.mdx)
+- [resumeWithEvent()](./resumeWithEvent.mdx)
+- [Suspend and Resume](../../workflows/suspend-and-resume.mdx)
+- [Workflow Class](./workflow.mdx)

package/.docs/raw/reference/workflows/commit.mdx

@@ -0,0 +1,37 @@
+---
+title: "Reference: Workflow.commit() | Running Workflows | Mastra Docs"
+description: Documentation for the `.commit()` method in workflows, which re-initializes the workflow machine with the current step configuration.
+---
+
+# Workflow.commit()
+
+The `.commit()` method re-initializes the workflow's state machine with the current step configuration.
+
+## Usage
+
+```typescript
+workflow
+  .step(stepA)
+  .then(stepB)
+  .commit();
+```
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance"
+    }
+  ]}
+/>
+
+## Related
+
+- [Branching Paths example](../../../examples/workflows/branching-paths.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Step Reference](./step-class.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```

package/.docs/raw/reference/workflows/createRun.mdx

@@ -0,0 +1,77 @@
+---
+title: "Reference: Workflow.createRun() | Running Workflows | Mastra Docs"
+description: "Documentation for the `.createRun()` method in workflows, which initializes a new workflow run instance."
+---
+
+# Workflow.createRun()
+
+The `.createRun()` method initializes a new workflow run instance. It generates a unique run ID for tracking and returns a start function that begins workflow execution when called.
+
+One reason to use `.createRun()` vs `.execute()` is to get a unique run ID for tracking, logging, or subscribing via `.watch()`.
+
+## Usage
+
+```typescript
+const { runId, start, watch } = workflow.createRun();
+
+const result = await start();
+```
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "runId",
+      type: "string",
+      description: "Unique identifier for tracking this workflow run",
+    },
+    {
+      name: "start",
+      type: "() => Promise<WorkflowResult>",
+      description: "Function that begins workflow execution when called",
+    },
+    {
+      name: "watch",
+      type: "(callback: (record: WorkflowResult) => void) => () => void",
+      description: "Function that accepts a callback function that will be called with each transition of the workflow run",
+    },
+    {
+      name: "resume",
+      type: "({stepId: string, context: Record<string, any>}) => Promise<WorkflowResult>",
+      description: "Function that resumes a workflow run from a given step ID and context",
+    },
+    {
+      name: "resumeWithEvent",
+      type: "(eventName: string, data: any) => Promise<WorkflowResult>",
+      description: "Function that resumes a workflow run from a given event name and data",
+    },
+  ]}
+/>
+
+## Error Handling
+
+The start function may throw validation errors if the workflow configuration is invalid:
+
+```typescript
+try {
+  const { runId, start, watch, resume, resumeWithEvent } = workflow.createRun();
+  await start({ triggerData: data });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // Handle validation errors
+    console.log(error.type); // 'circular_dependency' | 'no_terminal_path' | 'unreachable_step'
+    console.log(error.details);
+  }
+}
+```
+
+## Related
+
+- [Workflow Class Reference](./workflow.mdx)
+- [Step Class Reference](./step-class.mdx)
+- See the [Creating a Workflow](../../../examples/workflows/creating-a-workflow.mdx) example for complete usage
+
+```
+
+```

package/.docs/raw/reference/workflows/else.mdx

@@ -0,0 +1,72 @@
+---
+title: "Reference: Workflow.else() | Conditional Branching | Mastra Docs"
+description: "Documentation for the `.else()` method in Mastra workflows, which creates an alternative branch when an if condition is false."
+---
+
+# Workflow.else()
+
+> Experimental
+
+The `.else()` method creates an alternative branch in the workflow that executes when the preceding `if` condition evaluates to false. This enables workflows to follow different paths based on conditions.
+
+## Usage
+
+```typescript copy showLineNumbers
+workflow
+  .step(startStep)
+  .if(async ({ context }) => {
+    const value = context.getStepResult<{ value: number }>('start')?.value;
+    return value < 10;
+  })
+  .then(ifBranchStep)
+  .else() // Alternative branch when the condition is false
+  .then(elseBranchStep)
+  .commit();
+```
+
+## Parameters
+
+The `else()` method does not take any parameters.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining"
+    }
+  ]}
+/>
+
+## Behavior
+
+- The `else()` method must follow an `if()` branch in the workflow definition
+- It creates a branch that executes only when the preceding `if` condition evaluates to false
+- You can chain multiple steps after an `else()` using `.then()`
+- You can nest additional `if`/`else` conditions within an `else` branch
+
+## Error Handling
+
+The `else()` method requires a preceding `if()` statement. If you try to use it without a preceding `if`, an error will be thrown:
+
+```typescript
+try {
+  // This will throw an error
+  workflow
+    .step(someStep)
+    .else()
+    .then(anotherStep)
+    .commit();
+} catch (error) {
+  console.error(error); // "No active condition found"
+}
+```
+
+## Related
+
+- [if Reference](./if.mdx)
+- [then Reference](./then.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+- [Step Condition Reference](./step-condition.mdx)