Comparteix a través de

Personalización de indicaciones de voz para los usuarios con la acción Reproducir

  • Article

Esta guía le ayudará a empezar a reproducir archivos de audio para los participantes mediante la acción de reproducción proporcionada a través del SDK de Automatización de llamadas de Azure Communication Services.

Requisitos previos

Para las características de IA

Creación de una aplicación de C#

En la ventana de consola del sistema operativo, use el comando dotnet para crear una aplicación web.

dotnet new web -n MyApplication

Instalación del paquete NuGet.

El paquete NuGet se puede obtener desde aquí, si aún no lo has hecho.

(Opcional) Prepara el archivo de audio si desea usar archivos de audio para reproducir mensajes

Cree un archivo de audio, si aún no tiene uno, para usarlo para reproducir solicitudes y mensajes a los participantes. El archivo de audio debe hospedarse en una ubicación que sea accesible para Azure Communication Services con compatibilidad para la autenticación. Mantenga una copia de la dirección URL disponible para que la use al solicitar reproducir el archivo de audio. Azure Communication Services admite ambos tipos de archivos de archivos MP3 con archivos ID3V2TAG y WAV, PCM mono de 16 bits a una frecuencia de muestreo de 16 KHz. .

Puede probar la creación de su propio archivo de audio mediante nuestra Síntesis de voz con la herramienta de Creación de contenido de audio.

(Opcional) Conecta Azure Cognitive Service a Azure Communication Service

Si quieres usar funcionalidades de conversión de texto a voz, es necesario que conecte su Azure Cognitive Service a su instancia de Azure Communication Service.

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. También puedes usar el fragmento de código proporcionado aquí para comprender cómo responder a una llamada.

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

Reproducir audio

Una vez establecida la llamada, hay varias opciones para reproducir el audio. Puedes reproducir audio al participante que se ha unido a la llamada o reproducir audio a todos los participantes de la llamada.

Reproducir origen: archivo de audio

Para reproducir audio a los participantes mediante archivos de audio, debes asegurarte de que el archivo de audio es un archivo WAV, mono y 16 KHz. Para reproducir archivos de audio, debes asegurarte de proporcionar Azure Communication Services con un URI a un archivo que hospede en una ubicación donde Azure Communication Services pueda acceder a él. El tipo FileSource de nuestro SDK se puede usar para especificar archivos de audio para la acción de reproducción.

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

Origen de reproducción: texto a voz

Para reproducir audio mediante texto a voz a través de los servicios de Azure AI, debes proporcionar el texto que desea reproducir, así como SourceLocale y VoiceKind o VoiceName que quieres usar. Se admiten todos los nombres de voz admitidos por los servicios de Azure AI, la lista completa aquí.

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

Reproducir origen: texto a voz con SSML

Si quieres personalizar la salida de texto a voz aún más con los servicios de Azure AI, puede usar lenguaje de marcado de síntesis de voz SSML al invocar la acción de reproducción a través de La automatización de llamadas. Mediante SSML, puedes ajustar con precisión el tono, agregar pausas, mejorar la pronunciación, cambiar la velocidad del habla, ajustar el volumen y atribuir varias voces a un solo documento.

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

Modelos de voz personalizados

Si quieres mejorar más sus mensajes e incluir modelos de voz personalizados, la acción reproducir texto a voz ahora admite estas voces personalizadas. Esta es una excelente opción si estás intentando ofrecer a los clientes una experiencia más local, personalizada o tener situaciones en las que los modelos predeterminados pueden no cubrir las palabras y acentos que intentas pronunciar. Para obtener más información sobre cómo crear e implementar modelos, puedes leer esta guía.

Ejemplo de texto normal de nombres de voz personalizados

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

Ejemplo de SSML de nombres de voz personalizados


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

Una vez que hayas decidido qué playSource quieres usar para reproducir audio, puedes elegir si quieres reproducirlo a un participante específico o a todos los participantes.

Reproducir audio a todos los participantes

En este escenario, el audio se reproduce a todos los participantes de la llamada.

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

Reproducir audio a un participante específico

En este escenario, el audio se reproduce a un participante específico.

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

Reproducir audio en bucle

Puede usar la opción de bucle para reproducir música mientras se espera que se repite hasta que la aplicación esté lista para aceptar el autor de la llamada. O bien, haga avanzar el autor de la llamada al siguiente paso en función de la lógica de negocios de las aplicaciones.

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

Mejora de la reproducción con el almacenamiento en caché de archivos de audio

Si reproduce el mismo archivo de audio varias veces, la aplicación puede proporcionar a Azure Communication Services el sourceID para el archivo de audio. Azure Communication Services almacena en caché este archivo de audio durante 1 hora.

Nota:

El almacenamiento en caché de archivos de audio no es adecuado para avisos dinámicos. Si cambias la dirección URL proporcionada a Azure Communication Services, no se actualiza la dirección URL almacenada en caché inmediatamente. La actualización se producirá después de que expire la caché existente.

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

Control de las actualizaciones de eventos de acción de reproducción

La aplicación recibe actualizaciones de eventos de ciclo de vida de acción en la URL de devolución de llamada que se proporcionó al servicio de automatización de llamadas en el momento de responder a la llamada. Se muestra un ejemplo de una actualización correcta de eventos de reproducción.

Ejemplo de cómo se puede deserializar el evento PlayCompleted:

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

Ejemplo de cómo se puede deserializar el evento 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); 
    } 
}

Para obtener más información sobre otros eventos admitidos, visite el documento de información general de automatización de llamadas.

Cancelar acción de reproducción

Cancelar todas las operaciones de elementos multimedia, se cancelan todas las operaciones multimedia pendientes. Esta acción también cancela otras acciones de reproducción en cola.

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

Ejemplo de cómo se puede deserializar el evento PlayCanceled:

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

Requisitos previos

Para las características de IA

Creación de una aplicación Java

En la ventana de terminal o de comandos, navegue hasta el directorio en el que quiere crear la aplicación de Java. Ejecuta el comando que se muestra aquí para generar el proyecto de Java a partir de la plantilla maven-archetype-quickstart.

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

El comando anterior crea un directorio con el mismo nombre que el argumento artifactId. En este directorio, el directorio src/main/java contiene el código fuente del proyecto, el directorio src/test/java contiene el origen de prueba.

Verás que el paso ‘generar’ creó un directorio con el mismo nombre que el objeto artifactId. En este directorio, el directorio src/main/java contiene el código fuente, el directorio src/test/java contiene pruebas, y el archivo pom.xml es el modelo de objetos del proyecto o POM.

Actualice el archivo POM de la aplicación para usar Java 8 o posterior.

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

Incorporación de referencias de paquete

En el archivo POM, agregue la siguiente referencia para el proyecto.

azure-communication-callautomation

El paquete del SDK de automatización de llamadas de Azure Communication Services se recupera de la fuente de desarrollo del SDK de Azure.

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

(Opcional) Prepara el archivo de audio si desea usar archivos de audio para reproducir mensajes

Cree un archivo de audio, si aún no tiene uno, para usarlo para reproducir solicitudes y mensajes a los participantes. El archivo de audio debe hospedarse en una ubicación que sea accesible para Azure Communication Services con compatibilidad para la autenticación. Mantenga una copia de la dirección URL disponible para que la use al solicitar reproducir el archivo de audio. Azure Communication Services admite ambos tipos de archivos de archivos MP3 con archivos ID3V2TAG y WAV, PCM mono de 16 bits a una frecuencia de muestreo de 16 KHz. .

Puede probar la creación de su propio archivo de audio mediante nuestra Síntesis de voz con la herramienta de Creación de contenido de audio.

(Opcional) Conecta Azure Cognitive Service a Azure Communication Service

Si quieres usar funcionalidades de conversión de texto a voz, es necesario que conecte su Azure Cognitive Service a su instancia de Azure Communication Service.

Actualización de App.java con código

En el editor que prefiera, abra el archivo App.java y actualícelo con el código proporcionado en la sección Actualizar app.java con código.

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. También puedes usar el fragmento de código proporcionado aquí para comprender cómo responder a una llamada.

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

Reproducir audio

Una vez establecida la llamada, hay varias opciones para reproducir el audio. Puedes reproducir audio al participante que se ha unido a la llamada o reproducir audio a todos los participantes de la llamada.

Reproducir origen: archivo de audio

Para reproducir audio a los participantes mediante archivos de audio, debes asegurarte de que el archivo de audio es un archivo WAV, mono y 16 KHz. Para reproducir archivos de audio, debes asegurarte de proporcionar Azure Communication Services con un URI a un archivo que hospede en una ubicación donde Azure Communication Services pueda acceder a él. El tipo FileSource de nuestro SDK se puede usar para especificar archivos de audio para la acción de reproducción.

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

Origen de reproducción: texto a voz

Para reproducir audio mediante texto a voz a través de los servicios de Azure AI, debes proporcionar el texto que desea reproducir, así como SourceLocale y VoiceKind o VoiceName que quieres usar. Se admiten todos los nombres de voz admitidos por los servicios de Azure AI, la lista completa aquí.

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

Origen de reproducción: SSML de texto a voz

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

Modelos de voz personalizados

Si quieres mejorar más sus mensajes e incluir modelos de voz personalizados, la acción reproducir texto a voz ahora admite estas voces personalizadas. Esta es una excelente opción si estás intentando ofrecer a los clientes una experiencia más local, personalizada o tener situaciones en las que los modelos predeterminados pueden no cubrir las palabras y acentos que intentas pronunciar. Para obtener más información sobre cómo crear e implementar modelos, puedes leer esta guía.

Ejemplo de texto normal de nombres de voz personalizados

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

Ejemplo de SSML de nombres de voz personalizados

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

Una vez que hayas decidido qué playSource quieres usar para reproducir audio, puedes elegir si quieres reproducirlo a un participante específico o a todos los participantes.

Reproducir audio a todos los participantes

En este escenario, el audio se reproduce a todos los participantes de la llamada.

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

Reproducir audio a un participante específico

En este escenario, el audio se reproduce a un participante específico.

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

Reproducir audio en bucle

Puede usar la opción de bucle para reproducir música mientras se espera que se repite hasta que la aplicación esté lista para aceptar el autor de la llamada. O bien, haga avanzar el autor de la llamada al siguiente paso en función de la lógica de negocios de las aplicaciones.

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

Mejora de la reproducción con el almacenamiento en caché de archivos de audio

Si reproduce el mismo archivo de audio varias veces, la aplicación puede proporcionar a Azure Communication Services el sourceID para el archivo de audio. Azure Communication Services almacena en caché este archivo de audio durante 1 hora.

Nota:

El almacenamiento en caché de archivos de audio no es adecuado para avisos dinámicos. Si cambias la dirección URL proporcionada a Azure Communication Services, no se actualiza la dirección URL almacenada en caché inmediatamente. La actualización se producirá después de que expire la caché existente.

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

Control de las actualizaciones de eventos de acción de reproducción

La aplicación recibe actualizaciones de eventos de ciclo de vida de acción en la URL de devolución de llamada que se proporcionó al servicio de automatización de llamadas en el momento de responder a la llamada. Se muestra un ejemplo de una actualización correcta de eventos de reproducción.

Ejemplo de cómo se puede deserializar el evento PlayCompleted:

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

Ejemplo de cómo se puede deserializar el evento 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()); 
    } 
}

Para obtener más información sobre otros eventos admitidos, visite el documento de información general de automatización de llamadas.

Cancelar acción de reproducción

Cancelar todas las operaciones de elementos multimedia, se cancelan todas las operaciones multimedia pendientes. Esta acción también cancela otras acciones de reproducción en cola.

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

Ejemplo de cómo se puede deserializar el evento PlayCanceled:

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

Requisitos previos

Para las características de IA

Creación de una aplicación de JavaScript

Crea una nueva aplicación de JavaScript en el directorio del proyecto. Inicia un nuevo proyecto de Node.js con el siguiente comando. Esto crea un archivo package.json para el proyecto, que se usa para administrar las dependencias del proyecto.

npm init -y

Instalación del paquete de Automatización de llamadas de Azure Communication Services

npm install @azure/communication-call-automation

Crea un nuevo archivo JavaScript en el directorio del proyecto, por ejemplo, asígnale el nombre app.js. Escribe el código JavaScript en este archivo. Ejecuta la aplicación mediante Node.js con el comando siguiente. Este código ejecuta el código JavaScript que has escrito.

node app.js

(Opcional) Prepara el archivo de audio si desea usar archivos de audio para reproducir mensajes

Cree un archivo de audio, si aún no tiene uno, para usarlo para reproducir solicitudes y mensajes a los participantes. El archivo de audio debe hospedarse en una ubicación que sea accesible para Azure Communication Services con compatibilidad para la autenticación. Mantenga una copia de la dirección URL disponible para que la use al solicitar reproducir el archivo de audio. Azure Communication Services admite ambos tipos de archivos de archivos MP3 con archivos ID3V2TAG y WAV, PCM mono de 16 bits a una frecuencia de muestreo de 16 KHz.

Puede probar la creación de su propio archivo de audio mediante nuestra Síntesis de voz con la herramienta de Creación de contenido de audio.

(Opcional) Conecta Azure Cognitive Service a Azure Communication Service

Si desea usar funcionalidades de conversión de texto a voz, es necesario que conecte su Azure Cognitive Service a su instancia de Azure Communication Service.

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. También puedes usar el fragmento de código proporcionado aquí para comprender cómo responder a una llamada.

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

Reproducir audio

Una vez establecida la llamada, hay varias opciones para reproducir el audio. Puedes reproducir audio al participante que se ha unido a la llamada o reproducir audio a todos los participantes de la llamada.

Reproducir origen: archivo de audio

Para reproducir audio a los participantes mediante archivos de audio, debes asegurarte de que el archivo de audio es un archivo WAV, mono y 16 KHz. Para reproducir archivos de audio, debes asegurarte de proporcionar Azure Communication Services con un URI a un archivo que hospede en una ubicación donde Azure Communication Services pueda acceder a él. El tipo FileSource de nuestro SDK se puede usar para especificar archivos de audio para la acción de reproducción.

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

Origen de reproducción: texto a voz

Para reproducir audio mediante texto a voz a través de los servicios de Azure AI, debes proporcionar el texto que desea reproducir, así como SourceLocale y VoiceKind o VoiceName que quieres usar. Se admiten todos los nombres de voz admitidos por los servicios de Azure AI, la lista completa aquí.

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

Reproducir origen: texto a voz con SSML

Si quieres personalizar la salida de texto a voz aún más con los servicios de Azure AI, puede usar lenguaje de marcado de síntesis de voz SSML al invocar la acción de reproducción a través de La automatización de llamadas. Mediante SSML, puedes ajustar con precisión el tono, agregar pausas, mejorar la pronunciación, cambiar la velocidad del habla, ajustar el volumen y atribuir varias voces a un solo documento.

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

Modelos de voz personalizados

Si quieres mejorar más sus mensajes e incluir modelos de voz personalizados, la acción reproducir texto a voz ahora admite estas voces personalizadas. Esta es una excelente opción si estás intentando ofrecer a los clientes una experiencia más local, personalizada o tener situaciones en las que los modelos predeterminados pueden no cubrir las palabras y acentos que intentas pronunciar. Para obtener más información sobre cómo crear e implementar modelos, puedes leer esta guía.

Ejemplo de texto normal de nombres de voz personalizados

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

Ejemplo de SSML de nombres de voz personalizados

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

Una vez que hayas decidido qué playSource quieres usar para reproducir audio, puedes elegir si quieres reproducirlo a un participante específico o a todos los participantes.

Reproducir audio: todos los participantes

En este escenario, el audio se reproduce a todos los participantes de la llamada.

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

Reproducir audio: participante específico

En este escenario, el audio se reproduce a un participante específico.

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

Reproducir audio en bucle

Puede usar la opción de bucle para reproducir música mientras se espera que se repite hasta que la aplicación esté lista para aceptar el autor de la llamada. O bien, haga avanzar el autor de la llamada al siguiente paso en función de la lógica de negocios de las aplicaciones.

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

Mejora de la reproducción con el almacenamiento en caché de archivos de audio

Si reproduce el mismo archivo de audio varias veces, la aplicación puede proporcionar a Azure Communication Services el sourceID para el archivo de audio. Azure Communication Services almacena en caché este archivo de audio durante 1 hora.

Nota:

El almacenamiento en caché de archivos de audio no es adecuado para avisos dinámicos. Si cambias la dirección URL proporcionada a Azure Communication Services, no se actualiza la dirección URL almacenada en caché inmediatamente. La actualización se producirá después de que expire la caché existente.

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

Control de las actualizaciones de eventos de acción de reproducción

La aplicación recibe actualizaciones de eventos de ciclo de vida de acción en la URL de devolución de llamada que se proporcionó al servicio de automatización de llamadas en el momento de responder a la llamada.

Ejemplo de cómo se puede deserializar el evento PlayCompleted:

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

Ejemplo de cómo se puede deserializar el evento PlayFailed:

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

Para obtener más información sobre otros eventos admitidos, visite el documento de información general de automatización de llamadas.

Cancelar acción de reproducción

Cancelar todas las operaciones de elementos multimedia, se cancelan todas las operaciones multimedia pendientes. Esta acción también cancela otras acciones de reproducción en cola.

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

Ejemplo de cómo se puede deserializar el evento PlayCanceled:

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

Requisitos previos

Para las características de IA

Creación de una nueva aplicación de Python

Configuración de un entorno virtual de Python para el proyecto

python -m venv play-audio-app

Activación del entorno virtual

En Windows, use el siguiente comando:

.\ play-audio-quickstart \Scripts\activate

En Unix, use el comando siguiente:

source play-audio-quickstart /bin/activate

Instalación del paquete de Automatización de llamadas de Azure Communication Services

pip install azure-communication-callautomation

Cree el archivo de aplicación en el directorio del proyecto, por ejemplo, asígnale el nombre app.py. Escriba el código de Python en este archivo.

Ejecute la aplicación mediante Python con el comando siguiente.

python app.py

(Opcional) Prepara el archivo de audio si desea usar archivos de audio para reproducir mensajes

Cree un archivo de audio, si aún no tiene uno, para usarlo para reproducir solicitudes y mensajes a los participantes. El archivo de audio debe hospedarse en una ubicación que sea accesible para Azure Communication Services con compatibilidad para la autenticación. Mantenga una copia de la dirección URL disponible para que la use al solicitar reproducir el archivo de audio. Azure Communication Services admite ambos tipos de archivos de MP3 y WAV, PCM mono de 16 bits a una frecuencia de muestreo de 16 KHz. .

Puede probar la creación de su propio archivo de audio mediante nuestra Síntesis de voz con la herramienta de Creación de contenido de audio.

(Opcional) Conecta Azure Cognitive Service a Azure Communication Service

Si quieres usar funcionalidades de conversión de texto a voz, es necesario que conecte su Azure Cognitive Service a su instancia de Azure Communication Service.

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. También puedes usar el fragmento de código proporcionado aquí para comprender cómo responder a una llamada.

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

Reproducir audio

Una vez establecida la llamada, hay varias opciones para reproducir el audio. Puedes reproducir audio al participante que se ha unido a la llamada o reproducir audio a todos los participantes de la llamada.

Reproducir origen: archivo de audio

Para reproducir audio a los participantes mediante archivos de audio, debes asegurarte de que el archivo de audio es un archivo WAV, mono y 16 KHz. Para reproducir archivos de audio, debes asegurarte de proporcionar Azure Communication Services con un URI a un archivo que hospede en una ubicación donde Azure Communication Services pueda acceder a él. El tipo FileSource de nuestro SDK se puede usar para especificar archivos de audio para la acción de reproducción.

play_source = FileSource(url=audioUri)

Origen de reproducción: texto a voz

Para reproducir audio mediante texto a voz a través de los servicios de Azure AI, debes proporcionar el texto que desea reproducir, así como SourceLocale y VoiceKind o VoiceName que quieres usar. Se admiten todos los nombres de voz admitidos por los servicios de Azure AI, la lista completa aquí.

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
)

Reproducir origen: texto a voz con SSML

Si quieres personalizar la salida de texto a voz aún más con los servicios de Azure AI, puede usar lenguaje de marcado de síntesis de voz SSML al invocar la acción de reproducción a través de La automatización de llamadas. Mediante SSML, puedes ajustar con precisión el tono, agregar pausas, mejorar la pronunciación, cambiar la velocidad del habla, ajustar el volumen y atribuir varias voces a un solo documento.

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
)

Modelos de voz personalizados

Si quieres mejorar más sus mensajes e incluir modelos de voz personalizados, la acción reproducir texto a voz ahora admite estas voces personalizadas. Esta es una excelente opción si estás intentando ofrecer a los clientes una experiencia más local, personalizada o tener situaciones en las que los modelos predeterminados pueden no cubrir las palabras y acentos que intentas pronunciar. Para obtener más información sobre cómo crear e implementar modelos, puedes leer esta guía.

Ejemplo de texto normal de nombres de voz personalizados

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
)

Ejemplo de SSML de nombres de voz personalizados

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
)

Una vez que hayas decidido qué playSource quieres usar para reproducir audio, puedes elegir si quieres reproducirlo a un participante específico o a todos los participantes.

Reproducir audio: todos los participantes

Reproducir un archivo de audio pregrabado para todos los participantes de la llamada.

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
)

Reproducir audio: participante específico

Reproducir un archivo de audio pregrabado a un participante específico de la llamada.

play_to = [target_participant]

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

Reproducir audio en bucle

Puede usar la opción de bucle para reproducir música mientras se espera que se repite hasta que la aplicación esté lista para aceptar el autor de la llamada. O bien, haga avanzar el autor de la llamada al siguiente paso en función de la lógica de negocios de las aplicaciones.

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
)

Mejora de la reproducción con el almacenamiento en caché de archivos de audio

Si reproduce el mismo archivo de audio varias veces, la aplicación puede proporcionar a Azure Communication Services el sourceID para el archivo de audio. Azure Communication Services almacena en caché este archivo de audio durante 1 hora.

Nota:

El almacenamiento en caché de archivos de audio no es adecuado para avisos dinámicos. Si cambias la dirección URL proporcionada a Azure Communication Services, no se actualiza la dirección URL almacenada en caché inmediatamente. La actualización se producirá después de que expire la caché existente.

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
)

Control de las actualizaciones de eventos de acción de reproducción

La aplicación recibe actualizaciones de eventos de ciclo de vida de acción en la URL de devolución de llamada que se proporcionó al servicio de automatización de llamadas en el momento de responder a la llamada.

Ejemplo de cómo se puede deserializar el evento PlayCompleted:

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

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

Ejemplo de cómo se puede deserializar el evento PlayFailed:

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

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

Para obtener más información sobre otros eventos admitidos, visite el documento de información general de automatización de llamadas.

Cancelar acción de reproducción

Cancelar todas las operaciones de elementos multimedia, se cancelan todas las operaciones multimedia pendientes. Esta acción también cancela otras acciones de reproducción en cola.

call_automation_client.get_call_connection(
    call_connection_id
).cancel_all_media_operations()

Ejemplo de cómo se puede deserializar el evento PlayCanceled:

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

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

Códigos de evento

Estado Código SubCode Mensaje
PlayCompleted 200 0 La acción se ha completado correctamente.
PlayCanceled 400 8508 Error de acción, se canceló la operación.
PlayFailed 400 8535 Ha habido un error, el formato de archivo no es válido.
PlayFailed 400 8536 Ha habido un error, no se pudo descargar el archivo solicitado.
PlayFailed 400 8565 Ha habido un error, solicitud incorrecta a los servicios de Azure AI. Compruebe los parámetros de entrada.
PlayFailed 401 8565 Ha habido un error, error de autenticación de los servicios de Azure AI.
PlayFailed 403 8565 Ha habido un error, solicitud prohibida a los servicios de Azure AI, la suscripción gratuita usada por la solicitud ha agotado la cuota.
PlayFailed 429 8565 Ha habido un error, las solicitudes superaron el número de solicitudes simultáneas permitidas para la suscripción de servicios de Azure AI.
PlayFailed 408 8565 Ha habido un error, se agota el tiempo de espera de la solicitud a los servicios de Azure AI.
PlayFailed 500 9999 Error interno desconocido del servidor
PlayFailed 500 8572 Ha habido un error debido al apagado del servicio de reproducción.

Limitaciones conocidas

  • Los mensajes de texto a voz admiten un máximo de 400 caracteres, si el mensaje es mayor se recomienda usar SSML para acciones de reproducción basadas en la conversión de texto a voz.
  • En escenarios en los que se supera el límite de cuota del servicio de voz, puedes solicitar aumentar este limite siguiendo los pasos descritos aquí.

Limpieza de recursos

Si quiere limpiar y quitar una suscripción a Communication Services, puede eliminar el recurso o grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él. Obtenga más información sobre la limpieza de recursos.

Pasos siguientes