1. Panoramica
In questo codelab, imparerai a inviare un file audio tramite l'API Google Cloud Speech to Text e a eseguire l'output della trascrizione in un documento Google. L'API Speech to Text è facile da usare e applica potenti reti neurali per consentire agli sviluppatori di trasformare l'audio in testo. Inoltre, si basa sul machine learning.
Utilizzerai l'API Google Documenti per creare e scrivere in un nuovo documento. Dovrai creare un'applicazione a riga di comando Java ed eseguire il codice utilizzando il sistema di compilazione gradle, quindi utilizzare l'API Documenti per visualizzare i risultati.
Obiettivi didattici
- Come utilizzare l'API Google Cloud Speech to Text
- Come utilizzare l'API Google Documenti per creare un nuovo documento
- Come utilizzare l'API Documenti per scrivere in un documento
Che cosa ti serve
- Java installato (versione 7 o successiva)
- Gradle installato (versione 5 o successive)
- Accesso a internet e a un browser web
- Un Account Google
- Un progetto Google Cloud
2. Configura il progetto
Crea il tuo progetto cloud
- Accedi alla console Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Workspace, devi crearne uno.
Ricorda l'ID progetto, un nome univoco in tutti i progetti Google Cloud (il nome precedente è già stato utilizzato e non funzionerà correttamente). Verrà indicato più avanti in questo codelab come PROJECT_ID.
- Successivamente, dovrai abilitare la fatturazione in Cloud Console per utilizzare le risorse Google Cloud.
Eseguire questo codelab non dovrebbe costare molto. Assicurati di seguire le istruzioni nella sezione "Pulizia" in cui viene spiegato come arrestare le risorse in modo da non incorrere in fatturazione oltre questo tutorial. I nuovi utenti di Google Cloud sono idonei al programma prova senza costi di 300$.
Ottieni una chiave dell'account di servizio per l'API Cloud Speech-to-Text
- Vai alla console Google Cloud e trova il tuo nuovo progetto
- Crea un account di servizio
- Scarica una chiave dell'account di servizio in formato JSON
- Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio. Se riavvii la sessione shell, dovrai impostare di nuovo la variabile.
$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Ad esempio:
$ export GOOGLE_APPLICATION_CREDENTIALS="/home/usr/downloads/ServiceAccount.json"
Ottenere le credenziali per l'API Docs
- Torna alla console Google Cloud, vai a Credenziali
- Creare una chiave OAuth 2.0 e scaricarla come JSON
- Rinomina il file
credentials.jsone assicurati che si trovi nella directorysrc/main/resources/del codice
Abilita API
- Seleziona la scheda Dashboard, fai clic sul pulsante Abilita API e servizi e abilita le due API seguenti:
- Conversione della voce in testo
- Documenti Google
Ora è tutto pronto per iniziare a utilizzare il codice.
3. Configura il codice
recupera il codice campione
Per ottenere il codice di esempio, scarica il file ZIP sul tuo computer...
...o clona il repository GitHub dalla riga di comando.
$ git clone git@github.com:googleworkspace/docs-transcript-codelab.git
Lavorerai sul file CreateTranscript.java all'interno della directory start. I file Gradle non devono essere modificati.
Nella directory, vai alla cartella start e apri il file CreateTrascrizione.java. Scorri verso il basso fino a dove vedi la dichiarazione del corso 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);
Per la variabile SCOPES, hai specificato che il codice sarà in grado di visualizzare e gestire i documenti di Documenti Google dell'utente. Se il tuo codice richiede un'autorizzazione oltre o diversa da questo accesso, assicurati di modificare questa variabile di conseguenza in base agli ambiti delle API di Google OAuth 2.0.
Ad esempio, se non stavi scrivendo un documento Google, puoi modificare l'ambito in DOCUMENTS_READONLY. La variabile SCOPES è necessaria non solo per garantire alla tua app le autorizzazioni di accesso appropriate, ma anche per garantire la trasparenza nei confronti degli utenti. L'utente visualizza gli ambiti specifici da te richiesti nella pagina di verifica OAuth, in cui deve acconsentire all'utilizzo dell'app.
Rinomina variabili
Assicurati che le variabili sopra indicate siano dichiarate correttamente per il tuo progetto.
- Assicurati che AUDIO_FILENAME sia impostato sul nome del file demo che stai inviando all'API Speech to Text. Nel file CreateTranscript.java, dovresti già vedere che è impostato correttamente.
- Rinomina CREDENTIALS_FILE_PATH con il nome del file delle credenziali scaricato (deve essere "/
credentials.json'). Assicurati che il file si trovi nella directorysrc/main/resourcesdella cartella, quindi assicurati di creare questa directory se la clonazione di GitHub non risolve il problema.
Ora puoi iniziare a eseguire il tuo codice.
4. Inizializzare un client Documenti
Nel file CreateTranscript.java, trova la dichiarazione principale del metodo e dai un'occhiata a cosa contiene:
final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
Docs service = new Docs.Builder(HTTP_TRANSPORT, JSON_FACTORY,
getCredentials(HTTP_TRANSPORT))
.setApplicationName(APPLICATION_NAME)
.build();
Autorizzazione funzione
La prima attività da eseguire qui è la creazione della variabile Docs service. Il servizio rappresenta un client API autorizzato, che contiene le tue credenziali e, in questo caso, l'autenticazione dell'utente finale.
Nel codice, qualsiasi funzione che effettui una chiamata all'API Documenti dovrà utilizzare questa variabile service per eseguire attività relative a Documenti.
5. Creazione di un documento Google
Creerai un nuovo documento Google con un titolo specificato. Copia quindi il codice seguente nella funzione createDocument.
Document doc = new Document().setTitle("Transcript for " +
AUDIO_FILENAME);
doc = service.documents().create(doc).execute();
String documentId = doc.getDocumentId();
return documentId;
Questa funzione restituisce l'ID file di Drive del documento Google. Lo stesso ID è disponibile nell'URL del documento.
Successivamente, inizializza il client Speech-to-Text.
6. chiama l'API Speech to Text
L'attività successiva da eseguire nel codice è acquisire la trascrizione scritta del file audio. All'interno di CreateTranscript.java, trova la funzione getTranscript().
Innanzitutto, ottieni il percorso e i byte audio del file audio:
SpeechClient speech = SpeechClient.create();
Path path = Paths.get(AUDIO_FILENAME);
byte[] data = Files.readAllBytes(path);
ByteString audioBytes = ByteString.copyFrom(data);
Configura riconoscimento vocale
A questo punto, devi inizializzare correttamente la variabile RecognitionConfig.
Qui, config fornisce informazioni su come il tuo riconoscimento vocale deve elaborare esattamente la tua richiesta. Dovrai modificare setLanguageCode() se, ad esempio, il file audio è in una lingua diversa dall'inglese e modificare setSampleRateHertz() se il file audio ha una frequenza di campionamento diversa in Hertz (1600 è l'ideale).
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();
Preparazione del testo
Infine, gestisci la variabile result della trascrizione del file audio e preparala per l'inserimento in un documento.
Ogni elemento nei risultati è una trascrizione di tipo SpeechRecognitionAlternatives. Pertanto, ogni elemento contiene due parti: una trascrizione di testo e il punteggio di confidenza corrispondente dell'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. Inserire testo in un documento
Adesso inserirai il testo della trascrizione nel documento Google. Per apportare modifiche a un documento, devi utilizzare il metodo BatchUpdate. BatchUpdate è un container per diversi tipi di richieste di scrittura e, in questo caso, utilizzerai InsertTextRequest.
EndOfSegmentLocation è un parametro importante che specifica in quale punto del documento desideri stampare il testo. Nel codice sorgente, inserisci testo nel corpo del documento.
Inseriamo il codice seguente nella funzione per vedere in che modo i risultati dell'API Speech-to-Text, associati alle chiamate all'API Documenti, possono consentirci di inserire la trascrizione di un file audio in un documento Google:
BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(docId,
body.setRequests(insertRequests)).execute();
Creazione della richiesta in corso...
Quando effettui la richiesta BatchUpdate, devi impostare due specifiche molto importanti: ciò che vuoi stampare (.setText()) e la posizione del documento in cui vuoi farlo (.setIndex(1)).
Hai inserito la trascrizione del file audio nel documento creato.
8. Esecuzione del codice
Ora che hai tutto il codice necessario per prendere un file audio, ottenerne la trascrizione e stamparne la trascrizione in un documento Google appena creato, riproduciamo il programma.
Poiché eseguirai il codice Java utilizzando il sistema di compilazione gradle, devi indicare al file build.gradle cosa esattamente creare ed eseguire. In questo e in altri progetti, assicurati di mantenere mainClassName coerente con la classe Java che vuoi eseguire.
Bene. Ora è tutto pronto per eseguire il codice. Per farlo, digita quanto segue nella riga di comando:
$ gradle run
Autenticazione dell'utente finale
La prima volta che esegui questo codice, vedrai un URL stampato nel terminale, che ti chiede di accedere al tuo account di servizio e autorizzare l'accesso ai relativi documenti Google. Dopo aver consentito l'accesso, noterai un nuovo file archiviato nella tua directory.
All'interno della directory di lavoro, vedrai una cartella appena creata, denominata tokens, contenente un file StoredCredential. Si tratta del token di autenticazione appena fornito, che il client ha richiesto dal server di autenticazione Google, estratto dalla sua risposta e che ora invierà a qualsiasi API che chiami.
Soluzione
Se il codice non funziona, dai un'occhiata al file CreateTranscript.java nella cartella CreateTranscript.java. Questo file contiene tutto il codice esattamente come deve essere per essere eseguito correttamente.
Ora diamo un'occhiata al risultato.
9. Visualizzazione dei risultati
Hai appena creato un nuovo documento Google contenente la trascrizione del file audio, perciò diamo un'occhiata.
Questo documento è stato creato tramite l'account con cui l'utente finale ha fornito l'autorizzazione. Una possibile espansione è che puoi condividere automaticamente questo documento con altri utenti utilizzando l'API Drive.
Utilizzando il codice sorgente e il file audio fornito, dovresti vedere quanto segue:
10. Complimenti!
Ora hai imparato come creare un documento Google, effettuare una chiamata all'API Speech-to-Text e generare la trascrizione del file audio nel documento creato.
Possibili miglioramenti
Ecco alcune idee su come realizzare un'integrazione più convincente:
- Configura il codice da ascoltare quando un file audio viene aggiunto all'unità Drive del bucket Google Cloud Storage e attiva una funzione Google Cloud Functions per eseguire il codice
- Sperimenta l'inserimento di testo in un documento Google non vuoto
Scopri di più
- Leggi la documentazione per gli sviluppatori relativa all'API Google Docs
- Pubblica domande e trova risposte su Stack Overflow utilizzando il tag google-docs-api