Installing Masterpiece

This page lists every file a Masterpiece release offers, the systems each file runs on, what it installs and where, what happens at the first start, and how to update and remove the program. Use it to pick the right file for a computer, phone or tablet, to install it, and to find the plugins and the program’s data afterwards.

Release files

Each release on github.com/bonninr/masterpiece/releases carries the files below. <version> is the release number, for example 0.8.0. Every file name starts with masterpiece-<version>-.

The Raspberry Pi, Flatpak and mobile builds contain the standalone program only. The plugin formats are built for Windows, macOS and the Linux PC packages.

Download addresses

The addresses below on masterpieceorgan.com send the browser to the matching file of the latest release. When the latest release lacks the file, the address leads to the release page.

The two ARM .tar.gz archives have no short address. They are on the release page.

System requirements

Notes:

• The Windows program links the Visual C++ runtime statically. No redistributable package needs installing.
• The .deb packages were tested in CI by installing them in Debian 12 and Ubuntu 24.04 containers, for all three architectures.
• Android builds exist for 64-bit processors only. The build file gives the reason: a 32-bit device cannot hold a sample set worth playing.
• Memory is set by the sample sets. The default limit for the samples of one organ is 80% of the computer’s memory, with a floor of 512 MB. See Memory, loading and streaming and Small, medium and large organs.

Processor features and the vector engine

The audio engine renders several samples at a time with the processor’s vector unit. It picks the unit once, when the program starts.

The release builds target the baseline x86-64 instruction set and choose AVX2 at run time. A processor that lacks AVX2 runs the same program on the SSE2 path.

The box Faster audio engine on Settings > Organ settings… > Loading turns the vector engine on and off. It is on by default and takes effect at once. When on, the box reads Faster audio engine: using AVX2 (or SSE2, or NEON); on a processor that has none of them it reads Faster audio engine: not available on this processor. Setting the environment variable MASTERPIECE_SIMD=0 before starting the program forces the per-frame engine.

Windows

Installer

Run masterpiece-<version>-windows-setup.exe. The installer puts bin\Masterpiece.exe and Uninstall.exe into an install folder whose default name is Masterpiece, adds a Start menu entry in a folder that defaults to Masterpiece, adds an entry in Windows Apps & features, and registers the file types listed under File associations.

The installer installs Masterpiece.exe only. The VST3 plugin ships in the Windows zip.

The release workflow adds no code signature to the Windows files.

A silent installation, as used in the project’s own tests:

masterpiece-<version>-windows-setup.exe /S /D=C:\Path\To\Masterpiece

/D= has to be the last argument and takes no quotes. The silent uninstaller is Uninstall.exe /S in the install folder.

Zip

masterpiece-<version>-windows.zip runs from any folder and installs nothing. Extract it and start Masterpiece.exe. The archive also holds the VST3 plugin Masterpiece.vst3; copy it to a folder the DAW scans (see Plugins).

macOS

Download the zip for the processor: macos-arm64 for Apple silicon, macos-x86_64 for Intel. The zip unpacks to a folder Masterpiece that holds Masterpiece.app, Masterpiece.component (Audio Unit) and Masterpiece.vst3. Move Masterpiece.app to Applications.

The macOS builds are unsigned. At the first start macOS may report that Masterpiece “is damaged and can’t be opened”. Remove the quarantine flag and open the app from its context menu:

xattr -cr /Applications/Masterpiece.app

Then right-click Masterpiece.app and choose Open.

The Intel build runs on Apple silicon through Rosetta; it uses the SSE2 vector path there.

Linux

Flatpak

flatpak install --user ./masterpiece-<version>-linux-x86_64.flatpak
flatpak run io.github.bonninr.Masterpiece

The bundle runs on the freedesktop 24.08 runtime. Its permissions:

A sample set elsewhere (for example under /data) needs the folder granted:

flatpak override --user --filesystem=/data io.github.bonninr.Masterpiece

The Flatpak contains no plugins.

Debian, Ubuntu and relatives (.deb)

sudo apt install ./masterpiece-<version>-linux-amd64.deb

The package is named masterpiece and installs:

The package depends on libasound2 (or libasound2t64), libfreetype6, libfontconfig1, libx11-6, libxext6, libxrandr2, libxinerama1, libxcursor1 and libgl1, plus the C library version the binary needs. apt installs them. JACK is optional: Masterpiece opens libjack at run time when it exists and then lists JACK as an audio device type.

Remove it with sudo apt remove masterpiece.

Tar archive

masterpiece-<version>-linux-x86_64.tar.gz holds the program and the VST3 and LV2 plugins as loose files. The files are packed from build artifacts, which carry no executable bit; the build’s own launch check runs chmod +x on the binary. Set the bit on the Masterpiece file before the first start:

tar -xzf masterpiece-<version>-linux-x86_64.tar.gz
chmod +x path/to/Masterpiece

The libraries listed for the .deb have to be present on the system.

Raspberry Pi

Pick the package for the installed operating system, 64-bit or 32-bit:

sudo apt install ./masterpiece-<version>-linux-arm64.deb     # Raspberry Pi OS, 64-bit
sudo apt install ./masterpiece-<version>-linux-armhf.deb     # Raspberry Pi OS, 32-bit

Both install the program as masterpiece, with the menu entry and the file types. They contain no plugins. The tarballs linux-arm64.tar.gz and linux-armhf.tar.gz hold the same program as loose files, with the same chmod +x step as above.

The 64-bit build targets plain ARMv8-A, which covers the Raspberry Pi 3 to the Raspberry Pi 5. The 32-bit build is compiled for ARMv7-A with NEON and VFPv4 (-march=armv7-a -mfpu=neon-vfpv4, hard-float) and needs a processor with those.

Both builds use the NEON vector engine. Audio on the Pi goes through ALSA, or through JACK when libjack is installed. See Audio, room and mixer.

Android

Download masterpiece-<version>-android.apk on the device and open it, or install it from a computer with adb:

adb install -r masterpiece-<version>-android.apk

All versions share one signing key, so a newer APK installs over the older one and keeps the organs and settings.

The manifest asks for:

USB host, MIDI and Bluetooth LE are declared as optional features; the app installs on devices that lack them. Phones and tablets covers the app itself.

iPhone and iPad

masterpiece-<version>-ios.ipa is unsigned, and iOS runs only signed apps. Sign and install it with a sideloading tool and an Apple ID of your own; AltStore and Sideloadly are the tools the project’s build notes name. No Apple developer account is needed. The steps for each tool are in the 0.7.0 release notes.

Phones and tablets covers the app itself.

Plugins

The plugin formats are VST3 (Windows, macOS, Linux), Audio Unit (macOS) and LV2 (Linux). The plugin shares its settings folder with the standalone program. See Plugins in a DAW.

There are no separate plugin downloads. Windows and macOS ship the plugins as bundles inside the zips; copy them into a folder that the host scans.

File associations

Windows, macOS and Linux register the same five file types: .Organ_Hauptwerk_xml, .CustomOrgan_Hauptwerk_xml, .organ, .orgue and .rar. Double-clicking or Open with passes the file to the program, which opens it as File > Open… does. See Opening an organ.

First start

Settings folder

Masterpiece keeps its settings, logs and caches in a folder named Masterpiece inside the user’s application-data folder:

Files and folders lists the contents. Two files decide the first start:

Audio device defaults

Before the window opens, the program starts the system’s default audio device with two output channels and no input. A device that opens at a rate below 44.1 kHz is moved to 48 kHz, or to 44.1 kHz when 48 kHz is unavailable. On a first start, or when a saved setup could not be used, the buffer size is the available size nearest to about 10 ms. A saved setup that names missing hardware, or that opens with no live output, is replaced by the defaults.

MIDI inputs

At the start every MIDI input is opened, except those switched off earlier. A console plugged in for the first time plays at once. An input that another program holds is tried again every 3 seconds.

The first-run wizard

On a first start the window opens with a dialog titled Welcome to Masterpiece. It has three steps, shown as Step 1 of 3 and so on. Back and Next move between steps, Next becomes Finish on the last one, and Skip setup ends the wizard at any step. Finish and Skip setup both write settings.mpglobal with the current defaults, which ends the first-run state.

The wizard is a dialog of the standalone program. The plugins and the --gui-only mode skip it. It appears while settings.mpglobal is missing, and any write of that file ends the first-run state. Finish and Skip setup write it.

To see the wizard again, close Masterpiece and remove or rename settings.mpglobal. The general settings start from their defaults at the next start.

The first organ

The first load of each organ opens Organ settings on the Loading tab before the samples are read, so the memory profile can be chosen. Keep changes starts the load. The organ’s console is on screen in seconds, ahead of the samples. See Opening an organ and Memory, loading and streaming.

Updating

The program has no update check. Install a newer release the same way as the first one; settings, favourites and caches stay in the settings folder.

Uninstalling

The settings folder holds the saved organ settings, favourites, MIDI maps and the sample cache. The program creates it at run time; the installers and packages place no files in it, and the routes below leave it in place. Delete the folder by hand to remove that data. The sample cache is as large as the decoded samples of an organ and can fill several gigabytes; Cache folder on Settings > Organ settings… > Loading shows where it is.