Utilisation d'API vocales pour exécuter des analyses vocales

Pour des raisons de rétrocompatibilité, vous pouvez utiliser les API vocales du SDK Amazon Chime pour démarrer et gérer les analyses vocales. Cependant, seules les API Media Insights Pipeline pour l'analyse vocale proposent de nouvelles fonctionnalités. Nous vous recommandons donc vivement de les utiliser à la place.

Les sections suivantes expliquent les différences entre les API des pipelines d'informations vocales et multimédias.

Arrêter des tâches

Si vous utilisez un connecteur vocal pour démarrer des tâches d'analyse vocale, puis que vous utilisez l'UpdateMediaInsightsPipelineStatusAPI pour suspendre le pipeline, les tâches continuent de s'exécuter. Pour arrêter les tâches, vous devez appeler les StopVoiceToneAnalysisTaskAPI StopSpeakerSearchTaskand.

Comprendre les différences entre les notifications

Lorsque vous utilisez des API vocales pour exécuter des analyses vocales, les notifications sont différentes de celles générées par les pipelines d'informations sur les médias.

• Les événements prêts pour l'analyse vocale ne sont disponibles que pour les tâches démarrées à l'aide d'API vocales.

• Vous devez utiliser les callId champs voiceConnectorIdtransactionId, ou de vos notifications pour associer une tâche d'analyse vocale à un appel. Si vous utilisez des pipelines Media Insights pour exécuter des analyses vocales, vous utilisez les channelId champs mediaInsightsPipelineId et streamArn ou pour associer une tâche à un appel.

Les rubriques suivantes expliquent comment utiliser les notifications avec les API vocales.

Événements prêts pour l'analyse vocale

Les événements prêts pour l'analyse vocale sont de type VoiceAnalyticsStatus détaillé.

Vous utilisez les connecteurs vocaux du SDK Amazon Chime pour démarrer des tâches d'analyse. Lorsque vous recevez un événement prêt pour l'analyse vocale, vous pouvez déclencher une tâche de recherche de locuteur ou d'analyse de tonalité vocale pour l'appel, identifiée par les propriétés suivantes :

• voiceConnectorId

• transactionId

Note

Cette notification est fournie uniquement lorsque vous disposez d'une configuration de pipeline d'informations multimédia avec l'analyse vocale activée et associée à un connecteur vocal. Cette notification n'est PAS fournie lorsque les clients appellent l'CreateMediaInsightsPipelineAPI et lancent une tâche de recherche de locuteurs ou une tâche d'analyse de tonalité vocale via le SDK Media Pipelines.

Les en-têtes SIP renvoyés par un connecteur vocal contiennent letransactionId. Si vous n'avez pas accès aux en-têtes SIP, l'événement de AnalyticsReady notification contient également le voiceConnectorId ettransactionId. Cela vous permet de recevoir les informations par programmation et d'appeler StartSpeakerSearchTaskles API. StartVoiceToneAnalysisTask

Lorsque l'analyse vocale est prête à être traitée, le connecteur vocal envoie un événement "detailStatus": "AnalyticsReady" à la cible de notification sous forme de corps JSON. Si vous utilisez Amazon SNS ou Amazon SQS, ce corps apparaît dans le champ « Enregistrements » de la charge utile Amazon SNS ou Amazon SQS.

L'exemple suivant montre un corps JSON typique.

{
    "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"
        }
    }
}

Cette notification vous permet de déclencher des rappels supplémentaires vers votre application et de répondre à toutes les exigences légales, telles que la notification et le consentement, avant d'appeler les API de tâches d'analyse vocale.

Événements de recherche de conférenciers

Les événements de recherche de conférenciers sont de type SpeakerSearchStatus détaillé.

Les connecteurs vocaux du SDK Amazon Chime envoient les événements de recherche de haut-parleurs suivants :

• Allumettes d'identification

• Génération d'intégration vocale

Les événements peuvent avoir les statuts suivants :

• IdentificationSuccessful— Identification réussie d'au moins un identifiant de profil vocal correspondant avec un score de confiance élevé dans le domaine de profil vocal donné.

• IdentificationFailure— Impossible d'effectuer l'identification. Causes : l'appelant ne parle pas pendant au moins 10 secondes, qualité audio médiocre.

• IdentificationNoMatchesFound— Impossible de trouver une correspondance avec un niveau de confiance élevé dans le domaine de profil vocal donné. L'appelant est peut-être nouveau ou sa voix a peut-être changé.

• VoiceprintGenerationSuccessful— Le système a généré une intégration vocale en utilisant 20 secondes de son non silencieux.

• VoiceprintGenerationFailure— Le système n'a pas réussi à générer d'intégration vocale. Causes : l'appelant ne parle pas pendant au moins 20 secondes, qualité audio médiocre.

Allumettes d'identification

Une fois que l'StartSpeakerSearchTaskAPI est appelée pour une donnéetransactionId, le service Voice Connector renvoie une notification de correspondance d'identification après 10 secondes de conversation silencieuse. Le service renvoie les 10 meilleures correspondances, ainsi qu'un identifiant de profil vocal et un score de confiance compris entre [0, 1]. Plus le score de confiance est élevé, plus il est probable que le locuteur de l'appel corresponde à l'identifiant du profil vocal. Si le modèle d'apprentissage automatique ne trouve aucune correspondance, le detailStatus champ de notification contientIdentificationNoMatchesFound.

L'exemple suivant montre une notification en cas de correspondance réussie.

{    
    "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"
    }
} 

Génération d'intégration vocale

Après 10 secondes supplémentaires de parole non silencieuse, le connecteur vocal envoie une notification de génération d'intégration vocale aux cibles de notification. Vous pouvez inscrire de nouvelles intégrations vocales dans un profil vocal ou mettre à jour une impression déjà présente dans un profil vocal.

L'exemple suivant montre la notification d'une correspondance réussie, ce qui signifie que vous pouvez mettre à jour le profil vocal associé.

{
    "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"
    }
}

Événements d'analyse du ton vocal

Les événements d'analyse de tonalité vocale sont de type VoiceToneAnalysisStatus détaillé. Les analyses peuvent renvoyer les statuts suivants :

• VoiceToneAnalysisSuccessful— Analyse réussie des voix de l'appelant et de l'agent en fonction des probabilités de sentiment (positif, négatif ou neutre).

• VoiceToneAnalysisFailure— Impossible d'effectuer l'analyse de tonalité. Cela peut se produire si l'appelant se bloque sans parler pendant 10 secondes ou si la qualité audio devient trop mauvaise.

• VoiceToneAnalysisCompleted— Analyse réussie des voix de l'utilisateur et de l'agent en fonction des probabilités de sentiment pendant toute la durée de l'appel. Il s'agit du dernier événement, envoyé lorsque l'analyse de la tonalité vocale est terminée.

L'exemple suivant montre un événement typique d'analyse de tonalité vocale.

{
  "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"
}