OnSong^® Binder (Your Digital Sheet Music Hoarder)

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 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. (Translation: it just works, y'all.)

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

What's Hidin' Inside

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. Every property OnSong knows about it, in the same shape the OnSong web API uses. (Basically, the instruction manual for your stuff.)
• 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. (Shocker!)
• Folders for its children, named after what they are — songs, attachments — each holdin' more folders of exactly the same shape. (It's folders all the way down, peeps.)

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. (One format to rule 'em 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. (Basically, OnSong's way of sayin' "look over there.")

What It Actually Carries

• Songs — the chord chart & everything attached to it.
• Sets — the songs in their order, with the set's own arrangement.
• Books — a whole collection. (Your entire life's work, basically.)
• 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. (Finally, a feature that respects your disk space!)

Binder Or Archive? (The Showdown)

Both round-trip a library's content faithfully, so the choice is about what you need from the file:

• OnSong^® Archive is the older format, & is what to use for compatibility with earlier versions of OnSong. (The nostalgic choice.)
• OnSong^® Binder is the current one. Use it for sharing with newer versions of OnSong — & when you want a file you can open up & look inside. (The cool kids' choice.)

Importin' & Exportin' (AKA Copy-Paste for Grown-Ups)

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's not witchcraft, it's just files.)

To create one, use Share & pick OnSong Binder as the format. (Revolutionary stuff, I know.)

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' over the network. (ZOMG, consistency!)

Because a binder is a ZIP of plain JSON & ordinary media files, it'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't OnSong. (In other words: it's the format for the curious, the paranoid, & the API nerds. No judgment.)