Phones and tablets

This page describes Masterpiece on Android, iPhone and iPad: how the window is laid out for a touch screen, how a sample set reaches the device, how audio and MIDI work there, what the device’s memory allows, and where the app differs from the desktop program. For the files and the installation procedure, see Installing Masterpiece.

The mobile app is the standalone program, built from the same source as the desktop one. It plays the same Hauptwerk-format sample sets and GrandOrgue organs through the same engine. The plugin formats, the command line and the test tools have no mobile build.

The window

Screen and orientation

The console fills the screen with no title bar and no resize border. The window has a fixed size and keeps no remembered place.

The iPhone and iPad builds are landscape only (left and right). The Android manifest sets no orientation.

The console picks its layout from the shape of the room it has. In a window taller than wide it shows the organ’s portrait layout, when the set ships one; in a wider window it shows the main layout. A layout chosen by hand holds until the shape changes. The layout box in the top bar appears only when the organ has more than one layout, and names a portrait layout as such.

Touch sizes

Controls are enlarged for a finger. The code states the target as about 48 logical pixels, the size both platforms recommend.

The top bar gives the menus and the volume fader a row of their own when the width left after the buttons on the right is below 350 pixels.

Panels and dialogs

Every panel and dialog opens inside the main window, in a layer over the console. One window is on screen at a time, filling the screen, with a 48-pixel title bar and a close button within reach. Dialogs have a fixed size, and a dialog keeps no remembered size. The windows that float over the console on a desktop (Recorder, Combinations, Split keyboard, and a page opened in its own window) open the same way, as full-screen panels.

The pop-out button of a panel is hidden, and panels cannot be detached into windows of their own.

Menus and alerts keep windows of their own. On Android, the back button closes the front panel as Escape does on a desktop. The load progress dialog stays open; back does nothing while it shows.

Playing on the screen

The drawn console takes touches: drawstops, pistons, shoes and keys. View > Keyboard shows the on-screen keyboard, with a selector for the manual it plays when the organ has several. See Playing and A tour of the window.

First start

The first-run wizard appears on a phone or tablet as on a desktop, as a panel. See Installing Masterpiece.

Getting sample sets onto the device

What opens

A phone or tablet opens an organ from one package: a RAR archive (.rar, RAR 4 or 5, including solid and multi-part sets) or a GrandOrgue .orgue package. The file chooser is titled Choose an organ package and filters *.rar and *.orgue. A loose installation of thousands of files is slow to bring onto the device and slow to read through the system’s document layer, so loose definitions (.Organ_Hauptwerk_xml, .organ) stay out of the chooser. Masterpiece reads the samples from the package where it is. See Opening an organ.

The favourites window (File > Open…) works as on a desktop. Its button Open an organ file… opens the chooser. The last organ and the favourites reopen at the next start when their access is still granted.

Android

Android hands the app a document, which has no path. Masterpiece handles it in one of two ways.

During a copy the file carries the suffix .part and is renamed at the end, so a cancelled or failed copy never looks finished.

For a package read in place, Masterpiece asks the system for read access that survives restarts and keeps the list of documents in Linked/documents.txt. At the next start it makes the links again, so the last organ and the favourites reopen. A document that has gone, or whose access was withdrawn, is dropped from the list.

The picker cannot always filter by extension, so the choice is checked after it. Alerts titled Organ not copied report a failed import:

The app declares READ_EXTERNAL_STORAGE up to Android 12L (API level 32) for reading shared storage by path.

Android picks one document at a time and reads or copies that document alone. The question for the folder of a multi-volume set exists on iPhone and iPad only.

iPhone and iPad

The Files app lends a picked document through a security-scoped URL. Masterpiece starts that access and holds it until the program ends, and the package is read where it is. Nothing is copied, so a package of many gigabytes takes no extra space. The loans are remembered in held-documents.txt in the app’s data folder, and lent again at the next start with no new pick. A document that has gone, or whose loan was withdrawn, is dropped.

The build enables file sharing and the document browser, so a package can also be copied into the app’s own Documents folder through the Files app.

The Log tab of General settings lists the loans under Documents lent by the Files app, with a mark for each one that cannot be read now.

Audio and MIDI

Audio

Audio goes through the device’s audio system. On Android the low-latency interface needs Android 8.0 (API level 26), the minimum of the app. The iPhone and iPad app declares background audio: the organ keeps sounding when the screen locks or another app comes to the front.

The first start picks the default output, a rate of at least 44.1 kHz and a buffer of about 10 ms; see Installing Masterpiece. Settings > Audio and MIDI… opens the Audio tab of the general settings. See Audio, room and mixer.

The engine renders with the NEON vector unit on 64-bit ARM, so the Faster audio engine box applies on a phone as on a Raspberry Pi. The Android emulator (x86_64) uses AVX2 or SSE2.

MIDI

At the start the app opens every MIDI input the system reports, except those switched off earlier, and tries again every 3 seconds for an input that failed to open. The wizard’s Your keyboards step lists them.

The program remembers an input between sessions by a lasting identifier. On iOS it is the CoreMIDI identifier. Android numbers its devices afresh at each start, so there Masterpiece knows an input by its name, and two keyboards of the same model look alike.

A virtual MIDI input of Masterpiece’s own (--virtual-midi) exists on macOS and Linux only. The JACK audio and MIDI connections exist on Linux only.

MIDI learn is described in MIDI and consoles.

Memory

Phones and tablets have no memory setting of their own. The same limit and the same loading choices apply as on a desktop, with values that make a small device workable.

The limit

Memory limit for samples on Settings > Organ settings… > Loading is the most memory the samples and the voice pool of one organ may take. Its default is Default: 80% of memory, computed from the device’s total memory with a floor of 512 MB. The other choices are 50%, 60%, 70% and 90% of memory. It takes effect at the next load.

A load that would pass the limit stops with an alert titled Not enough memory for this organ and shows the console without sound, so that Organ settings can be opened. A load that reaches the limit part-way plays with some stops or notes silent and says so in an alert titled Only part of this organ fits. Stops and perspectives shows About <size> for this choice (the limit is <size>) for the stops kept, in red when the choice passes the limit.

The limit is measured against the device’s total memory. A phone or tablet ends a backgrounded app whenever it needs the memory, and the program treats a backgrounded session as ended cleanly, so the crash guard reads the end as a normal quit. With Reopen the last organ when Masterpiece starts on, the organ reopens at the next start.

What fits

The code gives no per-device figure. The measured sizes of a large organ are in Memory, loading and streaming; Friesach, a 44-stop set of 17 GB on disk, takes these amounts of sample memory:

On a phone or tablet, start from Smallest - 16-bit mono, stream releases, and leave out the stops and perspectives that the repertoire leaves unused (Stops and perspectives). See Small, medium and large organs.

The voice pool counts against the limit. With streamed release tails each voice holds a ring buffer of 2 seconds, 768 KB at 48 kHz, and the default pool is 1,536 voices, about 1.1 GB. With streaming off, the default pool is 725 voices per processor thread, at least 1,536. Polyphony limit on the same tab lists the memory of each pool size in its choices (256, 512, 768, 1,024 voices and more); a smaller pool leaves more of the limit to the samples, and thins a full registration. The code sets no separate pool default for phones.

The sample cache

The sample cache stores the decoded samples so that the next load of the same organ reads one file. Its default folder is cache in the app’s data folder; Cache folder on the Loading tab shows the path, Choose… picks another folder through the system chooser, and Default returns to the standard one. The cache is as large as the samples held in memory. Sample cache offers One cache, replaced as organs change (the default), One cache per organ (uses more disk) and Off; Off frees the storage and makes every load decode the package again. Save the sample cache chooses Before the organ plays or In silence, while it plays; the second writes the cache at the lowest background priority.

On Android, iPhone and iPad the Masterpiece folder lies in the app’s own application-data folder. Run the checks on the Log tab lists the cache folder and the size of the cache files.

Differences from the desktop program

Reporting a problem

Settings > General settings… > Log shows where the log is kept. Run the checks reports the folders Masterpiece writes to, the audio, the organ and its files, and on iOS the documents lent by the Files app. Copy the report puts the checks and the last 200 lines of the log on the clipboard. Send the report and the log opens the share sheet with masterpiece-report.txt, masterpiece.log and masterpiece.previous.log. See Troubleshooting and caveats.