기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 음성 API를 사용하여 Amazon Chime SDK용 음성 분석 실행
이전 버전과의 호환성을 위해 Amazon Chime SDK Voice API를 사용하여 음성 분석을 시작하고 관리할 수 있습니다. 그러나 음성 분석을 위한 미디어 인사이트 파이프라인 API만 새로운 기능을 제공하므로 대신 해당 API를 사용하는 것이 좋습니다.
다음 섹션에서는 음성 및 미디어 인사이트 파이프라인 API의 차이점을 설명합니다.
## 작업 중지
음성 커넥터를 사용하여 음성 분석 작업을 시작한 다음 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html) API를 사용하여 파이프라인을 일시 중지하면 작업이 계속 실행됩니다. 작업을 중지하려면 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopSpeakerSearchTask.html) 및 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopVoiceToneAnalysisTask.html) API를 직접 호출해야 합니다.
## 알림의 차이점 이해
음성 API를 사용하여 음성 분석을 실행하는 경우 알림은 미디어 인사이트 파이프라인에서 생성되는 알림과 다릅니다.
+ 음성 분석 준비 이벤트는 음성 API를 사용하여 시작된 작업에만 사용할 수 있습니다.
+ 음성 분석 작업을 통화와 연결하려면 알림의 `voiceConnectorId`, `transactionId`, 또는 `callId` 필드를 사용해야 합니다. 미디어 인사이트 파이프라인을 사용하여 음성 분석을 실행하는 경우 `mediaInsightsPipelineId` `streamArn` 및/또는 `channelId` 필드를 사용하여 작업을 통화와 연결합니다.
다음 주제에서는 음성 API로 알림을 사용하는 방법을 설명합니다.
**Topics**
+ [음성 분석 준비 이벤트](#va-ready-events)
+ [화자 검색 이벤트](#va-speaker-search-events)
+ [음성 톤 분석 이벤트](#va-tone-status)
### 음성 분석 준비 이벤트
음성 분석 준비 이벤트에는 `VoiceAnalyticsStatus` 세부 유형이 있습니다.
Amazon Chime SDK 음성 커넥터를 사용하여 분석 작업을 시작합니다. 음성 분석 준비 이벤트를 수신하면 다음 속성으로 식별되는 통화의 화자 검색 또는 음성 톤 분석 작업을 트리거할 수 있습니다.
+ `voiceConnectorId`
+ `transactionId`
**참고**
이 알림은 음성 분석이 활성화되고 음성 커넥터와 연결된 미디어 인사이트 파이프라인 구성이 있는 경우에만 제공됩니다. 고객이 `CreateMediaInsightsPipeline` API를 호출하고 Media Pipelines SDK를 통해 화자 검색 작업 또는 음성 톤 분석 작업을 시작하는 경우에는 이 알림이 제공되지 않습니다.
음성 커넥터에서 반환되는 SIP 헤더에는 `transactionId`가 포함됩니다. SIP 헤더에 액세스할 수 없는 경우 `AnalyticsReady` 알림 이벤트에는 `voiceConnectorId` 및 `transactionId`도 포함됩니다. 이를 통해 프로그래밍 방식으로 정보를 수신하고 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) 또는 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html) API를 직접 호출할 수 있습니다.
음성 분석을 처리할 준비가 되면 음성 커넥터는 `"detailStatus": "AnalyticsReady"`와 함께 이벤트를 알림 대상에 JSON 본문으로 보냅니다. Amazon SNS 또는 Amazon SQS를 사용하는 경우 해당 본문은 Amazon SNS 또는 Amazon SQS 페이로드의 ‘레코드’ 필드에 표시됩니다.
다음 예에서는 일반적인 JSON 본문을 보여줍니다.
```
{
"detail-type": "VoiceAnalyticsStatus",
"version": "0",
"id": "{{Id-f928dfe3-f44b-4965-8a17-612f9fb92d59}}",
"source": "aws.chime",
"account": "{{123456789012}}",
"time": "{{2022-08-26T17:55:15.563441Z}}",
"region": "us-east-1",
"resources": [],
"detail": {
"detailStatus": "AnalyticsReady",
"callDetails": {
"isCaller": {{false}},
"transactionId": "{{daaeb6bf-2fe2-4e51-984e-d0fbf2f09436}}",
"voiceConnectorId": "{{fuiopl1fsv9caobmqf2vy7}}"
}
}
}
```
이 알림을 통해 음성 분석 작업 API를 호출하기 전에 애플리케이션에 대한 추가 콜백을 트리거하고 통지 및 동의와 같은 법적 요구 사항을 처리할 수 있습니다.
### 화자 검색 이벤트
화자 검색 이벤트에는 `SpeakerSearchStatus` 세부 유형이 있습니다.
Amazon Chime SDK 음성 커넥터는 다음과 같은 화자 검색 이벤트를 전송합니다.
+ 식별 일치
+ 음성 임베딩 생성
이벤트에는 다음과 같은 상태가 있을 수 있습니다:
+ `IdentificationSuccessful` – 주어진 음성 프로필 도메인에서 높은 신뢰도 점수로 일치하는 음성 프로필 ID를 하나 이상 식별하는 데 성공했습니다.
+ `IdentificationFailure` – 식별을 수행하지 못했습니다. 원인: 발신자가 10초 이상 말을 하지 않았으며, 음질이 좋지 않습니다.
+ `IdentificationNoMatchesFound` – 해당 음성 프로필 도메인에서 신뢰도가 높은 일치 항목을 찾을 수 없습니다. 전화를 건 사람이 처음이거나 목소리가 바뀌었을 수 있습니다.
+ `VoiceprintGenerationSuccessful` – 시스템이 20초 분량의 무음이 아닌 오디오를 사용하여 음성 임베딩을 생성했습니다.
+ `VoiceprintGenerationFailure` – 시스템에서 음성 임베딩을 생성하지 못했습니다. 원인: 발신자가 20초 이상 말을 하지 않았으며, 음질이 좋지 않습니다.
#### 식별 일치
특정 `transactionId`로 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) API를 직접 호출한 후 음성 커넥터 서비스는 10초 동안 무음이 아닌 발화가 지속되면 식별 일치 알림을 반환합니다. 이 서비스는 음성 프로필 ID와 [0, 1] 범위의 신뢰도 점수와 함께 상위 10개의 매칭을 반환합니다. 신뢰도 점수가 높을수록 통화 중인 화자가 음성 프로필 ID와 일치할 가능성이 높아집니다. 기계 학습 모델에서 일치하는 항목이 없는 경우 알림의 `detailStatus` 필드에 `IdentificationNoMatchesFound`가 포함됩니다.
다음 예제는 매칭 성공 알림을 보여줍니다.
```
{
"version": "0",
"id": "{{12345678-1234-1234-1234-111122223333}}",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "{{111122223333}}",
"time": "{{yyyy-mm-ddThh:mm:ssZ}}",
"region": "{{us-east-1}}",
"resources": [],
"detail": {
"taskId": "{{uuid}}",
"detailStatus": "{{IdentificationSuccessful}}",
"speakerSearchDetails" : {
"results": [
{
"voiceProfileId": "{{vp-505e0992-82da-49eb-9d4a-4b34772b96b6}}",
"confidenceScore": "{{0.94567856}}",
},
{
"voiceProfileId": "{{vp-fba9cbfa-4b8d-4f10-9e41-9dfdd66545ab}}",
"confidenceScore": "{{0.82783350}}",
},
{
"voiceProfileId": "{{vp-746995fd-16dc-45b9-8965-89569d1cf787}}",
"confidenceScore": "{{0.77136436}}",
}
]
},
"isCaller": false,
"voiceConnectorId": "{{abcdef1ghij2klmno3pqr4}}",
"transactionId": "{{daaeb6bf-2fe2-4e51-984e-d0fbf2f09436}}"
}
}
```
#### 음성 임베딩 생성
추가로 10초 동안 무음이 아닌 발화가 지속되면 음성 커넥터는 알림 대상에 음성 임베딩 생성 알림을 보냅니다. 음성 프로필에 새 음성 임베딩을 등록하거나 이미 음성 프로필에 있는 성문을 업데이트할 수 있습니다.
다음 예제는 매칭에 성공하면 관련 음성 프로필을 업데이트할 수 있다는 의미의 알림을 보여줍니다.
```
{
"version": "0",
"id": "{{12345678-1234-1234-1234-111122223333}}",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "{{111122223333}}",
"time": "{{yyyy-mm-ddThh:mm:ssZ}}",
"region": "{{us-east-1}}",
"resources": [],
"detail": {
"taskId": "{{guid}}",
"detailStatus": "{{VoiceprintGenerationSuccess}}",
"isCaller": {{false}},
"transactionId": "{{12345678-1234-1234}}",
"voiceConnectorId": "{{abcdef1ghij2klmno3pqr}}"
}
}
```
### 음성 톤 분석 이벤트
음성 톤 분석 이벤트에는 `VoiceToneAnalysisStatus` 세부 유형이 있습니다. 분석 결과 다음과 같은 상태가 반환될 수 있습니다.
+ `VoiceToneAnalysisSuccessful` – 발신자와 상담원의 음성을 긍정, 부정, 중립 등 감정의 확률로 분석하는 데 성공했습니다.
+ `VoiceToneAnalysisFailure` – 톤 분석을 수행하지 못했습니다. 발신자가 10초 동안 말을 하지 않고 전화를 끊거나 오디오 품질이 너무 나빠지면 이런 일이 발생할 수 있습니다.
+ `VoiceToneAnalysisCompleted` – 사용자와 상담원의 음성을 전체 통화에 대한 감정 확률로 분석하는 데 성공했습니다. 음성 톤 분석이 완료될 때 전송되는 마지막 이벤트입니다.
다음 예제에서는 일반적인 음성 톤 분석 이벤트를 보여줍니다.
```
{
"detail-type": "VoiceToneAnalysisStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "{{216539279014}}",
"time": "{{2022-08-26T17:55:15.563441Z}}",
"region": "{{us-east-1}}",
"detail": {
"taskId": "{{uuid}}",
"detailStatus": "{{VoiceToneAnalysisSuccessful}}",
"voiceToneAnalysisDetails": {
"currentAverageVoiceTone": {
"startTime": "{{2022-08-26T17:55:15.563Z}}",
"endTime": "{{2022-08-26T17:55:45.720Z}}",
"voiceToneLabel": "{{neutral}}",
"voiceToneScore": {
"neutral": "{{0.83}}",
"positive": "{{0.13}}",
"negative": "{{0.04}}"
}
},
"overallAverageVoiceTone": {
"startTime": "{{2022-08-26T16:23:13.344Z}}",
"endTime": "{{2022-08-26T17:55:45.720Z}}",
"voiceToneLabel": "{{positive}}",
"voiceToneScore": {
"neutral": "{{0.25}}",
"positive": "{{0.65}}",
"negative": "{{0.1}}"
}
}
},
"isCaller": true,
"transactionId": "{{daaeb6bf-2fe2-4e51-984e-d0fbf2f09436}}",
"voiceConnectorId": "{{fuiopl1fsv9caobmqf2vy7}}"
},
"version": "0",
"id": "{{Id-f928dfe3-f44b-4965-8a17-612f9fb92d59}}"
}
```