Pipe organ sample player for Hauptwerk-format and GrandOrgue sample sets.

masterpiece-hero.mp4

Watch the demonstration — thirty-three works on nine organs, recorded from the application's own output · programme and credits
Watch "New tested instruments" — thirty works on fifteen organs, filmed from the running console · programme and credits

Portable archives for every platform are on the releases page, and the plugins have archives of their own for Windows, macOS and Linux. The manual covers installing and every setting.

---

Masterpiece plays sampled pipe organs. It reads Hauptwerk-format sample sets and GrandOrgue organs, draws each instrument's own console, and plays it from the mouse, a MIDI keyboard or a full console. It is an independent implementation in C++20 and JUCE, licensed GPL-3.0-only.

• Standalone application, VST3 and LV2 plugins, and an Audio Unit on macOS
• Windows, macOS (Apple silicon and Intel), Linux, Raspberry Pi (64- and 32-bit), Android and iPhone/iPad
• Tested with more than 100 published sample sets, from a 9-register Flentrop to Nancy's 65 stops on four manuals

Features

Sample sets

• Hauptwerk-format definitions, full and compact, read directly
• GrandOrgue .organ definitions, converted as they load, console included
• Sets played straight from their packages: RAR 4 and 5 (solid, multi-part, multi-volume) and GrandOrgue .orgue
• WAV and WavPack samples, any rate; optional conversion to 48 or 44.1 kHz on load
• Sets that require a publisher's licence load once you confirm you hold it

Console

• The set's own artwork: drawstops, keys, pedals, shoes, jamb pages, several console sizes where a set ships them
• Couplers, sub- and super-octaves, unison off, reversible pistons, crescendo and alternate ranks, all through the set's own switch network
• A stop list grouped by division, for sets drawn across many jambs or shipped as text only; a screen reader reads it, and a key opens it
• A drag across a row of stops draws or retires each one it passes, on the console, the panels and the stop list
• Any page in its own window, remembered per organ
• Simple and Advanced display modes: the main settings with presets, or every setting
• A score panel: MusicXML engraved and played through the organ, with a cursor on the beat; a console piston turns the page in a score app over MIDI

Sound

• Attack, crossfaded sustain loop, and a release chosen by how long the key was held, with a crossfade into it
• Wind model: chests, bellows and valves solved as a system; a full registration lowers the pressure, and pitch and level follow it
• Tremulants per pipe and per chest; enclosures with level and filter per box, shaping the closed sound as the set defines it
• Release alignment for every release, a crossfade length by pitch, and GrandOrgue's short-note level and staccato fade as switches
• Release length: whole, or kept to a length down to 0.15 s, a tracker action's quick release
• Options: a sustain pedal; stop changes that leave held notes as they are
• Unevenness: pipe detune and wind sway, per organ, off by default
• Attack emphasis: each pipe begins louder or softer and settles to its own level
• Hermite interpolation; 725 voices a processor thread (at least 1,536), stealing the longest-fading releases first
• Vectorized engine, AVX2, SSE2 or NEON, 3 to 5 times faster on 512 voices, on by default; rendering on every logical processor, with real-time threads where the system grants them
• Performance presets, from Most voices (8,192) to Fewest voices (512) for a Raspberry Pi or a tablet; any polyphony limit typed in

Memory and loading

• Quality presets, from Best (as recorded, all in memory) to Smallest (16-bit mono, compressed, short releases only)
• Samples held as recorded (bit-identical to the files), 20-bit or 16-bit; stereo can be folded to mono
• Lossless compression in memory, decoded as the samples play: about a third of the plain size, the sound identical to the bit
• Sparse loading: every second or third note loaded, the others played from a neighbour's samples, retuned
• Release tails streamed from disk through per-voice ring buffers; keep the first second or 25, 50 or 75% of each release in memory
• Leave out stops, perspectives or single ranks; left-out stops take their tremulant ranks with them
• Decoded sample cache: a second load reads one cache file; one cache, one per organ, or none, written before the organ plays or in silence while it plays
• A memory limit, 80% of RAM by default; a load that reaches it stops, keeps what it read, and says what to change
• A file that several pipes play is read and held once
• Optionally keep an organ playable after its installation files are removed

Combinations and registration

• Player's own generals (up to 100), divisionals per manual, general cancel, and a 999-frame sequencer numbered from 000 with Insert, on any organ, beside the organ's own pistons
• Combinations that hold couplers, unison offs and octave couplers
• Named combination sets, saved per organ
• Options: Set turns off after storing, on the console and over MIDI; pistons leave the bass and melody couplers alone; a combinaison coupler, the Pedal divisional recalled with the Great's of the same number
• Extra couplers between the manuals at 16', 8' and 4', on any organ

Tuning

• The organ's temperament, equal, or Werckmeister III, Kirnberger III, Vallotti, Young II, quarter-comma meantone, Pythagorean, Silbermann sixth-comma; Scala .scl files
• Pitch in Hz (415, 440, 442 one click away); transposer ±12 semitones
• Voicing: level and tuning per rank and per pipe, with A/B sets to compare
• Voicing EQ: ten presets and the player's own, a MIDI button for each; an EQ, pan and stereo width per rank and per division

MIDI and consoles

• All inputs at once, each mapped to a manual by channel; key range, transpose, velocity window, short octaves, debounce, split keyboards
• MIDI learn for drawstops, pistons, shoes, pages, stepper and transposer; one message can work several stops and couplers
• MIDI out lights a console's drawstops, from the console and from the program, and sends the lamps once an organ loads
• Messages sent on organ load, on unload and on a ready lamp; learnable quit and power-off buttons for a console with no screen
• Live levels for each rank, division and output pair, from MIDI knobs
• Jamb text displays over system exclusive
• A virtual MIDI input on macOS and Linux
• Bluetooth MIDI pairing from the MIDI settings, where the system offers it

Recording and practice

• MIDI recording of notes, stops and shoes, replayable through another registration and on the keyboard each note was played on; Record and Play from console buttons
• Save for a sequencer: a MIDI file for other programs
• Audio recording alongside; metronome in the organ's own audio stream
• Convolution reverb for sets recorded dry

Output

• Mixer pairs on their own device channels, with bass management to a subwoofer channel
• Output compressor and peak limiter, with presets for small speakers, laptop speakers and headphones; off by default
• Settings export and import, one organ's or the program's, as one archive

Remote control

• A web console any browser on the network opens: the organ's stops, pistons, shoes and levels as panels, or its own console pages, drawn by the program
• One control API over HTTP, MIDI system exclusive and OSC, for consoles, scripts and control surfaces

Limitations

• Encrypted samples (.hbw, .hbx) are skipped and listed in the load report
• GrandOrgue divisional couplers are skipped on import

Measured

Friesach, 44 stops, 17 GB, 12,148 files (method and full figures):

Resident format	Memory
32-bit float	21.6 GB
24-bit	16.2 GB
24-bit, lossless compression	5.39 GB
24-bit, lossless compression, releases streamed	3.62 GB
24-bit, lossless compression, shortest release streamed	2.84 GB

Opening at 24-bit, compressed with releases streamed: 43.2 s, and 3.8 s from the sample cache. Streaming assumes SSD-class storage; the status line says when a disk falls behind.

Tested organs

Each set below is a separate, freely published library: 23 by Piotr Grabowski, 14 by Augustine's Virtual Organs. Full credits in ATTRIBUTION.md. Augustine's free sample sets, each downloaded from its own page: hauptwerk-augustine.info.

Screenshots of all 37

Lipiny — a historic case, drawstops lettered in Fraktur	Melcer Chamber Music Hall
A. Volkmann, 1898 · 25 stops · sample set by Piotr Grabowski	chamber organ · sample set by Piotr Grabowski
Azzio	Kraków, St. John Cantius
Mascioni, 2016 · 12 stops · sample set by Piotr Grabowski	40 stops, three manuals · sample set by Piotr Grabowski
Długa Kościelna	Raszczyce
22 stops · sample set by Piotr Grabowski	Vermeulen, 1965 · 21 stops · sample set by Piotr Grabowski
Strassburg	Friesach — three manuals, jambs on their own pages
C. Werner, 1743 · 20 stops · sample set by Piotr Grabowski	Eisenbarth, 2000 · 44 stops · sample set by Piotr Grabowski
Nancy — four manuals; the keys are part of the photograph, and the drawstops are colour-coded by division	Lemmer — a Flentrop under the saints, with the recording perspective on the case
65 stops, four manuals · sample set by Piotr Grabowski	Flentrop, 1977–78 · 9 registers · sample set by Augustine's Virtual Organs
Giubiasco	Alessandria — pipes reached through pallet switches
complete set · sample set by Piotr Grabowski	demonstration set · sample set by Piotr Grabowski
Pinerolo	Ermelo
demonstration set · sample set by Piotr Grabowski	demonstration set · sample set by Piotr Grabowski
Święta Lipka — pipes reached through pallet switches	Nitra
demonstration set · sample set by Piotr Grabowski	demonstration set · sample set by Piotr Grabowski
Erfurt-Büßleben	Erfurt, Predigerkirche — pipes reached through pallet switches
demonstration set · sample set by Piotr Grabowski	demonstration set · sample set by Piotr Grabowski
Obervellach	Düren
demonstration set · sample set by Piotr Grabowski	demonstration set · sample set by Piotr Grabowski
Chorzów, St Hedwig of Silesia	Goch
demonstration set · sample set by Piotr Grabowski	demonstration set · sample set by Piotr Grabowski
Oloron-Sainte-Marie	Bégard
demonstration set · sample set by Piotr Grabowski	demonstration set · sample set by Piotr Grabowski
Nagyrákos — an Angster organ	Hungarian village organs — the organs of two village churches in one set
Angster, 1938 · demonstration set · sample set by Augustine's Virtual Organs	composite set · sample set by Augustine's Virtual Organs
Zalalövő — a modern baroque organ	Császár — a Luber organ
Aquincum · demonstration set · sample set by Augustine's Virtual Organs	F. X. Luber, 1793 · demonstration set · sample set by Augustine's Virtual Organs
Vasvár, Dominican church	Kézdimartonfalva — a Dutch harmonium
demonstration set · sample set by Augustine's Virtual Organs	harmonium · sample set by Augustine's Virtual Organs
Szombathely — an Eule organ	Hajós — an Angster organ
Eule · demonstration set · sample set by Augustine's Virtual Organs	Angster · demonstration set · sample set by Augustine's Virtual Organs
Székesfehérvár, Franciscan church — a Mauracher organ	Székesfehérvár, Cistercian church — an Angster organ
Mauracher · demonstration set · sample set by Augustine's Virtual Organs	Angster · demonstration set · sample set by Augustine's Virtual Organs
Ják Abbey — an Angster organ	Monor, Reformed church — a Rieger organ
Angster, 1902 · demonstration set · sample set by Augustine's Virtual Organs	Rieger · demonstration set · sample set by Augustine's Virtual Organs
Budapest, Church of the Holy Spirit
demonstration set · sample set by Augustine's Virtual Organs

Installing

System	Oldest version
Windows	Windows 10, version 1607
macOS, Apple silicon	macOS 11
macOS, Intel	macOS 10.15

Windows. masterpiece-<version>-windows-setup.exe installs with a Start menu entry; the portable .zip runs from any folder. The VST3 and LV2 plugins are in masterpiece-<version>-plugins-windows.zip, in its VST3 and LV2 folders.

Debian, Ubuntu, Raspberry Pi OS.

sudo apt install ./masterpiece-0.8.1-linux-amd64.deb     # PC
sudo apt install ./masterpiece-0.8.1-linux-arm64.deb     # Raspberry Pi OS, 64-bit
sudo apt install ./masterpiece-0.8.1-linux-armhf.deb     # Raspberry Pi OS, 32-bit

Runs as masterpiece. The VST3 and LV2 plugins for the PC are in masterpiece-<version>-plugins-linux-x86_64.tar.gz.

Other Linux distributions. The Flatpak bundle runs on any x86-64 distribution with Flatpak installed; it uses the freedesktop 24.08 runtime, which Flatpak installs with it when it is not there yet:

flatpak install --user ./masterpiece-0.8.1-linux-x86_64.flatpak
flatpak run io.github.bonninr.Masterpiece

The .tar.gz archives hold the same program in a Masterpiece folder.

macOS. Move Masterpiece.app to Applications. The build is unsigned; if Gatekeeper reports it as damaged, run xattr -cr /Applications/Masterpiece.app and open it with right-click, Open. The Audio Unit and VST3 plugins are in masterpiece-<version>-plugins-macos-arm64.zip and -plugins-macos-x86_64.zip.

Android, iPhone and iPad. The .apk and .ipa on the releases page are installed directly; see the 0.7.0 release notes.

Running

Open takes a definition, a GrandOrgue .organ file, or a RAR or .orgue package. File managers offer Open with Masterpiece; Masterpiece <file> does the same from a terminal.

Option
--odf <file>	Load this organ at startup
--gui-only	Draw the console only, silent, in a second or two
--log <file>	Write a log, with load timings
--log-midi	Log every MIDI message and where it went
--record-midi <file>	Record the session, saved on quit
--play-midi <file>	Play a MIDI file through the organ
--virtual-midi [name]	Publish a MIDI input (macOS, Linux)

All options: Masterpiece --help and COMMAND-LINE.md. Each session writes masterpiece.log in the settings folder; attach it to bug reports.

Audio on Windows: WASAPI exclusive or ASIO for low latency; shared mode adds noticeable delay. On Linux: ALSA and JACK (including PipeWire's JACK); JACK is listed when a JACK library is installed.

Building

C++20 (MSVC 2022, GCC 12+, Clang 14+), CMake 3.22+, Ninja. JUCE, pugixml, cpp-httplib, Verovio, WavPack and the archive libraries are fetched by CMake.

• Debian, Ubuntu, Raspberry Pi OS:

  sudo apt-get install -y build-essential git cmake ninja-build pkg-config \
    libasound2-dev libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev \
    libxcomposite-dev libfreetype6-dev libfontconfig1-dev libglu1-mesa-dev \
    mesa-common-dev libxi-dev libjack-jackd2-dev

• macOS: xcode-select --install, then brew install cmake ninja.
• Windows: Visual Studio 2022 Build Tools with Desktop development with C++; build from the x64 Native Tools prompt.

cmake --preset dev
cmake --build --preset dev

CI presets: ci-linux, ci-macos, ci-windows, ci-linux-arm (32-bit Raspberry Pi cross-build).

Tests run on the small organs in tests/fixtures, in seconds:

cmake --build --preset dev --target mp_tests
build/dev/tests/mp_tests --no-perf

Releasing: cmake/set-version.sh <version>, merge, then tag v<version>; the release workflow builds and publishes every platform.

Layout

mp_core      definition loader, GrandOrgue import, validator, temperaments
mp_sampler   voice engine, release streaming
mp_control   key flow, couplers, switch network, pistons, stepper, crescendo, wind
mp_archive   RAR and .orgue packages, read in place
mp_split     split keyboard
mp_dsp       enclosure filters, tremulant modulation
mp_audio     audio processor, sample storage, cache, routing, output effects
mp_api       control API over HTTP, MIDI system exclusive and OSC; web console
mp_score     score panel: MusicXML engraving and playback
mp_ui        console, settings, MIDI learn

mp_core, mp_sampler, mp_control and mp_archive are plain C++20 and pugixml, so the musical path is tested against synthesised tones.

Credits

Written with four projects as references: GrandOrgue (voice engine, release crossfades), OdfEdit (the definition format), rusty-pipes (samples, loops, file formats) and HISE (streaming through per-voice buffers). Sample sets and MIDI sequences: ATTRIBUTION.md.

Licence

GPL-3.0-only, with an additional permission for combining it with JUCE under its own licence: LICENCE, COPYING. Contributing: CONTRIBUTING.md.

The Windows build includes ASIO support, used under the GPL option of the Steinberg ASIO SDK. ASIO is a trademark of Steinberg Media Technologies GmbH. Hauptwerk is a trademark of its owner. Masterpiece is an independent project.