Build Board: One-Tap ForScore Setlist Export

Spec status: DRAFT. This scope stays open to backer input for the first 14 days of the campaign, then locks and is republished as final. If the final version is not what you thought you were funding, you can withdraw for a full refund within 7 days of the lock.

Why this exists

Getting a setlist from Back On Stage into forScore currently means downloading charts one at a time and importing them one at a time. For a twenty-song set with players on different parts, that is not a two-minute job.

The setlist is already organised inside Back On Stage. The export is where the organisation stops. Several bands have raised this same friction independently, which is what got it scoped.

1. The headline answer

This is buildable, and it is smaller than it sounds.

forScore publishes an open, documented, plain-XML setlist format that any third party is allowed to generate. It is not a reverse-engineered binary. There is no SDK to license, no partnership required, no proprietary container to reproduce.

And PDFs can be embedded directly inside the file. That was the open question, and the answer is favourable: the format has an optional data attribute that takes Base64-encoded PDF bytes. So a single .4ss file can carry the setlist order and every chart, and the musician taps it once.

Source: forScore Developers / File Types, the "Open Setlist (4SS) Format" section.

The distinction that shapes the whole build

forScore has two different things both called .4ss:

forScore's own documentation is explicit that these are not the same file and are not interchangeable. Any scoping that misses this distinction will produce a wildly wrong estimate.

2. The format, exactly

<?xml version="1.0" encoding="UTF-8" ?>
<forScore kind="setlist" version="1.0" title="My New Setlist">
    <score title="Score Title" path="filename.pdf" data="..." />
    <placeholder title="A New Placeholder" />
</forScore>

Root element must be forScore with kind="setlist" and version="1.0". title is the setlist name. The score element is the one that matters, with placeholder used for songs that have no chart.

bookmark elements have no equivalent concept in Back On Stage setlists and are out of scope.

3. What ships

A musician exports their own part, for one role, as a single self-contained file.

That sentence carries three decisions, all settled. The export is self-serve by the musician rather than generated and distributed by the bandleader. It covers one role at a time, chosen by the musician at export. And it produces one file with the XML setlist plus every chart for that role embedded as Base64 in the data attribute.

• One tap, everything lands, nothing to pre-stage in the musician's library.
• File size is the sum of that role's chart PDFs, inflated roughly 33% by Base64, plus XML overhead.
• Requires forScore 14.3 or later. See below, this is not optional.

Requirement to check before this is useful to you

Every musician who needs to open the file must be on forScore 14.3 or later.

There is no fallback path in this build. A setlist-only variant that works on forScore 12.0+ was considered and deliberately parked in order to keep this scope tight, so if your players are on an older version, this feature will not work for them.

This is the single most important thing to confirm with your band.

4. What has to happen to Back On Stage data

Encouragingly little. Back On Stage already holds everything required.

The existing "Download All PDFs" feature is the proof that the hard part is already solved. It already resolves a setlist to its ordered charts and streams the bytes. The new work is substantially "take that same resolved list, filter it to one role, and write XML around it instead of zipping it."

Edge cases that must be handled

1. Songs with no chart for the selected role. Emit a placeholder carrying the song title, so the set order stays intact and the musician sees the gap rather than losing the song entirely. Never silently dropped.
2. A musician booked for more than one role on the same gig. They pick which role to export. See section 7.1.
3. A musician booked for exactly one role. No picker. The export runs directly, with the role named in the confirmation so there is no ambiguity about what they just got.
4. Duplicate filenames across songs. forScore adjusts path to avoid collisions on its end, which would then make our XML reference the wrong file for later entries. Deduplicated before writing.
5. Non-PDF attachments (images, scans). Filtered or converted; the data attribute is PDF only.
6. XML escaping. Titles routinely contain ampersands, apostrophes, quotes and accented characters. Base64 is XML-safe; titles are not.
7. Size ceiling. See section 5.

5. The one real technical risk: file size

Base64 inflates payload by roughly a third, and the whole thing is a single XML file that both the server and the iPad have to hold.

Exporting one role at a time helps here, since a musician carries their own book rather than the whole band's. It does not solve it: on material where every player reads from the same chart, one role's export is the same size as everybody's.

Built in from day one:

• Streaming generation. The document is never assembled in memory. Header, then per song fetch, encode, write, release, so server memory stays flat regardless of setlist length.
• A configurable size ceiling, starting at 50MB.
• Delivery by download link, not email attachment. Anything over ~20MB bounces off most mail servers.
• Testing on real, older iPads, not just a simulator. This is the failure mode users actually hit.

What happens past the ceiling

The export refuses, and says exactly why. The message names the specific charts pushing the file over the limit, so the problem is actionable rather than mysterious, and points the musician at the existing ZIP download, from which charts can be imported into forScore manually.

That is a deliberate choice over the alternatives. Silently reducing PDF quality is the kind of thing a musician discovers mid-performance. Splitting into several sequential files removes the single-tap benefit that is the entire point of the feature. Refusing clearly, with a working manual path already available, is the honest answer.

6. Scope

In scope

1. Server-side .4ss generator, streaming, with charts embedded, filtered to a single role.
2. Role selection at export time for musicians booked on more than one role.
3. Filename sanitisation and deduplication.
4. Placeholder handling for songs with no chart on the selected role.
5. Export access on the musician side, reachable from both the Gig Sheet and the Setlist (Performance Mode) screen.
6. A plain-English note about the forScore 14.3 requirement, shown at the point of export.
7. Delivery: generate, temporary storage, signed download link with expiry.
8. A size guard that refuses clearly, names the offending charts, and points at the existing ZIP download.
9. Tests: empty setlist, songs without charts for the selected role, a musician with one role, a musician with several roles, duplicate filenames, unicode titles, and a deliberately oversized setlist.

Explicitly out of scope

• A setlist-only mode without embedded charts (parked, see section 3).
• Exporting several roles at once, or a combined all-parts file.
• Generating forScore's proprietary export .4ss or .4sc bundles.
• Annotations, versions, or forScore metadata round-tripping.
• Bookmarks.
• Two-way sync, or reading anything back out of forScore.
• .4sb backup and archive generation.
• Automatic PDF compression or quality reduction to fit under the size ceiling.

Dependencies and assumptions

• Chart PDFs are retrievable server-side with reasonable latency. Already true, per the existing bulk download.
• Charts are assigned to roles, and musicians are booked to roles on a gig. Both already true.
• No registered forScore partnership is required. Nothing in their developer documentation suggests otherwise, though one confirmation with forScore is worth doing before launch.
• No licence fee or revenue share is anticipated.

7. The three questions this spec had to answer

These were the genuinely undecided points. All three are now settled, and the reasoning is published here so it can be argued with rather than just accepted. The spec locks on day 14. Until then these decisions are open to challenge.

7.1 Songs where each player reads a different part

Decision: the musician chooses one role at export time, and only that role's charts are included.

Back On Stage supports separate charts per instrument, while forScore's setlist model expects one score per entry. Three approaches were possible: route parts automatically by role, emit one entry per part so everyone receives everything, or let the musician choose.

Choosing is the right answer because it is the only one that is unambiguous. Automatic routing quietly makes a decision on someone's behalf, and gets it wrong for anyone doubling. Sending every part to everyone recreates the exact pile of irrelevant PDFs this feature exists to eliminate.

A musician booked on more than one role picks which one they are exporting. A musician booked on one role gets no picker at all.

7.2 Setlists that exceed the size ceiling

Decision: refuse, and name the charts causing it.

The export stops, explains why, identifies the specific charts pushing it over, and points at the existing ZIP download as the manual path into forScore.

Rejected alternatives, and why: automatic quality reduction hides a change to the thing a musician is reading from, which is unacceptable in performance. Splitting into several files defeats the single-tap purpose of the feature. Refusing clearly is worse in the moment and better in every other respect, and there is already a working fallback in the product.

7.3 Who receives the file

Decision: the musician viewing the setlist, self-serve, from their own side of Back On Stage.

In practice this means every musician on the gig, each pulling their own part when they want it. Export is reachable from both the Gig Sheet and the Setlist (Performance Mode) screen, which are the two places a musician is already looking before a gig.

This removes the bandleader from the loop entirely. Nobody has to remember to send anything, nobody is waiting on anyone, and a late substitute added the day before can pull their own book the moment they are booked.

8. Phasing

Format details verified against forScore's published developer documentation, 2026-08-13.

Sources: forScore Developers / File Types · forScore Compatible File Types