本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用语音 API 为 Amazon Chime SDK 运行语音分析
为了向后兼容，您可以使用 Amazon Chime SDK 语音 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 并通过媒体管道 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。
当语音分析准备好进行处理时，语音连接器会以 JSON 正文的形式向通知目标发送包含 `"detailStatus": "AnalyticsReady"` 的事件。如果您使用 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 秒钟的非静默话音后返回识别匹配通知。该服务会返回前 10 个匹配项，以及语音配置文件 ID 和范围为 [0, 1] 的置信度分数。置信度分数越高，呼叫中的发言人与语音配置文件 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}}"
}
```