User Guides

Cantabile Rebranding Kit

Cantabile Lite can be rebranded as a standalone plugin host using the Cantabile Rebranding Kit (CRK). This kit is supplied on a case by case basis to plugin vendors and this page describes the process for creating a rebranded version of Cantabile.

Rebranding Cantabile allows for:

  • Changing the application name (to a name approved by Topten Software)
  • Changing the company name of the folder where user settings are stored
  • Loading of plugins from a pre-determined path independent of the user's plugin path settings
  • Custom application icon
  • Custom song file extension
  • Custom welcome screen graphics (ie: first run wizard)
  • Custom website links in the About page
  • Custom website links in the Help menu
  • Custom default settings (eg: screen layout, window size etc...)
  • Display of plugin version information in Cantabile's about page
  • Inclusion of a default song used for new song files (that would typically have the vendors plugin preloaded).
  • Removes the need for Cantabile license registration
  • Feature set equivalent to Cantabile Lite

Prerequisites

In order to produce a rebranded version of Cantabile you will need the following which will be supplied by Topten Software when use of the CRK is approved.

  • A copy of the crksigntool (also requires a valid .NET Framework 4.6 installation)
  • A signing key for your company (a *.signkey.json file)

Without these files a rebranded version of Cantabile can't be produced.

The branding.json File

On startup Cantabile looks for a file named branding.json in the same directory as the Cantabile executable file. If found, the file is loaded, its embedded cryptographic hash signature is verified and if valid the settings in the file are used to run Cantabile in rebranded mode. If the file isn't found, or the cryptographic hash isn't valid Cantabile runs as the regular non-rebranded version of Cantabile.

The contents of branding.json are explained by comments in the sample file (see below).

Any external files referenced from branding.json are assumed to be relative paths to the branding.json file.

HiDPI Graphics

For any .png file referenced in branding.json, Cantabile will also look for hidpi versions with @2x, @3x, @4x etc... suffix to the base file name.

Eg: suppose you have a 64x64 icon file named Icon.png. On high DPI monitors Cantabile will also look for a hi-dpi version named Icon@2x.png which should be 128x128 pixels.

Signing the branding.json file

Before Cantabile will use branding.json it must be signed with a cyptographic hash using the crksigntool.exe command line utility. For example:

This will sign the file branding_unsigned.json and write the output to branding.json.

crksigntool branding_unsigned.json --out:branding.json

You can also sign a file inplace, but note that all comments will be removed:

crksigntool branding.json

In order to sign the file the tool must be able to locate your *.signkey.json file (as supplied by Topten Software). By default the tool looks for a file with that extension first in the current directory and then in the same directory as the crksigntool.exe file - so usually you shouldn't need to explicitly specify it. But if you do, use the --key: command line argument:

crksigntool branding.json --key:/some/other/path/myfile.signkey.json

Configuring a Default Song

The branding.json file can include a reference to a default song. This song will be loaded whenever the user chooses File|New or anytime a new empty song file is required (eg: first run).

By creating a song file with your plugin loaded, Cantabile will launch with your plugin loaded and ready to go.

Typically you'll also want the plugin's UI to be shown as the primary user interface in Cantabile's main window. To do this:

  1. Start Cantabile (either rebranded or regular Cantabile Lite)
  2. Load your plugin and configure its input and output routes (if required)
  3. Double click the plugin to bring up it's user interface
  4. From the hamburger menu at the top right, choose "Docked" - this will embed the plugin UI into Cantabile's main window
  5. From the same hamburger menu, choose "Primary View" - this tells Cantabile to switch to that plugin view tab when the song is loaded.
  6. Save the song file

Place the saved song file in the same directory as the branding.json file and reference it from the "defaultSong" setting. If you created the file using the non-rebranded version of Cantabile, you should also change its file extension to match your custom song file extension.

Testing

To test your rebranded version of Cantabile, download and extract the Cantabile .zip package from the Cantabile release notes page. Rebranding was introduced in build 4053 so you'll need that version or later.

Next, copy your signed branding.json file, along with any referenced asset files to the Cantabile installation directory. Run Cantabile by running Cantabile.exe in the extracted directory.

Remember after making changes to the branding.json file you'll need to resign the file again in order for Cantabile to load it.

Redistribution and Installation

Approval to use the Cantabile Rebranding Kit also includes permission to redistribute Cantabile either via download or on physical media.

Your installation program should:

  • Copy all the files in the above mentioned zip package to a directory under your product's installation folder.
  • Copy your signed branding.json file and any referenced asset files in the same directory.
  • Make sure Microsoft .NET 5.0.8 (or later) is installed.
  • Run cantabile.exe /regserver to register file associations.
  • Create a shortcut to Cantabile.exe that the user can use to launch the application.

You can choose to include both the x86 and x64 versions, or just one or the other. Note that there are separate .NET installations for each platform, so if you include both platforms, you'll also need to install both versions of the .NET runtime.

See Installation for details on required runtime versions.

Further information is also available in the readme file included in the .zip package. Note however the section on configuring the network isn't required for CRK installations since the network server isn't supported in Cantabile Lite.

Sample branding.json File

The following is a sample branding.json file for a fictional "Rocket" plugin by company "Acme".

{
    // Overrides the icon file on the main window and used for file extension associations
    "iconFile": "Rocket.ico",

    // Overrides the icon displayed in the about page
    // Expected size: 64x64 pts
    // HiDPI versions Rocket@2x.png etc.. will be use automatically if present
    "iconImage": "Rocket.png",

    // Path to plugin folder
    // This path will always be included before the user-paths configured in options
    // Omit either path if not distributing for that platform.
    "pluginPath64": "..\\Plugin64\\",
    "pluginPath32": "..\\Plugin32\\",

    // The base prog id for file association entries in the system registry
    "baseProgId": "Rocket3",

    // Base string for file extensions
    // eg: "Rocket" => "*.RocketSong"
    "baseExtension": "Rocket",

    // A title string to be displayed with the version number extracted from the file below
    "versionTitle": "Rocket Plugin",

    // Path to a file from which to extract version information
    "versionFile": "..\\Plugin64\\Rocket.dll",

    // A default song to load whenever File → New is selected.
    // Typically this would be configured with the plugin already loaded.
    "defaultSong": "defaultSong.RocketSong",

    // Overrides the banner image shown on the welcome/getting started pages
    // NB: two versions of this depending on whether dark or light theme is selected
    // Expected size: 420x80 pts and (@2x hidpi versions used if present)
    "welcomeGraphic_dark": "WelcomeGraphic_Dark.png",
    "welcomeGraphic_light": "WelcomeGraphic_Light.png",

    // Links to be displayed in the about page
    "aboutLinksTitle": "Acme",
    "aboutLinks": [
        {
            "title": "Website",
            "target": "https://acme.com"
        }
    ],

    // Links to be displayed in the help menu
    "helpLinksTitle": "Rocket",
    "helpLinks": [
        {
            "title": "FAQ",
            "target": "https://acme.com/faq"
        },
        {
            "title": "Support",
            "target": "https://acme.com/support"
        },
        {
            "title": "Updates",
            "target": "https://acme.com/updates"
        }
    ],

    // Default setting overrides.  These settings will be used when there's no
    // settings file found during startup.  All settings can be overriden by
    // the user after first run.  For other global settings refer to a complete
    // 'settings.json' file (see Cantabile → Tools → Open Settings Folder)
    "settings": {
        "mainWindow":
        {
            // Default to hidpi mode with plugin up-scaling enabled
            "dpiMode": "Window",

            "normalViewState":
            {
                // Adjust to suit the default size of your plugin
                "placement": "auto,auto,925,725,False:False,1",

                // Hide the side panel
                "sidePanelVisible": false
            },

            // Hide all panel tips
            "hiddenTips": 67
        }
    },
}