View source for Adding a music activity and using gcomprismusic.py module

If you wish to add an activity relating to music to gcompris, consider importing the module gcomprismusic.py This module contains several useful classes of objects that will not only make it easier for you to make your activity, but also help GCompris maintain a more uniform music platform.

The following music objects are currently included in the module:

* Musical Staff
** Bass Clef
** Treble Clef
* Music Note
** Eighth Note
** Quarter Note
** Half Note
** Whole Note
* Piano Keyboard
* General Utility Functions

The module was developed in 2012 by Beth Hadley through Google Summer of Code. It can always be improved, added to, and adjusted.

The documentation provided below will help you get started using the module. It provides coding examples, with pictures, that will help you create music objects. Not all, but most, methods and properties are documented.

Beth Hadley welcomes comments, ideas, contributions, and questions regarding the gcomprismusic module or GCompris music activities. Bug reports are welcome as well, file on GCompris' bug tracker or send me an email. (bethmhadley@gmail.com)

== How to import the gcomprismusic module ==
The gcomprismusic.py module is located in the piano_composition-activity. There are certain resources that support the module, and these are permanently located under the resources folder of the piano_composition activity. Thus, you must execute the following instructions to properly import the gcomprismusic module.
<ul>
<li> create your new activity (see [[Beginner]] if you need help)</li>
<li> open init_path.sh and find the <code> pythonplugindir</code> line. Replace this line with something like:
<pre> pythonplugindir=$path/../piano_composition-activity:$path/../name_of_your_activity-activity
</pre>
save and close this file </li>
<li> add a resources folder to your activity folder 
<li> create a symbolic link in this resources folder that references the piano_composition resources file. If you are unsure of this step, just go into the play_piano activity folder, click on resources, and copy the <code>piano_composition</code> folder and paste that into your resources folder 
<li> open the python file for your activity, <code>name_of_your_activity</code>, and find at the top where all the import statements are. add the following line to the import statements:
<pre>
from gcomprismusic import *
</pre>
</li>
<li> run your activity, and ensure that it works (you should see a screen that says "This is the first plugin in GCompris coded in the Python Programming language." If there are errors, enjoy troubleshooting or contact Beth.</li>
</ul>

== General Reference ==
Once you've imported the module, you may call or invoke all methods and classes. Instructions and examples are provided below for your reference.

<ul>
<li> Each note is assigned a number, stored internally as <code>numID</code> This is to prevent issues with converting between different language translations of note names. Each note is also assigned a color, according to <code>NOTE_COLOR_SCHEME</code> Unfortunately. currently only two octaves of notes are supported (bass clef C in the staff to treble clef C in the staff). Future improvements may include expanding the pitch possibilities to include both higher and lower notes. This is not difficult (I could do it if an activity needed it, and may prove to be a good task for an eager beginner). 
The following table represents the currently available notes:
{| class="wikitable"
|-
! English Name
! Northern European Name
! numID
! Color
|-
| C
| C
| 1
| <div style="background-color:#FF0000;width:20px;height:20px"></div>
|-
| C sharp / D flat (C♯ / D♭)
| Cis / Des
| -1
| <div style="background-color:#FF6347;width:20px;height:20px"></div>
|-
| D
| D
| 2
| <div style="background-color:#FF7F00;width:20px;height:20px"></div>
|-
| D sharp / E flat (D♯ / E♭)
| Dis / Es
| -2
| <div style="background-color:#FFD700;width:20px;height:20px"></div>
|-
| E
| E
| 3
| <div style="background-color:#FFFF00;width:20px;height:20px"></div>
|-
| F
| F
| 4
| <div style="background-color:#32CD32;width:20px;height:20px"></div>
|-
| F sharp / G flat (F♯ / G♭)
| Fis / Ges
| -3
| <div style="background-color:#20B2AA;width:20px;height:20px"></div>
|-
| G
| G
| 5
| <div style="background-color:#6495ED;width:20px;height:20px"></div>
|-
| G sharp / A flat (G♯ / G♭)
| Gis / As
| -4
| <div style="background-color:#8A2BE2;width:20px;height:20px"></div>
|-
| A
| A
| 6
| <div style="background-color:#D02090;width:20px;height:20px"></div>
|-
| A sharp / B flat (A♯ / B♭)
| Ais / B
| -5
| <div style="background-color:#FF00FF;width:20px;height:20px"></div>
|-
| B
| H
| 7
| <div style="background-color:#FF1493;width:20px;height:20px"></div>
|-
| C (higher octave)
| C (higher octave)
| 8
| <div style="background-color:#FF0000;width:20px;height:20px"></div>
|-
|}


<li> '''getKeyNameFromID(numID, sharpNotation=True)'''
<pre>
get the name of the key that corresponds to the numID given. optionally set sharpNotation = True for sharp notation, or sharpNotation = False for flat notation

>>> getKeyNameFromID(1)
C
>>> getKeyNameFromID(-3, sharpNotation=True)
F#
>>> getKeyNameFromID(-5, sharpNotation=False)
Bb
</pre>
</li>

<li> '''getIDFromKeyName(keyName)'''
<pre>
get the name of the key that corresponds to the numID given

>>> getIDFromKeyName('C')
1
>>> getIDFromKeyName('D#')
-2
>>> getIDFromKeyName('Eb')
-2
</pre>
</li>
</ul>

== Staff Classes ==
There are two  staff subclasses, both of which inherit from the master Staff Class:
* TrebleStaff
* BassStaff

To create these objects, the __init__ functions require the following arguments:
# <code>x</code>: starting x position of the staff
# <code>y</code>: starting y position of the staff
# <code>canvasRoot</code>: the rootitem of the canvas
# <code>numStaves</code>: the number of staves you'd like to create

An example of instantiating each object is below. Note that you must call the drawStaff() method to draw the staff to the canvas.

<pre>
>>> self.staff1 = TrebleStaff(50, 30, self.rootitem, numStaves=1)
>>> self.staff2 = BassStaff(50, 130, self.rootitem, numStaves=2)
</pre>

=== Staff Formatting Attributes ===

{| class="wikitable"
|-
! Attribute Name
! Default Value
! Description
|-
| <code>endx</code>
| 390
| width of staff lines
|-
| <code>verticalDistanceBetweenStaves</code>
| 115
| vertical distance between musical staves
|-
| <code>staffLineSpacing</code>
| 13
| vertical distance between lines in staff
|-
| <code>staffLineThickness</code> 
| 2.0
| thickness of staff lines
|-
| <code>numStaves</code>
| from __init__
| number of staves to draw
|}

=== Music Notation Formatting ===

{| class="wikitable"
|-
! Attribute Name
! Default Value
! Description
|-
| <code>initialNoteX</code>
| 30
| starting X position of first note
|-
| <code>noteSpacingX</code>
| 26
| distance between each note when appended to staff
|-
| <code>dynamicNoteSpacing</code>
| False
| adjust note spacing according to space needed by each note
|-
| <code>currentLineNum</code>
| 1
| the line number you're currently writing notes to
|-
| <code>currentNoteType</code> 
| 4
| the note type you're currently using to write to the musical staff, could be 4 (quarter), 8 (eighth), 2 (half) or 1 (whole)
|}

=== Note & Playback ===

{| class="wikitable"
|-
! Attribute Name
! Default Value
! Description
|-
| <code>initialNoteX</code>
| 30
| starting X position of first note
|-
| <code>colorCodeNotes</code>
| True
| color notes according to <code>NOTE_COLOR_SCHEME</code>
|-
| <code>labelBeatNumbers</code>
| False
| label the beat numbers for each note above the note (used in <code>play_rhythm-activity</code>)
|-
| <code>drawPlayingLine</code> 
| False
| draw vertical line on staff to follow the beat as the composition is being played
|-
| <code>notReadyToPlay</code> 
| False
| #set to True when staff is not ready to play composition (something else is going on for example)
|-
| <code>noteList</code>
| <code>[]</code>
| list of note objects written to staff
|-
| <code>staffName</code>
| 'trebleClef' or 'bassClef'
| name of the staff
|-
| <code>positionDict</code>
| {set values}
| a dictionary mapping the notes to the appropriate y coordinate on the staff
|}

=== Methods ===
====<code>drawStaff()</code>====
: draw the staff, including staff lines and staff clefs
<pre>
     self.newStaff = TrebleStaff(100, 80, self.rootitem, numStaves=4)
     self.newStaff.drawStaff(self)
</pre>
[[File:trebleclefstaff.png|550 px]]

   
====<code>drawNote(self,note)</code>====
: determine the correct x & y coordinate for the next note, and writes this note as an image to the staff. An alert is triggered if no more room is left on the staff. Color-codes the note or draws beat numbers if appropriate.
<pre>
     self.newStaff = TrebleStaff(50, 50, self.rootitem, numStaves=4)
     self.newStaff.drawStaff()
     self.newStaff.drawNote(QuarterNote(1, 'trebleClef', self.newStaff.rootitem))
     self.newStaff.drawNote(EighthNote(5, 'trebleClef', self.newStaff.rootitem))
     self.newStaff.drawNote(WholeNote(-3, 'trebleClef', self.newStaff.rootitem))
</pre>
[[File:withnotes.png|550 px]]
 

====<code>writeLabel(self, text, note)</code>====
: writes the text below the note, such as labeling the note name, in color-code if self.colorCodeNotes = True
<pre>
     self.newStaff = TrebleStaff(50, 50, self.rootitem, numStaves=1)
     self.newStaff.endx = 200
     self.newStaff.rootitem.scale(2.0, 2.0)
     self.newStaff.drawStaff()
     n2 = HalfNote(5, 'trebleClef', self.newStaff.rootitem)
     self.newStaff.drawNote(n2)
     self.newStaff.writeLabel('G', n2)
</pre>
[[File:labelNote.png|550 px]]


====<code>eraseOneNote(self, widget=None, target=None, event=None)</code>====
: removes the last note in the staff's noteList, updates self.currentLineNum if necessary, and updates self.currentNoteXCoordinate
<pre>
     self.newStaff.eraseOneNote()
</pre>

====<code>eraseAllNotes(self, widget=None, target=None, event=None)</code>====
: remove all notes from staff, deleting them from self.noteList, and restores self.currentLineNumto 1 and self.currentNoteXCoordinate to the starting position
<pre>
     self.newStaff.eraseAllNotes()
</pre>

====<code>clear(self, widget=None, target=None, event=None)</code>====
: clear all notes and clefs on the staff (for preparation of a clef change)
<pre>
     self.newStaff.clear()
</pre>
[[File:clear.png|550 px]]

====<code>playComposition(self, widget=None, target=None, event=None, playingLineOnly=False)</code>====
: plays entire composition. establish timers, one per note, called after different durations according to noteType. Only way to stop playback after calling this method and during play is self.eraseAllNotes()
<pre>
     self.newStaff.playComposition()
</pre>


====<code>stringToNotation(self, melodyString)</code>====
: parse the melody string and write the notes to the staff. The melody must be in a very simple format. It is one line, and begins the clef, either 'trebleClef' or 'bassClef' Then, each following note is seperated with a space and the note name (English system, sharp=#,flat=b, C (second octave is 2C rather than just C) written first followed by the note duration (8=eighth,4=quarter,2=half,1=whole)
<pre>
     self.staff1 = TrebleStaff(50, 30, self.rootitem, numStaves=1)
     self.staff1.endx = 200
     self.staff1.rootitem.scale(2.0, 2.0)
     self.staff1.drawStaff()
     self.staff1.stringToNotation('trebleClef C4 G2 F#4 Ab4 2C2')

     self.staff2 = BassStaff(50, 130, self.rootitem, numStaves=1)
     self.staff2.endx = 200
     self.staff2.rootitem.scale(2.0, 2.0)
     self.staff2.drawStaff()
     self.staff2.stringToNotation('bassClef Eb2 F4 C#8 Bb4 C2')
</pre>

[[File:stringtonotes.png|550 px]]

====<code>file_to_staff(self, filename)</code>====
: open text file, read contents and write to staff  
<pre>
     self.newStaff.file_to_staff('/dir/to/name_of_text_file.txt')  
</pre>


====<code>staff_to_file(self)</code>====
: convert staff to notation, write to text file, save to MyGCompris folder  
<pre>
     self.newStaff.staff_to_file()  
</pre>


====<code>drawScale(self, scaleName, includeNoteNames=True)</code>====
: return a note's vertical coordinate based on the note's name. This is unique to each type of clef (different for bass and treble). ScaleNames currently supported: 'C Major'
<pre>
     self.staff2 = TrebleStaff(50, 50, self.rootitem, numStaves=1)
     self.staff2.endx = 300
     self.staff2.rootitem.scale(2.0, 2.0)
     self.staff2.drawStaff()
     self.staff2.drawScale('C Major')
</pre>

[[File:treblescale.png|550 px]]

====<code>colorCodeAllNotes(self)</code>====
: color notes according to <code>NOTE_COLOR_SCHEME</code>
<pre>
     self.newStaff.colorCodeAllNotes()
</pre>

====<code>colorCodeAllNotes(self)</code>====
: color notes according to <code>NOTE_COLOR_SCHEME</code>
<pre>
     self.newStaff.colorCodeAllNotes()
</pre>

====<code>colorAllNotes(self, color)</code>====
: color all notes a certain color ('black', 'red', 'blue', etc.)
<pre>
     self.newStaff.colorAllNotes('black')
</pre>

====<code>getNoteXCoordinate(self)</code>====
: determines the x coordinate of the next note to be written to the staff, with consideration for the maximum staff line length. Increments <code>self.currentLineNum</code> and sets <code>self.currentNoteXCoordinate</code>

====<code>getNoteYCoordinate(self)</code>====
: return a note's vertical coordinate based on the note's name. This is unique to each type of clef (different for bass and treble)

== Note Classes ==
There are four types of notes classes, all of which subclass the <code>Note</code> class.
* Eighth Note
* Quarter Note
* Half Note
* Whole Note

To create these objects, the __init__ functions require the following arguments:
* <code>numID</code>: The numerical id number that corresponds to this note (see table above for note number correspondance)
* <code>staffType</code>: 'trebleClef' or 'bassClef', whichever clef this note will belong to
* <code>rootitem</code>: the rootitem of the canvas where you'd like this note to appear (use the staff's rootitem if you'd like the note to appear in the staff)
* <code>sharpNotation=True</code>optional argument, pass in False if you'd like this note to always display with flat notation. Default is to display with flat notation

An example of creating notes (these will not appear on the page until you call the draw() method)
<pre>
>>> n8 = EighthNote(1, 'trebleClef', self.rootitem)
>>> n4 = QuarterNote(1, 'trebleClef', self.rootitem)
>>> n2 = HalfNote(1, 'trebleClef', self.rootitem)
>>> n1 = WholeNote(1, 'trebleClef', self.rootitem)
</pre>
[[File:notes.png|550 px]]

Each note has an x and y coordinate, set to 0,0 initially but updated when it is drawn to the canvas.
{| class="wikitable"
|-
! Property Name
! Value(s)/Default
! Description
|-
| x
| 0
| x-position of note when written to canvas (updated when .draw() is called
|-
| y
| 0
| y-position of note when written to canvas (updated when .draw() is called
|-
| staffType
| from __init__
| the staffType ('trebleClef' or 'bassClef' this note corresponds to
|-
| sharpNotation
| from __init__
| toggle to switch note between sharp notation and flat notation, if applicable
|-
| noteType
| <code>Eighth:8, Quarter:4,Half:2, Whole:1</code>
| the number that corresponds to the note name
|-
| beatNums
| <code>Eighth:['+'],Quarter:['1'],Half:['1','2'],Whole:['1','2','3','4']</code>
| the beat numbers that correspond to the notes
|-
| millisecs
| <code>Eighth:250, Quarter:500,Half:1000, Whole:2000</code>
| millisecond length of each note (for use during composition playback
|}


=== Methods ===

====<code>draw(self, x,y)</code>====
: places note image in canvas at x,y
<pre>
     n2 = QuarterNote(5, 'trebleClef', self.rootitem)
     n2.rootitem.scale(2.0, 2.0)
     n2.draw(100, 100)
</pre>
[[File:noteoncanvas.png|550 px]]

====<code>play(self, widget=None, target=None, event=None)</code>====
: plays the note pitch. Each pitch is stored in the resources folder as an .ogg file (these are not synthesized)
<pre>
     self.newStaff = TrebleStaff(100, 80, self.rootitem, numStaves=4)
     self.newStaff.drawStaff(self)
</pre>
[[File:trebleclefstaff.png|550 px]]

====<code>color(self, color)</code>====
: color the note a certain color ("black", "blue", or html tags)

====<code>colorCodeNote(self)</code>====
: color the note the appropriate color based on the given color scheme

====<code>enablePlayOnClick(self)</code>====
: enables the function that the note will be played when the user clicks on the note

====<code>disablePlayOnClick(self)</code>====
: disables the function that the note will be played when the user clicks on the note (same as self.silent=True)

====<code>highlight(self)</code>====
: highlight the note for self.millisecs, then revert (used during playback)

[[File:highlightednote.png|550 px]]

====<code>remove(self)</code>====
: remove the note (delete the note's rootitem)

== PianoKeyboard Class ==
This is an object representing one-octave of a piano keyboard

To create a PianoKeyboard, the <code>__init__</code> function takes:
# <code>x</code>: The x coordinate of the keyboard
# <code>y</code>: The y coordinate of the keyboard
# <code>canvasroot</code>: The rootitem of the canvas

The PianoKeyboard class has the following attributes:
{| class="wikitable"
|-
! Attribute Name
! Value/Default
! Description
|-
| blackKeys
| False
| include black keys as buttons
|-
| whiteKeys
| True
| include white keys as buttons
|-
| sharpNotation
| True
| use sharp notation when labeling keys and writing notes to staff
|-
| colors
| dictionary set to <code>NOTE_COLOR_SCHEME</code>
| the colors to use for each key, default set the same as the note's color scheme
|}

=== Methods ===
====<code>draw(self, width, height, key_callback)</code>====

: draw the staff, including staff lines and staff clefs
<pre>
     def keyboard_button_press(self, widget=None, target=None, event=None):
         pass
     p = PianoKeyboard(50, 50, self.rootitem)
     p.draw(300, 200, keyboard_button_press)
</pre>
[[File:pianokeyboard.png|500 px]]

: or before drawing, use:
<pre>
     p.blackKeys=True
</pre>
[[File:keyboardblackkeys.png|550 px]]

: or before drawing, use:
<pre>
     p.sharpNotation=False
</pre>
[[File:keyboardflatblackkeys.png|550 px]]

== General Utility Functions ==
These are just a few methods I wrote that I used quite often throughout my activities, that might be useful to you.

===<code>textButton(x, y, text, self, color='gray', width=100000)</code>===
: Add a text button to the screen with the following parameters
:: <li> <code>x</code>: the x position of the button
:: <li> <code>y</code>: the y position of the button
:: <li> <code>text</code>: the text of the button
:: <li> <code>self</code>: the self object this button is to be written to (just pass 'self')
:: <li> <code>color</code>: the color of button you'd like to use. Unfortunately there
<pre>
     textButton(200, 300, 'Hello World!', self, color='brown')
     textButton(350, 300, 'Hola', self, color='darkpurple')
     textButton(500, 300, 'Ciao', self, color='gray')
     textButton(650, 300, 'Bonjour', self, color='green')
     textButton(200, 400, 'Guten Tag', self, color='purple')
     textButton(350, 400, 'Nei Ho', self, color='red')
     textButton(500, 400, 'Zdravstvuyte', self, color='teal', width=70)
</pre>

[[File:textButtons.png|550 px]]

===<code>textBox(text, x, y , self, width=10000, fill_color=None, stroke_color=None, noRect=False, text_color="black")</code>===
: write a textbox with text to the screen. By default the text is surrounded with a rectangle. Customize with the following parameters:
:: <li> <code>text</code>: the text to write
:: <li><code>x</code>: the x position of the text
:: <li><code>y</code>: the y position of the text
:: <li><code>self</code>: the self object this text is to be written to (just pass 'self')
:: <li><code>width</code>: the width limit of the text
:: <li><code>fill_color</code>: the color to fill the rectangle
:: <li><code>stroke_color</code>: the color to make the rectangle lines
:: <li><code>noRect</code>: set to true for no rectangle to be drawn
:: <li><code>text_color</code>: the color of the text, accepted colors include string html color tags or english names
<pre>
     textBox('Hello World!', 200, 300, self)
     textBox('Hola', 350, 300, self, fill_color='green')
     textBox('Ciao', 500, 300, self, stroke_color='pink')
     textBox('Bonjour', 650, 300, self, noRect=True)
     textBox('Nei Ho', 350, 400, self, text_color='red')
     textBox('Guten Tag', 200, 400, self, width=10)
     textBox('Zdravstvuyte', 500, 400, self, fill_color='#FF00FF')
</pre>

[[File:textBoxes.png|550 px]]

===<code>ready(self, timeouttime=200)</code>===
: function to help prevent "double-clicks". If your function call is suffering from accidental system double-clicks, import this module and write these lines at the top of your method:
<pre>
     if not ready(self):
        return False
</pre>

===<code>displayIncorrectAnswer(self, nextMethod)</code>===
: displays the sad note for 900 milliseconds, then calls <code>nextMethod</code> (very similar to GCompris' bonus, but uses a sad note instead and has a few more tweaks

[[File:sadNote.png|550 px]]

===<code>displayYouWin(self, nextMethod)</code>===
: displays the happy note for 900 milliseconds, then calls nextMethod (very similar to GCompris' bonus, but uses a happy note instead and has a few more tweaks

[[File:happyNote.png|550 px]]

===<code>displayIncorrectAnswer(self, nextMethod)</code>===
: displays the sad note for 900 milliseconds, then calls nextMethod (very similar to GCompris' bonus, but uses a sad note instead and has a few more tweaks

===<code>pianokeyBindings(keyval, self)</code>===
: nice key bindings for the piano keys (see table mapping keys to functions below). In your activity's key_press method, call this method and pass in the keyval and self:
<pre>
     def key_press(self, keyval, commit_str, preedit_str):
         utf8char = gtk.gdk.keyval_to_unicode(keyval)
         pianokeyBindings(keyval, self)
</pre>

{| border="1"
|+ Key Bindings
|-
! Computer Keyboard Key
| 1 || 2 || 3 || 4 || 5 || 6 || 7 || 8 || F1 || F2 || F3 || F4 || F5
|-
! Piano Key
| C || D || E || F || G || A || B || C (higher octave) || C♯ / D♭  || D♯ / E♭ || F♯ / G♭ || G♯ / A♭ || A♯ / B♭
|-
|}

[[Category:English]]