Menu ☰
×
Home Features Artists Pricing Accessories Partners Resources Sign In

Developers

Actions

Not only can you use the onsong:// URL scheme to import content into OnSong, but you can also use it to perform actions in OnSong. Any action that can be performed with a foot pedal or screen tap can be performed in OnSong using the URL API.

Requirements

The Open Song URL API is only available in OnSong 2020.8 and higher. You can join our beta team to get pre-release versions of OnSong for testing. Since the onsong:// URL scheme is used on every version of OnSong, you'll want to ensure you only have the beta version installed to avoid conflict with other versions of the app.

Checking Installation

Of course to use any of these API calls, you'll need to ensure the user has OnSong installed on their device. To do this, add onsong as a registered URL scheme. Without this, your app will not be able to open OnSong scheme. However this does not apply to web-based apps.

Once registered, you can use the [UIApplication canOpenURL:] method to determine if the URL can be opened. If that returns false, then the OnSong app is not installed and you can present an appropriate user interface to have the user install OnSong. For instance, through an affiliate link. You can request to become an affiliate partner with OnSong by emailing us.

Discover Actions

At the most basic form, actions can be performed by just calling the action by its name. With over 170 actions, this can be difficult to memorize. The most important call here is list. This will return a list of dictionary objects that represent each supported action.

onsong://action/list

This will export the JSON-formatted list to the file sharing location. You can retrieve the list for review by using Finder or iTunes by connecting your device to a Mac or PC. If you rather send the list to another app or website, you can append a returnURL parameter. This will Base64 encode the JSON-formatted list and append it to the end of the URL:

onsong://action/list?returnURL=myapp%3A%2F%2Fretrieve-actions%2F%3Fdata%3D

The returned list contains parameters:

  • action is the unique value to send to perform the action.
  • title is the conversational name of the action, a combination of a noun and verb.
  • momentary determines if this is a momentary action that is performed simply by calling the action.
  • variable determines if the action expects a variable amount as input to perform the action.
  • parameters is a dictionary of parameters that can be sent to the action using the query string. The value of the dictionary field contains information about what the parameter contains including:
    • title is the conversational name of the parameter.
    • type is the type of value expected such as a string, integer, float, etc.
    • minimumValue determine the lowest value excepted for numeric types.
    • maximumValue determine the highest value excepted for numeric types.
    • format determine how numeric types should be formatted.

Perform Momentary Actions

Most actions in OnSong are momentary and can be performed with a simple tap of the screen or press of a foot pedal. To perform these actions with the URL API, just call the URL using the action value. To scroll down the current song in the song viewer, use this:

onsong://action/ForwardPedalWasPressed

Perform Variable Actions

Variable actions usually take input from a variable control that can be between 0-100%. For these, we need to pass an amount parameter in the query string. To scroll the screen to the 50% position in the song, use this:

onsong://action/PositionWasAdjusted?amount=0.5

Perform Parameterized Actions

More advanced actions require more specific input to perform. For instance, to switch to the chorus of the song, we could use this action:

onsong://action/SongSectionWasPressed?sectionID=Chorus