[education/minuet] doc: Update docbook documentation
Sandro S. Andrade
null at kde.org
Fri Jul 3 23:19:21 BST 2026
Git commit 845d8589ff56b8941d160cbae5543715d180fa84 by Sandro S. Andrade.
Committed on 03/07/2026 at 22:19.
Pushed by sandroandrade into branch 'master'.
Update docbook documentation
M +304 -78 doc/index.docbook
A +- -- doc/minuet-chords-manual.png
A +- -- doc/minuet-clapping.png
A +- -- doc/minuet-exercise-list.png
A +- -- doc/minuet-home.png
A +- -- doc/minuet-practice-mode.png
A +- -- doc/minuet-settings-advanced.png
A +- -- doc/minuet-settings-basic.png
A +- -- doc/minuet-singing-interval.png
A +- -- doc/minuet-singing-scale.png
https://invent.kde.org/education/minuet/-/commit/845d8589ff56b8941d160cbae5543715d180fa84
diff --git a/doc/index.docbook b/doc/index.docbook
index d9becfe..2071fa3 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -21,19 +21,20 @@
</authorgroup>
<copyright>
-<year>2016</year>
+<year>2026</year>
<holder>&Sandro.Andrade;</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
-<date>2021-10-19</date>
+<date>2026-07-03</date>
-<releaseinfo>0.4 (KDE Gear 21.08)</releaseinfo>
+<releaseinfo>Current development version</releaseinfo>
<abstract>
<para>
-&minuet; is an application for music education. It features a set of ear training exercises
-regarding intervals, chords, and scales.
+&minuet; is KDE's music education app for ear training, rhythm practice, and guided singing.
+It groups exercises by topic, lets you switch between listening and performance-based practice,
+and exposes sound and microphone settings for different instruments and rooms.
</para>
</abstract>
@@ -45,6 +46,9 @@ regarding intervals, chords, and scales.
<keyword>intervals</keyword>
<keyword>chords</keyword>
<keyword>scales</keyword>
+<keyword>rhythm</keyword>
+<keyword>microphone</keyword>
+<keyword>practice</keyword>
<keyword>Minuet</keyword>
</keywordset>
@@ -54,108 +58,330 @@ regarding intervals, chords, and scales.
<title>Introduction</title>
<para>
-Welcome to &minuet;: the software for music education. &minuet; aims at supporting
-students and teachers in many aspects of music education, such as ear
-training, first-sight reading, solfa, scales, rhythm, harmony, and improvisation. &minuet;
-makes extensive use of &MIDI; capabilities to provide a full-fledged set of features
-regarding volume, tempo, and pitch changes, which makes &minuet; a valuable tool for both
-novice and experienced musicians.
+Welcome to &minuet;: the software for music education. It is built around short exercises that let
+you listen, respond, and test your progress without leaving the app.
</para>
<para>
-&minuet; features a rich set of ear training's exercises and new ones can be <link linkend="creating-exercises">
-seamlessly added</link> in order to extend its functionalities and adapt it to several
-music education contexts.
+The app currently covers melodic ear training, rhythm recognition, clapping exercises, and singing
+exercises. The same exercise can often be practiced in more than one way, which is why the
+interface first asks whether you want to hear and identify, read and clap, or read and sing.
</para>
<screenshot>
- <screeninfo>&minuet; main window</screeninfo>
+ <screeninfo>&minuet; home screen</screeninfo>
<mediaobject>
- <imageobject><imagedata fileref="minuet-screenshot.png" format="PNG" /></imageobject>
- <textobject><phrase>&minuet;'s ear training chord exercises</phrase></textobject>
+ <imageobject><imagedata fileref="minuet-home.png" format="PNG" /></imageobject>
+ <textobject><phrase>The &minuet; home screen</phrase></textobject>
</mediaobject>
</screenshot>
+
+<para>
+The home page is intentionally minimal. Use the navigation drawer to move to the settings page,
+the about page, or a category of exercises.
+</para>
</chapter>
<chapter id="using-minuet">
<title>Using &minuet;</title>
<para>
-In the next two sections - <link linkend="starting-minuet">Starting &minuet;</link> and <link linkend="minuet-exercises">&minuet; Exercises</link> - we will provide you the required steps to get &minuet; up and running.
+The normal flow is simple: start &minuet;, choose an exercise, pick a practice mode, then work
+through a question or a test run.
</para>
<sect1 id="starting-minuet">
<title>Starting &minuet;</title>
[suppressed due to size limit]
+<para>
+Start &minuet; from the application launcher or from a terminal by running
+<command>minuet</command>. When the app opens, the home page shows a single prompt:
+<guilabel>Choose an exercise</guilabel>.
</para>
</sect1>
-<sect1 id="minuet-exercises">
-<title>&minuet; Exercises and Workflow</title>
+<sect1 id="browse-exercises">
+<title>Browse and choose exercises</title>
<para>
-&minuet;'s user interface entails three major components:
+The exercise browser groups topics by subject. Use the drawer or the category list to reach
+chords, intervals, rhythm, or scales. The browser updates itself from the installed exercise
+specification files, so the visible hierarchy reflects the exercises that are currently available.
</para>
<screenshot>
- <screeninfo>&minuet; main window</screeninfo>
+ <screeninfo>&minuet; exercise browser</screeninfo>
<mediaobject>
- <imageobject><imagedata fileref="minuet-ui-components.png" format="PNG" /></imageobject>
- <textobject><phrase>&minuet;'s UI components</phrase></textobject>
+ <imageobject><imagedata fileref="minuet-exercise-list.png" format="PNG" /></imageobject>
+ <textobject><phrase>The exercise browser in &minuet;</phrase></textobject>
</mediaobject>
</screenshot>
-<variablelist>
+<para>
+Each exercise entry has a title and a short description. Some categories lead directly to an
+exercise, while others expand into subcategories. The list is not fixed in code: new exercise files
+are merged into the hierarchy automatically when &minuet; starts.
+</para>
+
+</sect1>
+
+<sect1 id="practice-modes">
+<title>Practice modes</title>
+
+<para>
+When you open an exercise, &minuet; asks how you want to practice it.
+</para>
-<varlistentry>
-<term><guilabel>Navigation Menu</guilabel></term>
-<listitem><para>Allows for navigating in &minuet;'s exercise categories and selecting a particular exercise. The Navigation Menu is dynamically created based upon exercises specification files as described in <link linkend="creating-exercises">Creating Exercises</link>. &minuet;'s exercises are grouped according to classes such as intervals, scales, and chords.</para></listitem>
-</varlistentry>
+<screenshot>
+ <screeninfo>&minuet; practice mode chooser</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="minuet-practice-mode.png" format="PNG" /></imageobject>
+ <textobject><phrase>The practice mode chooser in &minuet;</phrase></textobject>
+ </mediaobject>
+</screenshot>
-<varlistentry>
-<term><guilabel>Keyboard View</guilabel></term>
-<listitem><para>Exhibits &MIDI; <parameter>note on</parameter> events being sequenced by a &MIDI; file or by an exercise execution.</para></listitem>
-</varlistentry>
+<para>
+There are two broad practice paths:
+</para>
-<varlistentry>
-<term><guilabel>Exercise View</guilabel></term>
[suppressed due to size limit]
-</varlistentry>
+<itemizedlist>
+<listitem>
+<para>
+<guilabel>Hear and identify</guilabel> plays the exercise and asks you to choose the answer from the
+available options. This is the main flow for melodic ear training.
+</para>
+</listitem>
+<listitem>
+<para>
+<guilabel>Read and clap</guilabel> is shown for rhythm exercises. <guilabel>Read and sing</guilabel>
+is shown for melodic exercises that accept vocal input, such as intervals and scales.
+</para>
+</listitem>
+</itemizedlist>
-</variablelist>
+<para>
+The practice choice changes the input mode, not the underlying exercise category. That means you
+can use the same exercise data for listening, clapping, or singing work depending on the topic.
+</para>
</sect1>
+
+<sect1 id="melodic-workflow">
+<title>Melodic ear training</title>
+
+<para>
+Melodic exercises follow the classic Minuet flow: the app plays a question, shows answer choices,
+and lets you replay the prompt if you need to hear it again. This manual mode is used for
+intervals, scales, and chords when you choose <guilabel>Hear and identify</guilabel>.
+</para>
+
+<screenshot>
+ <screeninfo>&minuet; chord exercise in manual mode</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="minuet-chords-manual.png" format="PNG" /></imageobject>
+ <textobject><phrase>A chord exercise in manual mode in &minuet;</phrase></textobject>
+ </mediaobject>
+</screenshot>
+
+<para>
+The exercise page gives you the controls you need for a single question or a longer test run:
+</para>
+
+<itemizedlist>
+<listitem><para><guibutton>New Question</guibutton> starts another question.</para></listitem>
+<listitem><para><guibutton>Play Question</guibutton> repeats the current prompt.</para></listitem>
+<listitem><para><guibutton>Give Up</guibutton> reveals the answer.</para></listitem>
+<listitem><para><guibutton>Start Test</guibutton> begins a scored sequence of questions.</para></listitem>
+<listitem><para><guibutton>Stop Test</guibutton> ends the test run.</para></listitem>
+</itemizedlist>
+
+<para>
+In melodic exercises, the answer buttons and the keyboard or staff view stay aligned, so you can
+see how each candidate maps to the notes being played.
+</para>
+
+<para>
+Chord exercises use the same manual workflow, but the prompt is played as a chord instead of a
+melodic sequence. &minuet; plays the chord, shows the root note on the keyboard and staff, and asks
+you to choose one chord quality from the available answers. The chord catalog includes triads,
+inversions, suspended chords, seventh chords, ninth chords, eleventh chords, and mixed chord sets
+such as <guilabel>Lots of chords</guilabel>.
+</para>
+
+<para>
+Use <guibutton>Play Question</guibutton> to hear the chord again before answering. In test mode,
+&minuet; scores the sequence using the configured number of exercises from the settings page.
+</para>
+</sect1>
+
+<sect1 id="rhythm-workflow">
+<title>Rhythm and clapping</title>
+
+<para>
+Rhythm exercises focus on timing rather than pitch. In the clapping mode, &minuet; listens to your
+microphone input and compares the onsets to the target pattern.
+</para>
+
+<screenshot>
+ <screeninfo>&minuet; clapping exercise</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="minuet-clapping.png" format="PNG" /></imageobject>
+ <textobject><phrase>A rhythm clapping exercise in &minuet;</phrase></textobject>
+ </mediaobject>
+</screenshot>
+
+<para>
+The clapping view shows the rhythm pattern cards, an input level meter, and a
+<guibutton>Calibrate Silence</guibutton> action. The count-in happens before recording starts, so
+you can settle into the tempo before the exercise listens for claps.
+</para>
+
+<para>
+Use the rhythm practice to work on:
+</para>
+
+<itemizedlist>
+<listitem><para>recognizing simple rhythm figures by ear;</para></listitem>
+<listitem><para>matching your claps to the beat;</para></listitem>
+<listitem><para>staying inside the configured timing tolerance.</para></listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="singing-workflow">
+<title>Singing exercises</title>
+
+<para>
+Singing exercises use the microphone to compare what you sing with the target pitch content. The
+same practice screen is used for both interval and scale work, but the target and feedback change
+with the chosen exercise.
+</para>
+
+<para>
+For interval exercises, &minuet; plays the root note and asks you to sing the requested interval
+relative to it. For scale exercises, the app presents a scale or mode and expects you to sing the
+notes in sequence while staying on pitch and on beat.
+</para>
+
+<screenshot>
+ <screeninfo>&minuet; singing interval exercise</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="minuet-singing-interval.png" format="PNG" /></imageobject>
+ <textobject><phrase>A singing interval exercise in &minuet;</phrase></textobject>
+ </mediaobject>
+</screenshot>
+
+<screenshot>
+ <screeninfo>&minuet; singing scale exercise</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="minuet-singing-scale.png" format="PNG" /></imageobject>
+ <textobject><phrase>A singing scale exercise in &minuet;</phrase></textobject>
+ </mediaobject>
+</screenshot>
+
+<para>
+The singing view shows the note targets, pitch and onset feedback, a live input meter, and a
+<guibutton>Calibrate Silence</guibutton> action. &minuet; also counts in before the first note, so
+you can start on the correct beat. The scale view extends the same feedback to longer sequences,
+which makes it useful for practicing melodic memory in addition to pitch matching.
+</para>
+
+<para>
+Singing exercises are influenced by several settings:
+</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Voice class</guilabel> selects the expected vocal range.</para></listitem>
+<listitem><para><guilabel>Pitch tolerance</guilabel> controls how far from the target pitch a sung note may be.</para></listitem>
+<listitem><para><guilabel>Timing tolerance</guilabel> controls how much rhythmic drift is accepted for claps.</para></listitem>
+</itemizedlist>
+</sect1>
+
+</chapter>
+
+<chapter id="settings">
+<title>Settings</title>
+
+<para>
+The settings page is split into four sections: <guilabel>Practice</guilabel>,
+<guilabel>Sound</guilabel>, <guilabel>Microphone</guilabel>, and <guilabel>Advanced</guilabel>.
+The first three sections keep the beginner controls visible. The advanced section stays collapsed
+until you open it.
+</para>
+
+<screenshot>
+ <screeninfo>&minuet; basic settings</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="minuet-settings-basic.png" format="PNG" /></imageobject>
+ <textobject><phrase>The basic settings page in &minuet;</phrase></textobject>
+ </mediaobject>
+</screenshot>
+
+<para>
+The visible settings cover the controls most users need day to day:
+</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Exercise speed</guilabel> sets the tempo in beats per minute.</para></listitem>
+<listitem><para><guilabel>Number of rhythm patterns</guilabel> controls the size of rhythm practice sets.</para></listitem>
+<listitem><para><guilabel>Number of exercises</guilabel> sets the length of a test run.</para></listitem>
+<listitem><para><guilabel>Volume</guilabel> adjusts playback loudness.</para></listitem>
+<listitem><para><guilabel>Instrument</guilabel> selects the melodic sound used for ear training.</para></listitem>
+<listitem><para><guilabel>Voice class</guilabel> selects the target singing range.</para></listitem>
+</itemizedlist>
+
+<para>
+The microphone section also includes short helper descriptions for the tolerance and calibration
+controls. Those descriptions explain when to tighten the tolerance and when to recalibrate silence.
+</para>
+
+<screenshot>
+ <screeninfo>&minuet; advanced settings</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="minuet-settings-advanced.png" format="PNG" /></imageobject>
+ <textobject><phrase>The advanced settings section in &minuet;</phrase></textobject>
+ </mediaobject>
+</screenshot>
+
+<para>
+Advanced settings expose detection algorithms and thresholds for difficult microphones or noisy
+rooms. Use them when the default detection behavior is not enough. The section is collapsed by
+default and includes a <guibutton>Reset to Defaults</guibutton> button so you can restore the
+factory values after experimenting.
+</para>
+
+<para>
+The advanced section includes separate groups for clapping detection and singing detection.
+Typical controls include onset method, onset threshold, input gate, minimum onset strength,
+silence level, pitch method, scoring mode, pitch confidence, and stable pitch frames.
+</para>
</chapter>
<chapter id="creating-exercises">
<title>Creating new &minuet;'s exercises</title>
<para>
-&minuet;'s exercises are defined in exercise specification files, written in &JSON; format:
+&minuet;'s exercises are defined in &JSON; specification files. The app loads all available files
+at startup and merges them into the visible exercise tree.
</para>
+
<para>
<programlisting>
{
"exercises": [
{
"name": "Intervals",
- "root": "21..104",
+ "root": "29..69",
"playMode": "scale",
+ "userMessage": "Hear the interval and choose your answer",
+ "numberOfSelectedOptions": 1,
+ "_icon": "minuet-intervals-symbolic.svg",
"children": [
{
- "name": "Ascending Melodic Intervals",
+ "name": "Ascending melodic intervals",
+ "and-tags": ["interval", "ascending"],
"children": [
{
"name": "Seconds",
- "options": [
- {
- "name": "Minor Second",
- "sequenceFromRoot": "1"
- },
- {
- "name": "Major Second",
- "sequenceFromRoot": "2"
- }
- ]
+ "or-tags": ["2"],
+ "description": "Practice identifying ascending melodic seconds by ear."
}
]
}
@@ -165,36 +391,36 @@ In the next two sections - <link linkend="starting-minuet">Starting &minuet;</li
}
</programlisting>
</para>
+
<para>
-&minuet;'s exercise specification files contain one top-level &JSON; object featuring the <parameter>exercises</parameter>
-array. Such an array defines a hierarchical structure of exercises, grouped by categories. Every category/exercise has a
-name. Category &JSON; objects contain a property named <parameter>children</parameter>, which describes the
-subcategories/exercises entailed by such a category. Exercise &JSON; objects contain a property named <parameter>
-options</parameter>, which defines the possible answers for such an exercise. In each exercise run, &minuet; randomly
-selects one answer among the possible ones and the student is expected to click the answer's button which corresponds to the
-selected answer.
-</para>
-<para>
-Any (sub)category may define a <parameter>root</parameter> parameter to specify the range from which the initial interval/chord/scale's
-note will be randomly chosen for all exercises in this category. Such range corresponds to standards &MIDI; note numbers and follows
-the format <parameter><min-value>..<max-value></parameter>. The example presented above uses all keyboard range as possible
-root notes (21..104). The <parameter>playMode</parameter> parameter indicates
-how possible answers should be played: as a <parameter>scale</parameter> (one note after the other) or as a <parameter>chord</parameter> (all
-notes ringing out simultaneously).
+The top-level object contains an <parameter>exercises</parameter> array. Each item in that array is
+either a category or an exercise leaf. Categories use <parameter>children</parameter> to define the
+next level of the tree.
</para>
+
<para>
-Each exercise's option defines a name and the sequence of notes which should be played from the root note randomly selected in
-each exercise run. Such sequence of notes is defined as relative distances from the root note, describing the interval
-each note forms in conjunction with the root note. For example, for a major scale, the sequence of notes is <quote>2 4 5 7 9 11 12</quote>,
-which respectively denotes the <quote>whole whole half whole whole whole half</quote> major scale structure. The <parameter>sequenceFromRoot</parameter> parameter may contain any notes in length. Also, &minuet;'s core ensures that only answers
-whose all notes lies within keyboard range are randomly selected.
+Useful fields include:
</para>
+
+<itemizedlist>
+<listitem><para><parameter>name</parameter> gives every node its visible label.</para></listitem>
+<listitem><para><parameter>root</parameter> limits the note range used to generate the prompt.</para></listitem>
+<listitem><para><parameter>playMode</parameter> selects scale, chord, or rhythm playback.</para></listitem>
+<listitem><para><parameter>userMessage</parameter> customizes the instruction shown to the user.</para></listitem>
+<listitem><para><parameter>numberOfSelectedOptions</parameter> controls how many answers may be correct.</para></listitem>
+<listitem><para><parameter>_icon</parameter> sets the icon shown in the drawer and exercise browser.</para></listitem>
+<listitem><para><parameter>and-tags</parameter> and <parameter>or-tags</parameter> help group and filter related nodes.</para></listitem>
+<listitem><para><parameter>description</parameter> gives the browser a short explanation for the node.</para></listitem>
+<listitem><para><parameter>options</parameter> describes answer choices for a leaf exercise.</para></listitem>
+<listitem><para><parameter>sequenceFromRoot</parameter> defines the note offsets for melodic answers.</para></listitem>
+<listitem><para><parameter>template</parameter> is used by rhythm exercises to render notation.</para></listitem>
+</itemizedlist>
+
<para>
-To provide a better infrastructure for organizing a large set of exercise specification files, &minuet;'s core supports the use
-of several specification files, which are automatically merged to compose the final exercise hierarchy presented in the
-Navigation Menu. Exercises are correctly merged as long as different specification files use the same (sub)category name
-when defining exercises. For now, &minuet;'s provides no &GUI; for creating exercise specifications so that you must manually create such &JSON; files. &minuet;'s exercise specification files may be installed system-wide or locally in the <filename class="directory">minuet/exercises/</filename>
-folder located in <userinput><command>qtpaths</command> <option>--paths GenericDataLocation</option></userinput>
+The app merges files that share the same category names, so separate specification files can
+contribute to one visible hierarchy. Install them system-wide or place them in
+<filename class="directory">minuet/exercises/</filename> under the generic data location returned by
+<userinput><command>qtpaths</command> <option>--paths GenericDataLocation</option></userinput>.
</para>
</chapter>
@@ -211,7 +437,7 @@ Program copyright 2016 &Sandro.Andrade; &Sandro.Andrade.mail;
</para>
<para>
-Documentation Copyright © 2016 &Sandro.Andrade; &Sandro.Andrade.mail;
+Documentation Copyright © 2026 &Sandro.Andrade; &Sandro.Andrade.mail;
</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
diff --git a/doc/minuet-chords-manual.png b/doc/minuet-chords-manual.png
new file mode 100644
index 0000000..755fa8f
Binary files /dev/null and b/doc/minuet-chords-manual.png differ
diff --git a/doc/minuet-clapping.png b/doc/minuet-clapping.png
new file mode 100644
index 0000000..02c4aba
Binary files /dev/null and b/doc/minuet-clapping.png differ
diff --git a/doc/minuet-exercise-list.png b/doc/minuet-exercise-list.png
new file mode 100644
index 0000000..b3fefb6
Binary files /dev/null and b/doc/minuet-exercise-list.png differ
diff --git a/doc/minuet-home.png b/doc/minuet-home.png
new file mode 100644
index 0000000..e5d49f4
Binary files /dev/null and b/doc/minuet-home.png differ
diff --git a/doc/minuet-practice-mode.png b/doc/minuet-practice-mode.png
new file mode 100644
index 0000000..7d36e23
Binary files /dev/null and b/doc/minuet-practice-mode.png differ
diff --git a/doc/minuet-settings-advanced.png b/doc/minuet-settings-advanced.png
new file mode 100644
index 0000000..4e9214c
Binary files /dev/null and b/doc/minuet-settings-advanced.png differ
diff --git a/doc/minuet-settings-basic.png b/doc/minuet-settings-basic.png
new file mode 100644
index 0000000..a4e4ed1
Binary files /dev/null and b/doc/minuet-settings-basic.png differ
diff --git a/doc/minuet-singing-interval.png b/doc/minuet-singing-interval.png
new file mode 100644
index 0000000..8bcfd0b
Binary files /dev/null and b/doc/minuet-singing-interval.png differ
diff --git a/doc/minuet-singing-scale.png b/doc/minuet-singing-scale.png
new file mode 100644
index 0000000..08aa36f
Binary files /dev/null and b/doc/minuet-singing-scale.png differ
More information about the kde-doc-english
mailing list