Google Gemini 라이브 음성

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

사용예

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

= 'gemini-2.0-flash-exp'

실시간 음성 상호작용에 사용할 Model ID입니다.

speaker?:

GeminiVoiceName

= 'Puck'

음성 합성에 사용할 기본 음성 ID입니다.

vertexAI?:

boolean

= false

인증에 Gemini API 대신 Vertex AI를 사용합니다.

project?:

string

Google Cloud 프로젝트 ID입니다(Vertex AI에 필요).

location?:

string

= 'us-central1'

Vertex AI에 사용할 Google Cloud 리전입니다.

serviceAccountKeyFile?:

string

Vertex AI 인증에 사용할 서비스 계정 JSON 키 파일의 경로입니다.

serviceAccountEmail?:

string

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

instructions?:

string

Model에 전달할 시스템 지침입니다.

sessionConfig?:

GeminiSessionConfig

중단 및 컨텍스트 설정을 포함하는 세션 구성입니다.

GeminiSessionConfig

interrupts?:

object

중단 처리 구성입니다.

interrupts.enabled?:

boolean

중단 처리를 활성화합니다.

interrupts.allowUserInterruption?:

boolean

사용자가 Model 응답을 중단할 수 있도록 허용합니다.

contextCompression?:

boolean

자동 컨텍스트 압축을 활성화합니다.

debug?:

boolean

= false

문제 해결을 위한 디버그 로깅을 활성화합니다.

행동 양식

connect()

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

requestContext?:

object

연결에 사용할 선택적 요청 컨텍스트입니다.

returns:

Promise<void>

연결이 설정되면 이행되는 Promise입니다.

speak()

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

input:

string | NodeJS.ReadableStream

음성으로 변환할 텍스트 또는 텍스트 스트림입니다.

options?:

GeminiLiveVoiceOptions

선택적 음성 구성입니다.

GeminiLiveVoiceOptions

speaker?:

GeminiVoiceName

이 특정 음성 요청에 사용할 음성 ID입니다.

languageCode?:

string

응답의 언어 코드입니다.

responseModalities?:

('AUDIO' | 'TEXT')[]

Model에서 수신할 응답 모달리티입니다.

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

sendContext()

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

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

선택적 구성입니다.

object

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:

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

Vertex AI(프로덕션)

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

// 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는 네트워크 중단 처리를 위한 세션 재개를 지원합니다.

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이 함수를 호출하도록 활성화합니다.

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는 텍스트 및 오디오를 통한 실시간 상호작용을 지원합니다.