OnSong^® Binder of Awesomeness

The OnSong^® Binder file format is how OnSong yeetus a song, a set, or a whole bloopin' book between libraries. Like the OnSong^® Archive it carries literally everything needed to rebuild your stuff somewhere else — the song text, attachments, styles, settings, transposition & annotations — but where an archive is a single opaque blob that you can't peek at, a binder is a folder of ordinary files. That makes it readable, inspectable, & able to carry all the media a song depends on alongside the song itself in a way that doesn't care what device you're flexin'.

The OnSong^® Binder file format has a file extension of either .onsongbinder or .binder, & a MIME type of application/onsong-binder.

What's Lurkin' Inside

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

• manifest.json — literally the item itself, all serialized & fancy. Every bleepin' property OnSong knows about it, in the exact same shape the OnSong web API uses.
• Its file, if it's got one. An attachment keeps its original filename, so a PDF or an MP3 inside a binder is just... a PDF or an MP3. Wild, right?
• Folders for its children, named after what they are — songs, attachments — each holdin' more folders of exactly the same setup.

That structure repeats all the way down: a set contains songs, a song contains attachments, & each is a folder with its own manifest chillin' beside its own files. A binder holdin' a book of two hundred songs looks exactly the same as one holdin' a single chart. We're not playin' favorites here.

Inside a manifest, references to children are marked with a $binder. prefix, so a reader can tell the difference between a value that belongs to the item & one that points into a folder next to it.

What This Shizzle Carries

• Songs — the chord chart & literally everything attached to it.
• Sets — the songs in their order, with the set's own arrangement. Very organized. Very you.
• Books — a whole freakin' collection.
• Attachments — PDFs, images, audio, & whatever other file y'all threw at a song. You can pick to include only the attachments actually in use instead of every version ever added. (Our developers thank you.)

Binder Or Archive? The Great Debate

Both round-trip your library's content like champs, so the choice is about what you actually need from the file:

• OnSong^® Archive is the old-school format. Use it if you're still kickin' it with earlier versions of OnSong & need the compat love.
• OnSong^® Binder is the shiny new hotness. Use it for sharin' with newer versions of OnSong — & when you want a file you can crack open & actually see what's inside.

Importin' & Exportin' (Or: How To Move Your Stuff Around)

Binders import like any other file does: yeet one from Files, Mail, AirDrop, or a cloud service & choose OnSong. Importin' a binder that holds a set recreates the set & every song in it; importin' one that holds a single song just adds that song. No drama.

To create one, use Share & pick OnSong Binder as the format. Boom.

Binders are also what OnSong Connect sends between devices when one device asks another for a song or a set, so the same format that lives in your Files app is literally the one travellin' over the network. We're consistent like that.

Because a binder is a ZIP of plain JSON & ordinary media files, it's the right format to grab when you need to see what OnSong actually stored — or when somethin' else needs to read your content & isn't OnSong.