快速入門：使用語音轉換文字建立字幕

  • 發行項

參考文件 | 套件 (NuGet) | GitHub 上的其他範例

在本快速入門中，您會執行主控台應用程式透過語音轉換文字來建立字幕。

提示

嘗試 Speech Studio，並選擇範例影片剪輯以查看即時或離線處理的字幕結果。

必要條件

設定環境

語音 SDK 可以 NuGet 套件的形式取得，並且實作 .NET Standard 2.0。 您會在本指南的後續部分中安裝語音 SDK，但請先參閱 SDK 安裝指南，了解其他需求。

您也必須針對壓縮的輸入音訊安裝 GStreamer。

設定環境變數

您必須驗證應用程式以存取 Azure AI 服務。 本文說明如何使用環境變數來儲存您的認證。 然後，您可以從程式碼存取環境變數，以驗證您的應用程式。 針對實際執行環境，使用更安全的方法來儲存和存取您的認證。

重要

我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

若要設定語音資源索引鍵和區域的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。

  • 若要設定 SPEECH_KEY 環境變數，請以您其中一個資源金鑰取代 your-key。
  • 若要設定 SPEECH_REGION 環境變數，請以您的其中一個資源區域取代 your-region。
setx SPEECH_KEY your-key
setx SPEECH_REGION your-region

注意

如果您只需要存取目前主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的程式，包括主控台視窗。 例如，如果正在使用 Visual Studio 作為編輯器，請您在執行範例前重新啟動 Visual Studio。

從語音建立字幕

請遵循下列步驟來建置和執行輔助字幕快速入門程式碼範例。

  1. 從 GitHub 複製 scenarios/csharp/dotnetcore/captioning/ (英文) 範例檔案。 如果您已安裝 Git (英文)，請開啟命令提示字元，然後執行 git clone 命令以下載語音 SDK 範例存放庫。 
    git clone https://github.com/Azure-Samples/cognitive-services-speech-sdk.git
  2. 開啟命令提示字元，並變更至專案目錄。 
    cd <your-local-path>/scenarios/csharp/dotnetcore/captioning/captioning/
  3. 使用 .NET CLI 建置專案。 
    dotnet build
  4. 使用您慣用的命令列引數執行應用程式。 如需可用選項，請參閱使用方式和引數。 以下是範例：
    dotnet run --input caption.this.mp4 --format any --output caption.output.txt --srt --realTime --threshold 5 --delay 0 --profanity mask --phrases "Contoso;Jessie;Rehaan"

    重要

    請確定 --input 和 --output 指定的路徑有效。 否則您必須變更路徑。

    確保您已如上所述設定 SPEECH_KEY 和 SPEECH_REGION 環境變數。 否則，請使用 --key 和 --region 引數。

檢查結果

當您在上述範例中使用 realTime 選項時，輸出中會包含來自 Recognizing 事件的部分結果。 在此範例中，只有最終 Recognized 事件包含逗號。 逗號不是 Recognizing 和 Recognized 事件之間的唯一差異。 如需詳細資訊，請參閱取得部分結果。

1
00:00:00,170 --> 00:00:00,380
The

2
00:00:00,380 --> 00:00:01,770
The rainbow

3
00:00:01,770 --> 00:00:02,560
The rainbow has seven

4
00:00:02,560 --> 00:00:03,820
The rainbow has seven colors

5
00:00:03,820 --> 00:00:05,050
The rainbow has seven colors red

6
00:00:05,050 --> 00:00:05,850
The rainbow has seven colors red
orange

7
00:00:05,850 --> 00:00:06,440
The rainbow has seven colors red
orange yellow

8
00:00:06,440 --> 00:00:06,730
The rainbow has seven colors red
orange yellow green

9
00:00:06,730 --> 00:00:07,160
orange, yellow, green, blue,
indigo and Violet.

當您使用 --offline 選項時，來自最終 Recognized 事件的結果會保持穩定。 部分結果不會包含在輸出中：

1
00:00:00,170 --> 00:00:05,540
The rainbow has seven colors, red,
orange, yellow, green, blue,

2
00:00:05,540 --> 00:00:07,160
indigo and Violet.

SRT (SubRip Text) 時間範圍輸出格式為 hh:mm:ss,fff。 如需詳細資訊，請參閱字幕輸出格式。

使用方式和引數

使用方式：captioning --input <input file>

連線選項包括：

  • --key：您的語音資源金鑰。 覆寫 SPEECH_KEY 環境變數。 您必須設定環境變數 (建議)，或使用 --key 選項。
  • --region REGION：您的語音資源區域。 覆寫 SPEECH_REGION 環境變數。 您必須設定環境變數 (建議)，或使用 --region 選項。 範例：westus、northeurope

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

輸入選項包括：

  • --input FILE：來自檔案的輸入音訊。 預設輸入為麥克風。
  • --format FORMAT：使用壓縮音訊格式。 只對 --file 有效。 有效值包括 alaw、any、flac、mp3、mulaw 和 ogg_opus。 預設值是 any。 若要使用 wav 檔案，請勿指定格式。 這個選項不適用於 JavaScript 字幕範例。 如需 MP4 之類的壓縮音訊檔案，請安裝 GStreamer，並參閱如何使用壓縮的輸入音訊。

語言選項包括：

  • --language LANG：使用其中一個對應的支援地區設定來指定語言。 這會在將字幕分成幾行時使用。 預設值為 en-US。

辨識選項包括：

  • --offline：輸出離線結果。 覆寫 --realTime。 預設輸出模式為離線。
  • --realTime：輸出即時結果。

即時輸出包含 Recognizing 事件結果。 預設離線輸出只有 Recognized 事件結果。 這些結果一律會寫入主控台，永遠不會寫入輸出檔案。 --quiet 選項會覆寫這個結果。 如需詳細資訊，請參閱取得語音辨識結果。

精確度選項包括：

  • --phrases PHRASE1;PHRASE2：您可以指定要辨識的片語清單，例如 Contoso;Jessie;Rehaan。 如需詳細資訊，請參閱使用片語清單改善辨識。

輸出選項包括：

  • --help：顯示此說明並停止
  • --output FILE：將字幕輸出至指定 file。 這個旗標是必要項目。
  • --srt：輸出字幕的格式為 SRT (SubRip Text) 格式。 預設格式為 WebVTT (Web Video Text Tracks)。 如需 SRT 和 WebVTT 字幕檔案格式的詳細資訊，請參閱字幕輸出格式。
  • --maxLineLength LENGTH：將字幕的每行字元數上限設定為 LENGTH。 最小值為 20。 預設值為 37 (中文為 30)。
  • --lines LINES：將字幕的行數設定為 LINE。 最小值為 1。 預設為 2。
  • --delay MILLISECONDS：延遲顯示每個字幕的 MILLISECONDS (毫秒) 數，以模擬即時體驗。 僅在您使用 realTime 旗標時才能使用此選項。 最小值為 0.0。 預設值為 1000。
  • --remainTime MILLISECONDS：如果字幕未由另一個字幕取代，則應該在畫面上保留的 MILLISECONDS (毫秒) 數。 最小值為 0.0。 預設值為 1000。
  • --quiet：隱藏主控台輸出，但是錯誤除外。
  • --profanity OPTION有效值：raw、remove、mask。 如需詳細資訊，請參閱不雅內容篩選概念。
  • --threshold NUMBER：設定穩定的部分結果閾值。 預設值是 3。 僅在您使用 realTime 旗標時才能使用此選項。 如需詳細資訊，請參閱取得部分結果概念。

清除資源

您可以使用 Azure 入口網站或 Azure 命令列介面 (CLI) 來移除您所建立的語音資源。

參考文件 | 套件 (NuGet) | GitHub 上的其他範例

在本快速入門中，您會執行主控台應用程式透過語音轉換文字來建立字幕。

提示

嘗試 Speech Studio，並選擇範例影片剪輯以查看即時或離線處理的字幕結果。

必要條件

設定環境

語音 SDK 可以 NuGet 套件的形式取得，並且實作 .NET Standard 2.0。 您會在本指南的後續部分中安裝語音 SDK，但請先參閱 SDK 安裝指南，了解其他需求

您也必須針對壓縮的輸入音訊安裝 GStreamer。

設定環境變數

您必須驗證應用程式以存取 Azure AI 服務。 本文說明如何使用環境變數來儲存您的認證。 然後，您可以從程式碼存取環境變數，以驗證您的應用程式。 針對實際執行環境，使用更安全的方法來儲存和存取您的認證。

重要

我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

若要設定語音資源索引鍵和區域的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。

  • 若要設定 SPEECH_KEY 環境變數，請以您其中一個資源金鑰取代 your-key。
  • 若要設定 SPEECH_REGION 環境變數，請以您的其中一個資源區域取代 your-region。
setx SPEECH_KEY your-key
setx SPEECH_REGION your-region

注意

如果您只需要存取目前主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的程式，包括主控台視窗。 例如，如果正在使用 Visual Studio 作為編輯器，請您在執行範例前重新啟動 Visual Studio。

從語音建立字幕

請遵循下列步驟，在 Windows 上使用 Visual Studio Community 2022 來建置和執行輔助字幕快速入門程式碼範例。

  1. 從 GitHub 將 scenarios/cpp/windows/captioning/ 範例檔案下載或複製到本機目錄。

  2. 在 Visual Studio Community 2022 中開啟 captioning.sln 解決方案檔案。

  3. 使用 NuGet 套件管理員在專案中安裝語音 SDK。

    Install-Package Microsoft.CognitiveServices.Speech

  4. 開啟 [專案] > [屬性] > [一般]。 將 [組態] 設定為 All configurations。 將 [C++ 語言標準] 設定為 ISO C++17 Standard (/std:c++17)。

  5. 開啟 [建置]> [組態管理員]。

    • 在 64 位元 Windows 安裝上，將 [作用中解決方案平台] 設定為 x64。
    • 在 32 位元 Windows 安裝上，將 [作用中解決方案平台] 設定為 x86。

  6. 開啟 [專案] > [屬性] > [偵錯]。 在 [命令引數] 中輸入您慣用的命令列引數。 如需可用選項，請參閱使用方式和引數。 以下是範例：

    --input caption.this.mp4 --format any --output caption.output.txt --srt --realTime --threshold 5 --delay 0 --profanity mask --phrases "Contoso;Jessie;Rehaan"

    重要

    請確定 --input 和 --output 指定的路徑有效。 否則您必須變更路徑。

    確保您已如上所述設定 SPEECH_KEY 和 SPEECH_REGION 環境變數。 否則，請使用 --key 和 --region 引數。

  7. 建置並執行主控台應用程式。

檢查結果

當您在上述範例中使用 realTime 選項時，輸出中會包含來自 Recognizing 事件的部分結果。 在此範例中，只有最終 Recognized 事件包含逗號。 逗號不是 Recognizing 和 Recognized 事件之間的唯一差異。 如需詳細資訊，請參閱取得部分結果。

1
00:00:00,170 --> 00:00:00,380
The

2
00:00:00,380 --> 00:00:01,770
The rainbow

3
00:00:01,770 --> 00:00:02,560
The rainbow has seven

4
00:00:02,560 --> 00:00:03,820
The rainbow has seven colors

5
00:00:03,820 --> 00:00:05,050
The rainbow has seven colors red

6
00:00:05,050 --> 00:00:05,850
The rainbow has seven colors red
orange

7
00:00:05,850 --> 00:00:06,440
The rainbow has seven colors red
orange yellow

8
00:00:06,440 --> 00:00:06,730
The rainbow has seven colors red
orange yellow green

9
00:00:06,730 --> 00:00:07,160
orange, yellow, green, blue,
indigo and Violet.

當您使用 --offline 選項時，來自最終 Recognized 事件的結果會保持穩定。 部分結果不會包含在輸出中：

1
00:00:00,170 --> 00:00:05,540
The rainbow has seven colors, red,
orange, yellow, green, blue,

2
00:00:05,540 --> 00:00:07,160
indigo and Violet.

SRT (SubRip Text) 時間範圍輸出格式為 hh:mm:ss,fff。 如需詳細資訊，請參閱字幕輸出格式。

使用方式和引數

使用方式：captioning --input <input file>

連線選項包括：

  • --key：您的語音資源金鑰。 覆寫 SPEECH_KEY 環境變數。 您必須設定環境變數 (建議)，或使用 --key 選項。
  • --region REGION：您的語音資源區域。 覆寫 SPEECH_REGION 環境變數。 您必須設定環境變數 (建議)，或使用 --region 選項。 範例：westus、northeurope

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

輸入選項包括：

  • --input FILE：來自檔案的輸入音訊。 預設輸入為麥克風。
  • --format FORMAT：使用壓縮音訊格式。 只對 --file 有效。 有效值包括 alaw、any、flac、mp3、mulaw 和 ogg_opus。 預設值是 any。 若要使用 wav 檔案，請勿指定格式。 這個選項不適用於 JavaScript 字幕範例。 如需 MP4 之類的壓縮音訊檔案，請安裝 GStreamer，並參閱如何使用壓縮的輸入音訊。

語言選項包括：

  • --language LANG：使用其中一個對應的支援地區設定來指定語言。 這會在將字幕分成幾行時使用。 預設值為 en-US。

辨識選項包括：

  • --offline：輸出離線結果。 覆寫 --realTime。 預設輸出模式為離線。
  • --realTime：輸出即時結果。

即時輸出包含 Recognizing 事件結果。 預設離線輸出只有 Recognized 事件結果。 這些結果一律會寫入主控台，永遠不會寫入輸出檔案。 --quiet 選項會覆寫這個結果。 如需詳細資訊，請參閱取得語音辨識結果。

精確度選項包括：

  • --phrases PHRASE1;PHRASE2：您可以指定要辨識的片語清單，例如 Contoso;Jessie;Rehaan。 如需詳細資訊，請參閱使用片語清單改善辨識。

輸出選項包括：

  • --help：顯示此說明並停止
  • --output FILE：將字幕輸出至指定 file。 這個旗標是必要項目。
  • --srt：輸出字幕的格式為 SRT (SubRip Text) 格式。 預設格式為 WebVTT (Web Video Text Tracks)。 如需 SRT 和 WebVTT 字幕檔案格式的詳細資訊，請參閱字幕輸出格式。
  • --maxLineLength LENGTH：將字幕的每行字元數上限設定為 LENGTH。 最小值為 20。 預設值為 37 (中文為 30)。
  • --lines LINES：將字幕的行數設定為 LINE。 最小值為 1。 預設為 2。
  • --delay MILLISECONDS：延遲顯示每個字幕的 MILLISECONDS (毫秒) 數，以模擬即時體驗。 僅在您使用 realTime 旗標時才能使用此選項。 最小值為 0.0。 預設值為 1000。
  • --remainTime MILLISECONDS：如果字幕未由另一個字幕取代，則應該在畫面上保留的 MILLISECONDS (毫秒) 數。 最小值為 0.0。 預設值為 1000。
  • --quiet：隱藏主控台輸出，但是錯誤除外。
  • --profanity OPTION有效值：raw、remove、mask。 如需詳細資訊，請參閱不雅內容篩選概念。
  • --threshold NUMBER：設定穩定的部分結果閾值。 預設值是 3。 僅在您使用 realTime 旗標時才能使用此選項。 如需詳細資訊，請參閱取得部分結果概念。

清除資源

您可以使用 Azure 入口網站或 Azure 命令列介面 (CLI) 來移除您所建立的語音資源。

參考文件 | 套件 (Go) | GitHub 上的其他範例

在本快速入門中，您會執行主控台應用程式透過語音轉換文字來建立字幕。

提示

嘗試 Speech Studio，並選擇範例影片剪輯以查看即時或離線處理的字幕結果。

必要條件

設定環境

檢查是否有任何平台特定的安裝步驟。

您也必須針對壓縮的輸入音訊安裝 GStreamer。

從語音建立字幕

請遵循下列步驟來建置和執行輔助字幕快速入門程式碼範例。

  1. 從 GitHub 將 scenarios/go/captioning/ 範例檔案下載或複製到本機目錄。

  2. 在與 captioning.go 相同的目錄中開啟命令提示字元。

  3. 執行下列命令來建立 go.mod 檔案，該檔案連結至 Github 上託管的語音 SDK 元件：

    go mod init captioning
go get github.com/Microsoft/cognitive-services-speech-sdk-go

  4. 建置 GO 模組。

    go build

  5. 使用您慣用的命令列引數執行應用程式。 如需可用選項，請參閱使用方式和引數。 以下是範例：

    go run captioning --key YourSubscriptionKey --region YourServiceRegion --input caption.this.mp4 --format any --output caption.output.txt --srt --recognizing --threshold 5 --profanity mask --phrases "Contoso;Jessie;Rehaan"

    將 YourSubscriptionKey 取代為您的語音資源金鑰，以及將 YourServiceRegion 取代為您的語音資源區域，例如 westus 或 northeurope。 請確定 --input 和 --output 指定的路徑有效。 否則您必須變更路徑。

    重要

    完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性一文。

檢查結果

具有完整字幕的輸出檔案會寫入 caption.output.txt。 中繼結果會顯示在主控台中：

00:00:00,180 --> 00:00:01,600
Welcome to

00:00:00,180 --> 00:00:01,820
Welcome to applied

00:00:00,180 --> 00:00:02,420
Welcome to applied mathematics

00:00:00,180 --> 00:00:02,930
Welcome to applied mathematics course

00:00:00,180 --> 00:00:03,100
Welcome to applied Mathematics course 2

00:00:00,180 --> 00:00:03,230
Welcome to applied Mathematics course 201.

SRT (SubRip Text) 時間範圍輸出格式為 hh:mm:ss,fff。 如需詳細資訊，請參閱字幕輸出格式。

使用方式和引數

使用方式：go run captioning.go helper.go --key <key> --region <region> --input <input file>

連線選項包括：

  • --key：您的語音資源金鑰。
  • --region REGION：您的語音資源區域。 範例：westus、northeurope

輸入選項包括：

  • --input FILE：來自檔案的輸入音訊。 預設輸入為麥克風。
  • --format FORMAT：使用壓縮音訊格式。 只對 --file 有效。 有效值包括 alaw、any、flac、mp3、mulaw 和 ogg_opus。 預設值是 any。 若要使用 wav 檔案，請勿指定格式。 這個選項不適用於 JavaScript 字幕範例。 如需 MP4 之類的壓縮音訊檔案，請安裝 GStreamer，並參閱如何使用壓縮的輸入音訊。

語言選項包括：

  • --languages LANG1,LANG2：啟用指定語言的語言識別。 例如： en-US,ja-JP 。 此選項僅適用於 C++、C# 和 Python 字幕範例。 如需詳細資訊，請參閱語言識別。

辨識選項包括：

  • --recognizing：輸出 Recognizing 事件結果。 預設輸出只有 Recognized 事件結果。 這些結果一律會寫入主控台，永遠不會寫入輸出檔案。 --quiet 選項會覆寫這個結果。 如需詳細資訊，請參閱取得語音辨識結果。

精確度選項包括：

  • --phrases PHRASE1;PHRASE2：您可以指定要辨識的片語清單，例如 Contoso;Jessie;Rehaan。 如需詳細資訊，請參閱使用片語清單改善辨識。

輸出選項包括：

  • --help：顯示此說明並停止
  • --output FILE：將字幕輸出至指定 file。 這個旗標是必要項目。
  • --srt：輸出字幕的格式為 SRT (SubRip Text) 格式。 預設格式為 WebVTT (Web Video Text Tracks)。 如需 SRT 和 WebVTT 字幕檔案格式的詳細資訊，請參閱字幕輸出格式。
  • --quiet：隱藏主控台輸出，但是錯誤除外。
  • --profanity OPTION有效值：raw、remove、mask。 如需詳細資訊，請參閱不雅內容篩選概念。
  • --threshold NUMBER：設定穩定的部分結果閾值。 預設值是 3。 如需詳細資訊，請參閱取得部分結果概念。

清除資源

您可以使用 Azure 入口網站或 Azure 命令列介面 (CLI) 來移除您所建立的語音資源。

參考文件 | GitHub 上的其他範例

在本快速入門中，您會執行主控台應用程式透過語音轉換文字來建立字幕。

提示

嘗試 Speech Studio，並選擇範例影片剪輯以查看即時或離線處理的字幕結果。

必要條件

設定環境

您必須先安裝語音 SDK，才能執行動作。 本快速入門中的範例適用於 Microsoft Build of OpenJDK 17

  1. 安裝 Apache Maven。 然後執行 mvn -v 以確認安裝成功。
  2. 在專案的根目錄中建立新 pom.xml 檔案，並將下列內容複製到其中：
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.microsoft.cognitiveservices.speech.samples</groupId>
    <artifactId>quickstart-eclipse</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <build>
        <sourceDirectory>src</sourceDirectory>
        <plugins>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.7.0</version>
            <configuration>
            <source>1.8</source>
            <target>1.8</target>
            </configuration>
        </plugin>
        </plugins>
    </build>
    <dependencies>
        <dependency>
        <groupId>com.microsoft.cognitiveservices.speech</groupId>
        <artifactId>client-sdk</artifactId>
        <version>1.40.0</version>
        </dependency>
    </dependencies>
</project>
  3. 安裝語音 SDK 和相依性。 
    mvn clean dependency:copy-dependencies
  4. 您也必須針對壓縮的輸入音訊安裝 GStreamer。

設定環境變數

您必須驗證應用程式以存取 Azure AI 服務。 本文說明如何使用環境變數來儲存您的認證。 然後，您可以從程式碼存取環境變數，以驗證您的應用程式。 針對實際執行環境，使用更安全的方法來儲存和存取您的認證。

重要

我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

若要設定語音資源索引鍵和區域的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。

  • 若要設定 SPEECH_KEY 環境變數，請以您其中一個資源金鑰取代 your-key。
  • 若要設定 SPEECH_REGION 環境變數，請以您的其中一個資源區域取代 your-region。
setx SPEECH_KEY your-key
setx SPEECH_REGION your-region

注意

如果您只需要存取目前主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的程式，包括主控台視窗。 例如，如果正在使用 Visual Studio 作為編輯器，請您在執行範例前重新啟動 Visual Studio。

從語音建立字幕

請遵循下列步驟來建置和執行輔助字幕快速入門程式碼範例。

  1. 從 GitHub 將 scenarios/java/jre/captioning/ 範例檔案複製到您的專案目錄。 您在環境設定中建立的 pom.xml 檔案也必須在此目錄中。
  2. 開啟命令提示字元，然後執行此命令來編譯專案檔。 
    javac Captioning.java -cp ".;target\dependency\*" -encoding UTF-8
  3. 使用您慣用的命令列引數執行應用程式。 如需可用選項，請參閱使用方式和引數。 以下是範例：
    java -cp ".;target\dependency\*" Captioning --input caption.this.mp4 --format any --output caption.output.txt --srt --realTime --threshold 5 --delay 0 --profanity mask --phrases "Contoso;Jessie;Rehaan"

    重要

    請確定 --input 和 --output 指定的路徑有效。 否則您必須變更路徑。

    確保您已如上所述設定 SPEECH_KEY 和 SPEECH_REGION 環境變數。 否則，請使用 --key 和 --region 引數。

檢查結果

當您在上述範例中使用 realTime 選項時，輸出中會包含來自 Recognizing 事件的部分結果。 在此範例中，只有最終 Recognized 事件包含逗號。 逗號不是 Recognizing 和 Recognized 事件之間的唯一差異。 如需詳細資訊，請參閱取得部分結果。

1
00:00:00,170 --> 00:00:00,380
The

2
00:00:00,380 --> 00:00:01,770
The rainbow

3
00:00:01,770 --> 00:00:02,560
The rainbow has seven

4
00:00:02,560 --> 00:00:03,820
The rainbow has seven colors

5
00:00:03,820 --> 00:00:05,050
The rainbow has seven colors red

6
00:00:05,050 --> 00:00:05,850
The rainbow has seven colors red
orange

7
00:00:05,850 --> 00:00:06,440
The rainbow has seven colors red
orange yellow

8
00:00:06,440 --> 00:00:06,730
The rainbow has seven colors red
orange yellow green

9
00:00:06,730 --> 00:00:07,160
orange, yellow, green, blue,
indigo and Violet.

當您使用 --offline 選項時，來自最終 Recognized 事件的結果會保持穩定。 部分結果不會包含在輸出中：

1
00:00:00,170 --> 00:00:05,540
The rainbow has seven colors, red,
orange, yellow, green, blue,

2
00:00:05,540 --> 00:00:07,160
indigo and Violet.

SRT (SubRip Text) 時間範圍輸出格式為 hh:mm:ss,fff。 如需詳細資訊，請參閱字幕輸出格式。

使用方式和引數

使用方式：java -cp ".;target\dependency\*" Captioning --input <input file>

連線選項包括：

  • --key：您的語音資源金鑰。 覆寫 SPEECH_KEY 環境變數。 您必須設定環境變數 (建議)，或使用 --key 選項。
  • --region REGION：您的語音資源區域。 覆寫 SPEECH_REGION 環境變數。 您必須設定環境變數 (建議)，或使用 --region 選項。 範例：westus、northeurope

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

輸入選項包括：

  • --input FILE：來自檔案的輸入音訊。 預設輸入為麥克風。
  • --format FORMAT：使用壓縮音訊格式。 只對 --file 有效。 有效值包括 alaw、any、flac、mp3、mulaw 和 ogg_opus。 預設值是 any。 若要使用 wav 檔案，請勿指定格式。 這個選項不適用於 JavaScript 字幕範例。 如需 MP4 之類的壓縮音訊檔案，請安裝 GStreamer，並參閱如何使用壓縮的輸入音訊。

語言選項包括：

  • --language LANG：使用其中一個對應的支援地區設定來指定語言。 這會在將字幕分成幾行時使用。 預設值為 en-US。

辨識選項包括：

  • --offline：輸出離線結果。 覆寫 --realTime。 預設輸出模式為離線。
  • --realTime：輸出即時結果。

即時輸出包含 Recognizing 事件結果。 預設離線輸出只有 Recognized 事件結果。 這些結果一律會寫入主控台，永遠不會寫入輸出檔案。 --quiet 選項會覆寫這個結果。 如需詳細資訊，請參閱取得語音辨識結果。

精確度選項包括：

  • --phrases PHRASE1;PHRASE2：您可以指定要辨識的片語清單，例如 Contoso;Jessie;Rehaan。 如需詳細資訊，請參閱使用片語清單改善辨識。

輸出選項包括：

  • --help：顯示此說明並停止
  • --output FILE：將字幕輸出至指定 file。 這個旗標是必要項目。
  • --srt：輸出字幕的格式為 SRT (SubRip Text) 格式。 預設格式為 WebVTT (Web Video Text Tracks)。 如需 SRT 和 WebVTT 字幕檔案格式的詳細資訊，請參閱字幕輸出格式。
  • --maxLineLength LENGTH：將字幕的每行字元數上限設定為 LENGTH。 最小值為 20。 預設值為 37 (中文為 30)。
  • --lines LINES：將字幕的行數設定為 LINE。 最小值為 1。 預設為 2。
  • --delay MILLISECONDS：延遲顯示每個字幕的 MILLISECONDS (毫秒) 數，以模擬即時體驗。 僅在您使用 realTime 旗標時才能使用此選項。 最小值為 0.0。 預設值為 1000。
  • --remainTime MILLISECONDS：如果字幕未由另一個字幕取代，則應該在畫面上保留的 MILLISECONDS (毫秒) 數。 最小值為 0.0。 預設值為 1000。
  • --quiet：隱藏主控台輸出，但是錯誤除外。
  • --profanity OPTION有效值：raw、remove、mask。 如需詳細資訊，請參閱不雅內容篩選概念。
  • --threshold NUMBER：設定穩定的部分結果閾值。 預設值是 3。 僅在您使用 realTime 旗標時才能使用此選項。 如需詳細資訊，請參閱取得部分結果概念。

清除資源

您可以使用 Azure 入口網站或 Azure 命令列介面 (CLI) 來移除您所建立的語音資源。

參考文件 | 套件 (npm) | GitHub 上的其他範例 | 程式庫原始程式碼

在本快速入門中，您會執行主控台應用程式透過語音轉換文字來建立字幕。

提示

嘗試 Speech Studio，並選擇範例影片剪輯以查看即時或離線處理的字幕結果。

必要條件

設定環境

您必須先安裝適用於 JavaScript 的語音 SDK，才能執行動作。 如果您只想要安裝套件名稱，請執行 npm install microsoft-cognitiveservices-speech-sdk。 如需引導式安裝指南，請參閱 SDK 安裝指南。

從語音建立字幕

請遵循下列步驟來建置和執行輔助字幕快速入門程式碼範例。

  1. 從 GitHub 將 scenarios/javascript/node/captioning/ 範例檔案複製到您的專案目錄。

  2. 在與 Captioning.js 相同的目錄中開啟命令提示字元。

  3. 安裝適用於 JavaScript 的語音 SDK：

    npm install microsoft-cognitiveservices-speech-sdk

  4. 使用您慣用的命令列引數執行應用程式。 如需可用選項，請參閱使用方式和引數。 以下是範例：

    node captioning.js --key YourSubscriptionKey --region YourServiceRegion --input caption.this.wav --output caption.output.txt --srt --recognizing --threshold 5 --profanity mask --phrases "Contoso;Jessie;Rehaan"

    將 YourSubscriptionKey 取代為您的語音資源金鑰，以及將 YourServiceRegion 取代為您的語音資源區域，例如 westus 或 northeurope。 請確定 --input 和 --output 指定的路徑有效。 否則您必須變更路徑。

    注意

    適用於 JavaScript 的語音 SDK 不支援壓縮的輸入音訊。 您必須使用 WAV 檔案，如範例所示。

    重要

    完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性一文。

檢查結果

具有完整字幕的輸出檔案會寫入 caption.output.txt。 中繼結果會顯示在主控台中：

00:00:00,180 --> 00:00:01,600
Welcome to

00:00:00,180 --> 00:00:01,820
Welcome to applied

00:00:00,180 --> 00:00:02,420
Welcome to applied mathematics

00:00:00,180 --> 00:00:02,930
Welcome to applied mathematics course

00:00:00,180 --> 00:00:03,100
Welcome to applied Mathematics course 2

00:00:00,180 --> 00:00:03,230
Welcome to applied Mathematics course 201.

SRT (SubRip Text) 時間範圍輸出格式為 hh:mm:ss,fff。 如需詳細資訊，請參閱字幕輸出格式。

使用方式和引數

使用方式：node captioning.js --key <key> --region <region> --input <input file>

連線選項包括：

  • --key：您的語音資源金鑰。
  • --region REGION：您的語音資源區域。 範例：westus、northeurope

輸入選項包括：

  • --input FILE：來自檔案的輸入音訊。 預設輸入為麥克風。
  • --format FORMAT：使用壓縮音訊格式。 只對 --file 有效。 有效值包括 alaw、any、flac、mp3、mulaw 和 ogg_opus。 預設值是 any。 若要使用 wav 檔案，請勿指定格式。 這個選項不適用於 JavaScript 字幕範例。 如需 MP4 之類的壓縮音訊檔案，請安裝 GStreamer，並參閱如何使用壓縮的輸入音訊。

語言選項包括：

  • --languages LANG1,LANG2：啟用指定語言的語言識別。 例如： en-US,ja-JP 。 此選項僅適用於 C++、C# 和 Python 字幕範例。 如需詳細資訊，請參閱語言識別。

辨識選項包括：

  • --recognizing：輸出 Recognizing 事件結果。 預設輸出只有 Recognized 事件結果。 這些結果一律會寫入主控台，永遠不會寫入輸出檔案。 --quiet 選項會覆寫這個結果。 如需詳細資訊，請參閱取得語音辨識結果。

精確度選項包括：

  • --phrases PHRASE1;PHRASE2：您可以指定要辨識的片語清單，例如 Contoso;Jessie;Rehaan。 如需詳細資訊，請參閱使用片語清單改善辨識。

輸出選項包括：

  • --help：顯示此說明並停止
  • --output FILE：將字幕輸出至指定 file。 這個旗標是必要項目。
  • --srt：輸出字幕的格式為 SRT (SubRip Text) 格式。 預設格式為 WebVTT (Web Video Text Tracks)。 如需 SRT 和 WebVTT 字幕檔案格式的詳細資訊，請參閱字幕輸出格式。
  • --quiet：隱藏主控台輸出，但是錯誤除外。
  • --profanity OPTION有效值：raw、remove、mask。 如需詳細資訊，請參閱不雅內容篩選概念。
  • --threshold NUMBER：設定穩定的部分結果閾值。 預設值是 3。 如需詳細資訊，請參閱取得部分結果概念。

清除資源

您可以使用 Azure 入口網站或 Azure 命令列介面 (CLI) 來移除您所建立的語音資源。

參考文件 | 套件 (下載) | GitHub 上的其他範例

適用於 Objective-C 的語音 SDK 支援取得字幕的語音辨識結果，但是我們尚未包含在這裡的指南中。 請選取另一種程式設計語言來開始使用並了解概念，或參閱本文開頭連結的 Objective-C 參考和範例。

參考文件 | 套件 (下載) | GitHub 上的其他範例

適用於 Swift 的語音 SDK 支援取得字幕的語音辨識結果，但是我們尚未包含在這裡的指南中。 請選取另一種程式設計語言來開始使用並了解概念，或參閱本文開頭連結的 Swift 參考和範例。

參考文件 | 套件 (PyPi) | GitHub 上的其他範例

在本快速入門中，您會執行主控台應用程式透過語音轉換文字來建立字幕。

提示

嘗試 Speech Studio，並選擇範例影片剪輯以查看即時或離線處理的字幕結果。

必要條件

設定環境

適用於 Python 的語音 SDK 會以 Python 套件索引 (PyPI) 模組的形式提供。 適用於 Python 的語音 SDK 與 Windows、Linux 和 macOS 相容。

  1. 安裝 Python 從 3.10 或更新的版本。 請先檢查 SDK 安裝指南以了解更多需求
  2. 您也必須針對壓縮的輸入音訊安裝 GStreamer。

設定環境變數

您必須驗證應用程式以存取 Azure AI 服務。 本文說明如何使用環境變數來儲存您的認證。 然後，您可以從程式碼存取環境變數，以驗證您的應用程式。 針對實際執行環境，使用更安全的方法來儲存和存取您的認證。

重要

我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

若要設定語音資源索引鍵和區域的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。

  • 若要設定 SPEECH_KEY 環境變數，請以您其中一個資源金鑰取代 your-key。
  • 若要設定 SPEECH_REGION 環境變數，請以您的其中一個資源區域取代 your-region。
setx SPEECH_KEY your-key
setx SPEECH_REGION your-region

注意

如果您只需要存取目前主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的程式，包括主控台視窗。 例如，如果正在使用 Visual Studio 作為編輯器，請您在執行範例前重新啟動 Visual Studio。

從語音建立字幕

請遵循下列步驟來建置和執行輔助字幕快速入門程式碼範例。

  1. 從 GitHub 將 scenarios/python/console/captioning/ 範例檔案下載或複製到本機目錄。
  2. 在與 captioning.py 相同的目錄中開啟命令提示字元。
  3. 執行此命令以安裝語音 SDK：
    pip install azure-cognitiveservices-speech
  4. 使用您慣用的命令列引數執行應用程式。 如需可用選項，請參閱使用方式和引數。 以下是範例：
    python captioning.py --input caption.this.mp4 --format any --output caption.output.txt --srt --realTime --threshold 5 --delay 0 --profanity mask --phrases "Contoso;Jessie;Rehaan"

    重要

    請確定 --input 和 --output 指定的路徑有效。 否則您必須變更路徑。

    確保您已如上所述設定 SPEECH_KEY 和 SPEECH_REGION 環境變數。 否則，請使用 --key 和 --region 引數。

檢查結果

當您在上述範例中使用 realTime 選項時，輸出中會包含來自 Recognizing 事件的部分結果。 在此範例中，只有最終 Recognized 事件包含逗號。 逗號不是 Recognizing 和 Recognized 事件之間的唯一差異。 如需詳細資訊，請參閱取得部分結果。

1
00:00:00,170 --> 00:00:00,380
The

2
00:00:00,380 --> 00:00:01,770
The rainbow

3
00:00:01,770 --> 00:00:02,560
The rainbow has seven

4
00:00:02,560 --> 00:00:03,820
The rainbow has seven colors

5
00:00:03,820 --> 00:00:05,050
The rainbow has seven colors red

6
00:00:05,050 --> 00:00:05,850
The rainbow has seven colors red
orange

7
00:00:05,850 --> 00:00:06,440
The rainbow has seven colors red
orange yellow

8
00:00:06,440 --> 00:00:06,730
The rainbow has seven colors red
orange yellow green

9
00:00:06,730 --> 00:00:07,160
orange, yellow, green, blue,
indigo and Violet.

當您使用 --offline 選項時，來自最終 Recognized 事件的結果會保持穩定。 部分結果不會包含在輸出中：

1
00:00:00,170 --> 00:00:05,540
The rainbow has seven colors, red,
orange, yellow, green, blue,

2
00:00:05,540 --> 00:00:07,160
indigo and Violet.

SRT (SubRip Text) 時間範圍輸出格式為 hh:mm:ss,fff。 如需詳細資訊，請參閱字幕輸出格式。

使用方式和引數

使用方式：python captioning.py --input <input file>

連線選項包括：

  • --key：您的語音資源金鑰。 覆寫 SPEECH_KEY 環境變數。 您必須設定環境變數 (建議)，或使用 --key 選項。
  • --region REGION：您的語音資源區域。 覆寫 SPEECH_REGION 環境變數。 您必須設定環境變數 (建議)，或使用 --region 選項。 範例：westus、northeurope

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開將其張貼。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

輸入選項包括：

  • --input FILE：來自檔案的輸入音訊。 預設輸入為麥克風。
  • --format FORMAT：使用壓縮音訊格式。 只對 --file 有效。 有效值包括 alaw、any、flac、mp3、mulaw 和 ogg_opus。 預設值是 any。 若要使用 wav 檔案，請勿指定格式。 這個選項不適用於 JavaScript 字幕範例。 如需 MP4 之類的壓縮音訊檔案，請安裝 GStreamer，並參閱如何使用壓縮的輸入音訊。

語言選項包括：

  • --language LANG：使用其中一個對應的支援地區設定來指定語言。 這會在將字幕分成幾行時使用。 預設值為 en-US。

辨識選項包括：

  • --offline：輸出離線結果。 覆寫 --realTime。 預設輸出模式為離線。
  • --realTime：輸出即時結果。

即時輸出包含 Recognizing 事件結果。 預設離線輸出只有 Recognized 事件結果。 這些結果一律會寫入主控台，永遠不會寫入輸出檔案。 --quiet 選項會覆寫這個結果。 如需詳細資訊，請參閱取得語音辨識結果。

精確度選項包括：

  • --phrases PHRASE1;PHRASE2：您可以指定要辨識的片語清單，例如 Contoso;Jessie;Rehaan。 如需詳細資訊，請參閱使用片語清單改善辨識。

輸出選項包括：

  • --help：顯示此說明並停止
  • --output FILE：將字幕輸出至指定 file。 這個旗標是必要項目。
  • --srt：輸出字幕的格式為 SRT (SubRip Text) 格式。 預設格式為 WebVTT (Web Video Text Tracks)。 如需 SRT 和 WebVTT 字幕檔案格式的詳細資訊，請參閱字幕輸出格式。
  • --maxLineLength LENGTH：將字幕的每行字元數上限設定為 LENGTH。 最小值為 20。 預設值為 37 (中文為 30)。
  • --lines LINES：將字幕的行數設定為 LINE。 最小值為 1。 預設為 2。
  • --delay MILLISECONDS：延遲顯示每個字幕的 MILLISECONDS (毫秒) 數，以模擬即時體驗。 僅在您使用 realTime 旗標時才能使用此選項。 最小值為 0.0。 預設值為 1000。
  • --remainTime MILLISECONDS：如果字幕未由另一個字幕取代，則應該在畫面上保留的 MILLISECONDS (毫秒) 數。 最小值為 0.0。 預設值為 1000。
  • --quiet：隱藏主控台輸出，但是錯誤除外。
  • --profanity OPTION有效值：raw、remove、mask。 如需詳細資訊，請參閱不雅內容篩選概念。
  • --threshold NUMBER：設定穩定的部分結果閾值。 預設值是 3。 僅在您使用 realTime 旗標時才能使用此選項。 如需詳細資訊，請參閱取得部分結果概念。

清除資源

您可以使用 Azure 入口網站或 Azure 命令列介面 (CLI) 來移除您所建立的語音資源。

在本快速入門中，您會執行主控台應用程式透過語音轉換文字來建立字幕。

提示

嘗試 Speech Studio，並選擇範例影片剪輯以查看即時或離線處理的字幕結果。

必要條件

設定環境

請遵循下列步驟，並參閱語音 CLI 快速入門，以了解平台的其他需求。

  1. 執行下列 .NET CLI 命令以安裝 Speech CLI: 

    dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI

  2. 執行下列命令來設定您的語音資源金鑰和區域。 以您的語音資源金鑰取代 SUBSCRIPTION-KEY，而以您的語音資源區域取代 REGION。

    spx config @key --set SUBSCRIPTION-KEY
spx config @region --set REGION

您也必須針對壓縮的輸入音訊安裝 GStreamer。

從語音建立字幕

透過語音 CLI，您可以從包含音訊的任何媒體類型輸出 SRT (SubRip Text) 和 WebVTT (Web Video Text Tracks) 字幕。

若要辨識檔案中的音訊，並輸出 WebVtt (vtt) 和 SRT (srt) 字幕，請遵循下列步驟。

  1. 請確定您在路徑中有名為 caption.this.mp4 的輸入檔。

  2. 執行下列命令，從影片檔案輸出字幕：

    spx recognize --file caption.this.mp4 --format any --output vtt file - --output srt file - --output each file - @output.each.detailed --property SpeechServiceResponse_StablePartialResultThreshold=5 --profanity masked --phrases "Constoso;Jessie;Rehaan"

    SRT 和 WebVTT 字幕會輸出至主控台，如下所示：

    1
00:00:00,180 --> 00:00:03,230
Welcome to applied Mathematics course 201.
WEBVTT

00:00:00.180 --> 00:00:03.230
Welcome to applied Mathematics course 201.
{
  "ResultId": "561a0ea00cc14bb09bd294357df3270f",
  "Duration": "00:00:03.0500000"
}

使用方式和引數

以下是上一個命令中選擇性引數的詳細資料：

  • --file caption.this.mp4 --format any：來自檔案的輸入音訊。 預設輸入為麥克風。 如需 MP4 之類的壓縮音訊檔案，請安裝 GStreamer，並參閱如何使用壓縮的輸入音訊。
  • --output vtt file - and --output srt file -：將 WebVTT 和 SRT 字幕輸出至標準輸出。 如需 SRT 和 WebVTT 字幕檔案格式的詳細資訊，請參閱字幕輸出格式。 如需 --output 引數的詳細資訊，請參閱語音 CLI 輸出選項。
  • @output.each.detailed：輸出含有文字、位移和持續時間的事件結果。 如需詳細資訊，請參閱取得語音辨識結果。
  • --property SpeechServiceResponse_StablePartialResultThreshold=5：您可以要求語音服務傳回較少但是更準確的 Recognizing 事件。 在此範例中，語音服務必須確認至少辨識文字五次，才能將部分結果傳回給您。 如需詳細資訊，請參閱取得部分結果概念。
  • --profanity masked：您可以指定是否要在辨識結果中遮罩、移除或顯示不雅內容。 如需詳細資訊，請參閱不雅內容篩選概念。
  • --phrases "Constoso;Jessie;Rehaan"：您可以指定要辨識的片語清單，例如 Contoso、Jessie 和 Rehaan。 如需詳細資訊，請參閱使用片語清單改善辨識。

清除資源

您可以使用 Azure 入口網站或 Azure 命令列介面 (CLI) 來移除您所建立的語音資源。

下一步

深入了解語音辨識