Home pageMusic Notation SDKMIDI TutorialMusic Data Structures

Music Notation Software Library Level I - Detailed API description

The Music Notation Software Library Level I contains a set of API (Application Programming Interface). 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).

The SDK comes with the source code of a full application example project, ready to run on Visual C++ 2010 Express for Windows and xCodefor Mac OS X and iPad simulator.

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 - Loading the library

MNLLoad(...)

This music notation software library function initializes the library and all needed resources. Only after a successful call to this function may the other functions be used.

The path of the directory where the DLL/dylib and the resource files are located is provided as a parameter, as well as a unique validation key that you receive when you buy the SDK. If the validation code is not correct, the calling program will not be able to use other functions of the SDK.

MNLRelease(...)

Release all resources needed by the library. Must be called only ifMNLLoad was successfully called. After calling MNLRelease, no other function may be called anymore.


Section B - Loading and saving documents

MNLOpenDocument(...)

This music notation software library function opens a document from a file. It can be a Pizzicato file (*.piz), a MIDI file (*.mid) or a musicXML file (*.xml). The function provides a unique document identifier (docID) that can be used in other functions to refer to an open document, but only if MNLOpenDocument returns no error.

MNLOpenDocumentFromBuffer(...)

Open the document from a memory buffer. It can be a Pizzicato file content, a MIDI file content or a musicXML file content. The function provides a docID that can be used in other functions to refer to an open document, but only if MNLOpenDocumentFromBuffer returns no error.

For MIDI files and old Pizzicato files (format 3.4 or earlier), a temporary file is created in the main directory. This file is removed immediately after the operation.

MNLCloseDocument(...)

Close the document specified by its docID. The document may no longer be referenced with any of the other functions.

MNLSaveDocument(...)

Save the specified document to a file name and location. A parameter specifies the format (PIZ,MID,XML;PDF;WAV). To save a document as a PDF file, it must have a page layout defined. To save a file in audio (WAV), you must first load a sound library with a call toMNLOpenSoundLibrary and also open a MIDI port with a call toMNLOpenMidiPort with midiOutIndex = 0. The sound library will be used to save the score in audio (stereo, 44.1 Khz, 16 bits, uncompressed).

MNLSaveDocumentToBuffer(...)

This music notation software library function saves the specified document to a memory allocated buffer. A parameter specifies the format ( PIZ,MID,XML;PDF;WAV).

To save as an audio file content (WAV), you must first load a sound library with a call toMNLOpenSoundLibrary and also open a MIDI port with a call to MNLOpenMidiPort with midiOutIndex = 0. The sound library will be used to save the score in audio (stereo, 44.1 Khz, 16 bits, uncompressed).


Section C - Getting information about a document

MNLGetScoreInformation(...)

This music notation software library function provides the number of measures, staves and pages in the score contained in the specified document. If no page layout is defined in the document, the number of pages returned will be zero. This is the case for instance of a MIDI file. The title of the document is also returned.

MNLGetPageSize(...)

Returns the size of the given page, from the specified document. The size is given in screen pixels, with a scaling factor of 1.0. If no page layout is defined in the score, the function will return an error code.

MNLGetPageMeasures(...)

Returns the first and last measure numbers inside the given page, from the specified document. This may be used to know which measures are displayed in a given page.

MNLGetKeySignature(...)

This music notation software library function returns the number of sharps (positive number) or flats (negative number, 0 for the key of C) in the specified document, for an index that goes from 1 to the number of key signatures present in the score (in case the key changes in the middle of the score). The measure number in which the index key signature was found is also provided. If index is greater than the number of key signatures present, the function returns an error code. Only the key signature changes are reported by this function. In the case of a page where there is a key signature at the beginning of each system (as it is the case in standard music notation), these repeated key signatures are not reported by the function.

MNLGetTimeSignature(...)

Returns the numerator and the denominator of the time signature (for instance 6 and 8 for a 6/8 time signature) in the specified document.Index goes from 1 to the number of time signatures present in the score (in case the time signature changes in the middle of the score). The measure number in which the index time signature was found is also provided. If index is greater than the number of time signatures present, the function returns an error code.


Section D - Displaying the score

MNLDisplayPage(...)

This music notation software library function displays the given page of the score in page mode, from the specified open document.

For Windows, drawing is performed to the device context supplied by thegraphic parameter. The graphic parameter is in fact a Windows HDC type (handle to a device context). The most obvious way to use this function is while handling the WM_PAINT Windows message.

For Mac, the graphic parameter is in fact an NSView object or a sub-class of it. The most obvious place to use this function is in the implementation function of the NSView object.

The position where the top left corner of the page will be displayed is provided as well as the rectangle used as a clipping rectangle for drawing. This means that anything outside this rectangle will not be drawn on the screen. A scale factor is used to scale the display, 1.0 being the reference size. You can get the page size information by usingMNLGetPageSize, so as to determine the scale factor to use to fit the screen display area where you want the score to appear. You can use the offset parameters to determine which part of the page to display if the area is too small to display the full page. The offset parameters could for instance be linked to scroll bars, so that the user can navigate in the page.

MNLDisplayLinear(...)

This function displays a specified set of measures of the score in linear mode in the given document. The linear mode displays all measures from left to right, with no attention to page layout. If the total number of measures is set to zero, the function will automatically compute the number of measures that can be displayed in the clipping rectangle, taking into account the scaling factor.

The use of the graphic parameter is the same as for MNLDisplayPage.

The offset parameters define the position where the top left corner of the first measure will be displayed. The rectangle is used as a clipping rectangle for drawing. This means that anything outside this rectangle will not be drawn on the screen. The scale factor is used to scale the display, 1.0 being the reference size.

When displaying with a scale of 1.0, a standard 5-lines staff is exactly 24 pixels high (6 pixels between each line).

MNLDisplayWrap(...)

This music notation software library function displays a given set of measures of the score in wrapping mode. The wrapping mode displays all measures from left to right, then go to the next line, fills the line, and so on. The size of the clipping rectangle as well as the scaling factor determine how much measures are displayed. If the total number of measures is set to zero, the score is displayed up to the last measure or to the maximum number of measures that can be displayed on the page.

The minimal and maximal scale factors that can be applied to the measures in order to calculate the optimum number of measures per system are provided to that function. This means that the function may scale the measures horizontally but not outside these values.

A padding value is provided as the number of pixels that are inserted vertically between systems.

The next function ( MNLSimulateDisplayWrap) may be used to estimate how this function will display the measures, for instance to know exactly how much measures will be displayed and what the exact height each system has (so as to compute a value of padding to display the systems equally on the page height.

The use of the graphic parameter is the same as for MNLDisplayPage.

Offset values, a scale factor and a clipping rectangle are also provided as parameters. This means that anything outside this rectangle will not be drawn on the screen.

Note for Windows users - When the user resizes the screen and you callMNLDisplayWrap in real time to display the score, using the standard displaying technique will create a visual flickering, as the area is first erased by Windows, then painted. This is also the case when displaying in page or linear mode. To avoid the flickering, you can draw the content of the window in an off-screen memory device context, then copy it to the screen area, without erasing the screen area first. This method is illustrated in the example provided with the SDK. The way to implement this is :

  1. Before the main loop, create a device context and a bitmap object that will be used to draw the score and any other element you have in that window (keyboard, fret board, custom items of your application).

  2. When registering the window class, set the wc.hbrBackgroundfield to NULL, so that Windows will not erase the background before sending the WM_PAINT message to your window, as this erasing is the cause of the visual flickering.

  3. When responding to the WM_PAINT message of Windows, draw everything in the off-screen device context and use the BitBltWindows function to copy the image to the screen.

On Mac, as there is a natural double-buffered display mechanism inQuartz, there is no need to use a temporary off-screen display.

MNLSimulateDisplayWrap(...)

This function computes how the function MNLDisplayWrap will display the measures, in wrapping mode. The parameters are similar to theMNLDisplayWrap function. The additional parameters are used to get information about the layout of the page regarding the positions of the systems and measures on the page so that you can predict the way the wrapping mode will display the score with the given values of the parameters.

MNLFindPosition(...)

This music notation software library function will locate the measure, the staff and the beat number (from 1 to the total number of beats in the measure) from the given graphic position x,y in the display area. The display area parameters (scale, offset and rectangle) are taken from the last call to one of the display functions.

The detected positions are either inside one of the measures (between two bar lines and inside the staff lines) or between two staves of the same system. In any other case, the function returns an error.

On Windows, the origin of the coordinate system is the upper left corner. On mac, an NSView has by default its origin in the bottom left corner. The SDK takes that into account for all drawing operations, but as you catch a mouse event on the Mac, you get the mouse position according to the bottom left corner, so you must convert it before passing it to this function.

In the SDK example, this function is used so that the user can click on one measure - while the score is playing - to start playing that measure.

MNLGetMeasurePosition(...)

This function returns the position (in pixels) of the top left corner of the given measure and staff numbers for a scaling factor of 100 %. It is the position where the measure is actually displayed.

MNLMeasureUnitsToPosition(...)

This function converts the time position (in units, one quarter note being 480 units) into the corresponding x position. Both units and x position are relative to the beginning of the specified measure.

MNLMeasurePositionToUnits(...)

This function converts the graphic position x (in pixels) into the corresponding time position in units. Both units and x position are relative to the beginning of the specified measure.


Section E - Modifying the document

MNLTranspose(...)

This music notation software library function transposes the score to the given key signature (from -7, meaning 7 flats, to +7, meaning 7 sharps), for a set of measures. The direction of the transposition is upwards or downwards. As an example, a melody in C starting on C3, transposed to G (1 #) will start on G3 if upwards or on G2 if downwards.

MNLTransposeByInterval(...)

This music notation software library function transposes the score using the given interval specification, for a set of measures. The note interval represents the interval in terms of note difference (0 = unison, 1 = second, 2 = third,...); it is the number of steps to add or subtract from the original note. C to D is a second, it is one note difference in the natural scale. The MIDI interval is the number of semitones in the interval. For instance, a Major third is 4 semitones. These two numbers thus represent any given interval unambiguously. A perfect fourth up is then (note Interval = +3, midi Interval = +5). A minor sixth down is (note Interval = -5, midi Interval = -8).

The pairs (note Interval, midi Interval) are not all possible. Only valid standard intervals are accepted by the function: unison, second, third, fourth, fifth, sixth, seventh or their octaves, and they must be perfect, augmented, diminished, minor or major.

As a special case, if the midi Interval is greater than or equal to 1000 (which is no valid midi interval anyway) then the transposition is done simply by shifting the notes on the staff, with no modification of the accidentals. This is used for instance to transpose between different clefs. With a value of 1000, the transposition is done on all staves. With value 1001, it is done only on staff 1, with 1002 on staff 2,...

The key signature may be adapted according to the resulting transposition. Depending on the accidentals present in the measures, and if the resulting key signature is outside the range of [7 flats, 7 sharps], the result is not guaranteed, as some notes may become impossible to specify (for instance notes that would require a triple sharp or flat).

MNLNewPageLayout(...)

This music notation software library function will create a new page layout for the score. The size of the paper is provided in millimeters. A scale factor can be used to increase the global size of the music (1.0 is standard 100 % display). Specification of the margins are in millimeters. If set to zero, the music will fill the whole page.

The staffFlags parameter is used to select which staves are displayed. If set to zero, then all staves are displayed. Otherwise, bit 0 must be set to display staff 1, bit 1 must be set to display staff 2, and so on. At least one existing staff must be visible, or the function will display automatically staff 1. The visible staves will also be used while displaying the score in wrapping mode.

staffChords is used to specify on which staff to display the chord symbols. If set to -1, it will not affect the existing chord symbols. If set to 0, no chord will be displayed. Otherwise, the chord symbols will be displayed above staff number staffChords.

This function must be called for an imported MIDI file (as a MIDI file does not have a page layout defined) before you can print it to a PDF file or display it in page view. Please note that some musicXML or Pizzicato file may also not have a default page layout when loaded in memory. You can also use this function to change the page layout of an existing document.


Section F - Playing the score

MNLOpenMidiPort(...)

This music notation software library function will open and prepare a MIDI output port to play a score. It must be called successfully before starting to play a score. This call must be matched with a call toMNLCloseMidiPort to close the MIDI port. Between these two calls, the Midi port is open and the internal Midi manager is running and using a one millisecond timer callback, for handling the timing of a Midi output flow. This timer also refresh the graphic pointer following the playback, the note coloring, as well as the piano keyboard and guitar fret board real time display.

To play a score on a standard MIDI output of the computer, midiOutIndexmust be a valid index between one and the total number of MIDI ports available.

To play the score with a sound library, set midiOutIndex to zero, but you must first load a sound library by calling MNLOpenSoundLibrary.

On the Windows API, the total number of MIDI outputs is returned bymidiOutGetNumDevs( ).

On Mac, use midiOutIndex = 1 to use the standard Quicktime instrument library. Values 2 and up are used to access possibly defined MIDI port on the Mac.

MNLCloseMidiPort(...)

This function will close the MIDI output port that was open and prepared by MNLOpenMidiPort.

MNLOpenSoundLibrary(...)

This music notation software library function opens a sound library of audio samples, so as to play the score without using the MIDI standard interface of Windows or Mac. The library must be prepared with Pizzicato Professional 3.6, from any General Midi SoundFont file library (file extension ".sf2"). This kind of library may be loaded freely or bought on the Internet, according to the use for commercial purposes or not. You are responsible for respecting the copyrights and license rights of the library you want to use.

The SDK can use SoundFont files to play the music, but a format conversion must be executed first, with Pizzicato Professional 3.6 (a downloadable license of Pizzicato Professional 3.6 is included in the price of the SDK). Here is how to do it.

Let us say that the SoundFont file you want to use is called "mysounds.sf2". It must be a General Midi compatible sound file, with 128 instruments + drum kit, otherwise the instruments may be wrong while playing (supposing that the music files you load use also General Midi).

  • Start Pizzicato 3.6 Professional

  • In the document manager (left part of the screen in Pizzicato), right-click on the folder "My scores" and select Import a soundfont file... and select your file mysounds.sf2.

  • In the next dialog box, keep the options by default (Editable sampler and Sort by banks and instruments) and click on Import.

  • When the operation is done, exit Pizzicato.

  • You must now copy the file and samples to the path of the MNL library, so that the program will be able to load all sound data. Copy the file named mysounds.piz from "my documents / Pizzicato 3.x / My scores" to the main path of the library (as defined by a call to MNLLoad). You must also copy the foldermysounds from "my documents / Pizzicato 3.x / DataEN / Libraries / Music libraries / Audio / SoundFonts", to the main path of the library. This folder contains all the sample files of individual instruments and notes. Do not forget to add these files in your program installer, so that the end user can use them.

When this is done, you can call MNLOpenSoundLibrary("mysounds") to load the library for playback.

You can edit the mysounds.piz file if you want, for instance to reorganize the sound library or to create a sound library of your own. You will find more information on that in the Pizzicato User Manual.

For more information about importing soundfont files:

http://www.arpegemusic.com/manual36/EN930.htm#J4

For information about how to edit an audio synthesizer:

http://www.arpegemusic.com/manual36/EN940.htm#J6

Once a sound library has been loaded successfully, you can callMNLOpenMidiPort with the midiOutIndex set to zero, to prepare playback to use this sound library. You can also save a document as an audio wave file (file extension ".wav") using the sound from the library.

If a MIDI port is already open, you must first close it withMNLCloseMidiPort.

The correct sequence is to load the sound library and then open a MIDI port with a value of zero. The playback will then be done using the sound library.

MNLCloseSoundLibrary(...)

This function releases the sound library. If you have opened a MIDI port, you must first close it with MNLCloseMidiPort.

MNLIdle(...)

This function must be called in the loop of the main program or in a timer callback, regularly enough so that the real time display of the notes playing and the pointer following the playback is smooth enough.

MNLStartPlaying(...)

This music notation software library function starts playing the specified score on the current Midi port defined by MNLOpenMidiPort. The score is played from measure fromMeasure to toMeasure. When playing is done or a call to MNLStopPlaying interrupts the playback, the functionmyCallbackWhenFinished is called, or nothing is done if you pass NULL to this parameter.

The graphic parameter is a Windows HDC (handle to a device context) that must be valid to display the cursor following the playback as well as coloring the notes played. For Mac, it must be a valid NSView object or sub-class of it. If NULL, then no graphic animation will be displayed.

The graphic parameters (zoom, clip rectangle and position of the measures) are the ones that have been used the most recently on that score (through a call to one of the three display functions). If no display function has been called for the score before starting to play, then the real time animation will not be available.

playbackMode is used only to specify how the audio playback is processed. For a standard MIDI port, this parameter is ignored. While playing with a sound library, two modes are possible:

  • playbackMode = 0 : The program computes the sound into memory buffers in advance of the playback. This mode is more suited to scores with a lot of staves and high density of notes, but may require a lot of memory.

  • playbackMode = 1 : The program computes the sound in real time. When there is only a few staves to play, or when the general note density is not too high, this mode should work properly. For instance, piano music should play correctly in that mode.

MNLStopPlaying(...)

This function will stop the playback of the score that is now playing.

MNLGetPlayingPosition(...)

This function returns the current playing measure number (from 1 to the total number of measures), beat number (from 1 to the total number of beat in that measure) and units (one quarter note is 480 units). It is used to know exactly where the music is playing right now.

MNLSetPlaybackOptions(...)

This music notation software library function sets the playback options as various flags telling the library which effect to play through MIDI commands. A score has 3 sources of effects :

  1. Initial values: these values are used to initialize the MIDI synthesizer before starting to play.

  2. MIDI commands that are associated in the MIDI tracks related to the staves.

  3. MIDI commands that are interpreted from the graphic symbols like nuances, tempo markings, ...

This function enables/disables the playback of MIDI commands coming from the MIDI tracks ( midiFlags ) and the commands coming from the graphic symbols ( symbolFlags), for the following effects :

  • 0x0001 : MIDI volume

  • 0x0002 : velocity

  • 0x0004 : tempo

  • 0x0008 : duration

  • 0x0010 : modulation

  • 0x0020 : reverb (Midi controller 91)

  • 0x0040 : Pitch bend

  • 0x0080 : Start of notes

  • 0x0100 : chorus (Midi controller 93)

  • 0x0200 : Polyphonic After Touch

  • 0x0400 : Monodic After Touch

  • 0x0800 : Patch (program change)

  • 0x1000 : Other controllers

The values may be combined as logical OR. By default, all flags are enabled, so the default values are 0x1FFF for both flags.

MNLGetPlaybackParameter(...)

This music notation software library function returns the value of a playback parameter, for the given staff. The possible values of for parameters are:

  • 1 : Tempo value, in quarter note per minute (from 1 to 500). For the tempo, the staff is ignored, but should be in the valid range of available staves in the score.

  • 2 : MIDI volume, from 0 to 127

  • 3 : MIDI pan (left to right, 0 to 127 , 64 is central position)

  • 4 : Program change (instrument), from 0 to 127, in General Midi standard.

  • 5 : returns the MIDI channel (from 0 to 15) used by that staff.

The value returned is the default value that is sent before playing the score.

MNLSetPlaybackParameter(...)

This function specifies the value of the given playback parameter, for the given staff. The possible values are the same as forMNLGetPlaybackParameter, except for value 5, as the MIDI channel is fixed by the document.

MNLDisplayKeyboard(...)

This music notation software library function defines a keyboard graphic area, where notes playing in a score will be displayed in real time. The width of a white key is provided, in screen pixels. A value of zero will adapt the width of the keys according to the height of the keyboard. The rectangle where the keyboard will be displayed in the graphic area is also provided.

The octave is the first octave that will be displayed on the keyboard. A value of 3 will display the first note as C3 (midi pitch value 60).

For Windows, graphic is a device context handle that must stay valid until the keyboard is released. On Mac, it is an NSView object or sub-class of it.

This function defines the keyboard. It can be released withMNLReleaseKeyboard. It can be redrawn with MNLRefreshKeyboard.

MNLKeyboardMidiFilter(...)

Defines the MIDI channels which will be displayed on the keyboard during playback. If bit 0 of midiFilter is set to 1, then notes of MIDI channel 0 will be displayed. Same for bits 1 to 15. You can find which MIDI channel is used on which staff by using the function MNLGetPlaybackParameterwith paramNumber = 5.

MNLReleaseKeyboard(...)

Releases the keyboard that has been created with MNLDisplayKeyboard.

MNLRefreshKeyboard(...)

This music notation software library function will redraw the keyboard by using the graphic parameter. For Windows, it is casted to the HDC type. On Mac, it is an NSView object or sub-class of it.

The keyboard may be displayed in two different ways. The first way is when the window is refreshed by the operating system, in which case you should use the MNLRefreshKeyboard with the graphic parameter provided by the operating system. The other way happens during playback, when notes are displayed as a result of playback. In that case, the keyboard is updated through the next call to MNLIddle and the drawing is done on thegraphic parameter provided when calling MNLDisplayKeyboard to define the keyboard

MNLDisplayFretboard(...)

Defines a fret board graphic area, where notes playing in a score will be displayed in real time.

fretDist is the distance between the two first frets, in screen pixels. A value of 60 is quite standard, but according to the width of the fret board you want to display, you may adapt this value.

The rectangle where the fret board will be displayed in the graphic area is also provided.

For Windows, graphic is a device context handle that must stay valid until the fret board is released. On Mac, it is an NSView object or sub-class of it.

This function defines the fret board. It can be released withMNLReleaseFretboard. It can be redrawn with MNLRefreshFretboard.

MNLFretboardMidiFilter(...)

Defines the MIDI channels which will be displayed on the fret board during playback. If bit 0 of midiFilter is set to 1, then notes of MIDI channel 0 will be displayed. Same for bits 1 to 15. You can find which MIDI channel is used on which staff by using the functionMNLGetPlaybackParameter with paramNumber = 5.

MNLRefreshFretboard(...)

This function will redraw the fret board by using the graphic parameter. For Windows, it is casted to the HDC type. On Mac, it is an NSView object or sub-class of it.

The way the fret board is displayed is the same as explained for the keyboard.

MNLReleaseFretboard(...)

Releases the fret board that has been created with MNLDisplayFretboard.

MNLResetMidi(...)

This music notation software library function resets the MIDI port according to the following midiResetMode values:

  • 0 : no reset
  • 1 : sends NOTE OFF midi messages for all notes that have been tracked to be playing.
  • 2 : sends an ALL NOTES OFF on the open MIDI port, for all MIDI channels
  • 3 : sends NOTE OFF midi messages for all notes and all MIDI channels.

In cases 1, 2 and 3, the sustain pedal is also switched off with a MIDI controller message.

If keyboardReset is non zero, all notes graphically displayed on the keyboard are cleared.

If fretboardReset is non zero, all notes graphically displayed on the fretboard are cleared.


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 Software Library Level I to Music SDK...



Copyright 2012 - Arpege Music - Dominique Vandenneucker