❮ Developers / Automation

Automation

URL SchemeforScore mini 3.4forScore 10.4

With forScore 10.4 and forScore mini 3.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
googledrive
onedrive
One
path A starting path to display upon open. (Available for Dropbox and Box accounts only.) No

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, in the case of Dropbox or Box accounts, a specific path to load. The service command requires a type value that must contain one of the following four options: dropbox, box, googledrive, and onedrive. The path value is absolute and usually case- and diacritics-sensitive (as handled by the provider).

// open the services panel to Google Drive
forscore://service?type=googledrive

// open to a specific path
forscore://service?type=dropbox&path=Directory%2FSubdirectory

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 forScore mini 3.4. 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.