MastraVoice
MastraVoice 类是一个抽象基类，定义了 Mastra 中语音服务的核心接口。所有语音提供商的实现（如 OpenAI、Deepgram、PlayAI、Speechify）都继承此类以提供各自的功能。该类现在包含通过 WebSocket 连接支持实时语音到语音的功能。
🌐 The MastraVoice class is an abstract base class that defines the core interface for voice services in Mastra. All voice provider implementations (like OpenAI, Deepgram, PlayAI, Speechify) extend this class to provide their specific functionality. The class now includes support for real-time speech-to-speech capabilities through WebSocket connections.
使用示例Direct link to 使用示例
🌐 Usage Example
import { MastraVoice } from "@mastra/core/voice";
// Create a voice provider implementation
class MyVoiceProvider extends MastraVoice {
constructor(config: {
speechModel?: BuiltInModelConfig;
listeningModel?: BuiltInModelConfig;
speaker?: string;
realtimeConfig?: {
model?: string;
apiKey?: string;
options?: unknown;
};
}) {
super({
speechModel: config.speechModel,
listeningModel: config.listeningModel,
speaker: config.speaker,
realtimeConfig: config.realtimeConfig,
});
}
// Implement required abstract methods
async speak(
input: string | NodeJS.ReadableStream,
options?: { speaker?: string },
): Promise<NodeJS.ReadableStream | void> {
// Implement text-to-speech conversion
}
async listen(
audioStream: NodeJS.ReadableStream,
options?: unknown,
): Promise<string | NodeJS.ReadableStream | void> {
// Implement speech-to-text conversion
}
async getSpeakers(): Promise<
Array<{ voiceId: string; [key: string]: unknown }>
> {
// Return list of available voices
}
// Optional speech-to-speech methods
async connect(): Promise<void> {
// Establish WebSocket connection for speech-to-speech communication
}
async send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void> {
// Stream audio data in speech-to-speech
}
async answer(): Promise<void> {
// Trigger voice provider to respond
}
addTools(tools: Array<unknown>): void {
// Add tools for the voice provider to use
}
close(): void {
// Close WebSocket connection
}
on(event: string, callback: (data: unknown) => void): void {
// Register event listener
}
off(event: string, callback: (data: unknown) => void): void {
// Remove event listener
}
}
构造函数参数Direct link to 构造函数参数
🌐 Constructor Parameters
config?:
config.speechModel?:
config.listeningModel?:
config.speaker?:
config.name?:
config.realtimeConfig?:
BuiltInModelConfigDirect link to BuiltInModelConfig
name:
apiKey?:
RealtimeConfigDirect link to RealtimeConfig
model?:
apiKey?:
options?:
抽象方法Direct link to 抽象方法
🌐 Abstract Methods
这些方法必须由继承自 MastraVoice 的未知类实现。
🌐 These methods must be implemented by unknown class extending MastraVoice.
speak()Direct link to speak()
使用配置的语音模型将文本转换为语音。
🌐 Converts text to speech using the configured speech model.
abstract speak(
input: string | NodeJS.ReadableStream,
options?: {
speaker?: string;
[key: string]: unknown;
}
): Promise<NodeJS.ReadableStream | void>
目的：
🌐 Purpose:
- 接受文本输入，并使用提供商的文本到语音服务将其转换为语音
- 支持字符串和流输入，灵活性更高
- 允许通过选项覆盖默认扬声器/语音
- 返回可播放或保存的音频数据流
- 如果音频通过触发 'speaking' 事件处理，可能会返回 void
listen()Direct link to listen()
使用配置的监听模型将语音转换为文本。
🌐 Converts speech to text using the configured listening model.
abstract listen(
audioStream: NodeJS.ReadableStream,
options?: {
[key: string]: unknown;
}
): Promise<string | NodeJS.ReadableStream | void>
目的：
🌐 Purpose:
- 获取音频流并使用提供商的语音转文本服务将其转换为文字
- 支持特定提供商的转录配置选项
- 可以返回完整的文字转录或实时转录文本流
- 并非所有提供商都支持此功能（例如，PlayAI、Speechify）
- 如果通过触发 'writing' 事件处理转录，可能返回空值
getSpeakers()Direct link to getSpeakers()
返回提供商支持的可用语音列表。
🌐 Returns a list of available voices supported by the provider.
abstract getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>>
目的：
🌐 Purpose:
- 从提供商处检索可用的语音/说话人列表
- 每个语音必须至少有一个 voiceId 属性
- 提供商可以为每个语音包含额外的元数据
- 用于发现可用于文本转语音转换的语音
可选方法Direct link to 可选方法
🌐 Optional Methods
这些方法有默认实现，但可以被支持语音对语音功能的语音提供商重写。
🌐 These methods have default implementations but can be overridden by voice providers that support speech-to-speech capabilities.
connect()Direct link to connect()
建立用于通信的 WebSocket 或 WebRTC 连接。
🌐 Establishes a WebSocket or WebRTC connection for communication.
connect(config?: unknown): Promise<void>
目的：
🌐 Purpose:
- 初始化与语音服务的连接以进行通信
- 在使用 send() 或 answer() 等功能之前必须调用
- 返回一个在连接建立时解析的 Promise
- 配置因提供商而异
send()Direct link to send()
将音频数据实时传输到语音提供商。
🌐 Streams audio data in real-time to the voice provider.
send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void>
目的：
🌐 Purpose:
- 将音频数据发送到语音提供商进行实时处理
- 适用于连续音频流场景，如实时麦克风输入
- 支持 ReadableStream 和 Int16Array 音频格式
- 在调用此方法之前必须处于连接状态
answer()Direct link to answer()
触发语音提供商生成回应。
🌐 Triggers the voice provider to generate a response.
answer(): Promise<void>
目的：
🌐 Purpose:
- 向语音提供商发送信号以生成响应
- 用于实时对话中提示 AI 进行回应
- 响应将通过事件系统发出（例如，“speaking”事件）
addTools()Direct link to addTools()
为语音提供商配备可在对话中使用的工具。
🌐 Equips the voice provider with tools that can be used during conversations.
addTools(tools: Array<Tool>): void
目的：
🌐 Purpose:
- 添加语音提供商在对话中可以使用的工具
- 工具可以扩展语音提供商的功能
- 实现方式因提供商而异
close()Direct link to close()
断开 WebSocket 或 WebRTC 连接。
🌐 Disconnects from the WebSocket or WebRTC connection.
close(): void
目的：
🌐 Purpose:
- 关闭与语音服务的连接
- 清理资源并停止任何正在进行的实时处理
- 在你完成语音实例后应调用
on()Direct link to on()
为语音事件注册一个事件监听器。
🌐 Registers an event listener for voice events.
on<E extends VoiceEventType>(
event: E,
callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void,
): void
目的：
🌐 Purpose:
- 注册一个回调函数，当指定事件发生时调用
- 标准事件包括“说话”、“写作”和“错误”
- 提供商也可以发出自定义事件
- 事件数据结构取决于事件类型
off()Direct link to off()
移除事件监听器。
🌐 Removes an event listener.
off<E extends VoiceEventType>(
event: E,
callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void,
): void
目的：
🌐 Purpose:
- 移除先前注册的事件监听器
- 用于在事件处理程序不再需要时进行清理
事件系统Direct link to 事件系统
🌐 Event System
MastraVoice 类包括一个用于实时通信的事件系统。标准事件类型包括：
🌐 The MastraVoice class includes an event system for real-time communication. Standard event types include:
speaking:
writing:
error:
受保护的属性Direct link to 受保护的属性
🌐 Protected Properties
listeningModel?:
speechModel?:
speaker?:
realtimeConfig?:
遥测支持Direct link to 遥测支持
🌐 Telemetry Support
MastraVoice 通过 traced 方法内置了遥测支持，该方法在调用过程中包含性能跟踪和错误监控。
🌐 MastraVoice includes built-in telemetry support through the traced method, which wraps method calls with performance tracking and error monitoring.
注意Direct link to 注意
🌐 Notes
- MastraVoice 是一个抽象类，不能直接实例化
- 实现必须为所有抽象方法提供具体实现
- 该类在不同的语音服务提供商之间提供了一致的接口
- 语音到语音功能是可选的，并且取决于提供商
- 事件系统支持异步通信，实现实时交互
- 所有方法调用的遥测都会自动处理