User Guides v3.0

Stream Deck Integration

Cantabile Performer Only

The Cantabile Stream Deck plugin provides tight integration between Cantabile and one or more Stream Deck controllers.

Note: this is a plugin that's loaded into the Stream Deck App, not Cantabile.

Stream Deck XL
Stream Deck

Features

Included actions:

  • Audio Engine Power On/Off
  • Live Mode
  • All Sounds Off button (panic)
  • Scrollable list/page of songs (names shown on buttons)
  • Scrollable list/page of states (names shown on buttons)
  • Countdown timer with presets and remaining time shown on button
  • Master Transport controls (with icons that light up to show current state)
  • Record and Auto Record controls
  • Tap Tempo button (with tempo flasher)
  • Metronome controls (tempo, time signature, sound on/off)
  • Media Player by Index controls (play, pause, stop, play/pause, play stop, fast-forward/rewind, next/previous marker)
  • Gain controls (Master in/out, audio ports, metronome)
  • Send MIDI from a stream deck button
  • Tightly integrated with the onscreen keyboard controllers (reflect controller state on the stream deck for notification/cue lights etc...)
  • Show Notes controls (page up/down, line up/down, home/end etc...)
  • Transpose controls (up/down semitone, up/down octave, up/down octave snapped)
  • String Expressions (display Cantabile $(variables) on a button)
  • Invoke any UI command
  • Invoke any binding target

Compatibility

The plugin has been tested with the Stream Deck standard (15-button) and the Stream Deck XL (32-button). It mostly works in the Stream Deck mobile app but I don't recommend it - the choose state and choose song actions don't work (not sure why yet) and it's a bit laggy (especially for the tempo flasher). It ok for getting a feel for what the plugin does but that's about it.

Installing the Plugin

As yet, the Cantabile Stream Deck plugin isn't available from the Elgato Stream Deck store and has to be manually installed.

To install the Cantabile Stream Deck plugin.

  1. Make sure you have Cantabile build 4046 or later installed (download). Although the plugin will work in a reduced capacity on older versions (even v3), it's highly recommended to use the newer build to ensure all features work correctly and reliably
  2. Enable Cantabile's network server - see here for more on this
  3. Download the Cantabile Stream Deck plugin from here
  4. Double click the downloaded file on the same machine that has the Stream Deck app installed and it should install itself

Upgrading the Plugin

In order to upgrade an existing installation of the Cantabile Stream Deck plugin you must first manually remove the prior installation as follows:

  1. Quit the StreamDeck app
  2. In Windows File Explorer, in the address bar, go to the folder %APPDATA%\Elgato\StreamDeck\Plugins
  3. Delete the folder com.toptensoftware.cantabile.sdPlugin
  4. Repeat the instructions for Installing the Plugin above
  5. When prompted to install profiles choose No (otherwise you’ll get duplicates).

Known Issues

  • The Choose State and Choose Set List actions don't work correctly on the Stream Deck mobile app
  • Tempo flashing in the mobile app is too laggy to be useful

Included Profiles

The plugin includes several Stream Deck profiles for both the standard 15 button Stream Deck and the 32 button Stream Deck XL:

  • Cantabile - a profile with common actions to serve as a starting point for configuring your own setup.
  • Cantabile Choose Song - a read-only profile used by the Set List | Choose Song action
  • Cantabile Choose State - a read-only profile used by the States | Choose State action

Profiles for the Stream Deck mobile app and foot controller are not included at this stage.

Configuring the Connection

By default the plugin connects to a Cantabile server running on the same machine as the plugin (aka: 'localhost'). If Cantabile is running on a different machine:

  1. In the Stream Deck app, click on the "Power Button" action
  2. In the properties for this action there's a button "Connection Settings"
  3. Click the button to enter a new host address
  4. Click Save to save the setting and connect to the new machine
Connection Settings

Organization of Actions

The Cantabile Stream Deck items are grouped according to function with an action setting to control what the button actually does.

For example, the Transport item:

Transport Action

Has sub-actions for Play, Pause and Stop:

Transport Sub-Actions

Button Appearance

The Stream Deck application allows you to change the image and title on a button. Please be aware that this will overwrite any images and titles that the plugin is trying to show. This means that any button that provides feedback from Cantabile may not work correctly.

For example:

  • If you set an image on the tempo button, it will not flash
  • If you set a title on the tempo button, it won't show the current time signature and tempo
  • If you set an image on the play or pause buttons, they will still work but won't light up to show the playing or paused state
  • If you set an image on a load song or state button it won't show the song or state name
  • etc...

In short, it's not recommended to set custom images or titles on buttons. For this reason, all of the plugin actions have properties to set the foregroud and background colors.

Page Controls

The Set List and State actions both provide the ability to build a scrollable list of items (either songs or states) using the "Load By Index", "Next Page" and "Previous Page" sub-actions.

Setup this feature as follows:

  1. Add a button with the "Load By Index" sub-action and set its index property to 0. This will represent the first item on the current page.
  2. Repeat step 1, with increasing values for the index (0, 1, 2, 3 etc...) for each button on the page.
  3. Add a button with a sub-action "Next Page" and set the page size property to the number of "Load By Index" buttons you created.
    ie: if you created 6 load by index buttons (with indicies 0, 1, 2, 3, 4 and 5) the page size should be set to 6.
  4. Add a button with the sub-action "Previous Page".

Once configured correctly, the Load By Index and Next/Previous page buttons work together to create a scrollable list of items.

Paging Controls

Note that most of the properties of the Load By Index sub-action are linked so changing the setting on one button will also affect all the other similar buttons on the same screen. This is by design and simplifies configuing these screens.

The MIDI Action

The MIDI button action can be used to send MIDI to any of the output MIDI ports configured in Cantabile.

It can also be configured to inject MIDI into Cantabile's on-screen keyboard device such that it appears the MIDI is originating from the on-screen keyboard device (and any ports attached to it). Because this device is owned and managed by Cantabile it provides for tighter integration with the Stream Deck plugin:

When "Device: Onscreen Keyboard" is selected as the MIDI target:

  • Toggle Buttons mapped to controllers (including CC, FineCC, RPN, NRPN etc...) will always reflect the active state of the controller
  • Buttons configured to send program changes (normal or banked) will light up when that program is selected for the on-screen keyboard

In both cases, it doesn't matter if the underlying setting is changed from the StreamDeck, from Cantabile's controller bar, from bindings or from other network clients... the Stream Deck button will always reflect the current setting.

Tips

Most of the other button actions are self explanatory, but here's a couple of tips:

  • Long pressing (about 1 second) the Record button toggles auto record on/off.
  • The tempo button works as a Tap Tempo button (tap it at the rate of the desired tempo).
  • When the countdown timer is running it can be reset by a long press.
  • When the countdown timer is stopped, a long press will cycle through the time out periods configured for the button.
  • The power button has a Connection Settings popup that can be used to configure the connection to Cantabile.

Debugging

In order to assist with diagnosing issues you may be asked to check the debug console for the plugin. This is a little cumbersome to setup, but can provide invaluable diagnostic information.

First, you need to enable debugging of the plugin:

  1. Start the Windows registry editor by clicking the Start button and typing "regedit"
  2. Navigate to the key: HKEY_CURRENT_USER\Software\Elgato Systems GmbH\StreamDeck
  3. Right click in the right-hand panel and choose New -> DWORD (32-bit) Value
  4. Name the key html_remote_debugging_enabled
  5. Set the key value to 1.
  6. Restart the Stream Deck application (right click tray icon and choose "Quit Stream Deck")
Stream Deck Debug Key

Once debugging has been enabled:

  1. Reproduce the problem
  2. Bring up any Chromium based browser (Chrome, Edge, Opera)
  3. Navigate to http://localhost:23654
  4. In the list of inspectable pages, click on the item labeled "Cantabile Stream Deck Plugin"
  5. Click on the Console tab at the top to view the log
  6. Right click on the log and choose "Save As" to save the log file.

Once finished you can set the registry key back to 0.