Home pageMusic Notation SDKMIDI TutorialMusic Data Structures

Music Notation SDK Level II - Detailed API description

The Music Notation SDK Level II contains an additional set of API to create and modify the details of the music content of measures and staves. You will find here a detailed specification of them, so that you can better understand what you can do with it and how easily you can do it.

All API functions returns an error code (0 if no error occur). You should always check the return value and take appropriate action accordingly. Ignoring the return value may produce unexpected results later.

The final documentation included when you buy the SDK contains more implementation details, for instance the exact parameters of each function (these are not described on this page).

Please note that there is also the possibility for you to make a list of specific modules as described below and/or a set of individual functions and submit it to us for a quote on a custom-made SDK that will fit your application's need with a better quality/price compromise. Send your list or specification to:

info@arpegemusic.com

and we will soon answer to you with a proposition.

For any question you may have about the interface, you can always contact me at the same e-mail address.

Section A - Creating and structuring a document

MNLCreateDocument(...)

Creates a new document, with the number of staves and measures specified. The document is create in linear mode, with no page layout. The document identifier is returned so that you can use it to further manipulate the document. The number of measures multiplied by the number of staves must be less then 32000. There must be at least one measure and one staff.

MNLInsertMeasures(...)

This music notation SDK function inserts measures before an existing measure number. If the first measure is 1, then the measures are inserted before the existing measure 1. If the first measure is greater than the total number of existing measures, then the measures are added after the last measure of the score. The total number of measures multiplied by the number of staves must stay less then 32000. The measures are added to all staves as all staves must contain the same number of measures.

MNLRemoveMeasures(...)

This music notation SDK function removes measures starting at the specified measure number. The content of these measures is lost. The measures are removed on all staves. At least one measure must be left in the score (you can not remove all measures).

MNLInsertStaves(...)

This music notation SDK function inserts staves before the existing staff number. If the number is 1, then the staves are inserted before the existing staff 1. If the number is greater than the total number of existing staves, then the staves are added after the last staff. The total number of measures multiplied by the total number of staves must stay less then 32000.

MNLRemoveStaves(...)

This music notation SDK function removes staves starting at the given staff. The content of these staves is lost. At least one staff must stay in the score (you cannot remove all staves).

MNLGetMeasureWidth(...)

This music notation SDK function returns in the width (in pixels) of the given measure, for a scaling factor of 100 % in page mode. If no page layout has been defined, the width returned is the default width used in linear mode.

MNLSetMeasureWidth(...)

This music notation SDK function sets the width (in pixels) of a measure,for a scaling factor of 100 %. This value is applied for the page layout as well as for the linear mode. The value must stay within a reasonable range, otherwise the function may return an error.

MNLGetBarLinesInfo(...)

This music notation SDK function retrieves the information about the bar lines and repeat parameters of the given measure. leftBarLine andrightBarLine respectively return the type of bar line present on the left and right part of the measure, according to the following table:

  • 0 = no bar (invisible)
  • 1 = thin bar
  • 2 = thick bar
  • 3 = double thin bar
  • 4 = thin + thick bar
  • 5 = repeat bar

The table for simulation of repeat contains 10 values. According to these values, the SDK decides which measure to play next. In the normal course of playback of the score, after the measure is played for the first time, the value of repeatTable[0] is used to determine which is the next measure to play. If the value is zero (default value) then the playback continues to the next measure. If the value is non zero, then the playback continues to measure number repeatTable[0]. The value ofrepeatTable[1] is used to determine which measure to play after that measure is played for the second time. The same happens withrepeatTable[2 - 8] and the value repeatTable[9] is used for specifying the next measure to be played after the 10th and next playbacks of that measure. In this way, the playback of repeats may be simulated. A value of -1 in the repeat table means that the playback should stop after that measure. This is a way to make a score repeat pattern where the score stops playing in a measure that is different from the last measure.

MNLSetBarLinesInfo(...)

This music notation SDK function specifies the information about the bar lines and repeat parameters of the given measure. leftBarLine andrightBarLine respectively define the type of bar line present on the left and right parts of the measure, as explained in the previous function.

repeatTable specifies the table of playback jumps, to be used to simulate the playback of repeats as explained in the previous function. You are responsible to make the display and the playback parameters fit, so that the resulting playback stays logical.

Section B - Handling the page layout

MNLGetPageLayout(...)

This music notation SDK function is used to retrieve information about the page layout. A page layout is made out of a number of pages and each page is made out of a certain number of systems. Each system is made out of a certain number of measures.

First call the function with systemTable = NULL and pageTable = NULL. This will return the total number of systems (for all pages) in totSystemsand the total number of pages in totPages. You can then allocate a table of long integers for the two tables, like this:

systemTable = (long *) malloc(totSystems * sizeof(long));
pageTable = (long *) malloc(totPages * sizeof(long));

Then call the function again, using the two allocated tables. If no error occurs, the systemTable will be filled with the number of measures present in each system (for all pages). pageTable will be filled with the number of systems present in each page.

For example, if you have a score of two pages, each one containing 5 systems of 4 measures, the two tables will be :

systemTable = { 4, 4, 4, 4, 4, 4, 4, 4, 4, 4 }
pageTable = { 5, 5 }

If you set totSystems and/or totPages to a lower value than the table dimensions, the function will only fill the tables up to these values, so as to avoid overflowing the tables.

MNLSetPageLayout(...)

This music notation SDK function is used to create the structure of a new page layout. The parameters used are explained in the previous function. The total number of measures present in the score must fit the content ofsystemTable and the total number of systems (which is totSystems) must fit the content of pageTable so that no measure or no system is left unused. A page may have no system in it (blank page), but a system must at least have one measure.

With this function, you are fully responsible for the resulting layout. If you try for instance to put 50 measures in one system, the resulting display can be quite confusing. You can (and should) combine this function with MNLGetMeasureWidth, MNLSetMeasureWidth as well asMNLGetSystemInfo and MNLSetSystemInfo to adjust the page layout.

If alignHorizontally is true, then the function will display the pages with the measures horizontally aligned on the margins, which means that the measures will be adjusted to fit the width of the page. If you set this option and if you set too much measures in a system, they may appear badly as they will be squeezed accordingly.

The size of the paper, the margins and the scale, as well as the staves and chords to display are defined as explained in MNLNewPageLayout.

You can also use MNLNewPageLayout to create a page layout that is based on the real content of the measures.

MNLGetSystemInfo(...)

This music notation SDK function is used to retrieve the position of a system inside the page, in posX and posY, as well as the distances between its staves, in staffDeltaTable. These values are returned in pixels. staffDeltaTable must have the size of the number of staves. The first value (staffDeltaTable[0] ) will be the distance between the top of the system and the top of the first staff. By default, it has a value of 24 pixels. The next values will be the vertical distances from the top of a staff to the top of the previous staff.

pageNumber is the page number and systemNumber is the index of the system within the page.

The origin point used for posX and posY is the upper left corner of the page margins.

MNLSetSystemInfo(...)

This music notation SDK function is used to specify the position of a system inside its page, to posX and posY, as well as the distances between staves, from staffDeltaTable. These values are specified in pixels and are described in the previous function.

pageNumber is the page number and systemNumber is the index of the system within the page.

MNLGetStaffParameters(...)

This music notation SDK function will return the parameters of staffstaffIndex (from 1 to the total number of staves) inside document docID. The parameters are returned in the structure pointed to by params and contains mainly the following information:

  • Name of the staff, displayed in front of the staff on the first system
  • Name of the staff, displayed in front of the staff on all systems except the first
  • Vertical position of the name displayed in front of the staff
  • Size of staff, default is 100 %, it affects the height of the staff
  • staffLines : Each bit specifies the presence of a line, in a set of 16 possible lines. The standard 5 lines staff value is 0x07C0.
  • attachBars : if TRUE, then the bar lines of this staff will join the next staff vertically
  • Midi channel used for the notes of the staff, 0 to 15
  • MIDI transposition that is applied when playing the notes of this staff. Value is in semitones, positive or negative.
  • Default velocity for playing the notes that do not have a velocity defined. Value must be between 1 and 127.
  • A table of all controllers, as they are sent before starting to play the measures. Values are from 0 to 127. A value of 255 (0xFF) will prevent any control value from being sent. These are the standard MIDI controllers (7 is volume,...)
  • Midi value of the program change information for instrument selection, from 0 to 127
  • Value of pitch bend sent before playing the staff
  • staccatoValue : 100 % by default, which means that the note that do not have a specified MIDI duration, will be played at the duration given here, computed on the base of their graphic rhythmic value. For instance, a quarter note will be played with an eighth note duration if this parameter is set to 50 %
  • playStaff : Default is TRUE, which means that this staff is played. A value of FALSE will mute this staff
  • playVoices : Bits 0 to 7 specifies if rhythmic voices from 1 to 8 are played of not. Default value is 0x00FF (all voices playing)
  • braceType : 0 = no brace, 1 = piano type of brace, 2 = orchestral type of brace
  • braceTotal : Number of staves included in the brace that starts on this staff
  • measNumberMode : 0 means no measure number displayed; 1 is every measure2 is for first measure of every system and 3 is everymeasNumberFreq measure.
  • measNumberFreq : Used to specify the frequency of measures numbersdisplayed, in case that measNumberMode is 3.
  • X position of the measure numbers, from the upper left corner of the measure
  • Y position of the measure numbers, from the upper left
  • measNumberFrame : TRUE if a frame must be drawn around the measure numbers corner of the measure (considering staves of 5 lines)
  • Vertical position of the upper corner of the measures in relation to the upper corner of the measures of the staff above it. This value is used to display thescore in linear mode only.
  • Default color associated with the staff. This parameter will be used in somefuture display function.
  • variousOptions : Bit 0 : TRUE if the stems of notes are displayed; Bit 1 : TRUE if the beams of notes are displayed; Bit 2 : TRUE will hide the time signature; Bit 3 : TRUE forces note stems up; Bit 4 : TRUE forces note stems down; Bit 5 : TRUE will display the chords diagrams.
  • tablatureID : Identifier of the tablature template to use for this staff; 1 is the default 6 strings guitar with standard tuning; 0 means no tablature. When using a tablature, staffLinesshould be 0x0FC0, sizeOfStaff should be 150 % andvariousOptions should be set to 0x0014. Other possible values of tablatureID can be found in the file "tablature.dat"; the ID to use is the parameter thatfollows the name of the tablature template in the lines of that text file.

MNLSetStaffParameters(...)

This music notation SDK function will set the parameters of staffstaffIndex (from 1 to the total number of staves) inside document docID. The parameters are defined in the structure pointed to by params, which has been defined previously.

For the playback parameters, they will only affect the playback at the next call to MNLStartPlaying. For graphic parameters, most values will be applied to the next display of the score.

The advised method to change one or more of these parameters is to callMNLGetStaffParameters, then modify the parameters and callMNLSetStaffParameters so that only the needed changes will affect the score.

If one of the variables of params is outside its normal range, the value is simply ignored.

MNLGetPageTotalText(...)

This music notation SDK function counts the total number of text block associated to page pageNumber in document docID and returns the result in total.

A text block may be associated to a measure or to a page. In the case of a page text block, the position of the block does not depend on how the measures are laid on the page. The text blocks that are contained in a measure are drawn relative to the position of the measure. This function only handles the text blocks associated to pages.

MNLGetPageText(...)

This music notation SDK function retrieves the information about the text block of index, associated to page pageNumber in document docID. The information is provided in the structure pointed to by text, which contains the following information:

  • x,y: location of the top left of the text block rectangle. A text bloc may be associated with a measure or with a page. If present inside a measure, the position is relative to the top left corner of the measure. If attached to a page, the position is relative to the top left corner of that page.
  • width,height: The width and height of the rectangle enclosing the text block
  • Font specification for the text
  • type: Must be "2" for a block associated with a measure. For a page block, the value "1" is to display the text on page "pageNumber". Value "3" is to display the text from page "pageNumber" to page "pageMax".
  • pageNumber: For a page text block, the number of page where the text must be displayed
  • pageMax: Last page to display the text block, in case of type=3. A value of zero means that there is no maximum
  • alignText: 0 = left aligned; 1 = right aligned; 2 = centered; 3 = left and right aligned.
  • verticalSpacing: A value of 100 % is the normal spacing for the font. Increasing this value will put more space between to lines.
  • String to display. The literal value "$1" is replaced by the page number when displayed and the literal "$2" is replaced with the total number of pages in the score.
  • options: Various options that can be combined for a page text: 0x0001 = the text block will be centered on the page automatically; 0x0002 = the text block will be a header; 0x0004 = the text block will be footer; 0x0010 = do not display on even pages; 0x0020 = do not display on odd pages.

MNLSetPageText(...)

This music notation SDK function specifies the information for the text block of index index, associated to page pageNumber in document docID.The information is provided in the structure pointed to by text. Calling this function may reorder the text block inside the page, according to the position of the text block.

MNLDeletePageText(...)

This music notation SDK function deletes a text block, associated to pagepageNumber in document docID.

MNLInsertPageText(...)

This music notation SDK function creates a new text block associated to page pageNumber in document docID. Calling this function may reorder the text block inside the page, according to the position of the text block. The text block information is provided in the structure pointed to by text.

Section C - Changing time signature, key signature and clef

MNLSetKeySignature(...)

This music notation SDK function changes the key signature in measuremeasureNumber for staff staffNumber. If staffNumber is zero, then the key signature is changed for every staff (except drums staves and tablatures). ksig is the number of sharps (1 to 7) or flats (-1 to -7). 0 is for the key of C. The score is not transposed but the existing notes are adapted to the new key signature.

MNLSetTimeSignature(...)

This music notation SDK function changes the time signature in measuremeasureNumber. num is the numerator and denom is the denominator of the time signature (for instance 6 and 8 for a 6/8 time signature). Validdenom are 1, 2, 4, 8, 16, 32, 64 and 128.

You are responsible to keep the content in synchronization with the time signature, as changing the time signature will not check the real rhythmic content of the measures.

MNLGetClef(...)

This music notation SDK function retrieves the information about the clef that is active at position xPos of measure measureNumber in staffstaffNumber. The parameters are returned in the structure pointed to byclef, which contains the following information:

  • clefID: Clef Identifier : 0 = G clef, line 2; 1 = F clef, line 4; 2 = F clef, line 3; 3 = C clef, line 1; 4 = C clef, line 2; 5 = C clef, line 3; 6 = C clef, line 4; 7 = G clef, line 1; 8 = percussion clef; 9 = invisible clef (same as 0);
  • octaveTransposition: The clef can transpose at -2, -1, 0, +1 or +2 octaves, showing a small "8" or "15" above or below the clef

xPos must be inside the measure itself or the function will return an error.

MNLSetClef(...)

This music notation SDK function sets the clef at position xPos of measuremeasureNumber, in staff staffNumber, as defined in the structure pointed to by clef. xPos must be inside the measure itself or the function will return an error. If xPos is zero, then the clef is placed at the beginning of the measure. If not, then the clef is a mobile clef, displayed smaller, that can be placed between notes. If an existing mobile clef is close to xPos, the clef is simply replaced.

MNLDeleteClef(...)

This music notation SDK function deletes the clef at position xPos of measure measureNumber, in staff staffNumber. If xPos is zero, the header clef is deleted, otherwise the closest mobile clef is deleted.

Notice that clefs are handled automatically, as a clef must appear at the begin of each staff. You can only remove a mobile clef, or a header clef that is the first of its type, that is, when a new clef appears.

Section D - Handling the music content of the measures

To handle the content of the measures, a set of structures is defined. A measure is in fact a list of objects. The objects are:

  • Note: each note in the measure is represented by a Note object.
  • Rest: each rest in the measure is represented by a Rest object.
  • Symbol: A symbol has a graphic aspect and may have a playback influence. Nuances, tempo markings, trills,... are symbols.
  • Text block: A text block may display one or more strings of text, with a given font and color.
  • Lyrics: Each note may be associated with a lyrics object, which contains the syllables of up to 8 lines of text associated to one note, including their vertical position.
  • Chord symbol: This object specifies where and how to draw a chord symbol, but a chord progression must exist in the score before a real chord is displayed.
  • Tuplet: A tuplet object encloses graphically notes and rests to play them as a tuplet group like 3 instead of 2, 5 instead of 4,...

A Note object contains the following information:

  • Horizontal position of the note in the measure, in pixels.
  • Vertical position of the note in the measure, in pixels. The origin is the top line of a 5 lines staff and positive values go down. Staff lines are 6 pixels apart. A value of 0 would be an F note in the G clef. A value of 24 is an E note in G clef.
  • The graphical value of the rhythm of the note: 0 = double whole note; 1 = whole note; 2 = half note; 3 = quarter note; 4 = 8th note; 5 = 16th note; 6 = 32nd note; 7 = 64th note; 8 = 128th note;
  • Number of dots for the note. One dot adds 50 % to the existing note duration
  • Accidental associated with the note : 0 = none; 1 = double flat; 2 = flat; 3 = natural; 4 = sharp; 5 = double sharp;
  • Graphic direction of the stem of the note: 0 = up; 1 = down
  • Stem length, in pixels.
  • voice: There can be up to 8 rhythmic voices in one measure. A rhythmic voice is defined as an independent series of notes and rests played in a continuous sequence.
  • Color of the note. The default color is 0 (black). The color format is hexadecimal 0x00BBGGRR, where BB is the blue component (0-255), GG is green and RR is red
  • noteHead: 0 is the default automatic note head shape according to the rhythmic value. Other values are defined in the documentation of the SDK.
  • groupID: A group of notes are beamed together by the spacing algorithm automatically. Notes that are not part of a group have groupID = 0. Notes beamed together have the the same positive groupID, that must be unique in themeasure.
  • chordID: If more than one note is attached to the same stem, as in a chord, chordID must be a positive and unique value that is the same for all the notes of the chord. In such a case, only one note has a positive stemLength and the others have stemLength = 0.
  • symbolID: If a graphic symbol is associated to a note, the note and the symbol must share a positive unique symbolID. 0 is the default value (no attached symbol)
  • lyricsID: If a lyrics object is associated to a note, the note and the lyrics object must share a positive unique lyricsID. The default value is 0, with no lyricsassociated.
  • tupletMask: To create a tuplet with a series of notes and rests inside a measure, the notes and rests must have the same mask bit set than the tuplet object. There are maximum 16 tuplets group in one measure. The first tuplet object and its notes and/or rests, must have the tupletMask set to 0x0001. A tuplet objecthas only one bit set, but notes and rests may have more than one, in the case of a tuplet of tuplets (quite rare but possible). Most cases will only have one.
  • fretNumber: For guitar tablature, the number of the fret on which the note is played. -1 by default.
  • Value of MIDI note played (0 to 127)
  • Value of velocity played (1 to 127)
  • Starting point of the note in units (480 units per quarter note) from the beginning of the measure
  • Duration of the note playback, in units.
  • customVelocity: If equal to -1, the velocity is determined by the staff specification and by the graphic symbols (nuances, accents,...). If between 1 and 127, the value is used as the fixed velocity value for playback.
  • customStart: If equal to 32000, the start time of the note is determined by the content of the measure itself. Otherwise, it is the starting point of the note, inunits. This is used to take account of a human playback of the note, as notes are never play 100 % exactly.
  • customDuration: If equal to 32000, the duration of the note is determined by its rhythmic value. Otherwise, it is the real duration of the note, in units.
  • graceNoteDuration: The duration of the grace note (only for grace notes)
  • options: Each bit has a specific meaning in the handling of the note. Some are graphic options, some are playback options. 0x0001 = The note is tied to the next note of same pitch, with a curve so that the note duration is extended. The following note must be the same pitch and its attack will not be played. 0x0002 = The note is the continuation of the previous note, which must be of the same pitch. The note attack is not played. 0x0010 = The note is invisible (not drawn on the score). 0x0020 = The beaming is forced with the previous note. If not set, the spacing algorithm automatically handles the standard beaming of notes.0x0080 = The beaming is prevented with the previous note. If not set, the spacing algorithm automatically handles the standard beaming. 0x0040 = Set if the stem direction is fixed and may no more be changed by the spacing algorithm. 0x0200 = The note is a grace note, which means that the graphic duration does not influence the sum of rhythms for the time signature present.The note is also drawn at 50 % of its size. 0x0400 = Only in the case of a grace note, the note is drawn with an oblique bar on the stem. 0x0800 = Only for grace notes : if set, the grace note must be played ahead of the main note (the main note keeps its start position and duration).

A Rest object contains the following information:

  • Horizontal position of the rest in the measure, in pixels.
  • Vertical position of the rest in the measure, in pixels. The origin is the top line of a 5 lines staff and positive values go down.
  • The graphical value of the rhythm of the rest. 0 = double whole rest; 1 = whole rest; 2 = half rest; 3 = quarter rest;4 = 8th rest; 5 = 16th rest; 6 = 32nd rest;7 = 64th rest; 8 = 128th rest;
  • Number of dots for the rest. One dot multiplies its graphic duration by 1.5
  • voice: There can be up to 8 rhythmic voices in one measure. A rhythmic voice is defined as an independent series of notes and rests played in a continuous sequence.
  • symbolID: If a graphic symbol is associated to a rest, the rest and the symbol must share a positive unique symbolID. 0 is the default value (no attached symbol).
  • tupletMask: To create a tuplet with a series of notes and rests inside a measure, the notes and rests must have the same mask bit set than the tuplet object. There are a maximum of 16 tuplets group in one measure. The first tuplet object and its notes and/or rests, must have the tupletMask set to 0x0001. A tuplet object has only one bit set, but notes and rests may have more than one, in the case of a tuplet of tuplets (quite rare but possible). Most cases will only have one.
  • Starting point of the rest in units (480 units per quarter note) from the beginning of the measure
  • Duration of the rest playback, in units. Nothing is played in MIDI for a rest, but the start and the duration of a rest may be useful in computing the full playback timing.
  • options: 0x0010 = The rest is invisible (not drawn on the score).

A Symbol object contains the following information:

  • toolID: Determines the type of symbol used, as defined in the documentation of the SDK.
  • symbolID: If a graphic symbol is associated to a note or rest, the // note or rest and the symbol must share a positive unique symbolID. 0 means that the symbol is not attached to a note or rest in the measure.
  • Position of the origin point of the symbol, relative to the top left corner of the measure
  • Horizontal and vertical scaling of the symbol, if the symbol accepts resizing. Default value is 100 %
  • x1,y1,x2,y2,x3,y3: For slurs only : the 3 points (relative to the top left corner of the measure) that define the curve. Symbols using this are tool ID 2400, 2401, 2070 and 2071.
  • invisible: If different than zero, it makes the symbol invisible.
  • effectStartMode: 0 = the MIDI effect starts at the beginning of the measure. 1 = the MIDI effect starts at the time position of the symbol in the measure. 2 = the MIDI effect starts at the time position of the note associated with the symbol.
  • effectDuration: 1 = the duration of the effect is fixed by the next three variables. The total duration of the effect is given by adding the number of measures, beats and units as determined by these variables. 2 = the duration of the effect is proportional to the graphic width of the symbol.
  • effectDurMeas: Number of measures for the duration of a MIDI effect, see the remark for variable "effectDuration".
  • effectDurBeats: Number of beats for the duration of a MIDI effect, see the remark for variable "effectDuration".
  • effectDurUnits: Number of units for the duration of a MIDI effect, see the remark for variable "effectDuration".
  • effectValue: This is the effect value in the case of a single value effect (nuances, tempo changes, transposition,...)
  • effectLocal: If set to 1, the MIDI effect is only local, so that the effect is canceled after the duration of the effect. Nuances, for instance, are not local, as their effects continue after the symbol. An accent is local, as it only affects the note with the accent. The value is 0 for a symbol that is not local.
  • relative: If set to 1, "effectValue" is relative to the value of the effect at the time when the symbol effect starts. An accent, for instance, is relative to the currentvelocity level of the notes.
  • effectProg1, effectProg2, effectProg3: These values are used only where the effect is based on a progression of value, like a crescendo, accelerando,... The 3 values are the values used for the progression.
  • notePitchOffset: For trills and grace notes, this value determines the pitch played, relative to the pitch of the main note to which the symbol is attached. A value of +1 would give a grace note one semitone higher than the main note.
  • timeScale: Used as a scale factor for playing trills and arpeggios. Default value is 100 %. The trills play slower when increase this value.

A Lyrics object contains the following information:

  • Horizontal position of the lyrics, relative to the top left corner of the measure
  • The 8 vertical positions of the 8 syllables in this lyrics object. They correspond up to 8 lines of lyrics associated with the notes in a measure
  • dash[8]: If different than "-1", it is the offset, relative to the x position, of the dash sign that must be drawn to separate the syllables of a word.
  • line[8]: If different than "-1", it is the length of a line drawn from the end of that syllable as a continuation sign, meaning to hold the same syllable on more thanone note.
  • lyricsID: If a lyrics object is associated to a note, the note and the lyrics object must share a positive unique lyricsID.
  • text[8][100]: The text of the 8 syllables, as null terminated strings.

A Chord Symbol object contains the following information:

  • Position of the chord symbol, relative to the top left corner of the measure
  • offset: the time offset from the beginning of the measure, in units (480 units = 1 quarter note) of the chord to display. To display a chord, there must be a chordprogression defined in the score, otherwise this object will display nothing

A Tuplet object contains the following information:

  • n1,n2: For a standard triplet, we have n1=3 and n2=2, which means "n1" notes played instead of "n2" notes
  • x and y positions of the starting point of the tuplet
  • x and y positions of the end point of the tuplet. The coordinates are relative to the upper left corner of the normal 5-lines measure.
  • above: true if the tuplet is graphically placed above the notes
  • shape: 1 is for a slur type of curve; 2 for a line bracket; 0 for no slur nor bracket
  • Style of display : 0 = No number displayed; 1 = "N1" is displayed; 2 = "N1:N2" is displayed; 3 = "N1/N2" is displayed.
  • transparent: If transparent=1 then the slur or bracket is made transparent under the number displayed
  • Vertical offset of the numbers displayed (N1 and/or N2) based on the middle value of y1 and y2 which is (y1+y2)/2.
  • tupletMask: To create a tuplet with a series of notes and rests inside a measure, the notes and rests must have the same mask bit set than the tuplet object. There are a maximum of 16 tuplets group in one measure. The first tuplet object and its notes and/or rests, must have the tupletMask set to 0x0001. A tuplet object has only one bit set, but notes and rests may have more than one, in the case of a tuplet of tuplets (quite rare but possible). Most cases will only have one.

This music notation SDK provides functions to access the content of the measures. One important point to note is that the SDK provides an automatic spacing algorithm that arranges the graphic content automatically inside the measure and so that notes playing on two different staves are horizontally aligned. It also handles the link between the graphic content and the MIDI playback.

When you add or modify the content of a measure, you should call the spacing function so that everything is nicely displayed and played back in MIDI, otherwise, according to the changes you make in the measure, unexpected results may occur. This is because the SDK gives you the possibility to create any content in a measure, even if not logical in standard music notation, so you are responsible for knowing what you do with it.

The spacing function is the following.

MNLApplySpacing(...)

This music notation SDK function will apply the spacing algorithm to the content of measure measureNumber, on all staves playing together. IfadaptWidth is TRUE, then the measure will be resized to its optimum width, according to the content of the measure.

One example is when you start adding notes into a measure. You can add them by specifying increasing posX values (by +10 pixels) to the notes, but you do not have to take care of the exact position of notes. Calling this function will nicely space the music according to standard music notation. Please note that this function may reorder the objects inside the measure.

The following functions are used to list the content of a given measure, to modify, create, insert and delete objects inside the measure.

MNLMeasureGetTotalObjects(...)

This music notation SDK function returns the number of objects present in the measure specified by measureNumber and staffNumber.

MNLMeasureGetObjectType(...)

This music notation SDK function returns the type of object of index, present in the measure specified. Displaying, playing and applying the spacing function may reorder the content of the objects present in a measure. Do never rely on a given index of object to stay the same all the time.

MNLMeasureGetNote(...)
MNLMeasureGetRest(...)
MNLMeasureGetSymbol(...)
MNLMeasureGetText(...)
MNLMeasureGetLyrics(...)
MNLMeasureGetChordSymbol(...)
MNLMeasureGetTuplet(...)

These functions fill the object structure pointed to by the last parameter, with the details of the object of index index, present in the measure specified by measureNumber and staffNumber. If object index is not the correct type of object, the function returns an error.

MNLMeasureDeleteObject(...)

This music notation SDK function deletes the object of index index, present in the measure specified by measureNumber and staffNumber. Ifchord is true and the object is a note that is part of a chord, all the notes of the chords are deleted.

MNLMeasureClear(...)

This music notation SDK function deletes all objects present in the measure specified. The measure is then empty of any notes, rests, symbols,... Notice that header clefs, as well as time and key signatures are not deleted from the measure.

MNLMeasureModifyNote(...)
MNLMeasureModifyRest(...)
MNLMeasureModifySymbol(...)
MNLMeasureModifyText(...)
MNLMeasureModifyLyrics(...)
MNLMeasureModifyChordSymbol(...)
MNLMeasureModifyTuplet(...)

These functions set the details of the object of index index, present in the measure specified by measureNumber and staffNumber, using the structure information pointed to by the last parameter. If object index is not the correct type of object, the function returns an error. If a parameter of the structure is invalid, the function simply ignores it.

MNLMeasureInitNote(...)
MNLMeasureInitRest(...)
MNLMeasureInitSymbol(...)
MNLMeasureInitText(...)
MNLMeasureInitLyrics(...)
MNLMeasureInitChordSymbol(...)
MNLMeasureInitTuplet(...)

These functions initialize the object structure pointed to by the last parameter, with the default values of each variable in the structure. They should be used to create a valid object, that you can thereafter modify and insert into a measure.

MNLMeasureInsertNote(...)
MNLMeasureInsertRest(...)
MNLMeasureInsertSymbol(...)
MNLMeasureInsertText(...)
MNLMeasureInsertLyrics(...)
MNLMeasureInsertChordSymbol(...)
MNLMeasureInsertTuplet(...)

These functions insert an object into the measure, based on the object structure pointed to by the last parameter. The objects in the measure are automatically reordered so that objects are sorted from the left to the right. Do not rely on a fixed index for a given object after you insert a new object, as they may have changed.

The following two functions are designed to easily specify or get the practical information about a note, from the object in the measure. You can of course use the MNLMeasureModifyNote functions, but you have to interpret the name of the note from its vertical position. To do this you have to know which clef is present and make the conversion. The following functions will help you to avoid these difficulties.

A note specification defines the following information:

  • noteIndex: This is the index of the note in the series of natural notes starting with 0 = C(-2), 1 = D(-2),... 35 = C3,... This numbering only takes into account the natural notes without any specification for the accidentals. To get the note name, you can simply take the remainder of the division by 7 and you get a number from 0 to 6 which are the notes C, D, E, F, G, A, B. To get the octave number, divide it by seven and subtract 2. The octave numbering used here is such that the reference note A3 is 440 Hz.
  • midiNote: This is the MIDI pitch note value by semitone (60 = C3). This numbering starts from C(-2) which is value 0 and continues semitone by semitone, and does note care about the exact note name. For instance, a value of 63 is D3 # or E3 b. The difference can be detected by looking at the value of "noteIndex".
  • noteAlt: +2 = double sharp; +1 = sharp; 0 = natural; -1 = flat; -2 = double flat

MNLMeasureGetNoteSpec(...)

This music notation SDK function returns the practical information about the index note/rest of the measure specified by measureNumber, staffNumber and docID. The information is returned in the structure pointed to by noteSpec. noteSpec.noteAlt is ignored, as it can be computed from noteIndex and midiNote.

MNLMeasureSetNoteSpec(...)

This music notation SDK function sets the practical information about theindex note/rest of the measure specified by measureNumber, staffNumber and docID. The information is provided in the structure pointed to by noteSpec. Most other characteristics of the note (as defined in MNLStructNote) are not modified.

Here is another function that can be used to quickly enter a melodic line.

MNLMeasureEnterNote(...)

This music notation SDK function will insert the note in the measure, in the specified voice. A voice is here considered to be a sequence of rhythmic values, represented either by a note, a chord or a rest. A measure may contain up to 8 independent rhythmic voices, numbered from 1 to 8. You should always start with voice 1 and use the other voices only when needed (for polyphonic music in the same staff).

If *index = 0 when you call the function, the note or rest will be added at the end of the content of the measure, providing that the rhythmic value does not overflow the measure. If *index is positive, it must be the index of the note or rest (of the same voice) before which the new note will be inserted.

docID, measureNumber and staffNumber specify the document and the measure in which the note will be inserted.

note specifies the note name : 0 = C, 1 = D, 2 = E, 3 = F, 4 = G, 5 = A and 6 = B. If note is -1, then a rest is inserted.

If chord is true, then this note is added to the last rhythmic value already in that measure, as an additional note to build a chord. In this case, the duration of the note is ignored, as it is imposed by the last rhythmic value of the measure. It is ignored if note is -1 or if the last rhythmic value of the measure is a rest.

octave can be between -2 and +8 (C3 is the note with one low ledger line in the G clef).

accidental can be : -2 = double flat, -1 = flat, 0 = natural, +1 = sharp, +2 = double sharp.

duration is : 0=Double whole note; 1=Whole note; 2=Half note; 3=Quarter note; 4=Eighth note; 5=16th note; 6=32nd note; 7=64th note; 8=128th note.

dots specifies 0 or more dots to influence the duration of the note.

voice is between 1 and 8, but you should build voices one at a time. In other words, fill in voice 1 completely before switching to voice 2, and so on.

tupletN1 and tupletN2 represent the ratio of the tuplet for the rhythmic value used. If you do not need a tuplet, simply set these two values to "1". For a triplet, use respectively 3 and 2 for instance. If tupletN1 is negative, then a new tuplet group is created, whether there is already the same type of tuplet before or not. Let us take an example. If you need to enter this:

you must enter the first three notes with tupletN1=3 and tupletN2=2. The next note must be entered with tupletN1=-3 and tupletN2=2. And the last two notes again with tupletN1=3 and tupletN2=2. If you do not use the "-3" value, you would get:

The resulting duration of the note or rest must fit with the duration left in the voice you are working with. The resulting duration is computed fromduration, dots and tupletN1, tupletN2 and must not overflow the content of the measure, according to the time signature. If it is greater, an error is returned and nothing is added. While adding notes, keep track of the total duration and switch to the next measure when the time signature duration is reached.

*index will return the index of the object that has been added in the measure. Before returning, the function will always apply the spacing, so that the musical layout of the measure is standard. Adding more notes may alter the indexes of the notes already in the measure. index is valid right after returning from this function and may be used for instance to modify advanced parameters of the note just entered, using the other functions already described. But do not count on this index to stay the same when you call another function of the library that can change the order of notes.

In case of an invalid parameter, the function returns an error, nothing is added in the measure and *index is set to zero.

MNLMeasureCopy(...)

Copies the content of the measure specified by measureFromNumber andstaffFromNumber, in document docIDFrom, to measuremeasureToNumber and staffToNumber, in document docIDTo. The content of the destination measure is lost.

MNLGetMeasureOptions(...)

This music notation SDK function retrieves various options of the measure specified by measureNumber and staffNumber, in document docID. It fills the data structure pointed to by options, which contains the following information:

  • timeSigDisplay: 0 = automatic time signature display of that measure; 1 = Always display the time signature of that measure; 2 = Never display the time signature of that measure;
  • keySigDisplay: 0 = automatic key signature display of that measure; 1 = Never display the key signature of that measure;
  • measureNumber: 0 = Automatic numbering; -1 = This measure does not count in the numbering. Any other positive value imposes the number of this measure.Any other negative value imposes the number of measures as a multiple rest measure to count. For instance, -5 means that this is a multi rest of 5 measures. To show the multi rest symbol, you should insert the multirest symbol in the measure (toolID = 2611), which will also display the number above it.
  • measNumDisplay: 0 = Automatic display of the measure number according to the staff specifications. 1 = Always display the number of this measure; 2 = Never display the number of this measure;
  • staffLines: Each bit specifies the presence of a line, in a set of 16 possible lines. The standard 5 lines staff value is 0x07C0.
  • spacingDisabled: if set, this means that any spacing is disabled in the measure, so that the content of the measure will not be reorganized graphically.
  • freeContent: If -1, the measure content is based on the time signature at the beginning of the staff. Values from 0 to 8 imposes that the measure content is free on the basis of a double whole note (0), a whole note (1), a half note (2),... up to a 128th note (8). This means that the spacing and playback functions will consider that the measure may contain and play any multiple of that basic duration.

MNLSetMeasureOptions(...)

This music notation SDK function sets various options of the measure specified by measureNumber and staffNumber, in document docID, from the data structure pointed to by options.

You should first call MNLGetMeasureOptions, change the options you want, and then call MNLSetMeasureOptions. Any invalid parameter inoptions is ignored by the function.

The parameters that influence the playback will be set for all staves.

MNLGetLyricsFont(...)

This music notation SDK function retrieves the font information of the font assigned to the lyric line lineNumber (1 to 8) of staff staffNumber, in document docID. The information about the font is stored in the data structure pointed to by font.

There can be up to 8 lines of lyrics for each staff and each one can use a different font.

MNLSetLyricsFont(...)

This music notation SDK function specifies the font information to use for the lyric line lineNumber (1 to 8) of staff staffNumber, in documentdocID. The information about the font is provided in the data structure pointed to by font.

MNLGetDocumentFont(...)

This function retrieves the font information assigned for :

  • 1 = Instrument name at the beginning of a staff
  • 2 = Measure numbers
  • 3 = Tuplets and tablatures
  • 4 = Chords symbols

The information about the font is stored in the data structure pointed to by font.

MNLSetDocumentFont(...)

This music notation SDK function specifies the font information assigned to the document, for the index value, which is the same as described in the above table.

The chord symbol font is stored globally, for all documents.

MNLFindObjectByPosition(...)

This music notation SDK function will locate if an object is present at thex,y position in the display area. This is typically used to let the user locate a musical object by clicking on it. If there is an object at that position, the function returns the measureNumber, the staffNumber, theobjectIndex of the object in that measure, as well as the identifier of the object found (MNL_NOTE_ID, MNK_REST_ID,...). If no object is found at the given position, the four parameters are set to zero, but no error is returned.

Section E - Handling the chord progression

A document is associated with a chord progression, valid for all the staves of the document. A chord is represented by the following data structure:

  • measure: Measure number where the chord is located
  • offset: Offset of the chord, in units (1 quarter note = 480 units) from the beginning of the measure. A chord placed on beat 3 of measure 5, would belocated by "measure=5" and "offset=960 (480 x 2)
  • rootNote: Note specification of the root of the chord
  • chordID: Chord identifier; the chord identifiers are listed in the SDK documentation.
  • altBass: Alternate bass note for the chord (the bass note played when the root is not at the bass note). If altBass.noteIndex = -1, then the bass note is the rootnote of the chord.

The following functions are used to edit or create the chord progression of a document. Before you can display a chord symbol inside a measure, there must be a chord progression defined.

MNLGetChordTotal(...)

This music notation SDK function returns in *total the number of chords defined in the chord progression of the docID document.

MNLGetChordInfo(...)

This music notation SDK function fills the structure pointed to by chordswith the information of the chord of index index, present in the chord progression of the docID document. index must be between 1 and the total number of chords in the progression.

MNLSetChordInfo(...)

This music notation SDK function sets the information of the chord index, present in the chord progression of the docID document. The information is provided in the structure pointed to by chord. index must be between 1 and the total number of chords in the progression.

According to the changes you make in the chord information, this function may reorder the chords of the progression, so that they stay in time sequence. In that case, the indexes of the chords may change.

MNLDeleteChord(...)

This music notation SDK function deletes the chord index from the chord progression of the docID document.

MNLInsertChord(...)

This music notation SDK function inserts a new chord in the chord progression of the docID document. The information is provided in the structure pointed to by chord. The chord is automatically inserted in the correct time sequence, so the indexes of the other chords may change. If there is another chord already defined exactly at the same time position, the new chord replaces the old one. The measure number and offset must have valid values inside the existing score.

MNLChordsToNotes(...)

This music notation SDK function converts the chords present in the chord progression into notes on the staff. The *chordsToNote data structure determines how the conversion is performed:

  • fromMeasureNumber: Starts the conversion at this measure number
  • toMeasureNumber: Last measure for the conversion
  • staffNumber: Staff on which the notes will be written
  • whichNotesToUse: A mask that determines which notes can be used in building the chord : 0x0001 : Root note; 0x0002 : Third; 0x0004 : Fourth; 0x0008 : Fifth; 0x0010 : Sixth; 0x0020 : Seventh; 0x0040 : Ninth; 0x0080 : Eleventh;0x0100 : Thirteenth; 0x8000 : Bass;
  • upperMidiNote: Maximal MIDI pitch value for the notes
  • lowerMidiNote: Minimal MIDI pitch value for the notes; These two values determine the pitch range for the generated chord notes.
  • conversionMode: 0 = The notes change at each new chord. 1 = The notes change every "duration" units.
  • duration: In the case of "conversionMode=1", this variable determines the duration of the notes that are generated. For instance, a value of 480 would create a series of quarter notes changing with the chord progression
  • legatoFactor: If equal to 100 %, the notes are fully legato, this means that the next note starts right after the previous stops. A value of 50 % would give a staccato effect.
  • maxNotes: The maximum number of notes to use in a chord.
  • minDistance: Minimal distance, in semitones, between two notes generated by the function.

The measures where the notes are written are first cleared of their previous content.

Section F - Handling MIDI events

Each measure of a staff has, in addition to the objects it contains (notes, rests, symbols,...) a MIDI track that can playback MIDI events. There are events that are generated by graphic symbols, like volume crescendo, pitch bend effects,... These are not visible by the following functions. But you can add other MIDI events directly into the measure tracks and they will be played back in the MIDI channel assigned to that staff. A MIDI event is defined with the following structure:

  • offset: Time offset from the beginning of the measure, in units
  • value1, value2: Values used according to the type of event
  • type: 0 = MIDI controller "value1" set to "value2"; 1 = Program change set to "value1"; 2 = Pitch bend set to "value1"; 3 = Tempo change, set to "value1".

MNLGetMidiEventTotal(...)

This music notation SDK function returns in *total the number of MIDI events present in the measure specified by measureNumber, staffNumberand docID.

MNLGetMidiEvent(...)

This music notation SDK function fills the structure pointed to by eventwith the information of the MIDI event index present in the measure specified by measureNumber, staffNumber and docID.

MNLSetMidiEvent(...)

This music notation SDK function modifies the information of the MIDI event index present in the measure specified by measureNumber, staffNumber and docID. The information is provided by the structure pointed to by event. This function may reorder the events in the track so that they are always in the correct time sequence.

MNLDeleteMidiEvent(...)

This music notation SDK function deletes the MIDI event index present in the measure specified by measureNumber, staffNumber and docID.

MNLInsertMidiEvent(...)

This music notation SDK function inserts a new MIDI event in the measure specified by measureNumber, staffNumber and docID. The information is provided by the structure pointed to by event. This function may reorder the events in the track so that they are always in the correct time sequence.

MNLSendMidiEvent(...)

This music notation SDK function sends a MIDI event to the current open MIDI port, on MIDI channel channel (0 to 15).

MNLFindKeyboardNote(...)

This music notation SDK function finds the key that contains the x,y coordinate inside the graphic keyboard and returns the MIDI value of the corresponding note (0 to 127) in *midiValue. If no key is found, the value returned in *midiValue is -1.

MNLFindFretboardNote(...)

This music notation SDK function finds the fret and string position that contains the x,y coordinate inside the graphic fretboard and returns the MIDI value of the corresponding note (0 to 127) in *midiValue. The fret number (0 to Number of frets visible) and string number (from 1 to the number of strings) are also returned. If no position is found, the value returned in *midiValue is -1.

Click here to download the Windows and/or Mac OS X
application examples of the music SDK.

Click here to receive the full pricing and ordering information...

Back from Music Notation SDK Level II to Music SDK...



Copyright 2012 - Arpege Music - Dominique Vandenneucker