Freigeben über

Anpassen von sprachbasierten Eingabeaufforderungen für Benutzer mit der Wiedergabeaktion

  • Artikel

Dieser Leitfaden enthält hilfreiche Informationen zu den ersten Schritten beim Wiedergeben von Audiodateien für Teilnehmer. Dazu verwenden Sie die Wiedergabeaktion, die über das Azure Communication Services Call Automation SDK bereitgestellt wird.

Voraussetzungen

Für KI-Features

Erstellen einer neuen C#-Anwendung

Verwenden Sie im Konsolenfenster Ihres Betriebssystems den Befehl dotnet, um eine neue Webanwendung zu erstellen.

dotnet new web -n MyApplication

Installieren des NuGet-Pakets

Das NuGet-Paket kann hier abgerufen werden, sofern noch nicht geschehen.

(Optional) Vorbereiten der Audiodatei, wenn Sie Audiodateien für die Wiedergabe von Prompts verwenden möchten

Erstellen Sie eine Audiodatei, wenn Sie noch keine haben, um Eingabeaufforderungen und Nachrichten für Teilnehmer wiederzugeben. Die Audiodatei muss an einem Speicherort gehostet werden, der für Azure Communication Services zugänglich ist und Authentifizierung unterstützt. Behalten Sie eine Kopie der URL, die Sie beim Anfordern der Wiedergabe der Audiodatei verwenden können. Azure Communication Services unterstützt die Dateitypen MP3 mit ID3V2TAG und WAV, Mono, 16-Bit-PCM mit 16 KHz Abtastrate. .

Sie können die Erstellung Ihrer eigenen Audiodatei testen, indem Sie unsere Sprachsynthese mit dem Audioinhaltserstellungs-Tool verwenden.

(Optional) Verknüpfen von Azure Cognitive Services mit Azure Communication Services

Wenn Sie Sprachsynthesefunktionen verwenden möchten, müssen Sie Azure Cognitive Services mit Azure Communication Services verknüpfen.

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. Sie können auch das folgende Codeschnipsel verwenden, um zu verstehen, wie auf einen Anruf reagiert wird.

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

Audiowiedergabe

Nachdem der Anruf eingerichtet wurde, gibt es mehrere Optionen für die Wiedergabe der Audiodatei. Sie können Audio für den Teilnehmer, der dem Anruf gerade beigetreten ist, oder für alle Teilnehmer des Anrufs wiedergeben.

Wiedergabequelle – Audiodatei

Um Audio mithilfe von Audiodateien für Teilnehmer wiederzugeben, müssen Sie sicherstellen, dass es sich bei der Audiodatei um eine WAV-Datei (Mono) mit 16 KHz handelt. Um Audiodateien wiederzugeben, müssen Sie sicherstellen, dass Sie Azure Communication Services mit einem URI für eine Datei bereitstellen, die Sie an einem Ort hosten, an dem Azure Communication Services darauf zugreifen kann. Der FileSource-Typ in unserem SDK kann verwendet werden, um Audiodateien für die Wiedergabeaktion anzugeben.

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

Wiedergabequelle – Sprachsynthese

Um Audio mit Sprachsynthese über Azure KI Services wiederzugeben, müssen Sie den Text bereitstellen, den Sie wiedergeben möchten, sowie entweder die „SourceLocale“ und „VoiceKind“ oder „VoiceName“, die Sie verwenden möchten. Wir unterstützen alle Stimmnamen, die von Azure KI Services unterstützt werden. Die vollständige Liste finden Sie hier.

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

Wiedergabequelle – Sprachsynthese mit SSML

Wenn Sie Ihre Sprachsyntheseausgabe mit Azure KI Services weiter anpassen möchten, können Sie Speech Synthesis Markup Language SSML- verwenden, wenn Sie Ihre Wiedergabeaktion über die Anrufautomatisierung aufrufen. Mit SSML können Sie die Tonhöhe, Pausen und die Aussprache verbessern, die Sprechgeschwindigkeit ändern, die Lautstärke anpassen und mehrere Stimmen attributieren.

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

Benutzerdefinierte Stimmmodelle

Wenn Sie Ihre Prompts weiter verbessern und benutzerdefinierte Stimmmodelle einbeziehen möchten, unterstützt die Wiedergabeaktion „Sprachsynthese“ jetzt diese benutzerdefinierten Stimmen. Diese sind gut geeignet, wenn Sie versuchen, Kunden eine lokale, personalisierte Erfahrung zu bieten, oder in Situationen, in denen die Standardmodelle möglicherweise nicht die Wörter und Akzente abdecken, die ausgesprochen werden sollen. Weitere Informationen zum Erstellen und Bereitstellen von benutzerdefinierten Modellen finden Sie in diesem Leitfaden.

Reguläres Textbeispiel für benutzerdefinierte Stimmnamen

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

SSML-Beispiel für benutzerdefinierte Stimmnamen


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

Nachdem Sie entschieden haben, welche Wiedergabequelle Sie für die Audiowiedergabe verwenden möchten, können Sie auswählen, ob Sie sie für einen bestimmten Teilnehmer oder allen Teilnehmer wiedergeben möchten.

Wiedergeben von Audio für alle Teilnehmer

In diesem Szenario wird Audio für alle Teilnehmer im Anruf wiedergegeben.

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

Wiedergeben von Audio für einen bestimmten Teilnehmer

In diesem Szenario wird Audio für einen bestimmten Teilnehmer wiedergegeben.

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

Wiedergeben von Audio als Schleife

Sie können die Option für die Wiedergabeschleife verwenden, um Warteschleifenmusik wiederzugeben, die so lange läuft, bis Ihre Anwendung bereit ist, den Anruf anzunehmen. Oder leiten Sie den Anrufer auf der Grundlage der Geschäftslogik Ihrer Anwendung zum nächsten logischen Schritt weiter.

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

Verbessern der Wiedergabe mit der Zwischenspeicherung von Audiodateien

Wenn Sie dieselbe Audiodatei mehrmals wiedergeben, kann Ihre Anwendung die Quell-ID der Audiodatei für Azure Communication Services bereitstellen. Azure Communication Services speichert diese Audiodatei eine Stunde lang zwischen.

Hinweis

Das Zwischenspeichern von Audiodateien eignet sich nicht für dynamische Prompts. Wenn Sie die für Azure Communication Services bereitgestellte URL ändern, wird die zwischengespeicherte URL nicht sofort aktualisiert. Das Update erfolgt, nachdem der vorhandene Cache abgelaufen ist.

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

Behandeln von Ereignisupdates für die Wiedergabeaktion

Ihre Anwendung erhält Ereignisupdates für den Aktionslebenszyklus unter der Rückruf-URL, die zum Zeitpunkt der Anrufannahme für den Anrufautomatisierungsdienst bereitgestellt wurde. Nachfolgend sehen Sie ein Beispiel für ein erfolgreiches Wiedergabeereignisupdate:

Beispiel zur Deserialisierung des PlayCompleted-Ereignisses:

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

Beispiel zur Deserialisierung des PlayFailed-Ereignisses:

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

Weitere Informationen zu anderen unterstützten Ereignissen finden Sie im Übersichtsdokument zur Anrufautomatisierung.

Abbrechen der Wiedergabeaktion

Wenn Sie alle Medienvorgänge abbrechen, werden alle ausstehenden Medienvorgänge abgebrochen. Mit dieser Aktion werden auch andere Wiedergabeaktionen in der Warteschlange abgebrochen.

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

Beispiel zur Deserialisierung des PlayCanceled-Ereignisses:

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

Voraussetzungen

Für KI-Features

Erstellen einer neuen Java-Anwendung

Navigieren Sie in Ihrem Terminal- oder Befehlsfenster zu dem Verzeichnis, in dem Sie Ihre Java-Anwendung erstellen möchten. Führen Sie den hier gezeigten Befehl aus, um das Java-Projekt aus der Vorlage „maven-archetype-quickstart“ zu generieren.

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

Der vorherige Befehl erstellt ein Verzeichnis mit demselben Namen wie das artifactId-Argument. In diesem Verzeichnis enthält das Verzeichnis src/main/java den Projektquellcode, und das Verzeichnis src/test/java enthält die Testquelle.

Sie sehen, dass über den Schritt „generate“ ein Verzeichnis mit dem gleichen Namen wie für „artifactId“ erstellt wurde. In diesem Verzeichnis enthält der Ordner src/main/java den Quellcode, src/test/java enthält die Tests, und die Datei pom.xml repräsentiert das Projektobjektmodell (POM).

Aktualisieren Sie die POM-Datei Ihrer Anwendung für die Verwendung von Java 8 oder höher:

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

Hinzufügen von Paketverweisen

Fügen Sie in Ihrer POM-Datei den folgenden Verweis für das Projekt hinzu:

azure-communication-callautomation

Das Paket für das Call Automation SDK für Azure Communication Services wird aus dem Azure SDK-Entwicklungsfeed abgerufen.

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

(Optional) Vorbereiten der Audiodatei, wenn Sie Audiodateien für die Wiedergabe von Prompts verwenden möchten

Erstellen Sie eine Audiodatei, wenn Sie noch keine haben, um Eingabeaufforderungen und Nachrichten für Teilnehmer wiederzugeben. Die Audiodatei muss an einem Speicherort gehostet werden, der für Azure Communication Services zugänglich ist und Authentifizierung unterstützt. Behalten Sie eine Kopie der URL, die Sie beim Anfordern der Wiedergabe der Audiodatei verwenden können. Azure Communication Services unterstützt die Dateitypen MP3 mit ID3V2TAG und WAV, Mono, 16-Bit-PCM mit 16 KHz Abtastrate. .

Sie können die Erstellung Ihrer eigenen Audiodatei testen, indem Sie unsere Sprachsynthese mit dem Audioinhaltserstellungs-Tool verwenden.

(Optional) Verknüpfen von Azure Cognitive Services mit Azure Communication Services

Wenn Sie Sprachsynthesefunktionen verwenden möchten, müssen Sie Azure Cognitive Services mit Azure Communication Services verknüpfen.

Aktualisieren von App.java mit Code

Öffnen Sie in dem Editor Ihrer Wahl die Datei „App.java“, und aktualisieren Sie sie mit dem Code aus dem Abschnitt Aktualisieren von App.java mit Code.

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. Sie können auch das folgende Codeschnipsel verwenden, um zu verstehen, wie auf einen Anruf reagiert wird.

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

Audiowiedergabe

Nachdem der Anruf eingerichtet wurde, gibt es mehrere Optionen für die Wiedergabe der Audiodatei. Sie können Audio für den Teilnehmer, der dem Anruf gerade beigetreten ist, oder für alle Teilnehmer des Anrufs wiedergeben.

Wiedergabequelle – Audiodatei

Um Audio mithilfe von Audiodateien für Teilnehmer wiederzugeben, müssen Sie sicherstellen, dass es sich bei der Audiodatei um eine WAV-Datei (Mono) mit 16 KHz handelt. Um Audiodateien wiederzugeben, müssen Sie sicherstellen, dass Sie Azure Communication Services mit einem URI für eine Datei bereitstellen, die Sie an einem Ort hosten, an dem Azure Communication Services darauf zugreifen kann. Der FileSource-Typ in unserem SDK kann verwendet werden, um Audiodateien für die Wiedergabeaktion anzugeben.

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

Wiedergabequelle – Sprachsynthese

Um Audio mit Sprachsynthese über Azure KI Services wiederzugeben, müssen Sie den Text bereitstellen, den Sie wiedergeben möchten, sowie entweder die „SourceLocale“ und „VoiceKind“ oder „VoiceName“, die Sie verwenden möchten. Wir unterstützen alle Stimmnamen, die von Azure KI Services unterstützt werden. Die vollständige Liste finden Sie hier.

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

Wiedergabequelle – Sprachsynthese mit 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);

Benutzerdefinierte Stimmmodelle

Wenn Sie Ihre Prompts weiter verbessern und benutzerdefinierte Stimmmodelle einbeziehen möchten, unterstützt die Wiedergabeaktion „Sprachsynthese“ jetzt diese benutzerdefinierten Stimmen. Diese sind gut geeignet, wenn Sie versuchen, Kunden eine lokale, personalisierte Erfahrung zu bieten, oder in Situationen, in denen die Standardmodelle möglicherweise nicht die Wörter und Akzente abdecken, die ausgesprochen werden sollen. Weitere Informationen zum Erstellen und Bereitstellen von benutzerdefinierten Modellen finden Sie in diesem Leitfaden.

Reguläres Textbeispiel für benutzerdefinierte Stimmnamen

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

SSML-Beispiel für benutzerdefinierte Stimmnamen

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

Nachdem Sie entschieden haben, welche Wiedergabequelle Sie für die Audiowiedergabe verwenden möchten, können Sie auswählen, ob Sie sie für einen bestimmten Teilnehmer oder allen Teilnehmer wiedergeben möchten.

Wiedergeben von Audio für alle Teilnehmer

In diesem Szenario wird Audio für alle Teilnehmer im Anruf wiedergegeben.

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

Wiedergeben von Audio für einen bestimmten Teilnehmer

In diesem Szenario wird Audio für einen bestimmten Teilnehmer wiedergegeben.

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

Wiedergeben von Audio als Schleife

Sie können die Option für die Wiedergabeschleife verwenden, um Warteschleifenmusik wiederzugeben, die so lange läuft, bis Ihre Anwendung bereit ist, den Anruf anzunehmen. Oder leiten Sie den Anrufer auf der Grundlage der Geschäftslogik Ihrer Anwendung zum nächsten logischen Schritt weiter.

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

Verbessern der Wiedergabe mit der Zwischenspeicherung von Audiodateien

Wenn Sie dieselbe Audiodatei mehrmals wiedergeben, kann Ihre Anwendung die Quell-ID der Audiodatei für Azure Communication Services bereitstellen. Azure Communication Services speichert diese Audiodatei eine Stunde lang zwischen.

Hinweis

Das Zwischenspeichern von Audiodateien eignet sich nicht für dynamische Prompts. Wenn Sie die für Azure Communication Services bereitgestellte URL ändern, wird die zwischengespeicherte URL nicht sofort aktualisiert. Das Update erfolgt, nachdem der vorhandene Cache abgelaufen ist.

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

Behandeln von Ereignisupdates für die Wiedergabeaktion

Ihre Anwendung erhält Ereignisupdates für den Aktionslebenszyklus unter der Rückruf-URL, die zum Zeitpunkt der Anrufannahme für den Anrufautomatisierungsdienst bereitgestellt wurde. Nachfolgend sehen Sie ein Beispiel für ein erfolgreiches Wiedergabeereignisupdate:

Beispiel zur Deserialisierung des PlayCompleted-Ereignisses:

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

Beispiel zur Deserialisierung des PlayFailed-Ereignisses:

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

Weitere Informationen zu anderen unterstützten Ereignissen finden Sie im Übersichtsdokument zur Anrufautomatisierung.

Abbrechen der Wiedergabeaktion

Wenn Sie alle Medienvorgänge abbrechen, werden alle ausstehenden Medienvorgänge abgebrochen. Mit dieser Aktion werden auch andere Wiedergabeaktionen in der Warteschlange abgebrochen.

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

Beispiel zur Deserialisierung des PlayCanceled-Ereignisses:

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

Voraussetzungen

Für KI-Features

Erstellen einer neuen JavaScript-Anwendung

Erstellen Sie eine neue JavaScript-Anwendung in Ihrem Projektverzeichnis. Initialisieren Sie mit dem folgenden Befehl ein Node.js-Projekt. Damit wird eine Datei „package.json“ für Ihr Projekt erstellt, die zum Verwalten der Abhängigkeiten Ihres Projekts verwendet wird.

npm init -y

Installieren des Anrufautomatisierungspakets für Azure Communication Services

npm install @azure/communication-call-automation

Erstellen Sie eine neue JavaScript-Datei in Ihrem Projektverzeichnis, und nennen Sie sie z. B. „app.js“. Sie schreiben Ihren JavaScript-Code in dieser Datei. Führen Sie Ihre Anwendung mit dem folgenden Node.js-Befehl aus. Dieser Code führt den JavaScript-Code aus, den Sie geschrieben haben.

node app.js

(Optional) Vorbereiten der Audiodatei, wenn Sie Audiodateien für die Wiedergabe von Prompts verwenden möchten

Erstellen Sie eine Audiodatei, wenn Sie noch keine haben, um Eingabeaufforderungen und Nachrichten für Teilnehmer wiederzugeben. Die Audiodatei muss an einem Speicherort gehostet werden, der für Azure Communication Services zugänglich ist und Authentifizierung unterstützt. Behalten Sie eine Kopie der URL, die Sie beim Anfordern der Wiedergabe der Audiodatei verwenden können. Azure Communication Services unterstützt die Dateitypen MP3 mit ID3V2TAG und WAV, Mono, 16-Bit-PCM mit 16 KHz Abtastrate.

Sie können die Erstellung Ihrer eigenen Audiodatei testen, indem Sie unsere Sprachsynthese mit dem Audioinhaltserstellungs-Tool verwenden.

(Optional) Verknüpfen von Azure Cognitive Services mit Azure Communication Services

Wenn Sie Sprachsynthesefunktionen verwenden möchten, müssen Sie Azure Cognitive Services mit Azure Communication Services verknüpfen.

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. Sie können auch das folgende Codeschnipsel verwenden, um zu verstehen, wie auf einen Anruf reagiert wird.

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

Audiowiedergabe

Nachdem der Anruf eingerichtet wurde, gibt es mehrere Optionen für die Wiedergabe der Audiodatei. Sie können Audio für den Teilnehmer, der dem Anruf gerade beigetreten ist, oder für alle Teilnehmer des Anrufs wiedergeben.

Wiedergabequelle – Audiodatei

Um Audio mithilfe von Audiodateien für Teilnehmer wiederzugeben, müssen Sie sicherstellen, dass es sich bei der Audiodatei um eine WAV-Datei (Mono) mit 16 KHz handelt. Um Audiodateien wiederzugeben, müssen Sie sicherstellen, dass Sie Azure Communication Services mit einem URI für eine Datei bereitstellen, die Sie an einem Ort hosten, an dem Azure Communication Services darauf zugreifen kann. Der FileSource-Typ in unserem SDK kann verwendet werden, um Audiodateien für die Wiedergabeaktion anzugeben.

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

Wiedergabequelle – Sprachsynthese

Um Audio mit Sprachsynthese über Azure KI Services wiederzugeben, müssen Sie den Text bereitstellen, den Sie wiedergeben möchten, sowie entweder die „SourceLocale“ und „VoiceKind“ oder „VoiceName“, die Sie verwenden möchten. Wir unterstützen alle Stimmnamen, die von Azure KI Services unterstützt werden. Die vollständige Liste finden Sie hier.

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" };

Wiedergabequelle – Sprachsynthese mit SSML

Wenn Sie Ihre Sprachsyntheseausgabe mit Azure KI Services weiter anpassen möchten, können Sie Speech Synthesis Markup Language SSML- verwenden, wenn Sie Ihre Wiedergabeaktion über die Anrufautomatisierung aufrufen. Mit SSML können Sie die Tonhöhe, Pausen und die Aussprache verbessern, die Sprechgeschwindigkeit ändern, die Lautstärke anpassen und mehrere Stimmen attributieren.

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" };

Benutzerdefinierte Stimmmodelle

Wenn Sie Ihre Prompts weiter verbessern und benutzerdefinierte Stimmmodelle einbeziehen möchten, unterstützt die Wiedergabeaktion „Sprachsynthese“ jetzt diese benutzerdefinierten Stimmen. Diese sind gut geeignet, wenn Sie versuchen, Kunden eine lokale, personalisierte Erfahrung zu bieten, oder in Situationen, in denen die Standardmodelle möglicherweise nicht die Wörter und Akzente abdecken, die ausgesprochen werden sollen. Weitere Informationen zum Erstellen und Bereitstellen von benutzerdefinierten Modellen finden Sie in diesem Leitfaden.

Reguläres Textbeispiel für benutzerdefinierte Stimmnamen

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

SSML-Beispiel für benutzerdefinierte Stimmnamen

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"};

Nachdem Sie entschieden haben, welche Wiedergabequelle Sie für die Audiowiedergabe verwenden möchten, können Sie auswählen, ob Sie sie für einen bestimmten Teilnehmer oder allen Teilnehmer wiedergeben möchten.

Wiedergeben von Audio: alle Teilnehmer

In diesem Szenario wird Audio für alle Teilnehmer im Anruf wiedergegeben.

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

Wiedergeben von Audio: bestimmter Teilnehmer

In diesem Szenario wird Audio für einen bestimmten Teilnehmer wiedergegeben.

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

Wiedergeben von Audio als Schleife

Sie können die Option für die Wiedergabeschleife verwenden, um Warteschleifenmusik wiederzugeben, die so lange läuft, bis Ihre Anwendung bereit ist, den Anruf anzunehmen. Oder leiten Sie den Anrufer auf der Grundlage der Geschäftslogik Ihrer Anwendung zum nächsten logischen Schritt weiter.

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

Verbessern der Wiedergabe mit der Zwischenspeicherung von Audiodateien

Wenn Sie dieselbe Audiodatei mehrmals wiedergeben, kann Ihre Anwendung die Quell-ID der Audiodatei für Azure Communication Services bereitstellen. Azure Communication Services speichert diese Audiodatei eine Stunde lang zwischen.

Hinweis

Das Zwischenspeichern von Audiodateien eignet sich nicht für dynamische Prompts. Wenn Sie die für Azure Communication Services bereitgestellte URL ändern, wird die zwischengespeicherte URL nicht sofort aktualisiert. Das Update erfolgt, nachdem der vorhandene Cache abgelaufen ist.

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

Behandeln von Ereignisupdates für die Wiedergabeaktion

Ihre Anwendung erhält Ereignisupdates für den Aktionslebenszyklus unter der Rückruf-URL, die zum Zeitpunkt der Anrufannahme für den Anrufautomatisierungsdienst bereitgestellt wurde.

Beispiel zur Deserialisierung des PlayCompleted-Ereignisses:

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

Beispiel zur Deserialisierung des PlayFailed-Ereignisses:

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

Weitere Informationen zu anderen unterstützten Ereignissen finden Sie im Übersichtsdokument zur Anrufautomatisierung.

Abbrechen der Wiedergabeaktion

Wenn Sie alle Medienvorgänge abbrechen, werden alle ausstehenden Medienvorgänge abgebrochen. Mit dieser Aktion werden auch andere Wiedergabeaktionen in der Warteschlange abgebrochen.

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

Beispiel zur Deserialisierung des PlayCanceled-Ereignisses:

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

Voraussetzungen

Für KI-Features

Erstellen einer neuen Python-Anwendung

Einrichten einer virtuellen Python-Umgebung für Ihr Projekt

python -m venv play-audio-app

Aktivieren der virtuellen Umgebung

Verwenden Sie unter Windows den folgenden Befehl:

.\ play-audio-quickstart \Scripts\activate

Verwenden Sie unter Unix den folgenden Befehl:

source play-audio-quickstart /bin/activate

Installieren des Anrufautomatisierungspakets für Azure Communication Services

pip install azure-communication-callautomation

Erstellen Sie Ihre Anwendungsdatei in Ihrem Projektverzeichnis, und nennen Sie sie z. B. „app.py“. Sie schreiben Ihren Python-Code in dieser Datei.

Führen Sie Ihre Anwendung mit dem folgenden Python-Befehl aus, um Code auszuführen.

python app.py

(Optional) Vorbereiten der Audiodatei, wenn Sie Audiodateien für die Wiedergabe von Prompts verwenden möchten

Erstellen Sie eine Audiodatei, wenn Sie noch keine haben, um Eingabeaufforderungen und Nachrichten für Teilnehmer wiederzugeben. Die Audiodatei muss an einem Speicherort gehostet werden, der für Azure Communication Services zugänglich ist und Authentifizierung unterstützt. Behalten Sie eine Kopie der URL, die Sie beim Anfordern der Wiedergabe der Audiodatei verwenden können. Azure Communication Services unterstützt die Dateitypen MP3 und WAV, Mono, 16-Bit-PCM mit 16 KHz Abtastrate. .

Sie können die Erstellung Ihrer eigenen Audiodatei testen, indem Sie unsere Sprachsynthese mit dem Audioinhaltserstellungs-Tool verwenden.

(Optional) Verknüpfen von Azure Cognitive Services mit Azure Communication Services

Wenn Sie Sprachsynthesefunktionen verwenden möchten, müssen Sie Azure Cognitive Services mit Azure Communication Services verknüpfen.

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. Sie können auch das folgende Codeschnipsel verwenden, um zu verstehen, wie auf einen Anruf reagiert wird.

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

Audiowiedergabe

Nachdem der Anruf eingerichtet wurde, gibt es mehrere Optionen für die Wiedergabe der Audiodatei. Sie können Audio für den Teilnehmer, der dem Anruf gerade beigetreten ist, oder für alle Teilnehmer des Anrufs wiedergeben.

Wiedergabequelle – Audiodatei

Um Audio mithilfe von Audiodateien für Teilnehmer wiederzugeben, müssen Sie sicherstellen, dass es sich bei der Audiodatei um eine WAV-Datei (Mono) mit 16 KHz handelt. Um Audiodateien wiederzugeben, müssen Sie sicherstellen, dass Sie Azure Communication Services mit einem URI für eine Datei bereitstellen, die Sie an einem Ort hosten, an dem Azure Communication Services darauf zugreifen kann. Der FileSource-Typ in unserem SDK kann verwendet werden, um Audiodateien für die Wiedergabeaktion anzugeben.

play_source = FileSource(url=audioUri)

Wiedergabequelle – Sprachsynthese

Um Audio mit Sprachsynthese über Azure KI Services wiederzugeben, müssen Sie den Text bereitstellen, den Sie wiedergeben möchten, sowie entweder die „SourceLocale“ und „VoiceKind“ oder „VoiceName“, die Sie verwenden möchten. Wir unterstützen alle Stimmnamen, die von Azure KI Services unterstützt werden. Die vollständige Liste finden Sie hier.

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
)

Wiedergabequelle – Sprachsynthese mit SSML

Wenn Sie Ihre Sprachsyntheseausgabe mit Azure KI Services weiter anpassen möchten, können Sie Speech Synthesis Markup Language SSML- verwenden, wenn Sie Ihre Wiedergabeaktion über die Anrufautomatisierung aufrufen. Mit SSML können Sie die Tonhöhe, Pausen und die Aussprache verbessern, die Sprechgeschwindigkeit ändern, die Lautstärke anpassen und mehrere Stimmen attributieren.

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
)

Benutzerdefinierte Stimmmodelle

Wenn Sie Ihre Prompts weiter verbessern und benutzerdefinierte Stimmmodelle einbeziehen möchten, unterstützt die Wiedergabeaktion „Sprachsynthese“ jetzt diese benutzerdefinierten Stimmen. Diese sind gut geeignet, wenn Sie versuchen, Kunden eine lokale, personalisierte Erfahrung zu bieten, oder in Situationen, in denen die Standardmodelle möglicherweise nicht die Wörter und Akzente abdecken, die ausgesprochen werden sollen. Weitere Informationen zum Erstellen und Bereitstellen von benutzerdefinierten Modellen finden Sie in diesem Leitfaden.

Reguläres Textbeispiel für benutzerdefinierte Stimmnamen

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-Beispiel für benutzerdefinierte Stimmnamen

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
)

Nachdem Sie entschieden haben, welche Wiedergabequelle Sie für die Audiowiedergabe verwenden möchten, können Sie auswählen, ob Sie sie für einen bestimmten Teilnehmer oder allen Teilnehmer wiedergeben möchten.

Wiedergeben von Audio: alle Teilnehmer

So geben Sie eine vorab aufgezeichneten Audiodatei für alle Anrufteilnehmer wieder:

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
)

Wiedergeben von Audio: bestimmter Teilnehmer

So geben Sie eine vorab aufgezeichneten Audiodatei für bestimmte Anrufteilnehmer wieder:

play_to = [target_participant]

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

Wiedergeben von Audio als Schleife

Sie können die Option für die Wiedergabeschleife verwenden, um Warteschleifenmusik wiederzugeben, die so lange läuft, bis Ihre Anwendung bereit ist, den Anruf anzunehmen. Oder leiten Sie den Anrufer auf der Grundlage der Geschäftslogik Ihrer Anwendung zum nächsten logischen Schritt weiter.

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
)

Verbessern der Wiedergabe mit der Zwischenspeicherung von Audiodateien

Wenn Sie dieselbe Audiodatei mehrmals wiedergeben, kann Ihre Anwendung die Quell-ID der Audiodatei für Azure Communication Services bereitstellen. Azure Communication Services speichert diese Audiodatei eine Stunde lang zwischen.

Hinweis

Das Zwischenspeichern von Audiodateien eignet sich nicht für dynamische Prompts. Wenn Sie die für Azure Communication Services bereitgestellte URL ändern, wird die zwischengespeicherte URL nicht sofort aktualisiert. Das Update erfolgt, nachdem der vorhandene Cache abgelaufen ist.

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
)

Behandeln von Ereignisupdates für die Wiedergabeaktion

Ihre Anwendung erhält Ereignisupdates für den Aktionslebenszyklus unter der Rückruf-URL, die zum Zeitpunkt der Anrufannahme für den Anrufautomatisierungsdienst bereitgestellt wurde.

Beispiel zur Deserialisierung des PlayCompleted-Ereignisses:

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

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

Beispiel zur Deserialisierung des PlayFailed-Ereignisses:

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

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

Weitere Informationen zu anderen unterstützten Ereignissen finden Sie im Übersichtsdokument zur Anrufautomatisierung.

Abbrechen der Wiedergabeaktion

Wenn Sie alle Medienvorgänge abbrechen, werden alle ausstehenden Medienvorgänge abgebrochen. Mit dieser Aktion werden auch andere Wiedergabeaktionen in der Warteschlange abgebrochen.

call_automation_client.get_call_connection(
    call_connection_id
).cancel_all_media_operations()

Beispiel zur Deserialisierung des PlayCanceled-Ereignisses:

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

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

Ereigniscodes

Status Code Subcode `Message`
PlayCompleted 200 0 Die Aktion wurde erfolgreich abgeschlossen.
PlayCanceled 400 8508 Fehler bei der Aktion, der Vorgang wurde abgebrochen.
PlayFailed 400 8535 Fehler bei der Aktion, Dateiformat ist ungültig
PlayFailed 400 8536 Fehler bei der Aktion, Datei konnte nicht heruntergeladen werden
PlayFailed 400 8565 Fehler bei der Aktion, ungültige Anforderung an Azure KI Services. Eingabeparameter prüfen.
PlayFailed 401 8565 Fehler bei der Aktion, Azure KI Services-Authentifizierungsfehler
PlayFailed 403 8565 Fehler bei der Aktion; unzulässige Anforderung an Azure KI Services, kein Kontingent mehr beim für die Anforderung verwendeten kostenlosen Abonnement
PlayFailed 429 8565 Fehler bei der Aktion, Anzahl der zulässigen gleichzeitigen Anforderungen für das Azure KI Services-Abonnement überschritten
PlayFailed 408 8565 Fehler bei der Aktion, Timeout bei der Anforderung an Azure KI Services
PlayFailed 500 9999 Unbekannter interner Serverfehler
PlayFailed 500 8572 Fehler bei der Aktion, Wiedergabedienst heruntergefahren

Bekannte Einschränkungen

  • In Textprompts für die Sprachsynthese werden maximal 400 Zeichen unterstützen. Wenn Ihr Prompt länger ist, wird die Verwendung von SSML für Sprachsynthese-Wiedergabeaktionen empfohlen.
  • Sie können für Szenarios, in denen Sie Ihre Kontingentgrenze für den Speech-Dienst überschreiten, eine Erhöhung dieses Grenzwerts anfordern, indem Sie die hier beschriebenen Schritte befolgen.

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Nächste Schritte