> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Sarvam

Mastra 中的 SarvamVoice 类通过 Sarvam AI 模型提供文本转语音和语音转文本功能。

## 使用示例

```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:v3',
    apiKey: process.env.SARVAM_API_KEY!,
    language: 'en-IN',
    properties: {
      pace: 1.0,
      temperature: 0.6,
      speech_sample_rate: 24000,
      output_audio_codec: 'wav',
    },
  },
  listeningModel: {
    model: 'saarika:v2.5',
    apiKey: process.env.SARVAM_API_KEY!,
    languageCode: 'en-IN',
    filetype: 'wav',
  },
  speaker: 'shubh', // Default voice for bulbul:v3
})

// 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 文档 -

<https://docs.sarvam.ai/api-reference-docs/text-to-speech/convert>

## 配置

### 构造函数选项

**speechModel** (`SarvamVoiceConfig`): 文本转语音合成的配置。 (Default: `{ model: 'bulbul:v3', language: 'en-IN' }`)

**speechModel.apiKey** (`string`): Sarvam API key。未设置时使用 SARVAM\_API\_KEY 环境变量。

**speechModel.model** (`SarvamTTSModel`): 指定用于文本转语音的模型。可用选项：bulbul:v2、bulbul:v3、bulbul:v3-beta。bulbul:v3-beta 是 bulbul:v3 的 beta 变体，两者共享同一个 speaker 目录。注意：bulbul:v1 已被 Sarvam 弃用，不再受支持。

**speechModel.language** (`SarvamTTSLanguage`): 语音合成的目标语言。可用选项：hi-IN、bn-IN、kn-IN、ml-IN、mr-IN、od-IN、pa-IN、ta-IN、te-IN、en-IN、gu-IN

**speechModel.properties** (`object`): 用于自定义的其他音色属性。

**speechModel.properties.pace** (`number`): 控制音频速度。bulbul:v2（范围为 0.3–3.0）和 bulbul:v3（范围为 0.5–2.0）均支持此属性。

**speechModel.properties.temperature** (`number`): 控制所生成音色随机性的采样温度。仅限 bulbul:v3。范围：0.01–2.0。默认值：0.6。

**speechModel.properties.dict\_id** (`string`): 发音词典 ID。仅限 bulbul:v3。

**speechModel.properties.pitch** (`number`): 控制音频音高。值越低，声音越低沉；值越高，声音越尖锐。仅限 bulbul:v2。范围：-0.75 到 0.75。

**speechModel.properties.loudness** (`number`): 控制音频响度。仅限 bulbul:v2。范围：0.3 到 3.0。

**speechModel.properties.enable\_preprocessing** (`boolean`): 启用英语单词和数值实体（数字、日期等）的规范化。仅限 bulbul:v2。默认值为 false。

**speechModel.properties.speech\_sample\_rate** (`8000 | 16000 | 22050 | 24000 | 32000 | 44100 | 48000`): 音频采样率（Hz）。

**speechModel.properties.output\_audio\_codec** (`'mp3' | 'wav' | 'linear16' | 'mulaw' | 'alaw' | 'opus' | 'flac' | 'aac'`): 输出音频编解码器。

**speaker** (`SarvamVoiceId`): 用于输出音频的 speaker。默认为 'shubh'。bulbul:v3 支持 39 种音色（shubh、aditya、ritu、priya、neha、rahul、pooja、rohan、simran、kavya、amit、dev、ishita、shreya、ratan、varun、manan、sumit、roopa、kabir、aayan、ashutosh、advait、amelia、sophia、anand、tanya、tarun、sunny、mani、gokul、vijay、shruti、suhani、mohit、kavitha、rehan、soham、rupali）。bulbul:v2 支持 7 种音色（anushka、manisha、vidya、arya、abhilash、karun、hitesh）。不同模型版本之间的 speaker 不可互换。 (Default: `'shubh'`)

**listeningModel** (`SarvamListenOptions`): 语音转文本识别的配置。 (Default: `{ model: 'saarika:v2.5', languageCode: 'unknown' }`)

**listeningModel.apiKey** (`string`): Sarvam API key。未设置时使用 SARVAM\_API\_KEY 环境变量。

**listeningModel.model** (`SarvamSTTModel`): 指定用于语音转文本的模型。可用选项：saarika:v2.5（转录）、saaras:v3（多模式：transcribe/translate/verbatim/translit/codemix）。注意：saarika:v1、saarika:v2 和 saarika:flash 已被 Sarvam 弃用。

**listeningModel.languageCode** (`SarvamSTTLanguage`): 输入音频的 BCP-47 语言代码。对于 saarika:v2.5 和 saaras:v3，此项可选（传入 'unknown' 时，API 会自动检测语言）。可用选项：unknown、hi-IN、bn-IN、kn-IN、ml-IN、mr-IN、od-IN、pa-IN、ta-IN、te-IN、en-IN、gu-IN。

**listeningModel.filetype** (`'mp3' | 'wav'`): 输入流的音频格式。

**listeningModel.mode** (`SarvamSTTMode`): 操作模式。仅在使用 saaras:v3 模型时有效；saarika:v2.5 会忽略此项。可用选项：'transcribe'、'translate'、'verbatim'、'translit'、'codemix'。

## 方法

### `speak()`

使用 Sarvam 的文本转语音模型将文本转换为语音。

**input** (`string | NodeJS.ReadableStream`): 要转换为语音的文本或文本流。

**options** (`Options`): 配置选项。

**options.speaker** (`SarvamVoiceId`): 用于语音合成的音色 ID。

返回：`Promise<NodeJS.ReadableStream>`

### `listen()`

使用 Sarvam 的语音识别模型转录音频。

**input** (`NodeJS.ReadableStream`): 要转录的音频流。

**options** (`SarvamListenOptions`): 语音识别的配置选项。

返回：`Promise<string>`

### `getSpeakers()`

返回可用音色选项的数组。

返回：`Promise<Array<{voiceId: SarvamVoiceId}>>`

## 注意事项

- 可以通过构造函数选项或 `SARVAM_API_KEY` 环境变量提供 API key
- 如果未提供 API key，构造函数会抛出错误
- 该服务通过 `https://api.sarvam.ai` 与 Sarvam AI API 通信
- 音频以包含二进制音频数据的流形式返回
- 语音识别支持 mp3 和 wav 音频格式
- `bulbul:v1`、`saarika:v1`、`saarika:v2` 和 `saarika:flash` 已被 Sarvam 弃用，不再受支持。TTS 请使用 `bulbul:v3`（或 `bulbul:v2`），STT 请使用 `saarika:v2.5`（或 `saaras:v3`）。
- `bulbul:v2` 和 `bulbul:v3` 之间的 speaker 名称不可互换。每个模型版本都有自己的 speaker 目录。