再生アクションを使用してユーザーへの音声プロンプトをカスタマイズする

このガイドは、Azure Communication Services Call Automation SDK で提供されている再生アクションを使用して、参加者へのオーディオ ファイルの再生を開始するのに役立ちます。

前提条件

• アクティブなサブスクリプションを持つ Azure アカウント。詳細については、アカウントの無料作成に関するページを参照してください。
• Azure Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください。 このリソースの接続文字列を保存します。
• Call Automation SDK を使用して新しい Web サービス アプリケーションを作成する。
• お使いのオペレーティング システムに対応した最新の .NET ライブラリ。
• 最新の NuGet パッケージを取得します。

AI 機能のために

• Azure AI サービスを作成し、Azure Communication Services リソースに接続します。
• Azure AI サービス リソースのカスタム サブドメインを作成します。

新しい C# アプリケーションを作成する

オペレーティング システムのコンソール ウィンドウで、次の dotnet コマンドを使用して、新しい Web アプリケーションを作成します。

dotnet new web -n MyApplication

NuGet パッケージのインストール

まだ入手していない場合は、こちらから NuGet パッケージを取得できます。

(省略可能) プロンプトの再生にオーディオ ファイルを使用する場合は、オーディオ ファイルを準備します

参加者へのプロンプトやメッセージの再生に使用するオーディオ ファイルを作成します (まだない場合)。 オーディオ ファイルは、認証をサポートする Azure Communication Services からアクセスできる場所でホストされている必要があります。 オーディオ ファイルの再生を要求するときに使用できるように URL のコピーを保持します。 Azure Communication Services では、ID3V2TAG を使用した MP3 ファイルと WAV ファイル (16 KHz サンプル レートのモノラル 16 ビット PCM) の両方のファイルの種類がサポートされています。 。

「Audio Content Creation ツールを使用する音声合成」を使用して、独自のオーディオ ファイルの作成をテストできます。

(省略可能) 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 ファイル、モノラル、16 KHz であることを確認する必要があります。 オーディオ ファイルを再生するには、Azure Communication Services がアクセスできる場所でホストするファイルへの URI を Azure Communication Services に提供する必要があります。 Microsoft の 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 サービスでテキスト読み上げ出力をさらにカスタマイズする場合は、Call Automation を使用して再生アクションを呼び出すときに音声合成マークアップ言語 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 時間キャッシュされます。

Note

オーディオ ファイルのキャッシュは、動的プロンプトには適していません。 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); 

再生アクション イベントの更新を処理する

アプリケーションは、通話への応答時に Call Automation サービスに提供されたコールバック 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); 
    } 
} 

サポートされているその他のイベントの詳細については、Call Automation の概要に関するドキュメントを参照してください。

再生アクションを取り消す

すべてのメディア アクションを取り消します。保留中のすべてのメディア アクションが取り消されます。 このアクションは、キューに登録されている他の再生アクションも取り消します。

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

PlayCanceled イベントを逆シリアル化する方法の例:

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

前提条件

• アクティブなサブスクリプションを持つ Azure アカウント。詳細については、アカウントの無料作成に関するページを参照してください。
• Azure Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください
• Call Automation SDK を使用して新しい Web サービス アプリケーションを作成する。
• Java Development Kit バージョン 8 以降。
• Apache Maven。

AI 機能のために

• Azure AI サービスを作成し、Azure Communication Services リソースに接続します。
• Azure 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 Call Automation 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 では、ID3V2TAG を使用した MP3 ファイルと WAV ファイル (16 KHz サンプル レートのモノラル 16 ビット PCM) の両方のファイルの種類がサポートされています。 。

「Audio Content Creation ツールを使用する音声合成」を使用して、独自のオーディオ ファイルの作成をテストできます。

(省略可能) 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 ファイル、モノラル、16 KHz であることを確認する必要があります。 オーディオ ファイルを再生するには、Azure Communication Services がアクセスできる場所でホストするファイルへの URI を Azure Communication Services に提供する必要があります。 Microsoft の 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"); 

ソースの再生 - テキスト読み上げ 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 時間キャッシュされます。

Note

オーディオ ファイルのキャッシュは、動的プロンプトには適していません。 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(); 

再生アクション イベントの更新を処理する

アプリケーションは、通話への応答時に Call Automation サービスに提供されたコールバック 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()); 
    } 
} 

サポートされているその他のイベントの詳細については、Call Automation の概要に関するドキュメントを参照してください。

再生アクションを取り消す

すべてのメディア アクションを取り消します。保留中のすべてのメディア アクションが取り消されます。 このアクションは、キューに登録されている他の再生アクションも取り消します。

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()); 
} 

前提条件

• アクティブなサブスクリプションを持つ Azure アカウント。詳細については、アカウントの無料作成に関するページを参照してください。
• Azure Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください。 このリソースの接続文字列を保存します。
• Call Automation SDK を使用して新しい Web サービス アプリケーションを作成する。
• Node.js がインストールされている場合は、公式 Web サイトからインストールできます。

AI 機能のために

• Azure AI サービスを作成し、Azure Communication Services リソースに接続します。
• Azure AI サービス リソースのカスタム サブドメインを作成します。

新しい JavaScript アプリケーションを作成する

プロジェクト ディレクトリに新しい JavaScript アプリケーションを作成します。 次のコマンドを使って、新しい Node.js プロジェクトを初期化します。 これにより、プロジェクトの依存関係を管理するために使われる、プロジェクトの package.json ファイルが作成されます。

npm init -y

Azure Communication Services Call Automation パッケージをインストールする

npm install @azure/communication-call-automation

プロジェクト ディレクトリに新しい JavaScript ファイルを作成します。たとえば、app.js という名前を付けます。 このファイルに JavaScript コードを記述します。 次のコマンドを使用して、Node.js を使用してアプリケーションを実行します。 このコードは、作成した JavaScript コードを実行します。

node app.js

(省略可能) プロンプトの再生にオーディオ ファイルを使用する場合は、オーディオ ファイルを準備します

参加者へのプロンプトやメッセージの再生に使用するオーディオ ファイルを作成します (まだない場合)。 オーディオ ファイルは、認証をサポートする Azure Communication Services からアクセスできる場所でホストされている必要があります。 オーディオ ファイルの再生を要求するときに使用できるように URL のコピーを保持します。 Azure Communication Services では、ID3V2TAG を使用した MP3 ファイルと WAV ファイル (16 KHz サンプル レートのモノラル 16 ビット PCM) の両方のファイルの種類がサポートされています。

「Audio Content Creation ツールを使用する音声合成」を使用して、独自のオーディオ ファイルの作成をテストできます。

(省略可能) 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 ファイル、モノラル、16 KHz であることを確認する必要があります。 オーディオ ファイルを再生するには、Azure Communication Services がアクセスできる場所でホストするファイルへの URI を Azure Communication Services に提供する必要があります。 Microsoft の 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 サービスでテキスト読み上げ出力をさらにカスタマイズする場合は、Call Automation を使用して再生アクションを呼び出すときに音声合成マークアップ言語 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 時間キャッシュされます。

Note

オーディオ ファイルのキャッシュは、動的プロンプトには適していません。 Azure Communication Services に提供された URL を変更しても、キャッシュされた URL はそのまますぐに更新されません。 更新は、既存のキャッシュの有効期限が切れた後に発生します。

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

再生アクション イベントの更新を処理する

アプリケーションは、通話への応答時に Call Automation サービスに提供されたコールバック 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)); 
} 

サポートされているその他のイベントの詳細については、Call Automation の概要に関するドキュメントを参照してください。

再生アクションを取り消す

すべてのメディア アクションを取り消します。保留中のすべてのメディア アクションが取り消されます。 このアクションは、キューに登録されている他の再生アクションも取り消します。

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

PlayCanceled イベントを逆シリアル化する方法の例:

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

前提条件

• アクティブなサブスクリプションを持つ Azure アカウント。詳細については、アカウントの無料作成に関するページを参照してください。
• Azure Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください。 このリソースの接続文字列を保存します。
• Call Automation SDK を使用して新しい Web サービス アプリケーションを作成する。
• Python がインストールされている場合は、公式サイトからインストールできます。

AI 機能のために

• Azure AI サービスを作成し、Azure Communication Services リソースに接続します。
• Azure AI サービス リソースのカスタム サブドメインを作成します。

新しい Python アプリケーションを作成する

プロジェクトの Python 仮想環境を設定する

python -m venv play-audio-app

仮想環境をアクティブ化する

Windows では、次のコマンドを使います。

.\ play-audio-quickstart \Scripts\activate

Unix では、次のコマンドを使います。

source play-audio-quickstart /bin/activate

Azure Communication Services Call Automation パッケージをインストールする

pip install azure-communication-callautomation

プロジェクト ディレクトリにアプリケーション ファイルを作成し、たとえば app.py という名前を付けます。 このファイルに Python コードを記述します。

次のコマンドを使用して Python を使用してアプリケーションを実行し、コードを実行します。

python app.py

(省略可能) プロンプトの再生にオーディオ ファイルを使用する場合は、オーディオ ファイルを準備します

参加者へのプロンプトやメッセージの再生に使用するオーディオ ファイルを作成します (まだない場合)。 オーディオ ファイルは、認証をサポートする Azure Communication Services からアクセスできる場所でホストされている必要があります。 オーディオ ファイルの再生を要求するときに使用できるように URL のコピーを保持します。 Azure Communication Services では、MP3 ファイルと WAV ファイル (16 KHz サンプル レートのモノラル 16 ビット PCM) の両方のファイルの種類がサポートされています。 。

「Audio Content Creation ツールを使用する音声合成」を使用して、独自のオーディオ ファイルの作成をテストできます。

(省略可能) 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 ファイル、モノラル、16 KHz であることを確認する必要があります。 オーディオ ファイルを再生するには、Azure Communication Services がアクセスできる場所でホストするファイルへの URI を Azure Communication Services に提供する必要があります。 Microsoft の 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 サービスでテキスト読み上げ出力をさらにカスタマイズする場合は、Call Automation を使用して再生アクションを呼び出すときに音声合成マークアップ言語 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 時間キャッシュされます。

Note

オーディオ ファイルのキャッシュは、動的プロンプトには適していません。 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
)

再生アクション イベントの更新を処理する

アプリケーションは、通話への応答時に Call Automation サービスに提供されたコールバック 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 の概要に関するドキュメントを参照してください。

再生アクションを取り消す

すべてのメディア アクションを取り消します。保留中のすべてのメディア アクションが取り消されます。 このアクションは、キューに登録されている他の再生アクションも取り消します。

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"))

イベント コード

Status	コード	サブコード	メッセージ
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 サービスのクォータ制限を超過したシナリオの場合、こちらに記載されている手順でこの制限の引き上げを要求できます。

リソースをクリーンアップする

Communication Services サブスクリプションをクリーンアップして解除する場合は、リソースまたはリソース グループを削除できます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。 詳細については、リソースのクリーンアップに関する記事を参照してください。

次のステップ

• Call Automation の詳細を確認する
• 呼び出しでのユーザー入力の収集に関する詳細情報