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 do 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, ele é alimentado por aprendizado de máquina.
Você vai 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 do Gradle. Depois, vai usar a API Docs para conferir os resultados.
O que você vai aprender
- Como usar a API Google Cloud Speech-to-Text
- Como usar a API Google Docs para criar um documento
- Como usar a API Docs para gravar em um documento
O que é necessário
- Java instalado (versão 7 ou mais recente)
- 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. Crie uma conta do Gmail ou do Workspace, se ainda não tiver 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.
Receber uma chave de 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 do 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 Google Docs
- De volta ao console do GCP, acesse Credenciais.
- Criar uma chave do 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
- Google Docs
Agora você já pode começar a trabalhar com seu código.
3. Configurar o código
Acessar o exemplo de código
Para acessar o exemplo de código, faça o download do arquivo zip para seu computador...
...ou clone o repositório do GitHub pela linha de comando.
$ git clone git@github.com:googleworkspace/docs-transcript-codelab.git
Você vai trabalhar no arquivo CreateTranscript.java dentro do diretório start. Os arquivos gradle não devem ser modificados.
No diretório, navegue até a pasta start e abra o arquivo CreateTranscript.java. Role a tela para baixo até encontrar a declaração da 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);
Na variável SCOPES, você especificou que seu código poderá visualizar e gerenciar os documentos do Google Docs do usuário. Se o código exigir autorização além ou diferente desse acesso, ajuste a variável de acordo com os escopos da API do Google do OAuth 2.0.
Por exemplo, se você não estivesse escrevendo em um Google Docs, poderia mudar o escopo para DOCUMENTS_READONLY. A variável SCOPES é necessária não apenas para que o app tenha permissões de acesso adequadas, mas também para manter a transparência com os usuários. Os escopos específicos que você solicita são mostrados ao usuário na página de verificação do OAuth, onde ele precisa dar consentimento para usar o app.
Renomear variáveis
Verifique se as variáveis acima foram declaradas corretamente para seu 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 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 sua pasta. Se não estiver, crie o diretório.
Agora você pode começar a executar seu código.
4. Inicializar um cliente do Google 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 de função
A primeira tarefa que você está realizando aqui é a criação da Docs service (variável). O serviço representa um cliente de API autorizado, que contém suas credenciais e, neste caso, sua autenticação de usuário final.
No seu código, qualquer função que faça uma chamada para a API Docs precisará usar essa variável service para realizar tarefas relacionadas aos Documentos.
5. Criar um documento Google
Você vai criar um novo documento do Google com um título especificado. Copie 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 ID do arquivo do Drive do documento do Google. O mesmo ID pode ser encontrado no URL do documento.
Em seguida, inicialize o cliente da Speech-to-Text.
6. Chamar a API Speech-to-Text
A próxima tarefa que você quer realizar no código é obter a transcrição escrita do arquivo de áudio. Em CreateTranscript.java, encontre a função getTranscript().
Primeiro, obtenha o caminho e os bytes de áudio do arquivo:
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 o reconhecedor de voz deve processar sua solicitação. Edite setLanguageCode() se, por exemplo, o arquivo de áudio estiver em um idioma diferente do inglês e mude setSampleRateHertz() se ele 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();
Preparar o texto
Por fim, processe a variável result da 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 de 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, insira o texto da transcrição no documento do Google. Para fazer modificações em um documento, use o método BatchUpdate. BatchUpdate é um contêiner para diferentes tipos de solicitações de gravação e, aqui, você vai usar InsertTextRequest.
EndOfSegmentLocation é um parâmetro importante que especifica onde no 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 ver como os resultados da API Speech-to-Text, combinados com chamadas à API Docs, podem permitir que você insira a transcrição de um arquivo de áudio em um documento do Google:
BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(docId,
body.setRequests(insertRequests)).execute();
Como criar a solicitação
Ao fazer a solicitação BatchUpdate, você define duas especificações muito importantes: o que você quer imprimir (.setText()) e onde no documento você quer fazer isso (.setIndex(1)).
Agora 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 necessário para pegar um arquivo de áudio, obter a transcrição dele e imprimir essa transcrição em um novo documento do Google, vamos começar!
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 criar e executar. Neste e em outros projetos, mantenha o mainClassName consistente com a classe Java que você quer executar.
Ótimo! Agora você pode executar o código. Para fazer isso, digite o seguinte na linha de comando:
$ gradle run
Autenticação de usuário final
Na primeira vez que você executar esse código, um URL será impresso no terminal, pedindo que você faça login na sua conta de serviço e autorize o acesso ao Google Docs dela. Depois de permitir o acesso, você vai notar um novo arquivo armazenado no seu diretório.
No diretório de trabalho, você vai encontrar uma pasta recém-criada chamada tokens, que contém um arquivo StoredCredential. Esse é o token de autenticação que você acabou de fornecer. Ele foi solicitado pelo cliente ao servidor de autenticação do Google, extraído da resposta e agora será enviado para qualquer API que você chamar.
Solução
Se o código não estiver funcionando, confira o arquivo CreateTranscript.java na pasta finish. Esse arquivo tem todo o código exatamente como ele precisa estar para ser executado corretamente.
Agora vamos conferir o resultado.
9. Como ver os resultados
Você acabou de criar um documento do Google com a transcrição do arquivo de áudio. Vamos dar uma olhada nele.
Este documento foi criado com a conta que o usuário final autorizou. Uma possível expansão é compartilhar automaticamente esse documento com outras pessoas usando a API Drive.
Usando o código-fonte e o arquivo de áudio fornecidos, você vai ver o seguinte:
10. Parabéns!
Agora você aprendeu a criar um documento do Google, fazer uma chamada para a API Speech-to-Text e gerar a transcrição do arquivo de áudio no documento criado.
Possíveis melhorias
Confira algumas ideias para fazer uma integração mais interessante:
- Configure seu código para detectar quando um arquivo de áudio for adicionado ao bucket do Cloud Storage no Google Cloud Storage e acione uma função do Cloud para executar esse código.
- Insira texto em um documento do Google que não esteja vazio
Saiba mais
- Leia a documentação da API Google Docs para desenvolvedores.
- Publique perguntas e encontre respostas no Stack Overflow com a tag google-docs-api.