SpeakMaster: Module Builder

Durante o processo de criação de um novo módulo para fornecer novas funcionalidades e possibilidades para o SpeakMaster, o desenvolvedor tem que gerar alguns arquivos JSON que são usados pelo SpeakMaster para permitir que os usuários possam utilizar o módulo. A seguir estão descritos quais são esses arquivos:

1. sm-module-features.json: este é o arquivo obrigatório que descreve as funcionalidades que o módulo implementa e como elas podem ser utilizadas. A partir deste arquivo os usuários finais podem usar a plataforma web do SpeakMaster para criar comandos que executam as funcionalidades listadas neste arquivo. Este arquivo inclui descrições em múltiplos idiomas para as funcionalidades, parâmetros e valores restritos a certos parâmetros.

2. sm-module-preferences.json: este é o arquivo obrigatório que descreve a estrutura das preferências do módulo. A partir deste arquivo os usuários finais podem usar a plataforma web do SpeakMaster para configurar o módulo e personalizar seu uso. TODO: o construtor de preferências ainda não está implementado.

3. sm-module-default-commands.json: este é o arquivo opcional que descreve os comandos padrões do módulo para facilitar para o usuário final utilizar suas funcionalidades. A partir deste arquivo os usuários finais podem executar comandos do módulo sem terem que configurá-los manualmente. Este arquivo inclui definições de comandos em múltiplos idiomas que acionam as funcionalidades implementadas no módulo. Embora seja opcional, é fortemente recomendado que o desenvolvedor crie comandos padrões para ao menos servirem de referência para os usuários.

Instalação

npm i -D speakmaster-module-builder

Como este módulo é utilizado apenas para a geração dos arquivos JSON necessários para publicação de um módulo no SpeakMaster, ele não precisa estar presente no produto final do módulo que será distribuído para os usuários. Sendo assim, o instale como uma dependência de desenvolvimento (em devDependencies).

Como Usar

Este pacote pode ser usado para gerar os arquivos JSON listados acima, veja abaixo como usá-lo para gerar cada arquivo.

sm-module-features.json

Este pacote fornece a classe ModuleFeaturesBuilder para registrar a funcionalidades oferecidas pelo módulo em desenvolvimento e para a geração do arquivo JSON. Além disso, utilize a classe Feature para especificar cada funcionalidade implementada, podendo adicionar traduções e parâmetros como instâncias da classe Parameter. Caso deseje utilizar um parâmetro com específico valores aceitos, como uma enumeração, utilize instâncias da classe ParameterValue para definir estes valores.

Utilize a função addFeature de uma instância da classe ModuleFeaturesBuilder para registrar funcionalidades e quando finalizar, chame a função generateJSON para finalmente gerar o arquivo sm-module-features.json.

Associação dos Identificadores

Ao criar uma instância de Feature você deve definir um identifier (identificador), este valor deverá ser o mesmo que você utilizará para registrar a função que implementa a funcionalidade em questão para associa-la na Central de Comandos do SpeakMaster. Ou seja, quando o usuário executar um comando associado à funcionalidade, este identifier será enviado para a Central de Comandos que por sua vez irá encaminhar essa informação para o módulo, e com base nela o módulo deverá chamar a função correspondente para executar a ação desejada pelo usuário.

Além disso, ao criar uma instância de Parameter você também deve definir um identifier que será utilizado como a chave do objeto JSON que identifica o parâmetro em questão nos dados recebidos do SpeakMaster para a execução da funcionalidade. Caso o parâmetro definido seja uma enumeração com determinados valores aceitos, crie uma instância de ParameterValue para cada valor possível, e ao criar cada instância você também deve definir um identifier que, neste caso, será o valor passado para o parâmetro no objeto JSON dos dados recebidos do SpeakMaster.

Exemplo:

Abaixo temos um exemplo de funcionalidade para um módulo de controle do mouse.

const { LanguageCode } = require("speakmaster-module-builder");
const { ModuleFeaturesBuilder, Feature, Parameter, ParameterValue } = require("speakmaster-module-builder/features-builder");

new ModuleFeaturesBuilder()
  .addFeature(
    new Feature("moveMouse", LanguageCode.EN_US)
      .addTranslation("Move Mouse", "Moves the mouse in the given direction", [LanguageCode.EN_US, LanguageCode.EN_GB])
      .addTranslation("Mover o Mouse", "Move o mouse na direção informada", [LanguageCode.PT_BR, LanguageCode.PT_PT])
      .addParameter(
        new Parameter("direction")
          .addTranslation("Direction", "Direction to move mouse", [LanguageCode.EN_US, LanguageCode.EN_GB])
          .addTranslation("Direção", "Direção na qual o mouse irá mover", [LanguageCode.PT_BR, LanguageCode.PT_PT])
          .addAllowedValue(
            new ParameterValue("UP")
              .addTranslation("Up", "Move mouse upwards", [LanguageCode.EN_US, LanguageCode.EN_GB])
              .addTranslation("Pra Cima", "Move o mouse pra cima", [LanguageCode.PT_BR, LanguageCode.PT_PT]),
            new ParameterValue("DOWN")
              .addTranslation("Down", "Move mouse downwards", [LanguageCode.EN_US, LanguageCode.EN_GB])
              .addTranslation("Pra Baixo", "Move o mouse pra baixo", [LanguageCode.PT_BR, LanguageCode.PT_PT]),
            new ParameterValue("LEFT")
              .addTranslation("Left", "Move mouse leftwards", [LanguageCode.EN_US, LanguageCode.EN_GB])
              .addTranslation("Esquerda", "Move o mouse esquerda", [LanguageCode.PT_BR, LanguageCode.PT_PT]),
            new ParameterValue("RIGHT")
              .addTranslation("Right", "Move mouse rightwards", [LanguageCode.EN_US, LanguageCode.EN_GB])
              .addTranslation("Direita", "Move o mouse direita", [LanguageCode.PT_BR, LanguageCode.PT_PT])
          )
      )
  )
  .generateJSON();

Com base na funcionalidade definida acima, caso o usuário executasse um comando associado a ela, a Central de Comandos do SpeakMaster enviaria, por exemplo, os seguintes dados para o módulo:

{
  "event": "COMMAND",
  "featureIdentifier": "moveMouse",
  "parameters": { "direction": "RIGHT" },
  "sentAt": 1712476663131
}

O módulo deve tratar esses dados corretamente realizando a chamada da função associada ao identificador de funcionalidade moveMouse, e passar para ela os parâmetros presentes no objeto { "direction": "RIGHT" }. Se estiver usando Node.js, este processo é facilitado utilizando o pacote speakmaster-module-connection.

sm-module-preferences.json

TODO: implementação pendente.

sm-module-default-commands.json

Este pacote fornece a classe DefaultCommandsBuilder para facilitar o processo de definição dos comandos padrões do módulo em múltiplos idiomas. O usuário final poderá fazer a importação desses comandos para já começar a usar as funcionalidades oferecidas pelo módulo imediatamente após a instalação dele. Para criar comandos, chame a função addCommand de uma instância da classe DefaultCommandsBuilder e passe para ela um vetor de idiomas (LanguageCodes) aos quais o comando se aplica, e em seguida uma instância da classe Command. Quando finalizar, chame a função generateJSON para finalmente gerar o arquivo sm-module-default-commands.json.

Para criar instâncias da classe Command passe os seguintes parâmetros:

1. A definição do comando usando a Linguagem de Reconhecimento de Comandos (CRL);

2. O identifier da funcionalidade que deverá ser executada quando este comando for reconhecido;

3. Opcionalmente, o parâmetro ou lista de parâmetros aceitos pela funcionalidade como instâncias da classe CommandParameter. Ao criar instâncias dessa classe, passe o identifier do parâmetro que será utilizado como a chave do objeto JSON que identifica o parâmetro nos dados recebidos do SpeakMaster para a execução da funcionalidade. Em seguida, chame uma das seguintes funções para definir o tipo do parâmetro:

   • useConstant: utiliza um valor fixo para o parâmetro. Passe uma string com o valor desejado para esta função.

   • useVariable: utiliza uma variável usada na definição do comando para receber um valor dinâmico para este parâmetro, isto é, qualquer string reconhecida pelo comando e associado a variável será passada para este parâmetro. Passe o nome da variável para esta função.

   • useRestrictedVariable: mapeia os valores aceitos pelo parâmetro aos valores reconhecidos por uma variável usada na definição do comando. Passe para esta função o nome da variável e, em seguida, o vetor de valores aceitos fazendo a associação direta com os itens reconhecidos pela variável da definição do comando.

Exemplo:

const { LanguageCode } = require("speakmaster-module-builder");
const { DefaultCommandsBuilder, Command, CommandParameter } = require("speakmaster-module-builder/default-commands-builder");

new DefaultCommandsBuilder()
  .addCommand(
    [LanguageCode.EN_US, LanguageCode.EN_GB],
    new Command(
      "move mouse {DIRECTION (up, down, left, right)}",
      "moveMouse",
      new CommandParameter("direction").useRestrictedVariable("DIRECTION", ["UP", "DOWN", "LEFT", "RIGHT"])
    )
  )
  .addCommand(
    [LanguageCode.PT_BR, LanguageCode.PT_PT],
    new Command(
      "mover [o] mouse [(para, pra)] {DIREÇÃO (cima, baixo, esquerda, direita)}",
      "moveMouse",
      new CommandParameter("direction").useRestrictedVariable("DIREÇÃO", ["UP", "DOWN", "LEFT", "RIGHT"])
    )
  )
  .generateJSON();

Com base no comando em português definido acima, o parâmetro direction da funcionalidade associada ao identificador moveMouse receberá o valor:

• UP: se a variável DIREÇÃO for igual a cima;
• DOWN: se a variável DIREÇÃO for igual a baixo;
• LEFT: se a variável DIREÇÃO for igual a esquerda;
• RIGHT: se a variável DIREÇÃO for igual a direita;

Ou seja, se o usuário disser mover mouse pra baixo, a Central de Comandos do SpeakMaster enviaria, por exemplo, os seguintes dados para o módulo:

{
  "event": "COMMAND",
  "featureIdentifier": "moveMouse",
  "parameters": { "direction": "DOWN" },
  "sentAt": 1712518896706
}