Comandos Iara (Iara Commands)

Comandos permitem que o reconhecimento de voz da Iara seja utilizado como forma de interação do usuário com sua aplicação. Através de comandos, um usuário pode solicitar, usando a voz, que a aplicação salve o conteúdo de algum trabalho, por exemplo.

Funcionamento básico

Comandos são compostos por duas partes principais: uma string de ativação e uma função de callback, invocada quando a string de ativação é reconhecida na transcrição atual. Diversos comandos podem ser adicionados, e eles não impactam na performance de reconhecimento de voz.

Antes de utilizar qualquer comando, é importante notar que a string de ativação precisa ser composta, obrigatoriamente, por palavras existentes no dicionário de linguagem da Iara. Por essa razão, se o comando oi tudo bem for criado, isso não garante que ele será disparado.

IMPORTANTE: comandos precisam ser obrigatoriamente compostos por palavras existentes no dicionário de linguagem da Iara.

O comando vias biliares hepáticas, por exemplo, será reconhecido, visto que cada uma das três palavras utilizadas para compor a string de ativação existem no dicionário de linguagem da Iara.

Um comando pode ser composto por uma ou diversas palavras (não há um limite real). Recomenda-se, porém, que comandos não tenham mais do que 3 ou 4 palavras, para garantir uma boa UX e alta taxa de reconhecimento do comando.

Utilização básica

Comandos são adicionados através de commands.add() no reconhecedor:

var recognition = new IaraSpeechRecognition();

recognition.commands.add('string ativação', function callback() {
    console.log('Comando executado');
});

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

DICA: Como boa prática de UX, recomenda-se que comandos iniciem com a palavra iara seguida da ação desejada. Por exemplo, iara texto poderia ser utilizado para criar um texto novo, enquanto iara laudo criaria um laudo novo.

Comandos podem ser adicionados a qualquer momento durante o ciclo de vida de sua aplicação. Dessa forma, eles podem ser adicionados antes ou depois da inicialização do reconhecedor:

var recognition = new IaraSpeechRecognition();

// Comando adicionado antes da inicialização do reconhecedor
recognition.commands.add('iara texto', function callback() {
    console.log('Comando executado: iara texto');
});

recognition.init({
    // ...
}).done(function(e) {
    // Comando adicionado depois da inicialização do reconhecedor
    recognition.commands.add('iara laudo', function callback() {
        console.log('Comando executado: iara laudo');
    });
}).fail(function(e) {
    // ...
});

// Comando adicionado durante o runtime da aplicação.
recognition.commands.add('iara fígado', function callback() {
    console.log('Comando executado: iara fígado');
});

Comandos também podem ser removidos a qualquer momento através de commands.remove().

Parâmetros de contextualização

Comandos podem ser facilmente contextualizados através de parâmetros. A função de callback de um comando receberá esses parâmetros.

Parâmetros próprios do SDK

A função de callback de um comando receberá, sempre, dois parâmetros fornecidos pelo próprio SDK: detail e command, nessa ordem.

O exemplo abaixo ilustra os parâmetros recebidos pela callback:

recognition.commands.add('iara texto', function(detail, command) {
    // O comando "iara texto" foi reconhecido. O parâmetro `detail`
    // contém os detalhes do audio reconhecido, `command` contém o
    // comando iara reconhecido nessa callback ("iara texto", nesse caso).
    console.log('Iara comando: ', detail, command);
});

O parâmetro detail da callback contém os detalhes do audio reconhecido, que é exatamente o mesmo objeto da propriedade event.detail de um reconhecimento, como o ilustrado no exemplo abaixo:

var recognition = new IaraSpeechRecognition();

recognition.init({
    // (...)
}).done(function(e) {
    recognition.onresult = function(event) {
        console.log('Detalhes do reconhecimento: ', event.detail);
        //                                          --------^^^
        // A propriedade `detail` do `event.detail` acima é o mesmo objeto passado como
        // primeiro parâmetro para a callback de um comando ativado.
    };
});

Através do parâmetro detail, a função de callback do comando tem acesso ao conteúdo da transcrição atual, que pode ser utilizado no próprio comando, por exemplo.

O parâmetro command, o 2º parâmetro recebido pela callback do comando, contém a string de ativação que ocasionou a invocação dessa callback. Ou seja, o comando reconhecido que causou a invocação. No primeiro exemplo dessa seção, o comando "iara texto" foi adicionado, logo o parâmetro command da callback conterá a string "iara texto".

DICA: através do parâmetro command da callback de comandos, a aplicação pode utilizar uma única função para tratamento de todos os comandos, se isso for de interesse. Basta que o parâmetro command seja inspecionado para definir qual comando, de fato, foi disparado.

Parâmetro adicional para a função de callback

Quando um comando é adicionado via commands.add(), pode-se fornecer algum dado que será passado, via parâmetro, a para a callback daquele comando. O dado a ser passado para função de callback pode ser de qualquer tipo, objeto, string, inteiro, etc.

O valor é informado como o terceiro parâmetro do commands.add(), e estará disponível para a callback do comando também como o terceiro parâmetro:

function callback(detail, command, param) {
    // O parâmetro `param` conterá a string "olá mundo".
    console.log('Comando ' + command + ' invocado com parâmetro ' + param);
}

var recognition = new IaraSpeechRecognition();

// Adiciona o comando `iara texto` com o dado extra "olá mundo"
recognition.commands.add('iara texto', callback, null, ['olá mundo']);

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

Veja o exemplo de código iara-commands para conhecer mais sobre comandos.

Utilização avançada

Comandos podem ter seu comportamento ajustado para necessidades muito específicas de cada aplicação. Essa customização é feita através de um objeto de configuração do comando. O objeto de configuração é passado como o 4º parâmetro de commands.add():

function callback(detail, command, param) {
    // ...
}

// Objeto de configuração
var cmdConfig = {
    // key: value,
    // key2: value2,
    // ...
};

var recognition = new IaraSpeechRecognition();

// Adiciona o comando `iara texto` com o dado extra `olá mundo`
// e configuração adicional definida por `cmdConfig`.
recognition.commands.add('iara texto', callback, null, ['olá mundo'],  cmdConfig);

O objeto de configuração pode conter os seguintes campos:

Campo	Tipo	Valor default	Descrição
transcript	bool	true	Manter string de ativação no detail.transcript?
richTranscript	bool	false	Manter string de ativação no detail.richTranscript?
replaceValue	string	''	O que colocar no lugar da string de ativação do comando se ela for removida das transcrições.
replaceFunction	function	null	Função que será usada para fazer a substituição da string de ativação por replaceValue nas transcrições.
resultFunction	function	null	Função que será chamada para alterar o resultado do reconhecimento.
searchRichTranscript	bool	false	Procurar a string de ativação no detail.richTranscript?

Controle sobre transcript e richTranscript

O reconhecimento de voz da Iara disponibilizará a transcrição de qualquer audio através das propriedades event.detail.transcript e event.detail.richTranscript. Se sua aplicação estiver usando comandos, a string de ativação também aparecerá na transcrição.

Por padrão, a string de ativação de qualquer comando é mantida em transcript e removida de richTranscript. Isso pode ser customizado através das configurações transcript e richTranscript. Esses campos indicam se a string de ativação deve ser mantida em event.detail.transcript e/ou event.detail.richTranscript, respectivamente. Dessa forma, pode-se controlar se os eventos de reconhecimento de audio conterão ou não transcrição do comando em questão.

No exemplo abaixo, a string de ativação do comando será removida tanto de transcript quanto de richTranscript quando o comando for reconhecido:

function callback(detail, command, param) {
    console.log('Comando ' + command + ' invocado com parâmetro ' + param);
}

// Objeto de configuração do comando
var cmdConfig = {
    transcript: false,     // Manter no transcript? Não, o texto do comando, i.e. "iara alerta", deve ser removido do transcript.
    richTranscript: false  // Manter no richTranscript? Não, o texto do comando, i.e. "iara alerta", deve ser removido do richTranscript.
};

var recognition = new IaraSpeechRecognition();

// Adiciona o comando `iara alerta` com o dado extra `olá mundo`
recognition.commands.add('iara alerta', callback, null, ['olá mundo'], cmdConfig);

Valor de substituição para transcript e richTranscript

As propriedades de configuração transcript e richTranscript controlam se a string de ativação do comando deve ser mantida ou não nas transcrições. Se a string de ativação do comando deve ser removida, você pode definir que string que será usada para assumir o seu lugar. Isso é controlado pela propriedade de configuração replaceValue.

Por padrão, replaceValue tem o valor '' (string vazia), o que significa que a string de ativação do comando é substituída por uma string vazia. Entretanto, qualquer string pode ser usada. No exemplo abaixo, a string de ativação do comando é substituída por @TOMO nas propriedades transcript e richTranscript:

function callback(detail, command, param) {
    //...
}

var cmdConfigReplace = {
    transcript: false,       // Manter no transcript? Não, substituir pelo conteúdo de `replaceValue`.
    richTranscript: false,   // Manter no richTranscript? Não, substituir pelo contéudo de `replaceValue`.
    replaceValue: '@TOMO',   // String que será usada para substituir a string de ativação.
};
recognition.commands.add('iara tomografia', callback, null, ['olá mundo'], cmdConfigReplace);

recognition.init({
    // (...)
}).done(function(e) {
    // Assumindo que o usuário falou "vias biliares iara tomografia":
    recognition.onresult = function(event) {
        console.log(event.detail.transcript); // vias biliares @TOMO
        console.log(event.detail.richTranscript); // <div>vias biliares @TOMO</div>
    };
});

Função customizada de substituição para transcript e richTranscript

Se sua aplicação precisa de ainda mais controle na substituição de uma string de ativação de comando além de trocar ela por replaceValue, você pode implementar sua própria função de substituição e informar ela através de replaceFuncion.

A assinatura de replaceFunction é a seguinte:

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

onde haystack é a string contendo a transcrição atual do reconhecimento, needle é a string de ativação do comando, replaceValue é a string informada no objeto de configuração do comando, e prop é uma string com o nome da propriedade sendo tratada, i.e "transcript" ou "richTranscript".

A função replaceFunction deve, obrigatoriamente, retornar uma string que será atribuída à transcrição (transcript ou richTranscript) como resultado da substituição da string de ativação do comando.

No exemplo abaixo, o comando iara controle é adicionado. Quando ele for ativado, a string de ativação "iara controle" será substituída pela string "_CONTROLE:transcript" na propriedade transcript, e por "_CONTROLE:richTranscript" na propriedade richTranscript:

function callback(detail, command, param) {
    //...
}

var cmdConfigFunc = {
    transcript: false,       // Manter no transcript? Não, substituir.
    richTranscript: false,   // Manter no richTranscript? Não, substituir.

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

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

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

recognition.init({
    // (...)
}).done(function(e) {
    // Assumindo que o usuário falou "vias biliares iara controle":
    recognition.onresult = function(event) {
        console.log(event.detail.transcript); // vias biliares _CONTROLE:transcript
        console.log(event.detail.richTranscript); // <div>vias biliares _CONTROLE:richTranscript</div>
    };
});

Alteração do resultado de uma transcrição

Se a aplicação precisa, por alguma razão, alterar qualquer o resultado de um reconhecimento quando um comando for executado, isso pode ser feito através da propriedade de configuração resultFunction.

Similarmente a replaceFunction, a função informada em resultFunction será chamada quando o comando for executado, porém ela receberá como parâmetro o objeto que será propagado como evento de resultado do reconhecimento (parâmetro event do recognition.onresult). A assinatura de resultFunction é a seguinte:

function(Object resultEvent, String needle, Object entry) -> Void;

onde resultResult é o objeto de evento que será propagado como resultado do conhecimento, needle é a string de ativação do comando e entry é um objeto contendo das as informações do comando em questão, como string de ativação, configurações, etc.

Veja o exemplo de código iara-commands-advanced para conhecer mais sobre o assunto.

Procura da string de ativação no richTranscript

Se sua aplicação necessitar cadastrar um comando iara cuja string de ativação seja um texto no formato richTranscript, isso pode ser feito através da propriedade de configuração searchRichTranscript.

Se essa propriedade tiver o valor true, a string de ativação deve ser um texto no formato richTranscript. Isto pode facilitar o uso para casos onde a string de ativação contém elementos como siglas, vértebras, números, e outros, como visto abaixo:

function callback(detail, command, param) {
    //...
}

var cmdConfigFunc = {
    searchRichTranscript: true
};

// Se a propriedade searchRichTranscript fosse diferente de true, o comando seria:
// 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) {
    // ...
});

Utilização de Regex

Se sua aplicação necessitar cadastrar um comando com maior flexibilidade, você pode fornecer um regex como string de ativação. Para isto, a string de ativação deve seguir o formato especificado na documentação para construção de objetos RegExp com padrões de string.

Algumas dicas para utilização:

• Para que o regex tenha uma contrabarra nele, essa deve ser antecidada de outra contrabarra
• Procure limitar o escopo do regex o máximo possível, pois o callback do comando será chamado na primeira correspondência com o regex

Você ainda pode usar grupos de captura no regex fornecido. Se algum grupo for capturado, ele será fornecido ao callback através do parâmetro groups. Este parâmetro é um array de strings, onde o primeiro índice é a correspondência total com o regex, e os índices seguintes são os grupos capturados do regex. Veja um exemplo de uso abaixo:

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

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

// Captura qualquer palavra reconhecida após "iara texto".
// Para capturar caracteres especiais como ã, é, veja:
// 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 o comando deve ser comparado com o texto parseado, ou seja, o rich transcript
var searchRichTranscriptConfig = {
    searchRichTranscript: true
};

// Captura qualquer sequência de números reconhecidos após "iara exame"
recognition.commands.add('iara exame (\\d+)', secondCommandCallback, null, null, searchRichTranscriptConfig);

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