Udostępnij za pośrednictwem

Dostosowywanie monitów głosowych do użytkowników za pomocą akcji Odtwórz

  • Artykuł

Ten przewodnik pomoże Ci rozpocząć odtwarzanie plików audio uczestnikom za pomocą akcji odtwarzania udostępnionej za pomocą zestawu SDK usługi Azure Communication Services Call Automation.

Wymagania wstępne

W przypadku funkcji sztucznej inteligencji

  • Tworzenie i łączenie usług Azure AI z zasobem usług Azure Communication Services.
  • Utwórz niestandardową poddomenę dla zasobu usług Azure AI.

Tworzenie nowej aplikacji w języku C#

W oknie konsoli systemu operacyjnego użyj dotnet polecenia , aby utworzyć nową aplikację internetową.

dotnet new web -n MyApplication

Instalowanie pakietu NuGet

Pakiet NuGet można uzyskać z tego miejsca, jeśli jeszcze tego nie zrobiono.

(Opcjonalnie) Przygotuj plik audio, jeśli chcesz użyć plików audio do odtwarzania monitów

Utwórz plik audio, jeśli jeszcze go nie masz, aby użyć do odtwarzania monitów i komunikatów dla uczestników. Plik audio musi być hostowany w lokalizacji dostępnej dla usług Azure Communication Services z obsługą uwierzytelniania. Zachowaj kopię adresu URL, która będzie dostępna podczas żądania odtwarzania pliku audio. Usługi Azure Communication Services obsługują oba typy plików MP3 z plikami ID3V2TAG i WAV, mono 16-bitowym pcm z częstotliwością próbkowania 16 KHz. .

Możesz przetestować tworzenie własnego pliku audio przy użyciu naszego narzędzia do syntezy mowy za pomocą narzędzia do tworzenia zawartości audio.

(Opcjonalnie) Łączenie usługi Azure Cognitive Service z usługą Azure Communication Service

Jeśli chcesz używać funkcji zamiany tekstu na mowę, musisz połączyć usługę Azure Cognitive Service z usługą Azure Communication Service.

Ustanawianie połączenia

W tym momencie należy zapoznać się z rozpoczynaniem wywołań, jeśli musisz dowiedzieć się więcej na temat nawiązywania połączenia, postępuj zgodnie z naszym przewodnikiem Szybki start. Możesz również użyć fragmentu kodu podanego tutaj, aby dowiedzieć się, jak odpowiedzieć na połączenie.

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

Odtwarzanie dźwięku

Po nawiązaniu połączenia istnieje wiele opcji odtwarzania dźwięku. Możesz odtworzyć dźwięk uczestnikowi, który dołączył do połączenia lub odtworzyć dźwięk do wszystkich uczestników połączenia.

Odtwórz źródło — plik audio

Aby odtwarzać dźwięk dla uczestników przy użyciu plików audio, należy upewnić się, że plik dźwiękowy jest plikiem WAV, mono i 16 KHz. Aby odtwarzać pliki audio, musisz upewnić się, że udostępniasz usługom Azure Communication Services identyfikator URI do pliku, który hostujesz w lokalizacji, w której usługi Azure Communication Services mogą uzyskiwać do niego dostęp. Typ FileSource w naszym zestawie SDK może służyć do określania plików audio dla akcji odtwarzania.

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

//Multiple FileSource Prompts, if you want to play multiple audio files in one request you can provide them in a list.
//var playSources = new List<PlaySource>() { new FileSource(new Uri("https://www2.cs.uic.edu/~i101/SoundFiles/StarWars3.wav")), new FileSource(new Uri("https://www2.cs.uic.edu/~i101/SoundFiles/preamble10.wav")) };

Źródło odtwarzania — zamiana tekstu na mowę

Aby odtwarzać dźwięk przy użyciu funkcji zamiany tekstu na mowę za pośrednictwem usług Azure AI, musisz podać tekst, który chcesz odtworzyć, a także element SourceLocale i VoiceKind lub VoiceName, którego chcesz użyć. Obsługujemy wszystkie nazwy głosowe obsługiwane przez usługi Azure AI, pełną listę tutaj.

String textToPlay = "Welcome to Contoso";

// Provide SourceLocale and VoiceKind to select an appropriate voice. 
var playSource = new TextSource(textToPlay, "en-US", VoiceKind.Female);

//Multiple TextSource prompt, if you want to play multiple text prompts in one request you can provide them in a list.
//var playSources = new List<PlaySource>() { new TextSource("recognize prompt one") { VoiceName = SpeechToTextVoice }, new TextSource("recognize prompt two") { VoiceName = SpeechToTextVoice }, new TextSource(content) { VoiceName = SpeechToTextVoice } };

String textToPlay = "Welcome to Contoso"; 
 
// Provide VoiceName to select a specific voice. 
var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural");

//Multiple TextSource prompt, if you want to play multiple text prompts in one request you can provide them in a list.
//var playSources = new List<PlaySource>() { new TextSource("recognize prompt one") { VoiceName = SpeechToTextVoice }, new TextSource("recognize prompt two") { VoiceName = SpeechToTextVoice }, new TextSource(content) { VoiceName = SpeechToTextVoice } };

Źródło odtwarzania — zamiana tekstu na mowę za pomocą języka SSML

Jeśli chcesz jeszcze bardziej dostosować dane wyjściowe zamiany tekstu na mowę za pomocą usług Azure AI, możesz użyć języka SSML syntezy mowy podczas wywoływania akcji odtwarzania za pomocą usługi Call Automation. Za pomocą języka SSML można precyzyjnie dostosować boisko, wstrzymać, poprawić wymowę, zmienić szybkość mówienia, dostosować głośność i atrybut wiele głosów.

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

Niestandardowe modele głosu

Jeśli chcesz ulepszyć więcej monitów i uwzględnić niestandardowe modele głosu, akcja odtwarzania Zamiana tekstu na mowę obsługuje teraz te niestandardowe głosy. Jest to świetna opcja, jeśli próbujesz dać klientom bardziej lokalne, spersonalizowane środowisko lub sytuacje, w których domyślne modele mogą nie obejmować słów i akcentów, które próbujesz wymawiać. Aby dowiedzieć się więcej na temat tworzenia i wdrażania modeli niestandardowych, możesz przeczytać ten przewodnik.

Niestandardowe nazwy głosu zwykłego tekstu exmaple

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

Przykład niestandardowych nazw głosów SSML


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

Po podjęciu decyzji o tym, którego elementu playSource chcesz użyć do odtwarzania dźwięku, możesz wybrać, czy chcesz odtworzyć go dla określonego uczestnika, czy wszystkich uczestników.

Odtwarzanie dźwięku dla wszystkich uczestników

W tym scenariuszu dźwięk jest odtwarzany dla wszystkich uczestników połączenia.

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

Obsługa barge-in

Podczas scenariuszy, w których odtwarzasz dźwięk w pętli dla wszystkich uczestników, np. oczekujących lobby może odtwarzać dźwięk do uczestników w holu i aktualizować ich numer w kolejce. W przypadku korzystania z obsługi barge-in spowoduje to anulowanie trwającego dźwięku i odtworzenie nowej wiadomości. Następnie, jeśli chcesz kontynuować odtwarzanie oryginalnego dźwięku, utwórz kolejne żądanie odtwarzania.

var GoodbyePlaySource = new TextSource("Good bye")
{
    VoiceName = "en-US-NancyNeural"
};

PlayToAllOptions playOptions = new PlayToAllOptions(GoodbyePlaySource)
{
    InterruptCallMediaOperation = false,
    OperationCallbackUri = new Uri(callbackUriHost),
    Loop = true
};

await callConnectionMedia.PlayToAllAsync(playOptions);

// Interrupt media with text source

// Option1:
var interrupt = new TextSource("Interrupt prompt message")
{
    VoiceName = "en-US-NancyNeural"
};

PlayToAllOptions playInterrupt = new PlayToAllOptions(interrupt)
{
    InterruptCallMediaOperation = true,
    OperationCallbackUri = new Uri(callbackUriHost),
    Loop = false
};

await callConnectionMedia.PlayToAllAsync(playInterrupt);

/*
Option2: Interrupt media with file source
var interruptFile = new FileSource(new Uri(<AUDIO URL>));
PlayToAllOptions playFileInterrupt = new PlayToAllOptions(interruptFile)
{
    InterruptCallMediaOperation = true,
    OperationCallbackUri = new Uri(callbackUriHost),
    Loop = false
};
await callConnectionMedia.PlayToAllAsync(playFileInterrupt);
*/

Odtwarzanie dźwięku dla określonego uczestnika

W tym scenariuszu dźwięk jest odtwarzany dla określonego uczestnika.

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

Odtwórz wiele monitów dźwiękowych

Wszystkie akcje odtwarzania obsługują możliwość wysyłania wielu źródeł odtwarzania za pomocą tylko jednego żądania. Oznacza to, że wysyłasz listę monitów, aby grać w jednym miejscu zamiast indywidualnie wysyłać te żądania.

Odtwarzanie dźwięku w pętli

Możesz użyć opcji pętli, aby odtwarzać muzykę, która zapętla się, aż aplikacja będzie gotowa do zaakceptowania wywołującego. Możesz też przejść do następnego kroku logicznego w oparciu o logikę biznesową aplikacji.

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

Ulepszanie odtwarzania za pomocą buforowania plików audio

Jeśli odtwarzasz ten sam plik audio wielokrotnie, aplikacja może udostępnić usługom Azure Communication Services identyfikator sourceID pliku audio. Usługi Azure Communication Services buforuje ten plik audio przez 1 godzinę.

Uwaga

Buforowanie plików audio nie jest odpowiednie dla monitów dynamicznych. Jeśli zmienisz adres URL podany w usługach Azure Communication Services, nie zaktualizuje on od razu buforowanego adresu URL. Aktualizacja zostanie wykonana po wygaśnięciu istniejącej pamięci podręcznej.

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

Obsługa aktualizacji zdarzeń akcji odtwarzania

Aplikacja otrzymuje aktualizacje zdarzeń cyklu życia akcji w adresie URL wywołania zwrotnego dostarczonego do usługi Call Automation w momencie odbierania połączenia. Przykład pomyślnej aktualizacji zdarzenia odtwarzania.

Przykładowy sposób deserializacji zdarzenia PlayCompleted :

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

Przykładowy sposób deserializacji zdarzenia PlayStarted :

if (acsEvent is PlayStarted playStarted) 
{ 
    logger.LogInformation("Play started successfully, context={context}", playStarted.OperationContext); 
}

Przykładowy sposób deserializacji zdarzenia 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); 
    } 
}

Aby dowiedzieć się więcej o innych obsługiwanych zdarzeniach, odwiedź dokument Omówienie usługi Call Automation.

Anuluj akcję odtwarzania

Anuluj wszystkie operacje multimediów, wszystkie oczekujące operacje multimediów zostaną anulowane. Ta akcja powoduje również anulowanie innych akcji odtwarzania w kolejce.

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

Przykład sposobu deserializacji zdarzenia PlayCanceled :

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

Wymagania wstępne

W przypadku funkcji sztucznej inteligencji

  • Tworzenie i łączenie usług Azure AI z zasobem usług Azure Communication Services.
  • Utwórz niestandardową poddomenę dla zasobu usług Azure AI.

Tworzenie nowej aplikacji Java

W terminalu lub oknie polecenia przejdź do katalogu, w którym chcesz utworzyć aplikację Java. Uruchom pokazane tutaj polecenie, aby wygenerować projekt Java z szablonu maven-archetype-quickstart.

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

Poprzednie polecenie tworzy katalog o takiej samej nazwie jak artifactId argument. W tym katalogu src/main/java katalog zawiera kod źródłowy projektu, src/test/java katalog zawiera źródło testowe.

Zauważysz, że krok "generuj" utworzył katalog o takiej samej nazwie jak artifactId. W tym katalogu src/main/java katalog zawiera kod źródłowy, src/test/java katalog zawiera testy, a pom.xml plik jest projektem Project Object Model lub POM.

Zaktualizuj plik POM aplikacji, aby używać środowiska Java 8 lub nowszego.

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

Dodawanie odwołań do pakietu

W pliku POM dodaj następujące odwołanie do projektu.

azure-communication-callautomation

Pakiet zestawu SDK usługi Azure Communication Services Call Automation jest pobierany z źródła danych deweloperskich zestawu Azure SDK.

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

(Opcjonalnie) Przygotuj plik audio, jeśli chcesz użyć plików audio do odtwarzania monitów

Utwórz plik audio, jeśli jeszcze go nie masz, aby użyć do odtwarzania monitów i komunikatów dla uczestników. Plik audio musi być hostowany w lokalizacji dostępnej dla usług Azure Communication Services z obsługą uwierzytelniania. Zachowaj kopię adresu URL, która będzie dostępna podczas żądania odtwarzania pliku audio. Usługi Azure Communication Services obsługują oba typy plików MP3 z plikami ID3V2TAG i WAV, mono 16-bitowym pcm z częstotliwością próbkowania 16 KHz. .

Możesz przetestować tworzenie własnego pliku audio przy użyciu naszego narzędzia do syntezy mowy za pomocą narzędzia do tworzenia zawartości audio.

(Opcjonalnie) Łączenie usługi Azure Cognitive Service z usługą Azure Communication Service

Jeśli chcesz używać funkcji zamiany tekstu na mowę, musisz połączyć usługę Azure Cognitive Service z usługą Azure Communication Service.

Aktualizowanie App.java przy użyciu kodu

W wybranym edytorze otwórz plik App.java i zaktualizuj go przy użyciu kodu podanego w sekcji Update app.java za pomocą kodu .

Ustanawianie połączenia

W tym momencie należy zapoznać się z rozpoczynaniem wywołań, jeśli musisz dowiedzieć się więcej na temat nawiązywania połączenia, postępuj zgodnie z naszym przewodnikiem Szybki start. Możesz również użyć fragmentu kodu podanego tutaj, aby dowiedzieć się, jak odpowiedzieć na połączenie.

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

Odtwarzanie dźwięku

Po nawiązaniu połączenia istnieje wiele opcji odtwarzania dźwięku. Możesz odtworzyć dźwięk uczestnikowi, który dołączył do połączenia lub odtworzyć dźwięk do wszystkich uczestników połączenia.

Odtwórz źródło — plik audio

Aby odtwarzać dźwięk dla uczestników przy użyciu plików audio, należy upewnić się, że plik dźwiękowy jest plikiem WAV, mono i 16 KHz. Aby odtwarzać pliki audio, musisz upewnić się, że udostępniasz usługom Azure Communication Services identyfikator URI do pliku, który hostujesz w lokalizacji, w której usługi Azure Communication Services mogą uzyskiwać do niego dostęp. Typ FileSource w naszym zestawie SDK może służyć do określania plików audio dla akcji odtwarzania.

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

/* Multiple FileSource Prompts
var p1 = new FileSource().setUrl("https://www2.cs.uic.edu/~i101/SoundFiles/StarWars3.wav");
var p2 = new FileSource().setUrl("https://www2.cs.uic.edu/~i101/SoundFiles/preamble10.wav");

var playSources = new ArrayList();
playSources.add(p1);
playSources.add(p2);
*/

Źródło odtwarzania — zamiana tekstu na mowę

Aby odtwarzać dźwięk przy użyciu funkcji zamiany tekstu na mowę za pośrednictwem usług Azure AI, musisz podać tekst, który chcesz odtworzyć, a także element SourceLocale i VoiceKind lub VoiceName, którego chcesz użyć. Obsługujemy wszystkie nazwy głosowe obsługiwane przez usługi Azure AI, pełną listę tutaj.

// Provide SourceLocale and VoiceKind to select an appropriate voice.
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setSourceLocale("en-US") 
    .setVoiceKind(VoiceKind.FEMALE);

/* Multiple Prompt list setup: Multiple TextSource prompt

var p1 = new TextSource().setText("recognize prompt one").setSourceLocale("en-US").setVoiceKind(VoiceKind.FEMALE);
var p2 = new TextSource().setText("recognize prompt two").setSourceLocale("en-US").setVoiceKind(VoiceKind.FEMALE);
var p3 = new TextSource().setText(content).setSourceLocale("en-US").setVoiceKind(VoiceKind.FEMALE);

var playSources = new ArrayList();
playSources.add(p1);
playSources.add(p2);
playSources.add(p3);
*/

// Provide VoiceName to select a specific voice.
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setVoiceName("en-US-ElizabethNeural");

/* Multiple Prompt list setup: Multiple TextSource prompt

var p1 = new TextSource().setText("recognize prompt one").setVoiceName("en-US-NancyNeural");
var p2 = new TextSource().setText("recognize prompt two").setVoiceName("en-US-NancyNeural");
var p3 = new TextSource().setText(content).setVoiceName("en-US-NancyNeural");

var playSources = new ArrayList();
playSources.add(p1);
playSources.add(p2);
playSources.add(p3);
*/

Źródło odtwarzania — SSML zamiany tekstu na mowę

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

Niestandardowe modele głosu

Jeśli chcesz ulepszyć więcej monitów i uwzględnić niestandardowe modele głosu, akcja odtwarzania Zamiana tekstu na mowę obsługuje teraz te niestandardowe głosy. Jest to świetna opcja, jeśli próbujesz dać klientom bardziej lokalne, spersonalizowane środowisko lub sytuacje, w których domyślne modele mogą nie obejmować słów i akcentów, które próbujesz wymawiać. Aby dowiedzieć się więcej na temat tworzenia i wdrażania modeli niestandardowych, możesz przeczytać ten przewodnik.

Niestandardowe nazwy głosu zwykłego tekstu exmaple

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

Przykład niestandardowych nazw głosów 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");

Po podjęciu decyzji o tym, którego elementu playSource chcesz użyć do odtwarzania dźwięku, możesz wybrać, czy chcesz odtworzyć go dla określonego uczestnika, czy wszystkich uczestników.

Odtwarzanie dźwięku dla wszystkich uczestników

W tym scenariuszu dźwięk jest odtwarzany dla wszystkich uczestników połączenia.

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

Obsługa barge-in

Podczas scenariuszy, w których odtwarzasz dźwięk w pętli dla wszystkich uczestników, np. oczekujących lobby może odtwarzać dźwięk do uczestników w holu i aktualizować ich numer w kolejce. W przypadku korzystania z obsługi barge-in spowoduje to anulowanie trwającego dźwięku i odtworzenie nowej wiadomości. Następnie, jeśli chcesz kontynuować odtwarzanie oryginalnego dźwięku, utwórz kolejne żądanie odtwarzania.

// Option1: Interrupt media with text source
var textPlay = new TextSource()
    .setText("First Interrupt prompt message")
    .setVoiceName("en-US-NancyNeural");

var playToAllOptions = new PlayToAllOptions(textPlay)
    .setLoop(false)
    .setOperationCallbackUrl(appConfig.getBasecallbackuri())
    .setInterruptCallMediaOperation(false);

client.getCallConnection(callConnectionId)
    .getCallMedia()
    .playToAllWithResponse(playToAllOptions, Context.NONE);

/*
Option2: Interrupt media with text source
client.getCallConnection(callConnectionId)
    .getCallMedia()
    .playToAll(textPlay);
*/

/*
Option1: Barge-in with file source
var interruptFile = new FileSource()
    .setUrl("https://www2.cs.uic.edu/~i101/SoundFiles/StarWars3.wav");

var playFileOptions = new PlayToAllOptions(interruptFile)
    .setLoop(false)
    .setOperationCallbackUrl(appConfig.getBasecallbackuri())
    .setInterruptCallMediaOperation(true);

client.getCallConnection(callConnectionId)
    .getCallMedia()
    .playToAllWithResponse(playFileOptions, Context.NONE);

Option2: Barge-in with file source
client.getCallConnection(callConnectionId)
    .getCallMedia()
    .playToAll(interruptFile);
*/

Odtwarzanie dźwięku dla określonego uczestnika

W tym scenariuszu dźwięk jest odtwarzany dla określonego uczestnika.

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

Odtwarzanie dźwięku w pętli

Możesz użyć opcji pętli, aby odtwarzać muzykę, która zapętla się, aż aplikacja będzie gotowa do zaakceptowania wywołującego. Możesz też przejść do następnego kroku logicznego w oparciu o logikę biznesową aplikacji.

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

Ulepszanie odtwarzania za pomocą buforowania plików audio

Jeśli odtwarzasz ten sam plik audio wielokrotnie, aplikacja może udostępnić usługom Azure Communication Services identyfikator sourceID pliku audio. Usługi Azure Communication Services buforuje ten plik audio przez 1 godzinę.

Uwaga

Buforowanie plików audio nie jest odpowiednie dla monitów dynamicznych. Jeśli zmienisz adres URL podany w usługach Azure Communication Services, nie zaktualizuje on od razu buforowanego adresu URL. Aktualizacja zostanie wykonana po wygaśnięciu istniejącej pamięci podręcznej.

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

Obsługa aktualizacji zdarzeń akcji odtwarzania

Aplikacja otrzymuje aktualizacje zdarzeń cyklu życia akcji w adresie URL wywołania zwrotnego dostarczonego do usługi Call Automation w momencie odbierania połączenia. Przykład pomyślnej aktualizacji zdarzenia odtwarzania.

Przykładowy sposób deserializacji zdarzenia PlayCompleted :

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

Przykładowy sposób deserializacji zdarzenia PlayStarted :

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

Przykładowy sposób deserializacji zdarzenia 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()); 
    } 
}

Aby dowiedzieć się więcej o innych obsługiwanych zdarzeniach, odwiedź dokument Omówienie usługi Call Automation.

Anuluj akcję odtwarzania

Anuluj wszystkie operacje multimediów, wszystkie oczekujące operacje multimediów zostaną anulowane. Ta akcja powoduje również anulowanie innych akcji odtwarzania w kolejce.

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

Przykład sposobu deserializacji zdarzenia PlayCanceled :

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

Wymagania wstępne

W przypadku funkcji sztucznej inteligencji

  • Tworzenie i łączenie usług Azure AI z zasobem usług Azure Communication Services.
  • Utwórz niestandardową poddomenę dla zasobu usług Azure AI.

Tworzenie nowej aplikacji JavaScript

Utwórz nową aplikację JavaScript w katalogu projektu. Zainicjuj nowy projekt Node.js za pomocą następującego polecenia. Spowoduje to utworzenie pliku package.json dla projektu, który służy do zarządzania zależnościami projektu.

npm init -y

Instalowanie pakietu automatyzacji wywołań usług Azure Communication Services

npm install @azure/communication-call-automation

Utwórz nowy plik JavaScript w katalogu projektu, na przykład nadaj mu nazwę app.js. W tym pliku napiszesz kod JavaScript. Uruchom aplikację przy użyciu Node.js za pomocą następującego polecenia. Ten kod wykonuje napisany kod JavaScript.

node app.js

(Opcjonalnie) Przygotuj plik audio, jeśli chcesz użyć plików audio do odtwarzania monitów

Utwórz plik audio, jeśli jeszcze go nie masz, aby użyć do odtwarzania monitów i komunikatów dla uczestników. Plik audio musi być hostowany w lokalizacji dostępnej dla usług Azure Communication Services z obsługą uwierzytelniania. Zachowaj kopię adresu URL, która będzie dostępna podczas żądania odtwarzania pliku audio. Usługi Azure Communication Services obsługują oba typy plików MP3 z plikami ID3V2TAG i WAV, mono 16-bitowym pcm z częstotliwością próbkowania 16 KHz.

Możesz przetestować tworzenie własnego pliku audio przy użyciu naszego narzędzia do syntezy mowy za pomocą narzędzia do tworzenia zawartości audio.

(Opcjonalnie) Łączenie usługi Azure Cognitive Service z usługą Azure Communication Service

Jeśli chcesz używać funkcji zamiany tekstu na mowę, musisz połączyć usługę Azure Cognitive Service z usługą Azure Communication Service.

Ustanawianie połączenia

W tym momencie należy zapoznać się z rozpoczynaniem wywołań, jeśli musisz dowiedzieć się więcej na temat nawiązywania połączenia, postępuj zgodnie z naszym przewodnikiem Szybki start. Możesz również użyć fragmentu kodu podanego tutaj, aby dowiedzieć się, jak odpowiedzieć na połączenie.

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

Odtwarzanie dźwięku

Po nawiązaniu połączenia istnieje wiele opcji odtwarzania dźwięku. Możesz odtworzyć dźwięk uczestnikowi, który dołączył do połączenia lub odtworzyć dźwięk do wszystkich uczestników połączenia.

Odtwórz źródło — plik audio

Aby odtwarzać dźwięk dla uczestników przy użyciu plików audio, należy upewnić się, że plik dźwiękowy jest plikiem WAV, mono i 16 KHz. Aby odtwarzać pliki audio, musisz upewnić się, że udostępniasz usługom Azure Communication Services identyfikator URI do pliku, który hostujesz w lokalizacji, w której usługi Azure Communication Services mogą uzyskiwać do niego dostęp. Typ FileSource w naszym zestawie SDK może służyć do określania plików audio dla akcji odtwarzania.

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

Źródło odtwarzania — zamiana tekstu na mowę

Aby odtwarzać dźwięk przy użyciu funkcji zamiany tekstu na mowę za pośrednictwem usług Azure AI, musisz podać tekst, który chcesz odtworzyć, a także element SourceLocale i VoiceKind lub VoiceName, którego chcesz użyć. Obsługujemy wszystkie nazwy głosowe obsługiwane przez usługi Azure AI, pełną listę tutaj.

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

Źródło odtwarzania — zamiana tekstu na mowę za pomocą języka SSML

Jeśli chcesz jeszcze bardziej dostosować dane wyjściowe zamiany tekstu na mowę za pomocą usług Azure AI, możesz użyć języka SSML syntezy mowy podczas wywoływania akcji odtwarzania za pomocą usługi Call Automation. Za pomocą języka SSML można precyzyjnie dostosować boisko, wstrzymać, poprawić wymowę, zmienić szybkość mówienia, dostosować głośność i atrybut wiele głosów.

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

Niestandardowe modele głosu

Jeśli chcesz ulepszyć więcej monitów i uwzględnić niestandardowe modele głosu, akcja odtwarzania Zamiana tekstu na mowę obsługuje teraz te niestandardowe głosy. Jest to świetna opcja, jeśli próbujesz dać klientom bardziej lokalne, spersonalizowane środowisko lub sytuacje, w których domyślne modele mogą nie obejmować słów i akcentów, które próbujesz wymawiać. Aby dowiedzieć się więcej na temat tworzenia i wdrażania modeli niestandardowych, możesz przeczytać ten przewodnik.

Niestandardowe nazwy głosu zwykłego tekstu exmaple

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

Przykład niestandardowych nazw głosów 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"};

Po podjęciu decyzji o tym, którego elementu playSource chcesz użyć do odtwarzania dźwięku, możesz wybrać, czy chcesz odtworzyć go dla określonego uczestnika, czy wszystkich uczestników.

Odtwarzanie dźwięku — wszyscy uczestnicy

W tym scenariuszu dźwięk jest odtwarzany dla wszystkich uczestników połączenia.

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

Obsługa barge-in

Podczas scenariuszy, w których odtwarzasz dźwięk w pętli dla wszystkich uczestników, np. oczekujących lobby może odtwarzać dźwięk do uczestników w holu i aktualizować ich numer w kolejce. W przypadku korzystania z obsługi barge-in spowoduje to anulowanie trwającego dźwięku i odtworzenie nowej wiadomości. Następnie, jeśli chcesz kontynuować odtwarzanie oryginalnego dźwięku, utwórz kolejne żądanie odtwarzania.

// Interrupt media with text source 
//Option1:

const playSource: TextSource = { text: "Interrupt prompt", voiceName: "en-US-NancyNeural", kind: "textSource" };

const interruptOption: PlayToAllOptions = { 
loop: false, 
interruptCallMediaOperation: true, 
operationContext: "interruptOperationContext", 
operationCallbackUrl: process.env.CALLBACK_URI + "/api/callbacks" 
}; 

await callConnectionMedia.playToAll([playSource], interruptOption); 

/*
// Interrupt media with file source 

Option2: 

const playSource: FileSource = { 
url: MEDIA_URI + "MainMenu.wav", 
kind: "fileSource" 
}; 

const interruptOption: PlayToAllOptions = { 
loop: false, 
interruptCallMediaOperation: true, 
operationContext: "interruptOperationContext", 
operationCallbackUrl: process.env.CALLBACK_URI + "/api/callbacks" 
}; 

await callConnectionMedia.playToAll([playSource], interruptOption); 
*/

Odtwarzanie dźwięku — konkretny uczestnik

W tym scenariuszu dźwięk jest odtwarzany dla określonego uczestnika.

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

Odtwarzanie dźwięku w pętli

Możesz użyć opcji pętli, aby odtwarzać muzykę, która zapętla się, aż aplikacja będzie gotowa do zaakceptowania wywołującego. Możesz też przejść do następnego kroku logicznego w oparciu o logikę biznesową aplikacji.

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

Ulepszanie odtwarzania za pomocą buforowania plików audio

Jeśli odtwarzasz ten sam plik audio wielokrotnie, aplikacja może udostępnić usługom Azure Communication Services identyfikator sourceID pliku audio. Usługi Azure Communication Services buforuje ten plik audio przez 1 godzinę.

Uwaga

Buforowanie plików audio nie jest odpowiednie dla monitów dynamicznych. Jeśli zmienisz adres URL podany w usługach Azure Communication Services, nie zaktualizuje on od razu buforowanego adresu URL. Aktualizacja zostanie wykonana po wygaśnięciu istniejącej pamięci podręcznej.

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

Obsługa aktualizacji zdarzeń akcji odtwarzania

Aplikacja otrzymuje aktualizacje zdarzeń cyklu życia akcji w adresie URL wywołania zwrotnego dostarczonego do usługi Call Automation w momencie odbierania połączenia.

Przykładowy sposób deserializacji zdarzenia PlayCompleted :

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

Przykładowy sposób deserializacji zdarzenia PlayFailed :

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

Przykładowy sposób deserializacji zdarzenia PlayStarted :

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

Aby dowiedzieć się więcej o innych obsługiwanych zdarzeniach, odwiedź dokument Omówienie usługi Call Automation.

Anuluj akcję odtwarzania

Anuluj wszystkie operacje multimediów, wszystkie oczekujące operacje multimediów zostaną anulowane. Ta akcja powoduje również anulowanie innych akcji odtwarzania w kolejce.

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

Przykład sposobu deserializacji zdarzenia PlayCanceled :

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

Wymagania wstępne

W przypadku funkcji sztucznej inteligencji

  • Tworzenie i łączenie usług Azure AI z zasobem usług Azure Communication Services.
  • Utwórz niestandardową poddomenę dla zasobu usług Azure AI.

Tworzenie nowej aplikacji w języku Python

Konfigurowanie środowiska wirtualnego języka Python dla projektu

python -m venv play-audio-app

Uaktywnienie środowiska wirtualnego

W systemie Windows użyj następującego polecenia:

.\ play-audio-quickstart \Scripts\activate

W systemie Unix użyj następującego polecenia:

source play-audio-quickstart /bin/activate

Instalowanie pakietu automatyzacji wywołań usług Azure Communication Services

pip install azure-communication-callautomation

Utwórz plik aplikacji w katalogu projektu, na przykład nadaj mu nazwę app.py. Napiszesz kod w języku Python w tym pliku.

Uruchom aplikację przy użyciu języka Python za pomocą następującego polecenia, aby wykonać kod.

python app.py

(Opcjonalnie) Przygotuj plik audio, jeśli chcesz użyć plików audio do odtwarzania monitów

Utwórz plik audio, jeśli jeszcze go nie masz, aby użyć do odtwarzania monitów i komunikatów dla uczestników. Plik audio musi być hostowany w lokalizacji dostępnej dla usług Azure Communication Services z obsługą uwierzytelniania. Zachowaj kopię adresu URL, która będzie dostępna podczas żądania odtwarzania pliku audio. Usługi Azure Communication Services obsługują oba typy plików MP3 i WAV, mono 16-bitowe PCM z częstotliwością próbkowania 16 KHz. .

Możesz przetestować tworzenie własnego pliku audio przy użyciu naszego narzędzia do syntezy mowy za pomocą narzędzia do tworzenia zawartości audio.

(Opcjonalnie) Łączenie usługi Azure Cognitive Service z usługą Azure Communication Service

Jeśli chcesz używać funkcji zamiany tekstu na mowę, musisz połączyć usługę Azure Cognitive Service z usługą Azure Communication Service.

Ustanawianie połączenia

W tym momencie należy zapoznać się z rozpoczynaniem wywołań, jeśli musisz dowiedzieć się więcej na temat nawiązywania połączenia, postępuj zgodnie z naszym przewodnikiem Szybki start. Możesz również użyć fragmentu kodu podanego tutaj, aby dowiedzieć się, jak odpowiedzieć na połączenie.

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

Odtwarzanie dźwięku

Po nawiązaniu połączenia istnieje wiele opcji odtwarzania dźwięku. Możesz odtworzyć dźwięk uczestnikowi, który dołączył do połączenia lub odtworzyć dźwięk do wszystkich uczestników połączenia.

Odtwórz źródło — plik audio

Aby odtwarzać dźwięk dla uczestników przy użyciu plików audio, należy upewnić się, że plik dźwiękowy jest plikiem WAV, mono i 16 KHz. Aby odtwarzać pliki audio, musisz upewnić się, że udostępniasz usługom Azure Communication Services identyfikator URI do pliku, który hostujesz w lokalizacji, w której usługi Azure Communication Services mogą uzyskiwać do niego dostęp. Typ FileSource w naszym zestawie SDK może służyć do określania plików audio dla akcji odtwarzania.

play_source = FileSource(url=audioUri)

#Play multiple audio files
#file_source1 = FileSource(MAIN_MENU_PROMPT_URI) 
#file_source2 = FileSource(MAIN_MENU_PROMPT_URI) 
#
# play_sources = [file_source1, file_source2]
# 
# call_connection_client.play_media_to_all(
#     play_source=play_sources,
#     interrupt_call_media_operation=False,
#     operation_context="multiplePlayContext",
#     operation_callback_url=CALLBACK_EVENTS_URI,
#     loop=False
# )

Źródło odtwarzania — zamiana tekstu na mowę

Aby odtwarzać dźwięk przy użyciu funkcji zamiany tekstu na mowę za pośrednictwem usług Azure AI, musisz podać tekst, który chcesz odtworzyć, a także element SourceLocale i VoiceKind lub VoiceName, którego chcesz użyć. Obsługujemy wszystkie nazwy głosowe obsługiwane przez usługi Azure AI, pełną listę tutaj.

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
)

#Multiple text prompts
#play_source1 = TextSource(text="Hi, This is multiple play source one call media test.", source_locale="en-US", voice_kind=VoiceKind.FEMALE) 
#play_source2 = TextSource(text="Hi, This is multiple play source two call media test.", source_locale="en-US", voice_kind=VoiceKind.FEMALE)
#
#play_sources = [play_source1, play_source2]
#
#call_connection_client.play_media_to_all(
#    play_source=play_sources,
#    interrupt_call_media_operation=False,
#    operation_context="multiplePlayContext",
#    operation_callback_url=CALLBACK_EVENTS_URI,
#    loop=False
#)

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
)

#Play multiple text prompts
#play_source1 = TextSource(text="Hi, This is multiple play source one call media test.", voice_name=SPEECH_TO_TEXT_VOICE) 
#play_source2 = TextSource(text="Hi, This is multiple play source two call media test.", voice_name=SPEECH_TO_TEXT_VOICE)
#
#play_sources = [play_source1, play_source2]
#
#call_connection_client.play_media_to_all(
#    play_source=play_sources,
#    interrupt_call_media_operation=False,
#    operation_context="multiplePlayContext",
#    operation_callback_url=CALLBACK_EVENTS_URI,
#    loop=False
#)

Źródło odtwarzania — zamiana tekstu na mowę za pomocą języka SSML

Jeśli chcesz jeszcze bardziej dostosować dane wyjściowe zamiany tekstu na mowę za pomocą usług Azure AI, możesz użyć języka SSML syntezy mowy podczas wywoływania akcji odtwarzania za pomocą usługi Call Automation. Za pomocą języka SSML można precyzyjnie dostosować boisko, wstrzymać, poprawić wymowę, zmienić szybkość mówienia, dostosować głośność i atrybut wiele głosów.

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
)

Niestandardowe modele głosu

Jeśli chcesz ulepszyć więcej monitów i uwzględnić niestandardowe modele głosu, akcja odtwarzania Zamiana tekstu na mowę obsługuje teraz te niestandardowe głosy. Jest to świetna opcja, jeśli próbujesz dać klientom bardziej lokalne, spersonalizowane środowisko lub sytuacje, w których domyślne modele mogą nie obejmować słów i akcentów, które próbujesz wymawiać. Aby dowiedzieć się więcej na temat tworzenia i wdrażania modeli niestandardowych, możesz przeczytać ten przewodnik.

Niestandardowe nazwy głosu zwykłego tekstu 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
)

Przykład niestandardowych nazw głosów 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
)

Po podjęciu decyzji o tym, którego elementu playSource chcesz użyć do odtwarzania dźwięku, możesz wybrać, czy chcesz odtworzyć go dla określonego uczestnika, czy wszystkich uczestników.

Odtwarzanie dźwięku — wszyscy uczestnicy

Odtwórz wstępnie rozpoznany plik dźwiękowy dla wszystkich uczestników wywołania.

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
)

Obsługa barge-in

Podczas scenariuszy, w których odtwarzasz dźwięk w pętli dla wszystkich uczestników, np. oczekujących lobby może odtwarzać dźwięk do uczestników w holu i aktualizować ich numer w kolejce. W przypadku korzystania z obsługi barge-in spowoduje to anulowanie trwającego dźwięku i odtworzenie nowej wiadomości. Następnie, jeśli chcesz kontynuować odtwarzanie oryginalnego dźwięku, utwórz kolejne żądanie odtwarzania.

# Interrupt media with text source
# Option 1
play_source = TextSource(text="This is interrupt call media test.", voice_name=SPEECH_TO_TEXT_VOICE)
call_connection_client.play_media_to_all(
    play_source, 
    interrupt_call_media_operation=True, 
    operation_context="interruptContext", 
    operation_callback_url=CALLBACK_EVENTS_URI, 
    loop=False
)

# Interrupt media with file source
# Option 2
#play_source = FileSource(MAIN_MENU_PROMPT_URI)
#call_connection_client.play_media_to_all(
#    play_source, 
#    interrupt_call_media_operation=True, 
#    operation_context="interruptContext", 
#    operation_callback_url=CALLBACK_EVENTS_URI, 
#    loop=False
#)

Odtwarzanie dźwięku — konkretny uczestnik

Odtwórz wstępnie rozpoznany plik dźwiękowy określonemu uczestnikowi połączenia.

play_to = [target_participant]

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

Odtwarzanie dźwięku w pętli

Możesz użyć opcji pętli, aby odtwarzać muzykę, która zapętla się, aż aplikacja będzie gotowa do zaakceptowania wywołującego. Możesz też przejść do następnego kroku logicznego w oparciu o logikę biznesową aplikacji.

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
)

Ulepszanie odtwarzania za pomocą buforowania plików audio

Jeśli odtwarzasz ten sam plik audio wielokrotnie, aplikacja może udostępnić usługom Azure Communication Services identyfikator sourceID pliku audio. Usługi Azure Communication Services buforuje ten plik audio przez 1 godzinę.

Uwaga

Buforowanie plików audio nie jest odpowiednie dla monitów dynamicznych. Jeśli zmienisz adres URL podany w usługach Azure Communication Services, nie zaktualizuje on od razu buforowanego adresu URL. Aktualizacja zostanie wykonana po wygaśnięciu istniejącej pamięci podręcznej.

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
)

Obsługa aktualizacji zdarzeń akcji odtwarzania

Aplikacja otrzymuje aktualizacje zdarzeń cyklu życia akcji w adresie URL wywołania zwrotnego dostarczonego do usługi Call Automation w momencie odbierania połączenia.

Przykładowy sposób deserializacji zdarzenia PlayCompleted :

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

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

Przykładowy sposób deserializacji zdarzenia PlayStarted :

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

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

Przykładowy sposób deserializacji zdarzenia PlayFailed :

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

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

Aby dowiedzieć się więcej o innych obsługiwanych zdarzeniach, odwiedź dokument Omówienie usługi Call Automation.

Anuluj akcję odtwarzania

Anuluj wszystkie operacje multimediów, wszystkie oczekujące operacje multimediów zostaną anulowane. Ta akcja powoduje również anulowanie innych akcji odtwarzania w kolejce.

call_automation_client.get_call_connection(
    call_connection_id
).cancel_all_media_operations()

Przykład sposobu deserializacji zdarzenia PlayCanceled :

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

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

Kody zdarzeń

Stan Kod Subcode Komunikat
PlayCompleted 200 0 Akcja została ukończona pomyślnie.
PlayCanceled 400 8508 Akcja nie powiodła się. Operacja została anulowana.
PlayFailed 400 8535 Akcja nie powiodła się. Format pliku jest nieprawidłowy.
PlayFailed 400 8536 Akcja nie powiodła się. Nie można pobrać pliku.
PlayFailed 400 8565 Akcja nie powiodła się, nieprawidłowe żądanie do usług sztucznej inteligencji platformy Azure. Sprawdź parametry wejściowe.
PlayFailed 401 8565 Akcja nie powiodła się, błąd uwierzytelniania usług AI platformy Azure.
PlayFailed 403 8565 Akcja nie powiodła się, żądanie zabronione do usług azure AI, bezpłatna subskrypcja używana przez żądanie nie przekroczyła limitu przydziału.
PlayFailed 429 8565 Akcja nie powiodła się. Żądania przekroczyły liczbę dozwolonych żądań współbieżnych dla subskrypcji usług Azure AI.
PlayFailed 408 8565 Akcja nie powiodła się. Upłynął limit czasu żądania do usług sztucznej inteligencji platformy Azure.
PlayFailed 500 9999 Nieznany wewnętrzny błąd serwera
PlayFailed 500 8572 Akcja nie powiodła się z powodu zamknięcia usługi odtwarzania.

Znane ograniczenia

  • Monity tekstowe zamiany tekstu na mowę obsługują maksymalnie 400 znaków, jeśli monit jest dłuższy niż sugerujemy użycie języka SSML dla akcji odtwarzania opartych na zamianie tekstu na mowę.
  • W przypadku scenariuszy, w których przekroczono limit przydziału usługi Mowa, możesz poprosić o zwiększenie tego lilmit, wykonując kroki opisane tutaj.

Czyszczenie zasobów

Jeśli chcesz wyczyścić i usunąć subskrypcję usług Komunikacyjnych, możesz usunąć zasób lub grupę zasobów. Usunięcie grupy zasobów powoduje również usunięcie wszelkich innych skojarzonych z nią zasobów. Dowiedz się więcej o czyszczeniu zasobów.

Następne kroki