Build Board: One-Tap ForScore Setlist Export

Spec status: LOCKED, 11 September 2026. This scope was due to lock on 9 September, day 14 of the campaign. It was held open two extra days because a backer raised a real problem with section 7.1 and the fix changed the design. It is now final.

If you have already backed this, you can withdraw for a full refund up to 18 September 2026, seven days from the lock, if the final scope is not what you thought you were funding.

What changed on 9 September: the export no longer asks you to pick one role up front and filter everything to it. Parts are now worked out song by song, charts assigned to no role are treated as available to everyone, and you are only asked to choose on songs that genuinely offer you more than one part. See section 7.1.

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 book for a gig, 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. Parts are worked out song by song, with the musician asked to choose only where a song genuinely offers them more than one chart. And it produces one file with the XML setlist plus every selected chart 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 the selected 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, choose one chart per song, and write XML around it instead of zipping it."

Edge cases that must be handled

1. Songs where you have no candidate chart at all. Emit a placeholder carrying the song title, so the set order stays intact and you see the gap rather than losing the song entirely. Never silently dropped.
2. Songs with exactly one candidate chart. Used directly, no prompt. This is the overwhelming majority of songs for most musicians, and the export must not interrupt you for it.
3. Songs with more than one candidate chart. You choose, per song. See section 7.1.
4. A musician booked on no roles at all. Their candidate set is the unassigned charts alone. The export still runs rather than refusing.
5. Cancelling partway through the prompts. Nothing is generated and nothing is left behind. No partial file, no half-answered state to come back to.
6. 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.
7. Non-PDF attachments (images, scans). Filtered or converted; the data attribute is PDF only.
8. XML escaping. Titles routinely contain ampersands, apostrophes, quotes and accented characters. Base64 is XML-safe; titles are not.
9. Size ceiling. See section 5. Note that the total size is only known once selection is complete, so the guard runs after the prompts rather than before them.

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 chart per song 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 musician'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 the selected charts embedded.
2. Per-song candidate resolution: charts assigned to the musician's booked roles, plus charts assigned to no role.
3. Per-song part selection for ambiguous songs, including the remembered-choice shortcut described in section 7.1.
4. Filename sanitisation and deduplication.
5. Placeholder handling for songs where the musician has no candidate chart.
6. Export access on the musician side, reachable from both the Gig Sheet and the Setlist (Performance Mode) screen.
7. A plain-English note about the forScore 14.3 requirement, shown at the point of export.
8. Delivery: generate, temporary storage, signed download link with expiry.
9. A size guard that refuses clearly, names the offending charts, and points at the existing ZIP download.
10. Tests: empty setlist, songs with no candidate chart, songs with exactly one, songs with several, a musician booked on no roles, cancelling mid-selection, the remembered-choice path, 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 parts for the same song 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.
• Saving your part preferences permanently across different gigs. The remembered choice in section 7.1 lasts for one export run only.

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.
• Charts may also be assigned to no role, and where that is the case they are treated as available to every musician on the gig.
• 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. The reasoning is published here so it can be argued with rather than just accepted, and section 7.1 below is what happened when a backer took that invitation seriously. This spec locked on 11 September 2026 and these decisions are now final. Backers to date can withdraw for a full refund up to 18 September 2026.

7.1 Songs where each player reads a different part

Decision: parts are worked out song by song, and you are only asked to choose where a song is genuinely ambiguous. Revised 9 September 2026 after a backer challenge.

Back On Stage supports separate charts per instrument, while forScore's setlist model expects one score per entry.

The original answer, now superseded: you picked one role once, up front, and every song was filtered to it. A backer pointed out the flaw, and he was right. Real libraries are not that tidy. Charts sit against no role at all, players double on the same gig, and a single up-front role choice either buries the unassigned charts or hands you a set full of gaps. It also asks you to make a decision before you can see which songs it actually affects.

The rule

For each song independently, your candidate charts are every chart assigned to a role you are booked for, plus every chart assigned to no role. Unassigned charts are treated as available to everyone, because in practice that is what a lead sheet or a full score is.

Then, per song:

1. Exactly one candidate. It is used. No prompt, no interruption.
2. No candidates. A placeholder carrying the song title, so the set order survives and the gap is visible.
3. More than one candidate. You choose.

The choosing flow

Selection happens once, up front, before generation starts, so you answer everything in one pass rather than being interrupted repeatedly.

1. If any song is ambiguous, a single opening prompt: "Some songs have more than one part. Please select which part you'd like to export for each." with Cancel and Continue.
2. On Continue, one window per ambiguous song, in set order, showing the song title and a button for each candidate chart. Selecting a part advances you immediately to the next song. No confirm step, no back-and-forth.
3. Remembered choices. The first time you resolve a given combination of parts, you are offered "use this part for the rest of the set wherever the same choice comes up." Take it and every later song offering that same combination resolves silently. Decline and every song is asked individually.
4. Once every ambiguous song has a selection, the export proceeds.

The remembered-choice shortcut exists because the common case is a doubler facing the same trumpet-or-flugelhorn decision on thirty songs out of forty. Without it, a correct design becomes an unusable one at exactly the library sizes this feature is for. It is offered rather than assumed, and it is always overridable, because the whole point of asking is that you know something the data does not.

Rejected alternatives, and why

Routing parts automatically by role. Quietly makes a decision on your behalf and gets it wrong for anyone doubling, with no signal that a choice was even made.

Sending every part to everyone. Recreates the exact pile of irrelevant PDFs this feature exists to eliminate.

A single up-front role choice. The superseded answer above. Simpler to build, and wrong for any library with unassigned charts in it, which is most of them.

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. Section 7.1 revised 2026-09-09. Spec locked 2026-09-11.

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