OnSong^® Binder (AKA Your Digital Crutch)

The OnSong^® Binder file format is how OnSong yeets a song, a set, or a whole book between libraries. Like the OnSong^® Archive it carries literally 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. Fancy, amirite.

The OnSong^® Binder file format has a file extension of either .onsongbinder or .binder, & a MIME type of application/onsong-binder. (Yeah, we know, riveting stuff.)

What's Lurkin' Inside

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

• manifest.json — the item itself, serialized. Every property OnSong knows about it, in the same shape the OnSong web API uses. (It's basically a digital X-ray.)
• 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. Revolutionary, we know.
• Folders for its children, named after what they are — songs, attachments — each holding 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 holding a book of two hundred songs is the same format as one holding a single chart. (Size doesn't matter. Sadly.)

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. (It's basically a treasure map made of boring JSON.)

What It's Gonna Haul For Ya

• Songs — the chord chart & literally everything stuck to it.
• Sets — the songs in their order, with the set's own arrangement. (No, you can't rearrange 'em with your mind. Yet.)
• Books — a whole collection. Get organized, y'all.
• 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. (Translation: don't be a digital hoarder.)

Binder Or Archive? (The Thrilling Sequel Nobody Asked For)

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 if you'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 & spy on.

Importing & Exporting (The Boring But Necessary Part)

Binders import the way any other file does: open one from Files, Mail, AirDrop, or a cloud service & choose OnSong. Importing a binder that holds a set recreates the set & every song in it; importing one that holds a single song adds that song. (Shockingly intuitive, we know.)

To create one, use Share & pick OnSong Binder as the format. (Don't mess it up.)

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 travelin' over the network. Plot twist: it's the same format everywhere. Mind. Blown.

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. (AKA when you don't trust us. Fair.)