MusicRack – A Digital Sheet Music Display System

January 18, 2020

MusicRack is a simple yet flexible digital sheet music display system that I developed for the Raspberry Pi, but which can also be built on other Linux systems, and probably Mac and Windows too. The main application is implemented in Lazarus/FreePascal, and the image processing engine used to prepare music for display is written in C.

MusicRack displayed on a 22" HP monitor on top of my (modified) 1962 Hammond organ.

MusicRack displayed on a 22″ HP monitor on top of my (modified) 1962 Hammond organ.

To keep things as simple as possible, there are no command line options, no settings dialog, and no configuration file.

The source code for MusicRack is freely available, and can be found at https://github.com/svorkoetter/MusicRack.

System Requirements

MusicRack is intended to run full-screen on a widescreen (e.g. 16:10 or 16:9) monitor, displaying two pages at once. It works well on 1920×1080 and 1920×1200 monitors, but the higher the resolution, the better it will look.

MusicRack uses the following libraries and utilities, or newer versions thereof:

  • libjpeg
  • libpng12-0
  • libtiff5
  • zlib1g
  • GhostScript 9.26

If you are building MusicRack from source, you will need the following tools and libraries, or newer versions thereof:

  • To recompile the MusicRack application:
    • Lazarus 1.6.2
    • Free Pascal 3.0.0
  • To recompile the score preparation utility:
    • GCC 4.9.2
    • libjpeg-dev
    • libpng12-dev
    • libtiff5-dev
    • zlib1g-dev

Score Files

By default, MusicRack expects to find all score files in “$HOME/SheetMusic”, or subdirectories thereof. Scores can be provided as PDF, BMP, JPEG, PNG, or TIFF files. If MusicRack is invoked with one or more command line arguments, they are interpreted as directory names in which to search for scores instead of$HOME/SheetMusic”.

There is no index file or database that maps song titles to score files. The name of the score file itself, minus the file extension, is used as the title. Any sequence of one or more spaces or underscores in the file name is replaced by a single space when MusicRack displays the title.

For multi-page scores provided as images (BMP, JPEG, PNG, or TIFF), a separate file is needed for each page. These files should all have the same name, except for a suffix beginning with a “-” (ASCII minus sign) and followed by one or more digits. There should be no leading zeros on the suffixes.

A score in PDF format may optionally have one or two suffixes, each beginning with a “+” or “-” character, followed by one or more digits. These indicate the number of pages to skip at the beginning of the score when first opening it or pressing Home or a page number key, and the number of pages to stop short of the end of the score when pressing the “End” key. This is useful for skipping cover pages, end notes, etc. The skipped pages are still reachable using the other navigation keys.

The Score Preparation Process

The first time a score is opened for display, MusicRack will prepare the score for display. If the score is in PDF format, it will first be split into separate pages.

For each page of the score, MusicRack will produce pre-scaled image files suitable for fast display on your monitor. These will be saved in a subdirectory with a name of the form “.WxH”, where W is half the screen width in pixels and H is the screen height. For example, on a 1920×1080 screen, the subdirectory is named “.960x1080”. When a score is opened subsequently, the saved images will be used (unless the original files have been updated).

The pre-scaling process is performed by MusicRack’s muprep utility, which will also attempt to optimize each page for display. This includes conversion to greyscale, black and white level correction, trimming whitespace from the edges, and straightening scanned scores that are skewed by as much as two degrees. The resulting images are written out as colour-mapped PNG files using an off-white background colour to be easy on the eyes. For more details, please refer to muprep‘s documentation.

An example of how a score is automatically straightened and cleaned up.

An example of how a score is automatically straightened and cleaned up.

Unfortunately, MusicRack can’t fix everything. In the case of a scanned score, the scan should already have been cropped by hand to remove visible paper edges and bindings. For best results, a scan should be at 300dpi or higher.

Selecting a Score

To open a new score, press the “O” key, or right click anywhere and select “Open” from the popup menu. This will display the score selection dialog box.

The score selection dialog.

The score selection dialog.

The left side of the dialog shows the most recently selected scores, with the most recent at the top of the list. The right side lists all the scores that MusicRack knows about, sorted alphabetically (ignoring leading words “A”, “An”, or “The”).

Navigating Through a Score

Navigation through a score is done by keyboard shortcuts, since no one wants to stop playing to pick up a mouse. If you have a touchscreen, or really want to use that mouse, there are also gestures for the most common operations.

Operation Letter Key Alternate Keys Gesture
Back one page L Backspace, LeftArrow Swipe right
Forward one page R Space, Tab, RightArrow Swipe left
Back two pages U PageUp, UpArrow Swipe down
Forward two pages D PageDown, DownArrow Swipe up
First page H Home
Last page E End
Specific page 1 to 9, 0 F1 to F24
Open score list O
Quit Ctrl+Q

When performing a swipe operation, be careful not to start on an annotation, as this will move the annotation instead of changing pages.

Annotations

Musicians like to write stuff on their sheet music, so MusicRack lets you add annotations to your scores. Unlike paper sheet music, the actual scores are not defaced. The annotations are stored separately (in the “.annotations” subdirectory of the directory containing the score), and drawn over top of the page they belong to when the page is displayed.

To create an annotation anywhere on a page, click the left mouse button at the desired location. This will open a multi-line edit field into which you can type. When done, press the “Esc” key to close the edit field.

Creating or editing an annotation.

Creating or editing an annotation.

An existing annotation can be edited by clicking on it. This will reopen the edit field. Once again, pressing “Esc” will close the edit field.

Annotations rarely end up exactly where you want them, so they can be moved by clicking and dragging. An annotation can be dragged anywhere on the page that it belongs to. It cannot be dragged to another page.

Right clicking on an annotation (while it is not open for editing) will display a popup menu of formatting options:

Annotation formatting options.

Annotation formatting options.

  • Style: any combination of bold, italic, underlined, and strikethrough
  • Color: any one of black, red, green, blue, gray, or highlight
  • Size: any one of small, medium, large, subtitle, or title
  • Formatting and removal options on the popup menu

The selected formatting applies to the entire annotation. There is no facility for individually formatting words therein.

An annotation can be removed by selecting Remove from the popup menu.

Controlling MusicRack with Raspberry Pi GPIO Inputs

The original intention was to include support for manipulating MusicRack with GPIO inputs on the Raspberry Pi, to make it easy to connect dedicated page turning buttons or foot pedals for example. For various reasons, this proved troublesome, and it was decided to write a separate GPIO-to-Keypress utility, https://github.com/svorkoetter/GPIOKey, that is independent of MusicRack (and thus usable with other applications too).

My Hammond organ, pictured at the top of this article, has a Raspberry Pi based synthesizer added on top (replacing the top panel). The rightmost two control panel’s buttons of the synthesizer send GPIO signals to the Raspberry Pi running MusicRack. The GPIOKey utility is used to convert these into next and previous page commands.

Related Articles

If you've found this article useful, you may also be interested in:

8 Comments

  1. Paul Schmitz
    April 08, 2020

    So this looks like a nice software, but how do I actually run it? Are there precompiled files for the raspberry pi available somewhere or do I really need to install all those tools just to compile it and then run it?

  2. Stefan Vorkoetter
    April 08, 2020

    I only provide the sources, as I don’t have the time to set up a proper installable package. Just providing precompiled files wouldn’t help much if you don’t already have the dependencies installed.

  3. Zac
    May 02, 2020

    I managed to compile muprep and MusicRack on my pi. Unfortunately when I run MusicRack I only get a blank white screen. Any idea what might be wrong? I compiled with lazbuild, no added options, just the project file as input. It’s still located in the source folder.

    Cheers, Zac

  4. Stefan Vorkoetter
    May 02, 2020

    Zac, does the right-click menu work? The screen will be blank until you open a score.

  5. Zac
    May 04, 2020

    Hi Stefan, thanks for your reply. Seems I didn’t read properly. I now can select scores, but the conversion is unsuccessful. It creates the folder “.960×1080”, but the error message comes up “Failed to create $MY_FILE_001.png”. (my sources are PDFs)

    I’m pretty sure it’s not a permissions thing, I’m running it all as root at the moment. I’ve added muprep to my $PATH as well, in case that’s being used

  6. Stefan Vorkoetter
    May 04, 2020

    Where is muprep installed? It should be in the same directory as the MusicRack program.

  7. Zac
    May 04, 2020

    Ah, it was in the MuPrep subdirectory where I had built it with Make. It’s working now, thanks!

  8. Wiebe van der lee
    August 14, 2020

    Hello Stefan
    Thanks for your information about Hammond and good articles
    Because of that I good do recap mine ao28 amp but now I have something that would like your advice I notice that when I was playing that I had a hum and cracking noise I Gould not find the problem but by coincidence when I solder a wire on one of mi drawbar I touch
    The wiring harnas off the manuals to the TG and there was that noise
    After inspection I found it better to replace the whole loom
    79 wire total But now I have problem I have try to put it al back
    But i don’t get the richt tunes I make use of the wiring cart for a B3
    But that thus not work is there some advice of a start point how to do this please advice
    Thanks in advance
    Kr Wiebe from Holland

Leave a Comment

If you do not agree with the comment privacy policy, do not leave a comment.

Want to see your picture next to your comments on this site and others? Visit gravatar.com to register your own globally recognized avatar.

Buy Stefan a coffee! If you've found this article
useful, consider leaving a donation to help support
stefanv.com

Disclaimer: Although every effort has been made to ensure accuracy and reliability, the information on this web page is presented without warranty of any kind, and Stefan Vorkoetter assumes no liability for direct or consequential damages caused by its use. It is up to you, the reader, to determine the suitability of, and assume responsibility for, the use of this information. Links to Amazon.com merchandise are provided in association with Amazon.com. Links to eBay searches are provided in association with the eBay partner network.

Copyright: All materials on this web site, including the text, images, and mark-up, are Copyright © 2020 by Stefan Vorkoetter unless otherwise noted. All rights reserved. Unauthorized duplication prohibited. You may link to this site or pages within it, but you may not link directly to images on this site, and you may not copy any material from this site to another web site or other publication without express written permission. You may make copies for your own personal use.