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

# Google Gemini 라이브 음성

GeminiLiveVoice 클래스는 Google의 Gemini Live API를 사용하여 실시간 음성 상호작용 기능을 제공합니다. 양방향 오디오 스트리밍, Tool 호출, 세션 관리, 표준 Google API 및 Vertex AI 인증 방법을 모두 지원합니다.

## 사용예

```typescript
import { GeminiLiveVoice } from '@mastra/voice-google-gemini-live'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize with Gemini API (using API key)
const voice = new GeminiLiveVoice({
  apiKey: process.env.GOOGLE_API_KEY, // Required for Gemini API
  model: 'gemini-2.0-flash-exp',
  speaker: 'Puck', // Default voice
  debug: true,
})

// Or initialize with Vertex AI (using OAuth)
const voiceWithVertexAI = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
  serviceAccountKeyFile: '/path/to/service-account.json',
  model: 'gemini-2.0-flash-exp',
  speaker: 'Puck',
})

// Or use the VoiceConfig pattern (recommended for consistency with other providers)
const voiceWithConfig = new GeminiLiveVoice({
  speechModel: {
    name: 'gemini-2.0-flash-exp',
    apiKey: process.env.GOOGLE_API_KEY,
  },
  speaker: 'Puck',
  realtimeConfig: {
    model: 'gemini-2.0-flash-exp',
    apiKey: process.env.GOOGLE_API_KEY,
    options: {
      debug: true,
      sessionConfig: {
        interrupts: { enabled: true },
      },
    },
  },
})

// Establish connection (required before using other methods)
await voice.connect()

// Set up event listeners
voice.on('speaker', audioStream => {
  // Handle audio stream (NodeJS.ReadableStream)
  playAudio(audioStream)
})

voice.on('writing', ({ text, role }) => {
  // Handle transcribed text
  console.log(`${role}: ${text}`)
})

voice.on('turnComplete', ({ timestamp }) => {
  // Handle turn completion
  console.log('Turn completed at:', timestamp)
})

// Convert text to speech
await voice.speak('Hello, how can I help you today?', {
  speaker: 'Charon', // Override default voice
  responseModalities: ['AUDIO', 'TEXT'],
})

// Process audio input
const microphoneStream = getMicrophoneStream()
await voice.send(microphoneStream)

// Update session configuration
await voice.updateSessionConfig({
  speaker: 'Kore',
  instructions: 'Be more concise in your responses',
})

// When done, disconnect
await voice.disconnect()
// Or use the synchronous wrapper
voice.close()
```

## 구성

### 생성자 옵션

**apiKey** (`string`): Gemini API 인증에 사용할 Google API 키입니다. Vertex AI를 사용하지 않는 경우 필수입니다.

**model** (`GeminiVoiceModel`): 실시간 음성 상호작용에 사용할 Model ID입니다. (Default: `'gemini-2.0-flash-exp'`)

**speaker** (`GeminiVoiceName`): 음성 합성에 사용할 기본 음성 ID입니다. (Default: `'Puck'`)

**vertexAI** (`boolean`): 인증에 Gemini API 대신 Vertex AI를 사용합니다. (Default: `false`)

**project** (`string`): Google Cloud 프로젝트 ID입니다(Vertex AI에 필요).

**location** (`string`): Vertex AI에 사용할 Google Cloud 리전입니다. (Default: `'us-central1'`)

**serviceAccountKeyFile** (`string`): Vertex AI 인증에 사용할 서비스 계정 JSON 키 파일의 경로입니다.

**serviceAccountEmail** (`string`): 가장에 사용할 서비스 계정 이메일입니다(키 파일의 대안).

**instructions** (`string`): Model에 전달할 시스템 지침입니다.

**sessionConfig** (`GeminiSessionConfig`): 중단 및 컨텍스트 설정을 포함하는 세션 구성입니다.

**sessionConfig.interrupts** (`object`): 중단 처리 구성입니다.

**sessionConfig.interrupts.enabled** (`boolean`): 중단 처리를 활성화합니다.

**sessionConfig.interrupts.allowUserInterruption** (`boolean`): 사용자가 Model 응답을 중단할 수 있도록 허용합니다.

**sessionConfig.contextCompression** (`boolean`): 자동 컨텍스트 압축을 활성화합니다.

**debug** (`boolean`): 문제 해결을 위한 디버그 로깅을 활성화합니다. (Default: `false`)

## 행동 양식

### `connect()`

Gemini Live API에 대한 연결을 설정합니다. 말하기, 듣기 또는 보내기 메소드를 사용하기 전에 호출해야 합니다.

**requestContext** (`object`): 연결에 사용할 선택적 요청 컨텍스트입니다.

**returns** (`Promise<void>`): 연결이 설정되면 이행되는 Promise입니다.

### `speak()`

텍스트를 음성으로 변환하여 Model로 보냅니다. 문자열이나 읽기 가능한 스트림을 입력으로 받아들일 수 있습니다.

**input** (`string | NodeJS.ReadableStream`): 음성으로 변환할 텍스트 또는 텍스트 스트림입니다.

**options** (`GeminiLiveVoiceOptions`): 선택적 음성 구성입니다.

**options.speaker** (`GeminiVoiceName`): 이 특정 음성 요청에 사용할 음성 ID입니다.

**options.languageCode** (`string`): 응답의 언어 코드입니다.

**options.responseModalities** (`('AUDIO' | 'TEXT')[]`): Model에서 수신할 응답 모달리티입니다.

반환값: `Promise<void>`(응답은 `speaker` 및 `writing` 이벤트를 통해 내보내짐)

### `sendContext()`

Model 응답을 트리거하지 않고 대화 기록을 라이브 세션으로 보냅니다. 이를 사용하여 콜드 연결에서 이전 차례(예: Mastra Memory에서)를 시드하여 사용자가 말하기 전에 Model에 컨텍스트를 제공합니다.

```typescript
await voice.sendContext([
  { role: 'user', content: 'What is the weather?' },
  { role: 'assistant', content: 'It is 72°F in San Francisco.' },
])

// Model stays silent until the user actually speaks.
await voice.send(micStream)
```

**turns** (`IncrementalTurn[]`): 세션에 초기 데이터로 제공할 이전 대화 턴입니다. 각 턴에는 role("user" 또는 "assistant")과 content 문자열이 있습니다. 최신 Model(예: gemini-2.5-flash-native-audio-preview-12-2025)은 두 역할을 모두 지원합니다. 일부 이전 Model은 사용자 역할의 턴만 허용합니다.

**options** (`object`): 선택적 구성입니다.

**options.turnComplete** (`boolean`): 턴을 완료로 표시하고 Model 응답을 트리거할지 여부입니다.

보고:`Promise<void>`

### `listen()`

음성 인식을 위해 오디오 입력을 처리합니다. 읽을 수 있는 오디오 데이터 스트림을 가져와서 텍스트로 변환된 텍스트를 반환합니다.

**audioStream** (`NodeJS.ReadableStream`): 전사할 오디오 스트림입니다.

**options** (`GeminiLiveVoiceOptions`): 선택적 수신 구성입니다.

반환값: `Promise<string>` - 전사된 텍스트

### `send()`

라이브 마이크 입력과 같은 지속적인 오디오 스트리밍 시나리오를 위해 오디오 데이터를 실시간으로 Gemini 서비스로 스트리밍합니다.

**audioData** (`NodeJS.ReadableStream | Int16Array`): 서비스로 전송할 오디오 스트림 또는 버퍼입니다.

보고:`Promise<void>`

### `updateSessionConfig()`

런타임 시 세션 구성을 업데이트합니다. 음성 설정 및 스피커 선택을 수정할 수 있습니다. 또한 다른 런타임 구성을 수정할 수도 있습니다.

**config** (`Partial<GeminiLiveVoiceConfig>`): 적용할 구성 업데이트입니다.

보고:`Promise<void>`

### `addTools()`

음성 인스턴스에 Tool 세트를 추가합니다. Tool을 사용하면 Model이 대화 중에 추가 작업을 수행할 수 있습니다. GeminiLiveVoice가 Agent에 추가되면 Agent에 대해 구성된 모든 Tool을 자동으로 음성 인터페이스에서 사용할 수 있습니다.

**tools** (`ToolsInput`): 사용하도록 장착할 Tool 구성입니다.

보고:`void`

### `addInstructions()`

Model에 대한 시스템 지침을 추가하거나 업데이트합니다.

**instructions** (`string`): 설정할 시스템 지침입니다.

보고:`void`

### `answer()`

Model의 응답을 트리거합니다. 이 방법은 Agent와 통합될 때 주로 내부적으로 사용됩니다.

**options** (`Record<string, unknown>`): 응답 요청을 위한 선택적 매개변수입니다.

보고:`Promise<void>`

### `getSpeakers()`

Gemini Live API에 사용 가능한 음성 스피커 목록을 반환합니다.

보고:`Promise<Array<{ voiceId: string; description?: string }>>`

### `disconnect()`

Gemini Live 세션 연결을 끊고 리소스를 정리합니다. 이는 정리를 올바르게 처리하는 비동기 방법입니다.

보고:`Promise<void>`

### `close()`

Disconnect()에 대한 동기 래퍼입니다. 기다리지 않고 내부적으로 연결 해제()를 호출합니다.

보고:`void`

### `on()`

음성 이벤트에 대한 이벤트 리스너를 등록합니다.

**event** (`string`): 수신할 이벤트의 이름입니다.

**callback** (`Function`): 이벤트가 발생할 때 호출할 함수입니다.

보고:`void`

### `off()`

이전에 등록된 이벤트 리스너를 제거합니다.

**event** (`string`): 수신을 중지할 이벤트의 이름입니다.

**callback** (`Function`): 제거할 특정 콜백 함수입니다.

보고:`void`

## 이벤트

GeminiLiveVoice 클래스는 다음 이벤트를 내보냅니다.

**speaker** (`event`): Model에서 오디오 데이터를 수신하면 발생합니다. 콜백은 NodeJS.ReadableStream을 받습니다.

**speaking** (`event`): 오디오 메타데이터와 함께 발생합니다. 콜백은 { audioData?: Int16Array, sampleRate?: number }를 받습니다.

**writing** (`event`): 전사된 텍스트를 사용할 수 있을 때 발생합니다. 콜백은 { text: string, role: 'assistant' | 'user' }를 받습니다. 네이티브 오디오 Model에서 어시스턴트 전사는 modelTurn.parts.text가 아니라 서버의 output\_audio\_transcription 채널을 통해 제공됩니다.

**thinking** (`event`): 네이티브 오디오 Model에서 modelTurn.parts.text의 Model 사고 과정/추론 텍스트와 함께 발생합니다. 콜백은 { text: string }을 받습니다. 네이티브 오디오가 아닌 Model에서는 발생하지 않습니다. 이 경우 modelTurn.parts.text는 음성 응답이며 대신 writing으로 발생합니다.

**session** (`event`): 세션 상태가 변경될 때 발생합니다. 콜백은 { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'updated', config?: object }를 받습니다.

**turnComplete** (`event`): 대화 턴이 완료되면 발생합니다. 콜백은 { timestamp: number }를 받습니다.

**toolCall** (`event`): Model이 Tool 호출을 요청하면 발생합니다. 콜백은 { name: string, args: object, id: string }을 받습니다.

**usage** (`event`): 토큰 사용량 정보와 함께 발생합니다. 콜백은 { inputTokens: number, outputTokens: number, totalTokens: number, modality: string }을 받습니다.

**error** (`event`): 오류가 발생하면 발생합니다. 콜백은 { message: string, code?: string, details?: unknown }을 받습니다.

**interrupt** (`event`): 진행 중인 Model 응답 도중에 사용자가 말하기 시작하여 끼어들면 발생합니다. 서버는 현재 턴의 이후 오디오를 모두 취소합니다. 콜백은 { type: 'user', timestamp: number }를 받습니다.

## 네이티브 오디오 동작

네이티브 오디오 Gemini Live Model(ID에 `native-audio`가 포함된 모든 Model, 예: `gemini-2.5-flash-native-audio-preview-12-2025`)은 텍스트 출력을 두 채널로 나눕니다.

- Model의 음성 응답은 오디오와 함께 `output_audio_transcription` 전사로 전달되며 `role: 'assistant'`가 지정된 `writing`으로 노출됩니다.
- Model의 내부 추론은 `modelTurn.parts.text`로 전달되며 `thinking`으로 노출됩니다. 네이티브 오디오가 아닌 Model에는 `output_audio_transcription` 채널이 없으므로 `modelTurn.parts.text` 자체가 음성 응답이며 `writing`으로 발생합니다. `thinking` 이벤트는 발생하지 않습니다. 입력 전사, 출력 전사, 끼어들기 감지(`realtime_input_config.activity_handling = 'START_OF_ACTIVITY_INTERRUPTS'`)는 설정 페이로드에서 자동으로 활성화됩니다. 추가 구성이 필요하지 않습니다.

## 사용 가능한 Model

다음 Gemini Live Model을 사용할 수 있습니다:

- `gemini-2.0-flash-exp`(기본)
- `gemini-2.0-flash-exp-image-generation`
- `gemini-2.0-flash-live-001`
- `gemini-live-2.5-flash-preview-native-audio`
- `gemini-2.5-flash-exp-native-audio-thinking-dialog`
- `gemini-live-2.5-flash-preview`
- `gemini-2.6.flash-preview-tts`

## 사용 가능한 음성

다음과 같은 음성 옵션을 사용할 수 있습니다.

- `Puck`(기본값): 대화, 친근함
- `Charon`: 깊고 권위적
- `Kore`: 중립적, 전문적
- `Fenrir`: 따뜻하고 다가가기 쉬운

## 인증 방법

### Gemini API (개발)

API 키를 사용하는 가장 간단한 방법[Google AI Studio](https://makersuite.google.com/app/apikey):

```typescript
const voice = new GeminiLiveVoice({
  apiKey: 'your-api-key', // Required for Gemini API
  model: 'gemini-2.0-flash-exp',
})
```

### Vertex AI(프로덕션)

OAuth 인증 및 Google Cloud Platform을 사용한 프로덕션용:

```typescript
// Using service account key file
const voice = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
  serviceAccountKeyFile: '/path/to/service-account.json',
})

// Using Application Default Credentials
const voice = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
})

// Using service account impersonation
const voice = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
  serviceAccountEmail: 'service-account@project.iam.gserviceaccount.com',
})
```

## 고급 기능

### 세션 관리

Gemini Live API는 네트워크 중단 처리를 위한 세션 재개를 지원합니다.

```typescript
voice.on('sessionHandle', ({ handle, expiresAt }) => {
  // Store session handle for resumption
  saveSessionHandle(handle, expiresAt)
})

// Resume a previous session
const voice = new GeminiLiveVoice({
  sessionConfig: {
    enableResumption: true,
    maxDuration: '2h',
  },
})
```

### Tool 호출

대화 중에 Model이 함수를 호출하도록 활성화합니다.

```typescript
import { z } from 'zod'

voice.addTools({
  weather: {
    description: 'Get weather information',
    parameters: z.object({
      location: z.string(),
    }),
    execute: async ({ location }) => {
      const weather = await getWeather(location)
      return weather
    },
  },
})

voice.on('toolCall', ({ name, args, id }) => {
  console.log(`Tool called: ${name} with args:`, args)
})
```

## 메모

- Gemini Live API는 실시간 통신에 WebSocket을 사용합니다.
- 오디오는 입력의 경우 16kHz PCM16, 출력의 경우 24kHz PCM16으로 처리됩니다.
- 다른 메서드를 사용하기 전에 음성 인스턴스를 `connect()`로 연결해야 합니다.
- 완료 후에는 항상 `close()`를 호출하여 리소스를 올바르게 정리하세요.
- Vertex AI 인증에는 적절한 IAM 권한(`aiplatform.user` 역할)이 필요합니다.
- 세션 재개를 통해 네트워크 중단에서 복구할 수 있습니다.
- API는 텍스트 및 오디오를 통한 실시간 상호작용을 지원합니다.