バッチ文字起こしの使用方法How to use batch transcription

バッチ文字起こしは、ストレージ内の大量のオーディオを文字起こしできる一連の REST API 操作です。Batch transcription is a set of REST API operations that enables you to transcribe a large amount of audio in storage. 一般的な URI または Shared Access Signatures (SAS) URI を使用してオーディオ ファイルを示し、非同期に文字起こしの結果を受け取ることができます。You can point to audio files using a typical URI or a shared access signature (SAS) URI and asynchronously receive transcription results. v3.0 API では、1 つ以上のオーディオ ファイルを文字起こしするか、またはストレージ コンテナー全体を処理することがきます。With the v3.0 API, you can transcribe one or more audio files, or process a whole storage container.

バッチ文字起こし REST API を使用すると、次のメソッドを呼び出すことができます。You can use batch transcription REST APIs to call the following methods:

バッチ文字起こし操作Batch Transcription Operation MethodMethod REST API の呼び出しREST API Call
新しい文字起こしを作成する。Creates a new transcription. POSTPOST speechtotext/v3.0/transcriptionsspeechtotext/v3.0/transcriptions
認証されたサブスクリプションに対する文字起こしのリストを取得する。Retrieves a list of transcriptions for the authenticated subscription. GETGET speechtotext/v3.0/transcriptionsspeechtotext/v3.0/transcriptions
オフライン文字起こしでサポートされているロケールの一覧を取得する。Gets a list of supported locales for offline transcriptions. GETGET speechtotext/v3.0/transcriptions/localesspeechtotext/v3.0/transcriptions/locales
ID によって示された文字起こしの変更可能な詳細を更新する。Updates the mutable details of the transcription identified by its ID. PATCHPATCH speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
指定した文字起こしタスクを削除する。Deletes the specified transcription task. DELETEDELETE speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
指定した ID によって示される文字起こしを取得する。Gets the transcription identified by the given ID. GETGET speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
指定された ID で識別された文字起こしの結果ファイルを取得します。Gets the result files of the transcription identified by the given ID. GETGET speechtotext/v3.0/transcriptions/{id}/filesspeechtotext/v3.0/transcriptions/{id}/files

詳細な API を確認してテストできます。これは、Swagger ドキュメントで入手できます。You can review and test the detailed API, which is available as a Swagger document.

この API にはカスタム エンドポイントは必要ありません。また、同時実行要件はありません。This API does not require custom endpoints, and has no concurrency requirements.

バッチ文字起こしジョブは、ベスト エフォート ベースでスケジュールされます。Batch transcription jobs are scheduled on a best effort basis. ジョブが実行状態になるタイミングを見積もることはできませんが、通常のシステム負荷では数分以内に発生します。You cannot estimate when a job will change into the running state, but it should happen within minutes under normal system load. いったん実行状態になると、文字起こしはオーディオのランタイム再生速度よりも速く発生します。Once in the running state, the transcription occurs faster than the audio runtime playback speed.

前提条件Prerequisites

Speech Service の他の機能と同様に、使用開始ガイドに従って Azure portal でサブスクリプション キーを作成します。As with all features of the Speech service, you create a subscription key from the Azure portal by following our Get started guide.

注意

バッチ文字起こしを使用するには、音声サービスの Standard サブスクリプション (S0) が必要です。A standard subscription (S0) for Speech service is required to use batch transcription. Free サブスクリプション キー (F0) は機能しません。Free subscription keys (F0) don't work. 詳細については、価格と制限に関するページを参照してください。For more information, see pricing and limits.

モデルをカスタマイズする予定がある場合は、音響のカスタマイズ言語のカスタマイズの手順に従ってください。If you plan to customize models, follow the steps in Acoustic customization and Language customization. 作成されたモデルをバッチ文字起こしで使用するには、モデルの場所が必要です。To use the created models in batch transcription, you need their model location. モデルの詳細 (self プロパティ) を調べると、モデルの場所を取得できます。You can retrieve the model location when you inspect the details of the model (self property). デプロイされたカスタム エンドポイントは、バッチ文字起こしサービスには "必要ありません"。A deployed custom endpoint is not needed for the batch transcription service.

バッチ文字起こし APIBatch transcription API

バッチ文字起こし API では、次の形式がサポートされています。The batch transcription API supports the following formats:

FormatFormat コーデックCodec サンプルごとのビット数Bits Per Sample サンプル レートSample Rate
WAVWAV PCM 0PCM 16 ビット16-bit 8 kHz または 16 kHz、モノラルまたはステレオ8 kHz or 16 kHz, mono or stereo
MP3MP3 PCM 0PCM 16 ビット16-bit 8 kHz または 16 kHz、モノラルまたはステレオ8 kHz or 16 kHz, mono or stereo
OGGOGG OPUSOPUS 16 ビット16-bit 8 kHz または 16 kHz、モノラルまたはステレオ8 kHz or 16 kHz, mono or stereo

ステレオ オーディオ ストリームの場合、文字起こし中に左チャンネルと右チャンネルが分離されます。For stereo audio streams, the left and right channels are split during the transcription. JSON 結果ファイルが各チャネルに対して作成されます。A JSON result file is being created for each channel. 時間順の最終的なトランスクリプトを作成するには、発話ごとに生成されたタイムスタンプを使用します。To create an ordered final transcript, use the timestamps generated per utterance.

構成Configuration

構成パラメーターは JSON (1 つ以上の個別ファイル) として指定されています。Configuration parameters are provided as JSON (one or more individual files):

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

構成パラメーターは JSON (ストレージ コンテナー全体の処理) として指定されています。Configuration parameters are provided as JSON (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"
}

次の JSON では、バッチ文字起こしで使用するカスタムのトレーニング済みモデルが指定されています。The following JSON specifies a custom trained model to use in a batch transcription:

{
  "contentUrls": [
    "<URL to an audio file 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"
}

構成プロパティConfiguration properties

次の省略可能なプロパティを使用して、文字起こしを構成します。Use these optional properties to configure transcription:

パラメーターParameter

説明Description

profanityFilterMode

省略可能、既定値は Masked です。Optional, defaults to Masked. 認識結果内の不適切な表現をどう扱うかを指定します。Specifies how to handle profanity in recognition results. 指定できる値は、None (不適切な表現のフィルターを無効にする)、Masked (不適切な表現をアスタリスクに置き換える)、Removed (すべての不適切な表現を結果から除去する)、または Tags ("profanity" (不適切な表現) のタグを追加する) です。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

省略可能、既定値は DictatedAndAutomatic です。Optional, defaults to DictatedAndAutomatic. 認識結果内の句読点をどう扱うかを指定します。Specifies how to handle punctuation in recognition results. 指定できる値は、None (句読点を無効にする)、Dictated (明示的な (音声指示の) 句読点を暗黙指定する)、Automatic (デコーダーで句読点を処理する)、または DictatedAndAutomatic (口述指示および自動の句読点を使用する) です。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

省略可能、既定値は false です。Optional, false by default. 単語レベルのタイムスタンプを出力に追加するかどうかを指定します。Specifies if word level timestamps should be added to the output.

diarizationEnabled

省略可能、既定値は false です。Optional, false by default. 2 つの音声を含むモノラル チャネルであることが予測される入力に対してダイアライゼーション分析を実行する必要があることを指定します。Specifies that diarization analysis should be carried out on the input, which is expected to be mono channel containing two voices. 注:wordLevelTimestampsEnabledtrue に設定する必要があります。Note: Requires wordLevelTimestampsEnabled to be set to true.

channels

省略可能、既定では 01 が文字起こしされます。Optional, 0 and 1 transcribed by default. 処理するチャネル番号の配列。An array of channel numbers to process. ここでは、オーディオ ファイルで使用できるチャネルのサブセットを処理するように指定できます (例: 0 のみ)。Here a subset of the available channels in the audio file can be specified to be processed (e.g. 0 only).

timeToLive

省略可能、既定では削除は行われません。Optional, no deletion by default. 文字起こしの完了後に、文字起こしを自動的に削除する期間。A duration to automatically delete transcriptions after completing the transcription. timeToLive は、大量の文字起こしを最終的に確実に削除されるように処理するのに役立ちます (例: 12 時間の場合は PT12H)。The timeToLive is useful in mass processing transcriptions to ensure they will be eventually deleted (e.g. PT12H for 12 hours).

destinationContainerUrl

Azure の書き込み可能なコンテナーに対するサービス アドホック SAS のオプションの URL。Optional URL with Service ad hoc SAS to a writeable container in Azure. 結果はこのコンテナーに格納されます。The result is stored in this container. 保存されているアクセス ポリシーによる SAS はサポートされていませんSAS with stored access policy are not supported. 指定しない場合、Microsoft では、Microsoft が管理するストレージ コンテナーに結果を格納します。When not specified, Microsoft stores the results in a storage container managed by Microsoft. 文字起こしの削除を呼び出して文字起こしを削除すると、結果データも削除されます。When the transcription is deleted by calling Delete transcription, the result data will also be deleted.

ストレージStorage

バッチ文字起こしでは、公開されているインターネット URI からオーディオを読み取ることができます、また、Azure Blob Storage で SAS URI を使用してオーディオを読み取ったり、文字起こしを書き込んだりできます。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.

バッチ文字起こしの結果Batch transcription result

オーディオ入力ごとに、1 つの文字起こし結果ファイルが作成されます。For each audio input, one transcription result file is created. 文字起こしファイルの取得操作から、この文字起こしの結果ファイルの一覧が返されます。The Get transcriptions files operation returns a list of result files for this transcription. 特定の入力ファイルの文字起こしファイルを見つけるには、kind == Transcription および 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.

各文字起こし結果ファイルの形式は次のとおりです。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
            }
          ]
        }
      ]    
    }
  ]
}

結果には次のフィールドが含まれます。The result contains the following fields:

フィールドField

コンテンツContent

lexical

実際に認識された単語。The actual words recognized.

itn

認識されたテキストの逆テキスト正規化形式。Inverse-text-normalized form of the recognized text. 略語 ("doctor smith" から "dr smith")、電話番号、およびその他の変換が適用されます。Abbreviations ("doctor smith" to "dr smith"), phone numbers, and other transformations are applied.

maskedITN

不適切表現のマスキングを適用した ITN 形式。The ITN form with profanity masking applied.

display

認識されたテキストの表示形式。The display form of the recognized text. 追加された句読点と大文字化が含まれます。Added punctuation and capitalization are included.

話者の分離 (ダイアライゼーション)Speaker separation (diarization)

ダイアライゼーションは、音声に含まれる話者を分離するプロセスです。Diarization is the process of separating speakers in a piece of audio. ダイアライゼーションはバッチ パイプラインによってサポートされ、モノラル チャンネル レコーディングの 2 人の話者を認識できます。The batch pipeline supports diarization and is capable of recognizing two speakers on mono channel recordings. この機能は、ステレオ録音では使用できません。The feature is not available on stereo recordings.

ダイアライゼーションを有効にした文字起こしの出力には、文字起こしされたフレーズごとに Speaker エントリが含まれます。The output of transcription with diarization enabled contains a Speaker entry for each transcribed phrase. ダイアライゼーションが使用されない場合、Speaker プロパティは JSON 出力に存在しません。If diarization is not used, the Speaker property is not present in the JSON output. ダイアライゼーションでは 2 つの音声がサポートされるため、話者は 1 または 2 として識別されます。For diarization we support two voices, so the speakers are identified as 1 or 2.

ダイアライゼーションを要求するには、次に示す HTTP 要求のように、diarizationEnabled プロパティを追加して true に設定します。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"
}

上記の要求のパラメーターが示すように、ワードレベルのタイムスタンプを有効にする必要があります。Word-level timestamps must be enabled as the parameters in the above request indicate.

ベスト プラクティスBest practices

バッチ文字起こしサービスは、送信された多数の文字起こしを処理できます。The batch transcription service can handle large number of submitted transcriptions. 文字起こしの取得を実行して、文字起こしの状態を照会できます。You can query the status of your transcriptions with Get transcriptions. 結果を取得した後は、サービスから定期的に文字起こしの削除を呼び出します。Call Delete transcription regularly from the service once you retrieved the results. または、timeToLive プロパティを設定して、確実に結果が最終的に削除されるようにします。Alternatively set timeToLive property to ensure eventual deletion of the results.

サンプル コードSample code

完全なサンプルは、GitHub サンプル リポジトリsamples/batch サブディレクトリにあります。Complete samples are available in the GitHub sample repository inside the samples/batch subdirectory.

カスタム モデルを使用している場合は、サブスクリプション情報、サービス リージョン、文字起こしするオーディオ ファイルを指す URI、モデルの場所を使用してサンプル コードを更新します。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}");

サンプル コードでは、クライアントが設定されて、文字起こし要求が送信されます。The sample code sets up the client and submits the transcription request. その後、状態情報がポーリングされて、文字起こしの進行状況に関する詳細が表示されます。It then polls for the status information and print details about the transcription progress.

    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);

前の呼び出しに関する詳細については、Swagger ドキュメントを参照してください。For full details about the preceding calls, see our Swagger document. ここに示すすべてのサンプルについては、GitHubsamples/batch サブディレクトリにアクセスしてください。For the full sample shown here, go to GitHub in the samples/batch subdirectory.

このサンプルでは、非同期セットアップの使用により、オーディオをポストして文字起こしの状態を受け取っています。This sample uses a asynchronous setup to post audio and receive transcription status. PostTranscriptions メソッドによってオーディオ ファイルの詳細を送信し、GetTranscriptions メソッドによって状態を受け取ります。The PostTranscriptions method sends the audio file details and the GetTranscriptions method receives the states. PostTranscriptions はハンドルを返し、GetTranscriptions はそのハンドルを使用して文字起こしの状態を取得するためのハンドルを作成します。PostTranscriptions returns a handle, and GetTranscriptions uses it to create a handle to get the transcription status.

このサンプル コードでは、カスタム モデルは指定されていません。This sample code doesn't specify a custom model. このサービスでは、ファイルの文字起こしにベースライン モデルを使用します。The service uses the baseline model for transcribing the file or files. モデルを指定するには、同じメソッドにカスタム モデルのモデル参照を渡すことができます。To specify the model, you can pass on the same method the model reference for the custom model.

注意

ベースライン文字起こしの場合、ベースライン モデルの ID を宣言する必要はありません。For baseline transcriptions, you don't need to declare the ID for the baseline model.

次のステップNext steps