다음을 통해 공유

재생 작업을 사용하여 사용자에게 음성 프롬프트 사용자 지정

  • 아티클

이 가이드는 Azure Communication Services 통화 자동화 SDK를 통해 제공되는 재생 작업을 사용하여 참가자에게 오디오 파일 재생을 시작하는 데 도움이 됩니다.

필수 조건

AI 기능

새 C# 애플리케이션 만들기

운영 체제의 콘솔 창에서 dotnet 명령을 사용하여 새 웹 애플리케이션을 만듭니다.

dotnet new web -n MyApplication

NuGet 패키지 설치

NuGet 패키지가 아직 없는 경우 여기에서 가져올 수 있습니다.

(선택 사항) 프롬프트 재생을 위해 오디오 파일을 사용하려는 경우 오디오 파일 준비

오디오 파일이 아직 없는 경우 참가자에게 프롬프트 및 메시지를 재생하는 데 사용할 오디오 파일을 만듭니다. 오디오 파일은 인증을 지원하는 Azure Communication Services에 액세스할 수 있는 위치에 호스트되어야 합니다. 오디오 파일을 재생하도록 요청하는 경우 사용할 수 있는 URL 복사본을 유지합니다. Azure Communication Services는 16KHz 샘플 속도로 모노 16비트 PCM인 ID3V2TAG 및 WAV 파일이 있는 MP3 파일의 파일 형식을 모두 지원합니다. .

오디오 콘텐츠 만들기 도구를 사용하는 음성 합성을 통해 사용자 고유의 오디오 파일 만들기를 테스트할 수 있습니다.

(선택 사항) Azure Cognitive Service를 Azure Communication Service에 커넥트

텍스트 음성 변환 기능을 사용하려면 Azure Cognitive Service를 Azure Communication Service에 연결해야 합니다.

통화 설정

이 시점에서 통화를 시작하는 방법에 익숙해져야 합니다. 전화 걸기에 대해 자세히 알아보려면 빠른 시작을 따릅니다. 여기에 제공된 코드 조각을 사용하여 통화에 응답하는 방법을 이해할 수도 있습니다.

var callAutomationClient = new CallAutomationClient("<Azure Communication Services connection string>");   

var answerCallOptions = new AnswerCallOptions("<Incoming call context once call is connected>", new Uri("<https://sample-callback-uri>"))  

{  
    CallIntelligenceOptions = new CallIntelligenceOptions() { CognitiveServicesEndpoint = new Uri("<Azure Cognitive Services Endpoint>") } 
};  

var answerCallResult = await callAutomationClient.AnswerCallAsync(answerCallOptions);

오디오 재생

통화가 설정되면 오디오를 재생하는 방법에 대한 여러 옵션이 있습니다. 통화에 참가한 참가자에게 오디오를 재생하거나 통화 중인 모든 참가자에게 오디오를 재생할 수 있습니다.

재생 원본 - 오디오 파일

오디오 파일을 사용하여 참가자에게 오디오를 재생하려면 오디오 파일이 WAV 파일, 모노 및 16KHz인지 확인해야 합니다. 오디오 파일을 재생하려면 Azure Communication Services에서 액세스할 수 있는 위치에서 호스트하는 파일에 대한 URI를 Azure Communication Services에 제공해야 합니다. SDK의 FileSource 형식을 사용하여 재생 작업에 대한 오디오 파일을 지정할 수 있습니다.

var playSource = new FileSource(new Uri(audioUri));

재생 원본 - 텍스트 음성 변환

Azure AI 서비스를 통해 텍스트 음성 변환을 사용하여 오디오를 재생하려면 재생하려는 텍스트와 SourceLocale 및 VoiceKind 또는 사용하려는 VoiceName을 제공해야 합니다. 여기서는 Azure AI 서비스에서 지원하는 모든 음성 이름( 전체 목록)을 지원합니다.

String textToPlay = "Welcome to Contoso";

// Provide SourceLocale and VoiceKind to select an appropriate voice. 
var playSource = new TextSource(textToPlay, "en-US", VoiceKind.Female); 

String textToPlay = "Welcome to Contoso"; 
 
// Provide VoiceName to select a specific voice. 
var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural");

재생 원본 - SSML을 사용한 텍스트 음성 변환

Azure AI 서비스를 사용하여 텍스트 음성 변환 출력을 더 많이 사용자 지정하려는 경우 호출 자동화를 통해 재생 작업을 호출할 때 Speech Synthesis Markup Language SSML을 사용할 수 있습니다. SSML을 사용하면 피치를 미세 조정하고, 일시 중지하고, 발음을 개선하고, 말하기 속도를 변경하고, 볼륨을 조정하고, 여러 음성을 특성화할 수 있습니다.

String ssmlToPlay = "<speak version=\"1.0\" xmlns=\"http://www.w3.org/2001/10/synthesis\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">Hello World!</voice></speak>"; 

var playSource = new SsmlSource(ssmlToPlay);

사용자 지정 음성 모델

프롬프트를 더 향상시키고 사용자 지정 음성 모델을 포함하려는 경우 재생 작업 텍스트 음성 변환이 이제 이러한 사용자 지정 음성을 지원합니다. 이는 고객에게 보다 로컬적이고 개인화된 환경을 제공하거나 기본 모델이 발음하려는 단어와 악센트를 다루지 않을 수 있는 상황이 있는 경우에 유용한 옵션입니다. 사용자 지정 모델을 만들고 배포하는 방법에 대한 자세한 내용은 이 가이드를 참조하세요.

사용자 지정 음성 이름 일반 텍스트 예제

String textToPlay = "Welcome to Contoso"; 
 
// Provide VoiceName and CustomVoiceEndpointId to select custom voice. 
var playSource = new TextSource(textToPlay)
    {
        VoiceName = "YourCustomVoiceName",
        CustomVoiceEndpointId = "YourCustomEndpointId"
    };

사용자 지정 음성 이름 SSML 예제


var playSource = new SsmlSource(ssmlToPlay,"YourCustomEndpointId");

오디오 재생에 사용할 playSource를 결정한 후에는 특정 참가자 또는 모든 참가자에게 재생할지 여부를 선택할 수 있습니다.

모든 참가자에게 오디오 재생

이 시나리오에서는 통화 중인 모든 참가자에게 오디오가 재생됩니다.

var playResponse = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .PlayToAllAsync(playSource);

특정 참가자에게 오디오 재생

이 시나리오에서는 오디오가 특정 참가자에게 재생됩니다.

var playTo = new List<CommunicationIdentifier> { targetParticipant }; 
var playResponse = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .PlayAsync(playSource, playTo);

루프에서 오디오 재생

루프 옵션을 사용하여 애플리케이션에서 발신자를 수락할 준비가 될 때까지 반복되는 보류 음악을 재생할 수 있습니다. 또는 애플리케이션 비즈니스 논리에 따라 발신자를 다음 논리적 단계로 진행합니다.

var playOptions = new PlayToAllOptions(playSource) 
{ 
    Loop = true 
}; 
var playResult = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .PlayToAllAsync(playOptions);

오디오 파일 캐싱을 사용하여 재생 향상

동일한 오디오 파일을 여러 번 재생하는 경우 애플리케이션에서 오디오 파일에 대한 sourceID를 Azure Communication Services에 제공할 수 있습니다. Azure Communication Services는 이 오디오 파일을 1시간 동안 캐시합니다.

참고 항목

오디오 파일 캐싱은 동적 프롬프트에 적합하지 않습니다. Azure Communication Services에 제공된 URL을 변경하는 경우 캐시된 URL은 즉시 업데이트되지 않습니다. 업데이트는 기존 캐시가 만료된 후에 발생합니다.

var playTo = new List<CommunicationIdentifier> { targetParticipant }; 
var playSource = new FileSource(new Uri(audioUri)) 
{ 
    PlaySourceCacheId = "<playSourceId>" 
}; 
var playResult = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .PlayAsync(playSource, playTo);

재생 작업 이벤트 업데이트 처리

애플리케이션은 호출에 응답할 때 호출 자동화 서비스에 제공된 콜백 URL에 대한 작업 수명 주기 이벤트 업데이트를 받습니다. 성공적인 플레이 이벤트 업데이트의 예입니다.

PlayCompleted 이벤트를 역직렬화하는 방법의 예:

if (acsEvent is PlayCompleted playCompleted) 
{ 
    logger.LogInformation("Play completed successfully, context={context}", playCompleted.OperationContext); 
}

PlayFailed 이벤트를 역직렬화하는 방법의 예:

if (acsEvent is PlayFailed playFailed) 
{ 
    if (MediaEventReasonCode.PlayDownloadFailed.Equals(playFailed.ReasonCode)) 
    { 
        logger.LogInformation("Play failed: download failed, context={context}", playFailed.OperationContext); 
    } 
    else if (MediaEventReasonCode.PlayInvalidFileFormat.Equals(playFailed.ReasonCode)) 
    { 
        logger.LogInformation("Play failed: invalid file format, context={context}", playFailed.OperationContext); 
    } 
    else 
    { 
        logger.LogInformation("Play failed, result={result}, context={context}", playFailed.ResultInformation?.Message, playFailed.OperationContext); 
    } 
}

지원되는 다른 이벤트에 대해 자세히 알아보려면 통화 자동화 개요 문서를 방문하세요.

재생 작업 취소

모든 미디어 작업을 취소하고 보류 중인 모든 미디어 작업이 취소됩니다. 이 작업은 대기 중인 다른 재생 작업도 취소합니다.

var cancelResult = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .CancelAllMediaOperationsAsync();

PlayCanceled 이벤트를 역직렬화하는 방법의 예:

if (acsEvent is PlayCanceled playCanceled) 
{ 
    logger.LogInformation("Play canceled, context={context}", playCanceled.OperationContext); 
}

필수 조건

AI 기능

새 Java 애플리케이션 만들기

터미널 또는 명령 창에서 Java 애플리케이션을 만들려는 디렉터리로 이동합니다. 여기에 표시된 명령을 실행하여 maven-archetype-quickstart 템플릿에서 Java 프로젝트를 생성합니다.

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

이전 명령은 인수와 이름이 같은 artifactId 디렉터리를 만듭니다. 이 디렉터리 아래의 src/main/java 디렉터리에는 프로젝트 소스 코드가 포함되어 있고, src/test/java 디렉터리에는 테스트 원본이 포함되어 있습니다.

‘generate’ 단계에서 artifactId와 동일한 이름의 디렉터리를 만들었습니다. 이 디렉터리에서 src/main/java 디렉터리에는 소스 코드가 있고 src/test/java 디렉터리에는 테스트가 있으며 pom.xml 파일은 프로젝트의 POM(프로젝트 개체 모델)입니다.

Java 8 이상을 사용하도록 애플리케이션 POM 파일을 업데이트합니다.

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

패키지 참조 추가

POM 파일에서 프로젝트에 대한 다음 참조를 추가합니다.

azure-communication-callautomation

Azure Communication Services 호출 자동화 SDK 패키지는 Azure SDK Dev Feed에서 검색됩니다.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-callautomation</artifactId>
  <version>1.0.0</version>
</dependency>

(선택 사항) 프롬프트 재생을 위해 오디오 파일을 사용하려는 경우 오디오 파일 준비

오디오 파일이 아직 없는 경우 참가자에게 프롬프트 및 메시지를 재생하는 데 사용할 오디오 파일을 만듭니다. 오디오 파일은 인증을 지원하는 Azure Communication Services에 액세스할 수 있는 위치에 호스트되어야 합니다. 오디오 파일을 재생하도록 요청하는 경우 사용할 수 있는 URL 복사본을 유지합니다. Azure Communication Services는 16KHz 샘플 속도로 모노 16비트 PCM인 ID3V2TAG 및 WAV 파일이 있는 MP3 파일의 파일 형식을 모두 지원합니다. .

오디오 콘텐츠 만들기 도구를 사용하는 음성 합성을 통해 사용자 고유의 오디오 파일 만들기를 테스트할 수 있습니다.

(선택 사항) Azure Cognitive Service를 Azure Communication Service에 커넥트

텍스트 음성 변환 기능을 사용하려면 Azure Cognitive Service를 Azure Communication Service에 연결해야 합니다.

App.java를 코드로 업데이트

선택한 편집기에서 App.java 파일을 열고, app.java를 코드로 업데이트 섹션에 제공된 코드로 업데이트합니다.

통화 설정

이 시점에서 통화를 시작하는 방법에 익숙해져야 합니다. 전화 걸기에 대해 자세히 알아보려면 빠른 시작을 따릅니다. 여기에 제공된 코드 조각을 사용하여 통화에 응답하는 방법을 이해할 수도 있습니다.

CallIntelligenceOptions callIntelligenceOptions = new CallIntelligenceOptions().setCognitiveServicesEndpoint("https://sample-cognitive-service-resource.cognitiveservices.azure.com/"); 
answerCallOptions = new AnswerCallOptions("<Incoming call context>", "<https://sample-callback-uri>").setCallIntelligenceOptions(callIntelligenceOptions); 
Response<AnswerCallResult> answerCallResult = callAutomationClient 
    .answerCallWithResponse(answerCallOptions) 
    .block();

오디오 재생

통화가 설정되면 오디오를 재생하는 방법에 대한 여러 옵션이 있습니다. 통화에 참가한 참가자에게 오디오를 재생하거나 통화 중인 모든 참가자에게 오디오를 재생할 수 있습니다.

재생 원본 - 오디오 파일

오디오 파일을 사용하여 참가자에게 오디오를 재생하려면 오디오 파일이 WAV 파일, 모노 및 16KHz인지 확인해야 합니다. 오디오 파일을 재생하려면 Azure Communication Services에서 액세스할 수 있는 위치에서 호스트하는 파일에 대한 URI를 Azure Communication Services에 제공해야 합니다. SDK의 FileSource 형식을 사용하여 재생 작업에 대한 오디오 파일을 지정할 수 있습니다.

var playSource = new FileSource(new Uri(audioUri));

재생 원본 - 텍스트 음성 변환

Azure AI 서비스를 통해 텍스트 음성 변환을 사용하여 오디오를 재생하려면 재생하려는 텍스트와 SourceLocale 및 VoiceKind 또는 사용하려는 VoiceName을 제공해야 합니다. 여기서는 Azure AI 서비스에서 지원하는 모든 음성 이름( 전체 목록)을 지원합니다.

// Provide SourceLocale and VoiceKind to select an appropriate voice.
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setSourceLocale("en-US") 
    .setVoiceKind(VoiceKind.FEMALE); 

// Provide VoiceName to select a specific voice.
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setVoiceName("en-US-ElizabethNeural");

재생 원본 - Text-to-Speech SSML

String ssmlToPlay = "<speak version=\"1.0\" xmlns=\"http://www.w3.org/2001/10/synthesis\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">Hello World!</voice></speak>"; 
var playSource = new SsmlSource() 
    .setSsmlText(ssmlToPlay);

사용자 지정 음성 모델

프롬프트를 더 향상시키고 사용자 지정 음성 모델을 포함하려는 경우 재생 작업 텍스트 음성 변환이 이제 이러한 사용자 지정 음성을 지원합니다. 이는 고객에게 보다 로컬적이고 개인화된 환경을 제공하거나 기본 모델이 발음하려는 단어와 악센트를 다루지 않을 수 있는 상황이 있는 경우에 유용한 옵션입니다. 사용자 지정 모델을 만들고 배포하는 방법에 대한 자세한 내용은 이 가이드를 참조하세요.

사용자 지정 음성 이름 일반 텍스트 예제

// Provide VoiceName and  to select a specific voice.
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setCustomVoiceName("YourCustomVoiceName")
    .setCustomVoiceEndpointId("YourCustomEndpointId");

사용자 지정 음성 이름 SSML 예제

String ssmlToPlay = "<speak version=\"1.0\" xmlns=\"http://www.w3.org/2001/10/synthesis\" xml:lang=\"en-US\"><voice name=\"YourCustomVoiceName\">Hello World!</voice></speak>"; 
var playSource = new SsmlSource() 
    .setSsmlText(ssmlToPlay)
    .setCustomVoiceEndpointId("YourCustomEndpointId");

오디오 재생에 사용할 playSource를 결정한 후에는 특정 참가자 또는 모든 참가자에게 재생할지 여부를 선택할 수 있습니다.

모든 참가자에게 오디오 재생

이 시나리오에서는 통화 중인 모든 참가자에게 오디오가 재생됩니다.

var playOptions = new PlayToAllOptions(playSource); 
var playResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .playToAllWithResponse(playOptions) 
    .block(); 
log.info("Play result: " + playResponse.getStatusCode());

특정 참가자에게 오디오 재생

이 시나리오에서는 오디오가 특정 참가자에게 재생됩니다.

var playTo = Arrays.asList(targetParticipant); 
var playOptions = new PlayOptions(playSource, playTo); 
var playResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .playWithResponse(playOptions) 
    .block();

루프에서 오디오 재생

루프 옵션을 사용하여 애플리케이션에서 발신자를 수락할 준비가 될 때까지 반복되는 보류 음악을 재생할 수 있습니다. 또는 애플리케이션 비즈니스 논리에 따라 발신자를 다음 논리적 단계로 진행합니다.

var playOptions = new PlayToAllOptions(playSource) 
    .setLoop(true); 
var playResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .playToAllWithResponse(playOptions) 
    .block();

오디오 파일 캐싱을 사용하여 재생 향상

동일한 오디오 파일을 여러 번 재생하는 경우 애플리케이션에서 오디오 파일에 대한 sourceID를 Azure Communication Services에 제공할 수 있습니다. Azure Communication Services는 이 오디오 파일을 1시간 동안 캐시합니다.

참고 항목

오디오 파일 캐싱은 동적 프롬프트에 적합하지 않습니다. Azure Communication Services에 제공된 URL을 변경하는 경우 캐시된 URL은 즉시 업데이트되지 않습니다. 업데이트는 기존 캐시가 만료된 후에 발생합니다.

var playTo = Arrays.asList(targetParticipant); 
var playSource = new FileSource() 
    .setUrl(audioUri) \
    .setPlaySourceCacheId("<playSourceId>"); 
var playOptions = new PlayOptions(playSource, playTo); 
var playResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .playWithResponse(playOptions) 
    .block();

재생 작업 이벤트 업데이트 처리

애플리케이션은 호출에 응답할 때 호출 자동화 서비스에 제공된 콜백 URL에 대한 작업 수명 주기 이벤트 업데이트를 받습니다. 성공적인 플레이 이벤트 업데이트의 예입니다.

PlayCompleted 이벤트를 역직렬화하는 방법의 예:

if (acsEvent instanceof PlayCompleted) { 
    PlayCompleted event = (PlayCompleted) acsEvent; 
    log.info("Play completed, context=" + event.getOperationContext()); 
}

PlayFailed 이벤트를 역직렬화하는 방법의 예:

if (acsEvent instanceof PlayFailed) { 
    PlayFailed event = (PlayFailed) acsEvent; 
    if (ReasonCode.Play.DOWNLOAD_FAILED.equals(event.getReasonCode())) { 
        log.info("Play failed: download failed, context=" + event.getOperationContext()); 
    } else if (ReasonCode.Play.INVALID_FILE_FORMAT.equals(event.getReasonCode())) { 
        log.info("Play failed: invalid file format, context=" + event.getOperationContext()); 
    } else { 
        log.info("Play failed, result=" + event.getResultInformation().getMessage() + ", context=" + event.getOperationContext()); 
    } 
}

지원되는 다른 이벤트에 대해 자세히 알아보려면 통화 자동화 개요 문서를 방문하세요.

재생 작업 취소

모든 미디어 작업을 취소하고 보류 중인 모든 미디어 작업이 취소됩니다. 이 작업은 대기 중인 다른 재생 작업도 취소합니다.

var cancelResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .cancelAllMediaOperationsWithResponse() 
    .block(); 
log.info("Cancel result: " + cancelResponse.getStatusCode());

PlayCanceled 이벤트를 역직렬화하는 방법의 예:

if (acsEvent instanceof PlayCanceled) { 
    PlayCanceled event = (PlayCanceled) acsEvent; 
    log.info("Play canceled, context=" + event.getOperationContext()); 
}

필수 조건

AI 기능

새 JavaScript 애플리케이션 만들기

프로젝트 디렉터리에 새 JavaScript 애플리케이션을 만듭니다. 다음 명령으로 새 Node.js 프로젝트를 초기화합니다. 그러면 프로젝트의 종속성을 관리하는 데 사용되는 프로젝트 package.json 파일이 만들어집니다.

npm init -y

Azure Communication Services 통화 자동화 패키지 설치

npm install @azure/communication-call-automation

프로젝트 디렉터리에 새 JavaScript 파일을 만듭니다(예: app.js). 이 파일에 JavaScript 코드를 작성합니다. 다음 명령을 통해 Node.js를 사용하여 애플리케이션을 실행합니다. 이 코드는 작성한 JavaScript 코드를 실행합니다.

node app.js

(선택 사항) 프롬프트 재생을 위해 오디오 파일을 사용하려는 경우 오디오 파일 준비

오디오 파일이 아직 없는 경우 참가자에게 프롬프트 및 메시지를 재생하는 데 사용할 오디오 파일을 만듭니다. 오디오 파일은 인증을 지원하는 Azure Communication Services에 액세스할 수 있는 위치에 호스트되어야 합니다. 오디오 파일을 재생하도록 요청하는 경우 사용할 수 있는 URL 복사본을 유지합니다. Azure Communication Services는 16KHz 샘플 속도로 모노 16비트 PCM인 ID3V2TAG 및 WAV 파일이 있는 MP3 파일의 파일 형식을 모두 지원합니다.

오디오 콘텐츠 만들기 도구를 사용하는 음성 합성을 통해 사용자 고유의 오디오 파일 만들기를 테스트할 수 있습니다.

(선택 사항) Azure Cognitive Service를 Azure Communication Service에 커넥트

텍스트 음성 변환 기능을 사용하려면 Azure Cognitive Service를 Azure Communication Service에 연결해야 합니다.

통화 설정

이 시점에서 통화를 시작하는 방법에 익숙해져야 합니다. 전화 걸기에 대해 자세히 알아보려면 빠른 시작을 따릅니다. 여기에 제공된 코드 조각을 사용하여 통화에 응답하는 방법을 이해할 수도 있습니다.

const callIntelligenceOptions: CallIntelligenceOptions = { "<https://sample-callback-uri>" }; 
        const answerCallOptions: AnswerCallOptions = { callIntelligenceOptions: callIntelligenceOptions };
  
await acsClient.answerCall("<Incoming call context>", "<https://sample-callback-uri>", answerCallOptions);

오디오 재생

통화가 설정되면 오디오를 재생하는 방법에 대한 여러 옵션이 있습니다. 통화에 참가한 참가자에게 오디오를 재생하거나 통화 중인 모든 참가자에게 오디오를 재생할 수 있습니다.

재생 원본 - 오디오 파일

오디오 파일을 사용하여 참가자에게 오디오를 재생하려면 오디오 파일이 WAV 파일, 모노 및 16KHz인지 확인해야 합니다. 오디오 파일을 재생하려면 Azure Communication Services에서 액세스할 수 있는 위치에서 호스트하는 파일에 대한 URI를 Azure Communication Services에 제공해야 합니다. SDK의 FileSource 형식을 사용하여 재생 작업에 대한 오디오 파일을 지정할 수 있습니다.

const playSource: FileSource = { url: audioUri, kind: "fileSource" };

재생 원본 - 텍스트 음성 변환

Azure AI 서비스를 통해 텍스트 음성 변환을 사용하여 오디오를 재생하려면 재생하려는 텍스트와 SourceLocale 및 VoiceKind 또는 사용하려는 VoiceName을 제공해야 합니다. 여기서는 Azure AI 서비스에서 지원하는 모든 음성 이름( 전체 목록)을 지원합니다.

const textToPlay = "Welcome to Contoso"; 
// Provide SourceLocale and VoiceKind to select an appropriate voice. 
const playSource: TextSource = { text: textToPlay, sourceLocale: "en-US", voiceKind: VoiceKind.Female, kind: "textSource" }; 

const textToPlay = "Welcome to Contoso"; 
// Provide VoiceName to select a specific voice. 
const playSource: TextSource = { text: textToPlay, voiceName: "en-US-ElizabethNeural", kind: "textSource" };

재생 원본 - SSML을 사용한 텍스트 음성 변환

Azure AI 서비스를 사용하여 텍스트 음성 변환 출력을 더 많이 사용자 지정하려는 경우 호출 자동화를 통해 재생 작업을 호출할 때 Speech Synthesis Markup Language SSML을 사용할 수 있습니다. SSML을 사용하면 피치를 미세 조정하고, 일시 중지하고, 발음을 개선하고, 말하기 속도를 변경하고, 볼륨을 조정하고, 여러 음성을 특성화할 수 있습니다.

const ssmlToPlay = "<speak version=\"1.0\" xmlns=\"http://www.w3.org/2001/10/synthesis\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">Hello World!</voice></speak>"; 
const playSource: SsmlSource = { ssmlText: ssmlToPlay, kind: "ssmlSource" };

사용자 지정 음성 모델

프롬프트를 더 향상시키고 사용자 지정 음성 모델을 포함하려는 경우 재생 작업 텍스트 음성 변환이 이제 이러한 사용자 지정 음성을 지원합니다. 이는 고객에게 보다 로컬적이고 개인화된 환경을 제공하거나 기본 모델이 발음하려는 단어와 악센트를 다루지 않을 수 있는 상황이 있는 경우에 유용한 옵션입니다. 사용자 지정 모델을 만들고 배포하는 방법에 대한 자세한 내용은 이 가이드를 참조하세요.

사용자 지정 음성 이름 일반 텍스트 예제

const textToPlay = "Welcome to Contoso";
// Provide VoiceName and CustomVoiceEndpointID to play your custom voice
const playSource: TextSource = { text: textToPlay, voiceName: "YourCustomVoiceName", customVoiceEndpointId: "YourCustomEndpointId"}

사용자 지정 음성 이름 SSML 예제

const ssmlToPlay = "<speak version=\"1.0\" xmlns=\"http://www.w3.org/2001/10/synthesis\" xml:lang=\"en-US\"><voice name=\"YourCustomVoiceName\">Hello World!</voice></speak>"; 
const playSource: SsmlSource = { ssmlText: ssmlToPlay, kind: "ssmlSource", customVoiceEndpointId: "YourCustomEndpointId"};

오디오 재생에 사용할 playSource를 결정한 후에는 특정 참가자 또는 모든 참가자에게 재생할지 여부를 선택할 수 있습니다.

오디오 재생 - 모든 참가자

이 시나리오에서는 통화 중인 모든 참가자에게 오디오가 재생됩니다.

await callAutomationClient.getCallConnection(callConnectionId) 
    .getCallMedia() 
    .playToAll([ playSource ]);

오디오 재생 - 특정 참가자

이 시나리오에서는 오디오가 특정 참가자에게 재생됩니다.

await callAutomationClient.getCallConnection(callConnectionId) 
    .getCallMedia() 
    .play([ playSource ], [ targetParticipant ]);

루프에서 오디오 재생

루프 옵션을 사용하여 애플리케이션에서 발신자를 수락할 준비가 될 때까지 반복되는 보류 음악을 재생할 수 있습니다. 또는 애플리케이션 비즈니스 논리에 따라 발신자를 다음 논리적 단계로 진행합니다.

const playOptions: PlayOptions = { loop: true }; 
await callAutomationClient.getCallConnection(callConnectionId) 
    .getCallMedia() 
    .playToAll([ playSource ], playOptions);

오디오 파일 캐싱을 사용하여 재생 향상

동일한 오디오 파일을 여러 번 재생하는 경우 애플리케이션에서 오디오 파일에 대한 sourceID를 Azure Communication Services에 제공할 수 있습니다. Azure Communication Services는 이 오디오 파일을 1시간 동안 캐시합니다.

참고 항목

오디오 파일 캐싱은 동적 프롬프트에 적합하지 않습니다. Azure Communication Services에 제공된 URL을 변경하는 경우 캐시된 URL은 즉시 업데이트되지 않습니다. 업데이트는 기존 캐시가 만료된 후에 발생합니다.

const playSource: FileSource = { url: audioUri, playsourcacheid: "<playSourceId>", kind: "fileSource" }; 
await callAutomationClient.getCallConnection(callConnectionId) 
.getCallMedia() 
.play([ playSource ], [ targetParticipant ]);

재생 작업 이벤트 업데이트 처리

애플리케이션은 호출에 응답할 때 호출 자동화 서비스에 제공된 콜백 URL에 대한 작업 수명 주기 이벤트 업데이트를 받습니다.

PlayCompleted 이벤트를 역직렬화하는 방법의 예:

if (event.type === "Microsoft.Communication.PlayCompleted") { 
    console.log("Play completed, context=%s", eventData.operationContext); 
}

PlayFailed 이벤트를 역직렬화하는 방법의 예:

if (event.type === "Microsoft.Communication.PlayFailed") { 
    console.log("Play failed: data=%s", JSON.stringify(eventData)); 
}

지원되는 다른 이벤트에 대해 자세히 알아보려면 통화 자동화 개요 문서를 방문하세요.

재생 작업 취소

모든 미디어 작업을 취소하고 보류 중인 모든 미디어 작업이 취소됩니다. 이 작업은 대기 중인 다른 재생 작업도 취소합니다.

await callAutomationClient.getCallConnection(callConnectionId) 
.getCallMedia() 
.cancelAllOperations();

PlayCanceled 이벤트를 역직렬화하는 방법의 예:

if (event.type === "Microsoft.Communication.PlayCanceled") {
    console.log("Play canceled, context=%s", eventData.operationContext);
}

필수 조건

AI 기능

새 Python 애플리케이션 만들기

프로젝트의 Python 가상 환경 설정

python -m venv play-audio-app

가상 환경 활성화

창에서 다음 명령을 사용합니다.

.\ play-audio-quickstart \Scripts\activate

Unix의 경우 다음 명령을 사용합니다.

source play-audio-quickstart /bin/activate

Azure Communication Services 통화 자동화 패키지 설치

pip install azure-communication-callautomation

프로젝트 디렉터리에 애플리케이션 파일을 만듭니다(예: app.py). 이 파일에 Python 코드를 작성합니다.

다음 명령으로 Python을 사용하여 애플리케이션을 실행하여 코드를 실행합니다.

python app.py

(선택 사항) 프롬프트 재생을 위해 오디오 파일을 사용하려는 경우 오디오 파일 준비

오디오 파일이 아직 없는 경우 참가자에게 프롬프트 및 메시지를 재생하는 데 사용할 오디오 파일을 만듭니다. 오디오 파일은 인증을 지원하는 Azure Communication Services에 액세스할 수 있는 위치에 호스트되어야 합니다. 오디오 파일을 재생하도록 요청하는 경우 사용할 수 있는 URL 복사본을 유지합니다. Azure Communication Services는 16KHz 샘플 속도의 모노 16비트 PCM인 MP3 및 WAV 파일의 파일 형식을 모두 지원합니다. .

오디오 콘텐츠 만들기 도구를 사용하는 음성 합성을 통해 사용자 고유의 오디오 파일 만들기를 테스트할 수 있습니다.

(선택 사항) Azure Cognitive Service를 Azure Communication Service에 커넥트

텍스트 음성 변환 기능을 사용하려면 Azure Cognitive Service를 Azure Communication Service에 연결해야 합니다.

통화 설정

이 시점에서 통화를 시작하는 방법에 익숙해져야 합니다. 전화 걸기에 대해 자세히 알아보려면 빠른 시작을 따릅니다. 여기에 제공된 코드 조각을 사용하여 통화에 응답하는 방법을 이해할 수도 있습니다.

call_automation_client.answer_call(
    incoming_call_context="<Incoming call context>",
    callback_url="<https://sample-callback-uri>",
    cognitive_services_endpoint=COGNITIVE_SERVICE_ENDPOINT,
)

오디오 재생

통화가 설정되면 오디오를 재생하는 방법에 대한 여러 옵션이 있습니다. 통화에 참가한 참가자에게 오디오를 재생하거나 통화 중인 모든 참가자에게 오디오를 재생할 수 있습니다.

재생 원본 - 오디오 파일

오디오 파일을 사용하여 참가자에게 오디오를 재생하려면 오디오 파일이 WAV 파일, 모노 및 16KHz인지 확인해야 합니다. 오디오 파일을 재생하려면 Azure Communication Services에서 액세스할 수 있는 위치에서 호스트하는 파일에 대한 URI를 Azure Communication Services에 제공해야 합니다. SDK의 FileSource 형식을 사용하여 재생 작업에 대한 오디오 파일을 지정할 수 있습니다.

play_source = FileSource(url=audioUri)

재생 원본 - 텍스트 음성 변환

Azure AI 서비스를 통해 텍스트 음성 변환을 사용하여 오디오를 재생하려면 재생하려는 텍스트와 SourceLocale 및 VoiceKind 또는 사용하려는 VoiceName을 제공해야 합니다. 여기서는 Azure AI 서비스에서 지원하는 모든 음성 이름( 전체 목록)을 지원합니다.

text_to_play = "Welcome to Contoso"

# Provide SourceLocale and VoiceKind to select an appropriate voice. 
play_source = TextSource(
    text=text_to_play, source_locale="en-US", voice_kind=VoiceKind.FEMALE
)
play_to = [target_participant]
call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, play_to=play_to
) 

text_to_play = "Welcome to Contoso"

# Provide VoiceName to select a specific voice. 
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural")
play_to = [target_participant]
call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, play_to=play_to
)

재생 원본 - SSML을 사용한 텍스트 음성 변환

Azure AI 서비스를 사용하여 텍스트 음성 변환 출력을 더 많이 사용자 지정하려는 경우 호출 자동화를 통해 재생 작업을 호출할 때 Speech Synthesis Markup Language SSML을 사용할 수 있습니다. SSML을 사용하면 피치를 미세 조정하고, 일시 중지하고, 발음을 개선하고, 말하기 속도를 변경하고, 볼륨을 조정하고, 여러 음성을 특성화할 수 있습니다.

ssmlToPlay = '<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US"><voice name="en-US-JennyNeural">Hello World!</voice></speak>'

play_source = SsmlSource(ssml_text=ssmlToPlay)

play_to = [target_participant]

call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, play_to=play_to
)

사용자 지정 음성 모델

프롬프트를 더 향상시키고 사용자 지정 음성 모델을 포함하려는 경우 재생 작업 텍스트 음성 변환이 이제 이러한 사용자 지정 음성을 지원합니다. 이는 고객에게 보다 로컬적이고 개인화된 환경을 제공하거나 기본 모델이 발음하려는 단어와 악센트를 다루지 않을 수 있는 상황이 있는 경우에 유용한 옵션입니다. 사용자 지정 모델을 만들고 배포하는 방법에 대한 자세한 내용은 이 가이드를 참조하세요.

사용자 지정 음성 이름 일반 텍스트 예제

text_to_play = "Welcome to Contoso"

# Provide VoiceName to select a specific voice. 
play_source = TextSource(text=text_to_play, voice_name="YourCustomVoiceName", custom_voice_endpoint_id = "YourCustomEndpointId")
play_to = [target_participant]
call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, play_to=play_to
)

사용자 지정 음성 이름 SSML 예제

ssmlToPlay = '<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US"><voice name="YourCustomVoiceName">Hello World!</voice></speak>'

play_source = SsmlSource(ssml_text=ssmlToPlay, custom_voice_endpoint_id="YourCustomEndpointId")

play_to = [target_participant]

call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, play_to=play_to
)

오디오 재생에 사용할 playSource를 결정한 후에는 특정 참가자 또는 모든 참가자에게 재생할지 여부를 선택할 수 있습니다.

오디오 재생 - 모든 참가자

통화 중인 모든 참가자에게 미리 녹음된 오디오 파일을 재생합니다.

text_to_play = "Welcome to Contoso"

play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural")

call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source
)

오디오 재생 - 특정 참가자

통화의 특정 참가자에게 미리 녹음된 오디오 파일을 재생합니다.

play_to = [target_participant]

call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, play_to=play_to
)

루프에서 오디오 재생

루프 옵션을 사용하여 애플리케이션에서 발신자를 수락할 준비가 될 때까지 반복되는 보류 음악을 재생할 수 있습니다. 또는 애플리케이션 비즈니스 논리에 따라 발신자를 다음 논리적 단계로 진행합니다.

text_to_play = "Welcome to Contoso"

play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural")

call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, loop=True
)

오디오 파일 캐싱을 사용하여 재생 향상

동일한 오디오 파일을 여러 번 재생하는 경우 애플리케이션에서 오디오 파일에 대한 sourceID를 Azure Communication Services에 제공할 수 있습니다. Azure Communication Services는 이 오디오 파일을 1시간 동안 캐시합니다.

참고 항목

오디오 파일 캐싱은 동적 프롬프트에 적합하지 않습니다. Azure Communication Services에 제공된 URL을 변경하는 경우 캐시된 URL은 즉시 업데이트되지 않습니다. 업데이트는 기존 캐시가 만료된 후에 발생합니다.

play_source = FileSource(url=audioUri, play_source_cache_id="<playSourceId>")

play_to = [target_participant]

call_automation_client.get_call_connection(call_connection_id).play_media(
    play_source=play_source, play_to=play_to
)

재생 작업 이벤트 업데이트 처리

애플리케이션은 호출에 응답할 때 호출 자동화 서비스에 제공된 콜백 URL에 대한 작업 수명 주기 이벤트 업데이트를 받습니다.

PlayCompleted 이벤트를 역직렬화하는 방법의 예:

if event.type == "Microsoft.Communication.PlayCompleted":

    app.logger.info("Play completed, context=%s", event.data.get("operationContext"))

PlayFailed 이벤트를 역직렬화하는 방법의 예:

if event.type == "Microsoft.Communication.PlayFailed":

    app.logger.info("Play failed: data=%s", event.data)

지원되는 다른 이벤트에 대해 자세히 알아보려면 통화 자동화 개요 문서를 방문하세요.

재생 작업 취소

모든 미디어 작업을 취소하고 보류 중인 모든 미디어 작업이 취소됩니다. 이 작업은 대기 중인 다른 재생 작업도 취소합니다.

call_automation_client.get_call_connection(
    call_connection_id
).cancel_all_media_operations()

PlayCanceled 이벤트를 역직렬화하는 방법의 예:

if event.type == "Microsoft.Communication.PlayCanceled":

    app.logger.info("Play canceled, context=%s", event.data.get("operationContext"))

이벤트 코드

상태 코드 하위 코드 메시지
PlayCompleted 200 0 작업이 완료되었습니다.
PlayCanceled 400 8508 작업이 실패하여 작업이 취소되었습니다.
PlayFailed 400 8535 작업이 실패했습니다. 파일 형식이 잘못되었습니다.
PlayFailed 400 8536 작업이 실패했습니다. 파일을 다운로드할 수 없습니다.
PlayFailed 400 8565 작업 실패, Azure AI 서비스에 대한 잘못된 요청이 발생했습니다. 입력 매개 변수를 확인하세요.
PlayFailed 401 8565 작업 실패, Azure AI 서비스 인증 오류가 발생했습니다.
PlayFailed 403 8565 작업 실패, Azure AI 서비스에 대한 요청이 금지되었으며, 해당 요청에서 사용하는 무료 구독 할당량이 부족합니다.
PlayFailed 429 8565 작업 실패, 요청이 Azure AI 서비스 구독에 대해 허용되는 동시 요청 수를 초과했습니다.
PlayFailed 408 8565 작업 실패, Azure AI 서비스에 대한 요청 시간이 초과되었습니다.
PlayFailed 500 9999 알 수 없는 내부 서버 오류
PlayFailed 500 8572 재생 서비스 종료로 인해 작업이 실패했습니다.

알려진 제한 사항

  • 텍스트 음성 변환 텍스트 프롬프트는 최대 400자를 지원합니다. 프롬프트가 이보다 길면 텍스트 음성 변환 기반 재생 작업에 SSML을 사용하는 것이 좋습니다.
  • Speech Service 할당량 한도를 초과하는 시나리오의 경우 여기에 설명된 단계에 따라 이 lilmit를 늘리도록 요청할 수 있습니다.

리소스 정리

Communication Services 구독을 정리하고 제거하려면 리소스 또는 리소스 그룹을 삭제하면 됩니다. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다. 리소스 정리에 대해 자세히 알아보세요.

다음 단계