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

在本文中，您將瞭解如何使用 Azure AI 語音 CLI（也稱為 SPX）來存取語音服務，例如語音轉換文字、文字到語音轉換和語音翻譯，而不需要撰寫任何程式代碼。 語音 CLI 已準備就緒，您可以使用 或 Shell 腳本，將語音服務 .bat 中的簡單工作流程自動化。

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

注意

在 PowerShell 中 ，停止剖析權杖 （--%） 應該遵循 spx。 例如，執行 spx --% config @region 以檢視目前的區域組態值。

下載並安裝

Windows

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

1. 為您的平臺安裝適用於 Visual Studio 2019 的 Microsoft 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

警告

這篇文章參考 CentOS，這是接近生命週期結束 (EOL) 狀態的 Linux 發行版本。 請據以考慮您的使用方式和規劃。 如需詳細資訊，請參閱 CentOS 生命週期結束指引。

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

• CentOS 7/8
• Debian 9/10
• Red Hat Enterprise Linux （RHEL） 7/8
• Ubuntu 18.04/20.04

注意

語音 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. 在 RHEL/CentOS Linux 上， 設定適用於 Linux 的 OpenSSL。

4. 在Ubuntu 20.04 Linux上， 安裝 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，請為您的平台安裝 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

建立資源組態

終端機

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

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

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

若要開始使用，您需要語音資源金鑰和區域識別碼（例如， eastuswestus。 在 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 會開始接聽目前使用中輸入裝置上的音訊。 當您選取 Enter 時，它會停止接聽。 接著，口語音頻會辨識並轉換成控制台輸出中的文字。

使用語音 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 以搭配 MP3 和其他格式使用語音 CLI
• 語音 CLI 的組態選項
• 使用語音 CLI 進行批次作業