Powerful music score control library

2023 Conmajia, 2018 Ajcek84
SN: 23C.1
This Chinese translation has been approved by the original author.

Introduction

PSAM control library - Polish Music Document System - is a powerful WinForm library for displaying and formatting music scores. It includes a control called IncipitViewer for drawing music scores. The content of the music scores can be read from the MusicXml file, or fugues can be added to the program. , notes, measures, etc. This control is a component developed for the PSAM software (Figure 1). When I realized that other software developers might want to use its functionality, I decided to release the control under a BSD license. The PSAM control library is entirely implemented in C#.

Figure 1. Screenshot of PSAM system, demonstrating the display effect of multiple IncipitViewers

Use code

The IncipitViewer control requires special musical fonts to draw notes, etc. The download resources provided in this article come with Polihymnia's TrueType font so that you can install and use it directly. This font is based on Ben Laenen's Euterpe font, released under the Sil Open Font License.

IncipitViewer (PSAMControlLibrary.dll) is a standard C# control library. Simply drag and drop it into the Visual Studio Form Designer toolbox to get started. The control usage is similar to ordinary controls, such as TextBox, etc. If you create the IncipitViewer control programmatically, use the following code.

IncipitViewer viewer = new IncipitViewer();
viewer.Dock = DockStyle.Fill;
Controls.Add(viewer);

Generally speaking, Visual Studio will automatically add

using PSAMControlLibrary;

This control provides the function of reading music scores from MusicXML files - only the first line staff ¹ , ignoring subsequent staffs.

viewer.LoadFromXmlFile("example.xml");

The effect of reading and displaying music scores from a file is as follows.

Figure 2. Using IncipitViewer to display MusicXML file content

Use ClearMusicalIncipit()the method to clear the current display.

This control provides code for programmatically adding notes, etc. For example, the following code adds a G clef to line 2 of the score.

Clef c = new Clef(ClefType.GClef, 2);
viewer.AddMusicalSymbol(c);

and a new quarter note in the key of G (1=G4/4).

Note n = new Note("G", 0, 4, MusicalSymbolDuration.Quarter,
  NoteStemDirection.Up, NoteTieType.None,
  new List<NoteBeamType>() {
    
    NoteBeamType.Single});
viewer.AddMusicalSymbol(n);

The first parameter of the Note constructor is the key name (A, B, C, D, E, F, G), and the second parameter is the sharp number (+) or the flat number (-). If the rising and falling tone is 0, it means the original tone. The third parameter is octave. The next parameters are: note tempo, stem direction, and tie type (if none NoteTieType.None). The last parameter is a list of characters. If the note doesn't have any beams, even if the note's duration is longer than an eighth note, you still need this list, but it will only have one element NoteBeamType.Single. To clearly illustrate how beam lists work, the following code will try to add a group consisting of two sixteenth notes and one eighth note:

Note s1 = new Note("A", 0, 4, MusicalSymbolDuration.Sixteenth, 
	NoteStemDirection.Down, NoteTieType.None,
	new List<NoteBeamType>() {
    
     NoteBeamType.Start, NoteBeamType.Start});
Note s2 = new Note("C", 1, 5, MusicalSymbolDuration.Sixteenth, 
	NoteStemDirection.Down, NoteTieType.None,
	new List<NoteBeamType>() {
    
     NoteBeamType.Continue, NoteBeamType.End });
Note e = new Note("D", 0, 5, MusicalSymbolDuration.Eighth, 
	NoteStemDirection.Down, NoteTieType.None,
	new List<NoteBeamType>() {
    
     NoteBeamType.End });
viewer.AddMusicalSymbol(s1);
viewer.AddMusicalSymbol(s2);
viewer.AddMusicalSymbol(e);

The sheet music shown is below.

If the break bar is set to NoteBeamType.Single, the score is as follows.

This control also supports colored notes by simply modifying the note MusicalCharacterColorproperties.

Although IncipitViewer only supports single staffs, it still supports chords because they are part of the idiom of many monophonic instruments. If a note's IsChordElementproperty is set to true, then it is treated as the chord element of the previous note:

Note n1 = new Note("C", 0, 4, MusicalSymbolDuration.Half, 
	NoteStemDirection.Up, NoteTieType.None,
	new List<NoteBeamType>() {
    
     NoteBeamType.Single });
Note n2 = new Note("E", 0, 4, MusicalSymbolDuration.Half, 
	NoteStemDirection.Up, NoteTieType.None,
	new List<NoteBeamType>() {
    
     NoteBeamType.Single });
Note n3 = new Note("G", 0, 4, MusicalSymbolDuration.Half, 
	NoteStemDirection.Up, NoteTieType.None,
	new List<NoteBeamType>() {
    
     NoteBeamType.Single });
n2.IsChordElement = true;
n3.IsChordElement = true;

viewer.AddMusicalSymbol(n1);
viewer.AddMusicalSymbol(n2);
viewer.AddMusicalSymbol(n3);

The results are as follows.

The code below demonstrates dot, rest, and bar breaks.

Note n4 = new Note("A", 0, 4, MusicalSymbolDuration.Half,
	NoteStemDirection.Up, NoteTieType.None,
	new List<NoteBeamType>() {
    
     NoteBeamType.Single });
n4.NumberOfDots = 1;
Rest r = new Rest(MusicalSymbolDuration.Quarter);
Barline b = new Barline();
viewer.AddMusicalSymbol(n4);
viewer.AddMusicalSymbol(r);
viewer.AddMusicalSymbol(b);

The results are as follows.

Mouse interaction

When the mouse is hovering over the control, two buttons will appear in the upper right corner: the first is used to save the MusicXml file associated with the control, and the second is used to call the OnPlayExternalMidiPlayerevent handler, which is used as follows.

viewer.PlayExternalMidiPlayer += 
	new IncipitViewer.PlayExternalMidiPlayerDelegate(viewer_PlayExternalMidiPlayer);
void viewer_PlayExternalMidiPlayer(IncipitViewer sender) {
    
    
    //Place your code here
}

With this, you can use code to read notes from existing controls and play them using custom code or other third-party libraries. IncipitViewer.IncipitElement(int i)The method reads the i-th note, while MusicalSymbol.ToMidiPitch()the method converts the note in space to MIDI.

To print the contents of the IncipitViewer control, create an PrintDocumentobject and handle its PrintPageevents.

private void printDocument1_PrintPage(object sender, 
	System.Drawing.Printing.PrintPageEventArgs e) {
    
    
    Graphics g = e.Graphics;
    viewer.DrawViewer(g, true);
}

Next, call Print()the method to print the music document.

PrintDialog dlg = new PrintDialog();
dlg.Document = printDocument1;
if (dlg.ShowDialog() == DialogResult.OK) {
    
    
     printDocument1.Print();
}

The print sample is as follows.

license

This article and its accompanying files and code are released under the BSD license.

---

1. The clef refers to the clef and the staff together, as shown in the figure, the treble clef (top) and the bass clef (bottom).

   

   ↩︎