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:

• Piano Keyboard
• Music Note
  • Eighth Note
  • Quarter Note
  • Half Note
  • Whole Note
• Musical Staff
  • Bass Clef
  • Treble Clef

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.

Beth Hadley welcomes comments, ideas, contributions, and questions regarding the gcomprismusic module or GCompris music activities. Send her an email at 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.

• create your new activity (see Beginner if you need help)
• open init_path.sh and find the pythonplugindir line. Replace this line with something like:

   pythonplugindir=$path/../piano_composition-activity:$path/../name_of_your_activity-activity
  

  save and close this file
• add a resources folder to your activity folder
• 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 piano_composition folder and paste that into your resources folder
• open the python file for your activity, name_of_your_activity, and find at the top where all the import statements are. add the following line to the import statements:

  from gcomprismusic import *
  

• 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.

Using The Module

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

Musical Notes

• Each note is assigned a number, stored internally as numID This is to prevent issues with converting between different language translations of note names. Each note is also assigned a color, according to NOTE_COLOR_SCHEME The following table represents this:

  English Name	Northern European Name	numID	Color
  C	C	1
  C sharp / D flat (C♯ / D♭)	Cis / Des	-1
  D	D	2
  D sharp / E flat (D♯ / E♭)	Dis / Es	-2
  E	E	3
  F	F	4
  F sharp / G flat (F♯ / G♭)	Fis / Ges	-3
  G	G	5
  G sharp / A flat (G♯ / G♭)	Gis / As	-4
  A	A	6
  A sharp / B flat (A♯ / B♭)	Ais / B	-5
  B	H	7
  C (higher octave)	C (higher octave)	8

  
  

• getKeyNameFromID(numID, sharpNotation=True)

      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
  

Musical Staff

Staff Formatting Attributes

Attribute Name	Default Value	Description
endx	390	rightend location of staff lines
verticalDistanceBetweenStaves	115	vertical distance between musical staves
staffLineSpacing	13	vertical distance between lines in staff
staffLineThickness	2.0	thickness of staff lines
numStaves	from __init__	number of staves to draw




Music Notation Formatting

Attribute Name	Default Value	Description
initialNoteX	30	starting X position of first note
noteSpacingX	26	#distance between each note when appended to staff
currentLineNum	1	the line number you're currently writing notes to
currentNoteType	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

Attribute Name	Default Value	Description
initialNoteX	30	starting X position of first note
colorCodeNotes	True	color notes according to NOTE_COLOR_SCHEME
labelBeatNumbers	False	label the beat numbers for each note above the note (used in play_rhythm-activity)
drawPlayingLine	False	draw vertical line on staff to follow the beat as the composition is being played
notReadyToPlay	False	#set to True when staff is not ready to play composition (something else is going on for example)
noteList	[]	list of note objects written to staff

Methods

• drawStaff()

  draw the staff, including staff lines and staff clefs
  
  >>> self.newStaff = TrebleStaff(100, 80, self.rootitem, numStaves=4)
  >>> self.newStaff.drawStaff(self)
  

• drawNote(self,note)

  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.
  
  >>> 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))