Packaging Expansions

A Rhapsody expansion is distributed to end users as an .hr file, containing the expansion’s scripts, UI, configuration, user presets, and samples. Rhapsody installs it into the expansion’s own folder inside Rhapsody’s app data Expansions folder.

Sample audio data can be large, so users choose where to store it, often on a different drive. Rhapsody tracks the chosen location with a small Link file inside the expansion’s Samples folder, redirecting to wherever the user placed the actual sample data.

User presets ship embedded with the expansion. At least one preset is required, following the standard Bank > Category > Preset folder structure (for example Factory/Category/Default).

How you export all of this matters. Rhapsody reads specific project metadata and files when it loads an expansion, and how you package the sample data affects how users receive future updates.

Project Settings

Before exporting, also set these Project Settings in the project’s preferences:

Expansion Type

Set to Disabled.

Encryption Key

Set to 1234. The exporter requires this exact key.

Default User Preset

Leave empty. Rhapsody handles selecting the default preset itself; see Setting The Default Preset below.

Expansion Settings

Before exporting, complete the Expansion Settings section of the project’s preferences in the HISE.

UUID

A UUID (universally unique identifier) is a randomly generated ID, effectively guaranteed to be unique. Rhapsody currently uses it to identify an expansion when checking for updates, independent of its name.

It will likely also be used to prevent clashes when two expansions from different developers happen to share a name.

There’s a one-click button in the preferences to generate one, and it shouldn’t change once you’ve released the expansion.

Required Player Version

Sets the minimum Rhapsody Player version needed to load the expansion. Leave it blank unless the expansion relies on functionality from a specific Rhapsody Player version, since setting it will stop the expansion loading in older players.

Icon

Add a 500x500px Icon.png to the project’s Images folder. It’s embedded in the exported expansion, and is the icon Rhapsody will display.

Compressing Samples

Compress the project’s samples to monoliths via Tools > Convert all samples to Monolith + Samplemap. Normalisation is locked to Full Dynamics.

Setting The Default Preset

Load the expansion’s default user preset (for example Factory/Category/Default) and resave the project xml, so the correct preset is embedded when you export.

Factory presets are read-only in Rhapsody.

Exporting The Expansion

Export the expansion’s scripts, UI, configuration, and user presets via File > Export > Export Project as Full Expansion, choosing the HXI export mode. This produces an info.hxi file in the project’s root folder.

Creating the Package File

Package the compressed sample monoliths via File > Export > Package sample monolith files. The info.hxi exported earlier is picked up automatically and embedded as the archive’s header.

• Output format: HR Archive (custom FLAC).
• Split archive size: 2 GB. Once the archive exceeds this size, the exporter continues it across further files with an incrementing extension (..._Samples.hr1, ..._Samples.hr2, ..._Samples.hr3, and so on) instead of one large file.
• Archive layout:
  • Combined Archive: the info.hxi header and the sample data are packed into the same archive.
  • Split Data From Samples: the info.hxi header is written to its own file, kept separate from the sample data that follows. Use this if you want the option to ship a data-only update later without re-exporting the samples.
  • Data Only Update (reuse existing samples): exports just the info.hxi header, with no sample data at all. Use this for an update that only changes scripts or configuration, so customers who already have the sample archives installed don’t need to re-download them.

Either Combined Archive or Split Data From Samples works for the initial install. For a small expansion, a Combined Archive is simplest. For a larger one, Split Data From Samples is the better choice: it keeps the door open for a later Data Only Update, so customers won’t have to re-download unchanged sample data.

Update Checking

Rhapsody checks installed expansions for updates automatically (roughly monthly), and on demand via Check for Updates in the settings menu.

For an expansion to be checked, the project’s Company URL (User Settings) must be set. Rhapsody takes the base URL and requests rhapsody.json from it, so you need to host that file at the root of the same website. A URL that repeatedly fails to serve it gets skipped in future checks.

See librewave.com/rhapsody.json for a real example.

rhapsody.json is a JSON array, with one entry per expansion you publish updates for:

[
  {
    "uuid": "1234-5678-...",
    "version": "1.2.0",
    "description": "What changed in this version."
  }
]

Rhapsody matches each entry to an installed expansion by uuid. A match with a higher version than the installed one flags that expansion as having an update available.

description is optional: a changelog for the most recent update. Create new lines using \n. It isn’t used by Rhapsody yet, but may be in a future version.