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

# voice.connect()

`connect()` 方法會建立 WebSocket 或 WebRTC 連線，以進行即時語音對語音通訊。使用 `send()` 或 `answer()` 等其他即時功能前，必須先呼叫此方法。

## 使用範例

```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-5.1-realtime',
    apiKey: process.env.OPENAI_API_KEY,
    options: {
      sessionConfig: {
        turn_detection: {
          type: 'server_vad',
          threshold: 0.6,
          silence_duration_ms: 1200,
        },
      },
    },
  },
  speaker: 'alloy', // Default voice
})
// Connect to the real-time service
await voice.connect()
// Now you can use real-time features
voice.on('speaker', stream => {
  stream.pipe(speaker)
})
// With connection options
await voice.connect({
  timeout: 10000, // 10 seconds timeout
  reconnect: true,
})
```

## 參數

**options** (`Record<string, unknown>`): Provider 特定的連線選項

## 傳回值

傳回 `Promise<void>`；連線成功建立後便會 resolve。

## Provider 特定選項

各即時語音 Provider 的 `connect()` 方法可能支援不同選項：

### OpenAI Realtime

**options** (`Options`): 設定選項。

**options.timeout** (`number`): 連線逾時時間（毫秒）

**options.reconnect** (`boolean`): 連線中斷時是否自動重新連線

## 搭配 `CompositeVoice` 使用

使用 `CompositeVoice` 時，`connect()` 方法會委派給已設定的即時 Provider：

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
const realtimeVoice = new OpenAIRealtimeVoice()
const voice = new CompositeVoice({
  realtime: realtimeVoice,
})
// This will use the OpenAIRealtimeVoice provider
await voice.connect()
```

## 注意事項

- 只有支援語音對語音功能的即時語音 Provider 才會實作此方法
- 若對不支援此功能的語音 Provider 呼叫此方法，系統會記錄警告並立即 resolve
- 使用 `send()` 或 `answer()` 等其他即時方法前，必須先建立連線
- 使用完 Voice 執行個體後，請呼叫 `close()`，以妥善清理資源
- 視實作方式而定，部分 Provider 可能會在連線中斷時自動重新連線
- 連線錯誤通常會以例外形式擲回，應加以捕捉並處理

## 相關方法

- [voice.send()](https://mastra.zisheng.pro/zh-TW/reference/voice/voice.send)：將音訊資料傳送至語音 Provider
- [voice.answer()](https://mastra.zisheng.pro/zh-TW/reference/voice/voice.answer)：觸發語音 Provider 回應
- [voice.close()](https://mastra.zisheng.pro/zh-TW/reference/voice/voice.close)：中斷與即時服務的連線
- [voice.on()](https://mastra.zisheng.pro/zh-TW/reference/voice/voice.on)：為語音事件註冊事件監聽器