Alibaba Cloud Model Studio:SDK de HarmonyOS para síntesis de voz Sambert

Esta guía explica cómo utilizar el SDK de HarmonyOS para síntesis de voz Sambert con el fin de convertir texto en voz expresiva y de alta calidad.

Guía del usuario: Para introducciones a los modelos y recomendaciones de selección, consulte Síntesis de voz - Sambert.

Experiencia en línea: No compatible.

Reemplace {WorkspaceId} con su ID de espacio de trabajo real. El dominio existente permanece disponible.

NativeNui

Este SDK se basa en la arquitectura NativeNui y utiliza callbacks para procesar eventos de síntesis de voz.

Características de la arquitectura:

• Modo de instancia: Cree una instancia de síntesis de voz mediante new NativeNui(Constants.ModeType.MODE_TTS).
• Controlado por callbacks: Reciba eventos y datos a través de la interfaz NuiTtsSdkListener.
• Tipos de eventos:
  • NuiSdkTtsEvent: La tarea de síntesis comienza.
  • onTtsDataCallback: Se devuelven datos de audio.
  • NuiSdkTtsEvent: La tarea de síntesis finaliza.
  • NuiSdkTtsEvent: Ocurre un error de síntesis.

Procedimiento

1. tts_initialize - Inicialice el SDK y configure la interfaz de callback y los parámetros de conexión.
2. setParamTts - Configure los parámetros de efecto de síntesis de voz, como el modelo, la voz y el volumen.
3. startTts - Iniciar una tarea de síntesis de voz.
4. onTtsDataCallback - Recibir datos de audio.
5. tts_release - Liberar recursos del SDK.

Métodos de Sambert

tts_initialize

Inicializa una instancia del SDK de síntesis de voz. Cree una instancia mediante new NativeNui(Constants.ModeType.MODE_TTS). Cada instancia corresponde a un canal de síntesis de voz. No inicialice la misma instancia nuevamente antes de llamar a tts_release. Para procesar múltiples tareas simultáneamente, cree múltiples instancias.

Esta interfaz bloquea el hilo de llamada. Llámela desde un hilo que no sea de UI.

Firma del método:

public tts_initialize(callback: NuiTtsSdkListener,
                      ticket: string,
                      level: number,
                      save_log: boolean): number

Descripciones de parámetros:

Parámetro	Tipo	Descripción
callback	NuiTtsSdkListener	Una implementación de la interfaz de devolución de llamada de eventos y datos.
ticket	string	Una cadena JSON que contiene parámetros de autenticación, conexión y depuración. Consulte las descripciones de los parámetros de ticket a continuación.
level	number	Controla el nivel de registro del SDK. Los valores válidos están definidos por la enumeración Constants.LogLevel.
save_log	boolean	Especifica si se guardan registros locales. Si este parámetro es true, utilice debug_path en los parámetros del ticket para especificar una ruta. También puede utilizar max_log_file_size para establecer el tamaño del archivo.

Ejemplo de JSON de ticket:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id",
    "mode_type": "2"
}

Descripciones de parámetros de ticket:

Parámetro	Tipo	Obligatorio	Descripción
url	string	Sí	El punto de conexión. Esto está fijado en wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
apikey	string	Sí	La clave API. Recomendamos utilizar una clave API temporal más segura con un periodo de validez corto para reducir el riesgo de filtrar una clave a largo plazo.
mode_type	string	Sí	El tipo de modo. Debe establecerse en la cadena "2", que indica el modo de síntesis de voz en línea y corresponde a Constants.TtsModeTypeCloud.
device_id	string	Sí	Una cadena única que identifica al usuario final. Puede configurarla como un ID de usuario dentro de la aplicación o un identificador de dispositivo único generado por el cliente. Este ID se utiliza principalmente para el seguimiento de registros y la resolución de problemas.
debug_path	string	No	La ruta de almacenamiento para archivos de registro. Este parámetro solo surte efecto si establece save_log en true al llamar a tts_initialize. En este caso, debe especificar una ruta de archivo de registro. De lo contrario, se producirá un error. Se conservan un máximo de dos archivos de registro localmente.
max_log_file_size	number	No	Establece el tamaño máximo de un archivo de registro en bytes. Este parámetro solo surte efecto si establece save_log en true al llamar a tts_initialize. Valor predeterminado: 104857600 (100 * 1024 * 1024 bytes, o 100 MiB).

setParamTts

Establece los parámetros de efecto de síntesis de voz como pares clave-valor. Llame a este método antes de startTts.

Firma del método:

public setParamTts(param: string, value: string): number

Descripciones de parámetros:

Parámetro	Tipo	Descripción
param	string	El nombre del parámetro.
value	string	El valor del parámetro.

Parámetros disponibles:

Parámetro	Tipo	Obligatorio	Descripción
model	string	Sí	El nombre del modelo, como sambert-zhinan-v1.
format	string	No	El formato de codificación de audio. Valores válidos: - pcm - wav - mp3 (predeterminado).
volume	string	No	El volumen. Valor predeterminado: 50. Rango válido: [0, 100].
sample_rate	string	No	La tasa de muestreo de audio en Hz. Valores válidos: 8000, 16000, 22050, 24000 y 48000. La tasa de muestreo predeterminada para la mayoría de los modelos de voz Sambert es 48000. Configure el reproductor para usar la tasa de muestreo correspondiente.
rate	string	No	La velocidad de voz. Valor predeterminado: 1.0. Rango válido: [0.5, 2.0].
pitch	string	No	El tono. Valor predeterminado: 1.0. Rango válido: [0.5, 2.0].
word_timestamp_enabled	string	No	Especifica si se habilitan las marcas de tiempo a nivel de palabra. Valor predeterminado: false. Este parámetro se aplica a todos los modelos Sambert.
phoneme_timestamp_enabled	string	No	Especifica si se habilitan las marcas de tiempo a nivel de fonema. Valor predeterminado: false. Habilite primero word_timestamp_enabled.
enable_audio_decoder	string	No	Especifica si se habilita el decodificador de audio integrado. Valor predeterminado: 0. Valores válidos: - 1: habilitado. Cuando format es mp3, establezca este parámetro en "1" para habilitar el decodificador integrado del SDK. onTtsDataCallback entonces devuelve datos PCM decodificados. - 0: deshabilitado.
enable_callback_vol	string	No	Especifica si se habilita el callback de volumen. Establézcalo en "1" para habilitar onTtsVolCallback.
apikey	string	No	Actualiza una clave API temporal durante el tiempo de ejecución. Antes de que comience una tarea de síntesis, inyecte la clave temporal más reciente mediante setParamTts('apikey', ...).

getparamTts

Obtiene un valor de parámetro. Este método se utiliza principalmente para la solución de problemas.

Firma del método:

public getparamTts(param: string): string

Descripciones de parámetros:

Parámetro	Tipo	Descripción
param	string	El nombre del parámetro. Actualmente, solo se admite "error_msg".

Valor devuelto:

El valor del parámetro.

startTts

Inicia una tarea de síntesis de voz. El resultado de la síntesis se devuelve mediante callbacks.

Firma del método:

public startTts(priority: string, taskid: string, text: string): number

Descripciones de parámetros:

Parámetro	Tipo	Descripción
priority	string	La prioridad de la tarea. Establezca este parámetro en 1.
taskid	string	El ID de la tarea. Si se pasa una cadena vacía '', el SDK genera automáticamente un ID.
text	string	El texto que se va a sintetizar.

pauseTts

Pausa la tarea de síntesis de voz actual. Después de pausar la tarea, llame a resumeTts para reanudarla o a cancelTts para cancelarla. El SDK no puede iniciar una nueva tarea de síntesis mientras una tarea está pausada.

Nota: Esta operación solo pausa la recuperación de datos del servidor. Los datos de audio ya almacenados en búfer en el reproductor continúan reproduciéndose.

Firma del método:

public pauseTts(): number

resumeTts

Reanuda una tarea de síntesis de voz en pausa.

Firma del método:

public resumeTts(): number

cancelTts

Cancela una tarea de síntesis.

Nota: Esta operación solo cancela la recuperación de datos del servidor. Los datos de audio ya almacenados en búfer en el reproductor continúan reproduciéndose.

Firma del método:

public cancelTts(taskid: string): number

Descripciones de parámetros:

Parámetro	Tipo	Descripción
taskid	string	El ID de la tarea a cancelar. Si se pasa una cadena vacía '', se cancelan todas las tareas de síntesis pausadas o activas.

tts_release

Libera todos los recursos internos del SDK y termina forzosamente todas las tareas de síntesis activas. Después de llamar a este método, la instancia del SDK deja de estar disponible. Para usarla nuevamente, llame a tts_initialize para reinicializarla.

Firma del método:

public tts_release(): number

NuiTtsSdkListener

La interfaz de callback de síntesis de voz Sambert recibe eventos de síntesis y datos de audio. En el SDK de HarmonyOS, los callbacks se definen como funciones de flecha de ArkTS.

onTtsEventCallback

Escucha eventos de inicio, finalización, cancelación, pausa, reanudación y error de la tarea de síntesis de voz.

Firma del método:

onTtsEventCallback: (event: NuiSdkTtsEvent, taskid: string, ret_code: number) => void;

Descripciones de parámetros:

Parámetro	Tipo	Descripción
event	NuiSdkTtsEvent	El evento de devolución de llamada.
taskid	string	El ID de la tarea de síntesis de voz.
ret_code	number	Válido solo cuando ocurre el evento TTS_EVENT_ERROR.

onTtsDataCallback

Durante la síntesis, el SDK activa continuamente este callback. Obtenga los datos de audio del callback.

Firma del método:

onTtsDataCallback: (info: string, info_len: number, buffer: ArrayBuffer | null) => void;

Descripciones de parámetros:

Parámetro	Tipo	Descripción
info	string	Un resultado de marca de tiempo con formato JSON. Este parámetro surte efecto cuando word_timestamp_enabled se establece en "1".
info_len	number	La longitud de datos del campo info. Puede ignorar este parámetro.
buffer	ArrayBuffer | null	Los datos de audio para el segmento actual. Este parámetro puede ser null. Compruebe si es null en el callback.

onTtsVolCallback

Después de habilitar enable_callback_vol, este callback devuelve el volumen de los datos de síntesis recién recibidos por el SDK. Este no es el volumen que se está reproduciendo actualmente.

Firma del método:

onTtsVolCallback: (vol: number) => void;

Descripciones de parámetros:

Parámetro	Tipo	Descripción
vol	number	El volumen de los datos de síntesis.

NuiSdkTtsEvent

La enumeración de tipos de eventos de síntesis de voz de Sambert.

Evento	Descripción
TTS_EVENT_START	La tarea de síntesis comienza. Los datos de audio están a punto de ser devueltos.
TTS_EVENT_END	La tarea de síntesis finaliza correctamente. Todos los datos de audio se han devuelto mediante el callback.
TTS_EVENT_CANCEL	La tarea de síntesis está cancelada.
TTS_EVENT_PAUSE	La tarea de síntesis está en pausa.
TTS_EVENT_RESUME	La tarea de síntesis se reanuda.
TTS_EVENT_ERROR	Se produce un error durante la síntesis. Llame a getparamTts("error_msg") para obtener detalles. { "header": { "task_id": "xxxxxxxxx", "event": "task-failed", "error_code": "InvalidParameter", "error_message": "Please ensure input text is valid.", "attributes": {} }, "payload": {} }

Tipos auxiliares

Constants.LogLevel

Los valores de enumeración para el parámetro level son los siguientes:

Valor	Descripción
LOG_LEVEL_VERBOSE	Los registros más detallados.
LOG_LEVEL_DEBUG	Registros de depuración.
LOG_LEVEL_INFO	Registros informativos (predeterminado).
LOG_LEVEL_WARNING	Registros de advertencia.
LOG_LEVEL_ERROR	Registros de errores.
LOG_LEVEL_NONE	Desactiva el registro.

Código de ejemplo

1. Obtención de una clave de API: Obtención y configuración de una clave de API. Por motivos de seguridad, recomendamos configurar la clave de API como una variable de entorno.

   NotaPara otorgar acceso temporal a aplicaciones o usuarios externos, o para controlar estrictamente operaciones de alto riesgo como acceder o eliminar datos confidenciales, utilice una clave de API temporal. Una clave de API temporal tiene una validez predeterminada de 60 segundos. Obtenga una nueva después de que caduque.

2. Descargue el SDK y ejecute el código de ejemplo:

   • Descargue el paquete más reciente del SDK.
   • Extraiga el paquete TAR. Obtenga el SDK en formato HAR del directorio neonui y agréguelo a las dependencias de su proyecto. Para la integración con C++, obtenga las bibliotecas dinámicas y los archivos de encabezado de native/libs y native/include en el paquete TAR.
   • Abra el proyecto en DevEco Studio. El código de ejemplo se encuentra en DashSambertTtsPage.ets. Reemplace la clave API para probar la función.

Pasos de invocación

1. Inicialice el SDK: Llame a tts_initialize y pase los parámetros de callback NuiTtsSdkListener y ticket.
2. Configure los parámetros según sus requisitos comerciales: Utilice setParamTts para configurar los parámetros de efecto de síntesis de voz, como el modelo, el formato, la tasa de muestreo, la voz y el volumen. Recomendamos configurarlos inmediatamente después de que la inicialización sea exitosa.
3. Llame a startTts para iniciar la síntesis de voz.
4. Obtenga datos de audio del callback onTtsDataCallback. Recomendamos la reproducción en streaming como se describe en Reproducción de audio a continuación. Para guardar el audio localmente, añada los datos de audio al mismo archivo hasta que finalice la síntesis.
5. Después de que finalice la tarea, llame a tts_release para liberar los recursos del SDK.

Reproducción de audio

HarmonyOS utiliza AudioRenderer de @kit.AudioKit para reproducir audio sintetizado. La tasa de muestreo predeterminada del audio sintetizado por Sambert es 48 kHz, así que configure la tasa de muestreo del reproductor en 48000.

El ejemplo del producto encapsula la lógica en la clase de utilidad AudioPlayer.ets. Especifique la tasa de muestreo en el constructor:

// Play Sambert audio at the default sample rate of 48000. The default for AudioPlayer is 16000.
this.mAudioPlayer = new AudioPlayer(this, 48000);

El reproductor utiliza el callback writeData para recuperar datos de audio de una cola y devuelve AudioDataCallbackResult.VALID o AudioDataCallbackResult.INVALID. Cuando onTtsEventCallback recibe TTS_EVENT_END, el SDK ha completado la síntesis y ha devuelto todos los datos a través de los callbacks. Marque la cola de reproducción como completa para que el reproductor se detenga automáticamente después de reproducir los datos restantes.