# O Manual do &minuet;

## Introdução

Bem-vindo ao &minuet;: a aplicação do &kde; para educação musical. O &minuet; pretende ajudar os alunos e professores em diversos aspectos da educação musical, como o treino do ouvido, a leitura à primeira-vista, os solfejos, as escalas, o ritmo, a harmonia e o improviso. O &minuet; tira bastante partido das capacidades do &MIDI; para oferecer um conjunto completo de funcionalidades no que diz respeito às mudanças de volume, tempo e timbre, o que torna o &minuet; uma ferramenta valiosa tanto para os músicos amadores como para os profissionais.

O &minuet; oferece um conjunto rico de exercícios de treino de audição, podendo ser adicionados de forma transparente novos exercícios para alargar as suas funcionalidades e adaptá-lo a diversos contextos de educação musical.

Exercícios de acordes para o treino de audição do &minuet;

## Usar o &minuet;

Nas próximas três secções - Iniciar o &minuet; e Exercícios do &minuet; - daremos a si os passos necessários para colocar o &minuet; em execução.

### Iniciar o &minuet;

Poderá iniciar o &minuet; a partir do lançador de aplicações. Abra o menu de programas do &kde;, carregando para tal no ícone do lançador de aplicações na barra de ferramentas que existe no canto inferior esquerdo do seu ecrã. O mesmo irá abrir um menu - mova o seu cursor para cima da opção do menu Aplicações Educação Diversos &minuet; (Aplicação de Educação Musical).

### Exercícios e Fluxo de Trabalho do &minuet;

A interface de utilizador do &minuet; contempla três componentes importantes:

Componentes de interface do &minuet;

Menu de Navegação

- Permite a navegação pelas categorias de exercícios do &minuet; e a selecção de um exercício em particular. O Menu de Navegação é criado, de forma dinâmica, com base nos ficheiros de especificação de exercícios descritos em Criar os Exercícios. Os exercícios do &minuet; são agrupados de acordo com classes, como por exemplo intervalos, escalas e acordes.

Área do Teclado

- Exibe os eventos de `nota activa` do &MIDI; lidos a partir de um ficheiro &MIDI; ou da execução de um exercício.

Área do Exercício

- Apresenta, para um dado exercício, os botões para controlar a apresentação do exercício, bem como um conjunto das respostas possíveis para o exercício. A execução de um exercício começa ao carregar no botão `nova questão`. Um dado intervalo/acorde/escala aleatório é tocado pelo &minuet; e depois espera-se que o aluno escolha uma resposta entre as apresentadas na grelha da resposta. O &minuet; apresenta sempre - como um pequeno círculo branco na Área do Teclado - a primeira nota do intervalo/escala seleccionado ou a nota de base do acorde seleccionado. Se passar o cursor sobre uma resposta possível, o &minuet; realça a sua representação visual correspondente na Área do Teclado. As restantes notas da resposta realçada são apresentadas como pequenos círculos cujas cores são as mesmas que o botão da resposta realçada. O aluno poderá ouvir o exercício de novo se carregar no botão `tocar a questão`, carregar no botão da resposta escolhida, ou então obter a resposta correcta se carregar no botão `desistir`. Poderá iniciar uma nova execução do mesmo exercício se carregar de novo no botão `nova questão`.

## Criar novos exercícios do &minuet;

Os exercícios do &minuet; são definidos em ficheiros de especificação de exercícios, guardados no formato JSON:

    {
      "exercises": [
        {
          "name": "Intervalos",
          "root": "21..104",
          "playMode": "scale",
          "children": [
            {
              "name": "Intervalos Melódicos Ascendentes",
              "children": [
                {
                  "name": "Segundos",
                  "options": [
                    {
                      "name": "Segundo Menor",
                      "sequenceFromRoot": "1"
                    },
                    {
                      "name": "Segundo Maior",
                      "sequenceFromRoot": "2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }

Os ficheiros de especificação de exercícios do &minuet; contêm um objecto JSON de topo que contém a lista `exercises`. Essa lista descreve uma estrutura hierárquica de exercícios agrupada por categorias. Cada categoria/exercício tem um nome. Os objectos JSON das categorias contêm uma propriedade chamada `children`, que descreve as sub-categorias/exercícios que pertencem a essa categoria. Os objectos JSON dos exercícios contêm uma propriedade chamada `options`, que define as respostas possíveis para esse exercício. Na execução de cada exercício, o &minuet; selecciona aleatoriamente uma resposta entre as possíveis e espera-se que o aluno carregue no botão de resposta que corresponde à resposta seleccionada.

Qualquer (sub-)categoria poderá definir um parâmetro `root` que define o intervalo do qual a nota inicial do intervalo/acorde/escala será escolhido aleatoriamente para todos os exercícios dessa categoria. Esse intervalo corresponde aos números-padrão das notas em &MIDI; e segue o formato `<valor-mín>..<valor-máx>`. O exemplo apresentado acima usa toda a gama de teclados como notas de base possíveis (21..104). O parâmetro `playMode` indica como as respostas possíveis deverão ser tocadas: como `scale` (escala - uma nota a seguir à outra) ou como `chord` (acorde - todas as notas em simultâneo).

Cada opção do exercício define um nome e a sequência de notas que deverá ser tocada a partir da nota de base seleccionada aleatoriamente na execução de cada exercício. Essa sequência de notas é definida como distâncias relativas à nota de base, descrevendo o intervalo que cada nota forma em conjunto com a nota de base. Por exemplo, para uma escala completa, a sequência de notas é "2 4 5 7 9 11 12", que define respectivamente a estrutura da escala "completa completa metade completa completa completa metade". O parâmetro `sequenceFromRoot` poderá conter um número qualquer de notas como tamanho. Da mesma forma, o motor do &minuet; garante que só as respostas em que todas as notas que caibam da gama do teclado definida é que serão seleccionadas aleatoriamente.

Para oferecer uma melhor infra-estrutura para organizar um grande conjunto de ficheiros de especificação de exercícios, o motor do &minuet; suportam o uso de diversos ficheiros de configuração, os quais são reunidos automaticamente para compor a hierarquia final de exercícios no menu de Navegação. Os exercícios são correctamente reunidos desde que os diferentes ficheiros de configuração usem o mesmo nome de (sub-)categoria ao definir os exercícios. Por agora, o &minuet; não oferece nenhuma &GUI; para criar as definições de exercícios, pelo que terá de criar esses ficheiros JSON de forma manual. Os ficheiros de configuração de exercícios do &minuet; poderão ser instalados a nível do sistema na pasta `minuet/exercises/`, localizada em ``qtpaths` `--path GenericDataLocation``

## Créditos e Licença

&minuet;

Programa com 'copyright' 2016 de &Sandro.Andrade; &Sandro.Andrade.mail;

Documentação com 'copyright' © 2016 de &Sandro.Andrade; &Sandro.Andrade.mail;

Tradução de José Nuno Pires zepires@gmail.com

&underFDL; &underGPL;
&documentation.index;