~ubuntu-branches/ubuntu/saucy/solfege/saucy

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Lesson files</title><link rel="stylesheet" href="../style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="GNU Solfege 3.16.4 Manual de usuario"><link rel="up" href="extending-solfege.html" title="Capítulo 4. Extending GNU Solfege"><link rel="prev" href="extending-solfege.html" title="Capítulo 4. Extending GNU Solfege"><link rel="next" href="chordvoicing-module.html" title="The chordvoicing module"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Lesson files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="extending-solfege.html">Anterior</a> </td><th width="60%" align="center">Capítulo 4. Extending GNU Solfege</th><td width="20%" align="right"> <a accesskey="n" href="chordvoicing-module.html">Próximo</a></td></tr></table><hr></div><div class="sect1" title="Lesson files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="lesson-files"></a>Lesson files</h2></div></div></div><p>In GNU Solfege, each exercise is created by a lesson file

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Lesson files</title><link rel="stylesheet" href="../style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="GNU Solfege 3.19.6 Manual de usuario"><link rel="up" href="extending-solfege.html" title="Capítulo 4. Extending GNU Solfege"><link rel="prev" href="extending-solfege.html" title="Capítulo 4. Extending GNU Solfege"><link rel="next" href="chordvoicing-module.html" title="The chordvoicing module"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Lesson files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="extending-solfege.html">Anterior</a> </td><th width="60%" align="center">Capítulo 4. Extending GNU Solfege</th><td width="20%" align="right"> <a accesskey="n" href="chordvoicing-module.html">Próximo</a></td></tr></table><hr></div><div class="sect1" title="Lesson files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="lesson-files"></a>Lesson files</h2></div></div></div><p>In GNU Solfege, each exercise is created by a lesson file

interpreted by one of the exercise modules.</p><p>Deprecated modules: chord, harmonicprogressiondictation,

</p><p>Missing documentation: chordvoicing, identifybpm, twelvetone

</p><div class="sect2" title="File encoding"><div class="titlepage"><div><div><h3 class="title"><a name="File-encoding"></a>File encoding</h3></div></div></div><a class="indexterm" name="id2932518"></a><p>Solfege by default expects the content of lesson files to be in UTF-8

</p><div class="sect2" title="File encoding"><div class="titlepage"><div><div><h3 class="title"><a name="File-encoding"></a>File encoding</h3></div></div></div><a class="indexterm" name="id332609"></a><p>Solfege by default expects the content of lesson files to be in UTF-8

encoding.

Modern editors often let you

specify the encoding in the "Save As" dialog. One example is

the symbol you like.

</p></dd><dt><span class="term">♭ <code class="literal">266D MUSIC FLAT SIGN</code></span></dt><dd><p>This sign can be used instead of the letter 'b' for a

flat sign.</p></dd><dt><span class="term">♯ <code class="literal">266F MUSIC SHARP SIGN</code></span></dt><dd><p>This can be used instead of the letter '#' for the

sharp sign.</p></dd></dl></div></div><div class="sect2" title="Comments"><div class="titlepage"><div><div><h3 class="title"><a name="Comments"></a>Comments</h3></div></div></div><a class="indexterm" name="id2932725"></a><p>Everything after # on a line is ignored. Example:</p><pre class="programlisting"># This line is ignored. The next line is not.

sharp sign.</p></dd></dl></div></div><div class="sect2" title="Comments"><div class="titlepage"><div><div><h3 class="title"><a name="Comments"></a>Comments</h3></div></div></div><a class="indexterm" name="id332801"></a><p>Everything after # on a line is ignored. Example:</p><pre class="programlisting"># This line is ignored. The next line is not.

question { bla bla }

</pre></div><div class="sect2" title="Types"><div class="titlepage"><div><div><h3 class="title"><a name="Types"></a>Types</h3></div></div></div><div class="sect3" title="Strings"><div class="titlepage"><div><div><h4 class="title"><a name="lf-types-strings"></a>Strings</h4></div></div></div><a class="indexterm" name="id2932757"></a><p>Strings are quoted with the <code class="literal">"</code> character. Example:</p><pre class="programlisting">"this is a string"</pre><p>Use tripple quotes for strings that contain line breaks, or

</pre></div><div class="sect2" title="Types"><div class="titlepage"><div><div><h3 class="title"><a name="Types"></a>Types</h3></div></div></div><div class="sect3" title="Strings"><div class="titlepage"><div><div><h4 class="title"><a name="lf-types-strings"></a>Strings</h4></div></div></div><a class="indexterm" name="id332832"></a><p>Strings are quoted with the <code class="literal">"</code> character. Example:</p><pre class="programlisting">"this is a string"</pre><p>Use triple quotes for strings that contain line breaks, or

if the string itself has to contain the <code class="literal">"</code> character:</p><pre class="programlisting">

description = """<h1>Long desription<h1> This lessonfile need

very much descriptions. Qoutes (") are ok here. bla bla bla"""</pre><p>NB: All strings have to be unicode strings. If you get error messages like this one:</p><pre class="programlisting">

</pre><p>then you must check the encoding of your file, and maybe you should

read <a class="xref" href="lesson-files.html#File-encoding" title="File encoding">« File encoding »</a>. You can change the encoding of a file using the <span class="command"><strong>iconv</strong></span> program:</p><pre class="programlisting">iconv -f YOUR_ENCODING -t utf8 your.file</pre></div><div class="sect3" title="Tempo"><div class="titlepage"><div><div><h4 class="title"><a name="lf-type-tempo"></a>Tempo</h4></div></div></div><p>The tempo of music is entered as <code class="literal">bpm/beatlen</code>. The

following example will set the tempo to 120 beats per minute, each beat being a

quarter note.</p><pre class="programlisting">tempo = 120/4</pre></div></div><div class="sect2" title="Global variables"><div class="titlepage"><div><div><h3 class="title"><a name="Global-variables"></a>Global variables</h3></div></div></div><a class="indexterm" name="id2932852"></a><p>Global variables can save you a few key strokes.</p><pre class="programlisting">

quarter note.</p><pre class="programlisting">tempo = 120/4</pre></div></div><div class="sect2" title="Global variables"><div class="titlepage"><div><div><h3 class="title"><a name="Global-variables"></a>Global variables</h3></div></div></div><a class="indexterm" name="id332917"></a><p>Global variables can save you a few key strokes.</p><pre class="programlisting">

s = "\score\relative c'{ %s }

question {

# instead of music = music("\score\relative c'{ c d e f g2 g2 }")

ASSIGNMENT

...

}

</pre></div><div class="sect2" title="Header block"><div class="titlepage"><div><div><h3 class="title"><a name="Header-block"></a>Header block</h3></div></div></div><a class="indexterm" name="id2932900"></a><p>The header block can be placed anywhere in the file, but by convention

</pre></div><div class="sect2" title="Header block"><div class="titlepage"><div><div><h3 class="title"><a name="Header-block"></a>Header block</h3></div></div></div><a class="indexterm" name="id332960"></a><p>The header block can be placed anywhere in the file, but by convention

it should be the first block in the file. And there is a limitation that

the header has to be within the first 40000 characters of the file.</p><div class="variablelist" title="Variables shared by many exercise modules"><a name="lesson-header-vars"></a><p class="title"><b>Variables shared by many exercise modules</b></p><dl><dt><span class="term">

<code class="varname"><a name="lf-module"></a>module</code></span></dt><dd><p>Tell what execise module that will run the lesson file. This

variable is requried for all lesson files. (The variable was added in

<code class="varname"><a name="lf-module"></a>module</code></span></dt><dd><p>Tell what exercise module that will run the lesson file. This

variable is required for all lesson files. (The variable was added in

Solfege 2.9.0 where it replaced the <code class="varname">content</code>

variable.). Example:</p><pre class="programlisting">module = idbyname</pre></dd><dt><span class="term">

<span class="command"><strong>tools/hash-of-file.py</strong></span> can be used to get the hash value

of files before modifying them.</p><pre class="programlisting">replaces = "bf7dd374206451bff43d61fc8191f5fb3e88d007"

replaces = "bf7dd374206451bff43d61fc8191f5fb3e88d007", "cdb2f9415171650ee7682028788c1c42c62fdbf"

</pre></dd><dt><span class="term"><code class="literal"><a name="lf-lesson_id"></a>lesson_id</code></span></dt><dd><a class="indexterm" name="id2933266"></a><p class="remark"><i><span class="remark">This variable is deprecated in Solfege 3.15.3. It should remain in

</pre></dd><dt><span class="term"><code class="literal"><a name="lf-lesson_id"></a>lesson_id</code></span></dt><dd><a class="indexterm" name="id333061"></a><p class="remark"><i><span class="remark">This variable is deprecated in Solfege 3.15.3. It should remain in

existing lesson files for some time for backward compatability. But it should

not be added to new lesson files.</span></i></p><p>Each file need a unique identifier. The identifier can be any string

you like, and if you don't add one, Solfege will add one for you. Solfege

two files with identical <code class="literal">lesson_id</code>. Example:

</p><pre class="programlisting">lesson_id = "5b30c9ae-09f1-40b3-9333-4789638dc851"</pre></dd><dt><span class="term">

<code class="varname"><a name="lf-version"></a>version</code></span></dt><dd><p>

Tell the version of

solfege the lessonfile is known to work with. This variable is not

required, but it should be used because it can (but don't guarantee to)

Example:</p><pre class="programlisting">version = "3.0.7"</pre></dd><dt><span class="term">

<code class="varname"><a name="lf-title"></a>title</code></span></dt><dd><p>

100

Short one-line description that will be used for

101

creating the menu entry for the exercise. You should add this to all lesson

102

files. Example:</p><pre class="programlisting">title = "Minor and major chords in root position"</pre></dd><dt><span class="term">

103

104

<code class="varname"><a name="lf-lesson_heading"></a>lesson_heading</code></span></dt><dd><p>

105

105

106

A short heading that will be displayed above the exercise. It

107

should say what the purpose of the exercise is. Some modules provide a

108

default value, others leave the string empty. Example:</p><pre class="programlisting">lesson_heading = _("Identify the chord")</pre></dd><dt><span class="term">

109

110

111

111

112

This variable say which help file from the user manual will be

113

displayed when the user presses F1.

114

Example:</p><pre class="programlisting">help = "idbyname-intonation"</pre><p>By default, Solfege will display the help file that has the same

115

name as the exercise module being used in the lesson file.</p></dd><dt><span class="term">

116

117

<code class="varname"><a name="lf-theory"></a>theory</code></span></dt><dd><p>

118

118

119

This variable say which help file from the user manual will be

120

displayed when the user presses F3. Pressing F3 should display

121

music theory about the exercise. Don't include this variable if there

122

are no music theory written.

123

Example:</p><pre class="programlisting">theory = "scales/maj"</pre></dd><dt><span class="term">

124

125

<code class="varname">random_transpose</code></span></dt><dd><a class="indexterm" name="id2933469"></a><p>In some exercises the program can transpose the music to

125

<code class="varname">random_transpose</code></span></dt><dd><a class="indexterm" name="id333660"></a><p>In some exercises the program can transpose the music to

126

create variation. The default value is <code class="literal">yes</code>. (The

127

default value changed from <code class="literal">no</code> to

128

<code class="literal">yes</code> in Solfege 3.0.)</p><p>Used in modules: <code class="literal">chord</code>,

158

</p></dd><dt><span class="term">random_transpose = atonal, INTEGER1, INTEGER2</span></dt><dd><p>

159

Transpose the music at most INTEGER1 semitones down or INTEGER2

160

semitones up. Similar to <code class="literal">semitones</code>, but the

161

notes will be tranposed one by one, and the key will not change.

161

notes will be transposed one by one, and the key will not change.

162

</p></dd></dl></div></dd><dt><span class="term"><code class="literal">enable_right_click = no</code></span></dt><dd><p>By default, Solfege will let the user right-click on buttons to hear

163

the music they represent without guessing. Set this variable to

164

<code class="literal">no</code> for lesson files where it does not make sense, for

186

<code class="literal">singinterval</code>.</p></dd><dt><span class="term"><code class="varname"><a name="lf-intervals"></a>intervals</code></span></dt><dd><p>This variable tell which intervals should be asked for in exercises

187

using the <code class="literal">harmonicinterval</code> module. 1 for minor second, 2 for major

188

second, 3 or minor third etc. Example that will practise thirds:</p><pre class="programlisting">intervals = [3, 4]</pre><p>Modules: <code class="literal">harmonicinterval</code>.</p></dd><dt><span class="term">

189

189

190

This variable defines the test for the exercise. In a test,

191

Solfege will ask all the questions in the lesson file a number

192

of times.

198

and <code class="literal">singinterval</code>.</p></dd><dt><span class="term">

199

200

<code class="varname"><a name="lf-test_requirement"></a>test_requirement</code></span></dt><dd><p>

201

201

202

This variable defines how large percentage of the questions

203

has to be answered correctly to pass the test. Example:

204

</p><pre class="programlisting">test_requirement = "90%"</pre><p>Modules: <code class="literal">harmonicinterval</code>,

229

<code class="literal">elembuilder</code>.</p></dd><dt><span class="term">

230

231

<code class="varname"><a name="lf-at_question_start"></a>at_question_start</code>

232

232

233

234

<code class="literal"></code></span></dt><dd><p>This variable changes what happens when the user clicks

235

<span class="guibutton">New</span>. By default, Solfege will play the music when

251

will be used when the user clicks Show music or when the question is

252

answered correctly (if we have a musicdisplayer). Added to

253

<code class="literal">idbyname</code> in Solfege 2.5.1 and to

254

<code class="literal">elembuilder</code> in 3.9.2.</p><p>Modules: <code class="literal">idbyname</code> and <code class="literal">elembuilder</code>.</p></dd><dt><span class="term"><code class="literal"><a name="lf-rhythm_elements"></a>rhythm_elements</code></span></dt><dd><p>A list of integers (1-34) telling what elementes we should use when

254

255

creating questions. Example:</p><pre class="programlisting">rhythm_elements = 0, 1, 2, 3, 4</pre><p>

256

0:<span class="inlinemediaobject"><img src="../../graphics/rhythm-c4.png" alt="c4"></span> ,

257

1:<span class="inlinemediaobject"><img src="../../graphics/rhythm-c8c8.png" alt="c8 c8"></span> ,

301

name = "Lisa gikk til skolen"

302

music(...)

303

}

304

</pre><p>Music objects are documented in <a class="xref" href="lesson-files.html#music-object" title="music objects">« <code class="literal">music</code> objects »</a>.</p></dd><dt><span class="term"><code class="literal"><a name="lf-tempo"></a>tempo</code></span></dt><dd><p>Set the tempo for this questions music. The variable is defined

304

</pre><p>Music objects are documented in <a class="xref" href="lesson-files.html#music-object" title="music objects">« <code class="literal">music</code> objects »</a>.</p></dd><dt><span class="term"><code class="literal"><a name="lf-rhythm"></a>rhythm</code></span></dt><dd><p>If defined in a question, the rhythm of this music object is used

305

when comparing the users answer to the question. This can be useful if

306

the Solfege cannot find the rhythm of the question, for example when

307

the music object is a MP3 file.

308

</p><p>Used in modules: <code class="literal">rhythmtapping</code> and

309

<code class="literal">rhythmdictation.</code></p></dd><dt><span class="term"><code class="literal"><a name="lf-tempo"></a>tempo</code></span></dt><dd><p>Set the tempo for this questions music. The variable is defined

305

310

"beats per minute" / "notelen per beat". Example:</p><pre class="programlisting">tempo = 150 / 4</pre><p>This variable can also be defined globally for the whole lesson file.

306

311

Do do so you should put it in the beginning of the file, outside any

307

312

question blocks.</p><p>Modules: <code class="literal">idbyname</code>, <code class="literal">chord</code>,

308

<code class="literal">chordvoicing</code> and

309

<code class="literal">rhythmtapping</code>.</p></dd><dt><span class="term"><code class="literal">instrument</code></span></dt><dd><p>By default, Solfege will use the instrument specified on the

313

<code class="literal">chordvoicing</code>,

314

<code class="literal">rhythmdictation2</code> and

315

<code class="literal">rhythmtapping</code>.</p></dd><dt><span class="term"><code class="literal"><a name="lf-countin"></a>countin</code></span></dt><dd><p>A music object representing a count-in to be played before

316

the question. Only music objects that are parsed by the

317

<code class="literal">mpd</code> module can be used as count-in, and only

318

questions parsed by this module can have count-in. Example:</p><pre class="programlisting">tempo = rhythm("\time 4/4 d4 d d d")</pre><p>Entering the time signature is not necessary if the time

319

signature is 4/4, but for all other time signatures you must

320

include it.</p><p>Modules: <code class="literal">rhythmdictation</code> and

321

<code class="literal">rhythmdicatation2</code>

322

</p></dd><dt><span class="term"><code class="literal">instrument</code></span></dt><dd><p>By default, Solfege will use the instrument specified on the

310

323

<a class="link" href="preferences-window.html" title="Xanela de preferencias">preferences window</a> when playing questions. This variable let you select a different instrument. Example:

311

324

</p><pre class="programlisting">instrument = "cello", 100</pre><p>The instrument name has to be quoted. The integer is the volume,

312

325

and it should be in the range 0-127. You can see a list of

357

370

<span class="emphasis"><em>c</em></span> is translated to the midi sound <span class="emphasis"><em>Side

358

371

Stick</em></span> and <span class="emphasis"><em>d</em></span> to a <span class="emphasis"><em>Mute

359

372

triangle</em></span>.

360

</p><pre class="programlisting">variable = rhythm("d4 d d d c8 c8 c4")</pre><p>

361

</p></dd><dt><span class="term"><span class="bold"><a name="lfunc-rhythm"></a><strong>rhythm</strong></span>(<span class="emphasis"><em>musiccode</em></span>)</span></dt><dd><p>This music object let you write questions that taps rhythms with the

362

two instruments defined in the preferences window. The tone

363

<code class="literal">c</code> will play the rhythm representing the question,

364

and the tone <code class="literal">d</code> can be used if you want to write some

365

sort of "count-in" before the question starts. Example:</p><pre class="programlisting">rhythm("d4 d d d c8 c8 c4 c c8 c8")</pre><p>You should only use two pitches, <code class="literal">c</code> and

373

</p><pre class="programlisting">variable = percussion("d4 d d d c8 c8 c4")</pre><p>

374

375

two percussion instruments defined in the preferences window. The tone

376

<code class="literal">c</code> will play with the instrument intended for the

377

question and <code class="literal">d</code> will use the instrument

378

intended for count off. Example:</p><pre class="programlisting">rhythm("d4 d d d c8 c8 c4 c c8 c8")</pre><p>You should only use two pitches, <code class="literal">c</code> and

366

379

<code class="literal">d</code>. Other pitches will print a warning, but will still

367

380

work in the current implementation. To play real percussion with many

368

381

different instruments you should use the <a class="xref" href="lesson-files.html#lfunc-percussion">percussion</a> music object.</p></dd><dt><span class="term"><span class="bold"><a name="lfunc-midifile"></a><strong>midifile</strong></span>(<span class="emphasis"><em>filename</em></span>)</span></dt><dd><p>Play a midi file. The path given to the file

413

426

divide each chord in 3 parts and give them different font sizes, and also try

414

427

to make the chord compact, so that it should not take too much space on

415

428

screen.</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>The first part of the chord is the roman numberal, including

416

an optional <code class="literal">b</code> or <code class="literal">♭</code>

417

(unicode character <code class="literal">U+266D MUSIC FLAT SIGN</code>).

429

an optional <code class="literal">b</code>, <code class="literal">♭</code>

430

(unicode character <code class="literal">U+266D MUSIC FLAT SIGN</code>),

431

432

(unicode character <code class="literal">U+266F MUSIC SHARP SIGN</code>).

418

433

</p></li><li class="listitem"><p>The second part is the letters (if any) between the first

419

434

and the third part.</p></li><li class="listitem"><p>The third part is from the first digit and the rest of the

420

435

chord.</p></li></ul></div><pre class="programlisting">rnc("Imaj7-IIm7-V9-Imaj7")</pre><div class="informalfigure"><a name="fig-rnc"></a><div class="screenshot"><div class="mediaobject"><img src="../C/figures/rnc-example.png"></div></div></div><p>Spaces are not allowed in the chord name.</p><p>New in version 3.11.0.</p></li><li class="listitem"><p class="fdef"><a name="lfunc-chordname"></a><code class="literal">chordname(<em class="replaceable"><code>str</code></em>)</code></p><p>Display a sequence of chords. The chords are separated by whitespace.

Older »