Protocol Launcher

English

简体中文

English

简体中文

Appearance

OnSong ​

OnSong is a digital songbook and chord chart app for musicians. Protocol Launcher allows you to generate OnSong URL scheme links.

Usage ​

There are two ways to use this library:

  • On-Demand import from subpaths enables tree-shaking and keeps bundles small.
  • Full Import from the root package is convenient but includes all app modules.

Pick On-Demand for production builds; Full Import is fine for quick scripts or demos.

Select Installation Method

On-Demand
Recommended. Optimized for production.
Full Import
Convenient. Good for quick scripts.

Notes ​

The helpers below mirror OnSong's official developer documentation for importing content, opening songs, exporting song data, and performing actions. Only the documented onsong://, onsong://ImportData/..., onsong://open/songs, onsong://export/songs, onsong://action/list, and onsong://action/<value> URL shapes are exposed.

OnSong's Open Song and Actions URL APIs require OnSong 2020.8 or higher. importUrl() accepts an http:// file URL because the official import documentation says to replace the http:// component with onsong://; for SSL-hosted files, the official docs say to redirect to the https:// location. importData() expects Base64-encoded file data, and the filename extension is important because OnSong uses it to determine the file type.

The published Open Song page says export output can include additional properties, but it does not currently show a query parameter name or full URL syntax for that option. This module therefore does not expose a properties payload.

Use synthetic song titles, identifiers, set names, and short Base64 samples in examples and tests. Do not publish copyrighted lyrics, full sheet-music content, or real user library identifiers.

Open ​

On-Demand
ts
import { open } from 'protocol-launcher/onsong'

const url = open()

Import URL ​

On-Demand
ts
import { importUrl } from 'protocol-launcher/onsong'

const url = importUrl({
  url: 'http://my.domain.com/files/go/here/Song%20Title.txt',
})

Import Data ​

On-Demand
ts
import { importData } from 'protocol-launcher/onsong'

const url = importData({
  filename: 'My Song Title.pdf',
  base64Data: 'BASE_64_ENCODED_DATA_HERE',
})

Open Song ​

On-Demand
ts
import { openSong } from 'protocol-launcher/onsong'

const url = openSong({
  song: 'be-still',
})

Open Songs ​

On-Demand
ts
import { openSongs } from 'protocol-launcher/onsong'

const url = openSongs({
  song: ['be-still', 'beautiful-life', 'changes'],
  index: 1,
})

Export Songs ​

On-Demand
ts
import { exportSongs } from 'protocol-launcher/onsong'

const url = exportSongs({
  collection: 'current',
  returnURL: 'http://mywebsite.com/receive?data=',
})

List Actions ​

On-Demand
ts
import { listActions } from 'protocol-launcher/onsong'

const url = listActions({
  returnURL: 'myapp://retrieve-actions/?data=',
})

Perform Action ​

On-Demand
ts
import { performAction } from 'protocol-launcher/onsong'

const url = performAction({
  action: 'SongSectionWasPressed',
  parameters: {
    sectionID: 'Chorus',
  },
})

Generated URLs ​

ts
open()
// => 'onsong://'

importUrl({
  url: 'http://my.domain.com/files/go/here/Song%20Title.txt',
})
// => 'onsong://my.domain.com/files/go/here/Song%20Title.txt'

importData({
  filename: 'My Song Title.pdf',
  base64Data: 'BASE_64_ENCODED_DATA_HERE',
})
// => 'onsong://ImportData/My%20Song%20Title.pdf?BASE_64_ENCODED_DATA_HERE'

openSong({ song: 'be-still' })
// => 'onsong://open/songs?song=be-still'

openSongs({
  song: ['be-still', 'beautiful-life', 'changes'],
  index: 1,
})
// => 'onsong://open/songs/?song=be-still&song=beautiful-life&song=changes&index=1'

exportSongs({
  collection: 'current',
  returnURL: 'http://mywebsite.com/receive?data=',
})
// => 'onsong://export/songs?collection=current&returnURL=http%3A%2F%2Fmywebsite%2Ecom%2Freceive%3Fdata%3D'

listActions()
// => 'onsong://action/list'

performAction({ action: 'PositionWasAdjusted', amount: 0.5 })
// => 'onsong://action/PositionWasAdjusted?amount=0.5'

References ​