Comandos Iara (Comandos Iara)

Los comandos permiten utilizar el reconocimiento de voz de Iara como una forma de interacción del usuario con su aplicación. A través de comandos, un usuario puede solicitar, usando la voz, que la aplicación guarde el contenido de algún trabajo, por ejemplo.

Funcionamiento básico

Los comandos se componen de dos partes principales: unastring de activacióny unafunción de callback, invocada cuando la string de activación se reconoce en la transcripción actual. Se pueden añadir varios comandos y ellos no afectan el rendimiento del reconocimiento de voz.

Antes de usar cualquier comando, es importante tener en cuenta que la string de activación debe estar compuesta necesariamente por palabras existentes en el diccionario de lenguaje de Iara. Por esta razón, si se crea el comando hola cómo estas, esto no garantiza que se disparará.

IMPORTANTE:los comandos deben estar compuestos por palabras existentes en el diccionario de lenguaje de Iara.

El comando conductos biliares hepáticos, por ejemplo, será reconocido, ya que cada una de las tres palabras utilizadas para componer la string de activación existen en el diccionario de lenguaje de Iara.

Un comando puede ser compuesto por una o varias palabras (no hay límite real). Sin embargo, se recomienda que los comandos no tengan más de 3 o 4 palabras, para garantizar una buena UX y una alta tasa de reconocimiento de comandos.

Utilización básica

Comandos se agregan a través decommands.add()en el reconocedor:

var recognition = new IaraSpeechRecognition();
recognition.commands.add('string activación', function callback() {
    console.log('Comando ejecutado');
});
recognition.init({
    // ...
}).done(function(e) {
    // ...
}).fail(function(e) {
    // ...
});

PISTA:Como buena práctica de UX, se recomienda que los comandos comiencen con la palabra iara seguida de la acción deseada. Por ejemplo, iara texto podría usarse para crear un nuevo texto, mientras que iara informe crearía un nuevo informe.

Los comandos se pueden agregar en cualquier momento durante el ciclo de vida de su aplicación. De esa manera, se pueden agregar antes o después de que comience el reconocedor:

var recognition = new IaraSpeechRecognition();
// Comando agregado antes de la inicialización del reconocedor recognition.commands.add('iara texto', function callback() {
    console.log('Comando ejecutado:iara texto');});

recognition.init({
    // ...
}).done(function(e) {
    // Comando agregado después de la inicialización del reconocedor 
recognition.commands.add('iara informe', function callback() {
console.log('Comando ejecutado: iara informe');
    });
}).fail(function(e) {
    // ...
});

// Comando agregado durante el runtime de la aplicación.
recognition.commands.add('iara hígado', function callback() {
    console.log('Comando ejecutado: iara hígado');
});

Los comandos también se pueden eliminar en cualquier momento a través de commands.remove().

Parámetros de contextualización

Los comandos se pueden contextualizar fácilmente a través de parámetros. La función de callback de un comando recibirá estos parámetros.

Parámetros propios del SDK

La función de callback de un comando siempre recibirá dos parámetros proporcionados por el propio SDK: detail y command, en ese orden.

El siguiente ejemplo ilustra los parámetros recibidos por el callback:

recognition.commands.add('iara texto', function(detail, command) {
    // El comando "iara texto" fue reconocido. El parámetro `detail` 
// contiene los detalles del audio reconocido, `command` contiene el // comando iara reconocido en esta callback ("iara text", en este caso).
    console.log('Iara comando: ', detail, command);
});

El parámetro detail de la callback contiene los detalles del audio reconocido, que es exactamente el mismo objeto que la propiedad event.detail de un reconocimiento, como se ilustra en el siguiente ejemplo:

var recognition = new IaraSpeechRecognition();

recognition.init({
    // (...)
}).done(function(e) {
    recognition.onresult = function(event) {
        console.log('Detalles del reconocimiento: ', event.detail);
        //                                          --------^^^
        // La propriedad `detail` del `event.detail` anterior es el mismo objeto pasado como
        // primer parámetro a la callback de un comando activado.
    };
});

A través del parámetro detail, la función de callback del comando tiene acceso al contenido de la transcripción actual, que se puede utilizar en el propio comando, por ejemplo.

El parámetro command, el 2º parámetro recibido por el callback, contiene la string de activación que hizo que se invocara esta callback. Es decir, el comando reconocido que provocó la invocación. En el primer ejemplo de esta sección, se agregó el comando "iara texto", por lo que el parámetro command de la callback contendrá la string"iara texto".

PISTA: a través del parámetro command de la callback de comandos, la aplicación puede usar una sola función para manejar todos los comandos, si esto es de interés. Basta con que se inspeccione el parámetro command para definir qué comando se activó realmente.

Parámetro adicional para la función de callback

Cuando se agrega un comando a través de commands.add(), se puede proporcionar algun dato que se pasará, a través de un parámetro, a la callback de ese comando. El dato que se pasa a la función de callback puede ser de cualquier tipo, objeto, string, entero, etc.

El valor es informado como el tercer parámetro de commands.add(), y estará disponible para la callback del comando, también como el tercer parámetro:

función callback(detalle, comando, parámetro) {
    // El parámetro `param` contendrá la string "hola mundo".
    console.log('Comando ' + comando + ' invocado con parámetro ' + param); }
var recognition = new IaraSpeechRecognition();
// Agrega el comando `iara texto` con el dato extra "hola mundo"
recognition.commands.add('iara texto', callback, null, ['hola mundo']);
recognition.init({
    // ...
}).done(function(e) {
    // ..
}).fail(function(e) {
    // ...
});

Consulte el ejemplo de código iara-commands para obtener más información sobre los comandos.

Utilización avanzada

Los comandos pueden tener su comportamiento ajustado a las necesidades muy específicas de cada aplicación. Esta personalización se realiza a través de un objeto de configuración del comando. El objeto de configuración se pasa como el 4º parámetro de commands.add():

función callback(detalle, comando, parámetro) {
    // ...
}

// Objeto de configuración
var cmdConfig = {
    // key: value,
    // key2: value2,
    // ...
};

var recognition = new IaraSpeechRecognition();
// Agrega el comando `iara text` con el dato extra `hola mundo` // y configuración adicional definida por `cmdConfig`.
recognition.commands.add('iara texto', callback, null, ['hola mundo'],  cmdConfig);

El objeto de configuración puede contener los siguientes campos:

Campo	Tipo	Valor por defecto	Descripción
`transcripción`	`bool`	`verdadero`	Mantener string de activación en `detail.transcript`?
`richTranscript`	`bool`	`falso`	Mantener string de activación en `detail.richTranscript`?
`replaceValue`	`string`	`''`	Qué poner en lugar de la string de activación del comando si ella se elimina de las transcripciones.
`replaceFunction`	`función`	`nulo`	Función que se usará para reemplazar la string de activación por`replaceValue` en las transcripciones.
`resultFunction`	`función`	`nulo`	Función que será llamada para cambiar el resultado del reconocimiento.
`searchRichTranscript`	`bool`	`falso`	Busque la cadena de activación en `detail.richTranscript`?

Control sobre`transcript` e `richTranscript`

El reconocimiento de voz de Iara proporcionará la transcripción de cualquier audio a través de las propiedades event.detail.transcript e event.detail.richTranscript. Si su aplicación utiliza comandos, la string de activación también aparecerá en la transcripción.

De forma predeterminada, la string de activación de cualquier comando se mantiene en transcripción y se elimina de richTranscript. Esto se puede personalizar a través de las configuracionestranscript e richTranscript. Estos campos indican si la cadena de activación se debe mantener en event.detail.transcript y/o event.detail.richTranscript, respectivamente. De esta forma, puede controlar si los eventos de reconocimiento de audio contendrán o no una transcripción del comando en cuestión.

En el siguiente ejemplo, la string de activación del comando se eliminará tanto de transcript como de richTranscript cuando se reconozca el comando:

function callback(detail, command, param) {
    console.log('Comando ' + command + ' invocado con parámetro ' + param);
}
/ Objeto de configuración del comando
var cmdConfig = {
    transcript: false,     // mantener en la transcripción? No, el texto del comando, i.e. "iara alerta", debe eliminarse de la transcripción.
    richTranscript: false  // Mantener en richTranscript? No, el texto del comando, i.e. "iara alerta", debe eliminarse de richTranscript.
};

var recognition = new IaraSpeechRecognition();

// Agregue el comando `iara alerta` con el dato adicional de `hola mundo` recognition.commands.add('iara alerta', callback, null, ['hola mundo'], cmdConfig);

Valor de reemplazo para `transcript` y `richTranscript`

Las propiedades de configuración transcript y richTranscript controlan si la string de activación del comando debe mantenerse o no en las transcripciones. Si se va a eliminar la string de activación del comando, puede definir qué string se utilizará para ocupar su lugar. Esto es controlado por la propiedad de configuración replaceValue.

De forma predeterminada, replaceValue tiene el valor '' (string vacía), lo que significa que la cadena de activación del comando se reemplaza por una string vacía. Sin embargo, se puede utilizar cualquier string. En el siguiente ejemplo, la string de activación del comando se reemplaza por @TOMO en las propiedades transcript y richTranscript:

función callback(detalle, comando, parámetro) {
    //...
}

var cmdConfigReplace = {
    transcript: false,       // Mantener en la transcripción? No, reemplazar con el contenido de `replaceValue`.
    richTranscript: false  // Mantener en richTranscript? No, reemplazar con el contenido de `replaceValue`.
    replaceValue: '@TOMO',   // string que se usará para reemplazar la string de activación.
};
recognition.commands.add('iara tomografía', callback, null, ['hola mundo'], cmdConfigReplace);
recognition.init({
    // (...)
}).done(function(e) {
    // Suponiendo que el usuario dijo "conductos biliares iara tomografía":
tomografia":
    recognition.onresult = function(event) {
        console.log(event.detail.transcript); // conductos biliares @TOMO
        console.log(event.detail.richTranscript); // <div>conductos biliares @TOMO</div>
    };
});

Función personalizada de reemplazo para`transcript` y `richTranscript`

Si su aplicación necesita aún más control sobre el reemplazo de una string de activación de comando además de cambiarla porreplaceValue, puede implementar su propia función de reemplazo e informarla a través de replaceFuncion.

La firma de replaceFunction es la siguiente:

function(haystack, needle, replaceValue, prop) -> String

donde haystackes la string que contiene la transcripción actual del reconocimiento, needle es la string de activación del comando, replaceValuees la string informada en el objeto de configuración del comando, y propes una string con el nombre de la propiedad que se está manejando, i.ei.e "transcript" o "richTranscript".

La función replaceFunction debe, obligatoriamente, devolver una string que se asignará a la transcripción(transcript o richTranscript) como resultado del reemplazo de la string de activación del comando.

En el siguiente ejemplo, se agrega el comando iara control. Cuando se activa, la string de activación "iara control" será reemplazada por la string"_CONTROLE:transcript" en la propiedad transcript, y por "_CONTROLE:richTranscript" en la propiedad richTranscript:

función callback(detalle, comando, parámetro) {
    //...
}

var cmdConfigReplace = {
    transcript: false,       // Mantener en la transcripción? No, reemplazar.
    richTranscript: false,   // Mantener en la richTranscript? No, reemplazar.

    replaceFunction: function(haystack, needle, replaceValue, prop) {
        var text = (haystack || '') + '';
        var regex = new RegExp(needle, 'gi');
        replaceValue = '_CONTROL:' + prop;

        return text.replace(regex, replaceValue);
    }
        return text.replace(regex, replaceValue);
    }
};

recognition.commands.add('iara controle', callback, null, ['hola mundo'], cmdConfigFunc);

recognition.init({
    // (...)
}).done(function(e) {
    // Asumiendo que el usuario dijo "conductos biliares iara control":
    recognition.onresult = function(event) {
        console.log(event.detail.transcript); // conductos biliares _CONTROL:transcript
        console.log(event.detail.richTranscript); // <div>conductosbiliares _CONTROL:richTranscript</div>
    };
});

Cambio de resultado de una transcripción

Si la aplicación necesita, por alguna razón, cambiar cualquier resultado de reconocimiento cuando se ejecuta un comando, esto se puede hacer a través de la propiedad de configuraciónresultFunction.

Similar a replaceFunction, la función especificada en resultFunction será llamada cuando se ejecute el comando, pero ella recibirá como parámetro el objeto que se propagará como evento de resultado de reconocimiento (parámetro event de recognition.onresult). La firma de replaceFunction es la siguiente:

función(Object resultEvent, String needle, Object entry) -> Void;

donde resultResult es el objeto de evento que se propagará como resultado del conocimiento, needle es la string de activación del comando y entry es un objeto que contiene las informaciónes del comando en cuestión, como string de activación, configuraciónes, etc.

Consulte el ejemplo de código iara-commands-advanced para obtener más información sobre el asunto.

Búsqueda de la string de activación en richTranscript

Si su aplicación necesita registrar un comando iara cuya string de activación es un texto en el formatorichTranscript, esto se puede hacer a través de la propiedad de configuraciónsearchRichTranscript.

Si esta propiedad tiene el valor true, la string de activación debe ser un texto en el formato richTranscript. Esto puede facilitar su uso en los casos en que la string de activación contenga elementos como siglas, vértebras, números y otros, como se ve abajo:

función callback(detalle, comando, parámetro) {
    //...
}

var cmdConfigFunc = {
    searchRichTranscript: true
};
// Si la propiedad searchRichTranscript fuera diferente de true, el comando sería:
// recognition.commands.add('iara l cinco s um', callback, null, null, cmdConfigFunc);
recognition.commands.add('iara L5-S1', callback, null, null, cmdConfigFunc);
recognition.commands.add('iara exame 2', callback, null, null, cmdConfigFunc);

recognition.commands.add('iara Modic II', callback, null, null, cmdConfigFunc);

recognition.init({
    // ...
}).done(function(e) {
    // ...
});

Utilización de Regex

Si su aplicación necesita registrar un comando de manera más flexible, puedes proporcionar una regex como string de activación. Para eso, la string de activación debe seguir el formato especificado en eldocumentación para construción de objetos RegExp con patrones de string.

Algunos consejos de uso:

Para que el regex tenga una barra invertida, debe estar precedida por otra barra invertida
Intente limitar el alcance del regex tanto como sea posible, ya que el callback del comando se llamará en la primera coincidencia con el regex

Todavía puedes usar grupos de captura en el regex proporcionado. Si se captura algún grupo, se proporcionará a el callback a través del parámetrogroups. Este parámetro es una matriz de strings, donde el primer índice es la coincidencia completa con el regex y los siguientes índices son los grupos capturados del regex. Vea un ejemplo de uso abajo:

función firstCommandCallback(detail, command, param, groups) {
    if (groups) {
        console.log('iara texto:', groups[1]);
    }
    //...
}

función secondCommandCallback(detail, command, param, groups) {
    if (groups) {
        console.log('número do exame:', groups[1]);
    }
    //...
}

// Captura cualquier palabra reconocida después de "iara texto".
// Para capturar caracteres especiales como ã, é, vea:
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Unicode_Property_Escapes
recognition.commands.add('iara texto (\\p{Letter}+)', iaraCommandCallback);
// Especifica que el comando debe compararse con el texto analizado, o sea, el rich transcript
var searchRichTranscriptConfig = {
    searchRichTranscript: true
};
// Captura cualquier secuencia de números reconocidos después de "examen iara"
recognition.commands.add('iara exame (\\d+)', secondCommandCallback, null, null, searchRichTranscriptConfig);

recognition.init({
    // ...
}).done(function(e) {
    // ...
});

Funcionamiento básico​

Utilización básica​

Parámetros de contextualización​

Parámetros propios del SDK​

Parámetro adicional para la función de callback​

Utilización avanzada​

Control sobretranscript e richTranscript​

Valor de reemplazo para transcript y richTranscript​

Función personalizada de reemplazo paratranscript y richTranscript​

Cambio de resultado de una transcripción​

Búsqueda de la string de activación en richTranscript​

Utilización de Regex​