1. Panoramica
In questo codelab imparerai a inviare un file audio tramite l'API Google Cloud Speech to Text, quindi a generare 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 convertire l'audio in testo. Inoltre, sfrutta la tecnologia del machine learning.
Utilizzerai l'API Google Docs per creare e scrivere in un nuovo documento. Creerai un'applicazione a riga di comando Java ed eseguirai il codice utilizzando il sistema di build Gradle, quindi utilizzerai l'API Docs per visualizzare i risultati.
Obiettivi didattici
- Come utilizzare l'API Google Cloud Speech to Text
- Come utilizzare l'API Google Docs per creare un nuovo documento
- Come utilizzare l'API Docs per scrivere in un documento
Che cosa ti serve
- Java installato (versione 7 o successive)
- 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 progetto cloud
- Accedi alla console Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già un account Gmail o Workspace, devi crearne uno.
Ricorda l'ID progetto, un nome univoco tra tutti i progetti Google Cloud (il nome sopra è già stato utilizzato e non funzionerà per te, mi dispiace). In questo codelab verrà chiamato PROJECT_ID.
- Successivamente, dovrai abilitare la fatturazione in Cloud Console per utilizzare le risorse Google Cloud.
L'esecuzione di questo codelab non dovrebbe costare molto, se non nulla. Assicurati di seguire le istruzioni riportate nella sezione "Pulizia", che ti consiglia come arrestare le risorse in modo da non incorrere in addebiti oltre questo tutorial. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.
Ottenere una chiave del service account per l'API Cloud Speech-to-Text
- Vai alla console GCP e trova il tuo nuovo progetto.
- Crea un account di servizio
- Scaricare una chiave del service account come JSON
- Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave del service account. Se riavvii la sessione della 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
- Nella console GCP, vai a Credenziali.
- Crea una chiave OAuth 2.0 e scaricala in formato 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 seguenti due API:
- Speech to Text
- Documenti Google
Ora puoi iniziare a lavorare con il tuo codice.
3. Configurare il codice
recupera il codice campione
Per ottenere il codice campione, scarica il file ZIP sul computer…
...o clona il repository GitHub dalla riga di comando.
$ git clone git@github.com:googleworkspace/docs-transcript-codelab.git
Lavorerai nel 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 CreateTranscript.java. Scorri verso il basso fino a visualizzare la dichiarazione della 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);
Per la variabile SCOPES, hai specificato che il tuo codice potrà visualizzare e gestire i documenti Google Docs dell'utente. Se il tuo codice richiede un'autorizzazione diversa o superiore a questo accesso, assicurati di modificare questa variabile di conseguenza in base agli ambiti OAuth 2.0 delle API di Google.
Ad esempio, se non stai scrivendo in un documento Google, puoi modificare l'ambito in DOCUMENTS_READONLY. La variabile SCOPES è necessaria non solo per consentire alla tua app di disporre delle autorizzazioni di accesso corrette, ma anche per mantenere la trasparenza con gli utenti. All'utente vengono mostrati gli ambiti specifici che richiedi 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 invii all'API Speech-to-Text. Nel file CreateTranscript.java, dovresti già visualizzarlo impostato correttamente.
- Rinomina CREDENTIALS_FILE_PATH con il nome del file delle credenziali scaricato (deve essere "/
credentials.json'). Assicurati che questo file si trovi nella directorysrc/main/resourcesdella cartella, quindi crea questa directory se la clonazione di GitHub non lo fa per te.
Ora puoi iniziare a eseguire il codice.
4. Inizializzare un client Documenti
Nel file CreateTranscript.java, trova la dichiarazione del metodo principale e dai un'occhiata al suo interno:
final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
Docs service = new Docs.Builder(HTTP_TRANSPORT, JSON_FACTORY,
getCredentials(HTTP_TRANSPORT))
.setApplicationName(APPLICATION_NAME)
.build();
Autorizzazione di funzione
La prima attività che esegui qui è la creazione di Docs service (variabile). Il servizio rappresenta un client API autorizzato, che contiene le tue credenziali e, in questo caso, l'autenticazione dell'utente finale.
Nel tuo codice, qualsiasi funzione che effettua una chiamata all'API Docs dovrà utilizzare questa variabile service per eseguire attività correlate a Docs.
5. Creare un documento Google
Verrà creato un nuovo documento Google con un titolo specificato. Quindi, copia il codice riportato di seguito 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 può essere trovato nell'URL del documento.
Successivamente, inizializzerai il client Speech-to-Text.
6. Chiama l'API Speech-to-Text
L'attività successiva che vuoi eseguire nel codice è ottenere 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);
Configurare il riconoscimento vocale
Successivamente, devi inizializzare correttamente la variabile RecognitionConfig.
Qui, config fornisce informazioni su come esattamente il sistema di riconoscimento vocale deve elaborare la tua richiesta. Dovrai modificare setLanguageCode() se, ad esempio, il file audio è in una lingua diversa dall'inglese e setSampleRateHertz() se il file audio ha una frequenza di campionamento diversa in Hertz (1600 è ottimale).
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 è composto da 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
Ora il testo della trascrizione verrà inserito nel documento Google. Per apportare modifiche a un documento, devi utilizzare il metodo BatchUpdate. BatchUpdate è un contenitore per diversi tipi di richieste di scrittura e qui utilizzerai InsertTextRequest.
EndOfSegmentLocation è un parametro importante che specifica in quale punto del documento vuoi stampare il testo. Nel codice sorgente, inserisci il testo nel corpo del documento.
Inseriamo il codice riportato di seguito nella tua funzione per vedere come i risultati dell'API Speech-to-Text, combinati con le chiamate all'API Docs, 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
Quando effettui la richiesta BatchUpdate, imposti due specifiche molto importanti: cosa vuoi stampare (.setText()) e in quale punto del documento vuoi farlo (.setIndex(1)).
Ora 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, ottenere la relativa trascrizione e stamparla in un documento Google appena creato, possiamo iniziare.
Poiché eseguirai il codice Java utilizzando il sistema di build Gradle, devi indicare al file build.gradle cosa compilare ed eseguire esattamente. In questo progetto e in altri, assicurati che mainClassName sia coerente con la classe Java che vuoi eseguire.
Bene. Ora puoi eseguire il codice. Per farlo, digita quanto segue nella riga di comando:
$ gradle run
Autenticazione degli utenti finali
La prima volta che esegui questo codice, nel terminale viene stampato un URL che ti chiede di accedere al tuo account di servizio e autorizzare l'accesso ai suoi documenti Google. Dopo aver consentito l'accesso, noterai un nuovo file memorizzato nella tua directory.
All'interno della directory di lavoro, vedrai una cartella appena creata denominata tokens, che contiene un file StoredCredential. Questo è il token di autenticazione che hai appena fornito, che il tuo client ha richiesto al server di autenticazione di 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 all'interno della cartella finish. Questo file contiene tutto il codice esattamente come deve essere per essere eseguito correttamente.
Ora vediamo il risultato.
9. Visualizzare i risultati
Hai appena creato un nuovo documento Google contenente la trascrizione del file audio, quindi 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 utilizzando l'API Drive.
Utilizzando il codice sorgente e il file audio fornito, ecco cosa dovresti vedere:
10. Complimenti!
Ora hai imparato a creare un documento Google, a effettuare una chiamata all'API Speech-to-Text e a inserire la trascrizione del file audio nel documento creato.
Possibili miglioramenti
Ecco alcuni suggerimenti su come creare un'integrazione più coinvolgente:
- Configura il codice in modo che ascolti quando un file audio è stato aggiunto al bucket Google Cloud Storage Drive e attiva una funzione Google Cloud per eseguire questo codice
- Prova a inserire del testo in un documento Google non vuoto
Scopri di più
- Leggi la documentazione per gli sviluppatori dell'API Google Docs.
- Pubblica domande e trova risposte su Stack Overflow utilizzando il tag google-docs-api.