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

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.


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,, 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:


  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

  9. Dave Newton
    February 16, 2021

    Hi Stefan, I am using MusicRack and it performs extremely well. I am now trying to run gpiokey to turn pages using pedal switches. I am running a Pi 4 with Dietpi x64 and LXDE. I am using gpio 2.6 ( as V 2.52 does not work when trying to enable the pull up resistors on the GPIO pins. Using gpio at the command line I can read and write to the GPIO pins. My test is with BCM 25 (GPIO.6) pin 22. The command I’m running is: gpiokey 25 ~ + d. The pullup resistor is enabled but I get the error message:
    gpiokey: GPIO error with pin 25: unrecognized key symbol. If I leave off the ~ i.e. gpiokey 25 + d I don’t get an error message. Can you offer any sort of help please?

  10. Alan Carter
    January 30, 2022

    Hi Stefan- I would love one of these digital music systems- is it the sort of thing that my local pc shop could sort for me do you think. I have no knowledge of Raspberry Pie etc.
    many thanks

  11. Stefan Vorkoetter
    January 30, 2022

    Hi Alan: I don’t think a PC shop would be up to this sort of thing. It will theoretically work on a PC, but someone would have to compile it there.

  12. Simon Smith
    July 20, 2022

    Hello, I love using MusicRack and appreciate you making it available for free. It’s just what I was looking for. I have a USB pedal. It sends character ‘b’ for some reason and it was easy to change the code to use this to change the page. Even with the keyboard, it takes about 2 seconds to change page. Do you know if this latency can be reduced? I find myself having to press the key/pedal about a bar early.

  13. Stefan Vorkoetter
    July 22, 2022

    Hi Simon. I’m glad to hear you’re finding it to be useful. Which previous command did you set up to replace with ‘b’? Was it ‘R’ or ‘D’. I asked because ‘R’ goes forward only one page at a time; the one you were reading shifts left, and then the new pages appears on the right. Thus, the page you’re currently playing doesn’t go away when changing pages. I agree that everything has a bit of delay to it though; a Pi isn’t fast.

  14. Simon Smith
    July 22, 2022

    I can’t remember now, this was some time ago. It was probably ‘d’ so it behaves like a normal score turning the page would. I might try overclocking the Pi to speed it up.

    Could you post the full steps for installation? I found it tricky and I’m sure others will too. I wrote the steps I used down somewhere, but can’t find it now.

  15. Stefan Vorkoetter
    July 22, 2022

    I’m not sure how much faster it can get, but it probably not make a huge difference. I’m not sure what exactly you mean by the “full steps of installation”.

  16. Simon Smith
    July 24, 2022

    Just all the packages needed and how to build it. I think I had problems with Lazarus.

  17. Stefan Vorkoetter
    July 28, 2022

    The packages are all listed in the System Requirements section right near the beginning of the article. The source code is under and

  18. Simon Smith
    October 24, 2022

    Hello, I’m having a problem where PDF files created with gscan2pdf cannot be read by MusicRack. It gets as far as splitting the PDF files into temporary files (e.g. test-tmp-001.png), then a blank popup with a no entry sign appears. There’s no information what the problem is. Have you seen this before and have any ideas?

  19. Simon Smith
    November 02, 2022

    Hello, I’ve been having problems getting some newly scanned PDF files from gscan2PDF to open. The temp files get created, but then a blank popup appears with only an exclamation Mark only, with no text explaining what the problem is. Have you seen this before and any ideas how to proceed?

  20. SimonSmith
    November 07, 2022

    Hello, I’m having problems with PDFs generated by gscan2pdf. When I attempt to open thesefiles from Musicrack, a popup with only an exclamation mark and no text appears. It seems to generate some temporary files only. Is there a way to find out what the problem could be?

  21. Jade
    March 01, 2024

    I soooo want to build this, but I am so noobie that I don’t understand how to use your files! Do I need to compile them for raspberry pi with Lazarus? Would you consider writing a readme that outlines the basic steps for getting your code onto the raspberry pi?

  22. Jade
    March 05, 2024

    I get 4 Errors when trying to run this on my pi4.
    GPIO.pas(124,15)Error:Illegal qualifier,
    GPIO.pas(134,15)Error:Illegal qualifier,
    GPIO.pas(195,15)Error:Illegal qualifier,
    and GPIO.pas(199,15)Error:Illegal qualifier

    Could you shed some light on this?

Leave a Comment

Want to see your picture next to your comments on this site and others? Visit 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

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 merchandise are provided in association with 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 © 2024 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.