1. Visão geral
Neste codelab, você vai aprender a enviar um arquivo de áudio pela API Google Cloud Speech-to-Text e gerar a transcrição em um documento Google. A API Speech to Text é fácil de usar e aplica redes neurais avançadas para permitir que os desenvolvedores transformem áudio em texto. Além disso, usa a tecnologia de machine learning.
Você usará a API Google Docs para criar e gravar em um novo documento. Você vai criar um aplicativo de linha de comando Java e executar o código usando o sistema de build Gradle. Depois, vai usar a API Docs para ver os resultados.
O que você vai aprender
- Como usar a API Cloud Speech to Text do Google
- Como usar a API Google Docs para criar um novo documento
- Como usar a API Docs para gravar em um documento
O que é necessário
- Java instalado (versão 7 ou superior)
- Gradle instalado (versão 5 ou mais recente)
- Acesso à Internet e a um navegador da Web
- Uma Conta do Google
- Um projeto do Google Cloud Platform
2. Criar o projeto
Criar seu projeto na nuvem
- Faça login no console do Cloud e crie um novo projeto ou reutilize um existente. Se você ainda não tiver uma conta do Gmail ou do Workspace, crie uma.
Lembre-se do código do projeto, um nome exclusivo em todos os projetos do Google Cloud. O nome acima já foi escolhido e não servirá para você. Faremos referência a ele mais adiante neste codelab como PROJECT_ID.
- Em seguida, será necessário ativar o faturamento no Console do Cloud para usar os recursos do Google Cloud.
A execução deste codelab não será muito cara, se for o caso. Siga todas as instruções na seção "Limpeza", que orienta você sobre como encerrar recursos para não incorrer em cobranças além deste tutorial. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.
Gerar uma chave da conta de serviço para a API Cloud Speech-to-Text
- Acesse o Console do GCP e encontre seu novo projeto
- Criar uma conta de serviço
- Fazer o download de uma chave de conta de serviço como JSON
- Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Se você reiniciar a sessão de shell, vai precisar definir a variável novamente.
$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Exemplo:
$ export GOOGLE_APPLICATION_CREDENTIALS="/home/usr/downloads/ServiceAccount.json"
Receber credenciais para a API Docs
- No Console do GCP, acesse Credenciais.
- Criar uma chave OAuth 2.0 e fazer o download dela como JSON
- Renomeie o arquivo
credentials.jsone verifique se ele está no diretóriosrc/main/resources/do seu código.
Ativar APIs
- Selecione a guia Painel, clique no botão Ativar APIs e serviços e ative as duas APIs a seguir:
- Conversão de voz em texto
- Documentos Google
Agora você já pode começar a trabalhar com o código.
3. Configurar seu código
Fazer o download do exemplo de código
Para acessar o exemplo de código, faça o download do arquivo ZIP para seu computador...
...ou clonar o repositório do GitHub pela linha de comando.
$ git clone git@github.com:googleworkspace/docs-transcript-codelab.git
Você trabalhará no arquivo CreateTranscript.java dentro do diretório start. Os arquivos do Gradle não podem ser modificados.
No diretório, navegue até a pasta start e abra o arquivo CreateTransaction.java. Role para baixo até a declaração de classe CreateTranscript.
public class CreateTranscript {
private static final String CREDENTIALS_FILE_PATH = "/credentials.json";
// Specify audio file name below.
private static final String AUDIO_FILENAME = "audioFile.wav";
private static final String TOKENS_DIRECTORY_PATH = "tokens";
private static final JsonFactory JSON_FACTORY = JacksonFactory.getDefaultInstance();
private static final String APPLICATION_NAME = "CreateTranscript";
private static final List<String> SCOPES = Collections.singletonList(DocsScopes.DOCUMENTS);
Para sua variável SCOPES, você especificou que seu código poderá visualizar e gerenciar os documentos do usuário nos Documentos Google. Se seu código exigir uma autorização maior ou diferente desse acesso, ajuste a variável de acordo com os Escopos das APIs do Google para OAuth 2.0.
Por exemplo, se você não estiver escrevendo em um documento Google, poderá mudar o escopo para DOCUMENTS_READONLY. A variável SCOPES é necessária não só para que o app tenha as permissões de acesso adequadas, mas também para manter a transparência com os usuários. O usuário verá os escopos específicos solicitados na página de verificação do OAuth, onde precisará consentir para usar o aplicativo.
Renomear variáveis
Verifique se as variáveis acima foram declaradas corretamente para o projeto.
- Verifique se AUDIO_FILENAME está definido como o nome do arquivo de demonstração que você está enviando para a API Speech-to-Text. No seu arquivo CreateTranscript.java, ele já deve estar definido corretamente.
- Renomeie CREDENTIALS_FILE_PATH para o nome do arquivo de credenciais baixado (deve ser ‘/
credentials.json'). Verifique se esse arquivo está no diretóriosrc/main/resourcesda pasta. Crie esse diretório caso a clonagem do GitHub não ajude.
Agora, você pode começar a executar o código.
4. Inicializar um cliente do Docs
No arquivo CreateTranscript.java, encontre a declaração do método principal e confira o que está dentro:
final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
Docs service = new Docs.Builder(HTTP_TRANSPORT, JSON_FACTORY,
getCredentials(HTTP_TRANSPORT))
.setApplicationName(APPLICATION_NAME)
.build();
Autorização da função
A primeira tarefa que você vai realizar aqui é a criação da variável Docs service. O serviço representa um cliente de API autorizado que contém suas credenciais e, nesse caso, a autenticação do usuário final.
No seu código, qualquer função que faça uma chamada para a API Docs precisará utilizar essa variável service para realizar tarefas relacionadas ao Documentos.
5. Como criar um documento Google
Você criará um novo arquivo do Documentos Google com um título específico. Então, vamos copiar o código abaixo na função createDocument.
Document doc = new Document().setTitle("Transcript for " +
AUDIO_FILENAME);
doc = service.documents().create(doc).execute();
String documentId = doc.getDocumentId();
return documentId;
Essa função retorna o código do arquivo do Drive do documento Google. Esse mesmo ID pode ser encontrado no URL do documento.
Em seguida, você vai inicializar o cliente Speech-to-Text.
6. Chamar a API Speech-to-Text
A próxima tarefa a realizar no seu código é obter a transcrição escrita do arquivo de áudio. Em CreateTranscript.java, encontre a função getTranscript().
Primeiro, descubra o caminho e os bytes de áudio do arquivo de áudio:
SpeechClient speech = SpeechClient.create();
Path path = Paths.get(AUDIO_FILENAME);
byte[] data = Files.readAllBytes(path);
ByteString audioBytes = ByteString.copyFrom(data);
Configurar o reconhecimento de fala
Em seguida, inicialize corretamente a variável RecognitionConfig.
Aqui, config fornece informações sobre como exatamente seu reconhecedor de fala precisa processar sua solicitação. Será necessário editar setLanguageCode() se, por exemplo, o arquivo de áudio estiver em um idioma diferente do inglês, e mudar setSampleRateHertz() se o arquivo de áudio tiver uma taxa de amostragem diferente em Hertz (1600 é o ideal).
RecognitionConfig config =
RecognitionConfig.newBuilder()
.setEncoding(AudioEncoding.LINEAR16)
.setLanguageCode("en-US")
.setSampleRateHertz(8000)
.build();
RecognitionAudio audio =
RecognitionAudio.newBuilder().setContent(audioBytes).build();
RecognizeResponse response = speech.recognize(config, audio);
List<SpeechRecognitionResult> results = response.getResultsList();
Preparação do texto
Por fim, processe a variável result de transcrição do arquivo de áudio e prepare-a para ser inserida em um documento.
Cada item nos resultados é uma transcrição do tipo SpeechRecognitionAlternatives. Assim, cada item contém duas partes: uma transcrição do texto e a pontuação de confiança correspondente da API.
List<Request> requests = new ArrayList<>();
for (SpeechRecognitionResult result : results) {
// Using the first + most likely alternative transcript
SpeechRecognitionAlternative alternative =
result.getAlternativesList().get(0);
String toInsert = alternative.getTranscript();
// Add requests array list to return.
requests.add(
new Request()
.setInsertText(
new InsertTextRequest()
.setText(toInsert)
.setEndOfSegmentLocation(new
EndOfSegmentLocation().setSegmentId(""))));
}
return requests;
7. Inserir texto em um documento
Agora você vai inserir o texto da transcrição no documento Google. Para fazer modificações em um documento, você precisará usar o método BatchUpdate. O BatchUpdate é um contêiner para diferentes tipos de solicitações de gravação e, aqui, você vai usar InsertTextRequest.
O EndOfSegmentLocation é um parâmetro importante que especifica em que parte do documento você quer imprimir o texto. No código-fonte, você está inserindo texto no corpo do documento.
Vamos inserir o código abaixo na sua função para conferir como os resultados da API Speech-to-Text e as chamadas para a API Docs podem permitir a inserção da transcrição de um arquivo de áudio em um documento Google:
BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(docId,
body.setRequests(insertRequests)).execute();
Como criar a solicitação
Ao fazer a solicitação BatchUpdate, defina duas especificações muito importantes: o que você quer imprimir (.setText()) e em que parte do documento (.setIndex(1)).
Você inseriu a transcrição do arquivo de áudio no documento criado.
8. Como executar o código
Agora que você tem todo o código de que precisa para pegar um arquivo de áudio, obter a transcrição e imprimi-la em um documento Google recém-criado, vamos fazer o programa!
Como você vai executar o código Java usando o sistema de build do Gradle, é necessário informar ao arquivo build.gradle o que exatamente precisa ser criado e executado. Para este e outros projetos, mantenha a mainClassName consistente com a classe Java que você quer executar.
Ótimo! Agora você já pode executar o código. Para fazer isso, digite o seguinte na linha de comando:
$ gradle run
Autenticação de usuário final
Ao executar esse código pela primeira vez, você verá um URL impresso no terminal, solicitando que você faça login na sua conta de serviço e autorize o acesso aos Documentos Google. Depois de permitir o acesso, você vai notar um novo arquivo armazenado no seu diretório.
Dentro do diretório de trabalho, você verá uma pasta recém-criada chamada tokens, contendo um arquivo StoredCredential. Este é o token de autenticação que você acabou de fornecer, que seu cliente solicitou do Google Auth Server, extraído da resposta dele e que agora será enviado para qualquer API que você chamar.
Solução
Caso seu código não esteja funcionando, confira o arquivo CreateTranscript.java dentro da pasta CreateTranscript.java. Esse arquivo contém todo o código exatamente como ele precisa para ser executado com sucesso.
Agora vamos conferir o resultado.
9. Como ver os resultados
Você acabou de criar um novo documento do Google contendo a transcrição de seu arquivo de áudio. Então, vamos analisá-lo.
Este documento foi criado na conta que o usuário final autorizou. Também é possível compartilhar automaticamente o documento com outras pessoas usando a API Drive.
Usando o código-fonte e o arquivo de áudio fornecido, você verá o seguinte:
10. Parabéns!
Agora você aprendeu a criar um documento Google, chamar a API Speech-to-Text e gerar a transcrição do arquivo de áudio no documento criado.
Possíveis melhorias
Aqui estão algumas ideias sobre como fazer uma integração mais atraente:
- Configure seu código para detectar quando um arquivo de áudio for adicionado ao seu bucket do Google Cloud Storage no Drive e acione uma função do Google Cloud para executar esse código.
- Brinque com a inserção de texto em um documento Google que esteja preenchido
Saiba mais
- Leia a documentação da API Google Docs para desenvolvedores (em inglês).
- Publique perguntas e encontre respostas no Stack Overflow com a tag google-docs-api.