Construção da solicitação do 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 o Speech-to-Text, como construir essas solicitações e como lidar com as respostas. Recomendamos que todos os usuários do Speech-to-Text leiam este guia e um dos tutoriais associados antes de se aprofundar na API em si.

Observação: todos os usuários podem enviar até 60 minutos de áudio para a Speech-to-Text gratuitamente a cada mês. Se você exceder esse valor, serão cobrados custos. Veja detalhes na página Preços.

Faça um teste

Se você ainda não conhece o Google Cloud, crie uma conta para avaliar o desempenho da Speech-to-Text em cenários reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça um teste gratuito da Speech-to-Text

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 stream 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 executar o reconhecimento em dados de áudio de fala. A Speech-to-Text consegue processar até um minuto de dados 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 está causando bloqueios, o que significa que a Speech-to-Text precisa retornar uma resposta antes de processar a próxima solicitação. O Speech-to-Text normalmente processa o áudio mais rápido do que o tempo real, processando 30 segundos de áudio em 15 segundos, em média. Em casos de má qualidade de áudio, sua solicitação de reconhecimento pode demorar muito mais tempo.

O Speech-to-Text tem os métodos REST e gRPC para chamar solicitações assíncronas e sí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 configcampo 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 uma opção 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 o Speech-to-Text só retornará alternativas se o reconhecedor 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 (por exemplo, comandos de voz) e, portanto, são mais adequadas para solicitações de reconhecimento de streaming.
• profanityFilter - (opcional) indica se deve filtrar palavras ou frases obscenas. 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 este áudio. Um contexto contém os subcampos a seguir:
  • 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 que mostram 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 passado diretamente neste campo é limitado a um minuto de duração.
• uri contém um URI que aponta para o conteúdo de áudio. O arquivo não pode estar compactado (por exemplo, gzip). Atualmente, esse campo precisa conter um URI do Google Cloud Storage (de formato gs://bucket-name/path_to_audio_file). Consulte Como passar referência de áudio por um URI abaixo.

Mais informações sobre esses parâmetros de resposta e solicitação são exibidas abaixo.

Taxas de amostragem

Especifique a taxa de amostragem de seu á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 no 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 para a 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 apreciável na qualidade do reconhecimento de fala.

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 do Speech-to-Text é compatível com vários idiomas e dialetos. Você especifica o idioma (e o dialeto nacional ou regional) de seu áudio no campo languageCode da configuração da solicitação, usando um identificador BCP-47.

Veja uma lista completa de idiomas compatíveis para cada recurso na página Suporte a idiomas.

Ajustes de horário (carimbos de data/hora)

O Speech-to-Text pode incluir valores de ajuste de horário (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 horário só são incluídos para a primeira alternativa apresentada na resposta de reconhecimento.

Para incluir ajustes de horário 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 horário para cada palavra reconhecida conforme mostrado a seguir:

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

O Speech-to-Text pode usar um dos vários modelos de machine learning para transcrever seu 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. Isso permite que a API Speech-to-Text processe 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 sua solicitação, especificando o modelo que você quer usar.

Consulte a lista de modelos de transcrição do 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 dentro do 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 dentro de uma solicitação da REST precisa ser compatível com serialização JSON e primeiro ser codificado em Base64. Consulte Como codificar o áudio em Base64 para mais informações.

Ao construir uma solicitação usando uma biblioteca de cliente do Google Cloud, você geralmente grava esses dados binários (ou codificados em base-64) 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) localizado no Google Cloud Storage no seguinte formato:

gs://bucket-name/path_to_audio_file

Por exemplo, a parte a seguir de uma solicitação de fala faz referência ao arquivo de áudio de amostra usado no 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 mais de uma alternativa aparecer, você precisará ter solicitado mais de uma alternativa (definindo maxAlternatives como um valor maior que 1) e a Speech-to-Text deverá 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 nessa 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 áudio reconhecido (nos elementos transcript) será exibida na ordem contígua.

Selecione alternativas

Cada resultado em uma resposta de reconhecimento síncrona bem-sucedida pode conter um ou mais alternatives (se o valor maxAlternatives da solicitação for 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']

Valores 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.

Observação: seu código não deve esperar confidence como um campo obrigatório, porque não há garantia de precisão nem de definição em nenhum dos resultados.

Respostas e solicitações assíncronas

Uma solicitação assíncrona da API Speech-to-Text para o método LongRunningRecognize é idêntica em uma solicitação da API síncrona da Speech-to-Text. Mas, em vez de retornar uma resposta, a solicitação assíncrona iniciará uma operação de longa duração (do tipo Operação) e vai retornar esta operação imediatamente ao recebedor da chamada. É possível usar o reconhecimento de fala assíncrono com áudio de qualquer duração de 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 nenhum resultado ainda está presente. A Speech-to-Text continuará processando o áudio e 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 a operação response 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 informações de configuração para o áudio do tipo RecognitionConfig e é igual ao mostrado em solicitações síncronas e assíncronas.
• single_utterance - (opcional, o padrão é false) indica se esta solicitação deve terminar automaticamente após a fala não ser mais detectada. Se configurado, o Speech-to-Text detectará pausas, silêncio ou áudio sem fala para determinar quando encerrar o reconhecimento. Se não estiver configurado, o streaming continuará a ouvir e processar o áudio até que seja fechado 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 servem como marcadores dentro da resposta de streaming.
• 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 stream, mas o resultado isFinal=true só é garantido depois que o fluxo de gravação é fechado (metade de fechamento).
  • stability indica a volatilidade dos resultados obtidos até agora, com 0.0 indicando instabilidade completa, enquanto 1.0 indica 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.