1. Présentation
Dans cet atelier de programmation, vous allez apprendre à envoyer un fichier audio via l'API Google Cloud Speech-to-Text, puis à générer la transcription dans un document Google. L'API Speech-to-Text est facile à utiliser et s'appuie sur de puissants réseaux de neurones pour permettre aux développeurs de transformer l'audio en texte. De plus, il s'appuie sur le machine learning.
Vous allez utiliser l'API Google Docs pour créer un document et y écrire des données. Vous allez créer une application de ligne de commande Java, exécuter votre code à l'aide du système de compilation Gradle, puis utiliser l'API Docs pour afficher les résultats.
Points abordés
- Utiliser l'API Google Cloud Speech-to-Text
- Comment utiliser l'API Google Docs pour créer un document
- Utiliser l'API Docs pour écrire dans un document
Prérequis
- Java installé (version 7 ou ultérieure)
- Gradle installé (version 5 ou ultérieure)
- Accès à Internet et à un navigateur Web
- Un compte Google
- Un projet Google Cloud Platform.
2. Configurer votre projet
Créer votre projet Cloud
- Connectez-vous à la console Cloud, puis créez un projet ou réutilisez un projet existant. (Si vous ne possédez pas encore de compte Gmail ou Workspace, vous devez en créer un.)
Mémorisez l'ID du projet. Il s'agit d'un nom unique permettant de différencier chaque projet Google Cloud (le nom ci-dessus est déjà pris ; vous devez en trouver un autre). Il sera désigné par le nom PROJECT_ID tout au long de cet atelier de programmation.
- Vous devez ensuite activer la facturation dans Cloud Console pour pouvoir utiliser les ressources Google Cloud.
L'exécution de cet atelier de programmation est très peu coûteuse, voire gratuite. Veillez à suivre les instructions de la section "Nettoyer" qui indique comment désactiver les ressources afin d'éviter les frais une fois ce tutoriel terminé. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300 $.
Obtenir une clé de compte de service pour l'API Cloud Speech-to-Text
- Accédez à la console GCP et recherchez votre nouveau projet.
- Créer un compte de service
- Télécharger une clé de compte de service au format JSON
- Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pour qu'elle pointe vers le chemin du fichier JSON contenant votre clé de compte de service. Si vous redémarrez votre session de shell, vous devrez définir à nouveau la variable.
$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Exemple :
$ export GOOGLE_APPLICATION_CREDENTIALS="/home/usr/downloads/ServiceAccount.json"
Obtenir des identifiants pour l'API Docs
- De retour dans la console GCP, accédez à Identifiants.
- Créer une clé OAuth 2.0 et la télécharger au format JSON
- Renommez le fichier
credentials.jsonet assurez-vous qu'il se trouve dans le répertoiresrc/main/resources/de votre code
Activer les API
- Sélectionnez l'onglet Dashboard (Tableau de bord), cliquez sur le bouton Enable APIs and Services (Activer les API et les services), puis activez les deux API suivantes:
- Reconnaissance vocale
- Google Docs
Vous êtes maintenant prêt à commencer à travailler avec votre code.
3. Configurer votre code
Obtenir l'exemple de code
Pour obtenir l'exemple de code, téléchargez le fichier ZIP sur votre ordinateur...
...ou cloner le dépôt GitHub depuis la ligne de commande.
$ git clone git@github.com:googleworkspace/docs-transcript-codelab.git
Vous allez travailler dans le fichier CreateTranscript.java situé dans le répertoire start. Les fichiers Gradle ne doivent pas être modifiés.
Dans votre répertoire, accédez au dossier start et ouvrez le fichier CreateTranscript.java. Faites défiler la page jusqu'à l'emplacement de la déclaration 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);
Pour votre variable SCOPES, vous avez spécifié que votre code peut afficher et gérer les documents Google Docs de vos utilisateurs. Si votre code nécessite une autorisation supérieure ou différente à cet accès, veillez à ajuster cette variable en conséquence, en fonction des champs d'application d'API Google OAuth 2.0.
Par exemple, si vous n'écrivez pas dans un document Google Docs, vous pouvez redéfinir le champ d'application sur DOCUMENTS_READONLY. La variable SCOPES est nécessaire non seulement pour que votre application dispose des autorisations d'accès appropriées, mais aussi pour assurer la transparence envers les utilisateurs. L'utilisateur voit les niveaux d'accès spécifiques que vous avez demandés sur la page de validation OAuth, où il doit autoriser l'utilisation de l'application.
Renommer les variables
Assurez-vous que les variables ci-dessus sont correctement déclarées pour votre projet.
- Assurez-vous que AUDIO_FILENAME est défini sur le nom du fichier de démonstration que vous envoyez à l'API Speech to Text. Il devrait déjà être correctement défini dans votre fichier CreateTranscript.java.
- Remplacez CREDENTIALS_FILE_PATH par le nom du fichier d'identifiants téléchargé (il doit être '/
credentials.json'). Assurez-vous que ce fichier se trouve dans le répertoiresrc/main/resourcesde votre dossier. Veillez donc à créer ce répertoire si le clonage GitHub ne le fait pas pour vous.
Vous pouvez maintenant commencer à exécuter votre code.
4. Initialiser un client Docs
Dans le fichier CreateTranscript.java, recherchez la déclaration de la méthode principale et examinez son contenu:
final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
Docs service = new Docs.Builder(HTTP_TRANSPORT, JSON_FACTORY,
getCredentials(HTTP_TRANSPORT))
.setApplicationName(APPLICATION_NAME)
.build();
Autorisation des fonctions
La première tâche que vous effectuez ici consiste à créer la variable Docs service. Le service représente un client API autorisé, qui détient vos identifiants et, dans ce cas, l'authentification de l'utilisateur final.
Dans votre code, toute fonction qui appelle l'API Docs doit utiliser cette variable service pour effectuer des tâches liées à Docs.
5. Créer un document Google
Vous allez créer un document Google avec un titre donné. Copions donc le code ci-dessous dans la fonction createDocument.
Document doc = new Document().setTitle("Transcript for " +
AUDIO_FILENAME);
doc = service.documents().create(doc).execute();
String documentId = doc.getDocumentId();
return documentId;
Cette fonction renvoie l'ID du fichier Drive du document Google Docs. Ce même identifiant se trouve dans l'URL du document.
Vous allez maintenant initialiser le client Speech-to-Text.
6. Appeler l'API Speech-to-Text
La prochaine tâche que vous souhaitez effectuer dans votre code consiste à obtenir la transcription écrite du fichier audio. Dans CreateTranscript.java, recherchez la fonction getTranscript().
Commencez par obtenir le chemin d'accès et les octets audio du fichier audio:
SpeechClient speech = SpeechClient.create();
Path path = Paths.get(AUDIO_FILENAME);
byte[] data = Files.readAllBytes(path);
ByteString audioBytes = ByteString.copyFrom(data);
Configurer la reconnaissance vocale
Vous devez ensuite initialiser correctement la variable RecognitionConfig.
Ici, config fournit des informations sur la façon exacte dont votre outil de reconnaissance vocale doit traiter votre requête. Vous devrez modifier setLanguageCode() si, par exemple, votre fichier audio est dans une autre langue que l'anglais, et setSampleRateHertz() si votre fichier audio présente un taux d'échantillonnage différent en Hertz (1 600 est la meilleure langue).
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();
Préparer le texte
Enfin, gérez la variable result de transcription du fichier audio et préparez-la pour l'insérer dans un document.
Chaque élément des résultats est une transcription de type SpeechRecognitionAlternatives. Ainsi, chaque élément contient deux parties: une transcription de texte et le score de confiance correspondant de l'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. Insérer du texte dans un document
Vous allez maintenant insérer le texte de la transcription dans le document Google Docs. Pour apporter des modifications à un document, vous devez utiliser la méthode BatchUpdate. BatchUpdate est un conteneur pour différents types de requêtes d'écriture. Ici, vous allez utiliser InsertTextRequest.
EndOfSegmentLocation est un paramètre important qui indique l'emplacement où vous souhaitez imprimer le texte dans votre document. Dans le code source, vous insérez du texte dans le corps de votre document.
Insérons le code ci-dessous dans votre fonction pour voir comment les résultats de l'API Speech-to-Text associés aux appels de l'API Docs peuvent nous permettre d'insérer la transcription d'un fichier audio dans un document Google Docs:
BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(docId,
body.setRequests(insertRequests)).execute();
Créer la requête
Lorsque vous effectuez la requête BatchUpdate, vous définissez deux spécifications très importantes: ce que vous souhaitez imprimer (.setText()) et où vous souhaitez le faire dans votre document (.setIndex(1)).
Vous venez d'insérer la transcription de votre fichier audio dans le document que vous avez créé.
8. Exécuter le code
Maintenant que vous disposez de tout le code nécessaire pour créer un fichier audio, obtenir sa transcription et l'imprimer dans un nouveau document Google Docs, mettons-nous en route !
Étant donné que vous allez exécuter votre code Java à l'aide du système de compilation Gradle, vous devez indiquer précisément au fichier build.gradle les éléments à compiler et à exécuter. Dans ce projet et dans d'autres, veillez à ce que mainClassName reste cohérent avec la classe Java que vous souhaitez exécuter.
Parfait ! Vous êtes maintenant prêt à exécuter votre code. Pour ce faire, saisissez la commande suivante dans votre ligne de commande:
$ gradle run
Authentification de l'utilisateur final
La première fois que vous exécutez ce code, une URL s'affiche dans le terminal. Elle vous invite à vous connecter à votre compte de service et à autoriser l'accès à ses documents Google Docs. Une fois l'accès autorisé, vous remarquerez un nouveau fichier stocké dans votre répertoire.
Dans votre répertoire de travail, vous verrez un nouveau dossier intitulé tokens, qui contient un fichier StoredCredential. Il s'agit du jeton d'authentification que vous venez de fournir, que votre client a demandé au serveur d'authentification Google, extrait de sa réponse, puis envoyé à toutes les API que vous appelez.
Solution
Si votre code ne fonctionne pas, consultez le fichier CreateTranscript.java à l'intérieur du dossier CreateTranscript.java. Ce fichier contient l'intégralité de votre code tel qu'il a besoin pour s'exécuter correctement.
Examinons maintenant le résultat.
9. Afficher les résultats
Vous venez de créer un document Google contenant la transcription de votre fichier audio. Examinons-le de plus près.
Ce document a été créé à l'aide du compte auquel l'utilisateur final a accordé son autorisation. Vous pouvez aussi partager automatiquement ce document avec d'autres utilisateurs à l'aide de l'API Drive.
À l'aide de votre code source et du fichier audio fourni, vous devriez obtenir le résultat suivant:
10. Félicitations !
Vous savez maintenant comment créer un document Google Docs, appeler l'API Speech-to-Text et importer la transcription de votre fichier audio dans le document que vous avez créé.
Améliorations possibles
Voici quelques idées pour créer une intégration plus attrayante:
- Configurez votre code pour écouter lorsqu'un fichier audio a été ajouté au Drive de votre bucket Google Cloud Storage et déclencher une fonction Google Cloud pour exécuter ce code
- Jouez avec l'insertion de texte non vide dans un document Google Docs
En savoir plus
- Lisez la documentation destinée aux développeurs sur l'API Google Docs.
- Publiez vos questions et trouvez des réponses sur Stack Overflow à l'aide du tag google-docs-api.