Spraakprompts aanpassen aan gebruikers met de actie Afspelen

  • Artikel

Deze handleiding helpt u aan de slag te gaan met het afspelen van audiobestanden aan deelnemers met behulp van de afspeelactie die wordt geboden via de Azure Communication Services Call Automation SDK.

Vereisten

Voor AI-functies

Een nieuwe C#-toepassing maken

Gebruik in het consolevenster van uw besturingssysteem de dotnet opdracht om een nieuwe webtoepassing te maken.

dotnet new web -n MyApplication

Installeer het NuGet-pakket van

Het NuGet-pakket kan hier worden verkregen, als u dit nog niet hebt gedaan.

(Optioneel) Bereid uw audiobestand voor als u audiobestanden wilt gebruiken voor het afspelen van prompts

Maak een audiobestand als u er nog geen hebt, om te gebruiken voor het afspelen van prompts en berichten aan deelnemers. Het audiobestand moet worden gehost op een locatie die toegankelijk is voor Azure Communication Services met ondersteuning voor verificatie. Bewaar een kopie van de URL die u kunt gebruiken bij het aanvragen om het audiobestand af te spelen. Azure Communication Services ondersteunt beide bestandstypen MP3-bestanden met ID3V2TAG- en WAV-bestanden, mono 16-bits PCM met een samplefrequentie van 16 KHz. .

U kunt het maken van uw eigen audiobestand testen met behulp van onze spraaksynthese met het hulpprogramma Audio-inhoud maken.

(Optioneel) Verbinding maken uw Azure Cognitive Service naar uw Azure Communication Service

Als u tekst-naar-spraak-mogelijkheden wilt gebruiken, moet u uw Azure Cognitive Service verbinden met uw Azure Communication Service.

Een oproep tot stand brengen

Op dit punt moet u bekend zijn met het starten van oproepen, als u meer wilt weten over het maken van een gesprek, volgt u onze quickstart. U kunt ook het hier opgegeven codefragment gebruiken om te begrijpen hoe u een oproep beantwoordt.

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

Audio afspelen

Zodra het gesprek tot stand is gebracht, zijn er meerdere opties voor het afspelen van de audio. U kunt audio afspelen naar de deelnemer die deel uitmaakt van het gesprek of audio afspelen voor alle deelnemers in het gesprek.

Bron afspelen - audiobestand

Als u audio wilt afspelen voor deelnemers met behulp van audiobestanden, moet u ervoor zorgen dat het audiobestand een WAV-bestand, mono en 16 KHz is. Als u audiobestanden wilt afspelen, moet u ervoor zorgen dat u Azure Communication Services een URI verstrekt aan een bestand dat u host op een locatie waar Azure Communication Services toegang heeft. Het type FileSource in onze SDK kan worden gebruikt om audiobestanden voor de afspeelactie op te geven.

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

Bron afspelen - Tekst-naar-spraak

Als u audio wilt afspelen met behulp van Text-To-Speech via Azure AI-services, moet u de tekst opgeven die u wilt afspelen, evenals de SourceLocale en VoiceKind of de VoiceName die u wilt gebruiken. We ondersteunen hier alle spraaknamen die worden ondersteund door Azure AI-services, in de volledige lijst.

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

Bron afspelen - Tekst-naar-spraak met SSML

Als u uw tekst-naar-spraak-uitvoer nog meer wilt aanpassen met Azure AI-services, kunt u Speech Synthesis Markup Language SSML gebruiken bij het aanroepen van uw afspeelactie via Call Automation. Met SSML kunt u de toonhoogte verfijnen, onderbreken, uitspraak verbeteren, spreeksnelheid wijzigen, volume aanpassen en meerdere stemmen aanbrengen.

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

Aangepaste spraakmodellen

Als u uw prompts meer wilt verbeteren en aangepaste spraakmodellen wilt opnemen, ondersteunt de actie Tekst-naar-spraak afspelen nu deze aangepaste stemmen. Dit is een uitstekende optie als u klanten een meer lokale, persoonlijke ervaring wilt geven of situaties hebt waarin de standaardmodellen mogelijk niet de woorden en accenten behandelen die u probeert uit te spreken. Lees deze handleiding voor meer informatie over het maken en implementeren van aangepaste modellen.

Aangepaste spraaknamen, reguliere tekstoverzicht

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

SSML-voorbeeld van aangepaste spraaknamen


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

Zodra u hebt besloten welke playSource u wilt gebruiken voor het afspelen van audio, kunt u vervolgens kiezen of u deze wilt afspelen aan een specifieke deelnemer of aan alle deelnemers.

Audio afspelen voor alle deelnemers

In dit scenario wordt audio afgespeeld voor alle deelnemers aan het gesprek.

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

Audio afspelen voor een specifieke deelnemer

In dit scenario wordt audio afgespeeld voor een specifieke deelnemer.

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

Audio afspelen op lus

U kunt de lusoptie gebruiken om muziek die lussen afspeelt af te spelen totdat uw toepassing klaar is om de beller te accepteren. U kunt ook de aanroeper naar de volgende logische stap doorschakelen op basis van de bedrijfslogica van uw toepassingen.

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

Afspelen verbeteren met caching van audiobestanden

Als u hetzelfde audiobestand meerdere keren afspeelt, kan uw toepassing Azure Communication Services voorzien van de sourceID voor het audiobestand. Azure Communication Services slaat dit audiobestand gedurende 1 uur in de cache op.

Notitie

Het opslaan van audiobestanden in de cache is niet geschikt voor dynamische prompts. Als u de opgegeven URL wijzigt in Azure Communication Services, wordt de URL in de cache niet meteen bijgewerkt. De update vindt plaats nadat de bestaande cache is verlopen.

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

Actie-updates voor afspelen verwerken

Uw toepassing ontvangt updates voor de levenscyclus van acties op de callback-URL die is verstrekt aan de Call Automation-service op het moment van het beantwoorden van de oproep. Een voorbeeld van een geslaagde update van een play-gebeurtenis.

Voorbeeld van hoe u deserialiseren van de PlayCompleted-gebeurtenis kunt deserialiseren :

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

Voorbeeld van hoe u deserialiseren van de PlayFailed-gebeurtenis kunt deserialiseren :

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

Ga naar het overzichtsdocument gespreksautomatisering voor meer informatie over andere ondersteunde gebeurtenissen.

Actie Afspelen annuleren

Alle mediabewerkingen annuleren, alle in behandeling zijnde mediabewerkingen worden geannuleerd. Met deze actie worden ook andere acties voor afspelen in de wachtrij geannuleerd.

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

Voorbeeld van hoe u deserialiseren van de playCanceled-gebeurtenis :

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

Vereisten

Voor AI-functies

Een nieuwe Java-toepassing maken

Navigeer in het terminal- of opdrachtvenster naar de map waarin u uw Java-toepassing wilt maken. Voer de hier weergegeven opdracht uit om het Java-project te genereren op basis van de maven-archetype-quickstart-sjabloon.

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

Met de vorige opdracht maakt u een map met dezelfde naam als artifactId het argument. Onder deze map bevat de map src/main/java de broncode van het project, src/test/java de map bevat de testbron.

U ziet dat met de stap 'genereren' een map is gemaakt met dezelfde naam als de artifactId. Onder deze map src/main/java bevat map broncode, src/test/java map bevat tests en pom.xml bestand is het Project Object Model van het project of POM van het project.

Werk het POM-bestand van uw toepassingen bij om Java 8 of hoger te gebruiken.

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

Pakketverwijzingen toevoegen

Voeg in uw POM-bestand de volgende verwijzing toe voor het project.

azure-communication-callautomation

Het Azure Communication Services Call Automation SDK-pakket wordt opgehaald uit de Azure SDK Dev Feed.

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

(Optioneel) Bereid uw audiobestand voor als u audiobestanden wilt gebruiken voor het afspelen van prompts

Maak een audiobestand als u er nog geen hebt, om te gebruiken voor het afspelen van prompts en berichten aan deelnemers. Het audiobestand moet worden gehost op een locatie die toegankelijk is voor Azure Communication Services met ondersteuning voor verificatie. Bewaar een kopie van de URL die u kunt gebruiken bij het aanvragen om het audiobestand af te spelen. Azure Communication Services ondersteunt beide bestandstypen MP3-bestanden met ID3V2TAG- en WAV-bestanden, mono 16-bits PCM met een samplefrequentie van 16 KHz. .

U kunt het maken van uw eigen audiobestand testen met behulp van onze spraaksynthese met het hulpprogramma Audio-inhoud maken.

(Optioneel) Verbinding maken uw Azure Cognitive Service naar uw Azure Communication Service

Als u tekst-naar-spraak-mogelijkheden wilt gebruiken, moet u uw Azure Cognitive Service verbinden met uw Azure Communication Service.

App.java bijwerken met code

Open in de gewenste editor App.java bestand en werk het bij met de code die is opgegeven in Update app.java met codesectie .

Een oproep tot stand brengen

Op dit punt moet u bekend zijn met het starten van oproepen, als u meer wilt weten over het maken van een gesprek, volgt u onze quickstart. U kunt ook het hier opgegeven codefragment gebruiken om te begrijpen hoe u een oproep beantwoordt.

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

Audio afspelen

Zodra het gesprek tot stand is gebracht, zijn er meerdere opties voor het afspelen van de audio. U kunt audio afspelen naar de deelnemer die deel uitmaakt van het gesprek of audio afspelen voor alle deelnemers in het gesprek.

Bron afspelen - audiobestand

Als u audio wilt afspelen voor deelnemers met behulp van audiobestanden, moet u ervoor zorgen dat het audiobestand een WAV-bestand, mono en 16 KHz is. Als u audiobestanden wilt afspelen, moet u ervoor zorgen dat u Azure Communication Services een URI verstrekt aan een bestand dat u host op een locatie waar Azure Communication Services toegang heeft. Het type FileSource in onze SDK kan worden gebruikt om audiobestanden voor de afspeelactie op te geven.

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

Bron afspelen - Tekst-naar-spraak

Als u audio wilt afspelen met behulp van Text-To-Speech via Azure AI-services, moet u de tekst opgeven die u wilt afspelen, evenals de SourceLocale en VoiceKind of de VoiceName die u wilt gebruiken. We ondersteunen hier alle spraaknamen die worden ondersteund door Azure AI-services, in de volledige lijst.

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

Bron afspelen - Tekst-naar-spraak-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);

Aangepaste spraakmodellen

Als u uw prompts meer wilt verbeteren en aangepaste spraakmodellen wilt opnemen, ondersteunt de actie Tekst-naar-spraak afspelen nu deze aangepaste stemmen. Dit is een uitstekende optie als u klanten een meer lokale, persoonlijke ervaring wilt geven of situaties hebt waarin de standaardmodellen mogelijk niet de woorden en accenten behandelen die u probeert uit te spreken. Lees deze handleiding voor meer informatie over het maken en implementeren van aangepaste modellen.

Aangepaste spraaknamen, reguliere tekstoverzicht

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

SSML-voorbeeld van aangepaste spraaknamen

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

Zodra u hebt besloten welke playSource u wilt gebruiken voor het afspelen van audio, kunt u vervolgens kiezen of u deze wilt afspelen aan een specifieke deelnemer of aan alle deelnemers.

Audio afspelen voor alle deelnemers

In dit scenario wordt audio afgespeeld voor alle deelnemers aan het gesprek.

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

Audio afspelen voor een specifieke deelnemer

In dit scenario wordt audio afgespeeld voor een specifieke deelnemer.

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

Audio afspelen op lus

U kunt de lusoptie gebruiken om muziek die lussen afspeelt af te spelen totdat uw toepassing klaar is om de beller te accepteren. U kunt ook de aanroeper naar de volgende logische stap doorschakelen op basis van de bedrijfslogica van uw toepassingen.

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

Afspelen verbeteren met caching van audiobestanden

Als u hetzelfde audiobestand meerdere keren afspeelt, kan uw toepassing Azure Communication Services voorzien van de sourceID voor het audiobestand. Azure Communication Services slaat dit audiobestand gedurende 1 uur in de cache op.

Notitie

Het opslaan van audiobestanden in de cache is niet geschikt voor dynamische prompts. Als u de opgegeven URL wijzigt in Azure Communication Services, wordt de URL in de cache niet meteen bijgewerkt. De update vindt plaats nadat de bestaande cache is verlopen.

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

Actie-updates voor afspelen verwerken

Uw toepassing ontvangt updates voor de levenscyclus van acties op de callback-URL die is verstrekt aan de Call Automation-service op het moment van het beantwoorden van de oproep. Een voorbeeld van een geslaagde update van een play-gebeurtenis.

Voorbeeld van hoe u deserialiseren van de PlayCompleted-gebeurtenis kunt deserialiseren :

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

Voorbeeld van hoe u deserialiseren van de PlayFailed-gebeurtenis kunt deserialiseren :

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

Ga naar het overzichtsdocument gespreksautomatisering voor meer informatie over andere ondersteunde gebeurtenissen.

Actie Afspelen annuleren

Alle mediabewerkingen annuleren, alle in behandeling zijnde mediabewerkingen worden geannuleerd. Met deze actie worden ook andere acties voor afspelen in de wachtrij geannuleerd.

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

Voorbeeld van hoe u deserialiseren van de playCanceled-gebeurtenis :

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

Vereisten

Voor AI-functies

Een nieuwe JavaScript-toepassing maken

Maak een nieuwe JavaScript-toepassing in uw projectmap. Initialiseer een nieuw Node.js project met de volgende opdracht. Hiermee maakt u een package.json-bestand voor uw project, dat wordt gebruikt voor het beheren van de afhankelijkheden van uw project.

npm init -y

Het Azure Communication Services Call Automation-pakket installeren

npm install @azure/communication-call-automation

Maak een nieuw JavaScript-bestand in uw projectmap, bijvoorbeeld app.js. U schrijft uw JavaScript-code in dit bestand. Voer uw toepassing uit met Node.js met de volgende opdracht. Met deze code wordt de JavaScript-code uitgevoerd die u hebt geschreven.

node app.js

(Optioneel) Bereid uw audiobestand voor als u audiobestanden wilt gebruiken voor het afspelen van prompts

Maak een audiobestand als u er nog geen hebt, om te gebruiken voor het afspelen van prompts en berichten aan deelnemers. Het audiobestand moet worden gehost op een locatie die toegankelijk is voor Azure Communication Services met ondersteuning voor verificatie. Bewaar een kopie van de URL die u kunt gebruiken bij het aanvragen om het audiobestand af te spelen. Azure Communication Services ondersteunt beide bestandstypen MP3-bestanden met ID3V2TAG- en WAV-bestanden, mono 16-bits PCM met een samplefrequentie van 16 KHz.

U kunt het maken van uw eigen audiobestand testen met behulp van onze spraaksynthese met het hulpprogramma Audio-inhoud maken.

(Optioneel) Verbinding maken uw Azure Cognitive Service naar uw Azure Communication Service

Als u tekst-naar-spraak-mogelijkheden wilt gebruiken, moet u uw Azure Cognitive Service verbinden met uw Azure Communication Service.

Een oproep tot stand brengen

Op dit punt moet u bekend zijn met het starten van oproepen, als u meer wilt weten over het maken van een gesprek, volgt u onze quickstart. U kunt ook het hier opgegeven codefragment gebruiken om te begrijpen hoe u een oproep beantwoordt.

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

Audio afspelen

Zodra het gesprek tot stand is gebracht, zijn er meerdere opties voor het afspelen van de audio. U kunt audio afspelen naar de deelnemer die deel uitmaakt van het gesprek of audio afspelen voor alle deelnemers in het gesprek.

Bron afspelen - audiobestand

Als u audio wilt afspelen voor deelnemers met behulp van audiobestanden, moet u ervoor zorgen dat het audiobestand een WAV-bestand, mono en 16 KHz is. Als u audiobestanden wilt afspelen, moet u ervoor zorgen dat u Azure Communication Services een URI verstrekt aan een bestand dat u host op een locatie waar Azure Communication Services toegang heeft. Het type FileSource in onze SDK kan worden gebruikt om audiobestanden voor de afspeelactie op te geven.

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

Bron afspelen - Tekst-naar-spraak

Als u audio wilt afspelen met behulp van Text-To-Speech via Azure AI-services, moet u de tekst opgeven die u wilt afspelen, evenals de SourceLocale en VoiceKind of de VoiceName die u wilt gebruiken. We ondersteunen hier alle spraaknamen die worden ondersteund door Azure AI-services, in de volledige lijst.

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

Bron afspelen - Tekst-naar-spraak met SSML

Als u uw tekst-naar-spraak-uitvoer nog meer wilt aanpassen met Azure AI-services, kunt u Speech Synthesis Markup Language SSML gebruiken bij het aanroepen van uw afspeelactie via Call Automation. Met SSML kunt u de toonhoogte verfijnen, onderbreken, uitspraak verbeteren, spreeksnelheid wijzigen, volume aanpassen en meerdere stemmen aanbrengen.

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

Aangepaste spraakmodellen

Als u uw prompts meer wilt verbeteren en aangepaste spraakmodellen wilt opnemen, ondersteunt de actie Tekst-naar-spraak afspelen nu deze aangepaste stemmen. Dit is een uitstekende optie als u klanten een meer lokale, persoonlijke ervaring wilt geven of situaties hebt waarin de standaardmodellen mogelijk niet de woorden en accenten behandelen die u probeert uit te spreken. Lees deze handleiding voor meer informatie over het maken en implementeren van aangepaste modellen.

Aangepaste spraaknamen, reguliere tekstoverzicht

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

SSML-voorbeeld van aangepaste spraaknamen

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

Zodra u hebt besloten welke playSource u wilt gebruiken voor het afspelen van audio, kunt u vervolgens kiezen of u deze wilt afspelen aan een specifieke deelnemer of aan alle deelnemers.

Audio afspelen - Alle deelnemers

In dit scenario wordt audio afgespeeld voor alle deelnemers aan het gesprek.

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

Audio afspelen - Specifieke deelnemer

In dit scenario wordt audio afgespeeld voor een specifieke deelnemer.

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

Audio afspelen op lus

U kunt de lusoptie gebruiken om muziek die lussen afspeelt af te spelen totdat uw toepassing klaar is om de beller te accepteren. U kunt ook de aanroeper naar de volgende logische stap doorschakelen op basis van de bedrijfslogica van uw toepassingen.

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

Afspelen verbeteren met caching van audiobestanden

Als u hetzelfde audiobestand meerdere keren afspeelt, kan uw toepassing Azure Communication Services voorzien van de sourceID voor het audiobestand. Azure Communication Services slaat dit audiobestand gedurende 1 uur in de cache op.

Notitie

Het opslaan van audiobestanden in de cache is niet geschikt voor dynamische prompts. Als u de opgegeven URL wijzigt in Azure Communication Services, wordt de URL in de cache niet meteen bijgewerkt. De update vindt plaats nadat de bestaande cache is verlopen.

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

Actie-updates voor afspelen verwerken

Uw toepassing ontvangt updates voor de levenscyclus van acties op de callback-URL die is verstrekt aan de Call Automation-service op het moment van het beantwoorden van de oproep.

Voorbeeld van hoe u deserialiseren van de PlayCompleted-gebeurtenis kunt deserialiseren :

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

Voorbeeld van hoe u deserialiseren van de PlayFailed-gebeurtenis kunt deserialiseren :

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

Ga naar het overzichtsdocument gespreksautomatisering voor meer informatie over andere ondersteunde gebeurtenissen.

Actie Afspelen annuleren

Alle mediabewerkingen annuleren, alle in behandeling zijnde mediabewerkingen worden geannuleerd. Met deze actie worden ook andere acties voor afspelen in de wachtrij geannuleerd.

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

Voorbeeld van hoe u deserialiseren van de playCanceled-gebeurtenis :

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

Vereisten

Voor AI-functies

Een nieuwe Python-toepassing maken

Een virtuele Python-omgeving instellen voor uw project

python -m venv play-audio-app

Uw virtuele omgeving activeren

Gebruik in Windows de volgende opdracht:

.\ play-audio-quickstart \Scripts\activate

Gebruik in Unix de volgende opdracht:

source play-audio-quickstart /bin/activate

Het Azure Communication Services Call Automation-pakket installeren

pip install azure-communication-callautomation

Maak uw toepassingsbestand in uw projectmap, bijvoorbeeld de naam app.py. U schrijft uw Python-code in dit bestand.

Voer uw toepassing uit met behulp van Python met de volgende opdracht om code uit te voeren.

python app.py

(Optioneel) Bereid uw audiobestand voor als u audiobestanden wilt gebruiken voor het afspelen van prompts

Maak een audiobestand als u er nog geen hebt, om te gebruiken voor het afspelen van prompts en berichten aan deelnemers. Het audiobestand moet worden gehost op een locatie die toegankelijk is voor Azure Communication Services met ondersteuning voor verificatie. Bewaar een kopie van de URL die u kunt gebruiken bij het aanvragen om het audiobestand af te spelen. Azure Communication Services ondersteunt zowel bestandstypen van MP3- als WAV-bestanden, mono 16-bits PCM met een samplefrequentie van 16 KHz. .

U kunt het maken van uw eigen audiobestand testen met behulp van onze spraaksynthese met het hulpprogramma Audio-inhoud maken.

(Optioneel) Verbinding maken uw Azure Cognitive Service naar uw Azure Communication Service

Als u tekst-naar-spraak-mogelijkheden wilt gebruiken, moet u uw Azure Cognitive Service verbinden met uw Azure Communication Service.

Een oproep tot stand brengen

Op dit punt moet u bekend zijn met het starten van oproepen, als u meer wilt weten over het maken van een gesprek, volgt u onze quickstart. U kunt ook het hier opgegeven codefragment gebruiken om te begrijpen hoe u een oproep beantwoordt.

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

Audio afspelen

Zodra het gesprek tot stand is gebracht, zijn er meerdere opties voor het afspelen van de audio. U kunt audio afspelen naar de deelnemer die deel uitmaakt van het gesprek of audio afspelen voor alle deelnemers in het gesprek.

Bron afspelen - audiobestand

Als u audio wilt afspelen voor deelnemers met behulp van audiobestanden, moet u ervoor zorgen dat het audiobestand een WAV-bestand, mono en 16 KHz is. Als u audiobestanden wilt afspelen, moet u ervoor zorgen dat u Azure Communication Services een URI verstrekt aan een bestand dat u host op een locatie waar Azure Communication Services toegang heeft. Het type FileSource in onze SDK kan worden gebruikt om audiobestanden voor de afspeelactie op te geven.

play_source = FileSource(url=audioUri)

Bron afspelen - Tekst-naar-spraak

Als u audio wilt afspelen met behulp van Text-To-Speech via Azure AI-services, moet u de tekst opgeven die u wilt afspelen, evenals de SourceLocale en VoiceKind of de VoiceName die u wilt gebruiken. We ondersteunen hier alle spraaknamen die worden ondersteund door Azure AI-services, in de volledige lijst.

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
)

Bron afspelen - Tekst-naar-spraak met SSML

Als u uw tekst-naar-spraak-uitvoer nog meer wilt aanpassen met Azure AI-services, kunt u Speech Synthesis Markup Language SSML gebruiken bij het aanroepen van uw afspeelactie via Call Automation. Met SSML kunt u de toonhoogte verfijnen, onderbreken, uitspraak verbeteren, spreeksnelheid wijzigen, volume aanpassen en meerdere stemmen aanbrengen.

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
)

Aangepaste spraakmodellen

Als u uw prompts meer wilt verbeteren en aangepaste spraakmodellen wilt opnemen, ondersteunt de actie Tekst-naar-spraak afspelen nu deze aangepaste stemmen. Dit is een uitstekende optie als u klanten een meer lokale, persoonlijke ervaring wilt geven of situaties hebt waarin de standaardmodellen mogelijk niet de woorden en accenten behandelen die u probeert uit te spreken. Lees deze handleiding voor meer informatie over het maken en implementeren van aangepaste modellen.

Aangepaste spraaknamen, reguliere tekstoverzicht

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-voorbeeld van aangepaste spraaknamen

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
)

Zodra u hebt besloten welke playSource u wilt gebruiken voor het afspelen van audio, kunt u vervolgens kiezen of u deze wilt afspelen aan een specifieke deelnemer of aan alle deelnemers.

Audio afspelen - Alle deelnemers

Een vooraf opgenomen audiobestand afspelen voor alle deelnemers aan het gesprek.

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
)

Audio afspelen - Specifieke deelnemer

Een vooraf opgenomen audiobestand afspelen naar een specifieke deelnemer in het gesprek.

play_to = [target_participant]

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

Audio afspelen op lus

U kunt de lusoptie gebruiken om muziek die lussen afspeelt af te spelen totdat uw toepassing klaar is om de beller te accepteren. U kunt ook de aanroeper naar de volgende logische stap doorschakelen op basis van de bedrijfslogica van uw toepassingen.

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
)

Afspelen verbeteren met caching van audiobestanden

Als u hetzelfde audiobestand meerdere keren afspeelt, kan uw toepassing Azure Communication Services voorzien van de sourceID voor het audiobestand. Azure Communication Services slaat dit audiobestand gedurende 1 uur in de cache op.

Notitie

Het opslaan van audiobestanden in de cache is niet geschikt voor dynamische prompts. Als u de opgegeven URL wijzigt in Azure Communication Services, wordt de URL in de cache niet meteen bijgewerkt. De update vindt plaats nadat de bestaande cache is verlopen.

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
)

Actie-updates voor afspelen verwerken

Uw toepassing ontvangt updates voor de levenscyclus van acties op de callback-URL die is verstrekt aan de Call Automation-service op het moment van het beantwoorden van de oproep.

Voorbeeld van hoe u deserialiseren van de PlayCompleted-gebeurtenis kunt deserialiseren :

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

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

Voorbeeld van hoe u deserialiseren van de PlayFailed-gebeurtenis kunt deserialiseren :

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

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

Ga naar het overzichtsdocument gespreksautomatisering voor meer informatie over andere ondersteunde gebeurtenissen.

Actie Afspelen annuleren

Alle mediabewerkingen annuleren, alle in behandeling zijnde mediabewerkingen worden geannuleerd. Met deze actie worden ook andere acties voor afspelen in de wachtrij geannuleerd.

call_automation_client.get_call_connection(
    call_connection_id
).cancel_all_media_operations()

Voorbeeld van hoe u deserialiseren van de playCanceled-gebeurtenis :

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

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

Gebeurteniscodes

Status Code Subcode Bericht
PlayCompleted 200 0 De actie is voltooid.
PlayCanceled 400 8508 De actie is mislukt, de bewerking is geannuleerd.
PlayFailed 400 8535 De actie is mislukt, de bestandsindeling is ongeldig.
PlayFailed 400 8536 De actie is mislukt. Het bestand kan niet worden gedownload.
PlayFailed 400 8565 Actie is mislukt, ongeldige aanvraag voor Azure AI-services. Controleer de invoerparameters.
PlayFailed 401 8565 De actie is mislukt, verificatiefout in Azure AI-services.
PlayFailed 403 8565 Actie is mislukt, verboden aanvraag voor Azure AI-services, gratis abonnement dat door de aanvraag wordt gebruikt, heeft geen quotum meer.
PlayFailed 429 8565 Actie is mislukt, aanvragen hebben het aantal toegestane gelijktijdige aanvragen voor het Azure AI-servicesabonnement overschreden.
PlayFailed 408 8565 Er is een time-out opgetreden voor de actie van Azure AI-services.
PlayFailed 500 9999 Onbekende interne serverfout
PlayFailed 500 8572 De actie is mislukt vanwege het afsluiten van de play-service.

Bekende beperkingen

  • Tekst-naar-spraak-tekstprompts ondersteunen maximaal 400 tekens, als uw prompt langer is dan dit, raden we u aan om SSML te gebruiken voor op tekst-naar-spraak gebaseerde afspeelacties.
  • Voor scenario's waarin u de quotumlimiet van de Speech-service overschrijdt, kunt u aanvragen om deze lilmit te verhogen door de stappen te volgen die hier worden beschreven.

Resources opschonen

Als u een Communication Services-abonnement wilt opschonen en verwijderen, kunt u de resource of resourcegroep verwijderen. Als u de resourcegroep verwijdert, worden ook alle bijbehorende resources verwijderd. Meer informatie over het opschonen van resources.

Volgende stappen