빠른 시작: Azure AI Speech CLI 시작

2025-08-07

이 문서에서는 Azure AI Speech CLI(SPX라고도 함)를 사용하여 코드를 작성하지 않고도 음성 텍스트 변환, 텍스트 음성 변환 및 음성 번역과 같은 Speech Service에 액세스하는 방법에 대해 알아봅니다. Speech CLI는 프로덕션 환경에 즉시 사용할 수 있으며, .bat 또는 셸 스크립트를 사용하여 Speech Service에서 간단한 워크플로를 자동화하는 데 사용할 수 있습니다.

이 문서에서는 사용자가 명령 프롬프트 창, 터미널 또는 PowerShell에 대한 실무 지식이 있다고 가정합니다.

참고

PowerShell에서 stop-parsing 토큰(--%)은 spx 다음에 와야 합니다. 예를 들어 spx --% config @region을 실행하여 현재 지역 구성 값을 확인합니다.

다운로드 및 설치

Windows에 Speech CLI를 설치하려면 다음 단계를 수행합니다.

Visual Studio용 Microsoft Visual C++ 재배포 가능 패키지를 귀하의 플랫폼에 적합하게 설치하십시오. 처음 설치하는 경우 재시작이 필요할 수 있습니다.
.NET 8을 설치합니다.
다음 명령을 입력하여 .NET CLI를 통해 Speech CLI를 설치합니다.
```
dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
```
음성 CLI를 업데이트하려면 다음 명령을 입력합니다.
```
dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
```

음성 CLI에 대한 도움말을 보려면 spx 또는 spx help를 입력합니다.

글꼴 제한 사항

Windows에서 Speech CLI는 로컬 컴퓨터의 명령 프롬프트에서 사용할 수 있는 글꼴만 표시할 수 있습니다. Windows 터미널은 Speech CLI에서 대화형으로 생성하는 모든 글꼴을 지원합니다.

파일로 출력하면 메모장과 같은 텍스트 편집기나 Microsoft Edge와 같은 웹 브라우저도 모든 글꼴을 표시할 수 있습니다.

Speech CLI를 사용하는 x64 아키텍처를 지원하는 Linux 배포판은 다음과 같습니다.

Ubuntu 20.04/22.04/24.04
Debian 11/12

참고

Speech SDK는(Speech CLI 아님) 추가 아키텍처를 지원합니다. 자세한 내용은 Speech SDK 정보를 참조하세요.

x64 CPU에서 Linux에 Speech CLI를 설치하려면 다음 단계를 수행합니다.

.NET 8을 설치합니다.
다음 명령을 입력하여 .NET CLI를 통해 Speech CLI를 설치합니다.
```
dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
```
음성 CLI를 업데이트하려면 다음 명령을 입력합니다.
```
dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
```
압축된 오디오 지원을 위해 GStreamer를 설치합니다.

Speech CLI에 대한 도움말을 보려면 spx를 입력합니다.

macOS 10.14 이상에 음성 CLI를 설치하려면 다음 단계를 따릅니다.

.NET 8을 설치합니다.
다음 명령을 입력하여 .NET CLI를 통해 Speech CLI를 설치합니다.
```
dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
```
음성 CLI를 업데이트하려면 다음 명령을 입력합니다.
```
dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
```

음성 CLI에 대한 도움말을 보려면 spx 또는 spx help를 입력합니다.

다음 예제에서는 Docker 허브에서 공용 컨테이너 이미지를 가져옵니다. 익명 끌어오기 요청을 수행하는 대신 먼저 Docker 허브 계정(docker login)을 사용하여 인증하는 것이 좋습니다. 퍼블릭 콘텐츠를 사용할 때 안정성을 향상하려면 프라이빗 Azure Container Registry에서 이미지를 가져오고 관리합니다. 공용 이미지 사용에 대해 자세히 알아봅니다.

Docker 컨테이너에서 Speech CLI를 설치하려면 다음 단계를 수행합니다.

아직 설치되지 않은 경우 플랫폼에 Docker Desktop을 설치합니다.
새 명령 프롬프트 또는 터미널에서 다음 명령을 입력합니다.
```
docker pull msftspeech/spx
```

Speech CLI에 대한 도움말 정보를 표시하려면 다음 명령을 입력합니다.

docker run -it --rm msftspeech/spx help

컨테이너에 디렉터리 탑재

Speech CLI 도구는 구성 설정을 파일로 저장합니다. 명령을 수행할 때 (help 명령 제외) 시스템이 이러한 파일을 로드합니다.

Docker 컨테이너 내에서 Speech CLI를 사용하는 경우 도구에서 다음을 수행할 수 있도록 컨테이너의 로컬 디렉터리를 탑재해야 합니다.

구성 설정을 저장하거나 찾습니다.
음성의 오디오 파일과 같이 명령에 필요한 모든 파일을 읽거나 씁니다.

Windows에서 다음 명령을 입력하여 Speech CLI가 컨테이너 내에서 사용할 수 있는 로컬 디렉터리를 만듭니다.

mkdir c:\spx-data

Linux 또는 macOS에서 다음 명령을 터미널에 입력하여 디렉터리를 만들고 절대 경로를 확인합니다.

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

Speech CLI를 호출하면 절대 경로가 사용됩니다.

컨테이너에서 Speech CLI 실행

이 설명서에서는 비 Docker 설치에서 사용되는 Speech CLI spx 명령을 보여 줍니다. Docker 컨테이너에서 spx 명령을 호출하는 경우 Speech 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 로그인과 결합하고, Azure Portal을 사용하지 않고도 음성 키를 만들고, 일치하는 데이터 영역을 선택하는 SPX Init 가이드를 만들 수 있습니다. 키는 나중에 사용하기 위해 자동으로 저장됩니다.

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

az login
spx init

시작하려면 API 키 및 지역 식별자(예: eastus, westus)가 필요합니다. Azure Portal에서 Speech용 AI Foundry 리소스를 만듭니다. 자세한 내용은 AI Foundry 리소스 만들기를 참조하세요.

리소스 키와 지역 식별자를 구성하려면 다음 명령을 실행합니다.

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

키와 지역은 이후 Speech CLI 명령에 대해 저장됩니다. 현재 구성을 확인하려면 다음 명령을 실행합니다.

spx config @key
spx config @region

필요에 따라 저장된 값 중 하나를 제거하는 clear 옵션을 포함합니다.

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

시작하려면 API 키 및 지역 식별자(예: eastus, westus)가 필요합니다. Azure Portal에서 Speech용 AI Foundry 리소스를 만듭니다.

Speech 리소스 키 및 지역 식별자를 구성하려면 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 옵션을 포함하세요. CLI가 인증을 위해 음성 키를 사용하지 않도록 하려면 --key none도 지정해야 합니다. 예를 들어 spx recognize --key none --host wss://localhost:5000/ --file myaudio.wav를 실행하여 음성 텍스트 변환 컨테이너의 오디오 파일에서 음성을 인식합니다.

이 섹션에서는 처음으로 테스트 또는 실험을 수행할 때 도움이 되는 몇 가지 기본 SPX 명령을 보여줍니다. 도구 내 도움말을 보려면 다음 명령을 실행합니다.

spx

키워드를 기준으로 도움말 항목을 검색할 수 있습니다. 예를 들어 Speech CLI 사용 예제 목록을 보려면 다음 명령을 실행합니다.

spx help find --topics "examples"

recognize 명령에 대한 옵션을 보려면 다음 명령을 실행합니다.

spx help recognize

추가 도움말 명령이 콘솔 출력에 나열됩니다. 이러한 명령을 입력하여 하위 명령에 대한 자세한 도움말을 가져올 수 있습니다.

음성 - 텍스트 변환(음성 인식)

팁

문제가 발생하거나 Speech CLI 인식 옵션에 대해 자세히 알아보려면 spx help recognize를 실행할 수 있습니다.

마이크에서 음성 인식

다음 명령을 실행하여 마이크에서 음성 인식을 시작합니다.
```
spx recognize --microphone --source en-US
```
마이크에 대고 말하면 실시간으로 단어를 텍스트로 전사하는 것을 볼 수 있습니다. 음성 CLI는 일정 시간(30초) 동안 침묵 후 또는 Ctrl+C를 누를 때 중지됩니다.
```
Connection CONNECTED...
RECOGNIZED: I'm excited to try speech to text.
```

참고

Docker 컨테이너 내에서 Speech CLI를 실행하는 경우 컴퓨터의 마이크를 사용할 수 없습니다. 그러나 로컬에 탑재된 디렉터리에서는 오디오 파일을 읽고 저장할 수 있습니다.

파일에서 음성 인식

오디오 파일에서 음성을 인식하려면 --file 대신 --microphone을 사용합니다. MP4와 같은 압축 오디오 파일의 경우 GStreamer를 설치하고 --format을 사용합니다. 자세한 내용은 압축 입력 오디오 사용 방법을 참조하세요.

터미널
PowerShell

spx recognize --file YourAudioFile.wav
spx recognize --file YourAudioFile.mp4 --format any

spx recognize --file YourAudioFile.wav
spx --% recognize --file YourAudioFile.mp4 --format any

구문 목록

특정 단어 또는 발화의 인식 정확도를 높이려면 구 목록을 사용합니다. recognize 명령과 함께 인라인으로 또는 텍스트 파일을 사용해서 문구 목록을 포함할 수 있습니다.

터미널
PowerShell

spx recognize --microphone --phrases "Contoso;Jessie;Rehaan;"
spx recognize --microphone --phrases @phrases.txt

spx --% recognize --microphone --phrases "Contoso;Jessie;Rehaan;"
spx --% recognize --microphone --phrases @phrases.txt

언어 지원

음성 인식 언어를 변경하려면 en-US를 다른 지원되는 언어로 바꿉니다. 예를 들어 스페인어(스페인)의 경우 es-ES를 사용합니다. 언어를 지정하지 않으면 기본값은 en-US입니다.

spx recognize --microphone --source es-ES

연속 인식

30초보다 긴 오디오를 지속적으로 인식하려면 --continuous를 추가합니다.

spx recognize --microphone --source es-ES --continuous

텍스트 음성 변환(음성 합성)

팁

문제가 발생하거나 Speech CLI 인식 옵션에 대해 자세히 알아보려면 spx help synthesize를 실행할 수 있습니다.

다음 명령은 텍스트를 입력으로 사용한 다음, 합성된 음성을 현재 활성 출력 디바이스(예: 컴퓨터 스피커)로 출력합니다.

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

이 예제에서는 영어로 테스트하는 것으로 가정합니다. 그러나 Speech Service는 음성 합성을 다양한 언어로 지원합니다. 다음 명령을 실행하거나 언어 지원 페이지를 방문하여 전체 음성 목록을 끌어올 수 있습니다.

spx synthesize --voices

검색한 음성 중 하나를 사용하는 명령은 다음과 같습니다.

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

음성을 텍스트로 번역

팁

문제가 발생하거나 Speech CLI 번역 옵션에 대해 자세히 알아보려면 spx help translate을(를) 실행할 수 있습니다.

마이크에서 음성 번역

다음 명령을 실행하여 마이크에서 음성 번역을 시작합니다.
```
spx translate --source en-US --target it --microphone
```

마이크에 말하면 번역된 음성의 전사가 실시간으로 표시됩니다. 음성 CLI는 일정 시간(30초) 동안 침묵 후 또는 Ctrl+C를 누를 때 중지됩니다.

Connection CONNECTED...
TRANSLATING into 'it': Sono (from 'I'm')
TRANSLATING into 'it': Sono entusiasta (from 'I'm excited to')
TRANSLATING into 'it': Sono entusiasta di provare la parola (from 'I'm excited to try speech')
TRANSLATED into 'it': Sono entusiasta di provare la traduzione vocale. (from 'I'm excited to try speech translation.')

참고

파일에서 음성 번역

오디오 파일에서 음성을 번역하려면 --microphone 대신 --file을 사용하세요. MP4와 같은 압축 오디오 파일의 경우 GStreamer를 설치하고 --format을 사용합니다. 자세한 내용은 압축 입력 오디오 사용 방법을 참조하세요.

터미널
PowerShell

spx translate --source en-US --target it --file YourAudioFile.wav
spx translate --source en-US --target it --file YourAudioFile.mp4 --format any

spx translate --source en-US --target it --file YourAudioFile.wav
spx translate --source en-US --target it --file YourAudioFile.mp4 --format any

구문 목록

특정 단어 또는 발화의 인식 정확도를 높이려면 구 목록을 사용합니다. translate 명령과 함께 인라인으로 또는 텍스트 파일을 사용해서 문구 목록을 포함할 수 있습니다.

터미널
PowerShell

spx translate --source en-US --target it --microphone --phrases "Contoso;Jessie;Rehaan;"
spx translate --source en-US --target it --microphone --phrases @phrases.txt

spx --% translate --source en-US --target it --microphone --phrases "Contoso;Jessie;Rehaan;"
spx --% translate --source en-US --target it --microphone --phrases @phrases.txt

언어 지원

음성 인식 언어를 변경하려면 en-US를 다른 지원되는 언어로 바꿉니다. 대시(-) 구분 기호로 전체 로캘을 지정합니다. 예를 들어 스페인어(스페인)의 경우 es-ES입니다. 언어를 지정하지 않은 경우 기본 언어는 en-US입니다.

spx translate --microphone --source es-ES

번역 대상 언어를 변경하려면 it를 다른 지원되는 언어로 바꿉니다. 몇 가지 예외를 제외하고 로캘 대시(-) 구분 기호 앞에 오는 언어 코드만 지정합니다. 예를 들어 스페인어(스페인)의 경우 es-ES 대신 es를 사용합니다. 언어를 지정하지 않은 경우 기본 언어는 en입니다.

spx translate --microphone --target es

여러 대상 언어

여러 언어로 번역하는 경우 언어 코드를 세미콜론(;)으로 구분합니다.

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

연속 번역

30초보다 긴 오디오의 연속 번역의 경우 다음을 추가합니다 --continuous.

spx translate --source en-US --target it --microphone --continuous

다음 단계

피드백

이 페이지가 도움이 되었나요?

다음을 통해 공유

빠른 시작: Azure AI Speech CLI 시작

다운로드 및 설치

글꼴 제한 사항

리소스 구성 만들기

기본 사용법

음성 - 텍스트 변환(음성 인식)

마이크에서 음성 인식

파일에서 음성 인식

구문 목록

언어 지원

연속 인식

텍스트 음성 변환(음성 합성)

음성을 텍스트로 번역

마이크에서 음성 번역

파일에서 음성 번역

구문 목록

언어 지원

여러 대상 언어

번역 출력 저장

연속 번역

다음 단계

피드백

추가 리소스