Usar APIs de voz para executar análises de voz

Para compatibilidade com versões anteriores, você pode usar as APIs de voz do SDK do Amazon Chime para iniciar e gerenciar análise de voz. No entanto, somente as APIs do pipeline do Media Insights para análise de voz fornecem novos atributos, por isso é altamente recomendável usá-las.

As seções a seguir explicam as diferenças entre as APIs dos pipelines de insights de voz e mídia.

Interrupção tarefas

Se você usar um conector de voz para iniciar tarefas de análise de voz e depois usar a UpdateMediaInsightsPipelineStatusAPI para pausar o pipeline, as tarefas continuarão em execução. Para interromper as tarefas, você deve chamar as StopVoiceToneAnalysisTaskAPIs StopSpeakerSearchTaske.

Noções básicas sobre as diferenças de notificação

Quando você usa APIs de voz para executar análises de voz, as notificações são diferentes das geradas pelos pipelines do Media Insights.

• Eventos prontos para análise de voz só estão disponíveis para tarefas iniciadas usando APIs de voz.

• Você precisa usar os campos voiceConnectorId, transactionId ou callId em suas notificações para associar uma tarefa de análise de voz a uma chamada. Se você usa pipelines de insights de mídia para executar análises de voz, use os campos mediaInsightsPipelineId e streamArn, ou channelId para associar uma tarefa a uma chamada.

Os tópicos a seguir explicam como usar notificações com APIs de voz.

Eventos prontos para análise de voz

Os eventos prontos para análise de voz têm o tipo de detalhe VoiceAnalyticsStatus.

Use os conectores de voz do SDK do Amazon Chime para iniciar tarefas de análise. Ao receber um evento pronto para análise de voz, você pode acionar uma tarefa de busca de locutor ou análise do tom de voz para a chamada, identificada pelas seguintes propriedades:

• voiceConnectorId

• transactionId

nota

Essa notificação é fornecida somente quando você tem uma configuração de pipeline do Media Insights com análise de voz habilitada e associada a um Voice Connector. Essa notificação NÃO é fornecida quando os clientes chamam a API CreateMediaInsightsPipeline e iniciam uma tarefa de busca de locutor ou uma tarefa de análise do tom de voz por meio do SDK de pipelines de mídia.

Os cabeçalhos SIP retornados por um Voice Connector contêm a transactionId. Se você não tiver acesso aos cabeçalhos SIP, o evento de notificação AnalyticsReady também conterá o voiceConnectorId e o transactionId. Isso permite que você receba programaticamente as informações e chame as StartSpeakerSearchTask, ou StartVoiceToneAnalysisTaskAPIs.

Quando a análise de voz está pronta para processamento, o Voice Connector envia um evento "detailStatus": "AnalyticsReady" para o destino de notificação como um corpo JSON. Se você usa o Amazon SNS ou o Amazon SQS, esse corpo aparece no campo “Registros” na carga útil do Amazon SNS ou do Amazon SQS.

O exemplo a seguir mostra um típico corpo de 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"
        }
    }
}

Essa notificação permite que você acione retornos de chamada adicionais para seu aplicativo e atenda a quaisquer requisitos legais, como notificação e consentimento, antes de chamar as APIs de tarefas de análise de voz.

Eventos de pesquisa de locutor

Os eventos de pesquisa de locutor têm o tipo de detalhe SpeakerSearchStatus.

Os conectores de voz do SDK do Amazon Chime enviam os seguintes eventos de pesquisa de locutor:

• Identificação corresponde

• Geração de incorporação de voz

Os eventos podem ter os seguintes status:

• IdentificationSuccessful: identificou com sucesso pelo menos um ID de perfil de voz correspondente com uma alta pontuação de confiança em determinado domínio de perfil de voz.

• IdentificationFailure: falha ao realizar a identificação. Causas: o chamador não fala por pelo menos 10 segundos, baixa qualidade de áudio.

• IdentificationNoMatchesFound: não foi possível encontrar uma correspondência de alta confiança no domínio do perfil de voz fornecido. O chamador pode ser novo ou sua voz pode ter mudado.

• VoiceprintGenerationSuccessful: o sistema gerou uma incorporação de voz usando 20 segundos de áudio não silencioso.

• VoiceprintGenerationFailure: o sistema falhou ao gerar uma incorporação de voz. Causas: o chamador não fala por pelo menos 20 segundos, baixa qualidade de áudio.

Identificação corresponde

Depois que a StartSpeakerSearchTaskAPI é chamada para uma determinadatransactionId, o serviço Voice Connector retorna uma notificação de correspondência de identificação após 10 segundos de fala não silenciosa. O serviço retorna as 10 melhores correspondências, junto com um ID de perfil de voz e uma pontuação de confiança que varia de [0, 1]. Quanto maior a pontuação de confiança, maior a probabilidade de o locutor da chamada corresponder ao ID do perfil de voz. Se o modelo de machine learning não encontrar correspondências, o campo detailStatus da notificação conterá IdentificationNoMatchesFound.

O exemplo a seguir mostra a notificação de uma correspondência bem-sucedida.

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

Geração de incorporação de voz

Depois de mais 10 segundos de fala não silenciosa, o Voice Connector envia uma notificação de geração de incorporação de voz para os destinos de notificação. Você pode inscrever novas incorporações de voz em um perfil de voz ou atualizar uma impressão que já está em um perfil de voz.

O exemplo a seguir mostra a notificação de uma correspondência bem-sucedida, o que significa que você pode atualizar o perfil de voz associado.

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

Eventos de análise do tom de voz

Os eventos de análise do tom de voz têm o tipo de detalhe VoiceToneAnalysisStatus. As análises podem retornar esses status:

• VoiceToneAnalysisSuccessful: analisou com sucesso as vozes do chamador e do atendente em probabilidades de sentimento: positivo, negativo ou neutro.

• VoiceToneAnalysisFailure: falha ao realizar a análise do tom. Isso pode acontecer se o chamador ficar sem falar por 10 segundos ou se a qualidade do áudio ficar muito ruim.

• VoiceToneAnalysisCompleted: analisou com sucesso as vozes do usuário e do atendente quanto às probabilidades de sentimento durante toda a chamada. Esse é o evento final, enviado quando a análise do tom de voz é concluída.

O exemplo abaixo mostra um evento típico de análise do tom de voz.

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