Criação de solicitações da Speech-to-Text

Este documento é um guia sobre os princípios básicos do uso da Speech-to-Text. Neste guia conceitual, são abordados os tipos de solicitações que podem ser feitas para a Speech-to-Text, como criar essas solicitações e como lidar com as respostas. Recomendamos que todos os usuários da Speech-to-Text leiam este guia e um dos tutoriais associados antes de se aprofundar na API em si.

Solicitações de fala

O Speech-to-Text tem três métodos principais para realizar o reconhecimento de fala. Eles estão listados abaixo:

• O reconhecimento síncrono (REST e gRPC) envia dados de áudio para a API Speech-to-Text, executa o reconhecimento nesses dados e retorna os resultados depois que todo o áudio foi processado. As solicitações de reconhecimento síncrono são limitadas a dados de áudio de até um minuto de duração.

• O reconhecimento assíncrono (REST e gRPC) envia dados de áudio para a API Speech-to-Text e inicia uma operação de longa duração. Usando essa operação, é possível pesquisar periodicamente resultados de reconhecimento. Use solicitações assíncronas para dados de áudio de qualquer duração de até 480 minutos.

• O reconhecimento de streaming (somente gRPC) realiza reconhecimento em dados de áudio fornecidos em um fluxo gRPC bidirecional. As solicitações de streaming são projetadas para fins de reconhecimento em tempo real, como captura de áudio ao vivo de um microfone. O reconhecimento em streaming oferece resultados provisórios enquanto o áudio está sendo capturado, permitindo que o resultado apareça, por exemplo, enquanto um usuário ainda está falando.

As solicitações contêm parâmetros de configuração, bem como dados de áudio. Nas seções a seguir, descrevemos com mais detalhes esses tipos de solicitações de reconhecimento, as respostas que geram e como lidar com essas respostas.

Reconhecimento da API Speech-to-Text

Uma solicitação de reconhecimento síncrono da API Speech-to-Text é o método mais simples para realizar o reconhecimento em dados de áudio de fala. A Speech-to-Text consegue executar até um minuto de dados de áudio de voz enviados em uma solicitação síncrona. Depois que a Speech-to-Text processa e reconhece todo o áudio, ela retorna uma resposta.

Uma solicitação síncrona causa bloqueios, o que significa que a Speech-to-Text precisa retornar uma resposta antes de processar a próxima solicitação. Em geral, a Speech-to-Text processa o áudio mais rápido do que o tempo real, o que significa que ela processa 30 segundos de áudio em 15 segundos, em média. Em casos de qualidade baixa de áudio, sua solicitação de reconhecimento pode demorar muito mais tempo.

A Speech-to-Text tem os métodos REST e gRPC para chamar solicitações síncronas e assíncronas da API Speech-to-Text. Este artigo usa a API REST porque ela é mais simples para mostrar e explicar o uso básico da API. No entanto, a composição básica de uma solicitação REST ou gRPC é bastante semelhante. As solicitações de reconhecimento em streaming só são compatíveis com gRPC.

Solicitações síncronas de reconhecimento de fala

Uma solicitação síncrona da API Speech-to-Text consiste em uma configuração de reconhecimento de fala e dados de áudio. Uma solicitação de amostra é exibida abaixo:

{
    "config": {
        "encoding": "LINEAR16",
        "sampleRateHertz": 16000,
        "languageCode": "en-US",
    },
    "audio": {
        "uri": "gs://bucket-name/path_to_audio_file"
    }
}

Todas as solicitações de reconhecimento síncrono da API Speech-to-Text precisam incluir um campo config de reconhecimento de fala do tipo RecognitionConfig. Um RecognitionConfig contém os seguintes subcampos:

• encoding (obrigatório): especifica o esquema de codificação do áudio fornecido (do tipo AudioEncoding). Se você tiver opções no codec, opte por uma codificação sem perdas, como FLAC ou LINEAR16, para um melhor desempenho. Para mais informações, consulte Codificações de áudio. O campo encoding é opcional para arquivos FLAC e WAV em que a codificação está incluída no cabeçalho do arquivo.
• sampleRateHertz (obrigatório): especifica a taxa de amostragem (em Hertz) do áudio fornecido. Para mais informações sobre essa taxa, consulte as Taxas de amostragem abaixo. O campo sampleRateHertz é opcional para arquivos FLAC e WAV em que a taxa de amostragem é incluída no cabeçalho do arquivo.
• languageCode (obrigatório): contém o idioma + região/localidade a serem usados para o reconhecimento de fala do áudio fornecido. O código de idioma precisa ser um identificador BCP-47. Observe que os códigos de idioma geralmente consistem em tags de idioma principais e subtags de região secundárias para indicar dialetos. No exemplo acima, "en" para inglês e "US" para os Estados Unidos. Para uma lista de idiomas compatíveis, consulte Idiomas compatíveis.
• maxAlternatives - (opcional, o padrão é 1) indica o número de transcrições alternativas a serem fornecidas na resposta. Por padrão, a API Speech-to-Text fornece uma transcrição principal. Se você quiser avaliar alternativas diferentes, defina maxAlternatives para um valor mais alto. Observe que a Speech-to-Text só retornará alternativas se o identificador determinar que elas têm qualidade suficiente. De modo geral, elas são mais apropriadas para solicitações em tempo real que exigem feedback do usuário (como comandos de voz) e, portanto, são mais adequadas para solicitações de reconhecimento de streaming.
• profanityFilter (opcional): indica se palavras ou frases obscenas devem ser filtradas. As palavras filtradas contêm a primeira letra e asteriscos no lugar dos caracteres restantes (por exemplo, f***). O filtro de palavras impróprias opera em palavras isoladas e não detecta discurso abusivo ou ofensivo em uma frase ou uma combinação de palavras.
• speechContext (opcional): contém mais informações contextuais para processar o áudio. Um contexto contém os seguintes subcampos:
  • boost: contém um valor que atribui um peso ao reconhecimento de uma determinada palavra ou frase.
  • phrases: contém uma lista de palavras e frases com dicas para a tarefa de reconhecimento de fala. Para mais informações, consulte as informações sobre adaptação de fala.

O áudio é fornecido à Speech-to-Text por meio do parâmetro audio do tipo RecognitionAudio. O campo audio contém um dos seguintes subcampos:

• content contém o áudio a ser avaliado, incorporado à solicitação. Consulte Incorporação de conteúdo de áudio para mais informações. O áudio transmitido diretamente nesse campo é limitado a um minuto de duração.
• uri contém um URI que aponta para o conteúdo do áudio. O arquivo não pode estar compactado (por exemplo, gzip). No momento, esse campo precisa conter um URI do Google Cloud Storage (com o formato gs://bucket-name/path_to_audio_file). Consulte Como transmitir uma referência de áudio por URI abaixo.

Confira abaixo mais informações sobre esses parâmetros de resposta e solicitação.

Taxas de amostragem

Especifique a taxa de amostragem do áudio no campo sampleRateHertz da configuração da solicitação. Ela precisa corresponder à taxa de amostragem do conteúdo ou fluxo de áudio associado. Taxas de amostragem entre 8.000 Hz e 48.000 Hz são aceitas na Speech-to-Text. É possível especificar a taxa de amostragem para um arquivo FLAC ou WAV no cabeçalho do arquivo em vez de usar o campo sampleRateHertz. Um arquivo FLAC precisa conter a taxa de amostragem no cabeçalho FLAC para ser enviado à API Speech-to-Text.

Se houver uma escolha ao codificar o material de origem, capture o áudio usando uma taxa de amostragem de 16.000 Hz. Valores inferiores a esse podem prejudicar a precisão do reconhecimento de fala, e níveis mais altos não têm efeito prático na qualidade do reconhecimento.

No entanto, se os dados de áudio já foram gravados a uma taxa de amostra existente que não seja 16.000 Hz, não recrie seu áudio para 16.000 Hz. A maior parte do áudio de telefonia legado, por exemplo, usa taxas de amostra de 8.000 Hz, que pode oferecer resultados menos precisos. Se você precisa usar esse áudio, apresente-o à API Speech com a taxa de amostra nativa.

Idiomas

O mecanismo de reconhecimento da Speech-to-Text aceita vários idiomas e dialetos. Você especifica o idioma (e o dialeto nacional ou regional) do áudio no campo languageCode da configuração da solicitação usando um identificador BCP-47.

Confira uma lista completa de idiomas aceitos para cada recurso na página Suporte a idiomas.

Ajustes de tempo (carimbos de data/hora)

A Speech-to-Text pode incluir valores de ajuste de tempo (carimbos de data/hora) referentes ao início e ao fim de cada palavra falada que é reconhecida no áudio fornecido. Um valor de ajuste de horário representa a quantidade de tempo decorrido desde o início do áudio, em incrementos de 100 ms.

Os ajustes de horário são especialmente úteis para analisar arquivos de áudio mais longos, quando for necessário pesquisar uma determinada palavra no texto reconhecido e localizá-la (procurar) no áudio original. Ajustes de horário são compatíveis com todos os nossos métodos de reconhecimento: recognize, streamingrecognize e longrunningrecognize.

Os valores de ajuste de tempo só são incluídos para a primeira alternativa apresentada na resposta de reconhecimento.

Para incluir ajustes de tempo nos resultados da solicitação, defina o parâmetro enableWordTimeOffsets como verdadeiro na configuração da solicitação. Para exemplos que usem a API REST ou as bibliotecas de cliente, consulte Como usar ajustes de horário (carimbos de data/hora). Por exemplo, é possível incluir o parâmetro enableWordTimeOffsets na configuração da solicitação, conforme mostrado aqui:

{
"config": {
  "languageCode": "en-US",
  "enableWordTimeOffsets": true
  },
"audio":{
  "uri":"gs://gcs-test-data/gettysburg.flac"
  }
}

O resultado retornado pela API Speech-to-Text conterá valores de ajuste de tempo para cada palavra reconhecida, conforme mostrado abaixo:

{
  "name": "6212202767953098955",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata",
    "progressPercent": 100,
    "startTime": "2017-07-24T10:21:22.013650Z",
    "lastUpdateTime": "2017-07-24T10:21:45.278630Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse",
    "results": [
      {
        "alternatives": [
          {
            "transcript": "Four score and twenty...(etc)...",
            "confidence": 0.97186122,
            "words": [
              {
                "startTime": "1.300s",
                "endTime": "1.400s",
                "word": "Four"
              },
              {
                "startTime": "1.400s",
                "endTime": "1.600s",
                "word": "score"
              },
              {
                "startTime": "1.600s",
                "endTime": "1.600s",
                "word": "and"
              },
              {
                "startTime": "1.600s",
                "endTime": "1.900s",
                "word": "twenty"
              },
              ...
            ]
          }
        ]
      },
      {
        "alternatives": [
          {
            "transcript": "for score and plenty...(etc)...",
            "confidence": 0.9041967,
          }
        ]
      }
    ]
  }
}

Seleção de modelos

A Speech-to-Text pode usar um dos vários modelos de machine learning para transcrever o arquivo de áudio. O Google treinou esses modelos de reconhecimento de fala para origens e tipos de áudio específicos.

Ao enviar uma solicitação de transcrição de áudio para o Speech-to-Text, é possível melhorar os resultados recebidos especificando a origem do áudio original. Assim, a API Speech-to-Text pode processar seus arquivos de áudio usando um modelo de machine learning treinado para reconhecer o áudio de fala daquele tipo específico de origem.

Para especificar um modelo para reconhecimento de fala, inclua o campo model no objeto RecognitionConfig da solicitação, especificando o modelo que você quer usar.

Consulte a lista de modelos de transcrição da Speech-to-Text para conferir os modelos de machine learning disponíveis.

Conteúdo de áudio incorporado

O áudio incorporado é incluído na solicitação de reconhecimento de fala ao transmitir um parâmetro content no campo audio da solicitação. O áudio incorporado apresentado como conteúdo dentro de uma solicitação gRPC precisa ser compatível com a serialização Proto3 e oferecido como dados binários. O áudio incorporado apresentado como conteúdo em uma solicitação REST precisa ser aceito pela serialização JSON e codificado primeiro em Base64. Consulte Como codificar áudios em Base64 para mais informações.

Ao criar uma solicitação usando uma biblioteca de cliente do Google Cloud, você geralmente grava esses dados binários (ou codificados em Base64) diretamente no campo content.

Transmitir o áudio referenciado por um URI

Normalmente, você transmite um parâmetro uri no campo audio da solicitação de fala, apontando para um arquivo de áudio (em formato binário, não Base64) que está no Google Cloud Storage no seguinte formato:

gs://bucket-name/path_to_audio_file

Por exemplo, a parte abaixo de uma solicitação de fala faz referência ao arquivo de áudio de exemplo usado no guia de início rápido:

...
    "audio": {
        "uri":"gs://cloud-samples-tests/speech/brooklyn.flac"
    }
...

Você precisa ter permissões de acesso apropriadas para ler arquivos do Google Cloud Storage, como uma das mostradas a seguir:

• Leitura pública (como de arquivos de áudio de amostra).
• Leitura pela conta de serviço, se estiver usando a autorização da conta de serviço.
• Leitura por uma conta de usuário, se estiver usando o OAuth de três etapas para autorização da conta de usuário.

Mais informações sobre como gerenciar o acesso ao Google Cloud Storage estão disponíveis em Como criar e gerenciar listas de controle de acesso na documentação do Google Cloud Storage.

Respostas da API Speech-to-Text

Como indicado anteriormente, uma resposta síncrona da API Speech-to-Text pode levar algum tempo para retornar resultados, que é proporcional à duração do áudio fornecido. Depois de processado, a API retornará uma resposta conforme mostrado abaixo:

{
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.98267895,
          "transcript": "how old is the Brooklyn Bridge"
        }
      ]
    }
  ]
}

Estes campos são explicados abaixo:

• results contém a lista de resultados (do tipo SpeechRecognitionResult), em que cada resultado corresponde a um segmento de áudio (segmentos de áudio são separados por pausas). Cada resultado consistirá em um ou mais dos seguintes campos:
  • alternatives contém uma lista de transcrições possíveis, do tipo SpeechRecognitionAlternatives. Para que mais de uma alternativa apareça, você precisa ter solicitado mais de uma alternativa (definindo maxAlternatives como um valor maior que 1) e a Speech-to-Text deve ter produzido alternativas com qualidade alta o suficiente. Cada alternativa consistirá nos seguintes campos:
    • transcript contém o texto transcrito. Consulte Como manipular transcrições abaixo.
    • confidence contém um valor entre 0 e 1, o que indica o grau de confiança da Speech-to-Text na transcrição. Consulte Como interpretar valores de confiança abaixo.

Se nenhuma fala do áudio fornecido puder ser reconhecida, a lista results retornada não conterá itens. O discurso não reconhecido é geralmente o resultado de áudio de qualidade muito baixa ou de códigos de idioma, codificação ou valores de taxa de amostragem que não correspondem ao áudio apresentado.

Os componentes dessa resposta são explicados nas seções a seguir.

Cada resposta síncrona da API Speech-to-Text retorna uma lista de resultados, em vez de um único resultado que contém todo o áudio reconhecido. A lista de áudios reconhecidos (nos elementos transcript) será exibida na ordem contígua.

Selecionar alternativas

Cada resultado em uma resposta de reconhecimento síncrona bem-sucedida pode conter um ou mais alternatives (caso o valor maxAlternatives da solicitação seja maior que 1). Se a Speech-to-Text determinar que uma alternativa tem um nível de confiança suficiente, essa alternativa será incluída na resposta. A primeira opção na resposta é sempre a melhor alternativa (a mais provável).

Configurar maxAlternatives com um valor maior do que 1 não implica ou garante que várias alternativas serão retornadas. Em geral, mais de uma alternativa é mais apropriada para oferecer opções em tempo real aos usuários que conseguem resultados por meio de uma Solicitação de reconhecimento de streaming.

Como manipular transcrições

Cada alternativa fornecida na resposta terá um transcript contendo o texto reconhecido. Quando forem apresentadas alternativas sequenciais, você deverá concatenar essas transcrições juntas.

O seguinte código do Python itera sobre uma lista de resultados e concatena as transcrições juntas. Observe que tomamos a primeira alternativa (o zero) em todos os casos.

response = service_request.execute()
recognized_text = 'Transcribed Text: \n'
for i in range(len(response['results'])):
    recognized_text += response['results'][i]['alternatives'][0]['transcript']

Níveis de confiança

O valor confidence é uma estimativa entre 0,0 e 1,0. Ele é calculado agregando os valores de “probabilidade” atribuídos a cada palavra no áudio. Um número maior indica uma probabilidade maior estimada de que as palavras individuais foram reconhecidas corretamente. Esse campo normalmente é fornecido apenas para a hipótese principal e somente para resultados em que is_final=true. Por exemplo, é possível usar o valor confidence para decidir exibir resultados alternativos para o usuário ou solicitar a confirmação do usuário.

No entanto, esteja ciente de que o modelo determina o resultado melhor classificado com base em mais sinais do que a pontuação confidence isoladamente (como o contexto da frase). Por isso, há casos eventuais em que o principal resultado não tem o maior índice de confiança. Se você não solicitou vários resultados alternativos, o único resultado "melhor" retornado pode ter um valor de confiança menor do que o previsto. Isso pode ocorrer, por exemplo, nos casos em que palavras raras estão sendo usadas. Uma palavra que é raramente usada pode receber um valor baixo de “verossimilhança”, mesmo que seja reconhecida corretamente. Se o modelo determinar a palavra rara para ser a opção mais provável com base no contexto, esse resultado será retornado na parte superior, mesmo se o valor confidence do resultado for menor do que as opções alternativas.

Respostas e solicitações assíncronas

Uma solicitação assíncrona da API Speech-to-Text para o método LongRunningRecognize é idêntica a uma solicitação síncrona da API Speech-to-Text. No entanto, em vez de retornar uma resposta, a solicitação assíncrona vai iniciar uma operação de longa duração (do tipo Operação) e retornar essa operação imediatamente ao recebedor da chamada. É possível usar o reconhecimento de fala assíncrono com áudios de qualquer duração, até 480 minutos.

Uma resposta de operação típica é mostrada abaixo:

{
  "name": "operation_name",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata"
    "progressPercent": 34,
    "startTime": "2016-08-30T23:26:29.579144Z",
    "lastUpdateTime": "2016-08-30T23:26:29.826903Z"
  }
}

Observe que ainda não há nenhum resultado presente. A Speech-to-Text vai continuar processando o áudio e vai usar essa operação para armazenar os resultados. Os resultados serão exibidos no campo response da operação retornada quando a solicitação LongRunningRecognize for concluída.

Uma resposta completa após a conclusão da solicitação aparece abaixo:

{
  "name": "1268386125834704889",
  "metadata": {
    "lastUpdateTime": "2016-08-31T00:16:32.169Z",
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongrunningRecognizeMetadata",
    "startTime": "2016-08-31T00:16:29.539820Z",
    "progressPercent": 100
  }
  "response": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse",
    "results": [{
      "alternatives": [{
        "confidence": 0.98267895,
        "transcript": "how old is the Brooklyn Bridge"
      }]}]
  },
  "done": True,
}

Observe que done foi definido como True e que o response da operação contém um conjunto de resultados do tipo SpeechRecognitionResult, que é o mesmo tipo retornado por uma solicitação síncrona de reconhecimento da API Speech-to-Text.

Por padrão, uma resposta REST assíncrona definirá done como False, seu valor padrão. No entanto, como o JSON não exige que valores padrão estejam presentes em um campo, ao testar se uma operação foi concluída, é preciso testar se o campo done está presente e definido como True.

Como fazer streaming de solicitações de reconhecimento da API Speech-to-Text

Uma chamada de reconhecimento da API Speech-to-Text em streaming é projetada para captura e reconhecimento em tempo real do áudio em um fluxo bidirecional. Seu aplicativo pode enviar áudio no stream de solicitação e receber resultados de reconhecimento provisórios e finais no stream de resposta em tempo real. Resultados provisórios representam o resultado de reconhecimento atual para uma seção de áudio, enquanto o resultado de reconhecimento final apresenta a última e melhor sugestão para essa seção de áudio.

Solicitações de streaming

Ao contrário das chamadas síncronas e assíncronas, em que você envia tanto a configuração quanto o áudio em uma única solicitação, chamar a API Speech de streaming exige o envio de várias solicitações. O primeiro StreamingRecognizeRequest precisa conter uma configuração do tipo StreamingRecognitionConfig sem qualquer áudio de acompanhamento. Os StreamingRecognizeRequests subsequentes enviados pelo mesmo stream consistirão em frames consecutivos de bytes de áudio brutos.

Um StreamingRecognitionConfig é composto dos seguintes campos:

• config (obrigatório): contém as informações de configuração do áudio, do tipo RecognitionConfig, e é igual ao que é mostrado em solicitações síncronas e assíncronas.
• single_utterance (opcional, o padrão é false): indica se a solicitação deve ser encerrada automaticamente após a fala não ser mais detectada. Se configurado, a Speech-to-Text vai detectar pausas, silêncios ou áudios sem fala para determinar quando encerrar o reconhecimento. Se não estiver configurado, o fluxo continuará a ouvir e processar o áudio até que seja encerrado diretamente ou que o comprimento limite seja excedido. Definir single_utterance como true é útil para processar comandos de voz.
• interim_results - (opcional, o padrão é false) indica que esta solicitação de stream deve retornar resultados temporários que podem ser refinados posteriormente (após o processamento de mais áudio). Os resultados provisórios serão anotados nas respostas por meio da configuração de is_final a false.

Respostas de streaming

Os resultados de reconhecimento de fala em streaming são retornados dentro de uma série de respostas do tipo StreamingRecognitionResponse. Essa resposta consiste nos seguintes campos:

• speechEventType contém eventos do tipo SpeechEventType. O valor desses eventos indicará quando uma única fala for determinada como concluída. Os eventos de fala atuam como marcadores na resposta do fluxo.
• results contém a lista de resultados, que podem ser intermediários ou finais, do tipo StreamingRecognitionResult. A lista results contém os seguintes subcampos:
  • alternatives contém uma lista de transcrições alternativas.
  • isFinal indica se os resultados obtidos nessa entrada da lista são intermediários ou finais. O Google pode retornar vários resultados isFinal=true em um fluxo, mas o resultado isFinal=true só é garantido depois que o fluxo de gravação é encerrado (metade do encerramento).
  • stability indica a volatilidade dos resultados obtidos até agora, com 0.0 indicando instabilidade completa e 1.0 indicando estabilidade completa. Diferentemente de "confiança", que estima se uma transcrição está correta, stability estima se o resultado parcial pode ser alterado. Se isFinal estiver definido como true, stability não será definido.