Verbio Software Reference

Transcripción

1 Verbio Software Reference Referencia de las funciones del Dialogic SDK Verbio Technologies, S.L.

2 Verbio Software Reference: Referencia de las funciones del Dialogic SDK Verbio Technologies, S.L. publicado Septiembre de 2011 Copyright 2011 Verbio Technologies, S.L.

3

4

5 Tabla de contenidos 1. Introducción Descripción de las funciones vx_activatevcb vx_applydictionary vx_asr_init vx_asv_addfile vx_asv_spkinfo vx_asv_init vx_asv_train vx_asv_verify ATVX_BUILTIN vx_chkwrd vx_clrrsp vx_clrvad vx_deactivatevcb vx_devclose vx_dtmf_close vx_dtmf_open vx_dtmf_word vx_dtmf_write ATVX_ERRMSGP vx_getasrlic vx_getdllversion vx_getparm vx_getttslic vx_getusedasrlic vx_getusedttslic ATVX_IVCB ATVX_LASTERR vx_libclose vx_libinit vx_loadcd vx_loadvcb vx_nbest ATVX_NIND vx_playstr vx_playstr_close vx_playstr_open vx_playstr_read vx_playstr_release vx_playstr_wait vx_prevcb vx_prevcbdev vx_prevcbex vx_prevcbex vx_reccfg_release vx_reccfg_wait vx_recind vx_recstr vx_recstr_open vx_recstr_release vx_recstr_wait vx_recstr_write vx_registervvicallback vx_regsrvclose vx_sapiclose vx_sapiopen vx_sapiopenex...86

6 Verbio Software Reference 57. vx_sapiselect vx_setabbreviations vx_setcd vx_setdictionary vx_setparm vx_setvcb vx_srvclose vx_termplaystr vx_termrecstr vx_thclose vx_tts_init vx_ttssetabbreviations vx_ttssetdictionary vx_unloadvcb vx_vsd_close vx_vsd_open vx_vsd_write vx_word vx_wordex vx_wordrule Estructuras de datos y parámetros VX_RSP - Recognize String Parameter VAD_PRM - Voice Activity Detection Parameters MODEATTRIBUTES - SAPI Speaker Id Definición de parámetros para vx_getparm() y vx_setparm() Obtención de información adicional mediante vx_word o vx_wordex Código de ejemplos en C/C Ejemplo Síncrono Ejemplo Asíncrono Ejemplo con Barge-in Ejemplo de Detección de voz y de tonos DTMF A. Ficheros utilizados por los ejemplos Índice vi Referencia de las funciones del Dialogic SDK Verbio Technologies

7 Lista de tablas 3.1. Parámetros globales en el SDK de Dialogic Parámetros de canal en el SDK de Dialogic Elementos de un vocabulario o gramática ABNF

8

9 Lista de ejemplos 3.1. Información devuelta por el servidor de reconocimiento Ejemplo síncrono de Verbio Dialogic Ejemplo asíncrono de Verbio Dialogic Ejemplo con barge-in de Verbio Dialogic Ejemplo de Detección de voz y de tonos DTMF

10

11 Capítulo 1. Introducción El objectivo de este documento es describir el conjunto de funciones que constituyen el Dialogic SDK proporcionado en Verbio. Este SDK está diseñado pensando en aquellos integradores que trabajan en entornos de programación C/C++ sobre tarjetas Dialogic. Es compatible con las versiones antiguas de Verbio (IberVox 6.41 y anteriores), aunque en nuevos desarrollos es aconsejable utilizar la Advanced SDK, puesto que ésta facilita el uso de las nuevas funcionalidades incorporadas en Verbio (aunque este SDK sólo está disponible en entornos de programación Microsoft Visual Studio). En el Capítulo 2. Descripción de las funciones se describen todas las funciones disponibles en el SDK. En el Capítulo 3. Estructuras de datos y parámetros se describen las estructuras y parámetros comunes a las funciones del SDK. En el Capítulo 4. Código de ejemplos en C/C++ se incluyen 3 ejemplos de utilización de este SDK: un ejemplo de programación síncrona, otro de programación asíncrona y un tercero de programación utilizando la técnica del barge-in.

12

13 Capítulo 2. Descripción de las funciones

14 1. vx_activatevcb FUNCION int vx_activatevcb(int chdev, int vcbhandle, unsigned int mode) int chdev int vcbhandle unsigned int mode descriptor de un canal abierto de Dialogic descriptor de un vocabulario o gramática ABNF previamente cargado funcionamiento síncrono o asíncrono RETORNA >=0 indicando el descriptor del vocabulario si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono/asíncrono 1.1. Descripción La función vx_activatevcb() activa el vocabulario previamente cargado en el canal especificado. El descriptor del vocabulario cargado se obtiene invocando a la función vx_loadvcb(). Cuando no deba utilizarse en el siguente proceso de reconocimiento, debe ser desactivado mediante la función vx_deactivatevcb() Funcionamiento asíncrono En modo asíncrono la función retorna de inmediato, generándose el evento TVX_SETVCB una vez ha finalizado. En caso de error, se genera el evento TVX_ERROR Descripción de los parámetros chdev vcbhandle mode especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). descriptor de un vocabulario o gramática ABNF previamente cargado mediante la función vx_loadvcb(). especifica si debe ejecutarse la función vx_activatevcb() en modo síncrono o asíncrono. EV_ASYNC EV_SYNC Ejecuta vx_activatevcb() asíncronamente Ejecuta vx_activatevcb() síncronamente (valor por defecto) 1.4. Precauciones En cualquier momento, pueden estar activos varios vocabularios y gramáticas. El descriptor utilizado en la función vx_activatevcb() debe ser el valor retornado por la función vx_loadvcb(). La función ATVX_IVCB() retorna el descriptor asociado al vocabulario que contiene la locución reconocida. Si se establece el vocabulario o la gramática activa mediante la función vx_setvcb() o vx_setcd(), se descargarán automáticamente todos los vocabularios y gramáticas cargados hasta ese momento Errores En modo asíncrono, la función retorna de forma inmediata, generándose el evento TVX_SETVCB en cuanto 4 Referencia de las funciones del Dialogic SDK Verbio Technologies

15 finalice. Si se produce un error, el evento recibido será TVX_ERROR. En este caso, utilice la función ATVX_LASTERR() para conocer el motivo del error. En modo síncrono, si la función retorna -1 indicando que se ha producido un error, la función ATVX_LASTERR() devolverá alguno de los siguientes motivos: EVX_NOMEM EVX_VCBFILE EVX_INVWORD EVX_SYSTEM OUT OF MEMORY THE VOCABULARY FILE NAME IS NOT VALID. Check the vocabulary file name and path writing permission. THE VOCABULARY TRANSCRIPTION WAS NOT FOUND SYSTEM ERROR. Check errno Elementos relacionados vx_setvcb, vx_loadvcb, vx_deactivatevcb, vx_unloadvcb, ATVX_IVCB 1.7. Códigos de ejemplo Consulte el ejemplo síncrono. Verbio Technologies Referencia de las funciones del Dialogic SDK 5

16 2. vx_applydictionary FUNCION int vx_applydictionary(const char *invcbname, const char *outvcbname, const char *Dictionary) const char *invcbname const char *outvcbname const char *Dictionary nombre del fichero que contiene el vocabulario que debe procesarse nombre del fichero bajo el que se almacenará el fichero de vocabulario procesado nombre del fichero que contiene el vocabulario de excepciones RETORNA 0 si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono 2.1. Descripción La función vx_applydictionary() genera un fichero de vocabulario a partir de otro original incluyendo las excepciones y acrónimos contenidos en el diccionario especificado Descripción de los parámetros invcbname outvcbname Dictionary nombre del fichero de vocabulario original que debe ser procesado. Cada línea debe contener una palabra del vocabulario formado por una o más palabras. nombre del fichero que contendrá el nuevo vocabulario. Cada línea contendrá una palabra del vocabulario formada por las palabras originales o bien por aquellas que hayan sido modificadas siguiendo las pautas del diccionario de excepciones. nombre del fichero de texto que contiene las excepciones que deben considerarse. Consulte Verbio Software Reference: Guía del usuario para más información del formato que debe tener este un fichero de excepciones Errores Si la función retorna -1 indicando que se ha producido un error, mediante las funciones ATVX_LASTERR(-1) y ATVX_ERRMSGP(-1) obtendrá alguno de los siguientes motivos de error: EVX_NOMEM EVX_VCBFILE EVX_DICFILE OUT OF MEMORY THE VOCABULARY FILE NAME IS NOT VALID. Check the vocabulary file name and path writing permission. THE DICTIONARY FILE NAME IS NOT VALID. Check the dictionary file name Elementos relacionados vx_prevcb, vx_prevcbex, vx_chkwrd 6 Referencia de las funciones del Dialogic SDK Verbio Technologies

17 2.5. Códigos de ejemplo Consulte el ejemplo asíncrono. Verbio Technologies Referencia de las funciones del Dialogic SDK 7

18 3. vx_asr_init FUNCION int vx_asr_init(const char *configuration, const char *defasrlng) const char *configuration const char *defasrlng identificador de la configuración de reconocimiento por defecto identificador del idioma de reconocimiento por defecto RETORNA 0 si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono 3.1. Descripción La función vx_asr_init() inicializa la librería de reconocimiento del habla de Verbio. En nuevos desarrollos es recomendable utilizar esta función (conjuntamente con la función vx_tts_init en caso de que también se requiera síntesis del habla) en lugar de la función vx_libinit, puesto que permite indicar al servidor los parámetros de inicialización de una manera mucho más concreta Descripción de los parámetros configuration especifica la configuración por defecto con la que arrancará el servidor de reconocimiento. Por configuración de reconocimiento se entiende el idioma o idiomas soportados (en caso de configuraciones multilingües) por el servidor de reconocimiento. Cualquier proceso de reconocimiento invocado usará los modelos de reconocimiento asociados con la configuración activa en ese momento, por lo que únicamente podrá reconocerse en alguno de los idiomas contenidos en dicha configuración. Para más información, puede consultarse el documento Verbio Software Reference: Guía del Usuario. CFG_SPANISH Español castellano CFG_SPANISH_CATALAN Español castellano + catalán CFG_SPANISH_BASQUE Español castellano + euskera CFG_SPANISH_GALICIAN Español castellano + gallego CFG_SPANISH_CATALAN_BASQUE_GALICIAN Español castellano + catalán + euskera + gallego CFG_PORTUGUESE CFG_PORTUGUESE_BRAZILIAN CFG_SPANISH_ARGENTINIAN CFG_SPANISH_CHILEAN CFG_SPANISH_COLOMBIAN Portugués Portugués brasileño Español argentino Español chileno Español colombiano 8 Referencia de las funciones del Dialogic SDK Verbio Technologies

19 CFG_SPANISH_MEXICAN CFG_SPANISH_VENEZUELAN CFG_FRENCH CFG_ENGLISH Español mexicano Español venezolano Francés Inglés defasrlng especifica el idioma por defecto con el que trabaja la configuración por defecto. En el caso de configuraciones monolingües es redundante, aunque sí es imprescindible cuando se activa una configuración multilingüe. LNG_SPANISH LNG_CATALAN LNG_BASQUE LNG_GALICIAN LNG_PORTUGUESE LNG_PORTUGUESE_BRAZILIAN LNG_SPANISH_ARGENTINIAN LNG_SPANISH_CHILEAN LNG_SPANISH_COLOMBIAN LNG_SPANISH_MEXICAN LNG_SPANISH_VENEZUELAN LNG_FRENCH LNG_ENGLISH Español castellano Catalán Euskera Gallego Portugués Portugués brasileño Español argentino Español chileno Español colombiano Español mexicano Español venezolano Francés Inglés 3.3. Precauciones La función vx_asr_init() debe invocarse antes que ninguna otra de las funciones del SDK de Verbio relacionadas con el reconocimiento del habla, a excepción de aquella destinada a establecer el servidor de trabajo por defecto en configuraciones cliente-servidor (vx_setparm) Errores Si la función retorna -1 indicando que se ha producido un error, mediante las funciones ATVX_LASTERR(-1) y ATVX_ERRMSGP(-1) obtendrá alguno de los siguientes motivos de error: EVX_SRERROR DIALOGIC SRL ERROR. Check ATDV_LASTERR() and ATDV_ERRMSGP(). EVX_DXERROR DIALOGIC VOICE ERROR. Check ATDV_LASTERR() and ATDV_ERRMSGP(). EVX_NOBOARDS EVX_INVSETUP NO BOARDS DETECTED. Check Dialogic Drivers Start Up. VERBIO INTERNAL ERROR. Files may be corrupted. Check disk and repeat Setup. Verbio Technologies Referencia de las funciones del Dialogic SDK 9

20 EVX_NOMEM EVX_NOLICFILE EVX_INVLIC EVX_SYSTEM EVX_INVSRVER EVX_INVDXVER OUT OF MEMORY. NO LICENSE FILE WAS FOUND. Run CheckOut to obtain a license file. THE LICENSE FILE IS NOT VALID. Run CheckOut to obtain a valid license file. SYSTEM ERROR.Check errno. INVALID DIALOGIC SRL RELEASE (libsrlmt.dll). Check README.TXT. INVALID DIALOGIC VOICE LIBRARY RELEASE (libdxxmt.dll) Elementos relacionados vx_libinit vx_tts_init vx_libclose 3.6. Códigos de ejemplo Consulte el ejemplo síncrono. 10 Referencia de las funciones del Dialogic SDK Verbio Technologies

21 4. vx_asv_addfile FUNCION int vx_asv_addfile(int chdev, const char* id, const char* filename, const char* transcription, unsigned int mode) int chdev const char *id const char *filename const char *transcription unsigned int mode descriptor de un canal abierto de Dialogic identificador del usuario nombre del fichero de audio a incorporar al usuario transcripción del contenido del fichero formato de las muestras de audio RETORNA 0 si el resultado es satisfactorio <0 en caso de error INCLUDES MODO vxxxlib.h síncrono 4.1. Descripción La función vx_asv_addfile() almacena un fichero de audio en la base de datos de usuarios para ser utilizado en el momento de crear la huella vocal del usuario indicado, mediante la invocación de la función vx_asv_train. Adicionalmente, utilizando la capacidad de reconocimiento de Verbio ASR, comprueba también que el contenido del fichero coincide con la transcripción, de modo que pueda certificarse que el usuario ha pronunciado exactamente aquello que se le ha solicitado Descripción de los parámetros chdev id especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). identificador del usuario del que se ha obtenido un nuevo fichero de audio para el entrenamiento de su huella vocal. El identificador de un usuario es una cadena alfanumérica (dígitos o caracteres a-z,a-z) elegida por el desarrollador de la aplicación. Debe ser única para cada usuario, siendo habitual que el identificador coincida con el identificador numérico (cadena de dígitos) que se le solicitará al usuario para identificarse en el sistema. filename transcription mode nombre completo del fichero que contiene la locución del usuario indicado, destinado a ser utilizado en el proceso de creación de su huella vocal. transcripción del contenido del fichero de audio, para certificar que el contenido coincide con la secuencia de dígitos solicitada. especifica el formato de las muestras de audio del fichero. MC_ALAW fichero sin cabecera, muestras de audio en formato Ley A (8 bits, 8 KHz). MC_MULAW fichero sin cabecera, muestras de audio en formato Ley Mu (8 bits, 8 KHz). Verbio Technologies Referencia de las funciones del Dialogic SDK 11

22 MC_LIN16 fichero sin cabecera, muestras de audio en formato lineal (16 bits, 8 KHz). MC_WAVE fichero WAVE, muestras de audio en cualquiera de los formatos anteriores Precauciones El contenido de los ficheros de entrenamiento debe ser, exclusivamente, cadenas de dígitos (de longitud variable). Por lo tanto, las transcripciones proporcionadas deben ser cadenas numéricas, del tipo , , etcétera. Se aconseja que las cadenas de entrenamiento tengan una longitud mínima de 8 dígitos y que se proporcionen, al menos, 20 de ellas, obtenidas en diferentes días (mínimo dos) y franjas horarias (mañana/tarde). Alternativamente a utilizar la función vx_asv_addfile para cada nuevo fichero, también es posible invocar directamente la función vx_asv_train especificando un listado de ficheros de audio a utilizar en el entrenamiento de la huella vocal del usuario. No obstante, se aconseja el uso de la función vx_asv_addfile a medida que se adquieren los ficheros de audio, ya que de este modo podrán tomarse acciones correctivas en caso de que el proceso de validación indique que la transcripción no coincide con el contenido real del fichero Errores En caso de error, la función retorna un valor negativo. Los posibles códigos de error retornados por esta función son: -1 El canal especificado no es válido. -4 Error interno de Verbio. La estructura de la base de datos está corrupta. -6 Error al lanzar el proceso de reconocimiento del contenido del fichero de audio. -18 Algún parámetro no ha sido especificado o bien es incorrecto. -27 El contenido del fichero no coincide con la transcripción proporcionada, o bien no se ha podido comprobar Elementos relacionados vx_asv_init, vx_asv_spkinfo, vx_asv_train, vx_asv_verify 4.6. Códigos de ejemplo Consulte el ejemplo de la Library SDK. 12 Referencia de las funciones del Dialogic SDK Verbio Technologies

23 5. vx_asv_spkinfo FUNCION int vx_asv_spkinfo(int chdev, const char* id, ASV_SPKINFO* info) int chdev const char *id descriptor de un canal abierto de Dialogic identificador del usuario ASV_SPKINFO* info puntero a una estructura del tipo ASV Speaker Information RETORNA 2 si el usuario está registrado y dispone de huella vocal 1 si el usuario está registrado y no dispone de huella vocal 0 si el usuario no está registrado <0 en caso de error INCLUDES MODO vxxxlib.h síncrono 5.1. Descripción La función vx_asv_spkinfo() permite conocer el estado del usuario indicado, es decir, si está registrado (se ha realizado alguna operación sobre él) y si está listo para que se realicen sobre él operaciones de verificación (se ha generado su huella vocal). Además, a través de la estructura ASV Speaker Information (ASV_SPKINFO), permite obtener información adicional acerca de las locuciones de que dispone actualmente el usuario para el entrenamiento de su huella vocal Descripción de los parámetros chdev id especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). identificador del usuario del que se desea obtener información. el identificador de un usuario es una cadena alfanumérica (dígitos o caracteres a-z,a-z) elegida por el desarrollador de la aplicación. Debe ser única para cada usuario, siendo habitual que el identificador coincida con el identificador numérico (cadena de dígitos) que se le solicitará al usuario para identificarse en el sistema. info NULL si no se requiere información adicional. puntero a una estructura de tipo ASV Speaker Information (ASV_SPKINFO) en la que recibir información acerca de las locuciones de que dispone actualmente el usuario para el entrenamiento de su huella vocal. Para más información acerca de esta estructura, consulte Capítulo 3. Estructuras de datos y parámetros Errores Si la función retorna -1 indicando que se ha producido un error, debe comprobarse que el canal especificado como primer parámetro es válido Elementos relacionados vx_asv_init, vx_asv_addfile, vx_asv_train, vx_asv_verify Verbio Technologies Referencia de las funciones del Dialogic SDK 13

24 5.5. Códigos de ejemplo Consulte el ejemplo de la Library SDK. 14 Referencia de las funciones del Dialogic SDK Verbio Technologies

25 6. vx_asv_init FUNCION RETORNA int vx_asv_init() 0 si el resultado es satisfactorio <0 en caso de error INCLUDES MODO vxxxlib.h síncrono 6.1. Descripción La función vx_asv_init() inicializa la librería Verbio, preparándola para poder recibir peticiones de verificación de locutor Precauciones La función vx_asv_init() debe invocarse previamente a cualquier invocación del resto de funciones asociadas a la verificación de locutor, tales como: vx_asv_addfile, vx_asv_train, vx_asv_verify y vx_asv_spkinfo Errores En caso de error, la función retorna un valor negativo. Los posibles códigos de error retornados por esta función son: -13 Error interno de Verbio. Probablemente la instalación de los componentes de ASV no se ha realizado o se ha hecho de forma incorrecta. -14 No se dispone de licencias de ASV o bien éstas han caducado Elementos relacionados vx_asv_addfile, vx_asv_train, vx_asv_verify, vx_asv_spkinfo 6.5. Códigos de ejemplo Consulte el ejemplo de la Library SDK. Verbio Technologies Referencia de las funciones del Dialogic SDK 15

26 7. vx_asv_train FUNCION int vx_asv_train(int chdev, const char* id, const char* filename, int* lpiword, unsigned int mode) int chdev const char *id const char *filename int *lpiword unsigned int mode descriptor de un canal abierto de Dialogic identificador del usuario listado de ficheros de audio a utilizar durante el proceso de entrenamiento puntero a un entero que, en caso de error en alguno de los ficheros, almacenará la línea que contiene el fichero erróneo formato de las muestras de audio de los ficheros RETORNA 0 si el resultado es satisfactorio <0 en caso de error INCLUDES MODO vxxxlib.h síncrono 7.1. Descripción La función vx_asv_train() lanza el proceso de generación de la huella vocal del usuario indicado. Las locuciones del usuario que se utilizarán para este proceso serán las especificadas mediante el parámetro filename junto con todas aquellas asignadas al usuario anteriormente mediante llamadas a las funciones vx_asv_addfile y/o vx_asv_train(). Una vez completada correctamente la función vx_asv_train(), el usuario ya estará listo para que se realicen sobre él operaciones de verificación mediante la función vx_asv_verify(). En caso de que el usuario ya dispusiera de huella vocal, se generará una nueva huella vocal que reemplazará a la ya existente Descripción de los parámetros chdev id especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). identificador del usuario al que entrenar su huella vocal. El identificador de un usuario es una cadena alfanumérica (dígitos o caracteres a-z,a-z) elegida por el desarrollador de la aplicación. Debe ser única para cada usuario, siendo habitual que el identificador coincida con el identificador numérico (cadena de dígitos) que se le solicitará al usuario para identificarse en el sistema. filename NULL si todos los ficheros de audio y sus respectivas transcripciones se han proporcionado previamente invocando las funciones vx_asv_addfile y/o vx_asv_train(). En caso contrario, nombre completo del fichero de texto que contiene el listado de ficheros de audio a utilizar para la generación de la huella vocal, junto con sus respectivas transcripciones. El formato de este fichero debe ser el siguiente (una línea, acabada en retorno de carro, para cada fichero de audio a utilizar): nombre_fichero_audio TAB transcripcion_cadena_digitos RC 16 Referencia de las funciones del Dialogic SDK Verbio Technologies

27 RC = Retorno de Carro, TAB = Tabulador lpiword en caso de haber especificado un listado de ficheros mediante el parámetro filename, puntero a un entero que, en caso de error en alguno de los ficheros, recibirá el número de la línea que contiene el fichero erróneo. Debe consultarse este valor si la función retorna el error -27. NULL en caso contrario. mode en caso de haber especificado un listado de ficheros mediante el parámetro filename, indica el formato de las muestras de audio de los ficheros. MC_ALAW fichero sin cabecera, muestras de audio en formato Ley A (8 bits, 8 KHz). MC_MULAW fichero sin cabecera, muestras de audio en formato Ley Mu (8 bits, 8 KHz). MC_LIN16 fichero sin cabecera, muestras de audio en formato lineal (16 bits, 8 KHz). MC_WAVE fichero WAVE, muestras de audio en cualquiera de los formatos anteriores Precauciones El contenido de los ficheros de entrenamiento debe ser, exclusivamente, cadenas de dígitos (de longitud variable). Por lo tanto, las transcripciones proporcionadas deben ser cadenas numéricas, del tipo , , etcétera. Se aconseja que las cadenas de entrenamiento tengan una longitud mínima de 8 dígitos y que se proporcionen, al menos, 20 de ellas, obtenidas en diferentes días (mínimo dos) y franjas horarias (mañana/tarde). En lugar de especificar conjuntamente el listado de ficheros y sus transcripciones mediante la función vx_asv_train, es preferible utilizar la función vx_asv_addfile individualmente para cada fichero según se vayan obteniendo las locuciones del usuario. De este modo, podrán tomarse acciones correctivas en caso de que el proceso de validación interno indique que el contenido de algún fichero no coincide con la transcripción proporcionada Errores En caso de error, la función retorna un valor negativo. Los posibles códigos de error retornados por esta función son: -1 El canal especificado no es válido. -4 Error interno de Verbio. La estructura de la base de datos está corrupta. -5 No se dispone de suficiente memoria disponible para ejecutar la función. -6 Error al lanzar el proceso de reconocimiento del contenido del fichero de audio. -10 Error al lanzar el proceso de verificación del locutor. -18 Algún parámetro no ha sido especificado o bien es incorrecto. -21 El fichero especificado como parámetro no está disponible. -27 El contenido de algún fichero no coincide con la transcripción proporcionada, o bien no se ha podido comprobar. Verbio Technologies Referencia de las funciones del Dialogic SDK 17

28 -28 No se dispone de suficiente material para entrenar. Es necesario proporcionar más locuciones numéricas del usuario a entrenar Elementos relacionados vx_asv_init, vx_asv_spkinfo, vx_asv_addfile, vx_asv_verify 7.6. Códigos de ejemplo Consulte el ejemplo de la Library SDK. 18 Referencia de las funciones del Dialogic SDK Verbio Technologies

29 8. vx_asv_verify FUNCION int vx_asv_verify(int chdev, const char* id, const char* filename, const char* transcription, float* score, unsigned int mode) int chdev const char *id const char *filename const char *transcription float* score unsigned int mode descriptor de un canal abierto de Dialogic identificador del usuario nombre del fichero de audio utilizado para verificar la identidad del usuario transcripción del contenido del fichero de audio índice de confianza de la veracidad de la identidad del usuario formato de las muestras de audio RETORNA 1 si el usario SÍ es quien dice ser 0 si el usario NO es quien dice ser <0 en caso de error INCLUDES MODO vxxxlib.h síncrono 8.1. Descripción La función vx_asv_verify() lanza el proceso de verificación para determinar si la locución proporcionada pertenece realmente al usuario indicado. Para ello, se deberá haber generado previamente la huella vocal de dicho usuario mediante la función vx_asv_train Descripción de los parámetros chdev id especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). identificador del usuario cuya identidad pretende verificarse. el identificador de un usuario es una cadena alfanumérica (dígitos o caracteres a-z,a-z) elegida por el desarrollador de la aplicación. Debe ser única para cada usuario, siendo habitual que el identificador coincida con el identificador numérico (cadena de dígitos) que se le solicitará al usuario para identificarse en el sistema. filename transcription score mode nombre completo del fichero de audio que será utilizado en el proceso de verificación. transcripción del contenido del fichero de audio, para certificar que el contenido coincide con la secuencia de dígitos solicitada. puntero a float que, tras el proceso de verificación, almacenará el índice de confianza de la veracidad de la identidad del usuario. especifica el formato de las muestras de audio del fichero. Verbio Technologies Referencia de las funciones del Dialogic SDK 19

30 MC_ALAW fichero sin cabecera, muestras de audio en formato Ley A (8 bits, 8 KHz). MC_MULAW fichero sin cabecera, muestras de audio en formato Ley Mu (8 bits, 8 KHz). MC_LIN16 fichero sin cabecera, muestras de audio en formato lineal (16 bits, 8 KHz). MC_WAVE fichero WAVE, muestras de audio en cualquiera de los formatos anteriores Precauciones El contenido de los ficheros de verificación debe ser, exclusivamente, cadenas de dígitos (de longitud variable). Por lo tanto, las transcripciones proporcionadas deben ser cadenas numéricas, del tipo , , etcétera. Se aconseja que las cadenas de verificación tengan una longitud de entre 6 y 8 dígitos (cuanto más larga, mayor fiablidad en el proceso de verificación). En general, la decisión de si el usuario ha sido verificado o no deberá tomarse del valor devuelto por la función, y no del valor de índice de confianza (parámetro score), el cual se proporciona principalmente a efectos estadísticos Errores En caso de error, la función retorna un valor negativo. Los posibles códigos de error retornados por esta función son: -1 El canal especificado no es válido. -4 Error interno de Verbio. La estructura de la base de datos está corrupta. -5 No se dispone de suficiente memoria disponible para ejecutar la función. -6 Error al lanzar el proceso de reconocimiento del contenido del fichero de audio. -10 Error al lanzar el proceso de verificación del locutor. -18 Algún parámetro no ha sido especificado o bien es incorrecto. -21 El fichero especificado como parámetro no está disponible. -27 El contenido del fichero no coincide con la transcripción proporcionada, o bien no se ha podido comprobar Elementos relacionados vx_asv_init, vx_asv_spkinfo, vx_asv_train, vx_asv_addfile 8.6. Códigos de ejemplo Consulte el ejemplo de la Library SDK. 20 Referencia de las funciones del Dialogic SDK Verbio Technologies

31 9. ATVX_BUILTIN FUNCION int ATVX_BUILTIN(int chdev) int chdev descriptor de un canal abierto de Dialogic RETORNA 0 para indicar que el resultado del reconocimiento no procede de una gramática built-in 1 para indicar que el resultado del reconocimiento sí procede de una gramática built-in INCLUDES MODO vxxxlib.h síncrono 9.1. Descripción La función ATVX_BUILTIN() indica si la gramática que ha devuelto el resultado de reconocimiento al finalizar la llamada a la función vx_recind() o vx_nbest() es una gramática interna (built-in) o no Descripción de los parámetros chdev especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open() Precauciones El valor devuelto por la función ATVX_BUILTIN() únicamente es válido después de la correcta finalización de la función vx_recind() o vx_nbest() Elementos relacionados vx_recind, vx_nbest Verbio Technologies Referencia de las funciones del Dialogic SDK 21

32 10. vx_chkwrd FUNCION int vx_chkwrd(const char *word, int language) const char *word unsigned int language puntero a la palabra del vocabulario que desea verificarse idioma del vocabulario RETORNA 0 si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_chkwrd() chequea la palabra del vocabulario especificada para garantizar que la función vx_prevcb() (o vx_prevcbex() o vx_prevcbex2() o vx_prevcbdev()) realizará la transcripción de texto a fonema de forma correcta. Esta función es independiente del canal de Dialogic, por lo que únicamente debe ser llamada una vez para cada nueva palabra de los vocabularios, independientemente de si, con posterioridad, el vocabulario se usará en varios canales Descripción de los parámetros word language puntero a la palabra del vocabulario (formada por una o más palabras) que desea verificarse. especifica el idioma con el que se preparará el vocabulario que contiene la palabra a analizar. LVX_SPANISH LVX_CATALAN Español Catalán Precauciones Esta función realiza una verificación más exhaustiva que la utilizada por la función vx_prevcb(). Por lo tanto, es posible que la función vx_prevcb() (o vx_prevcbex() o vx_prevcbex2() o vx_prevcbdev()) realice una correcta transcripción a pesar de que la función vx_chkwrd() devuelva error. No obstante, es aconsejable corregir aquellas palabras incorrectas para conseguir una transcripción más precisa. Esta función únicamente está disponible para los idiomas castellano y catalán Elementos relacionados vx_prevcb, vx_prevcbex, vx_prevcbex2, vx_prevcbdev, vx_applydictionary Códigos de ejemplo Consulte el ejemplo con barge-in. 22 Referencia de las funciones del Dialogic SDK Verbio Technologies

33 11. vx_clrrsp FUNCION void vx_clrrsp(vx_rsp *rspp) VX_RSP *rspp puntero a una estructura de tipo Recognition String Parameter RETORNA INCLUDES MODO Nada vxxxlib.h síncrono Descripción La función vx_clrrsp() resetea todos los campos de la estructura VX_RSP asignándoles sus valores por defecto. Es aconsejable utilizar esta función para inicializar cualquier estructura VX_RSP antes de ser utilizada por otras funciones Descripción de los parámetros rspp puntero a la estructura de tipo Recognition String Parameter que desea inicializarse. Esta estructura especifica parámetros y condiciones de terminación adicionales para el proceso de reconocimiento. Consulte Capítulo 3. Estructuras de datos y parámetros para obtener més información acerca de las estructuras VX_RSP Precauciones La estructura RSP debe ser reseteada mediante la función vx_clrrsp() antes de modificar alguno de sus campos Elementos relacionados vx_recstr, vx_recstr_open Códigos de ejemplo Consulte el ejemplo síncrono. Verbio Technologies Referencia de las funciones del Dialogic SDK 23

34 12. vx_clrvad FUNCION void vx_clrvad(vad_prm *prm) VAD_PRM *prm puntero a una estructura de tipo Voice Activity Detection Parameter RETORNA INCLUDES MODO Nada vxxxlib.h síncrono Descripción La función vx_clrvad() resetea todos los campos de la estructura VAD_PRM asignándoles sus valores por defecto. Es aconsejable utilizar esta función para inicializar cualquier estructura VAD_PRM antes de ser utilizada por otras funciones. Para conocer el contenido de la estructura y los valores por defecto que les asigna esta función, consulte el Capítulo 3. Estructuras de datos y parámetros Descripción de los parámetros prm puntero a la estructura de tipo Voice Activity Detection Parameter que desea inicializarse. Esta estructura especifica parámetros y condiciones de contorno para el proceso de detección de la actividad vocal. Consulte el Capítulo 3. Estructuras de datos y parámetros para obtener més información acerca de la estructura VAD_PRM Precauciones La estructura VAD_PRM debe ser reseteada mediante la función vx_clrvad antes de modificar cualquiera de sus campos Elementos relacionados vx_vsd_open Códigos de ejemplo Consulte el ejemplo de detección de voz. 24 Referencia de las funciones del Dialogic SDK Verbio Technologies

35 13. vx_deactivatevcb FUNCION int vx_deactivatevcb(int chdev, int vcbhandle, unsigned int mode) int chdev int vcbhandle unsigned int mode descriptor de un canal abierto de Dialogic descriptor de un vocabulario o gramática ABNF previamente cargado y activado funcionamiento síncrono o asíncrono RETORNA >=0 indicando el descriptor del vocabulario si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono/asíncrono Descripción La función vx_deactivatevcb() desactiva un vocabulario o gramática ABNF previamente cargado y activado en el canal especificado. El descriptor del vocabulario se obtiene al cargarlo mediante la función vx_loadvcb() y también debe usarse para activarlo mediante la función vx_activatevcb() o para descargarlo mediante la función vx_unloadvcb() Funcionamiento asíncrono En modo asíncrono la función retorna de inmediato, generándose el evento TVX_SETVCB una vez ha finalizado. En caso de error, se genera el evento TVX_ERROR Descripción de los parámetros chdev vcbhandle mode especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). descriptor de un vocabulario o gramática ABNF previamente cargado mediante la función vx_loadvcb() y activado mediante la función vx_activatevcb(). especifica si debe ejecutarse la función vx_deactivatevcb() en modo síncrono o asíncrono. EV_ASYNC Ejecuta vx_deactivatevcb() asíncronamente EV_SYNC Ejecuta vx_deactivatevcb() síncronamente (valor por defecto) Precauciones En cualquier momento, pueden estar activos varios vocabularios y gramáticas. El descriptor utilizado en la función vx_deactivatevcb() debe ser el valor retornado por la función vx_loadvcb(). Si se establece el vocabulario o la gramática activa mediante la función vx_setvcb() o vx_setcd(), se descargarán automáticamente todos los vocabularios y gramáticas cargados hasta ese momento Errores Verbio Technologies Referencia de las funciones del Dialogic SDK 25

36 En modo asíncrono, la función retorna de forma inmediata, generándose el evento TVX_SETVCB en cuanto finalice. Si se produce un error, el evento recibido será TVX_ERROR. En este caso, utilice la función ATVX_LASTERR() para conocer el motivo del error. En modo síncrono, si la función retorna -1 indicando que se ha producido un error, la función ATVX_LASTERR() devolverá alguno de los siguientes motivos: EVX_NOMEM EVX_VCBFILE EVX_INVWORD EVX_SYSTEM OUT OF MEMORY THE VOCABULARY FILE NAME IS NOT VALID. THE VOCABULARY TRANSCRIPTION WAS OT FOUND SYSTEM ERROR. Check errno Elementos relacionados vx_setvcb, vx_loadvcb, vx_loadcd, vx_activatevcb, vx_unloadvcb, ATVX_IVCB Códigos de ejemplo Consulte el ejemplo síncrono. 26 Referencia de las funciones del Dialogic SDK Verbio Technologies

37 14. vx_devclose FUNCION int vx_devclose(int chdev) int chdev descriptor de un canal abierto de Dialogic RETORNA 0 si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_devclose() libera los recursos consumidos por el canal especificado. Es aconsejable invocarla cuando la aplicación no deba hacer uso de recursos de reconocimiento ni de síntesis por el canal indicado Descripción de los parámetros chdev especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open() Precauciones En aplicaciones cuyos descriptores de canal se creen y destruyan de forma permanente (es decir, que no son utilizados a lo largo de todo el tiempo de vida de la aplicación) es muy recomandable invocar a esta función al finalizar el uso del cada canal. De este modo, se liberaran recursos (memoria, procesos, etc.) que pueden ser requeridos por los nuevos canales a utilizar Errores Si la función retorna -1 indicando que se ha producido un error, mediante las funciones ATVX_LASTERR() y ATVX_ERRMSGP() obtendrá alguno de los siguientes motivos de error: EVX_NOLINE NO MORE LINES ARE AVAILABLE FOR THE SPECIFIED CHANNEL DEVICE Elementos relacionados vx_libclose, vx_srvclose, vx_thclose Códigos de ejemplo Consulte el ejemplo síncrono. Verbio Technologies Referencia de las funciones del Dialogic SDK 27

38 15. vx_dtmf_close FUNCION int vx_dtmf_close(int chdev, DTMF_REG* dtmfdev) int chdev DTMF_REG* dtmfdev descriptor de un canal abierto de Dialogic descriptor de detección de tonos DTMF válido RETORNA 0 si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_dtmf_close() cierra el desciptor de detección de tonos DTMF abierto mediante la función vx_dtmf_open y libera los recursos utilizados durante el proceso de detección de tonos DTMF Descripción de los parámetros chdev dtmfdev especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). especifica el descriptor de detección de tonos DTMF válido obtenido mediante la función vx_dtmf_open Elementos relacionados vx_dtmf_open, vx_dtmf_write Códigos de ejemplo Consulte el ejemplo anexo. 28 Referencia de las funciones del Dialogic SDK Verbio Technologies

39 16. vx_dtmf_open FUNCION DTMF_REG* vx_dtmf_open(int chdev, unsigned int mode) int chdev unsigned int mode descriptor de un canal abierto de Dialogic formato de las muestras (Ley A, Ley Mu o lineal) RETORNA!= -1 para indicar el descriptor de detección de tonos DTMF -1 en caso de error INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_dtmf_open() inicializa el detector de tonos DTMF en el canal especificado, de modo que esté preparado para empezar a recibir las muestras de audio mediante la función vx_dtmf_write(). El valor devuelto por la función es requerido por las funciones vx_dtmf_write() y vx_dtmf_close() Descripción de los parámetros chdev mode especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). especifica el formato de las muestras de audio pasadas al detector de voz. MC_ALAW MC_MULAW MC_LIN16 formato PCM (Ley A) a 8 KHz. formato PCM (Ley Mu) a 8 KHz. formato PCM (lineal 16 bits) a 8 KHz Precauciones Una vez finalizado el proceso de detección de tonos DTMF, es imprescindible invocar a la función vx_dtmf_close para liberar los recursos de memoria utilizados durante el proceso de detección Elementos relacionados vx_dtmf_write, vx_dtmf_close Códigos de ejemplo Consulte el ejemplo anexo. Verbio Technologies Referencia de las funciones del Dialogic SDK 29

40 17. vx_dtmf_word FUNCION char* vx_dtmf_word(int chdev, const char *sequence) int chdev const char* sequence descriptor de un canal abierto de Dialogic cadena de tonos DTMF recibida en el canal. RETORNA puntero a un vector de caracteres con el contenido de la palabra del vocabulario retornada por la gramática, cuando se cumple una de sus alternativas. puntero nulo si la secuencia no cumple ninguna de las opciones contempladas por la gramática DTMF. INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_dtmfword() devuelve un puntero a un vector de caracteres ASCIIZ con el contenido asociado a la secuencia de tonos DTMF recibido por el canal y contenidos en el vocabulario o gramática activa en el canal Descripción de los parámetros chdev sequence especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). cadena de tonos DTMF recibida mediante las funciones vx_dtmf_open, vx_dtmf_write y vx_dtmf_close y de la que se desea saber si cumple la gramática DTMF cargada en el canal especificado Elementos relacionados vx_wordex, vx_recstr Códigos de ejemplo Consulte el ejemplo síncrono. 30 Referencia de las funciones del Dialogic SDK Verbio Technologies

41 18. vx_dtmf_write FUNCION const char* vx_dtmf_write(dtmf_reg* dtmfdev, const void *buffer, unsigned int n) DTMF_REG* dtmfdev const void *buffer unsigned int n descriptor de detección de tonos DTMF válido vector en el que se encuentran las muestras de audio que debe procesar el detector de tonos DTMF tamaño del vector de muestras (en bytes) RETORNA puntero a un vector de caracteres con los tonos DTMF reconocidos en el vector de muestras acabado de procesar 0 (NULL) en caso de que no se haya detectado ningún tono DTMF en el vector de muestras acabado de procesar INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_dtmf_write() envía las muestras recibidas hacia el detector de tonos DTMF para ser procesadas. La función retorna los identificadores de los tonos DTMF detectados dentro de la última trama de muestras procesada. Los posibles identificadores son: * # A B C D Descripción de los parámetros dtmfdev buffer n especifica el descriptor de detección de tonos DTMF válido obtenido mediante la función vx_dtmf_open. vector en el que se encuentran las muestras de audio que debe procesar el detector de tonos DTMF. tamaño del vector de muestras Precauciones El vector de caracteres retornado es volátil, de modo que en las sucesivas invocaciones a esta función o a las funciones vx_dtmf_open y vx_dtmf_close su valor se verá modificado, siendo necesario su almacenamiento si se requiere un procesado posterior del resultado retornado Elementos relacionados vx_dtmf_open, vx_dtmf_close Códigos de ejemplo Consulte el ejemplo anexo. Verbio Technologies Referencia de las funciones del Dialogic SDK 31

42 19. ATVX_ERRMSGP FUNCION char * ATVX_ERRMSGP(int dev) int dev descriptor de un canal abierto de Dialogic o -1 para funciones independientes del canal RETORNA INCLUDES MODO vector de caracteres con una descripción del error ocurrido en la última llamada a una función del SDK vxxxlib.h síncrono Descripción La función ATVX_ERRMSGP() devuelve un puntero a un vector ASCIIZ que describe el motivo del error producido durante la última llamada a una función de la librería Verbio. Este puntero es válido a lo largo de la ejecución de la aplicación. Si no se ha producido ningún error durante la última llamada a una función, el vector contiene el valor "NO ERROR". Si el error se ha producido durante la llamada a una función dependiente del canal (vx_setvcb(), vx_recstr(),...) el parámetro de entrada dev especifica el descriptor de canal de Dialogic correspondiente. Si el error se ha producido durante la llamada a una función independiente del canal (vx_libinit(), vx_prevcb(), vx_applydictionary(),...) debe utilizarse -1 como valor del parámetro dev Descripción de los parámetros dev especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open() o -1 para funciones independientes del canal Elementos relacionados ATVX_LASTERR Códigos de ejemplo Consulte el ejemplo síncrono. 32 Referencia de las funciones del Dialogic SDK Verbio Technologies

43 20. vx_getasrlic FUNCION int vx_getasrlic(const char *configuration) const char *configuration identificador de la configuración de reconocimiento de la que se desean consultar las licencias disponibles RETORNA INCLUDES MODO Número de licencias máximas disponibles (adquiridas) vxxxlib.h síncrono Descripción La función vx_getasrlic() consulta el número de licencias de la configuración especificada disponibles en total (adquiridas) en el servidor utilizado (aquél especificado antes de invocar a la función vx_libinit o vx_asr_init) Descripción de los parámetros configuration especifica la configuración de reconocimiento de la que se desea conocer el número de licencias disponibles. Para más información, puede consultarse el documento Verbio Software Reference: Guía del Usuario. CFG_SPANISH Español castellano CFG_SPANISH_CATALAN Español castellano + catalán CFG_SPANISH_BASQUE Español castellano + euskera CFG_SPANISH_GALICIAN Español castellano + gallego CFG_SPANISH_CATALAN_BASQUE_GALICIAN Español castellano + catalán + euskera + gallego CFG_PORTUGUESE CFG_PORTUGUESE_BRAZILIAN CFG_SPANISH_ARGENTINIAN CFG_SPANISH_CHILEAN CFG_SPANISH_COLOMBIAN CFG_SPANISH_MEXICAN CFG_SPANISH_VENEZUELAN CFG_FRENCH CFG_ENGLISH Portugués Portugués brasileño Español argentino Español chileno Español colombiano Español mexicano Español venezolano Francés Inglés Precauciones Verbio Technologies Referencia de las funciones del Dialogic SDK 33

44 La función vx_getasrlic() debe invocarse una vez establecida la comunicación con el servidor de reconocimiento al que se le solicita el número de licencias disponibles, entendiendo por disponibles el número máximo de peticiones de reconocimiento simultáneas que pueden realizarse, en ese servidor, para la configuración especificada Elementos relacionados vx_getusedasrlic, vx_getttslic vx_getusedttslic, vx_libinit vx_asr_init Códigos de ejemplo Consulte el ejemplo síncrono. 34 Referencia de las funciones del Dialogic SDK Verbio Technologies

45 21. vx_getdllversion FUNCION int vx_getdllversion(unsigned long *fileverp, unsigned long *prodverp) unsigned long *fileverp unsigned long *prodverp número de versión del fichero DLL de VERBIO número de versión del producto RETORNA 0 si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_getdllversion() retorna el número de versión de la DLL de VERBIO tanto del fichero como del producto Descripción de los parámetros fileverp prodverp puntero en el que se guardará la información referente a la versión del fichero. puntero en el que se guardará la información referente a la versión del producto Elementos relacionados dx_getdllversion, sr_getdllversion (consulte la documentación de Dialogic) Códigos de ejemplo Consulte el ejemplo síncrono. Verbio Technologies Referencia de las funciones del Dialogic SDK 35

46 22. vx_getparm FUNCION int vx_getparm(int dev, unsigned long parm, void *valuep) int dev descriptor de un canal abierto de Dialogic o -1 para parámetros globales de VERBIO (independientes del canal) unsigned long parm void *valuep parámetro del que se desea obtener el valor puntero a la variable en la que se almacenará el valor del parámetro solicitado RETORNA 0 si el resultado es satisfactorio -1 en caso de error INCLUDES MODO vxxxlib.h síncrono Descripción La función vx_getparm() obtiene los valores actuales de los parámetros globales o dependientes del canal de VERBIO. Esta función puede obtener el valor de un único parámetro en cada invocación Descripción de los parámetros dev parm valuep especifica el descriptor de canal válido obtenido al abrir el canal mediante la función dx_open(). Use -1 para obtener el valor de parámetros globales de VERBIO. especifica el identificador del parámetro del que se desea recuperar el valor en la variable apuntada por valuep. Los identificadores de los parámetros pueden consultarse en Capítulo 3. Estructuras de datos y parámetros. puntero a la variable en la que se almacenará el valor del parámetro solicitado Elementos relacionados vx_setparm, dx_getparm (consulte la documentación de Dialogic) Códigos de ejemplo Consulte el ejemplo síncrono. 36 Referencia de las funciones del Dialogic SDK Verbio Technologies