翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 音声 API を使用して Amazon Chime SDK の音声分析を実行する
下位互換性を保つため、Amazon Chime SDK 音声 API を使用して音声分析を開始および管理することは可能です。ただし、音声分析用のメディアインサイトパイプライン API のみが新機能を提供するため、代わりにこの API を使用することを強くお勧めします。
以下のセクションでは、音声 API とメディアインサイトパイプライン API の違いについて説明します。
## タスクの停止
Voice Connector を使用して音声分析タスクを開始し、[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 Voice Connector を使用して分析タスクを開始します。音声分析準備完了イベントを受信したら、次のプロパティで識別される通話のスピーカー検索または音声トーン分析タスクをトリガーできます。
+ `voiceConnectorId`
+ `transactionId`
**注記**
この通知は、音声分析が有効で、Voice Connector に関連付けられているメディアインサイトパイプライン設定がある場合にのみ提供されます。この通知は、顧客が `CreateMediaInsightsPipeline` API を呼び出し、メディアパイプライン SDK を介してスピーカー検索タスクまたは音声トーン分析タスクを起動した場合には提供されません。
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) API を呼び出すことができるようになります。
音声分析の処理準備が整うと、Voice Connector は `"detailStatus": "AnalyticsReady"` のイベントを JSON 本文として通知ターゲットに送信します。Amazon SNS または Amazon SQS を使用している場合、その本文は Amazon SNS または Amazon SQS ペイロードの「Records」フィールドに表示されます。
次の例は一般的な 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 Voice Connector は、以下のスピーカー検索イベントを送信します。
+ ID の一致
+ 音声埋め込みの生成
イベントには以下のステータスがあります。
+ `IdentificationSuccessful` - 特定の音声プロファイルドメイン内で、高い信頼度スコアで一致する音声プロファイル ID を少なくとも 1 つ正常に識別しました。
+ `IdentificationFailure` - 識別を実行できませんでした。原因: 発信者が 10 秒以上話していないか、音質が良くありません。
+ `IdentificationNoMatchesFound` - 指定された音声プロファイルドメインで、高い確率で一致する音声プロファイルが見つかりませんでした。発信者が新規であるか、声が変わっている可能性があります。
+ `VoiceprintGenerationSuccessful` - システムは、20 秒間の無音ではない音声を使用して音声埋め込みを生成しました。
+ `VoiceprintGenerationFailure` - システムは音声埋め込みを生成できませんでした。原因: 発信者が 20 秒以上話していないか、音質が良くありません。
#### ID の一致
[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` に対して呼び出されると、Voice Connector サービスは、無音でない音声が 10 秒間聞こえた後、ID が一致したことを示す通知を返します。このサービスは、上位 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 秒間続くと、Voice Connector は通知ターゲットに音声埋め込み生成通知を送信します。音声プロファイルに新しい音声埋め込みを登録したり、音声プロファイルに既に登録されている声紋を更新したりできます。
次の例は、一致が見つかった場合の通知を示しています。この場合、関連する音声プロファイルを更新できます。
```
{
"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}}"
}
```