Developers / Automation
Automation
URL SchemeforScore 10.4
With forScore 10.4 we introduced a custom URL scheme that allows users to click links that navigate to a particular piece or activate certain functions. These URLs use the format forscore://command?key=value&key2=value2 where “command” is a specific type of instruction followed by one or more pairs of keys and values.
Values may be concrete (such as page numbers) or they may reference a user’s content instead. For content references, forScore looks for an exact match and uses it if found, otherwise it attempts a case-insensitive search and finally a case- and diacritics-insensitive search until it finds an acceptable result. If no match is found, the action will fail silently.
| Command | Key | Value | Required |
|---|---|---|---|
| open | path | The filename of a score in the user’s library (preferred over score if both are supplied) | Any (one or more) |
| score | The title of a score in the user’s library | ||
| setlist | The name of a setlist in the user’s library | ||
| page | The page number to open (in the current score if no path or score is supplied) | ||
| bookmark | The title of a bookmark within the referenced score, if found (ignored if no path or score values are supplied) | No | |
| service | type | dropbox box musicnotes noteflight virtualsheetmusic carlfischer presser brilee |
One |
| path | A starting path to display upon open (if supported) | No | |
| action | type | prevpage nextpage previtem nextitem back nowplaying |
One |
Open
The open command consists of at least one of the following: a path (filename), score (title), setlist (name), or page (number). You can supply as many of these values as is applicable; if both a path and score title are supplied, path takes precedence.
A setlist name may be supplied on its own (forScore will open the first item within that setlist), or it can be paired with additional values to direct the user to a specific piece and page within that setlist:
// open a score
forscore://open?path=My%20Score.pdf
forscore://open?score=My%20Score
// open a setlist to the first item
forscore://open?setlist=My%20Setlist
// open a setlist to a specific item
forscore://open?setlist=My%20Setlist&score=My%20Score
Optional values bookmark and page may be supplied if desired, directing users to a specific bookmark within a score (if found), and/or taking them to a specific page. If no path or score title are supplied, the bookmark value is ignored. A supplied page value will be respected if possible, or forScore will navigate to the first page if the number is out of bounds. If both bookmark and page number values are supplied, the page number is interpreted relatively (page “2” navigates to the second page of the bookmark, not the second page of the PDF file). Note that page numbers are absolute and do not respect “page offset” adjustments made through the Metadata panel.
// open a bookmark
forscore://open?path=My%20Score.pdf&bookmark=My%20Bookmark
forscore://open?score=My%20Score&bookmark=My%20Bookmark
// open an item to a specific page
forscore://open?score=My%20Score&page=3
forscore://open?path=My%20Score.pdf&bookmark=My%20Bookmark&page=3
// open a setlist to a specific bookmark and page number
forscore://open?setlist=My%20Setlist&score=My%20Score&bookmark=My%20Bookmark&page=3
Each time a user selects an item from the Score or Bookmark menus or from within a setlist, the items in that list are automatically queued up so that flipping between scores (if enabled) moves between those items in the same sort order. Changing a menu’s sort order after having selected an item does not alter this queue.
When directed to a score or bookmark and no setlist is specified, forScore attempts to preserve this queue whenever possible. While playing from a setlist, forScore navigates to the first instance of the score or bookmark within that setlist, if found, or reverts to the “all scores” list if necessary.
Service
Links can also be used to open forScore’s services panel to a specific account type (if set up) and a specific path to load, if desired. The service command requires a type value that must contain one of the following two options: dropbox or box. The path value is absolute and usually case- and diacritics-sensitive (as handled by the provider).
With forScore 11.2 or later, you can also open a content provider by specifying musicnotes, noteflight, or virtualsheetmusic as the type. Paths are not supported when opening content providers.
// open the services panel to Dropbox
forscore://service?type=dropbox
// open to a specific path
forscore://service?type=dropbox&path=Directory%2FSubdirectory
ActionforScore 11.0
The action command, added in forScore 11, is used to communicate relative navigation changes, such as moving to the previous or next page or item in the playback queue. It can also be used to present the current playback queue or to go back, if appropriate. (forScore allows a user to “go back” to the page they were viewing immediately prior to a significant change, currently defined as navigation to a different piece or to a non-consecutive page number in the same piece. The exact implementation of this command is not guaranteed and subject to change with future updates.)
// go to the next item in a setlist
forscore://action?type=nextitem
Link Generator
Use this link generator to create your own links for use with forScore.
Command:
Values:
Filename |
Title |
Page |
Setlist |
Bookmark |
Link:
A filename or title is required.Use this link with forScore 10.4 or later. Links can be embedded into PDF files as annotations or table of contents entries, or they can be used with forScore's Buttons. They're also supported system-wide, so you can view and tap a link in Mail, Safari, and many other apps to open forScore and navigate to the specified target.