本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用語音 APIs執行 Amazon Chime SDK 的語音分析
為了回溯相容性，您可以使用 Amazon Chime SDK Voice APIs來啟動和管理語音分析。不過，只有用於語音分析的媒體洞察管道 APIs 提供新功能，因此我們強烈建議改用它們。
下列各節說明語音和媒體洞察管道 APIs 之間的差異。
## 停止任務
如果您使用語音連接器啟動語音分析任務，然後使用 [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) APIs。
## 了解通知差異
當您使用語音 APIs 執行語音分析時，通知會與媒體洞察管道產生的通知不同。
+ 語音分析就緒事件僅適用於開始使用語音 APIs的任務。
+ 您需要使用通知中的 `voiceConnectorId`、 `transactionId`或 `callId` 欄位，將語音分析任務與通話建立關聯。如果您使用媒體洞察管道來執行語音分析，您可以使用 `mediaInsightsPipelineId`和 `streamArn`或 `channelId` 欄位將任務與通話建立關聯。
下列主題說明如何搭配語音 APIs使用通知。
**Topics**
+ [語音分析就緒事件](#va-ready-events)
+ [發言者搜尋事件](#va-speaker-search-events)
+ [語音音調分析事件](#va-tone-status)
### 語音分析就緒事件
語音分析就緒事件具有`VoiceAnalyticsStatus`詳細資訊類型。
您可以使用 Amazon Chime SDK Voice Connectors 來啟動分析任務。當您收到語音分析就緒事件時，您可以觸發通話的發言者搜尋或語音音分析任務，由下列屬性識別：
+ `voiceConnectorId`
+ `transactionId`
**注意**
只有在您的媒體洞察管道組態已啟用語音分析並與語音連接器相關聯時，才會提供此通知。當客戶透過媒體管道 SDK 呼叫 `CreateMediaInsightsPipeline` API 並啟動發言者搜尋任務或音調分析任務時，不會提供此通知。
Voice Connector 傳回的 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) APIs。
當語音分析準備好進行處理時，語音連接器會將事件`"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}}"
}
}
}
```
此通知可讓您在呼叫語音分析任務 APIs 之前，觸發應用程式的其他回呼，並處理任何法律要求，例如通知和同意。
### 發言者搜尋事件
發言者搜尋事件具有`SpeakerSearchStatus`詳細資訊類型。
Amazon Chime SDK Voice Connectors 會傳送下列發言者搜尋事件：
+ 識別相符項目
+ 語音內嵌產生
事件可以有下列狀態：
+ `IdentificationSuccessful` – 成功識別至少一個在指定語音設定檔網域中具有高可信度分數的相符語音設定檔 ID。
+ `IdentificationFailure` – 無法執行識別。原因：來電者至少 10 秒沒有說話，音訊品質不佳。
+ `IdentificationNoMatchesFound` – 在指定的語音設定檔網域中找不到高可信度配對。發起人可能是新的，或其語音可能已變更。
+ `VoiceprintGenerationSuccessful` – 系統使用 20 秒的非靜音音訊產生語音內嵌。
+ `VoiceprintGenerationFailure` – 系統無法產生語音內嵌。原因：來電者至少 20 秒沒有說話，音訊品質不佳。
#### 識別相符項目
為指定的 呼叫 [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 之後`transactionId`，語音連接器服務會在 10 秒的非無提示語音後傳回識別比對通知。服務會傳回前 10 個相符項目，以及 【0， 1】 範圍內的語音設定檔 ID 和可信度分數。可信度分數越高，通話的發言者越有可能符合語音設定檔 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}}"
}
```