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.
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:
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.
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:
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:
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.
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:
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.
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:
A Note object contains the following information:
A Rest object contains the following information:
A Symbol object contains the following information:
A Lyrics object contains the following information:
A Chord Symbol object contains the following information:
A Tuplet object contains the following information:
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:
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:
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 :
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.
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:
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:
The measures where the notes are written are first cleared of their previous content.
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:
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...