Guide d’utilisation de la transcription par lotsHow to use batch transcription

La transcription par lots est un ensemble d’opérations d’API REST qui vous permet de transcrire une grande quantité de données audio dans un stockage.Batch transcription is a set of REST API operations that enables you to transcribe a large amount of audio in storage. Vous pouvez pointer vers des fichiers audio à l’aide d’un URI type ou d’un URI de signature d’accès partagé (SAP) et recevoir les résultats de la transcription de manière asynchrone.You can point to audio files using a typical URI or a shared access signature (SAS) URI and asynchronously receive transcription results. L’API 3.0 vous permet de transcrire un ou plusieurs fichiers audio, ou de traiter un conteneur de stockage entier.With the v3.0 API, you can transcribe one or more audio files, or process a whole storage container.

Vous pouvez utiliser des API REST de transcription par lots pour appeler les méthodes suivantes :You can use batch transcription REST APIs to call the following methods:

Opération de transcription par lotsBatch Transcription Operation MéthodeMethod Appel d’API RESTREST API Call
Crée une transcription.Creates a new transcription. POSTPOST speechtotext/v3.0/transcriptionsspeechtotext/v3.0/transcriptions
Récupère une liste de transcriptions pour l’abonnement authentifié.Retrieves a list of transcriptions for the authenticated subscription. GETGET speechtotext/v3.0/transcriptionsspeechtotext/v3.0/transcriptions
Obtient la liste des paramètres régionaux pris en charge pour les transcriptions hors connexion.Gets a list of supported locales for offline transcriptions. GETGET speechtotext/v3.0/transcriptions/localesspeechtotext/v3.0/transcriptions/locales
Met à jour les détails mutables de la transcription identifiée par son ID.Updates the mutable details of the transcription identified by its ID. PATCHPATCH speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
Supprime la tâche de transcription spécifiée.Deletes the specified transcription task. SuppressionDELETE speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
Obtient la transcription identifiée par l’ID donné.Gets the transcription identified by the given ID. GETGET speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
Permet d'obtenir les fichiers de résultats de la transcription identifiés par l'ID donné.Gets the result files of the transcription identified by the given ID. GETGET speechtotext/v3.0/transcriptions/{id}/filesspeechtotext/v3.0/transcriptions/{id}/files

Vous pouvez examiner et tester l’API détaillée, disponible sous forme de document Swagger.You can review and test the detailed API, which is available as a Swagger document.

Les travaux de transcription par lots sont planifiés en faisant au mieux selon les circonstances.Batch transcription jobs are scheduled on a best effort basis. Vous ne pouvez pas estimer le moment où un travail passe à l’état d’exécution, mais cela doit intervenir sous quelques minutes en présence d’une charge système normale.You cannot estimate when a job will change into the running state, but it should happen within minutes under normal system load. Une fois en cours d’exécution, la transcription est plus rapide que la vitesse de lecture du runtime.Once in the running state, the transcription occurs faster than the audio runtime playback speed.

PrérequisPrerequisites

Comme pour toutes les fonctionnalités du service Speech, créez une clé d’abonnement à partir du Portail Azure en suivant les instructions du guide de démarrage rapide.As with all features of the Speech service, you create a subscription key from the Azure portal by following our Get started guide.

Notes

Pour pouvoir utiliser la transcription Batch, vous avez besoin d’un abonnement standard (S0) pour le service Speech.A standard subscription (S0) for Speech service is required to use batch transcription. Les clés d’abonnement gratuit (F0) ne fonctionnent pas.Free subscription keys (F0) will not work. Pour plus d’informations, voir Tarification et limites.For more information, see pricing and limits.

Si vous envisagez de personnaliser des modèles, suivez les étapes décrites dans les sections Personnalisation acoustique et Personnalisation de la langue.If you plan to customize models, follow the steps in Acoustic customization and Language customization. Pour utiliser les modèles créés dans la transcription de lot, vous avez besoin de l’emplacement du modèle.To use the created models in batch transcription, you need their model location. L’emplacement d’un modèle figure dans les détails associés (propriété self).You can retrieve the model location when you inspect the details of the model (self property). Il n’est pas nécessaire de déployer un point de terminaison personnalisé pour le service de transcription par lot.A deployed custom endpoint is not needed for the batch transcription service.

Notes

Dans le cadre de l’API REST, la transcription Batch comporte un ensemble de quotas et limites, que nous vous encourageons à examiner.As a part of the REST API, Batch Transcription has a set of quotas and limits, which we encourage to review. Pour tirer pleinement parti de la fonctionnalité de transcription Batch afin de transcrire efficacement un grand nombre de fichiers audio, nous vous recommandons d’envoyer toujours plusieurs fichiers par requête ou de pointer vers un conteneur Stockage Blob avec les fichiers audio à transcrire.To take the full advantage of Batch Transcription ability to efficiently transcribe a large number of audio files we recommend always sending multiple files per request or pointing to a Blob Storage container with the audio files to transcribe. Le service va transcrire les fichiers en réduisant par la même occasion le temps de bouclage.The service will transcribe the files concurrently reducing the turnaround time. L’utilisation de plusieurs fichiers dans une requête unique est très simple et directe : consultez la section Configuration.Using multiple files in a single request is very simple and straightforward - see Configuration section.

API de transcription BatchBatch transcription API

L’API de transcription Batch prend en charge les formats suivants :The batch transcription API supports the following formats:

FormatFormat CodecCodec Bits par échantillonBits Per Sample ÉchantillonnageSample Rate
WAVWAV PCMPCM 16 bits16-bit 8 kHz ou 16 kHz, mono ou stéréo8 kHz or 16 kHz, mono or stereo
MP3MP3 PCMPCM 16 bits16-bit 8 kHz ou 16 kHz, mono ou stéréo8 kHz or 16 kHz, mono or stereo
OGGOGG OPUSOPUS 16 bits16-bit 8 kHz ou 16 kHz, mono ou stéréo8 kHz or 16 kHz, mono or stereo

Dans le cas des flux audio stéréo, les canaux gauche et droit sont fractionnés lors de la transcription.For stereo audio streams, the left and right channels are split during the transcription. Un fichier de résultat JSON est créé pour chaque canal.A JSON result file is being created for each channel. Pour créer une transcription finale ordonnée chronologiquement, utilisez les timestamps générés par énoncé.To create an ordered final transcript, use the timestamps generated per utterance.

ConfigurationConfiguration

Les paramètres de configuration sont fournis au format JSON.Configuration parameters are provided as JSON.

Transcription d’un ou plusieurs fichiers individuels.Transcribing one or more individual files. Si vous avez plusieurs fichiers à transcrire, nous vous recommandons de les envoyer dans une seule requête.If you have more than one file to transcribe, we recommend sending multiple files in one request. L’exemple ci-dessous utilise trois fichiers :The example below is using three files:

{
  "contentUrls": [
    "<URL to an audio file 1 to transcribe>",
    "<URL to an audio file 2 to transcribe>",
    "<URL to an audio file 3 to transcribe>"
  ],
  "properties": {
    "wordLevelTimestampsEnabled": true
  },
  "locale": "en-US",
  "displayName": "Transcription of file using default model for en-US"
}

Traitement d’un conteneur de stockage entier :Processing a whole storage container:

{
  "contentContainerUrl": "<SAS URL to the Azure blob container to transcribe>",
  "properties": {
    "wordLevelTimestampsEnabled": true
  },
  "locale": "en-US",
  "displayName": "Transcription of container using default model for en-US"
}

Utilisez un modèle entraîné personnalisé dans une transcription Batch.Use a custom trained model in a batch transcription. L’exemple utilise trois fichiers :The example is using three files:

{
  "contentUrls": [
    "<URL to an audio file 1 to transcribe>",
    "<URL to an audio file 2 to transcribe>",
    "<URL to an audio file 3 to transcribe>"
  ],
  "properties": {
    "wordLevelTimestampsEnabled": true
  },
  "locale": "en-US",
  "model": {
    "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/models/{id}"
  },
  "displayName": "Transcription of file using default model for en-US"
}

Propriétés de configurationConfiguration properties

Utilisez les propriétés facultatives suivantes pour configurer la transcription :Use these optional properties to configure transcription:

ParamètreParameter

DescriptionDescription

profanityFilterMode

(Facultatif) La valeur par défaut est Masked.Optional, defaults to Masked. Spécifie comment traiter la vulgarité dans les résultats de la reconnaissance.Specifies how to handle profanity in recognition results. Les valeurs acceptées sont None pour désactiver le filtrage des termes vulgaires, Masked pour remplacer les termes vulgaires par des astérisques, Removed pour supprimer tous les termes vulgaires du résultat ou Tags pour ajouter des balises « termes vulgaires ».Accepted values are None to disable profanity filtering, Masked to replace profanity with asterisks, Removed to remove all profanity from the result, or Tags to add "profanity" tags.

punctuationMode

(Facultatif) La valeur par défaut est DictatedAndAutomatic.Optional, defaults to DictatedAndAutomatic. Spécifie comment traiter la ponctuation dans les résultats de la reconnaissance.Specifies how to handle punctuation in recognition results. Les valeurs acceptées sont None pour désactiver la ponctuation, Dictated pour indiquer une ponctuation explicite (parlée), Automatic pour permettre au décodeur de traiter la ponctuation ou DictatedAndAutomatic pour utiliser la ponctuation dictée et automatique.Accepted values are None to disable punctuation, Dictated to imply explicit (spoken) punctuation, Automatic to let the decoder deal with punctuation, or DictatedAndAutomatic to use dictated and automatic punctuation.

wordLevelTimestampsEnabled

(Facultatif) false par défaut.Optional, false by default. Spécifie si les timestamps au niveau des mots doivent être ajoutés à la sortie.Specifies if word level timestamps should be added to the output.

diarizationEnabled

(Facultatif) false par défaut.Optional, false by default. Spécifie que l’analyse de diarisation doit être effectuée sur l’entrée qui est censée être un canal unique contenant deux voix.Specifies that diarization analysis should be carried out on the input, which is expected to be mono channel containing two voices. Remarque : Requiert la définition de wordLevelTimestampsEnabled sur true.Note: Requires wordLevelTimestampsEnabled to be set to true.

channels

(Facultatif) 0 et 1 sont transcrits par défaut.Optional, 0 and 1 transcribed by default. Tableau de numéros de canaux à traiter.An array of channel numbers to process. Ici, vous pouvez spécifier un sous-ensemble des canaux disponibles dans le fichier audio (par exemple, 0 uniquement).Here a subset of the available channels in the audio file can be specified to be processed (for example 0 only).

timeToLive

(Facultatif) Pas de suppression par défaut.Optional, no deletion by default. Durée pour supprimer automatiquement les transcriptions terminées.A duration to automatically delete transcriptions after completing the transcription. Le paramètre timeToLive est utile pour le traitement en masse des transcriptions afin de s’assurer qu’elles seront effectivement supprimées (par exemple, PT12H pour 12 heures).The timeToLive is useful in mass processing transcriptions to ensure they will be eventually deleted (for example, PT12H for 12 hours).

destinationContainerUrl

URL facultative avec SAP ad hoc de service vers un conteneur accessible en écriture dans Azure.Optional URL with Service ad hoc SAS to a writeable container in Azure. Le résultat est stocké dans ce conteneur.The result is stored in this container. Les SAP avec stratégie d’accès stockée ne sont pas prises en charge.SAS with stored access policy are not supported. Si aucune URL n’est spécifiée, Microsoft stocke les résultats dans un conteneur de stockage géré par Microsoft.When not specified, Microsoft stores the results in a storage container managed by Microsoft. Lorsque la transcription est supprimée en appelant Supprimer la transcription, les données de résultats sont également supprimées.When the transcription is deleted by calling Delete transcription, the result data will also be deleted.

StockageStorage

La transcription Batch peut lire l’audio à partir d’un URI Internet visible par le public, et peut lire ou écrire des transcriptions à l’aide d’un URI SAS avec Stockage Blob Azure.Batch transcription can read audio from a public-visible internet URI, and can read audio or write transcriptions using a SAS URI with Azure Blob storage.

Résultat de la transcription BatchBatch transcription result

Pour chaque entrée audio, un fichier de résultat de transcription est créé.For each audio input, one transcription result file is created. L’opération Obtenir les fichiers de transcription renvoie une liste de fichiers de résultats pour cette transcription.The Get transcriptions files operation returns a list of result files for this transcription. Pour rechercher le fichier de transcription d’un fichier d’entrée spécifique, filtrez tous les fichiers retournés avec kind == Transcription et name == {originalInputName.suffix}.json.To find the transcription file for a specific input file, filter all returned files with kind == Transcription and name == {originalInputName.suffix}.json.

Le format de chaque fichier de résultats de transcription est le suivant :Each transcription result file has this format:

{
  "source": "...",                      // sas url of a given contentUrl or the path relative to the root of a given container
  "timestamp": "2020-06-16T09:30:21Z",  // creation time of the transcription, ISO 8601 encoded timestamp, combined date and time
  "durationInTicks": 41200000,          // total audio duration in ticks (1 tick is 100 nanoseconds)
  "duration": "PT4.12S",                // total audio duration, ISO 8601 encoded duration
  "combinedRecognizedPhrases": [        // concatenated results for simple access in single string for each channel
    {
      "channel": 0,                     // channel number of the concatenated results
      "lexical": "hello world",
      "itn": "hello world",
      "maskedITN": "hello world",
      "display": "Hello world."
    }
  ],
  "recognizedPhrases": [                // results for each phrase and each channel individually
    {
      "recognitionStatus": "Success",   // recognition state, e.g. "Success", "Failure"
      "channel": 0,                     // channel number of the result
      "offset": "PT0.07S",              // offset in audio of this phrase, ISO 8601 encoded duration 
      "duration": "PT1.59S",            // audio duration of this phrase, ISO 8601 encoded duration
      "offsetInTicks": 700000.0,        // offset in audio of this phrase in ticks (1 tick is 100 nanoseconds)
      "durationInTicks": 15900000.0,    // audio duration of this phrase in ticks (1 tick is 100 nanoseconds)
      
      // possible transcriptions of the current phrase with confidences
      "nBest": [
        {
          "confidence": 0.898652852,    // confidence value for the recognition of the whole phrase
          "speaker": 1,                 // if `diarizationEnabled` is `true`, this is the identified speaker (1 or 2), otherwise this property is not present
          "lexical": "hello world",
          "itn": "hello world",
          "maskedITN": "hello world",
          "display": "Hello world.",
          
          // if wordLevelTimestampsEnabled is `true`, there will be a result for each word of the phrase, otherwise this property is not present
          "words": [
            {
              "word": "hello",
              "offset": "PT0.09S",
              "duration": "PT0.48S",
              "offsetInTicks": 900000.0,
              "durationInTicks": 4800000.0,
              "confidence": 0.987572
            },
            {
              "word": "world",
              "offset": "PT0.59S",
              "duration": "PT0.16S",
              "offsetInTicks": 5900000.0,
              "durationInTicks": 1600000.0,
              "confidence": 0.906032
            }
          ]
        }
      ]    
    }
  ]
}

Le résultat contient les champs suivants :The result contains the following fields:

ChampField

ContenuContent

lexical

Les mots réels sont reconnus.The actual words recognized.

itn

Forme « normalisation du texte inversée » du texte reconnu.Inverse-text-normalized form of the recognized text. Abréviations (« Docteur Smith » en « Dr Smith »), numéros de téléphone, et d’autres transformations sont appliquées.Abbreviations ("doctor smith" to "dr smith"), phone numbers, and other transformations are applied.

maskedITN

Forme « normalisation du texte inversée » avec masquage des termes vulgaires appliqué.The ITN form with profanity masking applied.

display

Forme d’affichage du texte reconnu.The display form of the recognized text. Des signes de ponctuation et des majuscules ajoutés sont inclus.Added punctuation and capitalization are included.

Séparation des orateurs (diarisation)Speaker separation (diarization)

La diarisation est le processus de séparation des orateurs dans une partie de l’audio.Diarization is the process of separating speakers in a piece of audio. Le pipeline Batch prend en charge la diarisation et est capable de reconnaître deux orateurs dans les enregistrements sur canal mono.The batch pipeline supports diarization and is capable of recognizing two speakers on mono channel recordings. La fonctionnalité n’est pas disponible pour les enregistrements stéréo.The feature is not available on stereo recordings.

La sortie d’une transcription avec diarisation activée contient une entrée Speaker pour chaque expression transcrite.The output of transcription with diarization enabled contains a Speaker entry for each transcribed phrase. Si aucune diarisation n’est utilisée, la propriété Speaker n’est pas présente dans la sortie JSON.If diarization is not used, the Speaker property is not present in the JSON output. Nous prenons en charge deux voix pour la diarisation. Les orateurs sont identifiés en tant que 1 ou 2.For diarization we support two voices, so the speakers are identified as 1 or 2.

Pour demander la diarisation, définissez la propriété diarizationEnabled sur true comme le montre la requête HTTP ci-dessous.To request diarization, add set the diarizationEnabled property to true like the HTTP request shows below.

{
 "contentUrls": [
   "<URL to an audio file to transcribe>",
 ],
 "properties": {
   "diarizationEnabled": true,
   "wordLevelTimestampsEnabled": true,
   "punctuationMode": "DictatedAndAutomatic",
   "profanityFilterMode": "Masked"
 },
 "locale": "en-US",
 "displayName": "Transcription of file using default model for en-US"
}

Les timestamps au niveau du mot doivent être activés, comme l’indiquent les paramètres dans la requête ci-dessus.Word-level timestamps must be enabled as the parameters in the above request indicate.

Meilleures pratiquesBest practices

Le service de transcription Batch peut traiter un grand nombre de transcriptions envoyées.The batch transcription service can handle large number of submitted transcriptions. Vous pouvez interroger l’état de vos transcriptions avec Obtenir les transcriptions.You can query the status of your transcriptions with Get transcriptions. Appelez régulièrement Supprimer la transcription à partir du service une fois que vous avez récupéré les résultats.Call Delete transcription regularly from the service once you retrieved the results. Vous pouvez définir la propriété timeToLive pour garantir la suppression définitive des résultats.Alternatively set timeToLive property to ensure eventual deletion of the results.

Exemple de codeSample code

Des exemples complets sont disponibles dans le dépôt d’exemples GitHub à l’intérieur du sous-répertoire samples/batch.Complete samples are available in the GitHub sample repository inside the samples/batch subdirectory.

Mettez à jour l’exemple de code avec vos informations d’abonnement, la région du service, le pointage URI vers le fichier audio à transcrire et l’emplacement du modèle si vous utilisez un modèle personnalisé.Update the sample code with your subscription information, service region, URI pointing to the audio file to transcribe, and model location if you're using a custom model.

var newTranscription = new Transcription
{
    DisplayName = DisplayName, 
    Locale = Locale, 
    ContentUrls = new[] { RecordingsBlobUri },
    //ContentContainerUrl = ContentAzureBlobContainer,
    Model = CustomModel,
    Properties = new TranscriptionProperties
    {
        IsWordLevelTimestampsEnabled = true,
        TimeToLive = TimeSpan.FromDays(1)
    }
};

newTranscription = await client.PostTranscriptionAsync(newTranscription).ConfigureAwait(false);
Console.WriteLine($"Created transcription {newTranscription.Self}");

L’exemple de code configure le client et envoie la demande de transcription.The sample code sets up the client and submits the transcription request. Il demande ensuite des informations d’état et imprime les détails de la progression de la transcription.It then polls for the status information and print details about the transcription progress.

// get the status of our transcriptions periodically and log results
int completed = 0, running = 0, notStarted = 0;
while (completed < 1)
{
    completed = 0; running = 0; notStarted = 0;

    // get all transcriptions for the user
    paginatedTranscriptions = null;
    do
    {
        // <transcriptionstatus>
        if (paginatedTranscriptions == null)
        {
            paginatedTranscriptions = await client.GetTranscriptionsAsync().ConfigureAwait(false);
        }
        else
        {
            paginatedTranscriptions = await client.GetTranscriptionsAsync(paginatedTranscriptions.NextLink).ConfigureAwait(false);
        }

        // delete all pre-existing completed transcriptions. If transcriptions are still running or not started, they will not be deleted
        foreach (var transcription in paginatedTranscriptions.Values)
        {
            switch (transcription.Status)
            {
                case "Failed":
                case "Succeeded":
                    // we check to see if it was one of the transcriptions we created from this client.
                    if (!createdTranscriptions.Contains(transcription.Self))
                    {
                        // not created form here, continue
                        continue;
                    }

                    completed++;

                    // if the transcription was successful, check the results
                    if (transcription.Status == "Succeeded")
                    {
                        var paginatedfiles = await client.GetTranscriptionFilesAsync(transcription.Links.Files).ConfigureAwait(false);

                        var resultFile = paginatedfiles.Values.FirstOrDefault(f => f.Kind == ArtifactKind.Transcription);
                        var result = await client.GetTranscriptionResultAsync(new Uri(resultFile.Links.ContentUrl)).ConfigureAwait(false);
                        Console.WriteLine("Transcription succeeded. Results: ");
                        Console.WriteLine(JsonConvert.SerializeObject(result, SpeechJsonContractResolver.WriterSettings));
                    }
                    else
                    {
                        Console.WriteLine("Transcription failed. Status: {0}", transcription.Properties.Error.Message);
                    }

                    break;

                case "Running":
                    running++;
                    break;

                case "NotStarted":
                    notStarted++;
                    break;
            }
        }

        // for each transcription in the list we check the status
        Console.WriteLine(string.Format("Transcriptions status: {0} completed, {1} running, {2} not started yet", completed, running, notStarted));
    }
    while (paginatedTranscriptions.NextLink != null);

    // </transcriptionstatus>
    // check again after 1 minute
    await Task.Delay(TimeSpan.FromMinutes(1)).ConfigureAwait(false);
}

Pour plus d’informations sur les appels précédents, consultez notre document Swagger.For full details about the preceding calls, see our Swagger document. L’exemple complet présenté ici est disponible sur GitHub dans le sous-répertoire samples/batch.For the full sample shown here, go to GitHub in the samples/batch subdirectory.

Cet exemple utilise une configuration asynchrone pour publier des données audio et recevoir l’état de la transcription.This sample uses an asynchronous setup to post audio and receive transcription status. La méthode PostTranscriptions envoie les détails du fichier audio et la méthode GetTranscriptions reçoit les états.The PostTranscriptions method sends the audio file details and the GetTranscriptions method receives the states. PostTranscriptions renvoie un descripteur et GetTranscriptions l’utilise pour créer un descripteur permettant d’obtenir l’état de la transcription.PostTranscriptions returns a handle, and GetTranscriptions uses it to create a handle to get the transcription status.

Cet exemple de code ne spécifie pas de modèle personnalisé.This sample code doesn't specify a custom model. Le service utilise le modèle de base pour la transcription du ou des fichiers.The service uses the baseline model for transcribing the file or files. Pour spécifier le modèle, vous pouvez appliquer la même méthode de référence de modèle pour le modèle personnalisé.To specify the model, you can pass on the same method the model reference for the custom model.

Notes

Dans le cas des transcriptions de base, vous n’avez pas besoin de déclarer l’ID du modèle de base.For baseline transcriptions, you don't need to declare the ID for the baseline model.

Étapes suivantesNext steps