• Author / Uploaded
• jeider bastos

Citation preview

INVOX Medical Dictation Manual del SDK

INVOX Medical Dictation Manual del SDK Versiones Fecha

Versión

Responsable

Cambios

05-Jul-2013

2.0-alfa

David García

Borrador completo.

18-Sep-2013

2.0

David García

Nuevas propiedades ​ HighPriority​ y​ Subtype​ en DictationEvent​ . Corregir valores de retorno en el API de alto nivel. NewCorrectionEvent​ incluye ​ Alternates​ , lo que implica cambios en el protocolo de alto nivel. Añadido ​ SessionState​ RECOGNIZING​ ​ y procedimiento RecognizerEngineFlush()​ .

24-Sep-2013

2.1-alfa

David García

Traducción del API a inglés. Explicación de los comandos de voz. Añadido el procedimiento ​ MacrosGetGlobalMacros()​ y el tipo DictationScopeResult​ .

31-Ene-2014

2.1-beta

David García

Cambio de nombre de los servicios de reconocimiento: Recognizer​ →​ RecognizerEngine HighLevel​ →​ Recognizer​ .

14-Feb-2014

2.1

David García

Añadido el procedimiento ​ RecognizerEmulateCommand()​ . Añadida documentación sobre SDK JavaScript y .NET.

15-Jul-2014

2.2

David García

Cambios en el protocolo:  ● SendAudioArray()​ reemplaza a ​ SendAudio()​ . ● Desaparece ​ SessionErrorEvent​ (errores asíncronos), que ha sido absorbida por ​ SessionActEvent​ . ● Desaparece ​ Result.Error​ (errores síncronos). Ahora van en ​ Result.ExceptionType​ y Result.ExceptionMessage​ . ● Algunos procedimientos que utilizaban ​ Result.Value ahora devuelven ​ BoolResult​ : ver servicios ​ Dictionary​ , Macros​ y​ RecognizerEngineIsGrammarActive​ . ● IntegerResult.Integer​ ahora se llama ​ Value​ (utilizado por ​ RecognizerEngineGetMaxAlternates​ ). ● Nuevos tipos de resultado de procedimientos síncronos: WordArrayResult​ y​ MacroArrayResult​ . ● Nuevos procedimientos: ChangePassword()  RecognizerEngineSetFeedbackSuppression()  RecognizerEngineEmulateRecognition()  RecognizerSetFeedbackSuppression()  RecognizerEmulateRecognition()  ● KeepAlive​ es síncrono (hay que esperar devolución de objeto ​ Result​ ). ● Nuevo ​ DictationScope​ CUSTOM​ ​ . ● Uso de cookie de sesión (​ LoginResult.SessionKey​ ). ● Nuevos comandos en ​ IdCommand​ , que ahora se llama CommandId​ . Documentación detallada sobre integración web y .NET.

1

INVOX Medical Dictation Manual del SDK

Cambios en ​ invoxmd​ JavaScript: ● session.connect()​ requiere nombre de variable de sesión. El cliente no tiene que registrar los manejadores del objeto Flash. ● Los eventos relacionados con el reconocimiento ahora cuelgan del objeto ​ recognizer​ . ● Completado el API de ​ recognizer​ . ● Añadido ​ currentScopeEvent​ y​ adaptText()​ . ● Ejemplo muy enriquecido y mejorado. 4-Mar-2015

2.3

David García

Documentación dividida en 2 partes: manual y referencia. Explicación detallada sobre construcción de gramáticas de comandos (​ CommandSpec​ y​ CommandSpecBuilder​ ). Cómo cargar el fichero ​ frasesEntrenamiento.xml​ con Session.Trainer.SetTrainingSentences()​ . Uso de ​ CurrentScopeEvent​ y nuevo ámbito de dictado DictationScope.SPELLING​ . Los usuarios ahora tienen un rol, lo que implica restricciones notificadas con ​ ExceptionType.ROLE_VIOLATION​ y SessionAct.ROLE_VIOLATION​ . Cambios en API JavaScript: ● Todos los nombres de clases, propiedades y manejadores de eventos usan ​ CamelCase​ . Los métodos y enumeraciones siguen usando lowerCamelCase​ . ● El constructor de ​ Session​ requiere un parámetro adicional para activar la continuación automática de sesiones. ● Implementado API de ​ RecognizerEngine​ , incluyendo CommandSpecBuilder​ . ● Control del volumen en ​ AudioSource​ . Cambios en API .NET: ● Cambios diversos en las clases ​ Platform​ y ControlDeviceManager​ . ● Método ​ Session.Setup()​ . ● Soporte de proxys.

2

INVOX Medical Dictation Manual del SDK

Contenidos 1. Introducción 2. Funcionamiento 2.1. Configuración y gestión de recursos Diccionario Macros 2.2. Modo motor de dictado Construcción de gramáticas de comandos 2.3. Modo entrenamiento 2.4. Modo dictado Ámbitos de dictado Tipos de comandos Comandos simples Comandos con parte derecha Texto visible en el editor del documento Selección de la instancia de parte derecha Comando “corregir” Comando “ir a marcador” Ejemplo de uso 3. Integración Medios disponibles Versiones Despliegue 3.1. Comunicación WebSocket + JSON Tipos de mensajes Serialización JSON Ejemplos de mensajes Control de timeout Cookie de sesión Tratamiento de errores 3.2. Librería JavaScript + Flash Componentes Estructura de clases Ejemplo paso a paso El componente Flash invoxmd.Session Sesiones persistentes Componentes de la sesión Uso de la sesión invoxmd.RecognizerEngine invoxmd.Recognizer invoxmd.Trainer invoxmd.AudioSource Enumeraciones Utilidades 3.3. Ensamblados .NET 4 Componentes y dependencias Clases de servicio Clases de apoyo Instalación Aplicación de ejemplo 3

INVOX Medical Dictation Manual del SDK

1. Introducción INVOX Medical Dictation es una plataforma flexible para el dictado de informes clínicos bajo diversos entornos y especialidades médicas. El SDK de INVOX Medical Dictation se compone de una especificación, un API ofrecida en varios medios y la implementación de servicios de reconocimiento de voz (ASR) para el dictado de texto libre y/o basado en gramáticas estructuradas. Entre estos servicios destacan: ● Entrenamiento del perfil de voz del usuario. ● Transcripción de voz a texto a partir de modelos de lenguaje de texto libre. ● Reconocimiento de frases definidas en gramáticas de comandos al estilo SRGS. ● Comandos y otras facilidades para la edición de documentos. ● Gestión de diccionarios y macros (sustituciones), incluyendo la posibilidad de compartir. ● Almacenamiento centralizado y actualización automática del perfil de voz de los usuarios. El objeto de este SDK es el desarrollo de aplicaciones en las que los usuarios podrán invocar comandos y/o transcribir documentos con la voz directamente, canalizando el sonido a través del sistema INVOX y recogiendo de vuelta el texto reconocido y otros eventos. En estos momentos, existen tres medios diferentes para acceder al API con los servicios de INVOX Medical Dictation: ● Canal seguro WebSocket con datos serializados en JSON en un entorno cliente-servidor. El API consiste en llamadas síncronas y asíncronas a procedimientos remotos y recepción de eventos asíncronos. ● Librería JavaScript y Flash para clientes web. Internamente utiliza el canal WebSocket para comunicarse con el servidor de dictado. ● Ensamblados .NET 4 para clientes ligeros o pesados, es decir, con reconocimiento de voz remoto o local. El reconocimiento remoto utiliza internamente el canal WebSocket. Este documento recoge, por un lado, la información genérica de los servicios de reconocimiento de voz y, por otro, las particularidades de cada uno de los medios de integración disponibles. Además, el API completo y la nomenclatura utilizada está especificado en el documento ​ INVOX Medical Dictation - Referencia del SDK​ .

4

INVOX Medical Dictation Manual del SDK

2. Funcionamiento Los servicios de dictado están disponibles dentro del ámbito de una sesión de usuario. Es más, el conjunto de procedimientos que se pueden utilizar en un momento dado está sujeto al estado en que se encuentre esta sesión, tal y como se explica en el siguiente diagrama de estados UML:

Cuando el cliente crea una nueva sesión, ésta se encuentra en estado ​ Desconectada​ . Si el método ​ Login()se ejecuta con éxito, entonces se pasará a estado ​ Conectada​ , en el cual es posible ejecutar las funciones de configuración y gestión de la sesión así como el paso a los modos de ​ Motor de Dictado​ ,​ Entrenamiento o, alternativamente, ​ Dictado​ . Es posible cambiar de modo si se regresa al estado inicial (​ Conectada​ ). Para terminar la sesión correctamente es imprescindible llamar a ​ Logout()​ , con lo que se volverá al estado ​ Desconectada​ . Durante una sesión de ​ Motor de Dictado​ , el cliente puede controlar y configurar completamente el reconocimiento de voz, por ejemplo designando las gramáticas que serán aceptadas por el motor de reconocimiento. En este estado, el sistema puede generar los eventos ​ CommandEvent y DictationEvent​ . Cuando se cambia al modo ​ Entrenamiento​ , el cliente sólo puede configurar el motor de entrenamiento y procesar el evento ​ TrainingSentenceEvent​ .

5

INVOX Medical Dictation Manual del SDK

El modo ​ Dictado permite a las aplicaciones utilizar una configuración típica de reconocimiento de voz para el dictado de informes clínicos con comandos de edición de documentos. Con esto se evita la necesidad de configurar y controlar las operaciones del reconocedor a bajo nivel. El cliente aquí puede recibir los dos eventos del modo ​ Motor de Dictado así como CurrentScopeEvent​ , EndCorrectionEvent​ ​ , InstanceSelectionEvent​ ​ , KeyboardEvent​ ​ , NewCorrectionEvent​ y​ PhoneticEvent​ . En cualquiera de estos estados, el sistema puede lanzar los eventos ​ SessionActEventpara indicar el progreso de las acciones de larga duración y notificar errores asíncronos no vinculados a ninguna llamada del cliente.

2.1. Configuración y gestión de recursos Cuando la sesión está en estado ​ Conectada1 se pueden invocar procedimientos para gestionar el diccionario de palabras y las macros (sustituciones) del usuario.

Diccionario Un diccionario es un conjunto de palabras que el reconocedor de voz será capaz de interpretar además de aquellas que forman parte del modelo de lenguaje del idioma instalado. Cada palabra está compuesta por una forma escrita que la identifica y la distingue de las demás y por cero o más pronunciaciones, es decir, transcripciones fonéticas. El sistema de reconocimiento de voz utiliza dos diccionarios: uno compartido por todos los usuarios y uno personal de cada usuario. El API proporciona procedimientos para gestionar directamente las palabras del diccionario personal e indirectamente las del diccionario compartido: ● DictionaryGetWords()y ​ DictionaryGetWord()​ , para recuperar las palabras del diccionario personal. ● DictionaryAddWord()​ , ​ DictionaryRemoveWord() y ​ DictionaryReplaceWord(), para manipular el diccionario personal, incluyendo la posibilidad de compartir una palabra con el resto de usuarios.

Macros Es posible definir dos tipos de sustituciones: macros de teclado y macros de texto. En ambos casos, la macro se identifica por una secuencia de palabras clave que, cuando se pronuncian, producen un resultado distinto que la transcripción de esas palabras. En las macros de teclado, el resultado es una combinación de teclas codificada en una cadena y sirve para invocar comandos especiales en un editor de texto: negrita, subrayado, etc. Esta invocación se notifica al cliente mediante un ​ KeyboardEvent​ en el modo de ​ Dictado​ . Las macros de texto permiten incrustar fragmentos de texto rápidamente, a modo de plantillas. Son totalmente transparentes al cliente ya que se reciben como un ​ DictationEventque contiene el fragmento de texto resultante. Tener en cuenta que las macros sólo se disparan cuando el usuario hace una pausa de algunos segundos mientras está dictando. Es decir, si las palabras clave de la macro forman parte de una frase más larga, se considera que es texto dictado normal y corriente. Al igual que con la gestión del diccionario, existen dos conjuntos de macros: las compartidas y las personales de cada usuario. La gestión de diccionario y macros también está disponible en el modo ​ Dictado en determinadas condiciones. 1

6

INVOX Medical Dictation Manual del SDK

También aquí el API permite la manipulación directa de las personales e indirecta de las compartidas: ● MacrosGetMacros()​ , para listar las macros personales existentes. ● MacrosAddMacro()​ , ​ MacrosRemoveMacro() y ​ MacrosReplaceMacro()​ , para manipular el conjunto de macros personales y añadir una macro al conjunto de compartidas.

2.2. Modo motor de dictado La transición al estado ​ Motor de Dictado se produce cuando el cliente invoca el procedimiento RecognizerEngineStart()​ . A continuación, lo más habitual es añadir y activar al menos un modelo de lenguaje y/o una gramática de comandos con los métodos ​ RecognizerEngineAddLanguageModel() y RecognizerEngineAddCommandGrammar() respectivamente, ya que por defecto el sistema no reconoce absolutamente nada. Los modelos consisten en un identificador y una URI del modelo lingüístico. En INVOX Medical Dictation las URIs tienen el formato ​ grammar:dictation#​ , donde es un código de especialidad médica que será proporcionado por el administrador del servidor. Las gramáticas de comandos también contienen un identificador y una estructura de árbol de objetos ​ CommandSpec​ . Más información en el siguiente subapartado. Tener en cuenta que modelos y gramáticas comparten el mismo espacio de identificadores puesto que internamente se gestionan de la misma forma. Aunque no es habitual ni necesario, también se permite eliminar modelos y gramáticas con el mensaje ​ RecognizerEngineRemoveGrammar()​ . Sí es más común, por ser más rápido y eficiente, activar y desactivar modelos y gramáticas según lo requiera el caso de uso de la aplicación. Para ello, se proporcionan estos procedimientos: ● RecognizerEngineIsGrammarActive()​ pregunta por el estado de un modelo o gramática. ● RecognizerEngineActivateGrammars() y ​ RecognizerEngineDeactivateGrammars()​ , para activar o desactivar uno o más modelos/gramáticas. Un objeto lingüístico desactivado deja de producir eventos de reconocimiento de voz. ● RecognizerEngineResetGrammarsState() es una manera eficiente de cambiar temporalmente el contexto de dictado. Este procedimiento desactiva todos los modelos y gramáticas existentes y devuelve su estado original para poder restaurarlo posteriormente.  ● RecognizerEngineGetGrammarsState() devuelve el estado de todos los modelos y gramáticas existentes, pero no lo altera. ● RecognizerEngineSetGrammarsState() recibe como parámetro un estado completo de modelos y gramáticas y lo aplica, es decir, sirve para restaurar un estado obtenido con RecognizerEngineResetGrammarsState()​ o​ RecognizerEngineGetGrammarsState()​ .    Mientras se permanece en modo ​ Motor de Dictado​ , se puede invocar todas las veces que sea necesario los métodos ​ RecognizerEnginePlay()​ y​ RecognizerEnginePause()​ . Eso sí, cuando el reconocedor está en marcha es muy importante proporcionar sonido al sistema de manera continua y constante a través de un ​ AudioSource o con el mensaje asíncrono SendAudioArray()​ . Todo esto se explica en detalle más adelante porque depende del medio de integración concreto que se esté utilizando. Durante el procesamiento de sonido, el reconocedor irá lanzando diferentes tipos de eventos según vaya identificando fragmentos de voz, normalmente cada vez que el usuario realiza una mínima 7

INVOX Medical Dictation Manual del SDK

pausa (aunque sólo sea para tomar aire): ● DictationEvent​ , pueden indicar tres cosas distintas: ○ PartialDictationEvent​ : hipótesis de reconocimiento parciales, es decir, que todavía no se sabe si se van a aceptar o rechazar y que pueden cambiar sustancialmente conforme el usuario complete la frase. ○ AcceptedDictationEvent​ : hipótesis de reconocimiento aceptadas, que confirman lo que el usuario ha dicho y es lo que definitivamente debe transcribirse. También puede tratarse del texto de una macro. ○ RejectedDictationEvent​ : hipótesis de reconocimiento rechazadas, indican que lo dicho por el usuario es confuso, tiene un score muy bajo y, por lo tanto, debe descartarse. ● CommandEvent​ , cuando el usuario pronuncia una frase definida dentro de una gramática de comandos. Contiene información binaria serializada que de momento sólo es compatible con clientes escritos en el Framework .NET 4. Otros procedimientos de utilidad son: ● RecognizerEngineGetRecognitionDetail()​ , para obtener una lista ordenada por confianza descendente de todas las hipótesis de dictado que el reconocedor ha detectado, siendo la primera de ellas la que se ha aceptado y el resto otras alternativas posibles. ● RecognizerEngineGetMaxAlternates() y ​ RecognizerEngineSetMaxAlternates()​ , para cambiar el número máximo de hipótesis alternativas. Puede ser 0 si no se quieren calcular otras alternativas. ● RecognizerEngineFlush()​ , que puede llamarse cuando se inicia y detiene el dictado para limpiar los buffers internos. ● RecognizerEngineSetFeedbackSuppression()​ , útil si se utiliza un micrófono con altavoz que emite pitidos al iniciar el dictado. ● RecognizerEngineEmulateRecognition()​ , que permite emular un texto como si lo hubiera dictado el usuario. En último lugar, el procedimiento ​ RecognizerEngineStop()finaliza el reconocimiento de voz, libera los recursos y sale del modo ​ Motor de Dictado​ para volver al estado ​ Conectada​ .

Construcción de gramáticas de comandos Una gramática de comandos queda definida por un objeto ​ CommandSpecque es en sí mismo un árbol de objetos ​ CommandSpec​ según el patrón de diseño ​ Composite​ . En el siguiente diagrama de clases UML se ven los tipos de nodos que puede contener el árbol:

Estas composiciones de objetos en forma de árbol se pueden encontrar en las definiciones sintácticas de prácticamente todos los lenguajes estructurados. Es muy habitual que se representen con diagramas sintácticos (también llamados diagramas de ferrocarril) y documentos BNF (Backus-Naur Form). 8

INVOX Medical Dictation Manual del SDK

Por ejemplo, la siguiente definición gramatical en formato BNF: Reservar vuelo para (Madrid | Barcelona) [Gracias]  Se representa con el siguiente diagrama sintáctico:

Y se corresponde con la siguiente estructura de objetos ​ CommandSpec​ (en formato JSON): { "Sequence": [  { "Text": "Reservar vuelo para" },  { "Options": [  { "Text": "Madrid",    "Semantic": [ "DESTINO": "MAD" ]  },  { "Text": "Barcelona"    "Semantic": [ "DESTINO": "BCN" ]  }    ]  }  { "Element":  { "Text": "Gracias" },    "Min": 0,    "Max": 1  }    ]  }  Es decir, es una secuencia de: 1. Un texto simple. 2. Dos opciones de texto simple. 3. Un texto opcional, es decir, un texto que puede repetirse 0 o 1 vez. Además, INVOX Medical Dictation permite asociar información semántica a cada nodo de la gramática. Cuando el usuario pronuncia una frase que contiene un nodo con semántica, el resultado del reconocimiento incluirá ese valor semántico. En el ejemplo anterior, los nodos de texto “Madrid” y “Barcelona” contienen respectivamente los valores semánticos “MAD” y “BCN”. Si el usuario dice “reservar vuelo para Madrid”, la semántica del resultado de reconocimiento contendrá la tupla (“DESTINO”, “MAD”). Para construir estas estructuras gramaticales en .NET y JavaScript, el API de INVOX Medical Dictation ofrece el servicio ​ CommandSpecBuilder de ​ RecognizerEngine​ , basado en el patrón de diseño ​ Builder​ . El método ​ BuildText()permite construir nodos de texto simple ​ TextCommandSpec​ , mientras que el resto de métodos ​ Build...() van creando estructuras gramaticales más complejas a partir de otros objetos ​ CommandSpec​ . El último objeto ​ CommandSpecconstruido es el que recursivamente incluye al resto de objetos, es decir, el nodo raíz de la gramática y el que debe adjuntarse como parte de la ​ CommandGrammar​ . En el ejemplo anterior, el nodo ​ SequenceCommandSpec​ es la raíz de la gramática. 9

INVOX Medical Dictation Manual del SDK

2.3. Modo entrenamiento Desde el estado ​ Conectada se puede pasar al modo ​ Entrenamiento llamando al procedimiento TrainerStart()​ . Antes de poner en marcha el proceso de entrenamiento, el cliente debe llamar a TrainerSetTrainingSentences()para establecer la secuencia de frases de entrenamiento que el usuario debe leer para ajustar su perfil de voz. El SDK incluye un conjunto de frases recomendadas en el fichero ​ frasesEntrenamiento.xml​ . A partir de aquí el funcionamiento es similar al del dictado. Con ​ TrainerPlay() el reconocedor comenzará a procesar sonido, que debe ser enviado por el cliente a través de un ​ AudioSource o con el mensaje asíncrono ​ SendAudioArray() de manera continua y constante. Es posible, aunque no práctico, pausar el entrenamiento con ​ TrainerPause() y más adelante volver a reanudarlo por donde se quedó. Durante la pausa no es necesario enviar sonido al servidor. Cada vez que el usuario lea correctamente una frase de ejemplo, el servidor lanzará un evento TrainingSentenceEvent​ indicando cuál es la siguiente frase que debe ser leída. Cuando se complete el entrenamiento o si se desea cancelarlo, el cliente debe llamar a TrainerStop()​ , que llevará la sesión al estado ​ Conectada​ . Internamente, el sistema actualizará el perfil de voz del usuario para mejorar la calidad del reconocimiento. Tener en cuenta que el reconocedor también aprende y ajusta el perfil de voz mientras el usuario está dictando normalmente, así que el entrenamiento sólo es útil cuando el usuario utiliza el reconocimiento de voz por primera vez.

2.4. Modo dictado Para activar el modo ​ Dictado​ , el cliente debe llamar al procedimiento ​ RecognizerStart()en una sesión en estado ​ Conectada​ . El sistema está siempre escuchando cuando está activo el dictado de alto nivel, así que el cliente debe proporcionar sonido constantemente con un ​ AudioSource​ o el mensaje ​ SendAudioArray()​ . Lo que el sistema interpreta en cada momento depende del ámbito o contexto de reconocimiento actual, llamado ​ DictationScope​ . El cliente es el responsable de fijar el ámbito que requiera en cada momento mediante el procedimiento ​ RecognizerSetScope()​ . Las llamadas a este procedimiento provocarán el disparo del evento ​ CurrentScopeEvent​ . Al igual que ocurre con el modo ​ Motor de Dictado básico, el cliente recibirá los eventos de voz DictationEventy ​ CommandEvent(enriquecido con datos de alto nivel) en los ámbitos de dictado habituales (ver tabla más adelante). El el ​ DictationScope ​ RUNNING el usuario podrá invocar macros que se notificarán como DictationEvent​ (si es de texto) o ​ KeyboardEvent​ (si es de teclado). Si el dictado está en el ​ DictationScope ​ CORRECTION​ , el cliente deberá procesar los eventos NewCorrectionEvent​ y​ EndCorrectionEvent​ . En el ​ DictationScope​ INSTANCE_SELECTION​ ​ , el cliente recibirá un ​ InstanceSelectionEvent​ . Y en el ​ DictationScope​ PHONETIC_TRANSCRIPTION​ ​ , el sistema lanzará un ​ PhoneticEvent​ . Para salir del modo ​ Dictado​ se debe llamar al procedimiento ​ RecognizerStop()​ .

Ámbitos de dictado 10

INVOX Medical Dictation Manual del SDK

Cada ámbito de dictado está pensado para ser utilizado en una situación determinada:

● NONE 

●

Ámbito inicial en el que no se reconoce nada, así que no se producirá ningún evento relacionado con la voz. Este ámbito es un atajo para utilizar los servicios de gestión del diccionario y las macros sin necesidad de cerrar el modo ​ Dictado​ y volver al estado ​ Conectada​ . CUSTOM Una aplicación puede utilizar este ámbito para gestionar sus propias gramáticas de bajo nivel como si estuviera en el modo ​ Motor de dictado​ .

● PAUSED  El usuario no está dictando en este momento, pero puede iniciar el dictado con la voz. Normalmente, se establecerá este ámbito justo después de llamar a ​ RecognizerStart()​ .

● RUNNING  El usuario está dictando y se está transcribiendo texto. También se pueden invocar comandos relacionados con la composición de documentos y macros. Este es el uso normal por parte del usuario.

● CORRECTION  El usuario debe aceptar una de las alternativas de corrección, cancelar la corrección o decir nuevas alternativas. Los subapartados siguientes contienen más detalles.

● INSTANCE_SELECTION  El usuario ha invocado un comando “con parte derecha” que actúa sobre una o varias palabras y hay varias instancias alternativas, así que debe seleccionar una de ellas con la voz. Más información en el siguiente subapartado.

● PHONETIC_TRANSCRIPTION 

●

El usuario debe pronunciar una palabra para extraer su transcripción fonética. Este ámbito debe activarse cuando el usuario desea registrar la transcripción fonética de una palabra del diccionario (durante la gestión del diccionario). Es decir, la transcripción incluida en el ​ PhoneticEventes el valor que debe asignarse a la propiedad ​ Symbol de la ​ Pronunciation del objeto ​ Word dado como parámetro de los procedimientos ​ DictionaryAddWord()​ y​ DictionaryReplaceWord()​ . SPELLING Este modo está indicado para que el usuario pueda dictar secuencias de siglas o palabras que no existen en el modelo ni en los diccionarios. El sistema sólo acepta dígitos entre el 0 y el 9, signos de puntuación y letras pronunciadas como es habitual o mediante las palabras clave del alfabeto español por palabras. También se aceptan los comandos para desactivar el deletreo, detener el dictado, tabulación, deshacer y rehacer.

11

INVOX Medical Dictation Manual del SDK

En la tabla siguiente aparecen los eventos lanzados en cada ámbito: Instance  Dictation Command Keyboard  NewCorrection EndCorrection Phonetic  Selection  Event  Event  Event  Event  Event  Event  Event 

  NONE   

 

 

 

 

 

 

 

CUSTOM   

 

 

 

 

 

 

 

PAUSED   

 

 

 

 

 

 

 

RUNNING   

 

 

 

 

 

 

 

INSTANCE_    SELECTION 

 

 

 

 

 

 

CORRECTION     

 

 

 

 

 

 

PHONETIC_    TRANSCRIPTION 

 

 

 

 

 

 

SPELLING     

 

 

 

 

 

 

Tipos de comandos Independientemente del ámbito, el sistema distingue dos tipos de comandos: simples y con parte derecha.

Comandos simples Son los que están compuestos por una o más secuencias de invocación fijas, es decir, sin parámetros. Ejemplos de estos comandos son “iniciar dictado”, “comenzar dictado”, “ir al final del documento” y “activar mayúsculas”.

Comandos con parte derecha Estos comandos tienen dos partes: una o más secuencias de invocación fijas (parte izquierda) y un parámetro consistente en una o más palabras que aparecen en el documento (parte derecha). Por ejemplo, “corregir ​ buenas tartas​ ”, “todo mayúsculas ​ nota importante​ ” y “seleccionar introducción​ ” (las partes derechas se muestran en cursiva). A continuación se explica el modo en que el API resuelve dos cuestiones con este tipo de comandos:

1. Cómo hacer que INVOX conozca el texto que aparece en el editor del documento. 2. Cómo seleccionar la secuencia de palabras sobre la que actuar cuando la parte derecha existe más de una vez en el documento.

Texto visible en el editor del documento En los comandos con parte derecha, el texto que sigue a las palabras fijas que invocan el comando obviamente depende del contenido del documento que se está transcribiendo. INVOX Medical Dictation no tiene acceso directo al documento, así que es responsabilidad del cliente extraer el texto actualmente visible en la ventana de edición del documento y enviarlo al servidor con el procedimiento ​ RecognizerSetVisibleText()​ . 12

INVOX Medical Dictation Manual del SDK

Como el texto cambia constantemente, el cliente debe llamar a este método cada 2 segundos. Obviamente, el cliente es libre de implementar los mecanismos que considere necesarios para optimizar este proceso, entre los que cabe destacar:

1. Detección de cuándo ha cambiado realmente el texto del documento (basado en eventos o polling). De esta forma, se evita llamar a ​ RecognizerSetVisibleText()si el texto no ha sido modificado desde la última vez.

2. Extracción de la ventana de texto visible únicamente en vez de todo el documento. El usuario sólo va a invocar comandos con parte derecha referidos al texto que está visible en pantalla. Esto no sólo optimiza el rendimiento del sistema, sino que evita confusión y problemas de usabilidad.

Selección de la instancia de parte derecha Cuando se notifica la invocación de un comando con parte derecha, el cliente debe identificar la posición de las palabras afectadas en el editor del documento. Si sólo hay una aparición de dichas palabras, el cliente puede ejecutar el comando directamente porque no hay ambigüedad. Pero si hay más de una aparición, el cliente debe preguntar al usuario sobre cuál de las instancias se desea ejecutar el comando. INVOX Medical Dictation ofrece el ​ DictationScope​ INSTANCE_SELECTIONpara que el usuario pueda seleccionar el número de instancia directamente con la voz (o cancelar la selección). En este ámbito el sistema enviará un ​ InstanceSelectionEventcuando el usuario diga un número (a partir de 1) o la palabra “cancelar”. El cliente debe proporcionar al usuario una ayuda visual (tooltip, etiqueta o similar) para que sea sencillo y rápido saber qué número corresponde a cada instancia. Obviamente, tras la selección de la instancia, el propio cliente debe regresar al ​ DictationScope RUNNING​ .

Comando “corregir” Este es el caso más complejo de comando con parte derecha. La manera más fácil de entender su funcionamiento es siguiendo el ejemplo al final de este capítulo. Tras la selección de instancia (si fuera necesaria), aquí existe un paso extra que requiere la activación del ​ DictationScope​ CORRECTIONpara la selección de la alternativa correcta o, si no está entre las alternativas ofrecidas, el dictado de la nueva corrección. Pero incluso antes del cambio de ​ DictationScope​ , el cliente debe recuperar la lista inicial de interpretaciones alternativas disponibles (posibles correcciones) con el método RecognizerGetRecognitionDetail()​ . Dentro del ​ DictationScope​ CORRECTION​ ​ se podrán recibir dos tipos de eventos:

● NewCorrectionEvent​ cada vez que el usuario pronuncie una nueva corrección. La propiedad Alternates contiene una lista de ​ ​ RecognitionHypothesis con las correcciones propuestas por el sistema.

● EndCorrectionEvent​ si el usuario acepta una de las alternativas o cancela el proceso. El cliente reemplazará el texto a corregir (si el usuario ha aceptado una alternativa) y, en cualquier caso, volverá al ​ DictationScope​ RUNNING​ ​ .

Comando “ir a marcador” 13

INVOX Medical Dictation Manual del SDK

Se trata del único caso de comando con parte derecha en el que el texto pronunciado por el usuario no es una secuencia de palabras visible en la ventana de edición del documento, sino un identificador de un marcador o acceso directo para moverse por el documento. Por comodidad, las invocaciones de este comando se notifican como cualquier otro comando en el que la parte derecha es simplemente el identificador del marcador. Los nombres de los marcadores deben pasarse a INVOX Medical Dictation a través del método RecognizerSetBookmarks()​ .

Ejemplo de uso A continuación se muestra un diagrama de secuencia con un ejemplo de comando “corregir”. La secuencia de pasos es:

1. 2. 3. 4.

El usuario dicta “esto es un ejemplo de frase breve”. El sistema entiende “fase” en vez de “frase” y así se escribe en el documento. El usuario observa el error y pide “corregir fase”. Existen dos instancias de esa palabra en la ventana del documento, así que el cliente debe etiquetarlas con un número (1 y 2).

5. El usuario debe decir cuál de ellas es la que está mal, “dos” en este caso. 6. El cliente abre una ventana con la lista de palabras alternativas, entre las que aparecen cosas como “base”, “pase” y “parase”, pero supongamos que casualmente no está “frase”.

7. El usuario dice “frase”. 8. Ahora sí, la primera opción de la lista de alternativas es la palabra correcta. 9. El usuario acepta la primera opción diciendo “aceptar uno”. 10. El cliente reemplaza la instancia 2 de la palabra “fase” con “frase” y vuelve al dictado.

14

INVOX Medical Dictation Manual del SDK

15

INVOX Medical Dictation Manual del SDK

3. Integración Medios disponibles INVOX Medical Dictation ofrece por ahora tres medios de integración con aplicaciones de terceros: ● A través de un canal seguro WebSocket + JSON, apto para integraciones de más bajo nivel con entornos de ejecución no soportados de otra manera. ● Una librería JavaScript + Flash para clientes web, que internamente utiliza el canal WebSocket + JSON. ● Ensamblados para el Framework .NET 4 y superiores que pueden o no utilizar el canal WebSocket + JSON según el cliente sea ligero o pesado 2 . En cualquier caso, Vócali se reserva el derecho de añadir nuevos medios de integración con otros entornos, así como ampliar o modificar los medios actuales.

Versiones Los ejecutables y librerías entregados como parte del SDK son etiquetados con un valor de versión de 4 dígitos. Los dos últimos dígitos se incrementan cuando los cambios de implementación no implican la ruptura de ninguno de los contratos documentados en el API de INVOX Medical Dictation. Sin embargo, cuando se realice alguna ampliación o modificación de las interfaces existentes, sí se producirá un incremento en alguno de los dos primeros números (según el impacto del cambio).

Despliegue Aunque la instalación y mantenimiento de un despliegue de INVOX Medical Dictation cae fuera del ámbito de este documento, es importante tener claro cómo se despliegan los componentes del sistema.

Básicamente, se distinguen dos escenarios de despliegue: ● Cliente pesado, con reconocimiento de voz local. Sólo disponible si el cliente es una aplicación nativa de Windows 7 o superior. ● Cliente ligero, con reconocimiento de voz remoto. Para el resto de casos que no cumplen el requisito anterior. En cualquier escenario, INVOX gestiona toda la información a través de un servidor web ASP.NET con base de datos SQL Server. Los clientes pesados se conectan directamente a este servidor para recuperar y enviar información relacionada con la especialidad médica, el usuario, su perfil de voz, etc. Por otro lado, los clientes ligeros requieren de un servidor de dictado (INVOX Medical Dictation Server) que no sólo haga de intermediario, sino que además se encargue del reconocimiento de Debido a los requisitos de instalación del cliente pesado, de momento no se distribuye con el SDK estándar. 2

16

INVOX Medical Dictation Manual del SDK

voz. Es decir, los clientes ligeros se conectan al servidor de dictado mediante WebSocket y el servidor de dictado se conecta al servidor web.

3.1. Comunicación WebSocket + JSON Este es el medio de integración de más bajo nivel, así que sólo deberá utilizarse cuando no se disponga de una librería para el entorno de la aplicación cliente. El servidor de INVOX Medical Dictation sólo admite conexiones WebSocket seguras (WSS) sobre el puerto 8443. Las versiones del protocolo soportadas son: hixie-76/hybi-00, hybi-10 y rfc6455. La serialización JSON se realiza con la librería ​ NewtonSoft JSON.NET por su flexibilidad y compatibilidad.

Tipos de mensajes Por comodidad, facilidad de uso y comprensión, el protocolo ha sido especificado en forma de procedimientos y eventos en los que se intercambian tipos de datos estructurados. A continuación se explica el modo en que estas llamadas de alto nivel deben traducirse a mensajes WebSocket + JSON. Tipo de mensaje

Formato

Llamada a procedimiento asíncrono

NOMBRE PARÁMETRO

Llamada sin valor de retorno; el cliente no espera a que el sistema ejecute la orden enviada (send & forget).

Llamada a procedimiento síncrono Llamada tradicional en la que el cliente debe esperar a que el sistema devuelva un valor de retorno (RPC).

Retorno de procedimiento síncrono Valor de retorno devuelto como resultado de una llamada a procedimiento síncrono. Implica que el sistema ha terminado de ejecutar el procedimiento invocado.

Evento asíncrono Notificación del sistema recibida por el cliente (evento push).

NOMBRE­TOKEN PARÁMETRO

NOMBRE­TOKEN RESULTADO

NOMBRE INFORMACIÓN

Los elementos que componen los mensajes y aparecen indicados en el formato son: ● NOMBRE  Nombre del procedimiento o evento, tal cual aparecen documentados. ● TOKEN  Un valor numérico de 4 cifras generado y controlado por el cliente para asegurar la correspondencia entre una llamada síncrona y su valor de retorno. Puede ser aleatorio o secuencial. Lo único que hace el sistema con este número es incluirlo como parte del mensaje de respuesta en una llamada síncrona. ● PARÁMETRO  Las llamadas a procedimientos sólo pueden tener un parámetro en formato JSON. En el apartado siguiente se especifican las características de la serialización JSON. ● RESULTADO  Valor en formato JSON devuelto tras la ejecución de un procedimiento síncrono. Ver el apartado siguiente para los detalles sobre la serialización JSON. 17

INVOX Medical Dictation Manual del SDK

●

INFORMACIÓN Información sobre el evento que se ha notificado al cliente en formato JSON.

Serialización JSON La serialización JSON siempre espera la representación más básica para el dato a transmitir. Tipo de dato

Ejemplo

Booleano

true 

Entero

1 

Flotante

1.5 

Cadena

"Anatomía Patológica" 

Array o lista

["ComandosControl","ComandosExtra"] 

Diccionario, mapa o array asociativo

{"ComandosSimples":false,   "Instancias":false,   "ComandosControl":false,   "Dictado":true} 

Objeto simple

{"State":3,   "Error":0,   "Value":true} 

Objeto complejo

{"State":1,   "ExceptionType":0,   "User":    {"Login":"prueba_ap",     "Name":"Prueba AP",     "EMail":"[email protected]",     "Specialty":      {"Id":"1",       "Name":"Anatomía Patológica"}},   "Offline":false,   "SessionKey":"bdbb093f­d5a0­4d84­9f49­8d16b73a6d74",   "RequiredCodecType":0} 

18

INVOX Medical Dictation Manual del SDK

Ejemplos de mensajes A continuación se incluyen una serie de ejemplos de mensajes de diversos tipos. El símbolo > representa una llamada de cliente a servidor y < una respuesta de servidor al cliente.

>

Login­3079 {"Login":"prueba_ap","Password":"prueba","Remember":true,"Force":true} 




RecognizerEngineActivateGrammars­1557 ["FRASE_MICRO"] 




RecognizerEngineGetMaxAlternates­7684 false 




RecognizerEngineSetGrammarsState­9235  {"ComandosSimples":false,"Instancias":false,"ComandosControl":false,"Dictado":true} 




DictionaryReplaceWord­8883  [{"Text":"Palabra",    "Pronunciations":[],    "Shared":false},   {"Text":"frutas",    "Pronunciations":[{"Symbol":"f r u t a s","POS":0}],    "Shared":true}] 




RecognizerGetRecognitionDetail­9329 "el" 

19

INVOX Medical Dictation Manual del SDK




DictionaryGetWords­6119 false 




SendAudioArray  {"Data":["KdV...Cc=","Kcl...s4c=","Kdh...JCc=","Kdh...4Bc=","Kdh...fxc=","LyV...4Bc=","K/v. ..Mwc=","Kdh...QEc=","L21...0Cc=","LuA...rc="],"CodecType":1}