OnSong^® Binder of Your Wildest Dreams (Okay, Just Your Setlists)

The OnSong^® Binder file format is how OnSong moves a song, a set, or a whole bleepin' book between libraries. Like the OnSong^® Archive it carries literally everything you need to rebuild your content somewhere else — the song text, attachments, styles, settings, transposition & annotations — but where an archive is one big mysterious blob of mystery, a binder is just a folder of regular files. Wild, right? That makes it readable, inspectable, & able to cart around all the media a song depends on right alongside the song itself in a way that doesn't care what platform you're on.

The OnSong^® Binder file format has a file extension of either .onsongbinder or .binder, & a MIME type of application/onsong-binder. (Srsly, that's the boring part.)

What's Actually In There

A binder is a ZIP archive. Unzip one & you'll find a folder named after the item's identifier, holdin':

• manifest.json — the item itself, all serialized & stuff. Every property OnSong knows about it, in the exact same shape the OnSong web API uses. (We're very organized. Shocking, we know.)
• Its file, if it has one. An attachment keeps its original filename, so a PDF or MP3 inside a binder is literally just... a PDF or MP3. Groundbreaking.
• Folders for its kids, named after what they are — songs, attachments — each one holdin' more folders that look exactly the same.

That structure keeps goin' & goin' like a Energizer bunny: a set contains songs, a song contains attachments, & each one's got its own manifest chillin' next to its own files. A binder holdin' a book of two hundred songs looks identical to one holdin' a single chart. We're consistent like that.

Inside a manifest, references to kids are marked with a $binder. prefix, so a reader can figure out which values belong to the item & which ones are pointin' to a folder next to it. (You're welcome, future you.)

What It Actually Hauls

• Songs — the chord chart & literally everything stuck to it.
• Sets — the songs in their order, with the set's own special arrangement vibe.
• Books — a whole entire collection. Fancy.
• Attachments — PDFs, images, audio, & literally any other file that's vibin' with a song. You can cherry-pick & include only the attachments actually in use instead of every version you ever added. (We call that "not being a digital hoarder.")

Binder Or Archive? (Plot Twist: Pick One)

Both will faithfully round-trip your library's content, so really it's about what you need outta the file:

• OnSong^® Archive is the dinosaur format — use it if you gotta play nice with ancient versions of OnSong.
• OnSong^® Binder is the new hotness. Use it when you wanna share with newer versions of OnSong — & especially when you actually wanna peek inside the file like a nosy person.

Importing & Exporting (It's Not Rocket Science)

Binders import exactly like any other file does: open one from Files, Mail, AirDrop, or your fave cloud service & pick OnSong. Importing a binder that holds a set recreates the set & every song in it; importing one with a single song just adds that song. Easy peasy.

To create one, hit Share & pick OnSong Binder as your format. Done.

Binders are also what OnSong Connect sends between devices when one device is like "yo, gimme that song or set" — so the same format chillin' in your Files app is the one cruisin' over the network. Neat, huh?

Because a binder is literally just a ZIP of plain JSON & regular ol' media files, it's the golden format when you need to see what OnSong *actually stored — or when somethin' else needs to read your content but isn't OnSong.*