본문으로 건너뛰기

AWS 노바 소닉 목소리

그만큼NovaSonicVoice클래스는 실시간 음성 대 음성 기능을 제공합니다.AWS 베드락 노바 2 소닉. Model에 대한 양방향 스트림을 열고 보조 오디오, 기록된 텍스트, Tool 호출, 회전 경계 및 중단에 대한 이벤트를 내보냅니다.

사용예
사용예에 대한 직접 링크

src/mastra/voice.ts
import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize using the default AWS credential provider chain
const voice = new NovaSonicVoice({
  region: 'us-east-1',
  speaker: 'matthew',
})

// Or pass explicit credentials
const voiceWithCredentials = new NovaSonicVoice({
  region: 'us-east-1',
  speaker: 'tiffany',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
})

// Establish the bidirectional stream
await voice.connect()

// Listen for assistant audio (Int16Array PCM)
voice.on('speaking', ({ audioData }) => {
  if (audioData) playAudio(audioData)
})

// Listen for transcribed text from the user and assistant
voice.on('writing', ({ text, role, generationStage }) => {
  console.log(`${role} (${generationStage ?? 'FINAL'}): ${text}`)
})

// Stream microphone audio in real time
const microphoneStream = getMicrophoneStream()
await voice.send(microphoneStream)

// Disconnect when done
voice.close()

입증
입증에 대한 직접 링크

credentials 옵션을 전달하지 않으면 NovaSonicVoice는 AWS SDK 자격 증명 확인 체인을 사용합니다. Mastra는 @aws-sdk/credential-provider-node의 defaultProvider()를 호출하며, 이 함수는 환경 변수, 공유 자격 증명 파일, EC2의 IAM 역할, ECS, EKS 및 기타 표준 소스를 차례로 확인합니다. 정적 자격 증명을 사용하려면 생성자에 전달하세요.

new NovaSonicVoice({
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    sessionToken: process.env.AWS_SESSION_TOKEN,
  },
})

음성 제공자는 자격 증명 값을 기록하지 않습니다.

구성
구성에 대한 직접 링크

생성자 옵션
생성자 옵션에 대한 직접 링크

region?:

'us-east-1' | 'us-west-2' | 'ap-northeast-1'
= 'us-east-1'
Nova Sonic Model을 호스팅하는 AWS 리전입니다.

model?:

string
= 'amazon.nova-2-sonic-v1:0'
양방향 스트림에 사용할 Bedrock Model ID입니다.

credentials?:

AwsCredentialIdentity
정적 AWS 자격 증명입니다. 생략하면 기본 AWS 자격 증명 Provider 체인을 사용합니다.

speaker?:

string | NovaSonicVoiceConfigDetails
= 'matthew'
어시스턴트의 기본 음성입니다. 'matthew'와 같은 음성 ID 문자열이나 언어 코드와 성별을 포함하는 객체를 전달합니다.

languageCode?:

NovaSonicLanguageCode
세션에 사용할 언어 코드입니다. 다국어 음성은 나열된 모든 언어를 지원합니다.

instructions?:

string
세션 시작 시 전송할 시스템 Prompt입니다. connect() 전에 addInstructions()를 호출하는 것과 같습니다.

tools?:

NovaSonicToolConfig[]
Model에 노출할 Tools입니다. 음성 인스턴스가 Agent에 연결되면 Agent의 Tools가 자동으로 추가됩니다.

sessionConfig?:

NovaSonicSessionConfig
추론, 턴 감지 및 Tool 선택 구성입니다. 아래의 세션 구성을 참조하세요.

debug?:

boolean
= false
스트림 이벤트의 상세 로깅을 활성화합니다. 민감한 필드는 마스킹됩니다.

세션 구성
세션 구성에 대한 직접 링크

sessionConfig추론 매개변수와 순서대로 동작을 제어합니다. 모든 필드는 선택 사항입니다.

inferenceConfiguration?:

object
샘플링 및 디코딩 매개변수입니다.
object

maxTokens?:

number
Maximum tokens generated per turn.

temperature?:

number
Sampling temperature.

topP?:

number
Nucleus sampling probability.

topK?:

number
Top-k sampling.

stopSequences?:

string[]
Sequences that end generation.

turnDetectionConfiguration?:

object
턴 감지를 위한 엔드포인팅 민감도입니다.
object

endpointingSensitivity?:

'HIGH' | 'MEDIUM' | 'LOW'
Model이 턴이 완료되었다고 판단하기 전까지의 일시 정지 시간입니다. HIGH는 가장 빠르게 턴을 종료하고(약 1.5초 정지), MEDIUM은 균형 잡힌 설정이며(약 1.75초), LOW는 가장 오래 기다립니다(약 2초).

toolChoice?:

'auto' | 'any' | { tool: { name: string } }
Model이 Tool 호출 여부를 결정하는 방식입니다.

enableKnowledgeGrounding?:

boolean
Bedrock 지식 베이스를 대상으로 검색 증강 그라운딩을 활성화합니다.

knowledgeBaseConfig?:

{ knowledgeBaseId?: string; dataSourceId?: string }
지식 그라운딩이 활성화되었을 때 사용할 지식 베이스입니다.

행동 양식
행동 양식에 대한 직접 링크

connect()
connect에 대한 직접 링크

AWS Bedrock에 대한 양방향 스트림을 열고 초기 세션, Prompt 및 시스템 이벤트를 전송합니다. speak, listen 또는 send를 호출하기 전에 이 메서드를 호출하세요.

options?:

{ requestContext?: RequestContext }
세션 중 이루어지는 Tool 호출에 전파할 선택적 요청 컨텍스트입니다.

보고:Promise<void>

speak()
speak에 대한 직접 링크

텍스트 Prompt의 음성을 합성하고 오디오가 생성되는 동안 speaking 이벤트를 내보냅니다.

input:

string | NodeJS.ReadableStream
합성할 텍스트 또는 텍스트 스트림입니다.

options?:

NovaSonicVoiceOptions
화자 또는 언어 코드와 같은 호출별 재정의 설정입니다.

보고:Promise<void>

send()
send에 대한 직접 링크

마이크 오디오(또는 모든 PCM 소스)를 Model로 스트리밍합니다. 실시간으로 지속적인 대화를 하려면 이 기능을 사용하세요.

audioData:

NodeJS.ReadableStream | Int16Array
Model에 전달할 16비트 PCM 오디오입니다.

보고:Promise<void>

listen()
listen에 대한 직접 링크

send()에 위임하는 편의 래퍼입니다. 유한한 오디오 스트림을 한 번만 전사하려는 경우 사용하세요.

audioData:

NodeJS.ReadableStream
전사할 오디오 스트림입니다.

보고:Promise<void>

endAudioInput()
endaudioinput에 대한 직접 링크

Model이 응답을 마무리할 수 있도록 현재 오디오 턴의 끝을 신호로 보냅니다. 사용자가 말하기를 멈추고 공급자가 서버 측 회전 감지에 대해 구성되지 않은 경우 이 호출을 호출하세요.

보고:Promise<void>

addInstructions()
addinstructions에 대한 직접 링크

활성 세션에 대한 시스템 Prompt를 업데이트합니다.

instructions?:

string
세션에 적용할 시스템 Prompt입니다.

보고:void

addTools()
addtools에 대한 직접 링크

음성 인스턴스에 Tools를 등록합니다. NovaSonicVoice가 Agent에 연결되면 Agent의 Tools가 자동으로 추가됩니다.

tools?:

ToolsInput
Model에 노출할 Tools입니다.

보고:void

getSpeakers()
getspeakers에 대한 직접 링크

Nova 2 Sonic에서 지원하는 음성 목록을 반환합니다.

보고:Promise<Array<{ voiceId: string; name: string; language: string; locale: string; gender: 'masculine' | 'feminine'; polyglot: boolean }>>

getListener()
getlistener에 대한 직접 링크

음성 인스턴스가 현재 공개 스트림을 보유하고 있는지 여부를 반환합니다.

보고:Promise<{ enabled: boolean }>

close()
close에 대한 직접 링크

양방향 스트림을 닫고 기본 Bedrock 클라이언트를 삭제합니다. 대화가 끝나면 이것을 호출하세요.

보고:void

on() / off()
on--off에 대한 직접 링크

이벤트 리스너를 등록하고 제거합니다. 공통 이벤트 API는 Voice 이벤트를 참조하세요.

이벤트
이벤트에 대한 직접 링크

NovaSonicVoice다음 이벤트를 내보냅니다.

speaking:

event
어시스턴트 오디오 청크입니다. 콜백은 { audioData: Int16Array, sampleRate?: number }를 받습니다.

writing:

event
사용자 또는 어시스턴트가 말한 내용을 전사한 텍스트입니다. 콜백은 { text: string, role: 'assistant' | 'user', generationStage?: 'SPECULATIVE' | 'FINAL' }을 받습니다.

toolCall:

event
Model이 Tool 호출을 요청했습니다. 콜백은 { name: string, args: Record<string, any>, id: string }을 받습니다.

interrupt:

event
사용자 또는 Model이 현재 턴을 중단했습니다. 콜백은 { type: 'user' | 'model', timestamp: number }를 받습니다.

turnComplete:

event
Model이 턴을 완료했습니다. 콜백은 { timestamp: number }를 받습니다.

session:

event
세션 상태 전환입니다. 콜백은 { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'error' }를 받습니다.

usage:

event
턴의 토큰 사용량입니다. 콜백은 { inputTokens: number, outputTokens: number, totalTokens: number }를 받습니다.

error:

event
스트림 또는 Provider 오류입니다. 콜백은 { message: string, code?: string, details?: unknown }을 받습니다.

generationStage는 임시 전사문('SPECULATIVE')과 확정된 전사문('FINAL')을 구분합니다. 영구 저장에는 'FINAL' 텍스트를 사용하고 실시간 자막에는 'SPECULATIVE' 텍스트를 사용하세요.

사용 가능한 음성
사용 가능한 음성에 대한 직접 링크

Nova 2 Sonic은 10개 지역에서 음성을 제공합니다. Tiffany와 Matthew는 다중 언어를 구사하며 지원되는 모든 언어를 구사할 수 있습니다.

음성 ID이름언어로케일성별다국어
tiffanyTiffany영어en-US여성예
matthewMatthew영어en-US남성예
amyAmy영어en-GB여성아니요
oliviaOlivia영어en-AU여성아니요
kiaraKiara영어en-IN여성아니요
arjunArjun영어en-IN남성아니요
ambreAmbre프랑스어fr-FR여성아니요
florianFlorian프랑스어fr-FR남성아니요
beatriceBeatrice이탈리아어it-IT여성아니요
lorenzoLorenzo이탈리아어it-IT남성아니요
tinaTina독일어de-DE여성아니요
lennartLennart독일어de-DE남성아니요
lupeLupe스페인어es-US여성아니요
carlosCarlos스페인어es-US남성아니요
carolinaCarolina포르투갈어pt-BR여성아니요
leoLeo포르투갈어pt-BR남성아니요
kiaraKiara힌디어hi-IN여성아니요
arjunArjun힌디어hi-IN남성아니요

참고 사항
참고 사항에 대한 직접 링크

  • 오디오는 16비트 PCM으로 스트리밍됩니다. 어시스턴트 오디오는 speaking 이벤트에서 Int16Array로 내보내집니다.
  • 다른 스트리밍 메서드를 사용하기 전에 음성 인스턴스에서 connect()를 호출해야 합니다.
  • close()는 내부 BedrockRuntimeClient를 제거하여 HTTP/2 세션을 해제합니다.
  • Nova 2 Sonic은 us-east-1, us-west-2, ap-northeast-1에서 사용할 수 있습니다. 다른 리전에서는 생성 중 구성 오류가 발생합니다.
On this page