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

# AWS 노바 소닉 목소리

그만큼`NovaSonicVoice`클래스는 실시간 음성 대 음성 기능을 제공합니다.[AWS 베드락 노바 2 소닉](https://docs.aws.amazon.com/nova/latest/userguide/speech.html). Model에 대한 양방향 스트림을 열고 보조 오디오, 기록된 텍스트, Tool 호출, 회전 경계 및 중단에 대한 이벤트를 내보냅니다.

## 사용예

```typescript
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 및 기타 표준 소스를 차례로 확인합니다. 정적 자격 증명을 사용하려면 생성자에 전달하세요.

```typescript
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'`): Nova Sonic Model을 호스팅하는 AWS 리전입니다. (Default: `'us-east-1'`)

**model** (`string`): 양방향 스트림에 사용할 Bedrock Model ID입니다. (Default: `'amazon.nova-2-sonic-v1:0'`)

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

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

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

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

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

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

**debug** (`boolean`): 스트림 이벤트의 상세 로깅을 활성화합니다. 민감한 필드는 마스킹됩니다. (Default: `false`)

### 세션 구성

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

**inferenceConfiguration** (`object`): 샘플링 및 디코딩 매개변수입니다.

**inferenceConfiguration.maxTokens** (`number`): Maximum tokens generated per turn.

**inferenceConfiguration.temperature** (`number`): Sampling temperature.

**inferenceConfiguration.topP** (`number`): Nucleus sampling probability.

**inferenceConfiguration.topK** (`number`): Top-k sampling.

**inferenceConfiguration.stopSequences** (`string[]`): Sequences that end generation.

**turnDetectionConfiguration** (`object`): 턴 감지를 위한 엔드포인팅 민감도입니다.

**turnDetectionConfiguration.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()`

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

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

보고:`Promise<void>`

### `speak()`

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

**input** (`string | NodeJS.ReadableStream`): 합성할 텍스트 또는 텍스트 스트림입니다.

**options** (`NovaSonicVoiceOptions`): 화자 또는 언어 코드와 같은 호출별 재정의 설정입니다.

보고:`Promise<void>`

### `send()`

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

**audioData** (`NodeJS.ReadableStream | Int16Array`): Model에 전달할 16비트 PCM 오디오입니다.

보고:`Promise<void>`

### `listen()`

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

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

보고:`Promise<void>`

### `endAudioInput()`

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

보고:`Promise<void>`

### `addInstructions()`

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

**instructions** (`string`): 세션에 적용할 시스템 Prompt입니다.

보고:`void`

### `addTools()`

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

**tools** (`ToolsInput`): Model에 노출할 Tools입니다.

보고:`void`

### `getSpeakers()`

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

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

### `getListener()`

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

보고:`Promise<{ enabled: boolean }>`

### `close()`

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

보고:`void`

### `on()` / `off()`

이벤트 리스너를 등록하고 제거합니다. 공통 이벤트 API는 [Voice 이벤트](https://mastra.zisheng.pro/ko/reference/voice/voice.events)를 참조하세요.

## 이벤트

`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      | 이름       | 언어    | 로케일   | 성별 | 다국어 |
| ---------- | -------- | ----- | ----- | -- | --- |
| `tiffany`  | Tiffany  | 영어    | en-US | 여성 | 예   |
| `matthew`  | Matthew  | 영어    | en-US | 남성 | 예   |
| `amy`      | Amy      | 영어    | en-GB | 여성 | 아니요 |
| `olivia`   | Olivia   | 영어    | en-AU | 여성 | 아니요 |
| `kiara`    | Kiara    | 영어    | en-IN | 여성 | 아니요 |
| `arjun`    | Arjun    | 영어    | en-IN | 남성 | 아니요 |
| `ambre`    | Ambre    | 프랑스어  | fr-FR | 여성 | 아니요 |
| `florian`  | Florian  | 프랑스어  | fr-FR | 남성 | 아니요 |
| `beatrice` | Beatrice | 이탈리아어 | it-IT | 여성 | 아니요 |
| `lorenzo`  | Lorenzo  | 이탈리아어 | it-IT | 남성 | 아니요 |
| `tina`     | Tina     | 독일어   | de-DE | 여성 | 아니요 |
| `lennart`  | Lennart  | 독일어   | de-DE | 남성 | 아니요 |
| `lupe`     | Lupe     | 스페인어  | es-US | 여성 | 아니요 |
| `carlos`   | Carlos   | 스페인어  | es-US | 남성 | 아니요 |
| `carolina` | Carolina | 포르투갈어 | pt-BR | 여성 | 아니요 |
| `leo`      | Leo      | 포르투갈어 | pt-BR | 남성 | 아니요 |
| `kiara`    | Kiara    | 힌디어   | hi-IN | 여성 | 아니요 |
| `arjun`    | Arjun    | 힌디어   | hi-IN | 남성 | 아니요 |

## 참고 사항

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