OnSong^® Binder (aka Your Digital Sheet Music Salvation)

The OnSong^® Binder file format is how OnSong yeetus a song, a set, or a whole book between libraries. Like the OnSong^® Archive it carries everything needed to rebuild the content somewhere else — the song text, attachments, styles, settings, transposition & annotations — but where an archive is a single opaque blob, a binder is a folder of ordinary files. That makes it readable, inspectable, & able to carry the media a song depends on alongside the song itself in a platform-agnostic manner.

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

What's Inside This Thing

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

• manifest.json — the item itself, serialized. Like, every property OnSong knows about it, in the same shape the OnSong web API uses.
• Its file, if it has one. An attachment keeps its original filename, so a PDF or an MP3 inside a binder is just that PDF or MP3. Shocking, we know.
• Folders for its children, named after what they are — songs, attachments — each holdin' more folders of exactly the same shape.

That structure repeats all the way down: a set contains songs, a song contains attachments, & each is a folder with its own manifest beside its own files. A binder holdin' a book of two hundred songs is the same format as one holdin' a single chart. Democracy in action, y\u{2019}all.

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 It Carries (The Actual Stuff)

• Songs — the chord chart & everything attached to it.
• Sets — the songs in their order, with the set\u{2019}s own arrangement.
• Books — a whole collection. Get fancy with it.
• Attachments — PDFs, images, audio, & any other file associated with a song. You can choose to include only the attachments that are actually in use rather than every version ever added. (You\u{2019}re welcome for that feature, btw.)

Binder Or Archive? (The Smackdown)

Both round-trip a library\u{2019}s content faithfully, so the choice is about what you need from the file:

• OnSong^® Archive is the older format, & is what to use if you\u{2019}re stuck in the past with earlier versions of OnSong.
• OnSong^® Binder is the current hotness. Use it for sharing with newer versions of OnSong — & when you want a file you can open up & peek inside like some kind of digital nosy parker.

Importing & Exporting (The Boring But Necessary Bits)

Binders import the way any other file does: open 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 adds that song. It\u{2019}s literally rocket science but not really.

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

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 the one travellin\u{2019} over the network. Spooky action at a distance, but make it musical.

Because a binder is a ZIP of plain JSON & ordinary media files, it\u{2019}s the right format to reach for when you need to see what OnSong actually stored — or when something needs to read your content & isn\u{2019}t OnSong.