Developers / PDF Metadata
PDF Metadata
Values
The PDF specification includes several standard types of document metadata, such as Title, Author, Subject, and Keywords. With forScore, users may choose to adopt this information to categorize their content. The Title field is used as-is, while text found within the Author, Subject, and Keywords fields is comma-separated into multiple values and used as composers, genres, and tags (respectively). We also use several specially-formatted values in the Keywords field to represent additional types of information.
PDF Specification
| PDF Value | forScore Value | Format |
|---|---|---|
| Title | Title | Single value |
| Author | Composers | One or more comma-separated values |
| Subject | Genres | One or more comma-separated values |
| Keywords | Tags | One or more comma-separated values (excluding keywords listed in the chart below) |
Specialty KeywordsforScore 10.4
| Keyword | forScore Value | Format |
|---|---|---|
| rating:N | Rating | Whole number between 0 and 5 |
| difficulty:N | Difficulty | Whole number between 0 and 3 |
| duration:N | Duration | Non-negative whole number (in seconds) |
| keysf:N | Key | A whole number between -7 and 7 |
| keymi:N | 0 (major) or 1 (minor) |
Rating & Difficulty
Rating and Difficulty values are stored in the rating:N and difficulty:N keywords where N is a rating value between 0 and 5 or a difficulty value between 0 and 3. Previous versions of forScore used forScore-difficulty:N and forScore-rating:N but these specific keys have been retired in favor of the more generic replacements with forScore 10.4.
Duration
Duration is represented in seconds as seconds:N where N is a whole, non-negative number (a value of 60 or greater is translated into minutes and seconds; for example 72 seconds is displayed in forScore as 1 minute and 12 seconds).
Key
Using the MIDI standard, key values are stored in two parts. The first value is called keysf:N where N is a value between -7 and 7, and it corresponds to the number of sharps or flats in a key signature. The second value is keymi:N where N is either a 0 or 1, indicating that the key is major or minor.
| keysf | keymi | Key | keysf | keymi | Key |
|---|---|---|---|---|---|
| -7 | 0 | C♭ major | -7 | 1 | A♭ minor |
| -6 | 0 | G♭ major | -6 | 1 | E♭ minor |
| -5 | 0 | D♭ major | -5 | 1 | B♭ minor |
| -4 | 0 | A♭ major | -4 | 1 | F minor |
| -3 | 0 | E♭ major | -3 | 1 | C minor |
| -2 | 0 | B♭ major | -2 | 1 | G minor |
| -1 | 0 | F major | -1 | 1 | D minor |
| 0 | 0 | C major | 0 | 1 | A minor |
| 1 | 0 | G major | 1 | 1 | E minor |
| 2 | 0 | D major | 2 | 1 | B minor |
| 3 | 0 | A major | 3 | 1 | F♯ minor |
| 4 | 0 | E major | 4 | 1 | C♯ minor |
| 5 | 0 | B major | 5 | 1 | G♯ minor |
| 6 | 0 | F♯ major | 6 | 1 | D♯ minor |
| 7 | 0 | C♯ major | 7 | 1 | A♯ minor |
Table of Contents
For files that include multiple pieces, a Table of Contents is the perfect way to communicate this information to the user. With forScore, users can view the table of contents and tap a title to navigate directly to the corresponding page number. They can also import that table of contents as a set of Bookmarks. A bookmark is different from a table of contents item because it references a range of pages instead of just a starting page. This allows users to work with smaller pieces within their document as if they were a standalone PDFs. (Because the table of contents does not include an “ending” page number, we infer each piece’s end page as one page before the first page of the following item.)
The PDF specification also defines several additional types of actions that can be associated with Table of Contents entries, and forScore supports two of these: URLs and remote file (goToR) actions. URLs may be web links (http:// or https://), file links (file://), or they may use other common schemes such as mailto: or even app-specific schemes such as forScore’s own custom forscore:// scheme. These entries can be used as-is but are ignored when importing Table of Contents information as Bookmarks.