Anpassa röstmeddelanden till användare med uppspelningsåtgärd

  • Artikel

Den här guiden hjälper dig att komma igång med att spela upp ljudfiler till deltagarna med hjälp av uppspelningsåtgärden som tillhandahålls via Azure Communication Services Call Automation SDK.

Förutsättningar

För AI-funktioner

Skapa ett nytt C#-program

I konsolfönstret i operativsystemet använder du dotnet kommandot för att skapa ett nytt webbprogram.

dotnet new web -n MyApplication

Installera NuGet-paketet

NuGet-paketet kan hämtas härifrån, om du inte redan har gjort det.

(Valfritt) Förbered ljudfilen om du vill använda ljudfiler för att spela upp frågor

Skapa en ljudfil, om du inte redan har en, som du kan använda för att spela upp frågor och meddelanden till deltagarna. Ljudfilen måste finnas på en plats som är tillgänglig för Azure Communication Services med stöd för autentisering. Behåll en kopia av url:en som du kan använda när du begär att spela upp ljudfilen. Azure Communication Services stöder båda filtyperna av MP3-filer med ID3V2TAG - och WAV-filer, mono 16-bitars PCM med 16 KHz-exempelfrekvens. .

Du kan testa att skapa en egen ljudfil med hjälp av vårt talsyntes med verktyget Skapa ljudinnehåll.

(Valfritt) Anslut din Azure Cognitive Service till Azure Communication Service

Om du vill använda text-till-tal-funktioner måste du ansluta Azure Cognitive Service till Azure Communication Service.

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. Du kan också använda kodfragmentet här för att förstå hur du besvarar ett samtal.

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

Spela upp ljud

När samtalet har upprättats finns det flera alternativ för hur du vill spela upp ljudet. Du kan spela upp ljud till deltagaren som har anslutit samtalet eller spela upp ljud till alla deltagare i samtalet.

Uppspelningskälla – ljudfil

Om du vill spela upp ljud till deltagare med hjälp av ljudfiler måste du se till att ljudfilen är en WAV-fil, mono och 16 KHz. Om du vill spela upp ljudfiler måste du se till att du tillhandahåller Azure Communication Services med en URI till en fil som du är värd för på en plats där Azure Communication Services kan komma åt den. FileSource-typen i vårt SDK kan användas för att ange ljudfiler för uppspelningsåtgärden.

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

Uppspelningskälla – text till tal

Om du vill spela upp ljud med text-till-tal via Azure AI-tjänster måste du ange den text som du vill spela upp, samt antingen SourceLocale och VoiceKind eller voicename som du vill använda. Vi stöder alla röstnamn som stöds av Azure AI-tjänster, fullständig lista här.

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

Uppspelningskälla – Text till tal med SSML

Om du vill anpassa dina text-till-tal-utdata ännu mer med Azure AI-tjänster kan du använda Speech Synthesis Markup Language SSML när du anropar din uppspelningsåtgärd via Samtalsautomation. Med SSML kan du finjustera tonhöjden, pausa, förbättra uttalet, ändra talfrekvens, justera volym och attribut flera röster.

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

Anpassade röstmodeller

Om du vill förbättra dina frågor mer och inkludera anpassade röstmodeller stöder uppspelningsåtgärden Text-till-Tal nu dessa anpassade röster. Dessa är ett bra alternativ om du försöker ge kunderna en mer lokal, personlig upplevelse eller har situationer där standardmodellerna kanske inte täcker de ord och accenter som du försöker uttala. Mer information om hur du skapar och distribuerar anpassade modeller finns i den här guiden.

Vanlig textexmaple för anpassade röstnamn

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

SSML-exempel för anpassade röstnamn


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

När du har bestämt dig för vilken playSource du vill använda för att spela upp ljud kan du sedan välja om du vill spela upp den för en specifik deltagare eller till alla deltagare.

Spela upp ljud för alla deltagare

I det här scenariot spelas ljud upp för alla deltagare i samtalet.

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

Spela upp ljud till en specifik deltagare

I det här scenariot spelas ljud upp för en specifik deltagare.

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

Spela upp ljud på loop

Du kan använda loopalternativet för att spela upp musik som loopar tills programmet är redo att acceptera anroparen. Eller föra anroparen vidare till nästa logiska steg baserat på dina program affärslogik.

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

Förbättra uppspelning med cachelagring av ljudfiler

Om du spelar upp samma ljudfil flera gånger kan programmet tillhandahålla Azure Communication Services med sourceID för ljudfilen. Azure Communication Services cachelagrar den här ljudfilen i 1 timme.

Kommentar

Cachelagring ljudfiler är inte lämpliga för dynamiska frågor. Om du ändrar url:en som tillhandahålls till Azure Communication Services uppdaterar den inte den cachelagrade URL:en direkt. Uppdateringen sker när den befintliga cachen upphör att gälla.

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

Hantera händelseuppdateringar för uppspelningsåtgärd

Ditt program tar emot händelseuppdateringar för åtgärdslivscykeln på den motringnings-URL som tillhandahölls till Tjänsten För samtalsautomatisering när samtalet besvarades. Ett exempel på en lyckad uppdatering av uppspelningshändelser.

Exempel på hur du kan deserialisera händelsen PlayCompleted :

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

Exempel på hur du kan deserialisera PlayFailed-händelsen :

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

Mer information om andra händelser som stöds finns i översiktsdokumentet för Samtalsautomation.

Avbryt uppspelningsåtgärden

Avbryt alla medieåtgärder, alla väntande medieåtgärder avbryts. Den här åtgärden avbryter även andra uppspelningsåtgärder i kö.

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

Exempel på hur du kan deserialisera händelsen PlayCanceled :

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

Förutsättningar

För AI-funktioner

Skapa ett nytt Java-program

I terminalen eller kommandofönstret navigerar du till den katalog där du vill skapa java-programmet. Kör kommandot som visas här för att generera Java-projektet från mallen maven-archetype-quickstart.

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

Föregående kommando skapar en katalog med samma namn som artifactId argumentet. Under den här katalogen src/main/java innehåller katalogen projektets källkod, src/test/java katalogen innehåller testkällan.

Du märker att steget "generera" skapade en katalog med samma namn som artifactId. Under den här katalogen src/main/java innehåller katalogen källkod, src/test/java katalogen innehåller tester och pom.xml filen är projektets projektobjektmodell eller POM.

Uppdatera pom-filen för dina program så att den använder Java 8 eller senare.

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

Lägga till paketreferenser

Lägg till följande referens för projektet i POM-filen.

azure-communication-callautomation

Azure Communication Services Call Automation SDK-paketet hämtas från Azure SDK Dev Feed.

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

(Valfritt) Förbered ljudfilen om du vill använda ljudfiler för att spela upp frågor

Skapa en ljudfil, om du inte redan har en, som du kan använda för att spela upp frågor och meddelanden till deltagarna. Ljudfilen måste finnas på en plats som är tillgänglig för Azure Communication Services med stöd för autentisering. Behåll en kopia av url:en som du kan använda när du begär att spela upp ljudfilen. Azure Communication Services stöder båda filtyperna av MP3-filer med ID3V2TAG - och WAV-filer, mono 16-bitars PCM med 16 KHz-exempelfrekvens. .

Du kan testa att skapa en egen ljudfil med hjälp av vårt talsyntes med verktyget Skapa ljudinnehåll.

(Valfritt) Anslut din Azure Cognitive Service till Azure Communication Service

Om du vill använda text-till-tal-funktioner måste du ansluta Azure Cognitive Service till Azure Communication Service.

Uppdatera App.java med kod

Öppna App.java fil i valfri redigerare och uppdatera den med koden som anges i Avsnittet Uppdatera app.java med kod .

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. Du kan också använda kodfragmentet här för att förstå hur du besvarar ett samtal.

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

Spela upp ljud

När samtalet har upprättats finns det flera alternativ för hur du vill spela upp ljudet. Du kan spela upp ljud till deltagaren som har anslutit samtalet eller spela upp ljud till alla deltagare i samtalet.

Uppspelningskälla – ljudfil

Om du vill spela upp ljud till deltagare med hjälp av ljudfiler måste du se till att ljudfilen är en WAV-fil, mono och 16 KHz. Om du vill spela upp ljudfiler måste du se till att du tillhandahåller Azure Communication Services med en URI till en fil som du är värd för på en plats där Azure Communication Services kan komma åt den. FileSource-typen i vårt SDK kan användas för att ange ljudfiler för uppspelningsåtgärden.

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

Uppspelningskälla – text till tal

Om du vill spela upp ljud med text-till-tal via Azure AI-tjänster måste du ange den text som du vill spela upp, samt antingen SourceLocale och VoiceKind eller voicename som du vill använda. Vi stöder alla röstnamn som stöds av Azure AI-tjänster, fullständig lista här.

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

Uppspelningskälla – Text-till-tal-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);

Anpassade röstmodeller

Om du vill förbättra dina frågor mer och inkludera anpassade röstmodeller stöder uppspelningsåtgärden Text-till-Tal nu dessa anpassade röster. Dessa är ett bra alternativ om du försöker ge kunderna en mer lokal, personlig upplevelse eller har situationer där standardmodellerna kanske inte täcker de ord och accenter som du försöker uttala. Mer information om hur du skapar och distribuerar anpassade modeller finns i den här guiden.

Vanlig textexmaple för anpassade röstnamn

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

SSML-exempel för anpassade röstnamn

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

När du har bestämt dig för vilken playSource du vill använda för att spela upp ljud kan du sedan välja om du vill spela upp den för en specifik deltagare eller till alla deltagare.

Spela upp ljud för alla deltagare

I det här scenariot spelas ljud upp för alla deltagare i samtalet.

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

Spela upp ljud till en specifik deltagare

I det här scenariot spelas ljud upp för en specifik deltagare.

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

Spela upp ljud på loop

Du kan använda loopalternativet för att spela upp musik som loopar tills programmet är redo att acceptera anroparen. Eller föra anroparen vidare till nästa logiska steg baserat på dina program affärslogik.

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

Förbättra uppspelning med cachelagring av ljudfiler

Om du spelar upp samma ljudfil flera gånger kan programmet tillhandahålla Azure Communication Services med sourceID för ljudfilen. Azure Communication Services cachelagrar den här ljudfilen i 1 timme.

Kommentar

Cachelagring ljudfiler är inte lämpliga för dynamiska frågor. Om du ändrar url:en som tillhandahålls till Azure Communication Services uppdaterar den inte den cachelagrade URL:en direkt. Uppdateringen sker när den befintliga cachen upphör att gälla.

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

Hantera händelseuppdateringar för uppspelningsåtgärd

Ditt program tar emot händelseuppdateringar för åtgärdslivscykeln på den motringnings-URL som tillhandahölls till Tjänsten För samtalsautomatisering när samtalet besvarades. Ett exempel på en lyckad uppdatering av uppspelningshändelser.

Exempel på hur du kan deserialisera händelsen PlayCompleted :

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

Exempel på hur du kan deserialisera PlayFailed-händelsen :

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

Mer information om andra händelser som stöds finns i översiktsdokumentet för Samtalsautomation.

Avbryt uppspelningsåtgärden

Avbryt alla medieåtgärder, alla väntande medieåtgärder avbryts. Den här åtgärden avbryter även andra uppspelningsåtgärder i kö.

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

Exempel på hur du kan deserialisera händelsen PlayCanceled :

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

Förutsättningar

För AI-funktioner

Skapa ett nytt JavaScript-program

Skapa ett nytt JavaScript-program i projektkatalogen. Initiera ett nytt Node.js projekt med följande kommando. Detta skapar en package.json fil för projektet, som används för att hantera projektets beroenden.

npm init -y

Installera Azure Communication Services Call Automation-paketet

npm install @azure/communication-call-automation

Skapa en ny JavaScript-fil i projektkatalogen, till exempel ge den namnet app.js. Du skriver JavaScript-koden i den här filen. Kör programmet med Node.js med följande kommando. Den här koden kör JavaScript-koden som du har skrivit.

node app.js

(Valfritt) Förbered ljudfilen om du vill använda ljudfiler för att spela upp frågor

Skapa en ljudfil, om du inte redan har en, som du kan använda för att spela upp frågor och meddelanden till deltagarna. Ljudfilen måste finnas på en plats som är tillgänglig för Azure Communication Services med stöd för autentisering. Behåll en kopia av url:en som du kan använda när du begär att spela upp ljudfilen. Azure Communication Services stöder båda filtyperna av MP3-filer med ID3V2TAG - och WAV-filer, mono 16-bitars PCM med 16 KHz-exempelfrekvens.

Du kan testa att skapa en egen ljudfil med hjälp av vårt talsyntes med verktyget Skapa ljudinnehåll.

(Valfritt) Anslut din Azure Cognitive Service till Azure Communication Service

Om du vill använda text-till-tal-funktioner måste du ansluta Azure Cognitive Service till Azure Communication Service.

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. Du kan också använda kodfragmentet här för att förstå hur du besvarar ett samtal.

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

Spela upp ljud

När samtalet har upprättats finns det flera alternativ för hur du vill spela upp ljudet. Du kan spela upp ljud till deltagaren som har anslutit samtalet eller spela upp ljud till alla deltagare i samtalet.

Uppspelningskälla – ljudfil

Om du vill spela upp ljud till deltagare med hjälp av ljudfiler måste du se till att ljudfilen är en WAV-fil, mono och 16 KHz. Om du vill spela upp ljudfiler måste du se till att du tillhandahåller Azure Communication Services med en URI till en fil som du är värd för på en plats där Azure Communication Services kan komma åt den. FileSource-typen i vårt SDK kan användas för att ange ljudfiler för uppspelningsåtgärden.

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

Uppspelningskälla – text till tal

Om du vill spela upp ljud med text-till-tal via Azure AI-tjänster måste du ange den text som du vill spela upp, samt antingen SourceLocale och VoiceKind eller voicename som du vill använda. Vi stöder alla röstnamn som stöds av Azure AI-tjänster, fullständig lista här.

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

Uppspelningskälla – Text till tal med SSML

Om du vill anpassa dina text-till-tal-utdata ännu mer med Azure AI-tjänster kan du använda Speech Synthesis Markup Language SSML när du anropar din uppspelningsåtgärd via Samtalsautomation. Med SSML kan du finjustera tonhöjden, pausa, förbättra uttalet, ändra talfrekvens, justera volym och attribut flera röster.

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

Anpassade röstmodeller

Om du vill förbättra dina frågor mer och inkludera anpassade röstmodeller stöder uppspelningsåtgärden Text-till-Tal nu dessa anpassade röster. Dessa är ett bra alternativ om du försöker ge kunderna en mer lokal, personlig upplevelse eller har situationer där standardmodellerna kanske inte täcker de ord och accenter som du försöker uttala. Mer information om hur du skapar och distribuerar anpassade modeller finns i den här guiden.

Vanlig textexmaple för anpassade röstnamn

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

SSML-exempel för anpassade röstnamn

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

När du har bestämt dig för vilken playSource du vill använda för att spela upp ljud kan du sedan välja om du vill spela upp den för en specifik deltagare eller till alla deltagare.

Spela upp ljud – alla deltagare

I det här scenariot spelas ljud upp för alla deltagare i samtalet.

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

Spela upp ljud – specifik deltagare

I det här scenariot spelas ljud upp för en specifik deltagare.

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

Spela upp ljud på loop

Du kan använda loopalternativet för att spela upp musik som loopar tills programmet är redo att acceptera anroparen. Eller föra anroparen vidare till nästa logiska steg baserat på dina program affärslogik.

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

Förbättra uppspelning med cachelagring av ljudfiler

Om du spelar upp samma ljudfil flera gånger kan programmet tillhandahålla Azure Communication Services med sourceID för ljudfilen. Azure Communication Services cachelagrar den här ljudfilen i 1 timme.

Kommentar

Cachelagring ljudfiler är inte lämpliga för dynamiska frågor. Om du ändrar url:en som tillhandahålls till Azure Communication Services uppdaterar den inte den cachelagrade URL:en direkt. Uppdateringen sker när den befintliga cachen upphör att gälla.

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

Hantera händelseuppdateringar för uppspelningsåtgärd

Ditt program tar emot händelseuppdateringar för åtgärdslivscykeln på den motringnings-URL som tillhandahölls till Tjänsten För samtalsautomatisering när samtalet besvarades.

Exempel på hur du kan deserialisera händelsen PlayCompleted :

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

Exempel på hur du kan deserialisera PlayFailed-händelsen :

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

Mer information om andra händelser som stöds finns i översiktsdokumentet för Samtalsautomation.

Avbryt uppspelningsåtgärden

Avbryt alla medieåtgärder, alla väntande medieåtgärder avbryts. Den här åtgärden avbryter även andra uppspelningsåtgärder i kö.

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

Exempel på hur du kan deserialisera händelsen PlayCanceled :

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

Förutsättningar

För AI-funktioner

Skapa ett nytt Python-program

Konfigurera en virtuell Python-miljö för projektet

python -m venv play-audio-app

Aktivera din virtuella miljö

Använd följande kommando i Windows:

.\ play-audio-quickstart \Scripts\activate

Använd följande kommando i Unix:

source play-audio-quickstart /bin/activate

Installera Azure Communication Services Call Automation-paketet

pip install azure-communication-callautomation

Skapa programfilen i projektkatalogen, till exempel ge den namnet app.py. Du skriver Python-koden i den här filen.

Kör ditt program med Python med följande kommando för att köra kod.

python app.py

(Valfritt) Förbered ljudfilen om du vill använda ljudfiler för att spela upp frågor

Skapa en ljudfil, om du inte redan har en, som du kan använda för att spela upp frågor och meddelanden till deltagarna. Ljudfilen måste finnas på en plats som är tillgänglig för Azure Communication Services med stöd för autentisering. Behåll en kopia av url:en som du kan använda när du begär att spela upp ljudfilen. Azure Communication Services stöder både filtyper av MP3 - och WAV-filer, mono 16-bitars PCM med 16 KHz-exempelfrekvens. .

Du kan testa att skapa en egen ljudfil med hjälp av vårt talsyntes med verktyget Skapa ljudinnehåll.

(Valfritt) Anslut din Azure Cognitive Service till Azure Communication Service

Om du vill använda text-till-tal-funktioner måste du ansluta Azure Cognitive Service till Azure Communication Service.

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. Du kan också använda kodfragmentet här för att förstå hur du besvarar ett samtal.

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

Spela upp ljud

När samtalet har upprättats finns det flera alternativ för hur du vill spela upp ljudet. Du kan spela upp ljud till deltagaren som har anslutit samtalet eller spela upp ljud till alla deltagare i samtalet.

Uppspelningskälla – ljudfil

Om du vill spela upp ljud till deltagare med hjälp av ljudfiler måste du se till att ljudfilen är en WAV-fil, mono och 16 KHz. Om du vill spela upp ljudfiler måste du se till att du tillhandahåller Azure Communication Services med en URI till en fil som du är värd för på en plats där Azure Communication Services kan komma åt den. FileSource-typen i vårt SDK kan användas för att ange ljudfiler för uppspelningsåtgärden.

play_source = FileSource(url=audioUri)

Uppspelningskälla – text till tal

Om du vill spela upp ljud med text-till-tal via Azure AI-tjänster måste du ange den text som du vill spela upp, samt antingen SourceLocale och VoiceKind eller voicename som du vill använda. Vi stöder alla röstnamn som stöds av Azure AI-tjänster, fullständig lista här.

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
)

Uppspelningskälla – Text till tal med SSML

Om du vill anpassa dina text-till-tal-utdata ännu mer med Azure AI-tjänster kan du använda Speech Synthesis Markup Language SSML när du anropar din uppspelningsåtgärd via Samtalsautomation. Med SSML kan du finjustera tonhöjden, pausa, förbättra uttalet, ändra talfrekvens, justera volym och attribut flera röster.

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
)

Anpassade röstmodeller

Om du vill förbättra dina frågor mer och inkludera anpassade röstmodeller stöder uppspelningsåtgärden Text-till-Tal nu dessa anpassade röster. Dessa är ett bra alternativ om du försöker ge kunderna en mer lokal, personlig upplevelse eller har situationer där standardmodellerna kanske inte täcker de ord och accenter som du försöker uttala. Mer information om hur du skapar och distribuerar anpassade modeller finns i den här guiden.

Vanlig textexmaple för anpassade röstnamn

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-exempel för anpassade röstnamn

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
)

När du har bestämt dig för vilken playSource du vill använda för att spela upp ljud kan du sedan välja om du vill spela upp den för en specifik deltagare eller till alla deltagare.

Spela upp ljud – alla deltagare

Spela upp en förinspelad ljudfil för alla deltagare i samtalet.

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
)

Spela upp ljud – specifik deltagare

Spela upp en förinspelad ljudfil till en specifik deltagare i samtalet.

play_to = [target_participant]

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

Spela upp ljud på loop

Du kan använda loopalternativet för att spela upp musik som loopar tills programmet är redo att acceptera anroparen. Eller föra anroparen vidare till nästa logiska steg baserat på dina program affärslogik.

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
)

Förbättra uppspelning med cachelagring av ljudfiler

Om du spelar upp samma ljudfil flera gånger kan programmet tillhandahålla Azure Communication Services med sourceID för ljudfilen. Azure Communication Services cachelagrar den här ljudfilen i 1 timme.

Kommentar

Cachelagring ljudfiler är inte lämpliga för dynamiska frågor. Om du ändrar url:en som tillhandahålls till Azure Communication Services uppdaterar den inte den cachelagrade URL:en direkt. Uppdateringen sker när den befintliga cachen upphör att gälla.

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
)

Hantera händelseuppdateringar för uppspelningsåtgärd

Ditt program tar emot händelseuppdateringar för åtgärdslivscykeln på den motringnings-URL som tillhandahölls till Tjänsten För samtalsautomatisering när samtalet besvarades.

Exempel på hur du kan deserialisera händelsen PlayCompleted :

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

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

Exempel på hur du kan deserialisera PlayFailed-händelsen :

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

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

Mer information om andra händelser som stöds finns i översiktsdokumentet för Samtalsautomation.

Avbryt uppspelningsåtgärden

Avbryt alla medieåtgärder, alla väntande medieåtgärder avbryts. Den här åtgärden avbryter även andra uppspelningsåtgärder i kö.

call_automation_client.get_call_connection(
    call_connection_id
).cancel_all_media_operations()

Exempel på hur du kan deserialisera händelsen PlayCanceled :

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

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

Händelsekoder

Status Kod Underkod Meddelande
PlayCompleted 200 0 Åtgärden har slutförts.
PlayCanceled 400 8508 Åtgärden misslyckades, åtgärden avbröts.
PlayFailed 400 8535 Åtgärden misslyckades, filformatet är ogiltigt.
PlayFailed 400 8536 Åtgärden misslyckades, filen kunde inte laddas ned.
PlayFailed 400 8565 Åtgärden misslyckades, felaktig begäran till Azure AI-tjänster. Kontrollera indataparametrar.
PlayFailed 401 8565 Åtgärden misslyckades, autentiseringsfel för Azure AI-tjänster.
PlayFailed 403 8565 Åtgärden misslyckades, den förbjudna begäran till Azure AI-tjänster, den kostnadsfria prenumerationen som användes av begäran tog slut.
PlayFailed 429 8565 Åtgärden misslyckades, begäranden överskred antalet tillåtna samtidiga begäranden för Azure AI-tjänsteprenumerationen.
PlayFailed 408 8565 Åtgärden misslyckades, tidsgränsen för begäran till Azure AI-tjänster.
PlayFailed 500 9999 Okänt internt serverfel
PlayFailed 500 8572 Åtgärden misslyckades på grund av avstängning av uppspelningstjänsten.

Kända begränsningar

  • Text-till-tal-textprompter stöder högst 400 tecken, om din fråga är längre än detta föreslår vi att du använder SSML för text-till-tal-baserade uppspelningsåtgärder.
  • För scenarier där du överskrider kvotgränsen för Speech-tjänsten kan du begära att den här lilmiten ökar genom att följa stegen som beskrivs här.

Rensa resurser

Om du vill rensa och ta bort en Communication Services-prenumeration kan du ta bort resursen eller resursgruppen. Om du tar bort resursgruppen tas även alla andra resurser som är associerade med den bort. Läs mer om att rensa resurser.

Nästa steg