快速入門：開始使用 Azure AI 語音 CLI

在本文中，您會瞭解如何使用 Azure AI 語音 CLI (也稱之 SPX) 存取語音服務 (例如語音轉換文字、文字轉換語音及語音翻譯)，而無須撰寫程式碼。 語音 CLI 已可在生產環境中使用，您可以使用 .bat 或殼層指令碼將語音服務中的簡易工作流程自動化。

本文假設您已具備命令提示字元視窗、終端或 PowerShell 的使用知識。

注意

在 PowerShell 中，stop-parsing 權杖 (--%) 應遵循 spx。 例如，執行 spx --% config @region 以檢視目前的地區設定值。

下載並安裝

Windows

請遵循下列步驟，在 Windows 上安裝語音 CLI：

1. 您需根據平台來選擇適用於 Visual Studio 2019 的 Microsoft Visual C++ 可轉散發套件。 首次安裝時可能需要重新開機。

2. 安裝 .NET 6。

3. 輸入下列命令，透過 .NET CLI 安裝語音 CLI：

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

   若要更新語音 CLI，請輸入下列命令：

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

輸入 spx 或 spx help 以查看語音 CLI 的說明。

字型限制

在 Windows 上，語音 CLI 只能顯示本機電腦上的命令提示字元可用的字型。 Windows 終端支援語音 CLI 以互動方式產生的所有字型。

如果您輸出至檔案，像是記事本或網頁瀏覽器 (例如 Microsoft Edge) 的文字編輯器也可以顯示所有字型。

Linux

使用語音 CLI 的 x64 結構支援下列 Linux 發行版本：

• Ubuntu 20.04/22.04/24.04
• Debian 11/12

注意

語音 SDK (並非語音 CLI) 支援其他結構。 如需詳細資訊，請參閱關於語音 SDK。

請遵循下列步驟，在 x64 CPU 的 Linux 上安裝語音 CLI：

1. 安裝 .NET 6。

2. 輸入下列命令，透過 .NET CLI 安裝語音 CLI：

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

   若要更新語音 CLI，請輸入下列命令：

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

3. 安裝 GStreamer 以提供壓縮音訊支援。

輸入 spx 以查看語音 CLI 的說明。

macOS

請遵循下列步驟，在 macOS 10.14 或更新版本上安裝語音 CLI：

1. 安裝 .NET 6。

2. 輸入下列命令，透過 .NET CLI 安裝語音 CLI：

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

   若要更新語音 CLI，請輸入下列命令：

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

輸入 spx 或 spx help 以查看語音 CLI 的說明。

Docker (Windows, Linux, macOS)

下列範例會從 Docker Hub 提取公用容器映像。 建議您先驗證 Docker Hub 帳戶 (docker login)，而不是發出匿名提取要求。 若要改善使用公用內容時的可靠性，請在私人 Azure 容器登錄中匯入和管理映像。 深入了解公用映像的使用方式。

請遵循下列步驟，在 Docker 容器中安裝語音 CLI：

1. 為您的平台安裝 Docker Desktop (如果尚未安裝)。
2. 在新的命令提示字元或終端中，輸入下列命令：

   docker pull msftspeech/spx
   

輸入此命令以顯示語音 CLI 的說明資訊：

docker run -it --rm msftspeech/spx help

在容器中掛接目錄

語音 CLI 工具會將組態設定儲存為檔案。 當您執行任何命令時，其將載入這些檔案 (但說明命令除外)。

當您在 Docker 容器中使用語音 CLI 時，必須從容器掛接本機目錄，讓工具可以：

• 儲存或尋找組態設定。
• 讀取或寫入命令所需的任何檔案，例如語音的音訊檔案。

在 Windows 上，輸入此命令來建立可供語音 CLI 從容器內使用的本機目錄：

mkdir c:\spx-data

在 Linux 或 macOS 上，於終端中輸入此命令來建立目錄，並查看其完整路徑：

mkdir ~/spx-data
cd ~/spx-data
pwd

當您呼叫語音 CLI 時，將會使用該完整路徑。

在容器中執行語音 CLI

本文件顯示在非 Docker 安裝中使用的語音 CLI spx 命令。 當您在 Docker 容器中呼叫 spx 命令時，您必須將容器中的目錄掛接至您的檔案系統，讓語音 CLI 可以在其中儲存和尋找設定值，並讀取和寫入檔案。

在 Windows 上，命令的開頭會如下所示：

docker run -it -v c:\spx-data:/data --rm msftspeech/spx

在 Linux 或 macOS 上，您的命令看起來會如下列範例所示。 以掛接目錄的絕對路徑取代 ABSOLUTE_PATH。 命令 pwd 在上一節中傳回此路徑。 如果您在設定金鑰和區域之前執行此命令，則會收到錯誤，告知您要設定金鑰和區域。

sudo docker run -it -v ABSOLUTE_PATH:/data --rm msftspeech/spx

若要使用容器中安裝的 spx 命令，請一律輸入如上範例所示的完整命令，後面接著您的要求參數。 例如，在 Windows 上，此命令會設定您的金鑰：

docker run -it -v c:\spx-data:/data --rm msftspeech/spx config @key --set SUBSCRIPTION-KEY

若要使用命令列工具進行更多延伸的互動，您可以藉由新增 entrypoint 參數來啟動具有互動式 Bash 殼層的容器。 在 Windows 上，輸入此命令來啟動會公開互動式命令列介面的容器，您可以在其中輸入多個 spx 命令：

docker run -it --entrypoint=/bin/bash -v c:\spx-data:/data --rm msftspeech/spx

您可以將其與 AZ Login 結合，並讓 SPX Init 引導您逐步建立語音金鑰，並選取相符的資料區域，而不需要使用 Azure 入口網站。 該金鑰會自動儲存以供稍後使用。

docker run -it --rm --entrypoint /bin/bash -v c:\spx-data:/data msftspeech/spx

az login
spx init

建立資源設定

終端機

若要開始使用，您需要語音資源金鑰和區域識別碼 (例如 eastus、westus)。 在 Azure 入口網站上建立語音資源。 如需詳細資訊，請參閱建立 Azure AI 服務資源。

若要設定資源金鑰和區域識別碼，請執行下列命令：

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

金鑰和區域會儲存起來，以供後續語音 CLI 命令之用。 若要檢視目前的設定，請執行下列命令：

spx config @key
spx config @region

視需要加入 clear 選項以移除其中一個儲存值：

spx config @key --clear
spx config @region --clear

PowerShell

若要開始使用，您需要語音資源金鑰和區域識別碼 (例如 eastus、westus)。 在 Azure 入口網站上建立語音資源。

若要設定語音資源金鑰和區域識別碼，請在 PowerShell 中執行下列命令：

spx --% config @key --set SPEECH-KEY
spx --% config @region --set SPEECH-REGION

金鑰和區域會儲存起來，以供後續 SPX 命令之用。 若要檢視目前的設定，請執行下列命令：

spx --% config @key
spx --% config @region

視需要加入 clear 選項以移除其中一個儲存值：

spx --% config @key --clear
spx --% config @region --clear

基本使用方式

重要

當您在容器中使用語音 CLI 時，請包含 --host 選項。 您也必須指定 --key none 來確保 CLI 不會嘗試使用語音金鑰進行驗證。 例如，執行 spx recognize --key none --host wss://localhost:5000/ --file myaudio.wav 以從 語音轉換文字容器中的音訊檔案辨識語音。

本節將說明一些常可運用在首次測試和實驗的基本 SPX 命令。 請執行下列命令以檢視工具內說明：

spx

您可以依關鍵字搜尋說明主題。 例如，若要查看語音 CLI 使用量範例的清單，請執行下列命令：

spx help find --topics "examples"

若要查看 recognize 命令的選項，請執行下列命令：

spx help recognize

主控台輸出會列出更多說明命令。 您可以輸入這些命令，以取得子命令的詳細說明。

語音轉換文字 (語音辨識)

注意

在 Docker 容器內執行語音 CLI 時，無法使用電腦的麥克風。 不過，您可以在本機掛接的目錄中讀取及儲存音訊檔案。

若要使用系統的預設麥克風將語音轉換成文字 (語音辨識)，請執行下列命令：

spx recognize --microphone

執行該命令後，SPX 會開始聽取目前作用中輸入裝置上的音訊。 當您選取輸入時，其會停止聽取。 接著將會辨識口語音訊，並將其轉換為主控台輸出中的文字。

您也可以使用語音 CLI 來辨識音訊檔案中的語音。 執行以下命令：

spx recognize --file /path/to/file.wav

提示

如果您遇到困難或想要深入了解語音 CLI 的辨識選項，您可以執行 spx help recognize。

文字轉換語音 (語音合成)

下列命令會以文字作為輸入，並將合成的語音輸出至目前作用中的輸出裝置 (例如您的電腦喇叭)。

spx synthesize --text "Testing synthesis using the Speech CLI" --speakers

您也可以將合成的輸出儲存至檔案。 在此範例中，讓我們在執行命令的目錄中建立名為 my-sample.wav 的檔案。

spx synthesize --text "Enjoy using the Speech CLI." --audio output my-sample.wav

這些範例假設您要以英文進行測試。 不過，語音服務支援多種語言的語音合成。 您可以執行此命令來提取完整語音清單，或造訪語言支援頁面。

spx synthesize --voices

這是使用您探索到的其中一個語音的命令。

spx synthesize --text "Bienvenue chez moi." --voice fr-FR-AlainNeural --speakers

提示

如果您遇到困難或想要深入了解語音 CLI 的辨識選項，您可以執行 spx help synthesize。

語音轉換文字翻譯

透過語音 CLI，您也可以進行語音轉換文字翻譯。 執行下列命令以從您的預設麥克風擷取音訊，並以文字形式輸出翻譯。 請記住，您必須使用 translate 命令來提供 source 和 target 語言。

spx translate --microphone --source en-US --target ru-RU

當您翻譯至多種語言時，請將語言字碼之間以分號分隔 (;)。

spx translate --microphone --source en-US --target 'ru-RU;fr-FR;es-ES'

如果您想要儲存翻譯的輸出，請使用 --output 旗標。 在此範例中，您也會讀取檔案。

spx translate --file /some/file/path/input.wav --source en-US --target ru-RU --output file /some/file/path/russian_translation.txt

提示

如果您遇到困難或想要深入了解語音 CLI 的辨識選項，您可以執行 spx help translate。

下一步

• 安裝 GStreamer 以將語音 CLI 用於 MP3 和其他格式
• 語音 CLI 的組態選項
• 使用語音 CLI 的批次作業