> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 金鑰。若未提供，則使用 SARVAM\_API\_KEY 環境變數。

**speechModel.model** (`SarvamTTSModel`): 指定文字轉語音所使用的模型。可用選項：bulbul:v2、bulbul:v3、bulbul:v3-beta。bulbul:v3-beta 是 bulbul:v3 的 beta 變體，兩者共用相同的 speaker 目錄。注意：Sarvam 已棄用 bulbul:v1，因此不再支援。

**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'`): 輸出音訊 codec。

**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 金鑰。若未提供，則使用 SARVAM\_API\_KEY 環境變數。

**listeningModel.model** (`SarvamSTTModel`): 指定語音轉文字所使用的模型。可用選項：saarika:v2.5（轉錄）、saaras:v3（多模式：transcribe/translate/verbatim/translit/codemix）。注意：Sarvam 已棄用 saarika:v1、saarika:v2 與 saarika:flash。

**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 金鑰
- 若未提供 API 金鑰，建構函式會擲回錯誤
- 此服務透過 `https://api.sarvam.ai` 與 Sarvam AI API 通訊
- 音訊會以包含二進位音訊資料的串流回傳
- 語音辨識支援 mp3 與 wav 音訊格式
- Sarvam 已棄用 `bulbul:v1`、`saarika:v1`、`saarika:v2` 與 `saarika:flash`，因此不再支援。TTS 請使用 `bulbul:v3`（或 `bulbul:v2`），STT 請使用 `saarika:v2.5`（或 `saaras:v3`）。
- `bulbul:v2` 與 `bulbul:v3` 之間無法互換 speaker 名稱。每個模型版本都有自己的 speaker 目錄。