GSP125

Visão geral

A API de streaming Google Cloud Speech permite que os desenvolvedores transformem linguagem falada em texto em tempo real. Usando essa API combinada a WebSockets e à API Web Audio do JavaScript, um servlet Java pode receber áudio transmitido de uma página da Web e gerar transcrições em texto, possibilitando que qualquer página da Web utilize a fala como uma interface adicional para o usuário.

Este laboratório está dividido em várias seções, e cada uma delas apresenta um componente do aplicativo da Web final.

O web app que você criar vai receber áudio do microfone do cliente e transmiti-lo para um servlet Java. Ele, por sua vez, envia os dados para a API Cloud Speech, que transmite transcrições de qualquer fala detectada de volta para o servlet. Em seguida, o servlet passa os resultados da transcrição para o cliente, que os exibe na página.

Para fazer isso, você precisa criar vários componentes:

• Um servlet Java para veicular o HTML, o JavaScript e o CSS estáticos da página da Web.
• O JavaScript, o HTML e o CSS para conectar a página da Web ao microfone do usuário, extrair os bytes brutos e transmiti-los ao servlet por um WebSocket.
• Um gerenciador de WebSocket do servlet que transmite os bytes de áudio recebidos do cliente para a API Cloud Speech e envia os resultados da transcrição da API Cloud Speech de volta para o cliente.

Atividades deste laboratório

• Criar uma máquina virtual (VM)
• Iniciar um servlet Java HTTP
• Capturar áudio em uma página da Web
• Transformar voz em texto

Pré-requisitos

Para fazer este laboratório, é preciso ter familiaridade com:

• A linguagem de programação Java.
• Servlets Java (especificamente, o contêiner de servlet Jetty). Embora outros contêineres de servlet possam ser usados, a solução de exemplo utiliza o Jetty, o que dificulta a verificação de soluções baseadas em outros contêineres.
• A linguagem de programação JavaScript. O código de páginas da Web é escrito quase exclusivamente em JavaScript, então seria difícil que um laboratório sobre uma página da Web evitasse usar essa linguagem.
• A linha de comando do Linux. Grande parte do laboratório acontece em um prompt de comando do Linux. Por isso, vai ficar mais fácil se você tiver familiaridade com algumas ferramentas comuns e um editor de texto para esse ambiente.
• A ferramenta de gerenciamento de projetos Maven. Em princípio, qualquer ferramenta de gerenciamento de projetos Java pode ser usada, mas a solução de exemplo utiliza o Maven, o que dificulta a verificação de soluções baseadas em outras ferramentas.

Configuração e requisitos

Antes de clicar no botão Começar o Laboratório

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.

Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Tarefa 1: criar uma máquina virtual

O Compute Engine é um serviço que permite iniciar VMs na infraestrutura do Google. Neste laboratório, você vai criar e usar uma VM para executar um servlet escrito em Java 8 que hospeda o site e usa a API Cloud Speech para fornecer transcrições dinâmicas ao cliente. Para os fins deste laboratório, você também usará a VM para executar o código.

1. Para criar uma VM, clique no menu de navegação () > Compute Engine > Instâncias de VM.

2. Para criar uma instância, clique em Criar instância.

3. Na Configuração da máquina.

   • Nomeie a nova instância como speaking-with-a-webpage.

   • Escolha uma zona como .

   • Mantenha os valores padrão nas outras configurações.

4. Clique em SO e armazenamento.

   • Selecione Alterar para começar a configurar o disco de inicialização e selecione os seguintes valores:

     • Em Sistema operacional, selecione Debian.

     • Em Versão, selecione Debian GNU/Linux 12 (bookworm).

     • Mantenha o valor padrão em Tipo de disco de inicialização.

     • Na parte de baixo da janela, clique em Selecionar.

5. Clique em Rede.

   • Em Firewall, marque as opções Permitir tráfego HTTP e Permitir tráfego HTTPS.

6. Clique em Segurança.

   • Em Identidade e acesso à API > Conta de serviço, mantenha o valor padrão.

   • Em Escopos de acesso, selecione Permitir acesso total a todas as APIs do Cloud.

7. Clique em Criar.

Depois de alguns minutos, sua VM estará funcionando. Veja a VM e os detalhes dela na lista Instâncias de VM. Observe o botão SSH para usar na próxima etapa e o IP externo para usar mais tarde neste laboratório.

8. Para se conectar, clique no botão SSH à direita. Se for solicitado, clique em Autorizar.

Uma nova janela é aberta e conecta você à VM, mostrando um prompt de comando. Use essa interface no restante deste laboratório.

Testar a tarefa concluída

Clique em Verificar meu progresso para conferir a tarefa realizada.

Crie uma máquina virtual

Documentação relevante

Leia a documentação do Compute Enginepara saber mais sobre esse componente e os diferentes recursos dele.

Tarefa 2: baixar e configurar um exemplo funcional

1. Na sessão SSH, instale o Git, o Java 17 e a ferramenta de gerenciamento de projetos Maven para compilar e executar o exemplo de código:

sudo apt update && sudo apt install git -y sudo apt install -y maven openjdk-17-jdk Observação: esse comando pode levar alguns minutos.

2. Clone o exemplo funcional na sua VM:

git clone https://github.com/googlecodelabs/speaking-with-a-webpage.git

Isso cria o diretório speaking-with-a-webpage, que contém subdiretórios para cada uma das seções a seguir. Cada subdiretório se baseia no anterior, adicionando gradualmente novas funcionalidades:

• 01-hello-https: contém um servlet Jetty mínimo com arquivos estáticos e um manipulador veiculado por HTTPS.
• 02-webaudio: preenche o JavaScript do lado do cliente para gravar áudio do microfone do cliente e mostrar uma visualização para confirmar que funciona.
• 03-websockets: modifica o cliente e o servidor para que se comuniquem por um websocket.
• 04-speech: modifica o servidor para enviar áudio à API Cloud Speech e transcrições subsequentes ao cliente JavaScript.

O exemplo deste laboratório não usa a porta HTTPS normal, e sim a porta não privilegiada 8443 para fins de desenvolvimento.

3. Para acessar essa porta no navegador da Web, abra o firewall da VM usando este comando gcloud:

gcloud compute firewall-rules create dev-ports \ --allow=tcp:8443 \ --source-ranges=0.0.0.0/0 Observação: compare o que mudou entre as etapas.

Se você quiser comparar o que mudou entre uma seção e a próxima, use o seguinte comando:

cd ~/speaking-with-a-webpage

git diff --no-index 01-hello-https/ 02-webaudio/

Isso mostra as diferenças entre os diretórios / etapas 02-https e 03-webaudio.

Use as teclas de seta, PgUp / PgDn para navegar e q para sair.

Testar a tarefa concluída

Clique em Verificar meu progresso para conferir a tarefa realizada.

Instale o software necessário e crie uma regra de firewall

Tarefa 3: iniciar o servlet Java HTTPS

O servlet Java é a estrutura que oferece suporte a esse web app, já que ele disponibiliza o código HTML, CSS e JavaScript necessário do lado do cliente e se conecta à API Cloud Speech para fornecer transcrições.

Ao acessar o microfone de um usuário em uma página da Web, os navegadores exigem que a página se comunique por um canal seguro para evitar vazamento de informações. Por isso, configure seu servlet para veicular páginas da Web por HTTPS. Como a configuração e a publicação de páginas da Web seguras é um tema à parte, neste laboratório, use o certificado autoassinado e os arquivos de configuração do Jetty na solução de exemplo fornecida. Isso é suficiente para um ambiente de desenvolvimento.

Nesta seção, basta ler e executar o projeto do Maven fornecido em 01-hello-https. Preste atenção especial aos arquivos no diretório src/, que são os principais arquivos usados nas etapas subsequentes:

• Os arquivos em src/main/webapp incluem os arquivos JavaScript, CSS e HTML, que são veiculados de forma estática pelo Jetty.
• O TranscribeServlet.java define o servlet que trata as solicitações para o caminho /transcribe.

Como executar a solução de exemplo

O subdiretório 01-hello-https do repositório speaking-with-a-webpage fornecido contém um projeto do servlet Maven configurado para HTTPS. Esse servlet usa o framework do servlet Jetty para veicular arquivos estáticos e um endpoint dinâmico. Ele também usa a postagem do blog acima para gerar um certificado autoassinado usando o comando keytool e adiciona a configuração do Jetty para compatibilidade com HTTPS.

1. Inicie o servlet. Acesse 01-hello-https.

cd ~/speaking-with-a-webpage/01-hello-https

2. Execute o código:

mvn clean jetty:run

3. Em seguida, direcione o navegador da Web para: https://<your-external-ip>:8443

Observação : encontre seu endereço IP externo na página "Instâncias de VM" do console do Cloud.

Como o servlet de exemplo está detectando eventos em uma porta não padrão, clicar diretamente no link do IP externo não direciona você ao servlet em execução. Você precisa adicionar a porta relevante, conforme mostrado acima, para acessar o servlet.

Quando você acessar o web app usando o URL HTTPS, seu navegador provavelmente vai avisar que a conexão não é particular. Isso ocorre porque o app de exemplo usa um certificado SSL autoassinado para desenvolvimento. Em um ambiente de produção, você precisaria de um certificado SSL assinado por uma autoridade certificadora, mas, para fins deste laboratório, um certificado SSL autoassinado é suficiente. Só não conte nenhum segredo para sua página da Web. 😁

Testar a tarefa concluída

Clique em Verificar meu progresso para conferir a tarefa realizada.

Execute a solução de exemplo (hello-https)

Tarefa 4: capturar áudio em uma página da Web

A API Web Audio permite que uma página da Web capture dados de áudio do microfone de um usuário, desde que ele dê consentimento para isso. A API Cloud Speech precisa desses dados brutos em um formato específico e precisa saber a taxa de amostragem usada na captura.

Solução de exemplo

O subdiretório 02-webaudio do repositório speaking-with-a-webpage fornecido se baseia no exemplo de código 01-hello-https ao adicionar a função getUserMedia do Web Audio para conectar o microfone do usuário a uma visualização do áudio. Em seguida, ele adiciona um ScriptProcessorNode ao pipeline de áudio para recuperar os bytes de áudio brutos, preparando-o para envio ao servidor. Como a API Cloud Speech também vai precisar da sampleRate, essa informação é recuperada. Inicie o app 02-webaudio da seguinte maneira:

1. Pressione CTRL+C para interromper o servidor.

2. Navegue até o diretório que contém 02-webaudio:

cd ~/speaking-with-a-webpage/02-webaudio

3. Execute o aplicativo:

mvn clean jetty:run

4. Para acessar o web app em execução, procure o endereço IP externo na página "Instâncias de VM" do console do Cloud e direcione o navegador para https://<your-external-ip>:8443.

Observação: para verificar o que mudou entre a seção anterior (01-hello-https) e a atual (02-webaudio), execute:

cd ~/speaking-with-a-webpage git diff --no-index 01-hello-https/ 02-webaudio/

Testar a tarefa concluída

Clique em Verificar meu progresso para conferir a tarefa realizada.

Execute a solução de exemplo para capturar áudio na página da Web

5. Pressione CTRL+C para interromper o servidor.

Tarefa 5: transmitir áudio do cliente para o servidor

Uma conexão HTTP normal não é ideal para transmitir áudio em tempo real a um servidor enquanto recebe transcrições conforme elas são disponibilizadas. Nesta seção, você cria uma conexão WebSocket do cliente com o servidor e a usa para enviar os dados e metadados de áudio (ou seja, a taxa de amostragem) ao servidor, enquanto aguarda uma resposta (ou seja, a transcrição dos dados).

Transmissão de bytes de áudio

O exemplo fornecido muda o TranscribeServlet para estender WebSocketServlet e registrar um WebSocketAdapter. O WebSocketAdapter definido simplesmente recebe a mensagem e a envia de volta ao cliente.

No cliente, a amostra substitui o scriptNode da etapa anterior por outro que envia os dados a um soquete a ser definido mais tarde. Em seguida, ele cria uma conexão WebSocket segura com o servidor. Depois que o servidor e o microfone estiverem conectados, ele vai começar a detectar mensagens do servidor e enviar de volta a taxa de amostragem. Quando o servidor retorna a taxa de amostragem, o cliente substitui o listener pelo gerenciador de transcrição mais permanente e conecta o scriptNode para iniciar a transmissão de bytes de áudio ao servidor.

1. Navegue até o diretório que contém 03-websockets:

cd ~/speaking-with-a-webpage/03-websockets

2. Execute o aplicativo:

mvn clean jetty:run

3. Para acessar o web app em execução, procure o endereço IP externo na página "Instâncias de VM" do console do Cloud e direcione o navegador para https://<seu-ip-externo>:8443.

4. Pressione CTRL+C para interromper o servidor.

Tarefa 6: transformar voz em texto

A API de streaming Google Cloud Speech permite enviar bytes de áudio para a API em tempo real e receber de forma assíncrona transcrições de qualquer fala detectada. Essa API espera que os bytes estejam em um formato específico, conforme determinado pela configuração enviada no início de uma solicitação. Para esse web app, você envia as amostras de áudio bruto da API no formato LINEAR16. Ou seja, cada amostra é um número inteiro de 16 bits enviado na taxa de amostragem obtida pelo cliente.

Solução de exemplo

O subdiretório 04-speech do repositório speaking-with-a-webpage fornecido completa o código do servidor da etapa 03-websockets. Ele incorpora o código do exemplo StreamingRecognizeClient acima para se conectar à API Cloud Speech, transmitir bytes de áudio e receber transcrições dela. Quando recebe as transcrições de forma assíncrona, o servidor as repassa ao cliente JavaScript, que simplesmente as exibe na página da Web.

1. Inicie o aplicativo:

cd ~/speaking-with-a-webpage/04-speech mvn clean jetty:run

2. Para acessar o web app em execução, procure o endereço IP externo na página "Instâncias de VM" do console do Cloud e direcione o navegador para https://<your-external-ip>:8443.

Tarefa 7: testar seu conhecimento

Responda às perguntas de múltipla escolha a seguir para reforçar sua compreensão dos conceitos abordados neste laboratório. Use tudo o que você aprendeu até aqui.

Parabéns!

Você aprendeu a usar o gcloud para criar uma VM e iniciar um servlet Java para capturar áudio e transformá-lo em texto em uma página da Web.

Próximas etapas / Saiba mais

Pense em melhorias de software que você pode aproveitar:

• No momento, o app cliente apenas exibe o texto, mas pode ser usado de várias maneiras. Pense nele como mais uma interface do usuário. As palavras-chave podem invocar determinadas ações, e você pode integrar o texto a um mecanismo de conversa ou usá-lo para legendagem.
• Integre as transcrições à API Cloud Natural Language, que pode extrair estrutura de textos não estruturados.
• A API Cloud Speech é compatível com mais de 80 idiomas, que podem ser escolhidos com um simples parâmetro de configuração. Faça um teste com outro idioma que você fala ou está aprendendo.
• A configuração atual do projeto é adequada principalmente para fins de desenvolvimento e precisa ser alterada ao implantar em produção. Por exemplo, é possível usar várias instâncias do Compute Engine em um grupo de instâncias e o balanceador de carga SSL para fornecer comunicação segura entre o cliente e o servidor.

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 15 de setembro de 2025

Laboratório testado em 15 de setembro de 2025

Copyright 2025 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.