Přizpůsobení hlasových výzev uživatelům pomocí akce Přehrát

Tato příručka vám pomůže začít přehrávat zvukové soubory účastníkům pomocí akce přehrávání poskytované prostřednictvím sady SDK služby Azure Communication Services Call Automation.

Požadavky

• Podrobnosti o účtu Azure s aktivním předplatným najdete v tématu Vytvoření účtu zdarma.
• Prostředek Azure Communication Services Viz Vytvoření prostředku Azure Communication Services. Uložte připojovací řetězec pro tento prostředek.
• Vytvořte novou aplikaci webové služby pomocí sady SDK pro automatizaci volání.
• Nejnovější knihovna .NET pro váš operační systém.
• Získejte nejnovější balíček NuGet.

Funkce AI

• Vytvořte a připojte služby Azure AI k prostředku Azure Communication Services.
• Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.

Vytvoření nové aplikace jazyka C#

V okně konzoly operačního systému pomocí dotnet příkazu vytvořte novou webovou aplikaci.

dotnet new web -n MyApplication

Instalace balíčku NuGet

Balíček NuGet můžete získat odsud, pokud jste to ještě neudělali.

(Volitelné) Příprava zvukového souboru, pokud chcete k přehrávání výzev použít zvukové soubory

Pokud ho ještě nemáte, vytvořte zvukový soubor, který můžete použít k přehrávání výzev a zpráv účastníkům. Zvukový soubor musí být hostovaný v umístění, které je přístupné službě Azure Communication Services s podporou ověřování. Uchovávejte kopii adresy URL, kterou můžete použít při žádosti o přehrání zvukového souboru. Azure Communication Services podporuje oba typy souborů MP3 se soubory ID3V2TAG a WAV, mono 16bitové PCM s vzorkovací rychlostí 16 KHz. .

Vytvoření vlastního zvukového souboru můžete otestovat pomocí našeho nástroje Pro syntézu řeči pomocí nástroje Pro vytváření zvukového obsahu.

(Volitelné) Připojení služby Azure Cognitive Service do služby Azure Communication Service

Pokud chcete používat funkce převodu textu na řeč, je potřeba připojit službu Azure Cognitive Service ke službě Azure Communication Service.

Vytvoření hovoru

V tomto okamžiku byste měli být obeznámeni se spouštěním volání, pokud potřebujete získat další informace o volání, postupujte podle našeho rychlého startu. Můžete také použít fragment kódu, který je zde k dispozici, abyste pochopili, jak odpovědět na volání.

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

Přehrávání zvuku

Jakmile bude hovor vytvořen, existuje několik možností, jak můžete chtít přehrát zvuk. Zvuk můžete přehrát účastníkovi, který se připojil k hovoru, nebo přehrát zvuk všem účastníkům hovoru.

Přehrát zdroj – zvukový soubor

Pokud chcete přehrát zvuk účastníkům pomocí zvukových souborů, musíte se ujistit, že zvukový soubor je soubor WAV, mono a 16 KHz. Pokud chcete přehrávat zvukové soubory, musíte zajistit, abyste službě Azure Communication Services poskytli identifikátor URI souboru, který hostujete v umístění, kde k němu má přístup služba Azure Communication Services. Typ FileSource v naší sadě SDK lze použít k zadání zvukových souborů pro akci přehrávání.

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

Zdroj přehrávání – převod textu na řeč

Pokud chcete přehrávat zvuk pomocí převodu textu na řeč prostřednictvím služeb Azure AI, musíte zadat text, který chcete přehrát, a to buď SourceLocale, nebo VoiceKind nebo VoiceName, který chcete použít. Podporujeme všechna hlasová jména podporovaná službami Azure AI, úplný seznam zde.

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

Zdroj přehrávání – Převod textu na řeč pomocí SSML

Pokud chcete výstup převodu textu na řeč ještě více přizpůsobit pomocí služeb Azure AI, můžete použít SSML pro syntézu řeči při volání akce přehrávání prostřednictvím automatizace volání. Pomocí SSML můžete doladit tón, pozastavit, zlepšit výslovnost, změnit rychlost mluvení, upravit hlasitost a atribut více hlasů.

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

Vlastní hlasové modely

Pokud chcete své výzvy vylepšit a zahrnout vlastní hlasové modely, akce přehrávání převodu textu na řeč teď tyto vlastní hlasy podporuje. Jedná se o skvělou možnost, pokud se snažíte zákazníkům poskytnout více místního, přizpůsobeného prostředí nebo situace, kdy výchozí modely nemusí pokrývat slova a zvýraznění, které se snažíte vyslovovat. Další informace o vytváření a nasazování vlastních modelů najdete v této příručce.

Vlastní názvy hlasu – běžný text – exmaple

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

Příklad vlastních hlasových názvů SSML

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

Jakmile se rozhodnete, který playSource chcete použít k přehrávání zvuku, můžete zvolit, jestli ho chcete přehrát konkrétnímu účastníkovi nebo všem účastníkům.

Přehrání zvuku všem účastníkům

V tomto scénáři se zvuk přehraje všem účastníkům hovoru.

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

Přehrání zvuku konkrétnímu účastníkovi

V tomto scénáři se zvuk přehraje konkrétnímu účastníkovi.

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

Přehrávání zvuku ve smyčce

Pomocí možnosti smyčky můžete přehrávat hudbu, která smyčky přehrávají, dokud nebude vaše aplikace připravená přijmout volajícího. Nebo můžete volajícímu postupovat k dalšímu logickému kroku na základě obchodní logiky vašich aplikací.

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

Vylepšení přehrávání pomocí ukládání zvukových souborů do mezipaměti

Pokud vícekrát přehráváte stejný zvukový soubor, může vaše aplikace poskytnout službě Azure Communication Services id zdroje zvukového souboru. Azure Communication Services ukládá tento zvukový soubor do mezipaměti po dobu 1 hodiny.

Poznámka:

Ukládání do mezipaměti zvukové soubory nejsou vhodné pro dynamické výzvy. Pokud změníte adresu URL zadanou službou Azure Communication Services, neaktualizuje adresu URL uloženou v mezipaměti hned. Aktualizace proběhne po vypršení platnosti existující mezipaměti.

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

Zpracování aktualizací událostí akce přehrávání

Aplikace obdrží aktualizace událostí životního cyklu akcí na adrese URL zpětného volání, která byla poskytována službě Automation volání v době přijetí hovoru. Příklad úspěšné aktualizace události přehrávání

Příklad, jak můžete deserializovat událost PlayCompleted :

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

Příklad, jak můžete deserializovat událost PlayFailed :

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

Další informace o dalších podporovaných událostech najdete v dokumentu s přehledem služby Call Automation.

Zrušit akci přehrávání

Zrušit všechny operace médií, všechny čekající operace médií jsou zrušeny. Tato akce také zruší další akce přehrávání ve frontě.

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

Příklad, jak můžete deserializovat událost PlayCanceled :

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

Požadavky

• Podrobnosti o účtu Azure s aktivním předplatným najdete v tématu Vytvoření účtu zdarma.
• Prostředek Azure Communication Services Viz Vytvoření prostředku Azure Communication Services
• Vytvořte novou aplikaci webové služby pomocí sady SDK pro automatizaci volání.
• Java Development Kit verze 8 nebo novější.
• Apache Maven

Funkce AI

• Vytvořte a připojte služby Azure AI k prostředku Azure Communication Services.
• Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.

Vytvoření nové aplikace v Javě

V terminálu nebo příkazovém okně přejděte do adresáře, do kterého chcete vytvořit aplikaci v Javě. Spuštěním zde uvedeného příkazu vygenerujte projekt Java ze šablony maven-archetype-quickstart.

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

Předchozí příkaz vytvoří adresář se stejným názvem jako artifactId argument. V tomto adresáři src/main/java adresář obsahuje zdrojový kód projektu, src/test/java adresář obsahuje zdroj testu.

Všimněte si, že krok generate vytvořil adresář se stejným názvem jako artifactId. V tomto adresáři src/main/java adresář obsahuje zdrojový kód, src/test/java adresář obsahuje testy a pom.xml soubor je projektový objektový model nebo POM projektu.

Aktualizujte soubory POM aplikací tak, aby používaly Javu 8 nebo vyšší.

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

Přidání odkazů na balíčky

Do souboru POM přidejte následující odkaz na projekt.

azure-communication-callautomation

Balíček sady SDK služby Azure Communication Services pro automatizaci volání se načte z kanálu azure SDK pro vývoj.

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

(Volitelné) Příprava zvukového souboru, pokud chcete k přehrávání výzev použít zvukové soubory

Pokud ho ještě nemáte, vytvořte zvukový soubor, který můžete použít k přehrávání výzev a zpráv účastníkům. Zvukový soubor musí být hostovaný v umístění, které je přístupné službě Azure Communication Services s podporou ověřování. Uchovávejte kopii adresy URL, kterou můžete použít při žádosti o přehrání zvukového souboru. Azure Communication Services podporuje oba typy souborů MP3 se soubory ID3V2TAG a WAV, mono 16bitové PCM s vzorkovací rychlostí 16 KHz. .

Vytvoření vlastního zvukového souboru můžete otestovat pomocí našeho nástroje Pro syntézu řeči pomocí nástroje Pro vytváření zvukového obsahu.

(Volitelné) Připojení služby Azure Cognitive Service do služby Azure Communication Service

Pokud chcete používat funkce převodu textu na řeč, je potřeba připojit službu Azure Cognitive Service ke službě Azure Communication Service.

Aktualizace App.java pomocí kódu

Ve zvoleném editoru otevřete App.java soubor a aktualizujte ho kódem, který najdete v části Aktualizace app.java s kódem .

Vytvoření hovoru

V tomto okamžiku byste měli být obeznámeni se spouštěním volání, pokud potřebujete získat další informace o volání, postupujte podle našeho rychlého startu. Můžete také použít fragment kódu, který je zde k dispozici, abyste pochopili, jak odpovědět na volání.

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

Přehrávání zvuku

Jakmile bude hovor vytvořen, existuje několik možností, jak můžete chtít přehrát zvuk. Zvuk můžete přehrát účastníkovi, který se připojil k hovoru, nebo přehrát zvuk všem účastníkům hovoru.

Přehrát zdroj – zvukový soubor

Pokud chcete přehrát zvuk účastníkům pomocí zvukových souborů, musíte se ujistit, že zvukový soubor je soubor WAV, mono a 16 KHz. Pokud chcete přehrávat zvukové soubory, musíte zajistit, abyste službě Azure Communication Services poskytli identifikátor URI souboru, který hostujete v umístění, kde k němu má přístup služba Azure Communication Services. Typ FileSource v naší sadě SDK lze použít k zadání zvukových souborů pro akci přehrávání.

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

Zdroj přehrávání – převod textu na řeč

Pokud chcete přehrávat zvuk pomocí převodu textu na řeč prostřednictvím služeb Azure AI, musíte zadat text, který chcete přehrát, a to buď SourceLocale, nebo VoiceKind nebo VoiceName, který chcete použít. Podporujeme všechna hlasová jména podporovaná službami Azure AI, úplný seznam zde.

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

Zdroj přehrávání – SSML převodu textu na řeč

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

Vlastní hlasové modely

Pokud chcete své výzvy vylepšit a zahrnout vlastní hlasové modely, akce přehrávání převodu textu na řeč teď tyto vlastní hlasy podporuje. Jedná se o skvělou možnost, pokud se snažíte zákazníkům poskytnout více místního, přizpůsobeného prostředí nebo situace, kdy výchozí modely nemusí pokrývat slova a zvýraznění, které se snažíte vyslovovat. Další informace o vytváření a nasazování vlastních modelů najdete v této příručce.

Vlastní názvy hlasu – běžný text – exmaple

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

Příklad vlastních hlasových názvů SSML

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

Jakmile se rozhodnete, který playSource chcete použít k přehrávání zvuku, můžete zvolit, jestli ho chcete přehrát konkrétnímu účastníkovi nebo všem účastníkům.

Přehrání zvuku všem účastníkům

V tomto scénáři se zvuk přehraje všem účastníkům hovoru.

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

Přehrání zvuku konkrétnímu účastníkovi

V tomto scénáři se zvuk přehraje konkrétnímu účastníkovi.

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

Přehrávání zvuku ve smyčce

Pomocí možnosti smyčky můžete přehrávat hudbu, která smyčky přehrávají, dokud nebude vaše aplikace připravená přijmout volajícího. Nebo můžete volajícímu postupovat k dalšímu logickému kroku na základě obchodní logiky vašich aplikací.

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

Vylepšení přehrávání pomocí ukládání zvukových souborů do mezipaměti

Pokud vícekrát přehráváte stejný zvukový soubor, může vaše aplikace poskytnout službě Azure Communication Services id zdroje zvukového souboru. Azure Communication Services ukládá tento zvukový soubor do mezipaměti po dobu 1 hodiny.

Poznámka:

Ukládání do mezipaměti zvukové soubory nejsou vhodné pro dynamické výzvy. Pokud změníte adresu URL zadanou službou Azure Communication Services, neaktualizuje adresu URL uloženou v mezipaměti hned. Aktualizace proběhne po vypršení platnosti existující mezipaměti.

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

Zpracování aktualizací událostí akce přehrávání

Aplikace obdrží aktualizace událostí životního cyklu akcí na adrese URL zpětného volání, která byla poskytována službě Automation volání v době přijetí hovoru. Příklad úspěšné aktualizace události přehrávání

Příklad, jak můžete deserializovat událost PlayCompleted :

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

Příklad, jak můžete deserializovat událost PlayFailed :

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

Další informace o dalších podporovaných událostech najdete v dokumentu s přehledem služby Call Automation.

Zrušit akci přehrávání

Zrušit všechny operace médií, všechny čekající operace médií jsou zrušeny. Tato akce také zruší další akce přehrávání ve frontě.

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

Příklad, jak můžete deserializovat událost PlayCanceled :

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

Požadavky

• Podrobnosti o účtu Azure s aktivním předplatným najdete v tématu Vytvoření účtu zdarma.
• Prostředek Azure Communication Services Viz Vytvoření prostředku Azure Communication Services. Uložte připojovací řetězec pro tento prostředek.
• Vytvořte novou aplikaci webové služby pomocí sady SDK pro automatizaci volání.
• Máte nainstalované Node.js, můžete ho nainstalovat z oficiálních webových stránek.

Funkce AI

• Vytvořte a připojte služby Azure AI k prostředku Azure Communication Services.
• Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.

Vytvoření nové javascriptové aplikace

Vytvořte novou javascriptovou aplikaci v adresáři projektu. Inicializace nového projektu Node.js pomocí následujícího příkazu Tím se pro váš projekt vytvoří soubor package.json, který slouží ke správě závislostí projektu.

npm init -y

Instalace balíčku Automatizace volání služby Azure Communication Services

npm install @azure/communication-call-automation

V adresáři projektu vytvořte nový soubor JavaScriptu, například ho pojmenujte app.js. Do tohoto souboru napíšete kód JavaScriptu. Spusťte aplikaci pomocí Node.js pomocí následujícího příkazu. Tento kód spustí javascriptový kód, který jste napsali.

node app.js

(Volitelné) Příprava zvukového souboru, pokud chcete k přehrávání výzev použít zvukové soubory

Pokud ho ještě nemáte, vytvořte zvukový soubor, který můžete použít k přehrávání výzev a zpráv účastníkům. Zvukový soubor musí být hostovaný v umístění, které je přístupné službě Azure Communication Services s podporou ověřování. Uchovávejte kopii adresy URL, kterou můžete použít při žádosti o přehrání zvukového souboru. Azure Communication Services podporuje oba typy souborů MP3 se soubory ID3V2TAG a WAV, mono 16bitové PCM s vzorkovací rychlostí 16 KHz.

Vytvoření vlastního zvukového souboru můžete otestovat pomocí našeho nástroje Pro syntézu řeči pomocí nástroje Pro vytváření zvukového obsahu.

(Volitelné) Připojení služby Azure Cognitive Service do služby Azure Communication Service

Pokud chcete používat funkce převodu textu na řeč, je potřeba připojit službu Azure Cognitive Service ke službě Azure Communication Service.

Vytvoření hovoru

V tomto okamžiku byste měli být obeznámeni se spouštěním volání, pokud potřebujete získat další informace o volání, postupujte podle našeho rychlého startu. Můžete také použít fragment kódu, který je zde k dispozici, abyste pochopili, jak odpovědět na volání.

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

Přehrávání zvuku

Jakmile bude hovor vytvořen, existuje několik možností, jak můžete chtít přehrát zvuk. Zvuk můžete přehrát účastníkovi, který se připojil k hovoru, nebo přehrát zvuk všem účastníkům hovoru.

Přehrát zdroj – zvukový soubor

Pokud chcete přehrát zvuk účastníkům pomocí zvukových souborů, musíte se ujistit, že zvukový soubor je soubor WAV, mono a 16 KHz. Pokud chcete přehrávat zvukové soubory, musíte zajistit, abyste službě Azure Communication Services poskytli identifikátor URI souboru, který hostujete v umístění, kde k němu má přístup služba Azure Communication Services. Typ FileSource v naší sadě SDK lze použít k zadání zvukových souborů pro akci přehrávání.

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

Zdroj přehrávání – převod textu na řeč

Pokud chcete přehrávat zvuk pomocí převodu textu na řeč prostřednictvím služeb Azure AI, musíte zadat text, který chcete přehrát, a to buď SourceLocale, nebo VoiceKind nebo VoiceName, který chcete použít. Podporujeme všechna hlasová jména podporovaná službami Azure AI, úplný seznam zde.

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

Zdroj přehrávání – Převod textu na řeč pomocí SSML

Pokud chcete výstup převodu textu na řeč ještě více přizpůsobit pomocí služeb Azure AI, můžete použít SSML pro syntézu řeči při volání akce přehrávání prostřednictvím automatizace volání. Pomocí SSML můžete doladit tón, pozastavit, zlepšit výslovnost, změnit rychlost mluvení, upravit hlasitost a atribut více hlasů.

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

Vlastní hlasové modely

Pokud chcete své výzvy vylepšit a zahrnout vlastní hlasové modely, akce přehrávání převodu textu na řeč teď tyto vlastní hlasy podporuje. Jedná se o skvělou možnost, pokud se snažíte zákazníkům poskytnout více místního, přizpůsobeného prostředí nebo situace, kdy výchozí modely nemusí pokrývat slova a zvýraznění, které se snažíte vyslovovat. Další informace o vytváření a nasazování vlastních modelů najdete v této příručce.

Vlastní názvy hlasu – běžný text – exmaple

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

Příklad vlastních hlasových názvů SSML

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

Jakmile se rozhodnete, který playSource chcete použít k přehrávání zvuku, můžete zvolit, jestli ho chcete přehrát konkrétnímu účastníkovi nebo všem účastníkům.

Přehrávání zvuku – všichni účastníci

V tomto scénáři se zvuk přehraje všem účastníkům hovoru.

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

Přehrávání zvuku – konkrétní účastník

V tomto scénáři se zvuk přehraje konkrétnímu účastníkovi.

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

Přehrávání zvuku ve smyčce

Pomocí možnosti smyčky můžete přehrávat hudbu, která smyčky přehrávají, dokud nebude vaše aplikace připravená přijmout volajícího. Nebo můžete volajícímu postupovat k dalšímu logickému kroku na základě obchodní logiky vašich aplikací.

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

Vylepšení přehrávání pomocí ukládání zvukových souborů do mezipaměti

Pokud vícekrát přehráváte stejný zvukový soubor, může vaše aplikace poskytnout službě Azure Communication Services id zdroje zvukového souboru. Azure Communication Services ukládá tento zvukový soubor do mezipaměti po dobu 1 hodiny.

Poznámka:

Ukládání do mezipaměti zvukové soubory nejsou vhodné pro dynamické výzvy. Pokud změníte adresu URL zadanou službou Azure Communication Services, neaktualizuje adresu URL uloženou v mezipaměti hned. Aktualizace proběhne po vypršení platnosti existující mezipaměti.

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

Zpracování aktualizací událostí akce přehrávání

Aplikace obdrží aktualizace událostí životního cyklu akcí na adrese URL zpětného volání, která byla poskytována službě Automation volání v době přijetí hovoru.

Příklad, jak můžete deserializovat událost PlayCompleted :

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

Příklad, jak můžete deserializovat událost PlayFailed :

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

Další informace o dalších podporovaných událostech najdete v dokumentu s přehledem služby Call Automation.

Zrušit akci přehrávání

Zrušit všechny operace médií, všechny čekající operace médií jsou zrušeny. Tato akce také zruší další akce přehrávání ve frontě.

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

Příklad, jak můžete deserializovat událost PlayCanceled :

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

Požadavky

• Podrobnosti o účtu Azure s aktivním předplatným najdete v tématu Vytvoření účtu zdarma.
• Prostředek Azure Communication Services Viz Vytvoření prostředku Azure Communication Services. Uložte připojovací řetězec pro tento prostředek.
• Vytvořte novou aplikaci webové služby pomocí sady SDK pro automatizaci volání.
• Máte nainstalovaný Python, můžete ho nainstalovat z oficiálního webu.

Funkce AI

• Vytvořte a připojte služby Azure AI k prostředku Azure Communication Services.
• Vytvořte vlastní subdoménu pro prostředek služeb Azure AI.

Vytvoření nové aplikace v Pythonu

Nastavení virtuálního prostředí Pythonu pro váš projekt

python -m venv play-audio-app

Aktivace virtuálního prostředí

Ve Windows použijte následující příkaz:

.\ play-audio-quickstart \Scripts\activate

V systému Unix použijte následující příkaz:

source play-audio-quickstart /bin/activate

Instalace balíčku Automatizace volání služby Azure Communication Services

pip install azure-communication-callautomation

Vytvořte soubor aplikace v adresáři projektu, například ho pojmenujte app.py. Do tohoto souboru napíšete kód Pythonu.

Spusťte aplikaci pomocí Pythonu a následujícím příkazem spusťte kód.

python app.py

(Volitelné) Příprava zvukového souboru, pokud chcete k přehrávání výzev použít zvukové soubory

Pokud ho ještě nemáte, vytvořte zvukový soubor, který můžete použít k přehrávání výzev a zpráv účastníkům. Zvukový soubor musí být hostovaný v umístění, které je přístupné službě Azure Communication Services s podporou ověřování. Uchovávejte kopii adresy URL, kterou můžete použít při žádosti o přehrání zvukového souboru. Azure Communication Services podporuje oba typy souborů MP3 a WAV, mono 16bitové PCM s vzorkovací rychlostí 16 KHz. .

Vytvoření vlastního zvukového souboru můžete otestovat pomocí našeho nástroje Pro syntézu řeči pomocí nástroje Pro vytváření zvukového obsahu.

(Volitelné) Připojení služby Azure Cognitive Service do služby Azure Communication Service

Pokud chcete používat funkce převodu textu na řeč, je potřeba připojit službu Azure Cognitive Service ke službě Azure Communication Service.

Vytvoření hovoru

V tomto okamžiku byste měli být obeznámeni se spouštěním volání, pokud potřebujete získat další informace o volání, postupujte podle našeho rychlého startu. Můžete také použít fragment kódu, který je zde k dispozici, abyste pochopili, jak odpovědět na volání.

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

Přehrávání zvuku

Jakmile bude hovor vytvořen, existuje několik možností, jak můžete chtít přehrát zvuk. Zvuk můžete přehrát účastníkovi, který se připojil k hovoru, nebo přehrát zvuk všem účastníkům hovoru.

Přehrát zdroj – zvukový soubor

Pokud chcete přehrát zvuk účastníkům pomocí zvukových souborů, musíte se ujistit, že zvukový soubor je soubor WAV, mono a 16 KHz. Pokud chcete přehrávat zvukové soubory, musíte zajistit, abyste službě Azure Communication Services poskytli identifikátor URI souboru, který hostujete v umístění, kde k němu má přístup služba Azure Communication Services. Typ FileSource v naší sadě SDK lze použít k zadání zvukových souborů pro akci přehrávání.

play_source = FileSource(url=audioUri)

Zdroj přehrávání – převod textu na řeč

Pokud chcete přehrávat zvuk pomocí převodu textu na řeč prostřednictvím služeb Azure AI, musíte zadat text, který chcete přehrát, a to buď SourceLocale, nebo VoiceKind nebo VoiceName, který chcete použít. Podporujeme všechna hlasová jména podporovaná službami Azure AI, úplný seznam zde.

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
)

Zdroj přehrávání – Převod textu na řeč pomocí SSML

Pokud chcete výstup převodu textu na řeč ještě více přizpůsobit pomocí služeb Azure AI, můžete použít SSML pro syntézu řeči při volání akce přehrávání prostřednictvím automatizace volání. Pomocí SSML můžete doladit tón, pozastavit, zlepšit výslovnost, změnit rychlost mluvení, upravit hlasitost a atribut více hlasů.

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
)

Vlastní hlasové modely

Pokud chcete své výzvy vylepšit a zahrnout vlastní hlasové modely, akce přehrávání převodu textu na řeč teď tyto vlastní hlasy podporuje. Jedná se o skvělou možnost, pokud se snažíte zákazníkům poskytnout více místního, přizpůsobeného prostředí nebo situace, kdy výchozí modely nemusí pokrývat slova a zvýraznění, které se snažíte vyslovovat. Další informace o vytváření a nasazování vlastních modelů najdete v této příručce.

Vlastní názvy hlasu – běžný text – exmaple

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
)

Příklad vlastních hlasových názvů SSML

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

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

play_to = [target_participant]

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

Jakmile se rozhodnete, který playSource chcete použít k přehrávání zvuku, můžete zvolit, jestli ho chcete přehrát konkrétnímu účastníkovi nebo všem účastníkům.

Přehrávání zvuku – všichni účastníci

Přehrajte předem zaznamenaný zvukový soubor všem účastníkům hovoru.

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
)

Přehrávání zvuku – konkrétní účastník

Přehrajte předem zaznamenaný zvukový soubor konkrétnímu účastníkovi hovoru.

play_to = [target_participant]

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

Přehrávání zvuku ve smyčce

Pomocí možnosti smyčky můžete přehrávat hudbu, která smyčky přehrávají, dokud nebude vaše aplikace připravená přijmout volajícího. Nebo můžete volajícímu postupovat k dalšímu logickému kroku na základě obchodní logiky vašich aplikací.

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
)

Vylepšení přehrávání pomocí ukládání zvukových souborů do mezipaměti

Pokud vícekrát přehráváte stejný zvukový soubor, může vaše aplikace poskytnout službě Azure Communication Services id zdroje zvukového souboru. Azure Communication Services ukládá tento zvukový soubor do mezipaměti po dobu 1 hodiny.

Poznámka:

Ukládání do mezipaměti zvukové soubory nejsou vhodné pro dynamické výzvy. Pokud změníte adresu URL zadanou službou Azure Communication Services, neaktualizuje adresu URL uloženou v mezipaměti hned. Aktualizace proběhne po vypršení platnosti existující mezipaměti.

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
)

Zpracování aktualizací událostí akce přehrávání

Aplikace obdrží aktualizace událostí životního cyklu akcí na adrese URL zpětného volání, která byla poskytována službě Automation volání v době přijetí hovoru.

Příklad, jak můžete deserializovat událost PlayCompleted :

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

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

Příklad, jak můžete deserializovat událost PlayFailed :

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

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

Další informace o dalších podporovaných událostech najdete v dokumentu s přehledem služby Call Automation.

Zrušit akci přehrávání

Zrušit všechny operace médií, všechny čekající operace médií jsou zrušeny. Tato akce také zruší další akce přehrávání ve frontě.

call_automation_client.get_call_connection(
    call_connection_id
).cancel_all_media_operations()

Příklad, jak můžete deserializovat událost PlayCanceled :

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

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

Kódy událostí

Stav	Kód	Podkód	Zpráva
PlayCompleted	200	0	Akce byla úspěšně dokončena.
PlayCanceled	400	8508	Akce se nezdařila, operace byla zrušena.
PlayFailed	400	8535	Akce se nezdařila, formát souboru je neplatný.
PlayFailed	400	8536	Akce se nezdařila, soubor nelze stáhnout.
PlayFailed	400	8565	Akce selhala, chybný požadavek na služby Azure AI. Zkontrolujte vstupní parametry.
PlayFailed	401	8565	Akce selhala, chyba ověřování služeb Azure AI
PlayFailed	403	8565	Akce selhala, zakázaná žádost o služby Azure AI, bezplatné předplatné používané žádostí o kvótu vypršelo.
PlayFailed	429	8565	Akce selhala, požadavky překročily počet povolených souběžných požadavků pro předplatné služby Azure AI.
PlayFailed	408	8565	Akce selhala, vypršel časový limit požadavku na služby Azure AI.
PlayFailed	500	9999	Neznámá vnitřní chyba serveru
PlayFailed	500	8572	Akce selhala kvůli vypnutí služby přehrávání.

Známá omezení

• Výzvy k převodu textu na řeč podporují maximálně 400 znaků, pokud je výzva delší, než je tato možnost, doporučujeme použít SSML pro akce přehrávání založené na převodu textu na řeč.
• V situacích, kdy překročíte limit kvóty služby Speech, můžete požádat o zvýšení tohoto počtu lilmit pomocí zde uvedených kroků.

Vyčištění prostředků

Pokud chcete vyčistit a odebrat předplatné služby Communication Services, můžete odstranit prostředek nebo skupinu prostředků. Odstraněním skupiny prostředků se odstraní také všechny ostatní prostředky, které jsou k ní přidružené. Přečtěte si další informace o čištění prostředků.

Další kroky

• Další informace o automatizaci volání
• Další informace o shromažďování uživatelských vstupů ve volání